Update documentation

Fix incorrect register offsets
Add missing IPMI BT control register documentation

diff --git a/README.aquila.md b/README.aquila.md
index 7aa5b6ab737cb4a6705f1338ed0b8baa7c9ff21f..fc56ba8a3712f6cff9d10001511db5ad2ab752e9 100644 (file)
--- a/README.aquila.md
+++ b/README.aquila.md
@@ -10,14 +10,18 @@ Aquila provides two interfaces to the system:
 
 ## General Usage
 
-???
+TODO
+
+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:
+
+https://gitlab.raptorengineering.com/kestrel-collaboration/kestrel-firmware/zephyr-firmware/-/blob/master/kestrel/src/kestrel.c
 
 # REGISTER MAP
 
 ## [0x00 - 0x07] Device ID
 
  Device make/model unique identifier for PnP functionality
- Fixed value: 0x7c5250545350494d
+ Fixed value: 0x7c5250544c504353
 
 ## [0x08 - 0x0b] Device version
 
@@ -29,11 +33,9 @@ Aquila provides two interfaces to the system:
  | 15:8  | Minor version |
  | 7:0   | Patch level   |
 
-## [0x0c - 0x0f] System clock frequency
-
  Can be used to set divisor to meet specific SPI Flash clock frequency requirements
 
-## [0x10 - 0x13] Control register 1
+## [0x0c - 0x0f] Control register 1
 
  Default: 0x00000000
 
@@ -58,7 +60,7 @@ Aquila provides two interfaces to the system:
  | 1     | Allow LPC firmware cycles from host                                                               |
  | 0     | Global CIRQ enable, 0 disables all CIRQs, 1 allows any enabled CIRQs to assert main LPC core CIRQ |
 
-## [0x14 - 0x17] Control register 2
+## [0x10 - 0x13] Control register 2
 
  Default: 0x00000000
 
@@ -76,7 +78,7 @@ Aquila provides two interfaces to the system:
  | 1     | Signal LPC bus error to HOST if asserted when bit 0 asserted                                       |
  | 0     | Assert to transfer data in bits [15:8], [1] to HOST.  Completes the active LPC cycle on assertion. |
 
-## [0x18 - 0x1b] LPC address range 1 configuration register 1
+## [0x14 - 0x17] LPC address range 1 configuration register 1
 
  Default: 0x00000000
 
@@ -88,7 +90,7 @@ Aquila provides two interfaces to the system:
  | 28   | Reserved                            |
  | 27:0 | LPC range start address             |
 
-## [0x1c - 0x1f] LPC address range 1 configuration register 2
+## [0x18 - 0x1b] LPC address range 1 configuration register 2
 
  Default: 0x00000000
 
@@ -97,67 +99,67 @@ Aquila provides two interfaces to the system:
  | 31:28 | Reserved              |
  | 27:0  | LPC range end address |
 
-## [0x20 - 0x23] LPC address range 2 configuration register 1
+## [0x1c - 0x1f] LPC address range 2 configuration register 1
 
  Default: 0x00000000
 
  Same bit mapping as "LPC address range 1 configuration register 1"
 
-## [0x24 - 0x27] LPC address range 2 configuration register 2
+## [0x20 - 0x23] LPC address range 2 configuration register 2
 
  Default: 0x00000000
 
  Same bit mapping as "LPC address range 1 configuration register 2"
 
-## [0x28 - 0x2b]  LPC address range 3 configuration register 1
+## [0x24 - 0x27]  LPC address range 3 configuration register 1
 
  Default: 0x00000000
 
  Same bit mapping as "LPC address range 1 configuration register 1"
 
-## [0x2c - 0x2f] LPC address range 3 configuration register 2
+## [0x28 - 0x2b] LPC address range 3 configuration register 2
 
  Default: 0x00000000
 
  Same bit mapping as "LPC address range 1 configuration register 2"
 
-## [0x30 - 0x33]  LPC address range 4 configuration register 1
+## [0x2c - 0x2f]  LPC address range 4 configuration register 1
 
  Default: 0x00000000
 
  Same bit mapping as "LPC address range 1 configuration register 1"
 
