182 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3=============4SSDT Overlays5=============6 7In order to support ACPI open-ended hardware configurations (e.g. development8boards) we need a way to augment the ACPI configuration provided by the firmware9image. A common example is connecting sensors on I2C / SPI buses on development10boards.11 12Although this can be accomplished by creating a kernel platform driver or13recompiling the firmware image with updated ACPI tables, neither is practical:14the former proliferates board specific kernel code while the latter requires15access to firmware tools which are often not publicly available.16 17Because ACPI supports external references in AML code a more practical18way to augment firmware ACPI configuration is by dynamically loading19user defined SSDT tables that contain the board specific information.20 21For example, to enumerate a Bosch BMA222E accelerometer on the I2C bus of the22Minnowboard MAX development board exposed via the LSE connector [1], the23following 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 list42 043 }44 })45 46 Method (_CRS, 0, Serialized)47 {48 Return (RBUF)49 }50 }51 }52 }53 54which can then be compiled to AML binary format::55 56 $ iasl minnowmax.asl57 58 Intel ACPI Component Architecture59 ASL Optimizing Compiler version 20140214-64 [Mar 29 2014]60 Copyright (c) 2000 - 2014 Intel Corporation61 62 ASL Input: minnomax.asl - 30 lines, 614 bytes, 7 keywords63 AML Output: minnowmax.aml - 165 bytes, 6 named objects, 1 executable opcodes64 65[1] https://www.elinux.org/Minnowboard:MinnowMax#Low_Speed_Expansion_.28Top.2966 67The resulting AML code can then be loaded by the kernel using one of the methods68below.69 70Loading ACPI SSDTs from initrd71==============================72 73This option allows loading of user defined SSDTs from initrd and it is useful74when the system does not support EFI or when there is not enough EFI storage.75 76It works in a similar way with initrd based ACPI tables override/upgrade: SSDT77AML code must be placed in the first, uncompressed, initrd under the78"kernel/firmware/acpi" path. Multiple files can be used and this will translate79in loading multiple tables. Only SSDT and OEM tables are allowed. See80initrd_table_override.txt for more details.81 82Here 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 the86 # cpio archive.87 # The uncompressed cpio archive must be the first.88 # Other, typically compressed cpio archives, must be89 # concatenated on top of the uncompressed one.90 mkdir -p kernel/firmware/acpi91 cp ssdt.aml kernel/firmware/acpi92 93 # Create the uncompressed cpio archive and concatenate the original initrd94 # on top:95 find kernel | cpio -H newc --create > /boot/instrumented_initrd96 cat /boot/initrd >>/boot/instrumented_initrd97 98Loading ACPI SSDTs from EFI variables99=====================================100 101This is the preferred method, when EFI is supported on the platform, because it102allows a persistent, OS independent way of storing the user defined SSDTs. There103is also work underway to implement EFI support for loading user defined SSDTs104and using this method will make it easier to convert to the EFI loading105mechanism when that will arrive. To enable it, the106CONFIG_EFI_CUSTOM_SSDT_OVERLAYS should be chosen to y.107 108In order to load SSDTs from an EFI variable the ``"efivar_ssdt=..."`` kernel109command line parameter can be used (the name has a limitation of 16 characters).110The argument for the option is the variable name to use. If there are multiple111variables with the same name but with different vendor GUIDs, all of them will112be loaded.113 114In order to store the AML code in an EFI variable the efivarfs filesystem can be115used. It is enabled and mounted by default in /sys/firmware/efi/efivars in all116recent distribution.117 118Creating a new file in /sys/firmware/efi/efivars will automatically create a new119EFI variable. Updating a file in /sys/firmware/efi/efivars will update the EFI120variable. Please note that the file name needs to be specially formatted as121"Name-GUID" and that the first 4 bytes in the file (little-endian format)122represent the attributes of the EFI variable (see EFI_VARIABLE_MASK in123include/linux/efi.h). Writing to the file must also be done with one write124operation.125 126For example, you can use the following bash script to create/update an EFI127variable with the content from a given file::128 129 #!/bin/sh -e130 131 while [ -n "$1" ]; do132 case "$1" in133 "-f") filename="$2"; shift;;134 "-g") guid="$2"; shift;;135 *) name="$1";;136 esac137 shift138 done139 140 usage()141 {142 echo "Syntax: ${0##*/} -f filename [ -g guid ] name"143 exit 1144 }145 146 [ -n "$name" -a -f "$filename" ] || usage147 148 EFIVARFS="/sys/firmware/efi/efivars"149 150 [ -d "$EFIVARFS" ] || exit 2151 152 if stat -tf $EFIVARFS | grep -q -v de5e81e4; then153 mount -t efivarfs none $EFIVARFS154 fi155 156 # try to pick up an existing GUID157 [ -n "$guid" ] || guid=$(find "$EFIVARFS" -name "$name-*" | head -n1 | cut -f2- -d-)158 159 # use a randomly generated GUID160 [ -n "$guid" ] || guid="$(cat /proc/sys/kernel/random/uuid)"161 162 # efivarfs expects all of the data in one write163 tmp=$(mktemp)164 /bin/echo -ne "\007\000\000\000" | cat - $filename > $tmp165 dd if=$tmp of="$EFIVARFS/$name-$guid" bs=$(stat -c %s $tmp)166 rm $tmp167 168Loading ACPI SSDTs from configfs169================================170 171This option allows loading of user defined SSDTs from user space via the configfs172interface. The CONFIG_ACPI_CONFIGFS option must be select and configfs must be173mounted. In the following examples, we assume that configfs has been mounted in174/sys/kernel/config.175 176New tables can be loading by creating new directories in /sys/kernel/config/acpi/table177and writing the SSDT AML code in the aml attribute::178 179 cd /sys/kernel/config/acpi/table180 mkdir my_ssdt181 cat ~/ssdt.aml > my_ssdt/aml182