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