-## [0x34 - 0x37] LPC address range 4 configuration register 2
+## [0x30 - 0x33] LPC address range 4 configuration register 2
 
  Default: 0x00000000
 
  Same bit mapping as "LPC address range 1 configuration register 2"
 
-## [0x38 - 0x3b]  LPC address range 5 configuration register 1
+## [0x34 - 0x37]  LPC address range 5 configuration register 1
 
  Default: 0x00000000
 
  Same bit mapping as "LPC address range 1 configuration register 1"
 
-## [0x3c - 0x3f] LPC address range 5 configuration register 2
+## [0x38 - 0x3b] LPC address range 5 configuration register 2
 
  Default: 0x00000000
 
  Same bit mapping as "LPC address range 1 configuration register 2"
 
-## [0x40 - 0x43]  LPC address range 6 configuration register 1
+## [0x3c - 0x3f]  LPC address range 6 configuration register 1
 
  Default: 0x00000000
 
  Same bit mapping as "LPC address range 1 configuration register 1"
 
-## [0x44 - 0x47] LPC address range 6 configuration register 2
+## [0x40 - 0x43] LPC address range 6 configuration register 2
 
  Default: 0x00000000
 
  Same bit mapping as "LPC address range 1 configuration register 2"
 
-## [0x48 - 0x4b] DMA configuration register 1
+## [0x44 - 0x47] DMA configuration register 1
 
  Default: 0x00000000
 
@@ -170,7 +172,7 @@ Aquila provides two interfaces to the system:
  | 1    | Enable DMA for LPC firmware write cycles                                                                                  |
  | 0    | Enable DMA for LPC firmware read cycles                                                                                   |
 
-## [0x4c - 0x4f] DMA configuration register 2
+## [0x48 - 0x4b] DMA configuration register 2
 
  Default: 0x00000000
 
@@ -336,6 +338,26 @@ Aquila provides two interfaces to the system:
  | 1     | VUART1 CIRQ asserted                                                                             |
  | 0     | LPC global CIRQ asserted                                                                         |
 
+## [0x70 - 0x73] IPMI BT control register
+
+ Default: 0x00000000
+
+ | Bits | Description |
+ |------|-------------|
+ | 31:8 | Reserved    |
+ | 7    | B_BUSY      |
+ | 6    | H_BUSY      |
+ | 5    | OEM0        |
+ | 4    | EVT_ATN     |
+ | 3    | B2H_ATN     |
+ | 2    | H2B_ATN     |
+ | 1    | CLR_RD_PTR  |
+ | 0    | CLR_WR_PTR  |
+
+ This is the IPMI-defined BMC-side (CPU accessible) BT control register (BT_CTRL).
+
+ Please refer to the IPMI specification [1] f for a full register definition.
+
 # LICENSE
 
 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.
@@ -343,3 +365,7 @@ Aquila is licensed under the terms of the GNU LGPLv3+, with included third party
 # DOCUMENTATION CREDITS
 
 (c) 2022 Raptor Engineering, LLC
+
+# REFERENCES
+
+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
\ No newline at end of file

diff --git a/aquila/wishbone_lpc_slave_interface.v b/aquila/wishbone_lpc_slave_interface.v
index cd51f17f20336bb555dcaa3bbca9bc93857bb92b..705d4c14223bb04d76e50a606d82a75e7e97dfb9 100644 (file)
--- a/aquila/wishbone_lpc_slave_interface.v
+++ b/aquila/wishbone_lpc_slave_interface.v
@@ -39,7 +39,7 @@
 // Status register 2 (4 bytes): {4'b0, pending_address}
 // Status register 3 (4 bytes): {24'b0, pending_data}
 // Status register 4 (4 bytes): {16'b0, 4'b0, vuart2_irq_source, vuart1_irq_source, 1'b0, lpc_io_cycle_irq_asserted, lpc_tpm_cycle_irq_asserted, lpc_firmware_cycle_irq_asserted, ipmi_bt_bmc_irq_asserted, vuart2_irq_asserted, vuart1_irq_asserted, irq_asserted}
-// IPMI BT interface status register (4 bytes): {24'b0, BT_CTRL}
+// IPMI BT interface control register (4 bytes): {24'b0, BT_CTRL}
 
 // Required by this wrapper module
 `define LPC_SLAVE_DEBUG