0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ================================
0004 Upgrading ACPI tables via initrd
0005 ================================
0006
0007 What is this about
0008 ==================
0009
0010 If the ACPI_TABLE_UPGRADE compile option is true, it is possible to
0011 upgrade the ACPI execution environment that is defined by the ACPI tables
0012 via upgrading the ACPI tables provided by the BIOS with an instrumented,
0013 modified, more recent version one, or installing brand new ACPI tables.
0014
0015 When building initrd with kernel in a single image, option
0016 ACPI_TABLE_OVERRIDE_VIA_BUILTIN_INITRD should also be true for this
0017 feature to work.
0018
0019 For a full list of ACPI tables that can be upgraded/installed, take a look
0020 at the char `*table_sigs[MAX_ACPI_SIGNATURE];` definition in
0021 drivers/acpi/tables.c.
0022
0023 All ACPI tables iasl (Intel's ACPI compiler and disassembler) knows should
0024 be overridable, except:
0025
0026 - ACPI_SIG_RSDP (has a signature of 6 bytes)
0027 - ACPI_SIG_FACS (does not have an ordinary ACPI table header)
0028
0029 Both could get implemented as well.
0030
0031
0032 What is this for
0033 ================
0034
0035 Complain to your platform/BIOS vendor if you find a bug which is so severe
0036 that a workaround is not accepted in the Linux kernel. And this facility
0037 allows you to upgrade the buggy tables before your platform/BIOS vendor
0038 releases an upgraded BIOS binary.
0039
0040 This facility can be used by platform/BIOS vendors to provide a Linux
0041 compatible environment without modifying the underlying platform firmware.
0042
0043 This facility also provides a powerful feature to easily debug and test
0044 ACPI BIOS table compatibility with the Linux kernel by modifying old
0045 platform provided ACPI tables or inserting new ACPI tables.
0046
0047 It can and should be enabled in any kernel because there is no functional
0048 change with not instrumented initrds.
0049
0050
0051 How does it work
0052 ================
0053 ::
0054
0055 # Extract the machine's ACPI tables:
0056 cd /tmp
0057 acpidump >acpidump
0058 acpixtract -a acpidump
0059 # Disassemble, modify and recompile them:
0060 iasl -d *.dat
0061 # For example add this statement into a _PRT (PCI Routing Table) function
0062 # of the DSDT:
0063 Store("HELLO WORLD", debug)
0064 # And increase the OEM Revision. For example, before modification:
0065 DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000000)
0066 # After modification:
0067 DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000001)
0068 iasl -sa dsdt.dsl
0069 # Add the raw ACPI tables to an uncompressed cpio archive.
0070 # They must be put into a /kernel/firmware/acpi directory inside the cpio
0071 # archive. Note that if the table put here matches a platform table
0072 # (similar Table Signature, and similar OEMID, and similar OEM Table ID)
0073 # with a more recent OEM Revision, the platform table will be upgraded by
0074 # this table. If the table put here doesn't match a platform table
0075 # (dissimilar Table Signature, or dissimilar OEMID, or dissimilar OEM Table
0076 # ID), this table will be appended.
0077 mkdir -p kernel/firmware/acpi
0078 cp dsdt.aml kernel/firmware/acpi
0079 # A maximum of "NR_ACPI_INITRD_TABLES (64)" tables are currently allowed
0080 # (see osl.c):
0081 iasl -sa facp.dsl
0082 iasl -sa ssdt1.dsl
0083 cp facp.aml kernel/firmware/acpi
0084 cp ssdt1.aml kernel/firmware/acpi
0085 # The uncompressed cpio archive must be the first. Other, typically
0086 # compressed cpio archives, must be concatenated on top of the uncompressed
0087 # one. Following command creates the uncompressed cpio archive and
0088 # concatenates the original initrd on top:
0089 find kernel | cpio -H newc --create > /boot/instrumented_initrd
0090 cat /boot/initrd >>/boot/instrumented_initrd
0091 # reboot with increased acpi debug level, e.g. boot params:
0092 acpi.debug_level=0x2 acpi.debug_layer=0xFFFFFFFF
0093 # and check your syslog:
0094 [ 1.268089] ACPI: PCI Interrupt Routing Table [\_SB_.PCI0._PRT]
0095 [ 1.272091] [ACPI Debug] String [0x0B] "HELLO WORLD"
0096
0097 iasl is able to disassemble and recompile quite a lot different,
0098 also static ACPI tables.
0099
0100
0101 Where to retrieve userspace tools
0102 =================================
0103
0104 iasl and acpixtract are part of Intel's ACPICA project:
0105 https://acpica.org/
0106
0107 and should be packaged by distributions (for example in the acpica package
0108 on SUSE).
0109
0110 acpidump can be found in Len Browns pmtools:
0111 ftp://kernel.org/pub/linux/kernel/people/lenb/acpi/utils/pmtools/acpidump
0112
0113 This tool is also part of the acpica package on SUSE.
0114 Alternatively, used ACPI tables can be retrieved via sysfs in latest kernels:
0115 /sys/firmware/acpi/tables
