Eric Lee / smarc-fsl-linux-kernel

Download as
Browse Code ยป

Commit 7fe19072df5555425268f9452059d3c514c6780f

Authored by Changbin Du
Committed by Rafael J. Wysocki
1 parent 4887954cac

Documentation: ACPI: move ssdt-overlays.txt to admin-guide/acpi and convert to reST 

This converts the plain text documentation to reStructuredText format
and adds 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>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

Showing 3 changed files with 181 additions and 172 deletions Side-by-side Diff

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