doc: Add usage information for the acpi command

Add some documentation for this command.

Signed-off-by: Simon Glass <sjg@chromium.org>

2 files changed, 236 insertions, 0 deletions

diff --git a/doc/usage/acpi.rst b/doc/usage/acpi.rst
new file mode 100644
index 0000000..14bafc8
--- /dev/null
+++ b/doc/usage/acpi.rst
@@ -0,0 +1,235 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+acpi command
+============
+
+Synopis
+-------
+
+::
+
+    acpi list
+    acpi items [-d]
+    acpi dump <name>
+
+Description
+-----------
+
+The *acpi* command is used to dump the ACPI tables generated by U-Boot for passing
+to the operating systems.
+
+ACPI tables can be generated by various output functions and even devices can
+output material to include in the Differentiated System Description Table (DSDT)
+and SSDT tables (Secondary System Description Table). U-Boot keeps track of
+which device or table-writer produced each piece of the ACPI tables.
+
+The ACPI tables are stored contiguously in memory.
+
+
+acpi list
+~~~~~~~~~
+
+List the ACPI tables that have been generated. Each table has a 4-character
+table name (e.g. SSDT, FACS) and has a format defined by the
+`ACPI specification`_.
+
+U-Boot does not currently support decoding the tables. Unlike devicetree, ACPI
+tables have no regular schema and also some include bytecode, so decoding the
+tables requires a lot of code.
+
+The table shows the following information:
+
+Name
+    Table name, e.g. `MCFG`
+
+Base
+    Base address of table in memory
+
+Size
+    Size of table in bytes
+
+Detail
+    More information depending on the table type
+
+    Revision
+        Table revision number (two decimal digits)
+
+    OEM ID
+        ID for the Original Equipment Manufacturer. Typically this is "U-BOOT".
+
+    OEM Table ID
+        Table ID for the Original Equipment Manufacturer. Typically this is
+        "U-BOOTBL" (U-Boot bootloader)
+
+    OEM Revision
+        Revision string for the Original Equipment Manufacturer. Typically this
+        is the U-Boot release number, e.g. 20220101 (meaning v2022.01 since the
+        final 01 is not used). For DSDT, this is set by the source code in
+        the parameters of DefinitionBlock().
+
+    ACPI compiler-vendor ID
+        This is normally `INTL` for Intel
+
+    ACPI compiler revision
+        This is the compiler revision. It is set to the version string for the
+        DSDT table but other tables just use the value 0 or 1, since U-Boot does
+        not actually use the compiler in these cases. It generates the code
+        itself.
+
+acpi items
+~~~~~~~~~~
+
+List the ACPI data that was generated, broken down by item. An item is either
+an ACPI table generated by a writer function, or the part of a table that was
+generated by a particular device.
+
+The `-d` flag also shows a binary dump of the table.
+
+The table shows the following information about each item:
+
+Seq
+    Sequence number in hex
+
+Type
+    Type of item
+
+    =====  ============================================================
+    Type   Meaning
+    =====  ============================================================
+    dsdt   Fragment of a DSDT table, as generated by a device
+    ssdt   Fragment of a SSDT table, as generated by a device
+    other  A whole table of a particular type. as generated by a writer
+    =====  ============================================================
+
+Base
+    Base address of table in memory
+
+Size
+    Size of table in bytes
+
+Device / Writer
+    Name of device (for ssdt/dsdt) that wrong this fragment of the table, or
+    name of the registered writer function (otherwise) that wrote the table.
+
+acpi dump
+~~~~~~~~~
+
+Dump a paticular ACPI table in binary format. This can be used to read the table
+if you have the specification handy.
+
+
+Example
+-------
+
+::
+
+    => acpi list
+    Name      Base   Size  Detail
+    ----  --------  -----  ------
+    RSDP  79925000     24  v02 U-BOOT
+    RSDT  79925030     48  v01 U-BOOT U-BOOTBL 20220101 INTL 0
+    XSDT  799250e0     6c  v01 U-BOOT U-BOOTBL 20220101 INTL 0
+    FACP  79929570     f4  v04 U-BOOT U-BOOTBL 20220101 INTL 1
+    DSDT  79925280   32ea  v02 U-BOOT U-BOOTBL 20110725 INTL 20180105
+    FACS  79925240     40
+    MCFG  79929670     2c  v01 U-BOOT U-BOOTBL 20220101 INTL 0
+    SPCR  799296a0     50  v02 U-BOOT U-BOOTBL 20220101 INTL 0
+    TPM2  799296f0     4c  v04 U-BOOT U-BOOTBL 20220101 INTL 0
+    APIC  79929740     6c  v02 U-BOOT U-BOOTBL 20220101 INTL 0
+    SSDT  799297b0   1523  v02 U-BOOT U-BOOTBL 20220101 INTL 1
+    NHLT  7992ace0    e60  v05 coral coral 3 INTL 0
+    DBG2  7992db40     61  v00 U-BOOT U-BOOTBL 20220101 INTL 0
+    HPET  7992dbb0     38  v01 U-BOOT U-BOOTBL 20220101 INTL 0
+    => acpi items
+    Seq  Type       Base   Size  Device/Writer
+    ---  -----  --------   ----  -------------
+      0  other  79925000    240  0base
+      1  other  79925240     40  1facs
+      2  dsdt   799252a4     58  board
+      3  dsdt   799252fc     10  lpc
+      4  other  79925280   32f0  3dsdt
+      5  other  79928570   1000  4gnvs
+      6  other  79929570    100  5fact
+      7  other  79929670     30  5mcfg
+      8  other  799296a0     50  5spcr
+      9  other  799296f0     50  5tpm2
+      a  other  79929740     70  5x86
+      b  ssdt   799297d4     fe  maxim-codec
+      c  ssdt   799298d2     28  i2c2@16,0
+      d  ssdt   799298fa    270  da-codec
+      e  ssdt   79929b6a     28  i2c2@16,1
+      f  ssdt   79929b92     28  i2c2@16,2
+     10  ssdt   79929bba     83  tpm@50
+     11  ssdt   79929c3d     28  i2c2@16,3
+     12  ssdt   79929c65    282  elan-touchscreen@10
+     13  ssdt   79929ee7    285  raydium-touchscreen@39
+     14  ssdt   7992a16c     28  i2c2@17,0
+     15  ssdt   7992a194     d8  elan-touchpad@15
+     16  ssdt   7992a26c    163  synaptics-touchpad@2c
+     17  ssdt   7992a3cf     28  i2c2@17,1
+     18  ssdt   7992a3f7    111  wacom-digitizer@9
+     19  ssdt   7992a508     8f  sdmmc@1b,0
+     1a  ssdt   7992a597     4b  wifi
+     1b  ssdt   7992a5e2    1a0  cpu@0
+     1c  ssdt   7992a782    1a0  cpu@1
+     1d  ssdt   7992a922    1a0  cpu@2
+     1e  ssdt   7992aac2    211  cpu@3
+     1f  other  799297b0   1530  6ssdt
+     20  other  7992ace0   2f10  8dev
+    => acpi dump mcfg
+    MCFG @ 79929670
+    00000000: 4d 43 46 47 2c 00 00 00 01 41 55 2d 42 4f 4f 54  MCFG,....AU-BOOT
+    00000010: 55 2d 42 4f 4f 54 42 4c 01 01 22 20 49 4e 54 4c  U-BOOTBL.." INTL
+    00000020: 00 00 00 00 00 00 00 00 00 00 00 00              ............
+    => acpi items -d
+    Seq  Type       Base   Size  Device/Writer
+    ---  -----  --------   ----  -------------
+      0  other  79925000    240  0base
+    00000000: 52 53 44 20 50 54 52 20 9e 55 2d 42 4f 4f 54 02  RSD PTR .U-BOOT.
+    00000010: 30 50 92 79 24 00 00 00 e0 50 92 79 00 00 00 00  0P.y$....P.y....
+    00000020: a1 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
+    00000030: 52 53 44 54 48 00 00 00 01 8b 55 2d 42 4f 4f 54  RSDTH.....U-BOOT
+    00000040: 55 2d 42 4f 4f 54 42 4c 01 01 22 20 49 4e 54 4c  U-BOOTBL.." INTL
+    00000050: 00 00 00 00 70 95 92 79 70 96 92 79 a0 96 92 79  ....p..yp..y...y
+    00000060: f0 96 92 79 40 97 92 79 b0 97 92 79 e0 ac 92 79  ...y@..y...y...y
+    00000070: 40 db 92 79 b0 db 92 79 00 00 00 00 00 00 00 00  @..y...y........
+    00000080: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
+    00000090: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
+    000000a0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
+    000000b0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
+    000000c0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
+    000000d0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
+    000000e0: 58 53 44 54 6c 00 00 00 01 61 55 2d 42 4f 4f 54  XSDTl....aU-BOOT
+    000000f0: 55 2d 42 4f 4f 54 42 4c 01 01 22 20 49 4e 54 4c  U-BOOTBL.." INTL
+    00000100: 00 00 00 00 70 95 92 79 00 00 00 00 70 96 92 79  ....p..y....p..y
+    00000110: 00 00 00 00 a0 96 92 79 00 00 00 00 f0 96 92 79  .......y.......y
+    00000120: 00 00 00 00 40 97 92 79 00 00 00 00 b0 97 92 79  ....@..y.......y
+    00000130: 00 00 00 00 e0 ac 92 79 00 00 00 00 40 db 92 79  .......y....@..y
+    00000140: 00 00 00 00 b0 db 92 79 00 00 00 00 00 00 00 00  .......y........
+    00000150: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
+    00000160: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
+    ...
+
+      1  other  79925240     40  1facs
+    00000000: 46 41 43 53 40 00 00 00 00 00 00 00 00 00 00 00  FACS@...........
+    00000010: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
+    00000020: 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
+    00000030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
+
+      2  dsdt   799252a4     58  board
+    00000000: 10 87 05 00 5c 00 08 4f 49 50 47 12 8c 04 00 03  ....\..OIPG.....
+    00000010: 12 8b 01 00 04 01 01 0e ff ff ff ff ff ff ff ff  ................
+    00000020: 0d 49 4e 54 33 34 35 32 3a 30 31 00 12 85 01 00  .INT3452:01.....
+    00000030: 04 0a 03 01 0a 23 0d 49 4e 54 33 34 35 32 3a 30  .....#.INT3452:0
+    00000040: 31 00 12 85 01 00 04 0a 04 01 0a 0a 0d 49 4e 54  1............INT
+    00000050: 33 34 35 32 3a 30 30 00                          3452:00.
+
+      3  dsdt   799252fc     10  lpc
+    00000000: 10 8f 00 00 5c 00 08 4e 56 53 41 0c 10 50 93 79  ....\..NVSA..P.y
+
+      4  other  79925280   32f0  3dsdt
+    00000000: 44 53 44 54 ea 32 00 00 02 eb 55 2d 42 4f 4f 54  DSDT.2....U-BOOT
+    00000010: 55 2d 42 4f 4f 54 42 4c 25 07 11 20 49 4e 54 4c  U-BOOTBL%.. INTL
+
+
+.. _`ACPI specification`: https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index 33761af..964d761 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -18,6 +18,7 @@ Shell commands
 .. toctree::
    :maxdepth: 1
 
+   acpi
    addrmap
    askenv
    base