| Message ID | 20190423162932.21428-24-changbin.du@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Delegated to: | Bjorn Helgaas |
| Headers | show |
| Series | Include linux ACPI/PCI/X86 docs into Sphinx TOC tree | expand |
Em Wed, 24 Apr 2019 00:28:52 +0800 Changbin Du <changbin.du@gmail.com> escreveu: > This converts the plain text documentation to reStructuredText format and > add it to Sphinx TOC tree. No essential content change. > > Signed-off-by: Changbin Du <changbin.du@gmail.com> Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> > --- > Documentation/acpi/ssdt-overlays.txt | 172 ----------------- > Documentation/admin-guide/acpi/index.rst | 1 + > .../admin-guide/acpi/ssdt-overlays.rst | 180 ++++++++++++++++++ > 3 files changed, 181 insertions(+), 172 deletions(-) > delete mode 100644 Documentation/acpi/ssdt-overlays.txt > create mode 100644 Documentation/admin-guide/acpi/ssdt-overlays.rst > > 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 Thanks, Mauro
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
This converts the plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change. Signed-off-by: Changbin Du <changbin.du@gmail.com> --- Documentation/acpi/ssdt-overlays.txt | 172 ----------------- Documentation/admin-guide/acpi/index.rst | 1 + .../admin-guide/acpi/ssdt-overlays.rst | 180 ++++++++++++++++++ 3 files changed, 181 insertions(+), 172 deletions(-) delete mode 100644 Documentation/acpi/ssdt-overlays.txt create mode 100644 Documentation/admin-guide/acpi/ssdt-overlays.rst