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

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(-)

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
> 
>