leds.rst

  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