SSDT Overlays

SSDT overlay의 목적과 ASL 예제

이 GPL-2.0 문서는 SSDT overlay를 설명합니다. Development board처럼 hardware 구성을 계속 확장할 수 있는 ACPI system에서는 firmware image가 제공한 ACPI configuration에 정보를 보태는 방법이 필요합니다. 흔한 예는 development board의 I2C 또는 SPI bus에 sensor를 연결하는 경우입니다.

Kernel platform driver를 만들거나 수정된 ACPI table로 firmware image를 다시 compile할 수도 있지만 실용적이지 않습니다. 전자는 board-specific kernel code를 늘리고, 후자는 대개 공개되지 않은 firmware tool에 접근해야 합니다.

ACPI AML code는 external reference를 지원하므로 board-specific 정보를 담은 user-defined SSDT table을 동적으로 load하는 편이 더 실용적입니다.

예제는 Minnowboard MAX development board의 LSE connector에 노출된 I2C bus에서 Bosch BMA222E accelerometer를 enumerate합니다. ASL은 `\_SB.I2C6`를 external device로 선언하고 `STAC` device의 `_HID`, I2C address `0x0018`, controller path, GPIO interrupt와 `_CRS` resource method를 정의합니다.

    DefinitionBlock ("minnowmax.aml", "SSDT", 1, "Vendor", "Accel", 0x00000003)
    {
        External (\_SB.I2C6, DeviceObj)

        Scope (\_SB.I2C6)
        {
            Device (STAC)
            {
                Name (_HID, "BMA222E")
                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
                    }
                })

                Method (_CRS, 0, Serialized)
                {
                    Return (RBUF)
                }
            }
        }
    }

`iasl minnowmax.asl`로 ASL을 AML binary로 compile합니다. 예제 compiler는 30-line, 614-byte ASL을 165-byte AML과 named object 6개, executable opcode 1개로 변환합니다.

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] https://www.elinux.org/Minnowboard:MinnowMax#Low_Speed_Expansion_.28Top.29

생성된 AML은 아래의 initrd, EFI variable 또는 configfs 방식 중 하나로 kernel에 load할 수 있습니다.

initrd에서 ACPI SSDT load

이 방식은 user-defined SSDT를 initrd에서 load하며, system이 EFI를 지원하지 않거나 EFI storage가 부족할 때 유용합니다.

Initrd 기반 ACPI table override/upgrade와 비슷하게 SSDT AML을 첫 번째 uncompressed initrd의 `kernel/firmware/acpi` path에 둡니다. File 여러 개를 두면 table 여러 개를 load합니다. SSDT와 OEM table만 허용하며 자세한 내용은 `initrd_table_override.txt`를 참조합니다.

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

EFI variable에서 ACPI SSDT load

Platform이 EFI를 지원하면 EFI variable 방식이 선호됩니다. User-defined SSDT를 지속적이고 OS-independent하게 저장할 수 있고, 향후 EFI loading mechanism으로 전환하기도 쉽습니다. 활성화하려면 `CONFIG_EFI_CUSTOM_SSDT_OVERLAYS=y`를 선택합니다.

Kernel command line의 `efivar_ssdt=...` parameter로 읽을 variable name을 지정합니다. 이름은 16 characters로 제한됩니다. 같은 이름이면서 vendor GUID가 다른 variable이 여러 개라면 모두 load합니다.

AML은 `efivarfs`를 통해 EFI variable에 저장합니다. 최근 distribution에서는 기본적으로 `/sys/firmware/efi/efivars`에 활성화·mount됩니다. 이 directory에 file을 만들면 EFI variable을 새로 만들고 기존 file을 갱신하면 variable도 갱신합니다.

File name은 `Name-GUID` 형식이어야 합니다. File의 첫 4 bytes는 little-endian EFI variable attribute이며 `include/linux/efi.h`의 `EFI_VARIABLE_MASK`를 따릅니다. File write는 반드시 한 번의 write operation으로 수행해야 합니다.

예제 shell script는 `-f filename`, 선택적 `-g guid`, variable name을 parse합니다. `efivarfs`가 없으면 종료하고 필요하면 mount합니다. 기존 GUID를 찾되 없으면 random UUID를 생성합니다. Attribute bytes `07 00 00 00`과 AML file을 temporary file로 합친 뒤 정확한 byte count로 한 번에 `dd`하고 temporary file을 지웁니다.

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 [ -n "$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

configfs에서 ACPI SSDT load

Configfs 방식은 userspace에서 configfs interface를 통해 user-defined SSDT를 load합니다. `CONFIG_ACPI_CONFIGFS` option을 선택하고 configfs를 mount해야 합니다. 예제는 `/sys/kernel/config`에 mount됐다고 가정합니다.

`/sys/kernel/config/acpi/table` 아래 새 directory를 만들고 SSDT AML code를 그 directory의 `aml` attribute에 쓰면 새 table을 load합니다.

New tables can be loading by creating new directories in /sys/kernel/config/acpi/table
and writing the SSDT AML code in the aml attribute::

    cd /sys/kernel/config/acpi/table
    mkdir my_ssdt
    cat ~/ssdt.aml > my_ssdt/aml