diff options
| -rw-r--r-- | Documentation/acpi/ssdt-overlays.txt | 172 | ||||
| -rw-r--r-- | Documentation/admin-guide/acpi/index.rst | 1 | ||||
| -rw-r--r-- | Documentation/admin-guide/acpi/ssdt-overlays.rst | 180 |
3 files changed, 181 insertions, 172 deletions
diff --git a/Documentation/acpi/ssdt-overlays.txt b/Documentation/acpi/ssdt-overlays.txt deleted file mode 100644 index 5ae13f161ea2..000000000000 --- a/Documentation/acpi/ssdt-overlays.txt +++ /dev/null @@ -1,172 +0,0 @@ - -In order to support ACPI open-ended hardware configurations (e.g. development -boards) we need a way to augment the ACPI configuration provided by the firmware -image. A common example is connecting sensors on I2C / SPI buses on development -boards. - -Although this can be accomplished by creating a kernel platform driver or -recompiling the firmware image with updated ACPI tables, neither is practical: -the former proliferates board specific kernel code while the latter requires -access to firmware tools which are often not publicly available. - -Because ACPI supports external references in AML code a more practical -way to augment firmware ACPI configuration is by dynamically loading -user defined SSDT tables that contain the board specific information. - -For example, to enumerate a Bosch BMA222E accelerometer on the I2C bus of the -Minnowboard MAX development board exposed via the LSE connector [1], the -following ASL code can be used: - -DefinitionBlock ("minnowmax.aml", "SSDT", 1, "Vendor", "Accel", 0x00000003) -{ - External (\_SB.I2C6, DeviceObj) - - Scope (\_SB.I2C6) - { - Device (STAC) - { - Name (_ADR, Zero) - Name (_HID, "BMA222E") - - Method (_CRS, 0, Serialized) - { - Name (RBUF, ResourceTemplate () - { - I2cSerialBus (0x0018, ControllerInitiated, 0x00061A80, - AddressingMode7Bit, "\\_SB.I2C6", 0x00, - ResourceConsumer, ,) - GpioInt (Edge, ActiveHigh, Exclusive, PullDown, 0x0000, - "\\_SB.GPO2", 0x00, ResourceConsumer, , ) - { // Pin list - 0 - } - }) - Return (RBUF) - } - } - } -} - -which can then be compiled to AML binary format: - -$ iasl minnowmax.asl - -Intel ACPI Component Architecture -ASL Optimizing Compiler version 20140214-64 [Mar 29 2014] -Copyright (c) 2000 - 2014 Intel Corporation - -ASL Input: minnomax.asl - 30 lines, 614 bytes, 7 keywords -AML Output: minnowmax.aml - 165 bytes, 6 named objects, 1 executable opcodes - -[1] http://wiki.minnowboard.org/MinnowBoard_MAX#Low_Speed_Expansion_Connector_.28Top.29 - -The resulting AML code can then be loaded by the kernel using one of the methods -below. - -== Loading ACPI SSDTs from initrd == - -This option allows loading of user defined SSDTs from initrd and it is useful -when the system does not support EFI or when there is not enough EFI storage. - -It works in a similar way with initrd based ACPI tables override/upgrade: SSDT -aml code must be placed in the first, uncompressed, initrd under the -"kernel/firmware/acpi" path. Multiple files can be used and this will translate -in loading multiple tables. Only SSDT and OEM tables are allowed. See -initrd_table_override.txt for more details. - -Here is an example: - -# 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 ssdt.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 - -== Loading ACPI SSDTs from EFI variables == - -This is the preferred method, when EFI is supported on the platform, because it -allows a persistent, OS independent way of storing the user defined SSDTs. There -is also work underway to implement EFI support for loading user defined SSDTs -and using this method will make it easier to convert to the EFI loading -mechanism when that will arrive. - -In order to load SSDTs from an EFI variable the efivar_ssdt kernel command line -parameter can be used. The argument for the option is the variable name to -use. If there are multiple variables with the same name but with different -vendor GUIDs, all of them will be loaded. - -In order to store the AML code in an EFI variable the efivarfs filesystem can be -used. It is enabled and mounted by default in /sys/firmware/efi/efivars in all -recent distribution. - -Creating a new file in /sys/firmware/efi/efivars will automatically create a new -EFI variable. Updating a file in /sys/firmware/efi/efivars will update the EFI -variable. Please note that the file name needs to be specially formatted as -"Name-GUID" and that the first 4 bytes in the file (little-endian format) -represent the attributes of the EFI variable (see EFI_VARIABLE_MASK in -include/linux/efi.h). Writing to the file must also be done with one write -operation. - -For example, you can use the following bash script to create/update an EFI -variable with the content from a given file: - -#!/bin/sh -e - -while ! [ -z "$1" ]; do - case "$1" in - "-f") filename="$2"; shift;; - "-g") guid="$2"; shift;; - *) name="$1";; - esac - shift -done - -usage() -{ - echo "Syntax: ${0##*/} -f filename [ -g guid ] name" - exit 1 -} - -[ -n "$name" -a -f "$filename" ] || usage - -EFIVARFS="/sys/firmware/efi/efivars" - -[ -d "$EFIVARFS" ] || exit 2 - -if stat -tf $EFIVARFS | grep -q -v de5e81e4; then - mount -t efivarfs none $EFIVARFS -fi - -# try to pick up an existing GUID -[ -n "$guid" ] || guid=$(find "$EFIVARFS" -name "$name-*" | head -n1 | cut -f2- -d-) - -# use a randomly generated GUID -[ -n "$guid" ] || guid="$(cat /proc/sys/kernel/random/uuid)" - -# efivarfs expects all of the data in one write -tmp=$(mktemp) -/bin/echo -ne "\007\000\000\000" | cat - $filename > $tmp -dd if=$tmp of="$EFIVARFS/$name-$guid" bs=$(stat -c %s $tmp) -rm $tmp - -== Loading ACPI SSDTs from configfs == - -This option allows loading of user defined SSDTs from userspace via the configfs -interface. The CONFIG_ACPI_CONFIGFS option must be select and configfs must be -mounted. In the following examples, we assume that configfs has been mounted in -/config. - -New tables can be loading by creating new directories in /config/acpi/table/ and -writing the SSDT aml code in the aml attribute: - -cd /config/acpi/table -mkdir my_ssdt -cat ~/ssdt.aml > my_ssdt/aml diff --git a/Documentation/admin-guide/acpi/index.rst b/Documentation/admin-guide/acpi/index.rst index 9049a7b9f065..4d13eeea1eca 100644 --- a/Documentation/admin-guide/acpi/index.rst +++ b/Documentation/admin-guide/acpi/index.rst @@ -10,4 +10,5 @@ the Linux ACPI support. initrd_table_override dsdt-override + ssdt-overlays cppc_sysfs diff --git a/Documentation/admin-guide/acpi/ssdt-overlays.rst b/Documentation/admin-guide/acpi/ssdt-overlays.rst new file mode 100644 index 000000000000..da37455f96c9 --- /dev/null +++ b/Documentation/admin-guide/acpi/ssdt-overlays.rst @@ -0,0 +1,180 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============= +SSDT Overlays +============= + +In order to support ACPI open-ended hardware configurations (e.g. development +boards) we need a way to augment the ACPI configuration provided by the firmware +image. A common example is connecting sensors on I2C / SPI buses on development +boards. + +Although this can be accomplished by creating a kernel platform driver or +recompiling the firmware image with updated ACPI tables, neither is practical: +the former proliferates board specific kernel code while the latter requires +access to firmware tools which are often not publicly available. + +Because ACPI supports external references in AML code a more practical +way to augment firmware ACPI configuration is by dynamically loading +user defined SSDT tables that contain the board specific information. + +For example, to enumerate a Bosch BMA222E accelerometer on the I2C bus of the +Minnowboard MAX development board exposed via the LSE connector [1], the +following ASL code can be used:: + + DefinitionBlock ("minnowmax.aml", "SSDT", 1, "Vendor", "Accel", 0x00000003) + { + External (\_SB.I2C6, DeviceObj) + + Scope (\_SB.I2C6) + { + Device (STAC) + { + Name (_ADR, Zero) + Name (_HID, "BMA222E") + + Method (_CRS, 0, Serialized) + { + Name (RBUF, ResourceTemplate () + { + I2cSerialBus (0x0018, ControllerInitiated, 0x00061A80, + AddressingMode7Bit, "\\_SB.I2C6", 0x00, + ResourceConsumer, ,) + GpioInt (Edge, ActiveHigh, Exclusive, PullDown, 0x0000, + "\\_SB.GPO2", 0x00, ResourceConsumer, , ) + { // Pin list + 0 + } + }) + Return (RBUF) + } + } + } + } + +which can then be compiled to AML binary format:: + + $ iasl minnowmax.asl + + Intel ACPI Component Architecture + ASL Optimizing Compiler version 20140214-64 [Mar 29 2014] + Copyright (c) 2000 - 2014 Intel Corporation + + ASL Input: minnomax.asl - 30 lines, 614 bytes, 7 keywords + AML Output: minnowmax.aml - 165 bytes, 6 named objects, 1 executable opcodes + +[1] http://wiki.minnowboard.org/MinnowBoard_MAX#Low_Speed_Expansion_Connector_.28Top.29 + +The resulting AML code can then be loaded by the kernel using one of the methods +below. + +Loading ACPI SSDTs from initrd +============================== + +This option allows loading of user defined SSDTs from initrd and it is useful +when the system does not support EFI or when there is not enough EFI storage. + +It works in a similar way with initrd based ACPI tables override/upgrade: SSDT +aml code must be placed in the first, uncompressed, initrd under the +"kernel/firmware/acpi" path. Multiple files can be used and this will translate +in loading multiple tables. Only SSDT and OEM tables are allowed. See +initrd_table_override.txt for more details. + +Here is an example:: + + # 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 ssdt.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 + +Loading ACPI SSDTs from EFI variables +===================================== + +This is the preferred method, when EFI is supported on the platform, because it +allows a persistent, OS independent way of storing the user defined SSDTs. There +is also work underway to implement EFI support for loading user defined SSDTs +and using this method will make it easier to convert to the EFI loading +mechanism when that will arrive. + +In order to load SSDTs from an EFI variable the efivar_ssdt kernel command line +parameter can be used. The argument for the option is the variable name to +use. If there are multiple variables with the same name but with different +vendor GUIDs, all of them will be loaded. + +In order to store the AML code in an EFI variable the efivarfs filesystem can be +used. It is enabled and mounted by default in /sys/firmware/efi/efivars in all +recent distribution. + +Creating a new file in /sys/firmware/efi/efivars will automatically create a new +EFI variable. Updating a file in /sys/firmware/efi/efivars will update the EFI +variable. Please note that the file name needs to be specially formatted as +"Name-GUID" and that the first 4 bytes in the file (little-endian format) +represent the attributes of the EFI variable (see EFI_VARIABLE_MASK in +include/linux/efi.h). Writing to the file must also be done with one write +operation. + +For example, you can use the following bash script to create/update an EFI +variable with the content from a given file:: + + #!/bin/sh -e + + while ! [ -z "$1" ]; do + case "$1" in + "-f") filename="$2"; shift;; + "-g") guid="$2"; shift;; + *) name="$1";; + esac + shift + done + + usage() + { + echo "Syntax: ${0##*/} -f filename [ -g guid ] name" + exit 1 + } + + [ -n "$name" -a -f "$filename" ] || usage + + EFIVARFS="/sys/firmware/efi/efivars" + + [ -d "$EFIVARFS" ] || exit 2 + + if stat -tf $EFIVARFS | grep -q -v de5e81e4; then + mount -t efivarfs none $EFIVARFS + fi + + # try to pick up an existing GUID + [ -n "$guid" ] || guid=$(find "$EFIVARFS" -name "$name-*" | head -n1 | cut -f2- -d-) + + # use a randomly generated GUID + [ -n "$guid" ] || guid="$(cat /proc/sys/kernel/random/uuid)" + + # efivarfs expects all of the data in one write + tmp=$(mktemp) + /bin/echo -ne "\007\000\000\000" | cat - $filename > $tmp + dd if=$tmp of="$EFIVARFS/$name-$guid" bs=$(stat -c %s $tmp) + rm $tmp + +Loading ACPI SSDTs from configfs +================================ + +This option allows loading of user defined SSDTs from userspace via the configfs +interface. The CONFIG_ACPI_CONFIGFS option must be select and configfs must be +mounted. In the following examples, we assume that configfs has been mounted in +/config. + +New tables can be loading by creating new directories in /config/acpi/table/ and +writing the SSDT aml code in the aml attribute:: + + cd /config/acpi/table + mkdir my_ssdt + cat ~/ssdt.aml > my_ssdt/aml |