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

login
register
mail settings
Submitter Sakari Ailus
Date Feb. 26, 2019, 10:42 a.m.
Message ID <20190226104258.4262-1-sakari.ailus@linux.intel.com>
Download mbox | patch
Permalink /patch/735843/
State New
Headers show

Comments

Sakari Ailus - Feb. 26, 2019, 10:42 a.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. 26, 2019, 7:06 p.m.
Hi Sakari,

Thank you for the update.

Patch set looks good to me as far as LEDs are concerned.

I can take 1/2 as well, but need an ack from ACPI maintainer.

Cc Rafael and Len.

Best regards,
Jacek Anaszewski

On 2/26/19 11:42 AM, 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..81a63af42ed2
> --- /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", "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. <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
>
Rafael J. Wysocki - Feb. 26, 2019, 9:53 p.m.
On Tue, Feb 26, 2019 at 8:06 PM Jacek Anaszewski
<jacek.anaszewski@gmail.com> wrote:
>
> Hi Sakari,
>
> Thank you for the update.
>
> Patch set looks good to me as far as LEDs are concerned.
>
> I can take 1/2 as well, but need an ack from ACPI maintainer.

Go for it!

Acked-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

>
> Cc Rafael and Len.
>
> Best regards,
> Jacek Anaszewski
>
> On 2/26/19 11:42 AM, 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..81a63af42ed2
> > --- /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", "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. <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. 27, 2019, 7:53 a.m.
On Tue, Feb 26, 2019 at 10:53:55PM +0100, Rafael J. Wysocki wrote:
> On Tue, Feb 26, 2019 at 8:06 PM Jacek Anaszewski
> <jacek.anaszewski@gmail.com> wrote:
> >
> > Hi Sakari,
> >
> > Thank you for the update.
> >
> > Patch set looks good to me as far as LEDs are concerned.
> >
> > I can take 1/2 as well, but need an ack from ACPI maintainer.
> 
> Go for it!
> 
> Acked-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

Thanks, Rafael and Jacek!

Patch

diff --git a/Documentation/acpi/dsd/leds.txt b/Documentation/acpi/dsd/leds.txt
new file mode 100644
index 000000000000..81a63af42ed2
--- /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", "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. <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