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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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@xxxxxxxxxxxxxxx>
> > Acked-by: Jacek Anaszewski <jacek.anaszewski@xxxxxxxxx>
> > ---
> >   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
> > 
> 

-- 
Kind regards,

Sakari Ailus
sakari.ailus@xxxxxxxxxxxxxxx



[Index of Archives]     [Linux IBM ACPI]     [Linux Power Management]     [Linux Kernel]     [Linux Laptop]     [Kernel Newbies]     [Share Photos]     [Security]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux