soc/amd/common: Update AcpiMmio comments

Document the AcpiMmio individual blocks better.  This is in response
to a request in gerrit for
  69486cac7: Create AcpiMmio functionality from stoneyridge

Correct comments that were inadvertently left in place from older
patches.

Change-Id: I4c16a866de5622e8cfbd3a08816b9d3182950d0e
Signed-off-by: Marshall Dawson <marshalldawson3rd@gmail.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/32931
Reviewed-by: Martin Roth <martinroth@google.com>
Reviewed-by: Richard Spiegel <richard.spiegel@silverbackltd.com>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>

2 files changed, 110 insertions, 4 deletions

diff --git a/src/soc/amd/common/block/acpimmio/mmio_util.c b/src/soc/amd/common/block/acpimmio/mmio_util.c
index 281880cc25..d6320d69d8 100644
--- a/src/soc/amd/common/block/acpimmio/mmio_util.c
+++ b/src/soc/amd/common/block/acpimmio/mmio_util.c
@@ -214,7 +214,7 @@ void acpi_write32(u8 reg, u32 value)
 	write32((void *)(ACPIMMIO_ACPI_BASE + reg), value);
 }
 
-/* asf read/write - access registers at 0xfed80900 - not currently used */
+/* asf read/write - access registers at 0xfed80900 */
 
 u8 asf_read8(u8 reg)
 {
@@ -236,7 +236,7 @@ void asf_write16(u8 reg, u16 value)
 	write16((void *)(ACPIMMIO_ASF_BASE + reg), value);
 }
 
-/* smbus read/write - access registers at 0xfed80a00 and ASF at 0xfed80900 */
+/* smbus read/write - access registers at 0xfed80a00 */
 
 u8 smbus_read8(u8 reg)
 {
@@ -364,9 +364,9 @@ void xhci_pm_write32(uint8_t reg, uint32_t value)
 	write32((void *)(ACPIMMIO_XHCIPM_BASE + reg), value);
 }
 
-/* acdc_tmr read/write - access registers at 0xfed81d00 */
+/* acdc_tmr read/write - access registers at 0xfed81d00 - not currently used */
 
