[PATCH 1/3] dt-bindings: leds: Deprecate `linux,default-trigger` property

[PATCH 1/3] dt-bindings: leds: Deprecate `linux,default-trigger` property

[Marek Behún]

This property is deprecated in favor of the `function` property.

Signed-off-by: Marek Behún <kabel@kernel.org>
---
 Documentation/devicetree/bindings/leds/common.yaml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/devicetree/bindings/leds/common.yaml b/Documentation/devicetree/bindings/leds/common.yaml
index 697102707703..a19acc781e89 100644
--- a/Documentation/devicetree/bindings/leds/common.yaml
+++ b/Documentation/devicetree/bindings/leds/common.yaml
@@ -78,6 +78,7 @@ properties:
       This parameter, if present, is a string defining the trigger assigned to
       the LED.
     $ref: /schemas/types.yaml#/definitions/string
+    deprecated: true
 
     enum:
         # LED will act as a back-light, controlled by the framebuffer system
-- 
2.32.0

[PATCH 2/3] dt-bindings: leds: Add `excludes` property

[Marek Behún]

Some RJ-45 connectors have LEDs wired in the following way:

         LED1
      +--|>|--+
      |       |
  A---+--|<|--+---B
         LED2

With + on A and - on B, LED1 is ON and LED2 is OFF. Inverting the
polarity turns LED1 OFF and LED2 ON.

So these LEDs exclude each other.

Add new `excludes` property to the LED binding. The property is a
phandle-array to all the other LEDs that are excluded by this LED.

Signed-off-by: Marek Behún <kabel@kernel.org>
---
 Documentation/devicetree/bindings/leds/common.yaml | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Documentation/devicetree/bindings/leds/common.yaml b/Documentation/devicetree/bindings/leds/common.yaml
index a19acc781e89..03759d2e125a 100644
--- a/Documentation/devicetree/bindings/leds/common.yaml
+++ b/Documentation/devicetree/bindings/leds/common.yaml
@@ -59,6 +59,14 @@ properties:
       deprecated - use 'function' and 'color' properties instead.
       function-enumerator has no effect when this property is present.
 
+  excludes:
+    description:
+      List of LEDs that are excluded by this LED: if this LED is ON, the others
+      must be OFF. This is mostly the case when there are two LEDs connected in
+      parallel, but inversely: inverting the polarity of the source turns one
+      LED ON while the other OFF. There are RJ-45 connectors with such wiring.
+    $ref: /schemas/types.yaml#/definitions/phandle-array
+
   default-state:
     description:
       The initial state of the LED. If the LED is already on or off and the
-- 
2.32.0

[PATCH 3/3] dt-bindings: leds: Allow for multiple colors in the `color` property

[Marek Behún]

Some RJ-45 connectors have one green/yellow LED wired in the following
way:

        green
      +--|>|--+
      |       |
  A---+--|<|--+---B
        yellow

But semantically this is still just one (multi-color) LED (for example
it can be controlled by HW as one dual-LED).

This is a case that we do not support in device tree bindings; setting
  color = <LED_COLOR_ID_MULTI>;
or
  color = <LED_COLOR_ID_RGB>;
is wrong, because those are meant for when the controller can mix the
"channels", while for our case only one "channel" can be active at a
time.

Change the `color` property to accept an (non-empty) array of colors to
indicate this case.

Example:
  ethernet-phy {
    led@0 {
      reg = <0>;
      color = <LED_COLOR_ID_GREEN LED_COLOR_ID_YELLOW>;
      function = LED_FUNCTION_ID_LAN;
      trigger-sources = <&eth0>;
    };
  };

Signed-off-by: Marek Behún <kabel@kernel.org>
---
 .../devicetree/bindings/leds/common.yaml         | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

diff --git a/Documentation/devicetree/bindings/leds/common.yaml b/Documentation/devicetree/bindings/leds/common.yaml
index 03759d2e125a..492dd3e7f9ac 100644
--- a/Documentation/devicetree/bindings/leds/common.yaml
+++ b/Documentation/devicetree/bindings/leds/common.yaml
@@ -37,13 +37,21 @@ properties:
     $ref: /schemas/types.yaml#/definitions/string
 
   color:
