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