README.aquila.md

   1 # ARCHITECTURE
   2
   3 Aquila is a Wishbone-compatible, 32-bit, LPC slave device with 64-bit DMA support.
   4
   5 Aquila provides two interfaces to the system:
   6 1. A 32-bit Wishbone slave interface with IRQ support.  All functions are supported on this interface in a CPU-interactive mode.
   7 2. A 64-bit Wishbone master (DMA) interface, providing high speed data access and configurable DMA access protection ranges.
   8
   9 # USAGE
  10
  11 ## General Usage
  12
  13 TODO
  14
  15 Usage is complex, given the nature of the protocols and overall external host involvement.  Some documentation exists in the form of working firmware for a POWER9 host system, for example here:
  16
  17 https://gitlab.raptorengineering.com/kestrel-collaboration/kestrel-firmware/zephyr-firmware/-/blob/master/kestrel/src/kestrel.c
  18
  19 # REGISTER MAP
  20
  21 ## [0x00 - 0x07] Device ID
  22
  23  Device make/model unique identifier for PnP functionality
  24  Fixed value: 0x7c5250544c504353
  25
  26 ## [0x08 - 0x0b] Device version
  27
  28  Device revision (stepping)
  29
  30  | Bits  | Description   |
  31  |-------|---------------|
  32  | 31:16 | Major version |
  33  | 15:8  | Minor version |
  34  | 7:0   | Patch level   |
  35
  36 ## [0x0c - 0x0f] Control register 1
  37
  38  Default: 0x00000000
  39
  40  Definitions:
  41   - CIRQ: Interrupt request as wired to Wishbone-attached internal CPU
  42   - HIRQ: Interrupt request as wired to external host platform over LPC serial IRQ line
  43
  44  | Bits  | Description                                                                                       |
  45  |-------|---------------------------------------------------------------------------------------------------|
  46  | 31:20 | Reserved                                                                                          |
  47  | 19    | Fire CIRQ on LPC I/O cycle access                                                                 |
  48  | 18    | Fire CIRQ on LPC TPM cycle access                                                                 |
  49  | 17    | Fire CIRQ on LPC firmware cycle access                                                            |
  50  | 16    | Enable BMC BT interface CIRQ                                                                      |
  51  | 15:8  | IPMI BT I/O port address                                                                          |
  52  | 7     | Use alternate IPMI BT HIRQ (IRQ #11) instead of standard IPMI BT HIRQ (IRQ #10)                   |
  53  | 6     | Enable IPMI BT host interface                                                                     |
  54  | 5     | Enable VUART2 host interface                                                                      |
  55  | 4     | Enable VUART1 host interface                                                                      |
  56  | 3     | Allow LPC I/O cycles from host                                                                    |
  57  | 2     | Allow LPC TPM cycles from host                                                                    |
  58  | 1     | Allow LPC firmware cycles from host                                                               |
  59  | 0     | Global CIRQ enable, 0 disables all CIRQs, 1 allows any enabled CIRQs to assert main LPC core CIRQ |
  60
  61 ## [0x10 - 0x13] Control register 2
  62
  63  Default: 0x00000000
  64
  65  This register is used only in the CPU-interactive transfer mode.  Any activate DMA ranges will take precendence over this register for HOST firmware cycles.
  66
  67  Definitions:
  68   - CPU:  Wishbone-attached internal CPU
  69   - HOST: External host platform attached via LPC
  70
  71  | Bits  | Description                                                                                        |
  72  |-------|----------------------------------------------------------------------------------------------------|
  73  | 31:16 | Reserved                                                                                           |
  74  | 15:8  | LPC cycle data out (CPU to HOST)                                                                   |
  75  | 7:2   | Reserved                                                                                           |
  76  | 1     | Signal LPC bus error to HOST if asserted when bit 0 asserted                                       |
  77  | 0     | Assert to transfer data in bits [15:8], [1] to HOST.  Completes the active LPC cycle on assertion. |
  78
  79 ## [0x14 - 0x17] LPC address range 1 configuration register 1
  80
  81  Default: 0x00000000
  82
  83  | Bits | Description                         |
  84  |------|-------------------------------------|
  85  | 31   | Enable this LPC slave address range |
  86  | 30   | Allow I/O cycles for this range     |
  87  | 29   | Allow TPM cycles for this range     |
  88  | 28   | Reserved                            |
  89  | 27:0 | LPC range start address             |
  90
  91 ## [0x18 - 0x1b] LPC address range 1 configuration register 2
  92
  93  Default: 0x00000000
  94
  95  | Bits  | Description           |
  96  |-------|-----------------------|
  97  | 31:28 | Reserved              |
  98  | 27:0  | LPC range end address |
  99
 100 ## [0x1c - 0x1f] LPC address range 2 configuration register 1
 101
 102  Default: 0x00000000
 103
 104  Same bit mapping as "LPC address range 1 configuration register 1"
 105
 106 ## [0x20 - 0x23] LPC address range 2 configuration register 2
 107
 108  Default: 0x00000000
 109
 110  Same bit mapping as "LPC address range 1 configuration register 2"
 111
 112 ## [0x24 - 0x27]  LPC address range 3 configuration register 1
 113
 114  Default: 0x00000000
 115
 116  Same bit mapping as "LPC address range 1 configuration register 1"
 117
 118 ## [0x28 - 0x2b] LPC address range 3 configuration register 2
 119
 120  Default: 0x00000000
 121
 122  Same bit mapping as "LPC address range 1 configuration register 2"
 123
 124 ## [0x2c - 0x2f]  LPC address range 4 configuration register 1
 125
 126  Default: 0x00000000
 127
 128  Same bit mapping as "LPC address range 1 configuration register 1"
 129
 130 ## [0x30 - 0x33] LPC address range 4 configuration register 2
 131
 132  Default: 0x00000000
 133
 134  Same bit mapping as "LPC address range 1 configuration register 2"
 135
 136 ## [0x34 - 0x37]  LPC address range 5 configuration register 1
 137
 138  Default: 0x00000000
 139
 140  Same bit mapping as "LPC address range 1 configuration register 1"
 141
 142 ## [0x38 - 0x3b] LPC address range 5 configuration register 2
 143
 144  Default: 0x00000000
 145
 146  Same bit mapping as "LPC address range 1 configuration register 2"
 147
 148 ## [0x3c - 0x3f]  LPC address range 6 configuration register 1
 149
 150  Default: 0x00000000
 151
 152  Same bit mapping as "LPC address range 1 configuration register 1"
 153
 154 ## [0x40 - 0x43] LPC address range 6 configuration register 2
 155
 156  Default: 0x00000000
 157
 158  Same bit mapping as "LPC address range 1 configuration register 2"
 159
 160 ## [0x44 - 0x47] DMA configuration register 1
 161
 162  Default: 0x00000000
 163
 164  | Bits | Description                                                                                                               |
 165  |------|---------------------------------------------------------------------------------------------------------------------------|
 166  | 31:8 | Reserved                                                                                                                  |
 167  | 7:4  | LPC IDSEL filter                                                                                                          |
 168  | 3    | Reserved                                                                                                                  |
 169  | 2    | IDSEL filter enable.  When asserted, the DMA engine will require the LPC IDSEL to match the configured filter IDSEL value |
 170  | 1    | Enable DMA for LPC firmware write cycles                                                                                  |
 171  | 0    | Enable DMA for LPC firmware read cycles                                                                                   |
 172
 173 ## [0x48 - 0x4b] DMA configuration register 2
 174
 175  Default: 0x00000000
 176
 177  Definitions:
 178   - CPU:  Wishbone-attached internal CPU
 179   - HOST: External host platform attached via LPC
 180
 181  | Bits | Description                        |
 182  |------|------------------------------------|
 183  | 31:0 | CPU DMA window base address [31:0] |
 184
 185  NOTE: The DMA engine only supports full word length (64 bit) CPU bus alignment, therefore bits [3:0] of this register are hardwired to zero.
 186
 187 ## [0x4c - 0x4f] DMA configuration register 3
 188
 189  Default: 0x00000000
 190
 191  Definitions:
 192   - CPU:  Wishbone-attached internal CPU
 193   - HOST: External host platform attached via LPC
 194
 195  | Bits | Description                         |
 196  |------|-------------------------------------|
 197  | 31:0 | CPU DMA window base address [63:32] |
 198
 199 ## [0x50 - 0x53] DMA configuration register 4
 200
 201  Default: 0x00000000
 202
 203  Definitions:
 204   - CPU:  Wishbone-attached internal CPU
 205   - HOST: External host platform attached via LPC
 206
 207  | Bits | Description                        |
 208  |------|------------------------------------|
 209  | 31:0 | LPC firmware window length (bytes) |
 210
 211  NOTE: The DMA engine only supports full word length (64 bit) CPU bus alignment, therefore bits [3:0] of this register are hardwired to zero.
 212
 213 ## [0x54 - 0x57] DMA configuration register 5
 214
 215  Default: 0x00000000
 216
 217  Definitions:
 218   - CPU:  Wishbone-attached internal CPU
 219   - HOST: External host platform attached via LPC
 220
 221  | Bits | Description                              |
 222  |------|------------------------------------------|
 223  | 31:0 | LPC firmware window start offset (bytes) |
 224
 225  This register defines the start address (DMA window offset) of the active LPC firmware access window.
 226
 227  All LPC firmware transfers start with an implicit LPC base address of 0x0, which corresponds to offset 0x0 in the configured CPU DMA window (see "DMA configuration register 2").
 228  This register allows remapping of the LPC base address within the CPU DMA window, thus allowing LPC address 0x0 to be placed anywhere within the configured CPU DMA memory region.  In effect, it is the offset into DMA memory space where the LPC memory space origin is placed.
 229
 230  Together with the "DMA configuration register 6" register, a defined region of LPC firmware memory space can be set up for DMA access, which is then mapped onto an equivalent region of CPU DMA memory.
 231
 232 ## [0x58 - 0x5b] DMA configuration register 6
 233
 234  Default: 0x00000000
 235
 236  Definitions:
 237   - CPU:  Wishbone-attached internal CPU
 238   - HOST: External host platform attached via LPC
 239
 240  | Bits | Description                            |
 241  |------|----------------------------------------|
 242  | 31:0 | LPC firmware window end offset (bytes) |
 243
 244  This register defines the end address of the active LPC firmware access window.
 245
 246  Together with the "DMA configuration register 5" register, a defined region of LPC firmware memory space can be set up for DMA access, which is then mapped onto an equivalent region of CPU DMA memory.
 247
 248 ## [0x5c - 0x5f] DMA configuration register 7
 249
 250  Default: 0x00000000
 251
 252  Definitions:
 253   - CPU:  Wishbone-attached internal CPU
 254   - HOST: External host platform attached via LPC
 255
 256  | Bits | Description               |
 257  |------|---------------------------|
 258  | 31:0 | LPC firmware address mask |
 259
 260  This register defines the mask applied to all inbound LPC firmware space addresses, prior to any mapping of those addresses into the DMA region.
 261
 262  This design allows a specific section of CPU DMA memory to be effectively replicated through the entire LPC address space.  In particular, it helps to ensure the DMA window data is available at the end of the LPC firmware address space, as expected by various HOST access patterns.
 263
 264 ## [0x60 - 0x63] Status register 1
 265
 266  Default: 0x00000000
 267
 268  Definitions:
 269   - CPU:  Wishbone-attached internal CPU
 270   - HOST: External host platform attached via LPC
 271
 272  | Bits  | Description                                                                  |
 273  |-------|------------------------------------------------------------------------------|
 274  | 31:24 | Reserved                                                                     |
 275  | 23:20 | IDSEL of pending LPC firmware cycle                                          |
 276  | 19:16 | MSIZE of pending LPC firmware cycle                                          |
 277  | 15:5  | Reserved                                                                     |
 278  | 4     | Asserted when LPC bus is in external HOST-driven reset                       |
 279  | 3:2   | LPC cycle type from host -- 0 == I/O, 1 == TPM, 2 == firmware, 3 == reserved |
 280  | 1     | LPC cycle direction from HOST -- 0 == read, 1 == write                       |
 281  | 0     | Attention flag from LPC core                                                 |
 282
 283 ## [0x64 - 0x67] Status register 2
 284
 285  Default: 0x00000000
 286
 287  Definitions:
 288   - CPU:  Wishbone-attached internal CPU
 289   - HOST: External host platform attached via LPC
 290
 291  | Bits  | Description                  |
 292  |-------|------------------------------|
 293  | 31:28 | Reserved                     |
 294  | 27:0  | Address of pending LPC cycle |
 295
 296  This register contains the target LPC address of any pending LPC transaction initiated by the HOST.
 297
 298 ## [0x68 - 0x6b] Status register 3
 299
 300  Default: 0x00000000
 301
 302  Definitions:
 303   - CPU:  Wishbone-attached internal CPU
 304   - HOST: External host platform attached via LPC
 305
 306  | Bits | Description                             |
 307  |------|-----------------------------------------|
 308  | 31:8 | Reserved                                |
 309  | 7:0  | HOST-provided data of pending LPC cycle |
 310
 311  This register contains the HOST-provided data of any pending LPC transaction initiated by the HOST.
 312
 313  The contents of this register are only defined when the LPC cycle type is WRITE; the contents are undefined for all other cycle types.
 314
 315 ## [0x6c - 0x6f] Status register 4
 316
 317  Default: 0x00000000
 318
 319  Definitions:
 320   - CPU:  Wishbone-attached internal CPU
 321   - HOST: External host platform attached via LPC
 322   - CIRQ: Interrupt request as wired to Wishbone-attached internal CPU
 323   - HIRQ: Interrupt request as wired to external host platform over LPC serial IRQ line
 324
 325  | Bits  | Description                                                                                      |
 326  |-------|--------------------------------------------------------------------------------------------------|
 327  | 31:12 | Reserved                                                                                         |
 328  | 11:10 | Reason for VUART2 IRQ assert -- 0 == undefined, 1 == queue threshold reached, 2 == queue timeout |
 329  | 9:8   | Reason for VUART1 IRQ assert -- 0 == undefined, 1 == queue threshold reached, 2 == queue timeout |
 330  | 7     | Reserved                                                                                         |
 331  | 6     | LPC I/O cycle CIRQ asserted                                                                      |
 332  | 5     | LPC TPM cycle CIRQ asserted                                                                      |
 333  | 4     | LPC firmware cycle CIRQ asserted                                                                 |
 334  | 3     | IPMI BT CIRQ asserted                                                                            |
 335  | 2     | VUART2 CIRQ asserted                                                                             |
 336  | 1     | VUART1 CIRQ asserted                                                                             |
 337  | 0     | LPC global CIRQ asserted                                                                         |
 338
 339 ## [0x70 - 0x73] IPMI BT control register
 340
 341  Default: 0x00000000
 342
 343  | Bits | Description |
 344  |------|-------------|
 345  | 31:8 | Reserved    |
 346  | 7    | B_BUSY      |
 347  | 6    | H_BUSY      |
 348  | 5    | OEM0        |
 349  | 4    | EVT_ATN     |
 350  | 3    | B2H_ATN     |
 351  | 2    | H2B_ATN     |
 352  | 1    | CLR_RD_PTR  |
 353  | 0    | CLR_WR_PTR  |
 354
 355  This is the IPMI-defined BMC-side (CPU accessible) BT control register (BT_CTRL).
 356
 357  Please refer to the IPMI specification [1] for a full register definition.
 358
 359 # LICENSE
 360
 361 Aquila is licensed under the terms of the GNU LGPLv3+, with included third party components licensed under Apache 2.0.  See LICENSE.aquila for details.
 362
 363 # DOCUMENTATION CREDITS
 364
 365 (c) 2022 Raptor Engineering, LLC
 366
 367 # REFERENCES
 368
 369 1. https://www.intel.com/content/dam/www/public/us/en/documents/specification-updates/ipmi-intelligent-platform-mgt-interface-spec-2nd-gen-v2-0-spec-update.pdf