1Overriding ACPI tables via initrd
2=================================
3
41) Introduction (What is this about)
52) What is this for
63) How does it work
74) References (Where to retrieve userspace tools)
8
91) What is this about
10---------------------
11
12If the ACPI_INITRD_TABLE_OVERRIDE compile option is true, it is possible to
13override nearly any ACPI table provided by the BIOS with an instrumented,
14modified one.
15
16For a full list of ACPI tables that can be overridden, take a look at
17the char *table_sigs[MAX_ACPI_SIGNATURE]; definition in drivers/acpi/osl.c
18All ACPI tables iasl (Intel's ACPI compiler and disassembler) knows should
19be overridable, except:
20   - ACPI_SIG_RSDP (has a signature of 6 bytes)
21   - ACPI_SIG_FACS (does not have an ordinary ACPI table header)
22Both could get implemented as well.
23
24
252) What is this for
26-------------------
27
28Please keep in mind that this is a debug option.
29ACPI tables should not get overridden for productive use.
30If BIOS ACPI tables are overridden the kernel will get tainted with the
31TAINT_OVERRIDDEN_ACPI_TABLE flag.
32Complain to your platform/BIOS vendor if you find a bug which is so sever
33that a workaround is not accepted in the Linux kernel.
34
35Still, it can and should be enabled in any kernel, because:
36  - There is no functional change with not instrumented initrds
37  - It provides a powerful feature to easily debug and test ACPI BIOS table
38    compatibility with the Linux kernel.
39
40
413) How does it work
42-------------------
43
44# Extract the machine's ACPI tables:
45cd /tmp
46acpidump >acpidump
47acpixtract -a acpidump
48# Disassemble, modify and recompile them:
49iasl -d *.dat
50# For example add this statement into a _PRT (PCI Routing Table) function
51# of the DSDT:
52Store("HELLO WORLD", debug)
53iasl -sa dsdt.dsl
54# Add the raw ACPI tables to an uncompressed cpio archive.
55# They must be put into a /kernel/firmware/acpi directory inside the
56# cpio archive.
57# The uncompressed cpio archive must be the first.
58# Other, typically compressed cpio archives, must be
59# concatenated on top of the uncompressed one.
60mkdir -p kernel/firmware/acpi
61cp dsdt.aml kernel/firmware/acpi
62# A maximum of: #define ACPI_OVERRIDE_TABLES 10
63# tables are  currently allowed (see osl.c):
64iasl -sa facp.dsl
65iasl -sa ssdt1.dsl
66cp facp.aml kernel/firmware/acpi
67cp ssdt1.aml kernel/firmware/acpi
68# Create the uncompressed cpio archive and concatenate the original initrd
69# on top:
70find kernel | cpio -H newc --create > /boot/instrumented_initrd
71cat /boot/initrd >>/boot/instrumented_initrd
72# reboot with increased acpi debug level, e.g. boot params:
73acpi.debug_level=0x2 acpi.debug_layer=0xFFFFFFFF
74# and check your syslog:
75[    1.268089] ACPI: PCI Interrupt Routing Table [\_SB_.PCI0._PRT]
76[    1.272091] [ACPI Debug]  String [0x0B] "HELLO WORLD"
77
78iasl is able to disassemble and recompile quite a lot different,
79also static ACPI tables.
80
81
824) Where to retrieve userspace tools
83------------------------------------
84
85iasl and acpixtract are part of Intel's ACPICA project:
86http://acpica.org/
87and should be packaged by distributions (for example in the acpica package
88on SUSE).
89
90acpidump can be found in Len Browns pmtools:
91ftp://kernel.org/pub/linux/kernel/people/lenb/acpi/utils/pmtools/acpidump
92This tool is also part of the acpica package on SUSE.
93Alternatively, used ACPI tables can be retrieved via sysfs in latest kernels:
94/sys/firmware/acpi/tables
95