.. SPDX-License-Identifier: GPL-2.0+:

acpi command
============

Synopis
-------

::

    acpi list
    acpi items [-d]
    acpi dump <name>
    acpi set <address>

Description
-----------

The *acpi* command is used to dump the ACPI tables generated by U-Boot for
passing to the operating systems. It allows manually setting the address to take
a look at existing ACPI tables.

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

This shows searching for tables in a known area of memory, then setting the
pointer::

    => acpi list
    No ACPI tables present
    => ms.s bff00000 80000 "RSD PTR"
    bff75000: 52 53 44 20 50 54 52 20 cf 42 4f 43 48 53 20 00  RSD PTR .BOCHS .
    1 match
    => acpi set bff75000
    Setting ACPI pointer to bff75000
    => acpi list
    Name      Base   Size  Detail
    ----  --------  -----  ------
    RSDP  bff75000      0  v00 BOCHS
    RSDT  bff76a63     38  v01 BOCHS  BXPC     1 BXPC 1
    FACP  bff768ff     74  v01 BOCHS  BXPC     1 BXPC 1
    DSDT  bff75080   187f  v01 BOCHS  BXPC     1 BXPC 1
    FACS  bff75040     40
    APIC  bff76973     90  v01 BOCHS  BXPC     1 BXPC 1
    HPET  bff76a03     38  v01 BOCHS  BXPC     1 BXPC 1
    WAET  bff76a3b     28  v01 BOCHS  BXPC     1 BXPC 1
    SSDT  bff95040     c5  v02 COREv4 COREBOOT 2a CORE 20221020


.. _`ACPI specification`: https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf