Em Wed, 24 Apr 2019 00:28:52 +0800
Changbin Du <changbin.du@xxxxxxxxx> 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@xxxxxxxxx>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx>
> ---
> 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