-    description:
+    description: |
       Color of the LED. Use one of the LED_COLOR_ID_* prefixed definitions from
       the header include/dt-bindings/leds/common.h. If there is no matching
       LED_COLOR_ID available, add a new one.
-    $ref: /schemas/types.yaml#/definitions/uint32
-    minimum: 0
-    maximum: 9
+
+      For multi color LEDs there are two cases:
+        - the LED can mix the channels (i.e. RGB LED); in this case use
+          LED_COLOR_ID_MULTI or LED_COLOR_ID_RGB
+        - the LED cannot mix the channels, only one can be active; in this case
+          enumerate all the possible colors
+    $ref: /schemas/types.yaml#/definitions/uint32-array
+    minItems: 1
+    items:
+      minimum: 0
+      maximum: 9
 
   function-enumerator:
     description:
-- 
2.32.0

Re: [PATCH 2/3] dt-bindings: leds: Add `excludes` property

[Rob Herring]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 3688 bytes --]

On Wed, 13 Oct 2021 22:44:23 +0200, Marek Behún wrote:
> Some RJ-45 connectors have LEDs wired in the following way:
> 
>          LED1
>       +--|>|--+
>       |       |
>   A---+--|<|--+---B
>          LED2
> 
> With + on A and - on B, LED1 is ON and LED2 is OFF. Inverting the
> polarity turns LED1 OFF and LED2 ON.
> 
> So these LEDs exclude each other.
> 
> Add new `excludes` property to the LED binding. The property is a
> phandle-array to all the other LEDs that are excluded by this LED.
> 
> Signed-off-by: Marek Behún <kabel@kernel.org>
> ---
>  Documentation/devicetree/bindings/leds/common.yaml | 8 ++++++++
>  1 file changed, 8 insertions(+)
> 

My bot found errors running 'make DT_CHECKER_FLAGS=-m dt_binding_check'
on your patch (DT_CHECKER_FLAGS is new in v5.13):

yamllint warnings/errors:
./Documentation/devicetree/bindings/leds/common.yaml:66:7: [error] syntax error: could not find expected ':' (syntax)

dtschema/dtc warnings/errors:
make[1]: *** Deleting file 'Documentation/devicetree/bindings/leds/common.example.dts'
Traceback (most recent call last):
  File "/usr/local/bin/dt-extract-example", line 45, in <module>
    binding = yaml.load(open(args.yamlfile, encoding='utf-8').read())
  File "/usr/local/lib/python3.8/dist-packages/ruamel/yaml/main.py", line 434, in load
    return constructor.get_single_data()
  File "/usr/local/lib/python3.8/dist-packages/ruamel/yaml/constructor.py", line 120, in get_single_data
    node = self.composer.get_single_node()
  File "_ruamel_yaml.pyx", line 706, in _ruamel_yaml.CParser.get_single_node
  File "_ruamel_yaml.pyx", line 724, in _ruamel_yaml.CParser._compose_document
  File "_ruamel_yaml.pyx", line 775, in _ruamel_yaml.CParser._compose_node
  File "_ruamel_yaml.pyx", line 889, in _ruamel_yaml.CParser._compose_mapping_node
  File "_ruamel_yaml.pyx", line 775, in _ruamel_yaml.CParser._compose_node
  File "_ruamel_yaml.pyx", line 889, in _ruamel_yaml.CParser._compose_mapping_node
  File "_ruamel_yaml.pyx", line 775, in _ruamel_yaml.CParser._compose_node
  File "_ruamel_yaml.pyx", line 889, in _ruamel_yaml.CParser._compose_mapping_node
  File "_ruamel_yaml.pyx", line 775, in _ruamel_yaml.CParser._compose_node
  File "_ruamel_yaml.pyx", line 891, in _ruamel_yaml.CParser._compose_mapping_node
  File "_ruamel_yaml.pyx", line 904, in _ruamel_yaml.CParser._parse_next_event
ruamel.yaml.scanner.ScannerError: while scanning a simple key
  in "<unicode string>", line 65, column 7
could not find expected ':'
  in "<unicode string>", line 66, column 7
