Documentation/firmware-guide/acpi/dsd/leds.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2 .. include:: <isonum.txt>
   3
   4 ========================================
   5 Describing and referring to LEDs in ACPI
   6 ========================================
   7
   8 Individual LEDs are described by hierarchical data extension [6] nodes under the
   9 device node, the LED driver chip. The "reg" property in the LED specific nodes
  10 tells the numerical ID of each individual LED output to which the LEDs are
  11 connected. [3] The hierarchical data nodes are named "led@X", where X is the
  12 number of the LED output.
  13
  14 Referring to LEDs in Device tree is documented in [4], in "flash-leds" property
  15 documentation. In short, LEDs are directly referred to by using phandles.
  16
  17 While Device tree allows referring to any node in the tree[1], in ACPI
  18 references are limited to device nodes only [2]. For this reason using the same
  19 mechanism on ACPI is not possible. A mechanism to refer to non-device ACPI nodes
  20 is documented in [7].
  21
  22 ACPI allows (as does DT) using integer arguments after the reference. A
  23 combination of the LED driver device reference and an integer argument,
  24 referring to the "reg" property of the relevant LED, is used to identify
  25 individual LEDs. The value of the "reg" property is a contract between the
  26 firmware and software, it uniquely identifies the LED driver outputs.
  27
  28 Under the LED driver device, The first hierarchical data extension package list
  29 entry shall contain the string "led@" followed by the number of the LED,
  30 followed by the referred object name. That object shall be named "LED" followed
  31 by the number of the LED.
  32
  33 Example
  34 =======
  35
  36 An ASL example of a camera sensor device and a LED driver device for two LEDs is
  37 show below. Objects not relevant for LEDs or the references to them have been
  38 omitted. ::
  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
  82 where
  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
  90 References
  91 ==========
  92
  93 [1] Device tree. https://www.devicetree.org, referenced 2019-02-21.
  94
  95 [2] Advanced Configuration and Power Interface Specification.
  96     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     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     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