12b2d4247SSakari Ailus.. SPDX-License-Identifier: GPL-2.0 22b2d4247SSakari Ailus.. include:: <isonum.txt> 32b2d4247SSakari Ailus 42b2d4247SSakari Ailus======================================== 52b2d4247SSakari AilusDescribing and referring to LEDs in ACPI 62b2d4247SSakari Ailus======================================== 72b2d4247SSakari Ailus 82b2d4247SSakari AilusIndividual LEDs are described by hierarchical data extension [6] nodes under the 92b2d4247SSakari Ailusdevice node, the LED driver chip. The "reg" property in the LED specific nodes 102b2d4247SSakari Ailustells the numerical ID of each individual LED output to which the LEDs are 112b2d4247SSakari Ailusconnected. [3] The hierarchical data nodes are named "led@X", where X is the 122b2d4247SSakari Ailusnumber of the LED output. 132b2d4247SSakari Ailus 142b2d4247SSakari AilusReferring to LEDs in Device tree is documented in [4], in "flash-leds" property 152b2d4247SSakari Ailusdocumentation. In short, LEDs are directly referred to by using phandles. 162b2d4247SSakari Ailus 172b2d4247SSakari AilusWhile Device tree allows referring to any node in the tree[1], in ACPI 182b2d4247SSakari Ailusreferences are limited to device nodes only [2]. For this reason using the same 192b2d4247SSakari Ailusmechanism on ACPI is not possible. A mechanism to refer to non-device ACPI nodes 202b2d4247SSakari Ailusis documented in [7]. 212b2d4247SSakari Ailus 222b2d4247SSakari AilusACPI allows (as does DT) using integer arguments after the reference. A 232b2d4247SSakari Ailuscombination of the LED driver device reference and an integer argument, 242b2d4247SSakari Ailusreferring to the "reg" property of the relevant LED, is used to identify 252b2d4247SSakari Ailusindividual LEDs. The value of the "reg" property is a contract between the 262b2d4247SSakari Ailusfirmware and software, it uniquely identifies the LED driver outputs. 272b2d4247SSakari Ailus 282b2d4247SSakari AilusUnder the LED driver device, The first hierarchical data extension package list 292b2d4247SSakari Ailusentry shall contain the string "led@" followed by the number of the LED, 302b2d4247SSakari Ailusfollowed by the referred object name. That object shall be named "LED" followed 312b2d4247SSakari Ailusby the number of the LED. 322b2d4247SSakari Ailus 332b2d4247SSakari AilusExample 342b2d4247SSakari Ailus======= 352b2d4247SSakari Ailus 362b2d4247SSakari AilusAn ASL example of a camera sensor device and a LED driver device for two LEDs is 372b2d4247SSakari Ailusshow below. Objects not relevant for LEDs or the references to them have been 382b2d4247SSakari Ailusomitted. :: 392b2d4247SSakari Ailus 402b2d4247SSakari Ailus Device (LED) 412b2d4247SSakari Ailus { 422b2d4247SSakari Ailus Name (_DSD, Package () { 432b2d4247SSakari Ailus ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), 442b2d4247SSakari Ailus Package () { 452b2d4247SSakari Ailus Package () { "led@0", LED0 }, 462b2d4247SSakari Ailus Package () { "led@1", LED1 }, 472b2d4247SSakari Ailus } 482b2d4247SSakari Ailus }) 492b2d4247SSakari Ailus Name (LED0, Package () { 502b2d4247SSakari Ailus ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), 512b2d4247SSakari Ailus Package () { 522b2d4247SSakari Ailus Package () { "reg", 0 }, 532b2d4247SSakari Ailus Package () { "flash-max-microamp", 1000000 }, 542b2d4247SSakari Ailus Package () { "flash-timeout-us", 200000 }, 552b2d4247SSakari Ailus Package () { "led-max-microamp", 100000 }, 562b2d4247SSakari Ailus Package () { "label", "white:flash" }, 572b2d4247SSakari Ailus } 582b2d4247SSakari Ailus }) 592b2d4247SSakari Ailus Name (LED1, Package () { 602b2d4247SSakari Ailus ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), 612b2d4247SSakari Ailus Package () { 622b2d4247SSakari Ailus Package () { "reg", 1 }, 632b2d4247SSakari Ailus Package () { "led-max-microamp", 10000 }, 642b2d4247SSakari Ailus Package () { "label", "red:indicator" }, 652b2d4247SSakari Ailus } 662b2d4247SSakari Ailus }) 672b2d4247SSakari Ailus } 682b2d4247SSakari Ailus 692b2d4247SSakari Ailus Device (SEN) 702b2d4247SSakari Ailus { 712b2d4247SSakari Ailus Name (_DSD, Package () { 722b2d4247SSakari Ailus ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), 732b2d4247SSakari Ailus Package () { 742b2d4247SSakari Ailus Package () { 752b2d4247SSakari Ailus "flash-leds", 762b2d4247SSakari Ailus Package () { ^LED, "led@0", ^LED, "led@1" }, 772b2d4247SSakari Ailus } 782b2d4247SSakari Ailus } 792b2d4247SSakari Ailus }) 802b2d4247SSakari Ailus } 812b2d4247SSakari Ailus 822b2d4247SSakari Ailuswhere 832b2d4247SSakari Ailus:: 842b2d4247SSakari Ailus 852b2d4247SSakari Ailus LED LED driver device 862b2d4247SSakari Ailus LED0 First LED 872b2d4247SSakari Ailus LED1 Second LED 882b2d4247SSakari Ailus SEN Camera sensor device (or another device the LED is related to) 892b2d4247SSakari Ailus 902b2d4247SSakari AilusReferences 912b2d4247SSakari Ailus========== 922b2d4247SSakari Ailus 932b2d4247SSakari Ailus[1] Device tree. <URL:http://www.devicetree.org>, referenced 2019-02-21. 942b2d4247SSakari Ailus 952b2d4247SSakari Ailus[2] Advanced Configuration and Power Interface Specification. 962b2d4247SSakari Ailus <URL:https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf>, 972b2d4247SSakari Ailus referenced 2019-02-21. 982b2d4247SSakari Ailus 992b2d4247SSakari Ailus[3] Documentation/devicetree/bindings/leds/common.txt 1002b2d4247SSakari Ailus 1012b2d4247SSakari Ailus[4] Documentation/devicetree/bindings/media/video-interfaces.txt 1022b2d4247SSakari Ailus 1032b2d4247SSakari Ailus[5] Device Properties UUID For _DSD. 1042b2d4247SSakari Ailus <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>, 1052b2d4247SSakari Ailus referenced 2019-02-21. 1062b2d4247SSakari Ailus 1072b2d4247SSakari Ailus[6] Hierarchical Data Extension UUID For _DSD. 1082b2d4247SSakari Ailus <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>, 1092b2d4247SSakari Ailus referenced 2019-02-21. 1102b2d4247SSakari Ailus 1112b2d4247SSakari Ailus[7] Documentation/firmware-guide/acpi/dsd/data-node-references.rst 112