I'm not sure if the "pins1" and "pins2" subgroups can be extracted properly with current DT tooling, @mbolivar-nordic ?

Based on the example you gave, it looks doable to me. No compatible is shown, so I'm guessing you would want to use a child binding of the pinctrl node. Something like

	pinctrl: ... {
		compatible = "st,socmodel-pinctrl";

		pins1 {
			pinmux = <USART2_TX_PD5>, <USART2_RTS_PD4>;
			bias-disable;
			drive-push-pull;
			slew-rate = <3>;
		};
		pins2 {
			pinmux = <USART2_RX_PD6>, <USART2_CTS_NSS_PD3>;
			bias-disable;
		};
	}

then the binding would be something like

compatible: st,socmodel-pinctrl
include: pincfg-node.yaml
child-binding:
    properties:
        pinmux:
            type: array

@mbolivar-nordic there's actually one more level:

	pinctrl: ... {
		compatible = "st,socmodel-pinctrl";
                usart2_pins_c: ... {
                    pins1 {
	                    pinmux = <USART2_TX_PD5>, <USART2_RTS_PD4>;
	                    bias-disable;
	                    drive-push-pull;
	                    slew-rate = <3>;
                    };
                    pins2 {
	                    pinmux = <USART2_RX_PD6>, <USART2_CTS_NSS_PD3>;
	                    bias-disable;
                    };
              };
	};

so it's like the child binding has groups inside.

You could do this with the above binding if you give the usart2_pins_c node a binding with the above content. We might need some edtlib changes if you want to do it from the st,socmodel-pinctrl binding.

The Linux approach can be simplified by autogenerating the possible combinations

Sure, auto-generation is required, but this doesn't answer any of these points (bloated + hard to find correct config)

I imagine Linux has taken this path since they end up running on a large number of boards where "common configs" don't always apply.

In the contrary, as I know from ST part at least, they chose this path because they only have to consider a quite limited number of boards, which makes it easier to define groups (and they only provide a limited subset of combinations).

The Linux approach can be simplified by autogenerating the possible combinations

Sure, auto-generation is required, but this doesn't answer any of these points (bloated + hard to find correct config)

Current auto-generated DTS contains common but not necessarily correct configuration when it comes to pin properties. The correct configuration depends, in many cases, on the board design or operating conditions (e.g. bus speed).

I imagine Linux has taken this path since they end up running on a large number of boards where "common configs" don't always apply.

In the contrary, as I know from ST part at least, they chose this path because they only have to consider a quite limited number of boards, which makes it easier to define groups (and they only provide a limited subset of combinations).

The number of in-tree boards in Linux is low, that's true. I assume they just provide the few combinations that apply to common dev kits. Custom boards needs to create their own board-pinctrl.dtsi files.

Examples for multiple of the approaches listed in this thread for Nordic:

• Option 1: https://gist.github.com/gmarull/e2afed5c97a188f3830ff0bd59d3d3ae
• Option 2: https://gist.github.com/gmarull/214b49e6780af75aa9eec08abb45be84
• Option 3 (slight variation): https://gist.github.com/gmarull/6993e3eacad1b0d7c00c1ea2f16c3a12
• Option 4: https://gist.github.com/gmarull/a683cffc2a8afd4ca2b0ff8829f55425
• Option 5: https://gist.github.com/gmarull/02f76fba628fa556853c2acf01a65efb
• Option 6: https://gist.github.com/gmarull/ecb2c0066ac4b7ac5420f326ab94f683

Initial thoughts:

• When crafting -pinctrl.dtsi files manually, Option 1 seems to be the one generating less verbose files
• If the provided common defaults option is acceptable, Option 2 is the one that requires less user effort.

@mbolivar-nordic asked me to weigh in on the proposals from an editor support point of view. All of these proposals are snippet-able, but there's definitely a difference in usability, IMO.

Generally, the less macro magic there is going on, the easier it is to provide editor support for these definitions. For instance, the VS Code DT extension already supports autocompleting full nodes by spawning all properties as a snippet. If you for example type bma280 in an i2c bus node and press tab, it'll expand to

bma280 {
    compatible = "bosch,bma280";
    reg = <addr size>;
    label = "BMA280";
};

and mark addr and size as snippet fields to be filled. This uses the required properties from the bindings file to populate the properties, and this would work right out of the box for me in option 5. Option 6 would also be a good fit for this type of snippet expansion, but the engine would need to support child nodes in the snippets too.

