Add a binding description for the Realtek RTL8231's LED support, which
consists of up to 88 LEDs arranged in a number of scanning matrices.
Signed-off-by: Sander Vanheule <sander@svanheule.net>
---
.../bindings/leds/realtek,rtl8231-leds.yaml | 167 ++++++++++++++++++
1 file changed, 167 insertions(+)
create mode 100644 Documentation/devicetree/bindings/leds/realtek,rtl8231-leds.yaml
diff --git a/Documentation/devicetree/bindings/leds/realtek,rtl8231-leds.yaml b/Documentation/devicetree/bindings/leds/realtek,rtl8231-leds.yaml
new file mode 100644
index 000000000000..54e8593f8c06
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/realtek,rtl8231-leds.yaml
@@ -0,0 +1,167 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/realtek,rtl8231-leds.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Realtek RTL8231 LED scan matrix.
+
+maintainers:
+ - Sander Vanheule <sander@svanheule.net>
+
+description: |
+ The RTL8231 has support for driving a number of LED matrices, by scanning
+ over the LEDs pins, alternatingly lighting different columns and/or rows.
+
+ This functionality is available on an RTL8231, when it is configured for use
+ as an MDIO device, or SMI device.
+
+ In single color scan mode, 88 LEDs are supported. These are grouped into
+ three output matrices:
+ - Group A of 6×6 single color LEDs. Rows and columns are driven by GPIO
+ pins 0-11.
+ L0[n] L1[n] L2[n] L0[n+6] L1[n+6] L2[n+6]
+ | | | | | |
+ P0/P6 --<--------<--------<--------<--------<--------< (3)
+ | | | | | |
+ P1/P7 --<--------<--------<--------<--------<--------< (4)
+ | | | | | |
+ P2/P8 --<--------<--------<--------<--------<--------< (5)
+ | | | | | |
+ P3/P9 --<--------<--------<--------<--------<--------< (6)
+ | | | | | |
+ P4/P10 --<--------<--------<--------<--------<--------< (7)
+ | | | | | |
+ P5/P11 --<--------<--------<--------<--------<--------< (8)
+ (0) (1) (2) (9) (10) (11)
+ - Group B of 6×6 single color LEDs. Rows and columns are driven by GPIO
+ pins 12-23.
+ L0[n] L1[n] L2[n] L0[n+6] L1[n+6] L2[n+6]
+ | | | | | |
+ P12/P18 --<--------<--------<--------<--------<--------< (15)
+ | | | | | |
+ P13/P19 --<--------<--------<--------<--------<--------< (16)
+ | | | | | |
+ P14/P20 --<--------<--------<--------<--------<--------< (17)
+ | | | | | |
+ P15/P21 --<--------<--------<--------<--------<--------< (18)
+ | | | | | |
+ P16/P22 --<--------<--------<--------<--------<--------< (19)
+ | | | | | |
+ P17/P23 --<--------<--------<--------<--------<--------< (20)
+ (12) (13) (14) (21) (22) (23)
+ - Group C of 8 pairs of anti-parallel (or bi-color) LEDs. LED selection is
+ provided by GPIO pins 24-27 and 29-32, polarity selection by GPIO 28.
+ P24 P25 ... P30 P31
+ | | | |
+ LED POL --X-------X---/\/---X-------X (28)
+ (24) (25) ... (31) (32)
+
+ In bi-color scan mode, 72 LEDs are supported. These are grouped into four
+ output matrices:
+ - Group A of 12 pairs of anti-parallel LEDs. LED selection is provided
+ by GPIO pins 0-11, polarity selection by GPIO 12.
+ - Group B of 6 pairs of anti-parallel LEDs. LED selection is provided
+ by GPIO pins 23-28, polarity selection by GPIO 21.
+ - Group C of 6 pairs of anti-parallel LEDs. LED selection is provided
+ by GPIO pins 29-34, polarity selection by GPIO 22.
+ - Group of 4×6 single color LEDs. Rows are driven by GPIO pins 15-20,
+ columns by GPIO pins 13-14 and 21-22 (shared with groups B and C).
+ L2[n] L2[n+6] L2[n+12] L2[n+18]
+ | | | |
+ +0 --<--------<---------<---------< (15)
+ | | | |
+ +1 --<--------<---------<---------< (16)
+ | | | |
+ +2 --<--------<---------<---------< (17)
+ | | | |
+ +3 --<--------<---------<---------< (18)
+ | | | |
+ +4 --<--------<---------<---------< (19)
+ | | | |
+ +6 --<--------<---------<---------< (20)
+ (13) (14) (21) (22)
+
+ This node must always be a child of a 'realtek,rtl8231' node.
+
+properties:
+ $nodename:
+ const: led-controller
+
+ compatible:
+ const: realtek,rtl8231-leds
+
+ "#address-cells":
+ const: 2
+
+ "#size-cells":
+ const: 0
+
+ realtek,led-scan-mode:
+ $ref: /schemas/types.yaml#/definitions/string
+ description: |
+ Specify the scanning mode the chip should run in. See general description
+ for how the scanning matrices are wired up.
+ enum: [single-color, bi-color]
+
+patternProperties:
+ "^led@":
+ description: |
+ LEDs are addressed by their port index and led index. Ports 0-23 always
+ support three LEDs. Additionally, but only when used in single color scan
+ mode, ports 24-31 support two LEDs.
+ type: object
+
+ properties:
+ reg:
+ items:
+ - items:
+ - description: port index
+ maximum: 31
+ - description: led index
+ maximum: 2
+
+ allOf:
+ - $ref: ../leds/common.yaml#
+
+ required:
+ - reg
+
+required:
+ - compatible
+ - "#address-cells"
+ - "#size-cells"
+ - realtek,led-scan-mode
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/leds/common.h>
+ led-controller {
+ compatible = "realtek,rtl8231-leds";
+ #address-cells = <2>;
+ #size-cells = <0>;
+
+ realtek,led-scan-mode = "single-color";
+
+ led@0,0 {
+ reg = <0 0>;
+ color = <LED_COLOR_ID_GREEN>;
+ function = LED_FUNCTION_LAN;
+ function-enumerator = <0>;
+ };
+
+ led@0,1 {
+ reg = <0 1>;
+ color = <LED_COLOR_ID_AMBER>;
+ function = LED_FUNCTION_LAN;
+ function-enumerator = <0>;
+ };
+
+ led@0,2 {
+ reg = <0 2>;
+ color = <LED_COLOR_ID_GREEN>;
+ function = LED_FUNCTION_STATUS;
+ };
+ };
--
2.51.0
On Tue, Oct 21, 2025 at 04:23:58PM +0200, Sander Vanheule wrote: > Add a binding description for the Realtek RTL8231's LED support, which > consists of up to 88 LEDs arranged in a number of scanning matrices. > > Signed-off-by: Sander Vanheule <sander@svanheule.net> > --- > .../bindings/leds/realtek,rtl8231-leds.yaml | 167 ++++++++++++++++++ > 1 file changed, 167 insertions(+) > create mode 100644 Documentation/devicetree/bindings/leds/realtek,rtl8231-leds.yaml > > diff --git a/Documentation/devicetree/bindings/leds/realtek,rtl8231-leds.yaml b/Documentation/devicetree/bindings/leds/realtek,rtl8231-leds.yaml > new file mode 100644 > index 000000000000..54e8593f8c06 > --- /dev/null > +++ b/Documentation/devicetree/bindings/leds/realtek,rtl8231-leds.yaml > @@ -0,0 +1,167 @@ > +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause > +%YAML 1.2 > +--- > +$id: http://devicetree.org/schemas/leds/realtek,rtl8231-leds.yaml# > +$schema: http://devicetree.org/meta-schemas/core.yaml# > + > +title: Realtek RTL8231 LED scan matrix. > + > +maintainers: > + - Sander Vanheule <sander@svanheule.net> > + > +description: | > + The RTL8231 has support for driving a number of LED matrices, by scanning > + over the LEDs pins, alternatingly lighting different columns and/or rows. > + > + This functionality is available on an RTL8231, when it is configured for use > + as an MDIO device, or SMI device. > + > + In single color scan mode, 88 LEDs are supported. These are grouped into > + three output matrices: > + - Group A of 6×6 single color LEDs. Rows and columns are driven by GPIO > + pins 0-11. > + L0[n] L1[n] L2[n] L0[n+6] L1[n+6] L2[n+6] > + | | | | | | > + P0/P6 --<--------<--------<--------<--------<--------< (3) > + | | | | | | > + P1/P7 --<--------<--------<--------<--------<--------< (4) > + | | | | | | > + P2/P8 --<--------<--------<--------<--------<--------< (5) > + | | | | | | > + P3/P9 --<--------<--------<--------<--------<--------< (6) > + | | | | | | > + P4/P10 --<--------<--------<--------<--------<--------< (7) > + | | | | | | > + P5/P11 --<--------<--------<--------<--------<--------< (8) > + (0) (1) (2) (9) (10) (11) > + - Group B of 6×6 single color LEDs. Rows and columns are driven by GPIO > + pins 12-23. > + L0[n] L1[n] L2[n] L0[n+6] L1[n+6] L2[n+6] > + | | | | | | > + P12/P18 --<--------<--------<--------<--------<--------< (15) > + | | | | | | > + P13/P19 --<--------<--------<--------<--------<--------< (16) > + | | | | | | > + P14/P20 --<--------<--------<--------<--------<--------< (17) > + | | | | | | > + P15/P21 --<--------<--------<--------<--------<--------< (18) > + | | | | | | > + P16/P22 --<--------<--------<--------<--------<--------< (19) > + | | | | | | > + P17/P23 --<--------<--------<--------<--------<--------< (20) > + (12) (13) (14) (21) (22) (23) > + - Group C of 8 pairs of anti-parallel (or bi-color) LEDs. LED selection is > + provided by GPIO pins 24-27 and 29-32, polarity selection by GPIO 28. > + P24 P25 ... P30 P31 > + | | | | > + LED POL --X-------X---/\/---X-------X (28) > + (24) (25) ... (31) (32) > + > + In bi-color scan mode, 72 LEDs are supported. These are grouped into four > + output matrices: > + - Group A of 12 pairs of anti-parallel LEDs. LED selection is provided > + by GPIO pins 0-11, polarity selection by GPIO 12. > + - Group B of 6 pairs of anti-parallel LEDs. LED selection is provided > + by GPIO pins 23-28, polarity selection by GPIO 21. > + - Group C of 6 pairs of anti-parallel LEDs. LED selection is provided > + by GPIO pins 29-34, polarity selection by GPIO 22. > + - Group of 4×6 single color LEDs. Rows are driven by GPIO pins 15-20, > + columns by GPIO pins 13-14 and 21-22 (shared with groups B and C). > + L2[n] L2[n+6] L2[n+12] L2[n+18] > + | | | | > + +0 --<--------<---------<---------< (15) > + | | | | > + +1 --<--------<---------<---------< (16) > + | | | | > + +2 --<--------<---------<---------< (17) > + | | | | > + +3 --<--------<---------<---------< (18) > + | | | | > + +4 --<--------<---------<---------< (19) > + | | | | > + +6 --<--------<---------<---------< (20) > + (13) (14) (21) (22) > + > + This node must always be a child of a 'realtek,rtl8231' node. > + > +properties: > + $nodename: > + const: led-controller > + > + compatible: > + const: realtek,rtl8231-leds > + > + "#address-cells": > + const: 2 > + > + "#size-cells": > + const: 0 > + > + realtek,led-scan-mode: > + $ref: /schemas/types.yaml#/definitions/string > + description: | You don't need '|' if there is no formatting to preserve. > + Specify the scanning mode the chip should run in. See general description > + for how the scanning matrices are wired up. > + enum: [single-color, bi-color] Wouldn't 'single' and 'bi' be sufficient? > + > +patternProperties: > + "^led@": You need to define the unit-address format: "^led@([1-2]?[0-9]|3[0-1]),[0-2]$" > + description: | > + LEDs are addressed by their port index and led index. Ports 0-23 always > + support three LEDs. Additionally, but only when used in single color scan > + mode, ports 24-31 support two LEDs. > + type: object
Hi Rob, On Sun, 2025-10-26 at 16:59 -0500, Rob Herring wrote: > On Tue, Oct 21, 2025 at 04:23:58PM +0200, Sander Vanheule wrote: > > + realtek,led-scan-mode: > > + $ref: /schemas/types.yaml#/definitions/string > > + description: | > > You don't need '|' if there is no formatting to preserve. Will drop it. > > + Specify the scanning mode the chip should run in. See general > > description > > + for how the scanning matrices are wired up. > > + enum: [single-color, bi-color] > > Wouldn't 'single' and 'bi' be sufficient? I used these values to align with the datasheet: En_bicolor 1'b0: Uses single-color LED when in Scan LED mode 1'b1: Uses bi-color LED when in Scan LED mode If you would like a single word, I would prefer [single, dual] and mention the single-color/bi-color mapping in the description. > > > + > > +patternProperties: > > + "^led@": > > You need to define the unit-address format: > > "^led@([1-2]?[0-9]|3[0-1]),[0-2]$" Hadn't considered that yet. I'll update this too. Best, Sander
© 2016 - 2026 Red Hat, Inc.