-/* aoac read/write - access registers at 0xfed81e00 - not currently used */
+/* aoac read/write - access registers at 0xfed81e00 */
 
 u8 aoac_read8(u8 reg)
 {
diff --git a/src/soc/amd/common/block/include/amdblocks/acpimmio.h b/src/soc/amd/common/block/include/amdblocks/acpimmio.h
index c90c0c8add..6be856bc5c 100644
--- a/src/soc/amd/common/block/include/amdblocks/acpimmio.h
+++ b/src/soc/amd/common/block/include/amdblocks/acpimmio.h
@@ -18,81 +18,187 @@
 #ifndef __AMDBLOCKS_ACPIMMIO_H__
 #define __AMDBLOCKS_ACPIMMIO_H__
 
+/*
+ * The following AcpiMmio register block mapping represents definitions
+ * that have been documented in AMD publications.  All blocks aren't
+ * implemented in all products, so the caller should be careful not to
+ * inadvertently access a non-existent block.  The definitions within
+ * each block are also subject to change across products.  Please refer
+ * to the appropriate RRG, the BKDG, or PPR for the product.
+ *
+ * The base address is configurable in older products, but defaults to
+ * 0xfed80000.  The address is fixed at 0xfed80000 in newer products.
+ *
+ * +---------------------------------------------------------------------------+
+ * |0x000    SMBus PCI space                                                   |
+ * |           * Dual-mapped to PCI configuration header of D14F0              |
+ * +---------------------------------------------------------------------------+
+ * |0x100    GPIO configuration registers                                      |
+ * |           * old style, never implemented with newer style                 |
+ * +---------------------------------------------------------------------------+
+ * |0x200    SMI configuration registers                                       |
+ * +---------------------------------------------------------------------------+
+ * |0x300    Power Management registers                                        |
+ * |           * Dual-mapped via IO Index/Data 0xcd6/0xcd7 (byte access only)  |
+ * +---------------------------------------------------------------------------+
+ * |0x400    Power Management 2 registers                                      |
+ * +---------------------------------------------------------------------------+
+ * |0x500    BIOS RAM                                                          |
+ * |           * General-purpose storage in S3 domain                          |
+ * |           * Byte access only                                              |
+ * +---------------------------------------------------------------------------+
+ * |0x600    CMOS RAM                                                          |
+ * |           * Dual-mapped to storage at Alt RTC Index/Data (0x72/0x73)      |
+ * |           * Byte access only                                              |
+ * +---------------------------------------------------------------------------+
+ * |0x700    CMOS                                                              |
+ * |           * Dual-mapped to storage at RTC Index/Data (0x70/0x71)          |
+ * |           * Byte access only                                              |
+ * +---------------------------------------------------------------------------+
+ * |0x800    Standard ACPI registers                                           |
+ * |           * Dual-mapped to I/O ACPI registers                             |
+ * +---------------------------------------------------------------------------+
+ * |0x900    ASF controller registers                                          |
+ * |           * Dual-mapped to I/O ASF controller registers                   |
+ * +---------------------------------------------------------------------------+
+ * |0xa00    SMBus controller registers                                        |
+ * |           * Dual-mapped to I/O SMBus controller registers                 |
+ * +---------------------------------------------------------------------------+
+ * |0xb00    WDT registers                                                     |
+ * |           * Dual-mapped to WDT registers, typ. enabled at 0xfeb00000      |
+ * +---------------------------------------------------------------------------+
+ * |0xc00    HPET registers                                                    |
+ * |           * Dual-mapped to HPET registers, typ. enabled at 0xfed00000     |
+ * +---------------------------------------------------------------------------+
+ * |0xd00    MUX configuration registers for GPIO signals                      |
+ * +---------------------------------------------------------------------------+
+ * |0xe00    Miscellaneous registers                                           |
+ * +---------------------------------------------------------------------------+
+ * |0x1000   Serial debug bus                                                  |
+ * +---------------------------------------------------------------------------+
+ * |0x1400   DP-VGA                                                            |
+ * +---------------------------------------------------------------------------+
+ * |0x1500   GPIO configuration registers bank 0                               |
+ * |           * new style, never implemented with older style                 |
+ * +---------------------------------------------------------------------------+
+ * |0x1600   GPIO configuration registers bank 1                               |
+ * |           * new style, never implemented with older style                 |
+ * +---------------------------------------------------------------------------+
+ * |0x1700   GPIO configuration registers bank 2                               |
+ * |           * new style, never implemented with older style                 |
+ * +---------------------------------------------------------------------------+
+ * |0x1c00   xHCI Power Management registers                                   |
+ * +---------------------------------------------------------------------------+
+ * |0x1d00   Wake device (AC DC timer)                                         |
+ * +---------------------------------------------------------------------------+
+ * |0x1e00   Always On Always Connect registers                                |
+ * +---------------------------------------------------------------------------+
+ */
+
+/* Enable the AcpiMmio range at 0xfed80000 */
 void enable_acpimmio_decode(void);
+
+/* Access PM registers using IO cycles */
 uint8_t pm_io_read8(uint8_t reg);
 uint16_t pm_io_read16(uint8_t reg);
 uint32_t pm_io_read32(uint8_t reg);
 void pm_io_write8(uint8_t reg, uint8_t value);
 void pm_io_write16(uint8_t reg, uint16_t value);
 void pm_io_write32(uint8_t reg, uint32_t value);
+
+/* Access SMI registers at 0xfed80100 */
 uint8_t smi_read8(uint8_t reg);
 uint16_t smi_read16(uint8_t reg);
 uint32_t smi_read32(uint8_t reg);
 void smi_write8(uint8_t reg, uint8_t value);
 void smi_write16(uint8_t reg, uint16_t value);
 void smi_write32(uint8_t reg, uint32_t value);
+
+/* Access Power Management registers at 0xfed80300 */
 uint8_t pm_read8(uint8_t reg);
 uint16_t pm_read16(uint8_t reg);
 uint32_t pm_read32(uint8_t reg);
 void pm_write8(uint8_t reg, uint8_t value);
 void pm_write16(uint8_t reg, uint16_t value);
 void pm_write32(uint8_t reg, uint32_t value);
+
+/* Access Power Management 2 registers at 0xfed80400 */
 uint8_t pm2_read8(uint8_t reg);
 uint16_t pm2_read16(uint8_t reg);
 uint32_t pm2_read32(uint8_t reg);
 void pm2_write8(uint8_t reg, uint8_t value);
 void pm2_write16(uint8_t reg, uint16_t value);
 void pm2_write32(uint8_t reg, uint32_t value);
+
+/* Access BIOS RAM storage at 0xfed80500 */
 uint8_t biosram_read8(uint8_t reg);
 uint16_t biosram_read16(uint8_t reg);
 uint32_t biosram_read32(uint8_t reg);
 void biosram_write8(uint8_t reg, uint8_t value);
 void biosram_write16(uint8_t reg, uint16_t value);
 void biosram_write32(uint8_t reg, uint32_t value);
+
+/* Access ACPI registers at 0xfed80800 */
 uint8_t acpi_read8(uint8_t reg);
 uint16_t acpi_read16(uint8_t reg);
 uint32_t acpi_read32(uint8_t reg);
 void acpi_write8(uint8_t reg, uint8_t value);
 void acpi_write16(uint8_t reg, uint16_t value);
 void acpi_write32(uint8_t reg, uint32_t value);
+
+/* Access ASF controller registers at 0xfed80900 */
 uint8_t asf_read8(uint8_t reg);
 uint16_t asf_read16(uint8_t reg);
 void asf_write8(uint8_t reg, uint8_t value);
 void asf_write16(uint8_t reg, uint16_t value);
+
+/* Access SMBus controller registers at 0xfed80a00 */
 uint8_t smbus_read8(uint8_t reg);
 uint16_t smbus_read16(uint8_t reg);
 void smbus_write8(uint8_t reg, uint8_t value);
 void smbus_write16(uint8_t reg, uint16_t value);
+
+/* Access WDT registers at 0xfed80b00 */
 uint8_t wdt_read8(uint8_t reg);
 uint16_t wdt_read16(uint8_t reg);
 uint32_t wdt_read32(uint8_t reg);
 void wdt_write8(uint8_t reg, uint8_t value);
 void wdt_write16(uint8_t reg, uint16_t value);
 void wdt_write32(uint8_t reg, uint32_t value);
+
+/* Access HPET registers at 0xfed80c00 */
 uint8_t hpet_read8(uint8_t reg);
 uint16_t hpet_read16(uint8_t reg);
 uint32_t hpet_read32(uint8_t reg);
 void hpet_write8(uint8_t reg, uint8_t value);
 void hpet_write16(uint8_t reg, uint16_t value);
 void hpet_write32(uint8_t reg, uint32_t value);
+
+/* Access GPIO MUX registers at 0xfed80d00 */
 uint8_t iomux_read8(uint8_t reg);
 uint16_t iomux_read16(uint8_t reg);
 uint32_t iomux_read32(uint8_t reg);
 void iomux_write8(uint8_t reg, uint8_t value);
 void iomux_write16(uint8_t reg, uint16_t value);
 void iomux_write32(uint8_t reg, uint32_t value);
+
+/* Access Miscellaneous registers at 0xfed80e00 */
 uint8_t misc_read8(uint8_t reg);
 uint16_t misc_read16(uint8_t reg);
 uint32_t misc_read32(uint8_t reg);
 void misc_write8(uint8_t reg, uint8_t value);
 void misc_write16(uint8_t reg, uint16_t value);
 void misc_write32(uint8_t reg, uint32_t value);
+
+/* Access xHCI Power Management registers at 0xfed81c00 */
 uint8_t xhci_pm_read8(uint8_t reg);
 uint16_t xhci_pm_read16(uint8_t reg);
 uint32_t xhci_pm_read32(uint8_t reg);
 void xhci_pm_write8(uint8_t reg, uint8_t value);
 void xhci_pm_write16(uint8_t reg, uint16_t value);
 void xhci_pm_write32(uint8_t reg, uint32_t value);
+
+/* Access Always On Always Connect registers at 0xfed81e00 */
 uint8_t aoac_read8(uint8_t reg);
 void aoac_write8(uint8_t reg, uint8_t value);