ACPI: Document ACPI table overriding via initrd

Overriding ACPI tables via initrd

=================================

1) Introduction (What is this about)

2) What is this for

3) How does it work

4) References (Where to retrieve userspace tools)

1) What is this about

---------------------

If the ACPI_INITRD_TABLE_OVERRIDE compile option is true, it is possible to

override nearly any ACPI table provided by the BIOS with an instrumented,

modified one.

For a full list of ACPI tables that can be overridden, take a look at

the char *table_sigs[MAX_ACPI_SIGNATURE]; definition in drivers/acpi/osl.c

All ACPI tables iasl (Intel's ACPI compiler and disassembler) knows should

be overridable, except:

   - ACPI_SIG_RSDP (has a signature of 6 bytes)

   - ACPI_SIG_FACS (does not have an ordinary ACPI table header)

Both could get implemented as well.

2) What is this for

-------------------

Please keep in mind that this is a debug option.

ACPI tables should not get overridden for productive use.

If BIOS ACPI tables are overridden the kernel will get tainted with the

TAINT_OVERRIDDEN_ACPI_TABLE flag.

Complain to your platform/BIOS vendor if you find a bug which is so sever

that a workaround is not accepted in the Linux kernel.

Still, it can and should be enabled in any kernel, because:

  - There is no functional change with not instrumented initrds

  - It provides a powerful feature to easily debug and test ACPI BIOS table

    compatibility with the Linux kernel.

3) How does it work

-------------------

# Extract the machine's ACPI tables:

cd /tmp

acpidump >acpidump

acpixtract -a acpidump

# Disassemble, modify and recompile them:

iasl -d *.dat

# For example add this statement into a _PRT (PCI Routing Table) function

# of the DSDT:

Store("HELLO WORLD", debug)

iasl -sa dsdt.dsl

# Add the raw ACPI tables to an uncompressed cpio archive.

# They must be put into a /kernel/firmware/acpi directory inside the

# cpio archive.

# The uncompressed cpio archive must be the first.

# Other, typically compressed cpio archives, must be

# concatenated on top of the uncompressed one.

mkdir -p kernel/firmware/acpi

cp dsdt.aml kernel/firmware/acpi

# A maximum of: #define ACPI_OVERRIDE_TABLES 10

# tables are  currently allowed (see osl.c):

iasl -sa facp.dsl

iasl -sa ssdt1.dsl

cp facp.aml kernel/firmware/acpi

cp ssdt1.aml kernel/firmware/acpi

# Create the uncompressed cpio archive and concatenate the original initrd

# on top:

find kernel | cpio -H newc --create > /boot/instrumented_initrd

cat /boot/initrd >>/boot/instrumented_initrd

# reboot with increased acpi debug level, e.g. boot params:

acpi.debug_level=0x2 acpi.debug_layer=0xFFFFFFFF

# and check your syslog:

[    1.268089] ACPI: PCI Interrupt Routing Table [\_SB_.PCI0._PRT]

[    1.272091] [ACPI Debug]  String [0x0B] "HELLO WORLD"

iasl is able to disassemble and recompile quite a lot different,

also static ACPI tables.

4) Where to retrieve userspace tools

------------------------------------

iasl and acpixtract are part of Intel's ACPICA project:

http://acpica.org/

and should be packaged by distributions (for example in the acpica package

on SUSE).

acpidump can be found in Len Browns pmtools:

ftp://kernel.org/pub/linux/kernel/people/lenb/acpi/utils/pmtools/acpidump

This tool is also part of the acpica package on SUSE.

Alternatively, used ACPI tables can be retrieved via sysfs in latest kernels:

/sys/firmware/acpi/tables