Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
From:   =?UTF-8?q?Marek=20Beh=C3=BAn?= <kabel@kernel.org>
To:     devicetree@vger.kernel.org, linux-leds@vger.kernel.org,
        pavel@ucw.cz, Andrew Lunn <andrew@lunn.ch>
Cc:     robh+dt@kernel.org, Jacek Anaszewski <jacek.anaszewski@gmail.com>,
        netdev@vger.kernel.org, linux-kernel@vger.kernel.org,
        =?UTF-8?q?Marek=20Beh=C3=BAn?= <kabel@kernel.org>
Subject: [PATCH 3/3] dt-bindings: leds: Allow for multiple colors in the `color` property
Date:   Wed, 13 Oct 2021 22:44:24 +0200
Message-Id: <20211013204424.10961-3-kabel@kernel.org>
In-Reply-To: <20211013204424.10961-1-kabel@kernel.org>
References: <20211013204424.10961-1-kabel@kernel.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Precedence: bulk

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