leds.rst (3451B)
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