linux-kernel - [RFC PATCH 2/2] dt-bindings: leds: common: Add led-instance property

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite for Android: free password hash cracker in your pocket

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20251228182252.1550173-3-professorjonny98@gmail.com>
Date: Mon, 29 Dec 2025 07:22:45 +1300
From: Jonathan Brophy <professorjonny98@...il.com>
To: lee Jones <lee@...nel.org>,
	Pavel Machek <pavel@...nel.org>,
	Andriy Shevencho <andriy.shevchenko@...ux.intel.com>,
	Jonathan Brophy <professor_jonny@...mail.com>,
	Rob Herring <robh@...nel.org>,
	Krzysztof Kozlowski <krzk+dt@...nel.org>,
	Conor Dooley <conor+dt@...nel.org>,
	Radoslav Tsvetkov <rtsvetkov@...dotech.eu>
Cc: devicetree@...r.kernel.org,
	linux-kernel@...r.kernel.org,
	linux-leds@...r.kernel.org
Subject: [RFC PATCH 2/2] dt-bindings: leds: common: Add led-instance property

From: Jonathan Brophy <professor_jonny@...mail.com>

Document the optional "led-instance" property for providing deterministic
LED naming when multiple LEDs share the same function and color.

Signed-off-by: Jonathan Brophy <professor_jonny@...mail.com>
---
 .../devicetree/bindings/leds/common.yaml      | 93 +++++++++++++++++++
 1 file changed, 93 insertions(+)

diff --git a/Documentation/devicetree/bindings/leds/common.yaml b/Documentation/devicetree/bindings/leds/common.yaml
index f4e44b33f56d..0e9611662850 100644
--- a/Documentation/devicetree/bindings/leds/common.yaml
+++ b/Documentation/devicetree/bindings/leds/common.yaml
@@ -51,6 +51,33 @@ properties:
       needed, differing only with an ordinal number.
     $ref: /schemas/types.yaml#/definitions/uint32

+  led-instance:
+    description:
+      Optional instance identifier for deterministic LED naming when multiple
+      LEDs share the same function and color. Without this property, the LED
+      core appends numerical suffixes (_1, _2) based on registration order,
+      which is non-deterministic and breaks userspace automation.
+
+      The instance identifier becomes the third component in the LED name
+      using the format "function:color:instance" (or "color:function-N:instance"
+      when function-enumerator is present).
+
+      This property is only used with the modern function and color based naming
+      scheme. It is ignored when the deprecated "label" property is present, as
+      "label" already provides full control over the LED name.
+
+      Common use cases include multi-port network devices ("port0", "port1"),
+      multi-domain power indicators ("battery", "ac", "usb"), and system state
+      LEDs ("boot", "upgrade", "panic").
+
+      The identifier should be semantic (describes purpose), deterministic
+      (fixed in hardware description), and concise (under 32 characters).
+      Only alphanumeric characters, dashes, and underscores are allowed, and
+      the identifier must start with an alphanumeric character.
+    $ref: /schemas/types.yaml#/definitions/string
+    maxLength: 31
+    pattern: "^[a-zA-Z0-9][a-zA-Z0-9_-]*$"
+
   label:
     description:
       The label for this LED. If omitted, the label is taken from the node name
@@ -320,4 +347,70 @@ examples:
         };
     };

+  - |
+    #include <dt-bindings/gpio/gpio.h>
+    #include <dt-bindings/leds/common.h>
+
+    /* Example: 48-port network switch with deterministic port LEDs */
+    ethernet-leds {
+        compatible = "gpio-leds";
+
+        led-port0 {
+            function = LED_FUNCTION_LAN;
+            color = <LED_COLOR_ID_GREEN>;
+            led-instance = "port0";
+            gpios = <&gpio0 0 GPIO_ACTIVE_HIGH>;
+            /* Result: /sys/class/leds/green:lan:port0 */
+        };
+
+        led-port1 {
+            function = LED_FUNCTION_LAN;
+            color = <LED_COLOR_ID_GREEN>;
+            led-instance = "port1";
+            gpios = <&gpio0 1 GPIO_ACTIVE_HIGH>;
+            /* Result: /sys/class/leds/green:lan:port1 */
+        };
+
+        led-port47 {
+            function = LED_FUNCTION_LAN;
+            color = <LED_COLOR_ID_GREEN>;
+            led-instance = "port47";
+            gpios = <&gpio0 47 GPIO_ACTIVE_HIGH>;
+            /* Result: /sys/class/leds/green:lan:port47 */
+        };
+    };
+
+  - |
+    #include <dt-bindings/gpio/gpio.h>
+    #include <dt-bindings/leds/common.h>
+
+    /* Example: Multiple power domain LEDs */
+    power-leds {
+        compatible = "gpio-leds";
+
+        led-ac-power {
+            function = LED_FUNCTION_POWER;
+            color = <LED_COLOR_ID_GREEN>;
+            led-instance = "ac";
+            gpios = <&gpio1 10 GPIO_ACTIVE_HIGH>;
+            /* Result: /sys/class/leds/green:power:ac */
+        };
+
+        led-battery-power {
+            function = LED_FUNCTION_POWER;
+            color = <LED_COLOR_ID_GREEN>;
+            led-instance = "battery";
+            gpios = <&gpio1 11 GPIO_ACTIVE_HIGH>;
+            /* Result: /sys/class/leds/green:power:battery */
+        };
+
+        led-usbc-power {
+            function = LED_FUNCTION_POWER;
+            color = <LED_COLOR_ID_GREEN>;
+            led-instance = "usbc";
+            gpios = <&gpio1 12 GPIO_ACTIVE_HIGH>;
+            /* Result: /sys/class/leds/green:power:usbc */
+        };
+    };
+
 ...
--
2.43.0