1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 .. include:: <isonum.txt> 2 .. include:: <isonum.txt>
3 3
4 ======================================== 4 ========================================
5 Describing and referring to LEDs in ACPI 5 Describing and referring to LEDs in ACPI
6 ======================================== 6 ========================================
7 7
8 Individual LEDs are described by hierarchical !! 8 Individual LEDs are described by hierarchical data extension [6] nodes under the
9 device node, the LED driver chip. The "reg" pr 9 device node, the LED driver chip. The "reg" property in the LED specific nodes
10 tells the numerical ID of each individual LED 10 tells the numerical ID of each individual LED output to which the LEDs are
11 connected. [leds] The hierarchical data nodes !! 11 connected. [3] The hierarchical data nodes are named "led@X", where X is the
12 number of the LED output. 12 number of the LED output.
13 13
14 Referring to LEDs in Device tree is documented !! 14 Referring to LEDs in Device tree is documented in [4], in "flash-leds" property
15 "flash-leds" property documentation. In short, !! 15 documentation. In short, LEDs are directly referred to by using phandles.
16 using phandles. !! 16
17 !! 17 While Device tree allows referring to any node in the tree[1], in ACPI
18 While Device tree allows referring to any node !! 18 references are limited to device nodes only [2]. For this reason using the same
19 ACPI references are limited to device nodes on !! 19 mechanism on ACPI is not possible. A mechanism to refer to non-device ACPI nodes
20 the same mechanism on ACPI is not possible. A !! 20 is documented in [7].
21 ACPI nodes is documented in [data-node-ref]. <<
22 21
23 ACPI allows (as does DT) using integer argumen 22 ACPI allows (as does DT) using integer arguments after the reference. A
24 combination of the LED driver device reference 23 combination of the LED driver device reference and an integer argument,
25 referring to the "reg" property of the relevan 24 referring to the "reg" property of the relevant LED, is used to identify
26 individual LEDs. The value of the "reg" proper 25 individual LEDs. The value of the "reg" property is a contract between the
27 firmware and software, it uniquely identifies 26 firmware and software, it uniquely identifies the LED driver outputs.
28 27
29 Under the LED driver device, The first hierarc 28 Under the LED driver device, The first hierarchical data extension package list
30 entry shall contain the string "led@" followed 29 entry shall contain the string "led@" followed by the number of the LED,
31 followed by the referred object name. That obj 30 followed by the referred object name. That object shall be named "LED" followed
32 by the number of the LED. 31 by the number of the LED.
33 32
34 Example 33 Example
35 ======= 34 =======
36 35
37 An ASL example of a camera sensor device and a 36 An ASL example of a camera sensor device and a LED driver device for two LEDs is
38 show below. Objects not relevant for LEDs or t 37 show below. Objects not relevant for LEDs or the references to them have been
39 omitted. :: 38 omitted. ::
40 39
41 Device (LED) 40 Device (LED)
42 { 41 {
43 Name (_DSD, Package () { 42 Name (_DSD, Package () {
44 ToUUID("dbb8e3e6-5886- 43 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
45 Package () { 44 Package () {
46 Package () { " 45 Package () { "led@0", LED0 },
47 Package () { " 46 Package () { "led@1", LED1 },
48 } 47 }
49 }) 48 })
50 Name (LED0, Package () { 49 Name (LED0, Package () {
51 ToUUID("daffd814-6eba- 50 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
52 Package () { 51 Package () {
53 Package () { " 52 Package () { "reg", 0 },
54 Package () { " 53 Package () { "flash-max-microamp", 1000000 },
55 Package () { " 54 Package () { "flash-timeout-us", 200000 },
56 Package () { " 55 Package () { "led-max-microamp", 100000 },
57 Package () { " 56 Package () { "label", "white:flash" },
58 } 57 }
59 }) 58 })
60 Name (LED1, Package () { 59 Name (LED1, Package () {
61 ToUUID("daffd814-6eba- 60 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
62 Package () { 61 Package () {
63 Package () { " 62 Package () { "reg", 1 },
64 Package () { " 63 Package () { "led-max-microamp", 10000 },
65 Package () { " 64 Package () { "label", "red:indicator" },
66 } 65 }
67 }) 66 })
68 } 67 }
69 68
70 Device (SEN) 69 Device (SEN)
71 { 70 {
72 Name (_DSD, Package () { 71 Name (_DSD, Package () {
73 ToUUID("daffd814-6eba- 72 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
74 Package () { 73 Package () {
75 Package () { 74 Package () {
76 "flash 75 "flash-leds",
77 Packag 76 Package () { ^LED, "led@0", ^LED, "led@1" },
78 } 77 }
79 } 78 }
80 }) 79 })
81 } 80 }
82 81
83 where 82 where
84 :: 83 ::
85 84
86 LED LED driver device 85 LED LED driver device
87 LED0 First LED 86 LED0 First LED
88 LED1 Second LED 87 LED1 Second LED
89 SEN Camera sensor device (or anoth 88 SEN Camera sensor device (or another device the LED is related to)
90 89
91 References 90 References
92 ========== 91 ==========
93 92
94 [acpi] Advanced Configuration and Power Interf !! 93 [1] Device tree. https://www.devicetree.org, referenced 2019-02-21.
95 https://uefi.org/specifications/ACPI/6.4/, !! 94
>> 95 [2] Advanced Configuration and Power Interface Specification.
>> 96 https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf,
>> 97 referenced 2019-02-21.
96 98
97 [data-node-ref] Documentation/firmware-guide/a !! 99 [3] Documentation/devicetree/bindings/leds/common.txt
98 100
99 [devicetree] Devicetree. https://www.devicetre !! 101 [4] Documentation/devicetree/bindings/media/video-interfaces.txt
100 102
101 [dsd-guide] DSD Guide. !! 103 [5] Device Properties UUID For _DSD.
102 https://github.com/UEFI/DSD-Guide/blob/mai !! 104 https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf,
103 2021-11-30. !! 105 referenced 2019-02-21.
104 106
105 [leds] Documentation/devicetree/bindings/leds/ !! 107 [6] Hierarchical Data Extension UUID For _DSD.
>> 108 https://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf,
>> 109 referenced 2019-02-21.
106 110
107 [video-interfaces] Documentation/devicetree/bi !! 111 [7] Documentation/firmware-guide/acpi/dsd/data-node-references.rst
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.