1.. SPDX-License-Identifier: GPL-2.0 2 3================================ 4Upgrading ACPI tables via initrd 5================================ 6 7What is this about 8================== 9 10If the ACPI_TABLE_UPGRADE compile option is true, it is possible to 11upgrade the ACPI execution environment that is defined by the ACPI tables 12via upgrading the ACPI tables provided by the BIOS with an instrumented, 13modified, more recent version one, or installing brand new ACPI tables. 14 15When building initrd with kernel in a single image, option 16ACPI_TABLE_OVERRIDE_VIA_BUILTIN_INITRD should also be true for this 17feature to work. 18 19For a full list of ACPI tables that can be upgraded/installed, take a look 20at the char `*table_sigs[MAX_ACPI_SIGNATURE];` definition in 21drivers/acpi/tables.c. 22 23All ACPI tables iasl (Intel's ACPI compiler and disassembler) knows should 24be overridable, except: 25 26 - ACPI_SIG_RSDP (has a signature of 6 bytes) 27 - ACPI_SIG_FACS (does not have an ordinary ACPI table header) 28 29Both could get implemented as well. 30 31 32What is this for 33================ 34 35Complain to your platform/BIOS vendor if you find a bug which is so severe 36that a workaround is not accepted in the Linux kernel. And this facility 37allows you to upgrade the buggy tables before your platform/BIOS vendor 38releases an upgraded BIOS binary. 39 40This facility can be used by platform/BIOS vendors to provide a Linux 41compatible environment without modifying the underlying platform firmware. 42 43This facility also provides a powerful feature to easily debug and test 44ACPI BIOS table compatibility with the Linux kernel by modifying old 45platform provided ACPI tables or inserting new ACPI tables. 46 47It can and should be enabled in any kernel because there is no functional 48change with not instrumented initrds. 49 50 51How does it work 52================ 53:: 54 55 # Extract the machine's ACPI tables: 56 cd /tmp 57 acpidump >acpidump 58 acpixtract -a acpidump 59 # Disassemble, modify and recompile them: 60 iasl -d *.dat 61 # For example add this statement into a _PRT (PCI Routing Table) function 62 # of the DSDT: 63 Store("HELLO WORLD", debug) 64 # And increase the OEM Revision. For example, before modification: 65 DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000000) 66 # After modification: 67 DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000001) 68 iasl -sa dsdt.dsl 69 # Add the raw ACPI tables to an uncompressed cpio archive. 70 # They must be put into a /kernel/firmware/acpi directory inside the cpio 71 # archive. Note that if the table put here matches a platform table 72 # (similar Table Signature, and similar OEMID, and similar OEM Table ID) 73 # with a more recent OEM Revision, the platform table will be upgraded by 74 # this table. If the table put here doesn't match a platform table 75 # (dissimilar Table Signature, or dissimilar OEMID, or dissimilar OEM Table 76 # ID), this table will be appended. 77 mkdir -p kernel/firmware/acpi 78 cp dsdt.aml kernel/firmware/acpi 79 # A maximum of "NR_ACPI_INITRD_TABLES (64)" tables are currently allowed 80 # (see osl.c): 81 iasl -sa facp.dsl 82 iasl -sa ssdt1.dsl 83 cp facp.aml kernel/firmware/acpi 84 cp ssdt1.aml kernel/firmware/acpi 85 # The uncompressed cpio archive must be the first. Other, typically 86 # compressed cpio archives, must be concatenated on top of the uncompressed 87 # one. Following command creates the uncompressed cpio archive and 88 # concatenates the original initrd on top: 89 find kernel | cpio -H newc --create > /boot/instrumented_initrd 90 cat /boot/initrd >>/boot/instrumented_initrd 91 # reboot with increased acpi debug level, e.g. boot params: 92 acpi.debug_level=0x2 acpi.debug_layer=0xFFFFFFFF 93 # and check your syslog: 94 [ 1.268089] ACPI: PCI Interrupt Routing Table [\_SB_.PCI0._PRT] 95 [ 1.272091] [ACPI Debug] String [0x0B] "HELLO WORLD" 96 97iasl is able to disassemble and recompile quite a lot different, 98also static ACPI tables. 99 100 101Where to retrieve userspace tools 102================================= 103 104iasl and acpixtract are part of Intel's ACPICA project: 105https://acpica.org/ 106 107and should be packaged by distributions (for example in the acpica package 108on SUSE). 109 110acpidump can be found in Len Browns pmtools: 111ftp://kernel.org/pub/linux/kernel/people/lenb/acpi/utils/pmtools/acpidump 112 113This tool is also part of the acpica package on SUSE. 114Alternatively, used ACPI tables can be retrieved via sysfs in latest kernels: 115/sys/firmware/acpi/tables 116