Describing and referring to LEDs in ACPI

ACPI LED 노드와 참조 규칙

개별 LED는 LED driver chip인 device node 아래의 hierarchical data extension [5] node로 기술한다. 각 LED 전용 node의 `reg` property는 LED가 연결된 개별 LED output의 숫자 ID를 나타낸다 [leds]. Hierarchical data node 이름은 `led@X`이고 X는 LED output number다.

Device Tree에서 LED를 참조하는 방법은 [video-interfaces]의 `flash-leds` property 문서에 정의되어 있으며, 요약하면 phandle로 LED를 직접 참조한다.

ACPI도 DT와 마찬가지로 참조 뒤에 integer argument를 둘 수 있다. 개별 LED는 LED driver device reference와 관련 LED의 `reg` property를 가리키는 integer argument의 조합으로 식별한다.

`reg` 값은 firmware와 software 사이의 contract이며 LED driver output을 고유하게 식별한다. Firmware와 driver가 이 번호의 의미에 동의해야 같은 물리 출력을 선택할 수 있으므로, node의 나열 순서만으로 LED를 식별해서는 안 된다.

LED driver device 아래 첫 hierarchical data extension package list entry는 `led@` 문자열과 LED number를 결합한 key 뒤에 참조 object name을 둔다. 그 object는 `LED` 뒤에 LED number를 붙인 이름이어야 한다. 예를 들어 output 0은 `"led@0"` key와 `LED0` object를 사용한다.

.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>

========================================
Describing and referring to LEDs in ACPI
========================================

Individual LEDs are described by hierarchical data extension [5] nodes under the
device node, the LED driver chip. The "reg" property in the LED specific nodes
tells the numerical ID of each individual LED output to which the LEDs are
connected. [leds] The hierarchical data nodes are named "led@X", where X is the
number of the LED output.

Referring to LEDs in Device tree is documented in [video-interfaces], in
"flash-leds" property documentation. In short, LEDs are directly referred to by
using phandles.

ACPI allows (as does DT) using integer arguments after the reference. A
combination of the LED driver device reference and an integer argument,
referring to the "reg" property of the relevant LED, is used to identify
individual LEDs. The value of the "reg" property is a contract between the
firmware and software, it uniquely identifies the LED driver outputs.

Under the LED driver device, The first hierarchical data extension package list
entry shall contain the string "led@" followed by the number of the LED,
followed by the referred object name. That object shall be named "LED" followed
by the number of the LED.

두 출력 LED driver ASL 예제

예제는 두 LED를 위한 LED driver device와 camera sensor device를 ASL로 정의한다. LED 또는 그 참조와 무관한 object는 생략되어 있다.

`Device (LED)`의 `_DSD`는 Hierarchical Data Extension UUID `dbb8e3e6-5886-4ba6-8795-1319f52a966b`을 사용한다. 그 package는 `Package () { "led@0", LED0 }`과 `Package () { "led@1", LED1 }`을 통해 output 0·1을 각 property object에 연결한다.

`LED0`은 Device Properties UUID `daffd814-6eba-4d8c-8a91-bc9bbf4aa301` 아래에 `reg=0`, `flash-max-microamp=1000000`, `flash-timeout-us=200000`, `led-max-microamp=100000`, `label="white:flash"`를 제공한다. 즉 첫 LED는 white flash 역할과 연속·flash 전류 및 timeout 한계를 모두 가진다.

`LED1`은 같은 Device Properties UUID 아래에 `reg=1`, `led-max-microamp=10000`, `label="red:indicator"`를 제공한다. 두 번째 LED는 red indicator 역할이며 flash 전류나 timeout property는 없다.

Example
=======

An ASL example of a camera sensor device and a LED driver device for two LEDs is
show below. Objects not relevant for LEDs or the references to them have been
omitted. ::

        Device (LED)
        {
                Name (_DSD, Package () {
                        ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
                        Package () {
                                Package () { "led@0", LED0 },
                                Package () { "led@1", LED1 },
                        }
                })
                Name (LED0, Package () {
                        ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
                        Package () {
                                Package () { "reg", 0 },
                                Package () { "flash-max-microamp", 1000000 },
                                Package () { "flash-timeout-us", 200000 },
                                Package () { "led-max-microamp", 100000 },
                                Package () { "label", "white:flash" },
                        }
                })
                Name (LED1, Package () {
                        ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
                        Package () {
                                Package () { "reg", 1 },
                                Package () { "led-max-microamp", 10000 },
                                Package () { "label", "red:indicator" },
                        }
                })
        }

Camera sensor의 flash-leds 참조

`Device (SEN)`은 camera sensor device 또는 LED와 관련된 다른 device를 나타낸다. `SEN._DSD`는 Device Properties UUID를 사용하며 `flash-leds` property의 값으로 두 LED node reference를 담은 package를 제공한다.

참조 package는 `Package () { "^LED.LED0", "^LED.LED1" }`이다. `^`는 현재 `SEN` scope의 parent로 이동하고, `LED` device 아래의 `LED0`과 `LED1` object를 각각 직접 가리킨다. 따라서 sensor는 flash에 사용할 두 LED를 순서가 있는 참조 목록으로 얻는다.

이 예제는 앞 절에서 설명한 device reference와 integer argument 조합 대신 hierarchical LED object를 문자열 경로로 직접 참조하는 실제 ASL 표현을 보여준다. 원문의 두 설명과 예제 형식은 모두 아래에 그대로 보존한다.

        Device (SEN)
        {
                Name (_DSD, Package () {
                        ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
                        Package () {
                                Package () {
                                        "flash-leds",
                                        Package () { "^LED.LED0", "^LED.LED1" },
                                }
                        }
                })
        }

where
::

        LED        LED driver device
        LED0        First LED
        LED1        Second LED
        SEN        Camera sensor device (or another device the LED is related to)

참고 문서

[acpi]는 Advanced Configuration and Power Interface Specification이며 ACPI 6.4 URL `https://uefi.org/specifications/ACPI/6.4/`과 참조일 2021-11-30을 제시한다.

[data-node-ref]는 커널 내부 문서 `Documentation/firmware-guide/acpi/dsd/data-node-references.rst`다. Hierarchical data node의 문자열 경로 규칙은 이 문서를 따른다.

[devicetree]는 `https://www.devicetree.org`이며 참조일은 2019-02-21이다. [dsd-guide]는 `https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc`의 DSD Guide이며 참조일은 2021-11-30이다.

[leds]는 `Documentation/devicetree/bindings/leds/common.yaml`, [video-interfaces]는 `Documentation/devicetree/bindings/media/video-interfaces.yaml`이다. LED 공통 property와 `flash-leds` binding의 의미는 이 두 schema를 함께 확인한다.

References
==========

[acpi] Advanced Configuration and Power Interface Specification.
    https://uefi.org/specifications/ACPI/6.4/, referenced 2021-11-30.

[data-node-ref] Documentation/firmware-guide/acpi/dsd/data-node-references.rst

[devicetree] Devicetree. https://www.devicetree.org, referenced 2019-02-21.

[dsd-guide] DSD Guide.
    https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced
    2021-11-30.

[leds] Documentation/devicetree/bindings/leds/common.yaml

[video-interfaces] Documentation/devicetree/bindings/media/video-interfaces.yaml