make[1]: *** [Documentation/devicetree/bindings/Makefile:20: Documentation/devicetree/bindings/leds/common.example.dts] Error 1
make[1]: *** Waiting for unfinished jobs....
schemas/leds/common.yaml: ignoring, error parsing file
schemas/leds/common.yaml: ignoring, error parsing file
./Documentation/devicetree/bindings/leds/common.yaml:  while scanning a simple key
  in "<unicode string>", line 65, column 7
could not find expected ':'
  in "<unicode string>", line 66, column 7
/builds/robherring/linux-dt-review/Documentation/devicetree/bindings/leds/common.yaml: ignoring, error parsing file
warning: no schema found in file: ./Documentation/devicetree/bindings/leds/common.yaml
make: *** [Makefile:1441: dt_binding_check] Error 2

doc reference errors (make refcheckdocs):

See https://patchwork.ozlabs.org/patch/1540615

This check can fail if there are any dependencies. The base for a patch
series is generally the most recent rc1.

If you already ran 'make dt_binding_check' and didn't see the above
error(s), then make sure 'yamllint' is installed and dt-schema is up to
date:

pip3 install dtschema --upgrade

Please check and re-submit.

Re: [PATCH 2/3] dt-bindings: leds: Add `excludes` property

[Pavel Machek]

