Patchwork [v2,1/2] ACPI: Document how to refer to LEDs from remote nodes

login
register
mail settings
Submitter Sakari Ailus
Date Feb. 25, 2019, 12:23 p.m.
Message ID <20190225122341.3407-2-sakari.ailus@linux.intel.com>
Download mbox | patch
Permalink /patch/735041/
State New
Headers show

Comments

Sakari Ailus - Feb. 25, 2019, 12:23 p.m.
Document referring to LEDs from remote device nodes, such as from camera
sensors.

Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
Acked-by: Jacek Anaszewski <jacek.anaszewski@gmail.com>
---
 Documentation/acpi/dsd/leds.txt | 99 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 99 insertions(+)
 create mode 100644 Documentation/acpi/dsd/leds.txt
Jacek Anaszewski - Feb. 25, 2019, 6:50 p.m.
Hi Sakari,

I have one note below, must have overlooked that before.

On 2/25/19 1:23 PM, Sakari Ailus wrote:
> Document referring to LEDs from remote device nodes, such as from camera
> sensors.
> 
> Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
> Acked-by: Jacek Anaszewski <jacek.anaszewski@gmail.com>
> ---
>   Documentation/acpi/dsd/leds.txt | 99 +++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 99 insertions(+)
>   create mode 100644 Documentation/acpi/dsd/leds.txt
> 
> diff --git a/Documentation/acpi/dsd/leds.txt b/Documentation/acpi/dsd/leds.txt
> new file mode 100644
> index 000000000000..b665ed467f23
> --- /dev/null
> +++ b/Documentation/acpi/dsd/leds.txt
> @@ -0,0 +1,99 @@
> +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", "led:salama" },
Using Google translate I can infer that second section is
a function:

salama -> flash
huomiovalo -> torch (btw - isn't there a typo? The dictionary says that
                      this means "attention light", whereas huomivalo
                      means "a lamp").

What follows, the first section should be color, whereas we have "led"
here. Maybe it should be e.g. "white" ?

> +			}
> +		})
> +		Name (LED1, Package () {
> +			ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
> +			Package () {
> +				Package () { "reg", 1 },
> +				Package () { "led-max-microamp", 10000 },
> +				Package () { "label", "led:huomiovalo" },
> +			}
> +		})
> +	}
> +
> +	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. <URL:http://www.devicetree.org>, referenced 2019-02-21.
> +
> +[2] Advanced Configuration and Power Interface Specification.
> +    <URL:https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf>,
> +    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.
> +    <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>,
> +    referenced 2019-02-21.
> +
> +[6] Hierarchical Data Extension UUID For _DSD.
> +    <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,
> +    referenced 2019-02-21.
> +
> +[7] Documentation/acpi/dsd/data-node-reference.txt
>
Sakari Ailus - Feb. 26, 2019, 10:40 a.m.
Hi Jacek,

Thanks for the review!

On Mon, Feb 25, 2019 at 07:50:36PM +0100, Jacek Anaszewski wrote:
> Hi Sakari,
> 
> I have one note below, must have overlooked that before.
> 
> On 2/25/19 1:23 PM, Sakari Ailus wrote:
> > Document referring to LEDs from remote device nodes, such as from camera
> > sensors.
> > 
> > Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
> > Acked-by: Jacek Anaszewski <jacek.anaszewski@gmail.com>
> > ---
> >   Documentation/acpi/dsd/leds.txt | 99 +++++++++++++++++++++++++++++++++++++++++
> >   1 file changed, 99 insertions(+)
> >   create mode 100644 Documentation/acpi/dsd/leds.txt
> > 
> > diff --git a/Documentation/acpi/dsd/leds.txt b/Documentation/acpi/dsd/leds.txt
> > new file mode 100644
> > index 000000000000..b665ed467f23
> > --- /dev/null
> > +++ b/Documentation/acpi/dsd/leds.txt
> > @@ -0,0 +1,99 @@
> > +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", "led:salama" },
> Using Google translate I can infer that second section is
> a function:
> 
> salama -> flash
> huomiovalo -> torch (btw - isn't there a typo? The dictionary says that
>                      this means "attention light", whereas huomivalo
>                      means "a lamp").

Ah. :-) This is an indicator light (huomiovalo) indeed, not a torch: there
are two LEDs, one for the flash and another one for the indicator. That's
at least in a typical use case for the as3645a.

> 
> What follows, the first section should be color, whereas we have "led"
> here. Maybe it should be e.g. "white" ?

"white" for the flash LED and "red" for the indicator below?

I can also translate the names, they might be more easily understood by a
larger number of people that way. :-)

> 
> > +			}
> > +		})
> > +		Name (LED1, Package () {
> > +			ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
> > +			Package () {
> > +				Package () { "reg", 1 },
> > +				Package () { "led-max-microamp", 10000 },
> > +				Package () { "label", "led:huomiovalo" },
> > +			}
> > +		})
> > +	}
> > +
> > +	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. <URL:http://www.devicetree.org>, referenced 2019-02-21.
> > +
> > +[2] Advanced Configuration and Power Interface Specification.
> > +    <URL:https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf>,
> > +    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.
> > +    <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>,
> > +    referenced 2019-02-21.
> > +
> > +[6] Hierarchical Data Extension UUID For _DSD.
> > +    <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,
> > +    referenced 2019-02-21.
> > +
> > +[7] Documentation/acpi/dsd/data-node-reference.txt
> > 
>

Patch

diff --git a/Documentation/acpi/dsd/leds.txt b/Documentation/acpi/dsd/leds.txt
new file mode 100644
index 000000000000..b665ed467f23
--- /dev/null
+++ b/Documentation/acpi/dsd/leds.txt
@@ -0,0 +1,99 @@ 
+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", "led:salama" },
+			}
+		})
+		Name (LED1, Package () {
+			ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+			Package () {
+				Package () { "reg", 1 },
+				Package () { "led-max-microamp", 10000 },
+				Package () { "label", "led:huomiovalo" },
+			}
+		})
+	}
+
+	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. <URL:http://www.devicetree.org>, referenced 2019-02-21.
+
+[2] Advanced Configuration and Power Interface Specification.
+    <URL:https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf>,
+    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.
+    <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>,
+    referenced 2019-02-21.
+
+[6] Hierarchical Data Extension UUID For _DSD.
+    <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,
+    referenced 2019-02-21.
+
+[7] Documentation/acpi/dsd/data-node-reference.txt