Add a Devicetree binding for a generic pin controller where pinmux and/or
pin configuration are represented as fixed-width fields packed
sequentially within shared registers.
The binding targets controllers that are typically exposed as subnodes of
a syscon node and accessed via regmap-mmio through the parent.
Signed-off-by: Billy Tsai <billy_tsai@aspeedtech.com>
---
.../bindings/pinctrl/pinctrl-packed.yaml | 166 +++++++++++++++++++++
1 file changed, 166 insertions(+)
diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-packed.yaml b/Documentation/devicetree/bindings/pinctrl/pinctrl-packed.yaml
new file mode 100644
index 000000000000..dd01ba2fed71
--- /dev/null
+++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-packed.yaml
@@ -0,0 +1,166 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/pinctrl/pinctrl-packed.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Generic Pin Controller with Packed-Field Registers
+
+maintainers:
+ - Billy Tsai <billy_tsai@aspeedtech.com>
+
+description:
+ This binding describes pin controller hardware where pinmux and/or
+ pin configuration fields are represented as fixed-width fields packed
+ sequentially within shared registers.
+
+ Such controllers are commonly embedded within a larger system control
+ unit (SCU) register block and may be exposed as subnodes of a syscon
+ device.
+
+ Conceptually, this model is related to the pinctrl-single binding,
+ but instead of describing individual register offsets via
+ <offset, value, mask> tuples, the hardware provides fixed-width,
+ per-pin fields packed linearly within shared registers.
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - pinctrl-packed
+ - pinconf-packed
+
+ reg:
+ maxItems: 1
+
+ '#pinctrl-cells':
+ description:
+ The pinctrl provider uses standard state nodes referenced by pinctrl-N
+ properties; consumers do not pass per-pin arguments via phandle.
+ const: 1
+
+ pinctrl-packed,function-mask:
+ description: Mask of the allowed register bits for a single pin.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ pinctrl-packed,gpio-range:
+ description: Optional list of pin base, nr pins & gpio function.
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ items:
+ - description: phandle of a gpio-range node
+ - description: pin base
+ - description: number of pins
+ - description: gpio function
+
+patternProperties:
+ '-pins(-[0-9]+)?$|-pin$':
+ type: object
+ additionalProperties: false
+
+ properties:
+ pinctrl-packed,pins:
+ description: Array of pin index and function selector pairs.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+
+ pinctrl-packed,bias-pullup:
+ description: Optional bias pull-up configuration.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ maxItems: 4
+ items:
+ - description: Input value.
+ - description: Enabled pull-up bits.
+ - description: Disabled pull-up bits.
+ - description: Pull-up mask.
+ additionalItems: false
+
+ pinctrl-packed,bias-pulldown:
+ description: Optional bias pull-down configuration.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ maxItems: 4
+ items:
+ - description: Input value.
+ - description: Enabled pull-down bits.
+ - description: Disabled pull-down bits.
+ - description: Pull-down mask.
+ additionalItems: false
+
+ pinctrl-packed,drive-strength:
+ description: Optional drive strength configuration.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ maxItems: 2
+ items:
+ - description: Drive strength value.
+ - description: Drive strength mask.
+ additionalItems: false
+
+ pinctrl-packed,input-schmitt:
+ description: Optional input Schmitt trigger configuration.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ maxItems: 2
+ items:
+ - description: Schmitt trigger value.
+ - description: Schmitt trigger mask.
+ additionalItems: false
+
+ pinctrl-packed,input-schmitt-enable:
+ description: Optional input Schmitt enable configuration.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ maxItems: 4
+ items:
+ - description: Input value.
+ - description: Enable bits.
+ - description: Disable bits.
+ - description: Schmitt mask.
+ additionalItems: false
+
+ pinctrl-packed,low-power-mode:
+ description: Optional low power mode configuration.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ maxItems: 2
+ items:
+ - description: Low power value.
+ - description: Low power mask.
+ additionalItems: false
+
+ pinctrl-packed,slew-rate:
+ description: Optional slew rate configuration.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ maxItems: 2
+ items:
+ - description: Slew rate value.
+ - description: Slew rate mask.
+ additionalItems: false
+
+required:
+ - compatible
+ - reg
+ - "#pinctrl-cells"
+ - pinctrl-packed,function-mask
+
+additionalProperties: false
+
+allOf:
+ - $ref: pinctrl.yaml#
+
+examples:
+ - |
+ syscon@0 {
+ compatible = "syscon", "simple-mfd";
+ reg = <0x0 0x1000>;
+ ranges;
+ #address-cells = <1>;
+ #size-cells = <1>;
+
+ pinctrl@400 {
+ compatible = "pinctrl-packed";
+ reg = <0x400 0x80>;
+ #pinctrl-cells = <1>;
+ pinctrl-packed,function-mask = <0xf>;
+
+ uart0-pins {
+ /* <pin_index function_select> pairs */
+ pinctrl-packed,pins = <0 2>, <1 2>;
+ };
+ };
+ };
--
2.34.1Hi Billy, thanks for your patch! This approach is better than trying to extend pinctrl-single in my opinion, but it has a bit of road to cover. On Fri, Feb 13, 2026 at 9:18 AM Billy Tsai <billy_tsai@aspeedtech.com> wrote: > Add a Devicetree binding for a generic pin controller where pinmux and/or > pin configuration are represented as fixed-width fields packed > sequentially within shared registers. > > The binding targets controllers that are typically exposed as subnodes of > a syscon node and accessed via regmap-mmio through the parent. > > Signed-off-by: Billy Tsai <billy_tsai@aspeedtech.com> (...) > +properties: > + compatible: > + oneOf: > + - enum: > + - pinctrl-packed > + - pinconf-packed Why do you need two? Can't you just use one, pinctrl-packed. > + pinctrl-packed,function-mask: > + description: Mask of the allowed register bits for a single pin. > + $ref: /schemas/types.yaml#/definitions/uint32 To me this could be static data in the driver but I guess the whole point is to do what pinctrl-single is doing and store all of this information in the device tree, because reasons. I guess the DT binding maintainers need to decide on this and also what to name it. > + pinctrl-packed,gpio-range: > + description: Optional list of pin base, nr pins & gpio function. > + $ref: /schemas/types.yaml#/definitions/phandle-array > + items: > + items: > + - description: phandle of a gpio-range node > + - description: pin base > + - description: number of pins > + - description: gpio function Just use the standard gpio-range. > +patternProperties: > + '-pins(-[0-9]+)?$|-pin$': > + type: object > + additionalProperties: false > + properties: > + pinctrl-packed,pins: > + description: Array of pin index and function selector pairs. > + $ref: /schemas/types.yaml#/definitions/uint32-array Just use pinmux = <...>; from pinmux-node.yaml (make sure to use the ref include.) > + pinctrl-packed,bias-pullup: > + pinctrl-packed,bias-pulldown: > + pinctrl-packed,drive-strength: > + pinctrl-packed,input-schmitt: > + pinctrl-packed,input-schmitt-enable: > + pinctrl-packed,low-power-mode: > + pinctrl-packed,slew-rate: Just use the existing configs from pincfg-node.yaml and abstain from any new inventions here. Yours, Linus Walleij
On 13/02/2026 09:17, Billy Tsai wrote:
> Add a Devicetree binding for a generic pin controller where pinmux and/or
> pin configuration are represented as fixed-width fields packed
> sequentially within shared registers.
>
> The binding targets controllers that are typically exposed as subnodes of
> a syscon node and accessed via regmap-mmio through the parent.
>
> Signed-off-by: Billy Tsai <billy_tsai@aspeedtech.com>
> ---
> .../bindings/pinctrl/pinctrl-packed.yaml | 166 +++++++++++++++++++++
> 1 file changed, 166 insertions(+)
>
> diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-packed.yaml b/Documentation/devicetree/bindings/pinctrl/pinctrl-packed.yaml
> new file mode 100644
> index 000000000000..dd01ba2fed71
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-packed.yaml
> @@ -0,0 +1,166 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/pinctrl/pinctrl-packed.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Generic Pin Controller with Packed-Field Registers
> +
> +maintainers:
> + - Billy Tsai <billy_tsai@aspeedtech.com>
> +
> +description:
> + This binding describes pin controller hardware where pinmux and/or
> + pin configuration fields are represented as fixed-width fields packed
> + sequentially within shared registers.
> +
> + Such controllers are commonly embedded within a larger system control
> + unit (SCU) register block and may be exposed as subnodes of a syscon
> + device.
> +
> + Conceptually, this model is related to the pinctrl-single binding,
> + but instead of describing individual register offsets via
> + <offset, value, mask> tuples, the hardware provides fixed-width,
> + per-pin fields packed linearly within shared registers.
Why this cannot be part of pinctrl-single then? Why all these properties
are needed? I imagine that you need them to customize the generic
binding to your device and that would be counter argument - generic
bindings are too generic so people need to grow them with hundreds
properties (see the very simple binding of simple audio card).
> +
> +properties:
> + compatible:
> + oneOf:
Drop oneOf
> + - enum:
> + - pinctrl-packed
> + - pinconf-packed
> +
> + reg:
> + maxItems: 1
> +
> + '#pinctrl-cells':
> + description:
> + The pinctrl provider uses standard state nodes referenced by pinctrl-N
> + properties; consumers do not pass per-pin arguments via phandle.
> + const: 1
> +
> + pinctrl-packed,function-mask:
> + description: Mask of the allowed register bits for a single pin.
> + $ref: /schemas/types.yaml#/definitions/uint32
> +
> + pinctrl-packed,gpio-range:
> + description: Optional list of pin base, nr pins & gpio function.
> + $ref: /schemas/types.yaml#/definitions/phandle-array
> + items:
> + items:
> + - description: phandle of a gpio-range node
> + - description: pin base
> + - description: number of pins
> + - description: gpio function
> +
> +patternProperties:
> + '-pins(-[0-9]+)?$|-pin$':
> + type: object
> + additionalProperties: false
> +
> + properties:
> + pinctrl-packed,pins:
No, use standard pinctrl properties.
> + description: Array of pin index and function selector pairs.
> + $ref: /schemas/types.yaml#/definitions/uint32-array
> +
> + pinctrl-packed,bias-pullup:
> + description: Optional bias pull-up configuration.
> + $ref: /schemas/types.yaml#/definitions/uint32-array
> + maxItems: 4
> + items:
> + - description: Input value.
> + - description: Enabled pull-up bits.
> + - description: Disabled pull-up bits.
> + - description: Pull-up mask.
> + additionalItems: false
> +
> + pinctrl-packed,bias-pulldown:
> + description: Optional bias pull-down configuration.
> + $ref: /schemas/types.yaml#/definitions/uint32-array
> + maxItems: 4
> + items:
> + - description: Input value.
> + - description: Enabled pull-down bits.
> + - description: Disabled pull-down bits.
> + - description: Pull-down mask.
> + additionalItems: false
> +
> + pinctrl-packed,drive-strength:
> + description: Optional drive strength configuration.
> + $ref: /schemas/types.yaml#/definitions/uint32-array
> + maxItems: 2
> + items:
> + - description: Drive strength value.
> + - description: Drive strength mask.
> + additionalItems: false
> +
> + pinctrl-packed,input-schmitt:
> + description: Optional input Schmitt trigger configuration.
> + $ref: /schemas/types.yaml#/definitions/uint32-array
> + maxItems: 2
> + items:
> + - description: Schmitt trigger value.
> + - description: Schmitt trigger mask.
> + additionalItems: false
> +
> + pinctrl-packed,input-schmitt-enable:
> + description: Optional input Schmitt enable configuration.
> + $ref: /schemas/types.yaml#/definitions/uint32-array
> + maxItems: 4
> + items:
> + - description: Input value.
> + - description: Enable bits.
> + - description: Disable bits.
> + - description: Schmitt mask.
> + additionalItems: false
> +
> + pinctrl-packed,low-power-mode:
> + description: Optional low power mode configuration.
> + $ref: /schemas/types.yaml#/definitions/uint32-array
> + maxItems: 2
> + items:
> + - description: Low power value.
> + - description: Low power mask.
> + additionalItems: false
> +
> + pinctrl-packed,slew-rate:
> + description: Optional slew rate configuration.
> + $ref: /schemas/types.yaml#/definitions/uint32-array
> + maxItems: 2
> + items:
> + - description: Slew rate value.
> + - description: Slew rate mask.
> + additionalItems: false
> +
> +required:
> + - compatible
> + - reg
> + - "#pinctrl-cells"
> + - pinctrl-packed,function-mask
> +
> +additionalProperties: false
> +
> +allOf:
> + - $ref: pinctrl.yaml#
> +
> +examples:
> + - |
> + syscon@0 {
> + compatible = "syscon", "simple-mfd";
This is not allowed and you will have warnings here, which means you did
not test the binding correctly (completely). Not even needed here, drop
entire node.
Best regards,
Krzysztof
© 2016 - 2026 Red Hat, Inc.