Add a binding description for the Realtek RTL8231, a GPIO and LED
expander chip commonly used in ethernet switches based on a Realtek
switch SoC. These chips can be addressed via an MDIO or SMI bus, or used
as a plain 36-bit shift register.
This binding only describes the feature set provided by the MDIO/SMI
configuration, and covers the GPIO, PWM, and pin control properties. The
LED properties are defined in a separate binding.
Signed-off-by: Sander Vanheule <sander@svanheule.net>
---
Changes since v6:
- Relax description formatting
- Use absolute paths for schema references
- Add pinctrl properties to led-controller node in example
---
.../bindings/mfd/realtek,rtl8231.yaml | 193 ++++++++++++++++++
1 file changed, 193 insertions(+)
create mode 100644 Documentation/devicetree/bindings/mfd/realtek,rtl8231.yaml
diff --git a/Documentation/devicetree/bindings/mfd/realtek,rtl8231.yaml b/Documentation/devicetree/bindings/mfd/realtek,rtl8231.yaml
new file mode 100644
index 000000000000..5669dd58654e
--- /dev/null
+++ b/Documentation/devicetree/bindings/mfd/realtek,rtl8231.yaml
@@ -0,0 +1,193 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mfd/realtek,rtl8231.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Realtek RTL8231 GPIO and LED expander.
+
+maintainers:
+ - Sander Vanheule <sander@svanheule.net>
+
+description: |
+ The RTL8231 is a GPIO and LED expander chip, providing up to 37 GPIOs, up to
+ 88 LEDs, and up to one PWM output. This device is frequently used alongside
+ Realtek switch SoCs, to provide additional I/O capabilities.
+
+ To manage the RTL8231's features, its strapping pins can be used to configure
+ it in one of three modes: shift register, MDIO device, or SMI device. The
+ shift register mode does not need special support. In MDIO or SMI mode, most
+ pins can be configured as a GPIO output or LED matrix scan line/column. One
+ pin can be used as PWM output.
+
+ The GPIO, PWM, and pin control are part of the main node. LED support is
+ configured as a sub-node.
+
+properties:
+ compatible:
+ const: realtek,rtl8231
+
+ reg:
+ description: MDIO or SMI device address.
+ maxItems: 1
+
+ # GPIO support
+ gpio-controller: true
+
+ "#gpio-cells":
+ const: 2
+ description:
+ The first cell is the pin number and the second cell is used to specify
+ the GPIO active state.
+
+ gpio-ranges:
+ description:
+ Must reference itself, and provide a zero-based mapping for 37 pins.
+ maxItems: 1
+
+ # Pin muxing and configuration
+ drive-strength:
+ description:
+ Common drive strength used for all GPIO output pins, must be 4mA or 8mA.
+ On reset, this value will default to 8mA.
+ enum: [4, 8]
+
+ # LED scanning matrix
+ led-controller:
+ $ref: /schemas/leds/realtek,rtl8231-leds.yaml#
+
+ # PWM output
+ "#pwm-cells":
+ description:
+ Twos cells with PWM index (must be 0) and PWM frequency in Hz. To use
+ the PWM output, gpio35 must be muxed to its "pwm" function. Valid
+ frequency values for consumers are 1200, 1600, 2000, 2400, 2800, 3200,
+ 4000, and 4800.
+ const: 2
+
+patternProperties:
+ "-pins$":
+ type: object
+ $ref: /schemas/pinctrl/pinmux-node.yaml#
+
+ properties:
+ pins:
+ items:
+ enum: [gpio0, gpio1, gpio2, gpio3, gpio4, gpio5, gpio6, gpio7,
+ gpio8, gpio9, gpio10, gpio11, gpio12, gpio13, gpio14, gpio15,
+ gpio16, gpio17, gpio18, gpio19, gpio20, gpio21, gpio22, gpio23,
+ gpio24, gpio25, gpio26, gpio27, gpio28, gpio29, gpio30, gpio31,
+ gpio32, gpio33, gpio34, gpio35, gpio36]
+ minItems: 1
+ maxItems: 37
+
+ function:
+ description:
+ Select which function to use. "gpio" is supported for all pins, "led" is supported
+ for pins 0-34, "pwm" is supported for pin 35.
+ enum: [gpio, led, pwm]
+
+ required:
+ - pins
+ - function
+
+required:
+ - compatible
+ - reg
+ - gpio-controller
+ - "#gpio-cells"
+ - gpio-ranges
+
+additionalProperties: false
+
+examples:
+ - |
+ // Minimal example
+ mdio {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ expander0: expander@0 {
+ compatible = "realtek,rtl8231";
+ reg = <0>;
+
+ gpio-controller;
+ #gpio-cells = <2>;
+ gpio-ranges = <&expander0 0 0 37>;
+ };
+ };
+ - |
+ // All bells and whistles included
+ #include <dt-bindings/leds/common.h>
+ mdio {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ expander1: expander@1 {
+ compatible = "realtek,rtl8231";
+ reg = <1>;
+
+ gpio-controller;
+ #gpio-cells = <2>;
+ gpio-ranges = <&expander1 0 0 37>;
+
+ #pwm-cells = <2>;
+
+ drive-strength = <4>;
+
+ button-pins {
+ pins = "gpio36";
+ function = "gpio";
+ input-debounce = <100000>;
+ };
+
+ pwm-pins {
+ pins = "gpio35";
+ function = "pwm";
+ };
+
+ led_matrix: led-pins {
+ pins = "gpio0", "gpio1", "gpio3", "gpio4";
+ function = "led";
+ };
+
+ led-controller {
+ compatible = "realtek,rtl8231-leds";
+ #address-cells = <2>;
+ #size-cells = <0>;
+
+ pinctrl-names = "default";
+ pinctrl-0 = <&led_matrix>;
+
+ 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@1,0 {
+ reg = <1 0>;
+ color = <LED_COLOR_ID_GREEN>;
+ function = LED_FUNCTION_LAN;
+ function-enumerator = <1>;
+ };
+
+ led@1,1 {
+ reg = <1 1>;
+ color = <LED_COLOR_ID_AMBER>;
+ function = LED_FUNCTION_LAN;
+ function-enumerator = <1>;
+ };
+ };
+ };
+ };
--
2.51.1On Mon, Nov 17, 2025 at 3:52 PM Sander Vanheule <sander@svanheule.net> wrote:
>
> Add a binding description for the Realtek RTL8231, a GPIO and LED
> expander chip commonly used in ethernet switches based on a Realtek
> switch SoC. These chips can be addressed via an MDIO or SMI bus, or used
> as a plain 36-bit shift register.
>
> This binding only describes the feature set provided by the MDIO/SMI
> configuration, and covers the GPIO, PWM, and pin control properties. The
> LED properties are defined in a separate binding.
>
> Signed-off-by: Sander Vanheule <sander@svanheule.net>
> ---
> Changes since v6:
> - Relax description formatting
> - Use absolute paths for schema references
> - Add pinctrl properties to led-controller node in example
> ---
> .../bindings/mfd/realtek,rtl8231.yaml | 193 ++++++++++++++++++
> 1 file changed, 193 insertions(+)
> create mode 100644 Documentation/devicetree/bindings/mfd/realtek,rtl8231.yaml
>
> diff --git a/Documentation/devicetree/bindings/mfd/realtek,rtl8231.yaml b/Documentation/devicetree/bindings/mfd/realtek,rtl8231.yaml
> new file mode 100644
> index 000000000000..5669dd58654e
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/mfd/realtek,rtl8231.yaml
> @@ -0,0 +1,193 @@
> +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/mfd/realtek,rtl8231.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Realtek RTL8231 GPIO and LED expander.
> +
> +maintainers:
> + - Sander Vanheule <sander@svanheule.net>
> +
> +description: |
> + The RTL8231 is a GPIO and LED expander chip, providing up to 37 GPIOs, up to
> + 88 LEDs, and up to one PWM output. This device is frequently used alongside
> + Realtek switch SoCs, to provide additional I/O capabilities.
> +
> + To manage the RTL8231's features, its strapping pins can be used to configure
> + it in one of three modes: shift register, MDIO device, or SMI device. The
> + shift register mode does not need special support. In MDIO or SMI mode, most
> + pins can be configured as a GPIO output or LED matrix scan line/column. One
> + pin can be used as PWM output.
> +
> + The GPIO, PWM, and pin control are part of the main node. LED support is
> + configured as a sub-node.
> +
> +properties:
> + compatible:
> + const: realtek,rtl8231
> +
> + reg:
> + description: MDIO or SMI device address.
> + maxItems: 1
> +
> + # GPIO support
> + gpio-controller: true
> +
> + "#gpio-cells":
> + const: 2
> + description:
> + The first cell is the pin number and the second cell is used to specify
> + the GPIO active state.
> +
> + gpio-ranges:
> + description:
> + Must reference itself, and provide a zero-based mapping for 37 pins.
> + maxItems: 1
> +
> + # Pin muxing and configuration
> + drive-strength:
> + description:
> + Common drive strength used for all GPIO output pins, must be 4mA or 8mA.
> + On reset, this value will default to 8mA.
> + enum: [4, 8]
> +
> + # LED scanning matrix
> + led-controller:
> + $ref: /schemas/leds/realtek,rtl8231-leds.yaml#
> +
> + # PWM output
> + "#pwm-cells":
> + description:
> + Twos cells with PWM index (must be 0) and PWM frequency in Hz. To use
> + the PWM output, gpio35 must be muxed to its "pwm" function. Valid
> + frequency values for consumers are 1200, 1600, 2000, 2400, 2800, 3200,
> + 4000, and 4800.
> + const: 2
> +
> +patternProperties:
> + "-pins$":
> + type: object
> + $ref: /schemas/pinctrl/pinmux-node.yaml#
additionalProperties: false
> +
> + properties:
> + pins:
> + items:
> + enum: [gpio0, gpio1, gpio2, gpio3, gpio4, gpio5, gpio6, gpio7,
> + gpio8, gpio9, gpio10, gpio11, gpio12, gpio13, gpio14, gpio15,
> + gpio16, gpio17, gpio18, gpio19, gpio20, gpio21, gpio22, gpio23,
> + gpio24, gpio25, gpio26, gpio27, gpio28, gpio29, gpio30, gpio31,
> + gpio32, gpio33, gpio34, gpio35, gpio36]
> + minItems: 1
> + maxItems: 37
> +
> + function:
> + description:
> + Select which function to use. "gpio" is supported for all pins, "led" is supported
> + for pins 0-34, "pwm" is supported for pin 35.
> + enum: [gpio, led, pwm]
> +
> + required:
> + - pins
> + - function
> +
> +required:
> + - compatible
> + - reg
> + - gpio-controller
> + - "#gpio-cells"
> + - gpio-ranges
> +
> +additionalProperties: false
> +
> +examples:
> + - |
> + // Minimal example
> + mdio {
> + #address-cells = <1>;
> + #size-cells = <0>;
> +
> + expander0: expander@0 {
> + compatible = "realtek,rtl8231";
> + reg = <0>;
> +
> + gpio-controller;
> + #gpio-cells = <2>;
> + gpio-ranges = <&expander0 0 0 37>;
> + };
> + };
> + - |
> + // All bells and whistles included
> + #include <dt-bindings/leds/common.h>
> + mdio {
> + #address-cells = <1>;
> + #size-cells = <0>;
> +
> + expander1: expander@1 {
> + compatible = "realtek,rtl8231";
> + reg = <1>;
> +
> + gpio-controller;
> + #gpio-cells = <2>;
> + gpio-ranges = <&expander1 0 0 37>;
> +
> + #pwm-cells = <2>;
> +
> + drive-strength = <4>;
> +
> + button-pins {
> + pins = "gpio36";
> + function = "gpio";
> + input-debounce = <100000>;
> + };
> +
> + pwm-pins {
> + pins = "gpio35";
> + function = "pwm";
> + };
> +
> + led_matrix: led-pins {
> + pins = "gpio0", "gpio1", "gpio3", "gpio4";
> + function = "led";
> + };
> +
> + led-controller {
> + compatible = "realtek,rtl8231-leds";
> + #address-cells = <2>;
> + #size-cells = <0>;
> +
> + pinctrl-names = "default";
> + pinctrl-0 = <&led_matrix>;
> +
> + 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@1,0 {
> + reg = <1 0>;
> + color = <LED_COLOR_ID_GREEN>;
> + function = LED_FUNCTION_LAN;
> + function-enumerator = <1>;
> + };
> +
> + led@1,1 {
> + reg = <1 1>;
> + color = <LED_COLOR_ID_AMBER>;
> + function = LED_FUNCTION_LAN;
> + function-enumerator = <1>;
> + };
> + };
> + };
> + };
> --
> 2.51.1
>
>
Hi Rob, On Tue, 2025-11-18 at 15:28 -0600, Rob Herring wrote: > On Mon, Nov 17, 2025 at 3:52 PM Sander Vanheule <sander@svanheule.net> wrote: > > +patternProperties: > > + "-pins$": > > + type: object > > + $ref: /schemas/pinctrl/pinmux-node.yaml# > > additionalProperties: false In this case dt_binding_check doesn't recognize input-debounce. The following seems to work for the provided example: - $ref: /schemas/pinctrl/pinmux-node.yaml# + allOf: + - $ref: /schemas/pinctrl/pincfg-node.yaml# + - $ref: /schemas/pinctrl/pinmux-node.yaml# + + additionalProperties: false with this included in the led node properties: + input-debounce: true If I understand correctly, "unevaluatedProperties: false" (like for the leds binding) would allow everything from the referenced pincfg-node and pinmux-node schemas, which is more than is actually supported by this device. > Best, Sander
On Tue, Nov 18, 2025 at 3:57 PM Sander Vanheule <sander@svanheule.net> wrote: > > Hi Rob, > > On Tue, 2025-11-18 at 15:28 -0600, Rob Herring wrote: > > On Mon, Nov 17, 2025 at 3:52 PM Sander Vanheule <sander@svanheule.net> wrote: > > > +patternProperties: > > > + "-pins$": > > > + type: object > > > + $ref: /schemas/pinctrl/pinmux-node.yaml# > > > > additionalProperties: false > > In this case dt_binding_check doesn't recognize input-debounce. The following seems to > work for the provided example: > > - $ref: /schemas/pinctrl/pinmux-node.yaml# > + allOf: > + - $ref: /schemas/pinctrl/pincfg-node.yaml# > + - $ref: /schemas/pinctrl/pinmux-node.yaml# > + > + additionalProperties: false > > > with this included in the led node properties: > + input-debounce: true > > If I understand correctly, "unevaluatedProperties: false" (like for the leds binding) > would allow everything from the referenced pincfg-node and pinmux-node schemas, which is > more than is actually supported by this device. Yes, that works too. The first way lets you be explicit about which referenced properties are used, but either way is fine. If it is only 1 property, then I'd probably go with the first way. Rob
On Mon, 17 Nov 2025 22:51:32 +0100, Sander Vanheule wrote: > Add a binding description for the Realtek RTL8231, a GPIO and LED > expander chip commonly used in ethernet switches based on a Realtek > switch SoC. These chips can be addressed via an MDIO or SMI bus, or used > as a plain 36-bit shift register. > > This binding only describes the feature set provided by the MDIO/SMI > configuration, and covers the GPIO, PWM, and pin control properties. The > LED properties are defined in a separate binding. > > Signed-off-by: Sander Vanheule <sander@svanheule.net> > --- > Changes since v6: > - Relax description formatting > - Use absolute paths for schema references > - Add pinctrl properties to led-controller node in example > --- > .../bindings/mfd/realtek,rtl8231.yaml | 193 ++++++++++++++++++ > 1 file changed, 193 insertions(+) > create mode 100644 Documentation/devicetree/bindings/mfd/realtek,rtl8231.yaml > Reviewed-by: Rob Herring (Arm) <robh@kernel.org>
© 2016 - 2025 Red Hat, Inc.