From 2b2d4247e445b97113c5e61df8fbc0d756482ef8 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Wed, 14 Aug 2019 15:58:58 +0300 Subject: Documentation: ACPI: DSD: Convert LED documentation to ReST Convert the LED documentation in text format into ReST. Signed-off-by: Sakari Ailus Signed-off-by: Rafael J. Wysocki --- Documentation/acpi/dsd/leds.txt | 99 ---------------------- Documentation/firmware-guide/acpi/dsd/leds.rst | 111 +++++++++++++++++++++++++ Documentation/firmware-guide/acpi/index.rst | 1 + 3 files changed, 112 insertions(+), 99 deletions(-) delete mode 100644 Documentation/acpi/dsd/leds.txt create mode 100644 Documentation/firmware-guide/acpi/dsd/leds.rst (limited to 'Documentation') diff --git a/Documentation/acpi/dsd/leds.txt b/Documentation/acpi/dsd/leds.txt deleted file mode 100644 index cc58b1a574c5..000000000000 --- a/Documentation/acpi/dsd/leds.txt +++ /dev/null @@ -1,99 +0,0 @@ -Describing and referring to LEDs in ACPI - -Individual LEDs are described by hierarchical data extension [6] nodes under the -device node, the LED driver chip. The "reg" property in the LED specific nodes -tells the numerical ID of each individual LED output to which the LEDs are -connected. [3] The hierarchical data nodes are named "led@X", where X is the -number of the LED output. - -Referring to LEDs in Device tree is documented in [4], in "flash-leds" property -documentation. In short, LEDs are directly referred to by using phandles. - -While Device tree allows referring to any node in the tree[1], in ACPI -references are limited to device nodes only [2]. For this reason using the same -mechanism on ACPI is not possible. A mechanism to refer to non-device ACPI nodes -is documented in [7]. - -ACPI allows (as does DT) using integer arguments after the reference. A -combination of the LED driver device reference and an integer argument, -referring to the "reg" property of the relevant LED, is used to identify -individual LEDs. The value of the "reg" property is a contract between the -firmware and software, it uniquely identifies the LED driver outputs. - -Under the LED driver device, The first hierarchical data extension package list -entry shall contain the string "led@" followed by the number of the LED, -followed by the referred object name. That object shall be named "LED" followed -by the number of the LED. - -An ASL example of a camera sensor device and a LED driver device for two LEDs. -Objects not relevant for LEDs or the references to them have been omitted. - - Device (LED) - { - Name (_DSD, Package () { - ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), - Package () { - Package () { "led@0", LED0 }, - Package () { "led@1", LED1 }, - } - }) - Name (LED0, Package () { - ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), - Package () { - Package () { "reg", 0 }, - Package () { "flash-max-microamp", 1000000 }, - Package () { "flash-timeout-us", 200000 }, - Package () { "led-max-microamp", 100000 }, - Package () { "label", "white:flash" }, - } - }) - Name (LED1, Package () { - ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), - Package () { - Package () { "reg", 1 }, - Package () { "led-max-microamp", 10000 }, - Package () { "label", "red:indicator" }, - } - }) - } - - Device (SEN) - { - Name (_DSD, Package () { - ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), - Package () { - Package () { - "flash-leds", - Package () { ^LED, "led@0", ^LED, "led@1" }, - } - } - }) - } - -where - - LED LED driver device - LED0 First LED - LED1 Second LED - SEN Camera sensor device (or another device the LED is - related to) - -[1] Device tree. , referenced 2019-02-21. - -[2] Advanced Configuration and Power Interface Specification. - , - referenced 2019-02-21. - -[3] Documentation/devicetree/bindings/leds/common.txt - -[4] Documentation/devicetree/bindings/media/video-interfaces.txt - -[5] Device Properties UUID For _DSD. - , - referenced 2019-02-21. - -[6] Hierarchical Data Extension UUID For _DSD. - , - referenced 2019-02-21. - -[7] Documentation/firmware-guide/acpi/dsd/data-node-references.rst diff --git a/Documentation/firmware-guide/acpi/dsd/leds.rst b/Documentation/firmware-guide/acpi/dsd/leds.rst new file mode 100644 index 000000000000..946efe2b2936 --- /dev/null +++ b/Documentation/firmware-guide/acpi/dsd/leds.rst @@ -0,0 +1,111 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: + +======================================== +Describing and referring to LEDs in ACPI +======================================== + +Individual LEDs are described by hierarchical data extension [6] nodes under the +device node, the LED driver chip. The "reg" property in the LED specific nodes +tells the numerical ID of each individual LED output to which the LEDs are +connected. [3] The hierarchical data nodes are named "led@X", where X is the +number of the LED output. + +Referring to LEDs in Device tree is documented in [4], in "flash-leds" property +documentation. In short, LEDs are directly referred to by using phandles. + +While Device tree allows referring to any node in the tree[1], in ACPI +references are limited to device nodes only [2]. For this reason using the same +mechanism on ACPI is not possible. A mechanism to refer to non-device ACPI nodes +is documented in [7]. + +ACPI allows (as does DT) using integer arguments after the reference. A +combination of the LED driver device reference and an integer argument, +referring to the "reg" property of the relevant LED, is used to identify +individual LEDs. The value of the "reg" property is a contract between the +firmware and software, it uniquely identifies the LED driver outputs. + +Under the LED driver device, The first hierarchical data extension package list +entry shall contain the string "led@" followed by the number of the LED, +followed by the referred object name. That object shall be named "LED" followed +by the number of the LED. + +Example +======= + +An ASL example of a camera sensor device and a LED driver device for two LEDs is +show below. Objects not relevant for LEDs or the references to them have been +omitted. :: + + Device (LED) + { + Name (_DSD, Package () { + ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), + Package () { + Package () { "led@0", LED0 }, + Package () { "led@1", LED1 }, + } + }) + Name (LED0, Package () { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "reg", 0 }, + Package () { "flash-max-microamp", 1000000 }, + Package () { "flash-timeout-us", 200000 }, + Package () { "led-max-microamp", 100000 }, + Package () { "label", "white:flash" }, + } + }) + Name (LED1, Package () { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "reg", 1 }, + Package () { "led-max-microamp", 10000 }, + Package () { "label", "red:indicator" }, + } + }) + } + + Device (SEN) + { + Name (_DSD, Package () { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { + "flash-leds", + Package () { ^LED, "led@0", ^LED, "led@1" }, + } + } + }) + } + +where +:: + + LED LED driver device + LED0 First LED + LED1 Second LED + SEN Camera sensor device (or another device the LED is related to) + +References +========== + +[1] Device tree. , referenced 2019-02-21. + +[2] Advanced Configuration and Power Interface Specification. + , + referenced 2019-02-21. + +[3] Documentation/devicetree/bindings/leds/common.txt + +[4] Documentation/devicetree/bindings/media/video-interfaces.txt + +[5] Device Properties UUID For _DSD. + , + referenced 2019-02-21. + +[6] Hierarchical Data Extension UUID For _DSD. + , + referenced 2019-02-21. + +[7] Documentation/firmware-guide/acpi/dsd/data-node-references.rst diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst index 90c90d42d9ad..ad3b5afdae77 100644 --- a/Documentation/firmware-guide/acpi/index.rst +++ b/Documentation/firmware-guide/acpi/index.rst @@ -10,6 +10,7 @@ ACPI Support namespace dsd/graph dsd/data-node-references + dsd/leds enumeration osi method-customizing -- cgit v1.2.3-59-g8ed1b