0001 .. SPDX-License-Identifier: GPL-2.0
0002 .. include:: <isonum.txt>
0003
0004 ========================================
0005 Describing and referring to LEDs in ACPI
0006 ========================================
0007
0008 Individual LEDs are described by hierarchical data extension [5] nodes under the
0009 device node, the LED driver chip. The "reg" property in the LED specific nodes
0010 tells the numerical ID of each individual LED output to which the LEDs are
0011 connected. [leds] The hierarchical data nodes are named "led@X", where X is the
0012 number of the LED output.
0013
0014 Referring to LEDs in Device tree is documented in [video-interfaces], in
0015 "flash-leds" property documentation. In short, LEDs are directly referred to by
0016 using phandles.
0017
0018 While Device tree allows referring to any node in the tree [devicetree], in
0019 ACPI references are limited to device nodes only [acpi]. For this reason using
0020 the same mechanism on ACPI is not possible. A mechanism to refer to non-device
0021 ACPI nodes is documented in [data-node-ref].
0022
0023 ACPI allows (as does DT) using integer arguments after the reference. A
0024 combination of the LED driver device reference and an integer argument,
0025 referring to the "reg" property of the relevant LED, is used to identify
0026 individual LEDs. The value of the "reg" property is a contract between the
0027 firmware and software, it uniquely identifies the LED driver outputs.
0028
0029 Under the LED driver device, The first hierarchical data extension package list
0030 entry shall contain the string "led@" followed by the number of the LED,
0031 followed by the referred object name. That object shall be named "LED" followed
0032 by the number of the LED.
0033
0034 Example
0035 =======
0036
0037 An ASL example of a camera sensor device and a LED driver device for two LEDs is
0038 show below. Objects not relevant for LEDs or the references to them have been
0039 omitted. ::
0040
0041 Device (LED)
0042 {
0043 Name (_DSD, Package () {
0044 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
0045 Package () {
0046 Package () { "led@0", LED0 },
0047 Package () { "led@1", LED1 },
0048 }
0049 })
0050 Name (LED0, Package () {
0051 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
0052 Package () {
0053 Package () { "reg", 0 },
0054 Package () { "flash-max-microamp", 1000000 },
0055 Package () { "flash-timeout-us", 200000 },
0056 Package () { "led-max-microamp", 100000 },
0057 Package () { "label", "white:flash" },
0058 }
0059 })
0060 Name (LED1, Package () {
0061 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
0062 Package () {
0063 Package () { "reg", 1 },
0064 Package () { "led-max-microamp", 10000 },
0065 Package () { "label", "red:indicator" },
0066 }
0067 })
0068 }
0069
0070 Device (SEN)
0071 {
0072 Name (_DSD, Package () {
0073 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
0074 Package () {
0075 Package () {
0076 "flash-leds",
0077 Package () { ^LED, "led@0", ^LED, "led@1" },
0078 }
0079 }
0080 })
0081 }
0082
0083 where
0084 ::
0085
0086 LED LED driver device
0087 LED0 First LED
0088 LED1 Second LED
0089 SEN Camera sensor device (or another device the LED is related to)
0090
0091 References
0092 ==========
0093
0094 [acpi] Advanced Configuration and Power Interface Specification.
0095 https://uefi.org/specifications/ACPI/6.4/, referenced 2021-11-30.
0096
0097 [data-node-ref] Documentation/firmware-guide/acpi/dsd/data-node-references.rst
0098
0099 [devicetree] Devicetree. https://www.devicetree.org, referenced 2019-02-21.
0100
0101 [dsd-guide] DSD Guide.
0102 https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced
0103 2021-11-30.
0104
0105 [leds] Documentation/devicetree/bindings/leds/common.yaml
0106
0107 [video-interfaces] Documentation/devicetree/bindings/media/video-interfaces.yaml
