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 (_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
55which 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] https://www.elinux.org/Minnowboard:MinnowMax#Low_Speed_Expansion_.28Top.29
67
68The resulting AML code can then be loaded by the kernel using one of the methods
69below.
70
71Loading ACPI SSDTs from initrd
72==============================
73
74This option allows loading of user defined SSDTs from initrd and it is useful
75when the system does not support EFI or when there is not enough EFI storage.
76
77It works in a similar way with initrd based ACPI tables override/upgrade: SSDT
78aml 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
80in loading multiple tables. Only SSDT and OEM tables are allowed. See
81initrd_table_override.txt for more details.
82
83Here 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
99Loading ACPI SSDTs from EFI variables
100=====================================
101
102This is the preferred method, when EFI is supported on the platform, because it
103allows a persistent, OS independent way of storing the user defined SSDTs. There
104is also work underway to implement EFI support for loading user defined SSDTs
105and using this method will make it easier to convert to the EFI loading
106mechanism when that will arrive.
107
108In order to load SSDTs from an EFI variable the efivar_ssdt kernel command line
109parameter can be used. The argument for the option is the variable name to
110use. If there are multiple variables with the same name but with different
111vendor GUIDs, all of them will be loaded.
112
113In order to store the AML code in an EFI variable the efivarfs filesystem can be
114used. It is enabled and mounted by default in /sys/firmware/efi/efivars in all
115recent distribution.
116
117Creating a new file in /sys/firmware/efi/efivars will automatically create a new
118EFI variable. Updating a file in /sys/firmware/efi/efivars will update the EFI
119variable. 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)
121represent the attributes of the EFI variable (see EFI_VARIABLE_MASK in
122include/linux/efi.h). Writing to the file must also be done with one write
123operation.
124
125For example, you can use the following bash script to create/update an EFI
126variable 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
167Loading ACPI SSDTs from configfs
168================================
169
170This option allows loading of user defined SSDTs from userspace via the configfs
171interface. The CONFIG_ACPI_CONFIGFS option must be select and configfs must be
172mounted. In the following examples, we assume that configfs has been mounted in
173/config.
174
175New tables can be loading by creating new directories in /config/acpi/table/ and
176writing 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
181