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