xref: /linux/Documentation/firmware-guide/acpi/dsd/leds.rst (revision 3702a515edec515fcc7e085053da636fefac88d6) 
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
18ACPI allows (as does DT) using integer arguments after the reference. A
19combination of the LED driver device reference and an integer argument,
20referring to the "reg" property of the relevant LED, is used to identify
21individual LEDs. The value of the "reg" property is a contract between the
22firmware and software, it uniquely identifies the LED driver outputs.
23
24Under the LED driver device, The first hierarchical data extension package list
25entry shall contain the string "led@" followed by the number of the LED,
26followed by the referred object name. That object shall be named "LED" followed
27by the number of the LED.
28
29Example
30=======
31
32An ASL example of a camera sensor device and a LED driver device for two LEDs is
33show below. Objects not relevant for LEDs or the references to them have been
34omitted. ::
35
36	Device (LED)
37	{
38		Name (_DSD, Package () {
39			ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
40			Package () {
41				Package () { "led@0", LED0 },
42				Package () { "led@1", LED1 },
43			}
44		})
45		Name (LED0, Package () {
46			ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
47			Package () {
48				Package () { "reg", 0 },
49				Package () { "flash-max-microamp", 1000000 },
50				Package () { "flash-timeout-us", 200000 },
51				Package () { "led-max-microamp", 100000 },
52				Package () { "label", "white:flash" },
53			}
54		})
55		Name (LED1, Package () {
56			ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
57			Package () {
58				Package () { "reg", 1 },
59				Package () { "led-max-microamp", 10000 },
60				Package () { "label", "red:indicator" },
61			}
62		})
63	}
64
65	Device (SEN)
66	{
67		Name (_DSD, Package () {
68			ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
69			Package () {
70				Package () {
71					"flash-leds",
72					Package () { "^LED.LED0", "^LED.LED1" },
73				}
74			}
75		})
76	}
77
78where
79::
80
81	LED	LED driver device
82	LED0	First LED
83	LED1	Second LED
84	SEN	Camera sensor device (or another device the LED is related to)
85
86References
87==========
88
89[acpi] Advanced Configuration and Power Interface Specification.
90    https://uefi.org/specifications/ACPI/6.4/, referenced 2021-11-30.
91
92[data-node-ref] Documentation/firmware-guide/acpi/dsd/data-node-references.rst
93
94[devicetree] Devicetree. https://www.devicetree.org, referenced 2019-02-21.
95
96[dsd-guide] DSD Guide.
97    https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced
98    2021-11-30.
99
100[leds] Documentation/devicetree/bindings/leds/common.yaml
101
102[video-interfaces] Documentation/devicetree/bindings/media/video-interfaces.yaml
103