Documentation/acpi/initrd_table_override.txt

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