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:http://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:http://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:http://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