For the macro based ones, there's no way to provide completion options for the parameters without adding custom logic for each macro, not to mention things like guiconfig for DT. Unless some sort of schema for these macros are maintained in the main repo, they're a major pain to support in editor extensions, and I'd be very hesitant to add them in any out-of-tree support module. Additionally, they're completely unreadable in the compiled output, and cannot really be replaced by manual text. The only feasible way to let users know that they need to write certain properties as a macro is through examples and tribal knowledge, which increases the cost of entry for what should be one of the most basic things you'd want to do in your overlay file. It's a minor problem in things like -gpios definitions (e.g. GPIO_PULL_UP), but interacting with files like https://github.com/zephyrproject-rtos/zephyr/blob/main/dts/arm/atmel/same70-pinctrl.dtsi and https://github.com/zephyrproject-rtos/hal_stm32/blob/f8ff8d25aa0a9e65948040c7b47ec67f3fa300df/dts/st/f0/stm32f031k(4-6)ux-pinctrl.dtsi is tough, and there's virtually nothing an editor extension can do to improve it. Most of these things are read-only for end-user now, as they'll just reference them, but if they start leaking into overlay files, they will degrade the usability, IMO.

I'm not super familiar with pinctrl or its history in the Linux Kernel, but from a usability point of view, the closer we are to WYSIWYG, the better.

FWIW, I think options 5 and 6 are the most sensible, with option 2 as a runner-up. I am a bit surprised that none of the options use the -gpios syntax, but I know this has been rejected in the past. I'm pretty sure I'm missing something, but the phandle syntax is by far the most readable and sensible pin configuration scheme we use in Zephyr, IMO. For instance, I find this to be a lot more readable (and writable!) than the suggestions with macros or splitting pins and configurations into multiple properties:

&pinctrl {
    uart0_sleep {
        compatible = "nordic,nrf-uarte-pinctrl";
        tx-gpio = <&gpio0 6 GPIO_ACTIVE_HIGH>;
        rx-gpio = <&gpio0 8 GPIO_PULL_DOWN>;
        rts-gpio = <&gpio0 5 0>;
        cts-gpio = <&gpio0 7 GPIO_PULL_DOWN>;
    };
};

I think proposal 6 by @mbolivar-nordic makes the most sense, as it doesn't mix config and pin properties in the same node scope. Option 5 kind of mixes domains by splitting pins into multiple properties without grouping them by pins in any way. Having tx-pin, rx-pin and tx-cfg all at the same place in the hierarchy when there are several ways to make a hierarchy in DTS, seems a bit odd.

if properties are stored on a pin basis, the final value could be a combination of group, pin_creation macros and individuals.

at (4)

Cons:
Does not re-use pincfg-node.yaml properties (e.g. bias-..., slew-rate...)
In this case, there are no "common" defaults, users needs to explicitly set all pin configurations. Could be mitigated with more PINCTRL_NRF_XXX like macros, specific to e.g. UART.

It is possible to use a variable length list at pin creation at any proposal. I mean, a pin can be defined and all properties can follow pincfg-node.yaml. This is already available and below can be an option too. It is possible allow pincfg-node.yaml on the group too.

&pinctrl {
	/* UART0 */
	uart0_default: uart0_default {
		pincfg = <PINCTRL_NRF(0, 6, OUT, IDISC, PN, UART_TX)
                         /* Set individual property */
			  PINCTRL_NRF(0, 8, INP, ICONN, PU, UART_RX [, bias-pull-up, ..] )
			  PINCTRL_NRF(0, 5, OUT, IDISC, PN, UART_RTS)
			  PINCTRL_NRF(0, 7, INP, ICONN, PU, UART_CTS [, bias-pull-up, ..] )>;

This would re-use names in the macro, but they'd not be DT properties as defined in pincfg-node. Not sure how non-boolean properties would work in that case.

  /* Add a common property for all 4 pins */
  slew-rate = <3>;

If not common to all 4 pins then the "subgroups" need to be introduced somehow to group pins with common properties, which takes us to case 1 representation.

};
};

User still have the possibility to do below changes because properties are stored by pin individually.

&i2c1_scl_pb8 {
/delete-property/ bias-pull-up;
bias-pull-down;
};

Not sure if this kind of flexibility should be available.

This is how it's done today for the STM32 case, the flexibility is given by Devicetree itself.