1.. SPDX-License-Identifier: GPL-2.0
2
3=============
4SSDT Overlays
5=============
6
7In order to support ACPI open-ended hardware configurations (e.g. development
8boards) we need a way to augment the ACPI configuration provided by the firmware
9image. A common example is connecting sensors on I2C / SPI buses on development
10boards.
11
12Although this can be accomplished by creating a kernel platform driver or
13recompiling the firmware image with updated ACPI tables, neither is practical:
14the former proliferates board specific kernel code while the latter requires
15access to firmware tools which are often not publicly available.
16
17Because ACPI supports external references in AML code a more practical
18way to augment firmware ACPI configuration is by dynamically loading
19user defined SSDT tables that contain the board specific information.
20
21For example, to enumerate a Bosch BMA222E accelerometer on the I2C bus of the
22Minnowboard MAX development board exposed via the LSE connector [1], the
23following 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 list
42                        0
43                    }
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.asl
57
58    Intel ACPI Component Architecture
59    ASL Optimizing Compiler version 20140214-64 [Mar 29 2014]
60    Copyright (c) 2000 - 2014 Intel Corporation
61
62    ASL Input:     minnomax.asl - 30 lines, 614 bytes, 7 keywords
63    AML Output:    minnowmax.aml - 165 bytes, 6 named objects, 1 executable opcodes
64
65[1] https://www.elinux.org/Minnowboard:MinnowMax#Low_Speed_Expansion_.28Top.29
66
67The resulting AML code can then be loaded by the kernel using one of the methods
68below.
69
70Loading ACPI SSDTs from initrd
71==============================
72
73This option allows loading of user defined SSDTs from initrd and it is useful
74when 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: SSDT
77AML code must be placed in the first, uncompressed, initrd under the
78"kernel/firmware/acpi" path. Multiple files can be used and this will translate
79in loading multiple tables. Only SSDT and OEM tables are allowed. See
80initrd_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 the
86    # cpio archive.
87    # The uncompressed cpio archive must be the first.
88    # Other, typically compressed cpio archives, must be
89    # concatenated on top of the uncompressed one.
90    mkdir -p kernel/firmware/acpi
91    cp ssdt.aml kernel/firmware/acpi
92
93    # Create the uncompressed cpio archive and concatenate the original initrd
94    # on top:
95    find kernel | cpio -H newc --create > /boot/instrumented_initrd
96    cat /boot/initrd >>/boot/instrumented_initrd
97
98Loading ACPI SSDTs from EFI variables
99=====================================
100
101This is the preferred method, when EFI is supported on the platform, because it
102allows a persistent, OS independent way of storing the user defined SSDTs. There
103is also work underway to implement EFI support for loading user defined SSDTs
104and using this method will make it easier to convert to the EFI loading
105mechanism when that will arrive. To enable it, the
106CONFIG_EFI_CUSTOM_SSDT_OVERLAYS shoyld be chosen to y.
107
108In order to load SSDTs from an EFI variable the ``"efivar_ssdt=..."`` kernel
109command 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 multiple
111variables with the same name but with different vendor GUIDs, all of them will
112be loaded.
113
114In order to store the AML code in an EFI variable the efivarfs filesystem can be
115used. It is enabled and mounted by default in /sys/firmware/efi/efivars in all
116recent distribution.
117
118Creating a new file in /sys/firmware/efi/efivars will automatically create a new
119EFI variable. Updating a file in /sys/firmware/efi/efivars will update the EFI
120variable. Please note that the file name needs to be specially formatted as
121"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 in
123include/linux/efi.h). Writing to the file must also be done with one write
124operation.
125
126For example, you can use the following bash script to create/update an EFI
127variable with the content from a given file::
128
129    #!/bin/sh -e
130
131    while [ -n "$1" ]; do
132            case "$1" in
133            "-f") filename="$2"; shift;;
134            "-g") guid="$2"; shift;;
135            *) name="$1";;
136            esac
137            shift
138    done
139
140    usage()
141    {
142            echo "Syntax: ${0##*/} -f filename [ -g guid ] name"
143            exit 1
144    }
145
146    [ -n "$name" -a -f "$filename" ] || usage
147
148    EFIVARFS="/sys/firmware/efi/efivars"
149
150    [ -d "$EFIVARFS" ] || exit 2
151
152    if stat -tf $EFIVARFS | grep -q -v de5e81e4; then
153            mount -t efivarfs none $EFIVARFS
154    fi
155
156    # try to pick up an existing GUID
157    [ -n "$guid" ] || guid=$(find "$EFIVARFS" -name "$name-*" | head -n1 | cut -f2- -d-)
158
159    # use a randomly generated GUID
160    [ -n "$guid" ] || guid="$(cat /proc/sys/kernel/random/uuid)"
161
162    # efivarfs expects all of the data in one write
163    tmp=$(mktemp)
164    /bin/echo -ne "\007\000\000\000" | cat - $filename > $tmp
165    dd if=$tmp of="$EFIVARFS/$name-$guid" bs=$(stat -c %s $tmp)
166    rm $tmp
167
168Loading ACPI SSDTs from configfs
169================================
170
171This option allows loading of user defined SSDTs from user space via the configfs
172interface. The CONFIG_ACPI_CONFIGFS option must be select and configfs must be
173mounted. In the following examples, we assume that configfs has been mounted in
174/sys/kernel/config.
175
176New tables can be loading by creating new directories in /sys/kernel/config/acpi/table
177and writing the SSDT AML code in the aml attribute::
178
179    cd /sys/kernel/config/acpi/table
180    mkdir my_ssdt
181    cat ~/ssdt.aml > my_ssdt/aml
182