[-- Attachment #1: Type: text/plain, Size: 751 bytes --]

Hi!

> Some RJ-45 connectors have LEDs wired in the following way:
> 
>          LED1
>       +--|>|--+
>       |       |
>   A---+--|<|--+---B
>          LED2
> 
> With + on A and - on B, LED1 is ON and LED2 is OFF. Inverting the
> polarity turns LED1 OFF and LED2 ON.
> 
> So these LEDs exclude each other.
> 
> Add new `excludes` property to the LED binding. The property is a
> phandle-array to all the other LEDs that are excluded by this LED.

I don't think this belongs to the LED binding.

This is controller limitation, and the driver handling the controller
needs to know about it... so it does not need to learn that from the
LED binding.

Best regards,
								Pavel
-- 
http://www.livejournal.com/~pavelmachek

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

Re: [PATCH 2/3] dt-bindings: leds: Add `excludes` property

[Marek Behún]

On Thu, 14 Oct 2021 12:29:18 +0200
Pavel Machek <pavel@ucw.cz> wrote:

> Hi!
> 
> > Some RJ-45 connectors have LEDs wired in the following way:
> > 
> >          LED1
> >       +--|>|--+
> >       |       |
> >   A---+--|<|--+---B
> >          LED2
> > 
> > With + on A and - on B, LED1 is ON and LED2 is OFF. Inverting the
> > polarity turns LED1 OFF and LED2 ON.
> > 
> > So these LEDs exclude each other.
> > 
> > Add new `excludes` property to the LED binding. The property is a
> > phandle-array to all the other LEDs that are excluded by this LED.  
> 
> I don't think this belongs to the LED binding.
> 
> This is controller limitation, and the driver handling the controller
> needs to know about it... so it does not need to learn that from the
> LED binding.

It's not necessarily a controller limitation, rather a limitation of
the board (or ethernet connector, in the case of LEDs on an ethernet
connector).

But I guess we could instead document this property in the ethernet PHY
controller binding for a given PHY.

Marek

Re: [PATCH 2/3] dt-bindings: leds: Add `excludes` property

[Alexander Dahl]

Hei hei,

Am Thu, Oct 14, 2021 at 12:43:09PM +0200 schrieb Marek Behún:
> On Thu, 14 Oct 2021 12:29:18 +0200
> Pavel Machek <pavel@ucw.cz> wrote:
> 
> > Hi!
> > 
> > > Some RJ-45 connectors have LEDs wired in the following way:
> > > 
> > >          LED1
> > >       +--|>|--+
> > >       |       |
> > >   A---+--|<|--+---B
> > >          LED2
> > > 
> > > With + on A and - on B, LED1 is ON and LED2 is OFF. Inverting the
> > > polarity turns LED1 OFF and LED2 ON.
> > > 
> > > So these LEDs exclude each other.
> > > 
> > > Add new `excludes` property to the LED binding. The property is a
> > > phandle-array to all the other LEDs that are excluded by this LED.  
> > 
> > I don't think this belongs to the LED binding.
> > 
> > This is controller limitation, and the driver handling the controller
> > needs to know about it... so it does not need to learn that from the
> > LED binding.
> 
> It's not necessarily a controller limitation, rather a limitation of
> the board (or ethernet connector, in the case of LEDs on an ethernet
> connector).

Such LEDs are not limited to PHYs or ethernet connectors.  There is
hardware with such dual color LEDs connected to GPIO pins (either
directly to the SoC or through some GPIO expander like an 74hc595
shift register).  That mail points to such hardware:

https://www.spinics.net/lists/linux-leds/msg11847.html

I asked about how this can be modelled back in 2019 and it was also
discussed last year:

https://www.spinics.net/lists/linux-leds/msg11665.html
https://lore.kernel.org/linux-leds/2315048.uTtSMl1LR1@ada/

The "solution" back when I first asked was treating them as ordinary
GPIO-LEDs and ignore the "exclusion topic" which means in practice the
LED goes OFF if both pins are ON (high) at the same time, which works
well enough in practice.

> But I guess we could instead document this property in the ethernet PHY
> controller binding for a given PHY.

Because such LEDs are not restricted to ethernet PHYs, but can also be
used with GPIOs from the hardware point of view, I would not put it
there.

Furthermore I would not view this as a restriction of the gpio-leds
controller, but it's a property of the LEDs itself or the way they are
wired to the board.

This could (or should as Pavel suggested back in 2019) be put to a new
driver, at least for the GPIO case, but it would need some kind of new
binding anyways.  With that in mind I consider the proposed binding to
be well comprehensible for a human reader/writer.

I'm sorry, I did not have leisure time to implement such a driver yet.
Breadboard hardware for that still waiting in the drawer. :-/

Greets
Alex

Re: [PATCH 2/3] dt-bindings: leds: Add `excludes` property

[Marek Behún]

On Thu, 14 Oct 2021 13:30:39 +0200
Alexander Dahl <ada@thorsis.com> wrote:

> Hei hei,
> 
> Am Thu, Oct 14, 2021 at 12:43:09PM +0200 schrieb Marek Behún:
> > On Thu, 14 Oct 2021 12:29:18 +0200
> > Pavel Machek <pavel@ucw.cz> wrote:
> >   
> > > Hi!
> > >   
> > > > Some RJ-45 connectors have LEDs wired in the following way:
> > > > 
> > > >          LED1
> > > >       +--|>|--+
> > > >       |       |
> > > >   A---+--|<|--+---B
> > > >          LED2
> > > > 
> > > > With + on A and - on B, LED1 is ON and LED2 is OFF. Inverting
> > > > the polarity turns LED1 OFF and LED2 ON.
> > > > 
> > > > So these LEDs exclude each other.
> > > > 
> > > > Add new `excludes` property to the LED binding. The property is
> > > > a phandle-array to all the other LEDs that are excluded by this
> > > > LED.    
> > > 
> > > I don't think this belongs to the LED binding.
> > > 
> > > This is controller limitation, and the driver handling the
> > > controller needs to know about it... so it does not need to learn
> > > that from the LED binding.  
> > 
> > It's not necessarily a controller limitation, rather a limitation of
> > the board (or ethernet connector, in the case of LEDs on an ethernet
> > connector).  
> 
> Such LEDs are not limited to PHYs or ethernet connectors.  There is
> hardware with such dual color LEDs connected to GPIO pins (either
> directly to the SoC or through some GPIO expander like an 74hc595
> shift register).  That mail points to such hardware:
> 
> https://www.spinics.net/lists/linux-leds/msg11847.html
> 
> I asked about how this can be modelled back in 2019 and it was also
> discussed last year:
> 
> https://www.spinics.net/lists/linux-leds/msg11665.html
> https://lore.kernel.org/linux-leds/2315048.uTtSMl1LR1@ada/
> 
> The "solution" back when I first asked was treating them as ordinary
> GPIO-LEDs and ignore the "exclusion topic" which means in practice the
> LED goes OFF if both pins are ON (high) at the same time, which works
> well enough in practice.
> 
> > But I guess we could instead document this property in the ethernet
> > PHY controller binding for a given PHY.  
> 
> Because such LEDs are not restricted to ethernet PHYs, but can also be
> used with GPIOs from the hardware point of view, I would not put it
> there.
> 
> Furthermore I would not view this as a restriction of the gpio-leds
> controller, but it's a property of the LEDs itself or the way they are
> wired to the board.
> 
> This could (or should as Pavel suggested back in 2019) be put to a new
> driver, at least for the GPIO case, but it would need some kind of new
> binding anyways.  With that in mind I consider the proposed binding to
> be well comprehensible for a human reader/writer.
> 
> I'm sorry, I did not have leisure time to implement such a driver yet.
> Breadboard hardware for that still waiting in the drawer. :-/

That's why I think we need the `excludes` property.

On the sw side, it should work like this:
$ cd /sys/class/leds
$ echo 1 >LED1/brightness
$ cat LED1/brightness LED2/brightness
1
0
$ echo 1 >LED2/brightness
$ cat LED1/brightness LED2/brightness
0
1

The drivers could also implement brightness_hw_changed for these LEDs.

Marek

Re: [PATCH 1/3] dt-bindings: leds: Deprecate `linux,default-trigger` property

[Rob Herring]

On Wed, 13 Oct 2021 22:44:22 +0200, Marek Behún wrote:
> This property is deprecated in favor of the `function` property.
> 
> Signed-off-by: Marek Behún <kabel@kernel.org>
> ---
>  Documentation/devicetree/bindings/leds/common.yaml | 1 +
>  1 file changed, 1 insertion(+)
> 

Acked-by: Rob Herring <robh@kernel.org>

Re: [PATCH 3/3] dt-bindings: leds: Allow for multiple colors in the `color` property

[Rob Herring]

On Wed, Oct 13, 2021 at 10:44:24PM +0200, Marek Behún wrote:
> Some RJ-45 connectors have one green/yellow LED wired in the following
> way:
> 
>         green
>       +--|>|--+
>       |       |
>   A---+--|<|--+---B
>         yellow
> 
> But semantically this is still just one (multi-color) LED (for example
> it can be controlled by HW as one dual-LED).
> 
> This is a case that we do not support in device tree bindings; setting
>   color = <LED_COLOR_ID_MULTI>;
> or
>   color = <LED_COLOR_ID_RGB>;
> is wrong, because those are meant for when the controller can mix the
> "channels", while for our case only one "channel" can be active at a
> time.
> 
> Change the `color` property to accept an (non-empty) array of colors to
> indicate this case.
> 
> Example:
>   ethernet-phy {
>     led@0 {
>       reg = <0>;
>       color = <LED_COLOR_ID_GREEN LED_COLOR_ID_YELLOW>;
>       function = LED_FUNCTION_ID_LAN;
>       trigger-sources = <&eth0>;
>     };
>   };
> 
> Signed-off-by: Marek Behún <kabel@kernel.org>
> ---
>  .../devicetree/bindings/leds/common.yaml         | 16 ++++++++++++----
>  1 file changed, 12 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/devicetree/bindings/leds/common.yaml b/Documentation/devicetree/bindings/leds/common.yaml
> index 03759d2e125a..492dd3e7f9ac 100644
> --- a/Documentation/devicetree/bindings/leds/common.yaml
> +++ b/Documentation/devicetree/bindings/leds/common.yaml
> @@ -37,13 +37,21 @@ properties:
>      $ref: /schemas/types.yaml#/definitions/string
>  
>    color:
> -    description:
> +    description: |
>        Color of the LED. Use one of the LED_COLOR_ID_* prefixed definitions from
>        the header include/dt-bindings/leds/common.h. If there is no matching
>        LED_COLOR_ID available, add a new one.
> -    $ref: /schemas/types.yaml#/definitions/uint32
> -    minimum: 0
> -    maximum: 9
> +
> +      For multi color LEDs there are two cases:
> +        - the LED can mix the channels (i.e. RGB LED); in this case use
> +          LED_COLOR_ID_MULTI or LED_COLOR_ID_RGB
> +        - the LED cannot mix the channels, only one can be active; in this case
> +          enumerate all the possible colors
> +    $ref: /schemas/types.yaml#/definitions/uint32-array
> +    minItems: 1

And:

maxItems: 2

2 colors is a neat trick, but I don't see how you'd do more 
electrically.

> +    items:
> +      minimum: 0
> +      maximum: 9
>  
>    function-enumerator:
>      description:
> -- 
> 2.32.0
> 
>