Documentation/admin-guide/acpi/ssdt-overlays.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =============
   4 SSDT Overlays
   5 =============
   6
   7 In order to support ACPI open-ended hardware configurations (e.g. development
   8 boards) we need a way to augment the ACPI configuration provided by the firmware
   9 image. A common example is connecting sensors on I2C / SPI buses on development
  10 boards.
  11
  12 Although this can be accomplished by creating a kernel platform driver or
  13 recompiling the firmware image with updated ACPI tables, neither is practical:
  14 the former proliferates board specific kernel code while the latter requires
  15 access to firmware tools which are often not publicly available.
  16
  17 Because ACPI supports external references in AML code a more practical
  18 way to augment firmware ACPI configuration is by dynamically loading
  19 user defined SSDT tables that contain the board specific information.
  20
  21 For example, to enumerate a Bosch BMA222E accelerometer on the I2C bus of the
  22 Minnowboard MAX development board exposed via the LSE connector [1], the
  23 following ASL code can be used::
  24
  25     DefinitionBlock ("minnowmax.aml", "SSDT", 1, "Vendor", "Accel", 0x00000003)
  26     {
  27         External (\_SB.I2C6, DeviceObj)
  28
  29         Scope (\_SB.I2C6)
  30         {
  31             Device (STAC)
  32             {
  33                 Name (_HID, "BMA222E")
  34                 Name (RBUF, ResourceTemplate ()
  35                 {
  36                     I2cSerialBus (0x0018, ControllerInitiated, 0x00061A80,
  37                                 AddressingMode7Bit, "\\_SB.I2C6", 0x00,
  38                                 ResourceConsumer, ,)
  39                     GpioInt (Edge, ActiveHigh, Exclusive, PullDown, 0x0000,
  40                             "\\_SB.GPO2", 0x00, ResourceConsumer, , )
  41                     { // Pin list
  42                         0
  43                     }
  44                 })
  45
  46                 Method (_CRS, 0, Serialized)
  47                 {
  48                     Return (RBUF)
  49                 }
  50             }
  51         }
  52     }
  53
  54 which can then be compiled to AML binary format::
  55
  56     $ iasl minnowmax.asl
  57
  58     Intel ACPI Component Architecture
  59     ASL Optimizing Compiler version 20140214-64 [Mar 29 2014]
  60     Copyright (c) 2000 - 2014 Intel Corporation
  61
  62     ASL Input:     minnomax.asl - 30 lines, 614 bytes, 7 keywords
  63     AML Output:    minnowmax.aml - 165 bytes, 6 named objects, 1 executable opcodes
  64
  65 [1] https://www.elinux.org/Minnowboard:MinnowMax#Low_Speed_Expansion_.28Top.29
  66
  67 The resulting AML code can then be loaded by the kernel using one of the methods
  68 below.
  69
  70 Loading ACPI SSDTs from initrd
  71 ==============================
  72
  73 This option allows loading of user defined SSDTs from initrd and it is useful
  74 when the system does not support EFI or when there is not enough EFI storage.
  75
  76 It works in a similar way with initrd based ACPI tables override/upgrade: SSDT
  77 AML code must be placed in the first, uncompressed, initrd under the
  78 "kernel/firmware/acpi" path. Multiple files can be used and this will translate
  79 in loading multiple tables. Only SSDT and OEM tables are allowed. See
  80 initrd_table_override.txt for more details.
  81
  82 Here is an example::
  83
  84     # Add the raw ACPI tables to an uncompressed cpio archive.
  85     # They must be put into a /kernel/firmware/acpi directory inside the
  86     # cpio archive.
  87     # The uncompressed cpio archive must be the first.
  88     # Other, typically compressed cpio archives, must be
  89     # concatenated on top of the uncompressed one.
  90     mkdir -p kernel/firmware/acpi
  91     cp ssdt.aml kernel/firmware/acpi
  92
  93     # Create the uncompressed cpio archive and concatenate the original initrd
  94     # on top:
  95     find kernel | cpio -H newc --create > /boot/instrumented_initrd
  96     cat /boot/initrd >>/boot/instrumented_initrd
  97
  98 Loading ACPI SSDTs from EFI variables
  99 =====================================
 100
 101 This is the preferred method, when EFI is supported on the platform, because it
 102 allows a persistent, OS independent way of storing the user defined SSDTs. There
 103 is also work underway to implement EFI support for loading user defined SSDTs
 104 and using this method will make it easier to convert to the EFI loading
 105 mechanism when that will arrive. To enable it, the
 106 CONFIG_EFI_CUSTOM_SSDT_OVERLAYS shoyld be chosen to y.
 107
 108 In order to load SSDTs from an EFI variable the ``"efivar_ssdt=..."`` kernel
 109 command line parameter can be used (the name has a limitation of 16 characters).
 110 The argument for the option is the variable name to use. If there are multiple
 111 variables with the same name but with different vendor GUIDs, all of them will
 112 be loaded.
 113
 114 In order to store the AML code in an EFI variable the efivarfs filesystem can be
 115 used. It is enabled and mounted by default in /sys/firmware/efi/efivars in all
 116 recent distribution.
 117
 118 Creating a new file in /sys/firmware/efi/efivars will automatically create a new
 119 EFI variable. Updating a file in /sys/firmware/efi/efivars will update the EFI
 120 variable. Please note that the file name needs to be specially formatted as
 121 "Name-GUID" and that the first 4 bytes in the file (little-endian format)
 122 represent the attributes of the EFI variable (see EFI_VARIABLE_MASK in
 123 include/linux/efi.h). Writing to the file must also be done with one write
 124 operation.
 125
 126 For example, you can use the following bash script to create/update an EFI
 127 variable with the content from a given file::
 128
 129     #!/bin/sh -e
 130
 131     while [ -n "$1" ]; do
 132             case "$1" in
 133             "-f") filename="$2"; shift;;
 134             "-g") guid="$2"; shift;;
 135             *) name="$1";;
 136             esac
 137             shift
 138     done
 139
 140     usage()
 141     {
 142             echo "Syntax: ${0##*/} -f filename [ -g guid ] name"
 143             exit 1
 144     }
 145
 146     [ -n "$name" -a -f "$filename" ] || usage
 147
 148     EFIVARFS="/sys/firmware/efi/efivars"
 149
 150     [ -d "$EFIVARFS" ] || exit 2
 151
 152     if stat -tf $EFIVARFS | grep -q -v de5e81e4; then
 153             mount -t efivarfs none $EFIVARFS
 154     fi
 155
 156     # try to pick up an existing GUID
 157     [ -n "$guid" ] || guid=$(find "$EFIVARFS" -name "$name-*" | head -n1 | cut -f2- -d-)
 158
 159     # use a randomly generated GUID
 160     [ -n "$guid" ] || guid="$(cat /proc/sys/kernel/random/uuid)"
 161
 162     # efivarfs expects all of the data in one write
 163     tmp=$(mktemp)
 164     /bin/echo -ne "\007\000\000\000" | cat - $filename > $tmp
 165     dd if=$tmp of="$EFIVARFS/$name-$guid" bs=$(stat -c %s $tmp)
 166     rm $tmp
 167
 168 Loading ACPI SSDTs from configfs
 169 ================================
 170
 171 This option allows loading of user defined SSDTs from user space via the configfs
 172 interface. The CONFIG_ACPI_CONFIGFS option must be select and configfs must be
 173 mounted. In the following examples, we assume that configfs has been mounted in
 174 /sys/kernel/config.
 175
 176 New tables can be loading by creating new directories in /sys/kernel/config/acpi/table
 177 and writing the SSDT AML code in the aml attribute::
 178
 179     cd /sys/kernel/config/acpi/table
 180     mkdir my_ssdt
 181     cat ~/ssdt.aml > my_ssdt/aml