add support to store devicetree phandle+specifier as "foo_dt_spec" structures

[pabigot]

#23245 improves the devicetree access solution significantly, but currently lacks a replacement for phandle-array values which are a series of phandle + specifier. Example is a GPIO device reference plus a pin and initial flags; or an ADC device and and an input channel. In the existing access solution a C initializer list is generated that captures the combined values, e.g. { "GPIO_0", 1, 0" }.

This gap complicates conversions of drivers that use the initializer list, e.g. the following:

-       .bus_name = DT_INST_0_MAXIM_DS3231_BUS_NAME,
+       .bus_name = DT_INST_BUS_LABEL(0),
        /* Driver does not currently use 32k GPIO. */
-#ifdef DT_INST_0_MAXIM_DS3231_ISW_GPIOS_CONTROLLER
-       .isw_gpios = DT_INST_0_MAXIM_DS3231_ISW_GPIOS,
+#if DT_INST_NODE_HAS_PROP(0, isw_gpios)
+       .isw_gpios = DT_INST_GPIO(0, isw_gpios),
 #endif
-       .addr = DT_INST_0_MAXIM_DS3231_BASE_ADDRESS,
+       .addr = DT_INST_REG_ADDR(0),

requires local addition of the following macro:

#define DT_INST_GPIO(inst, gpio_pha) {		\
	DT_INST_GPIO_LABEL(inst, gpio_pha),	\
	DT_INST_GPIO_PIN(inst, gpio_pha),	\
	DT_INST_GPIO_FLAGS(inst, gpio_pha),	\
}

to initialize the local definition:

struct gpios {
        const char *ctrl;
        gpio_pin_t pin;
        gpio_dt_flags_t flags;
};

Such a definition has not been standardized because technically different GPIO controllers could use different cells in their specifiers.

Where we have consistent cells for all drivers it would good to have a standard structure that can be used to store a phandle+specifier, and a way to initialize such a structure.

See discussion at/around: #23245 (comment)

[pabigot]

@mbolivar @galak let's discuss here rather than clutter up #23245

[mbolivar-nordic]

@pabigot collecting a list of where we want interim "LPF" style macros as discussed in #23245:

• GPIOs
• ADC

Interrupts also? Anything else?

[pabigot]

git grep -e -cells dts/bindings/ | sed -r -e 's@^[^:]*:\s*@@' | sort | uniq probably shows the candidates. At minimum clock dma gpio interrupt io-channel (ADC) pinmux pwm may be candidates. An issue is that the number of cells and their names/roles is binding-specific.

[mbolivar-nordic]

I've renamed the issue now that we are using 'foo_dt_spec' (e.g. gpio_dt_spec, i2c_dt_spec, spi_dt_spec) for this type of thing.

[mbolivar-nordic]

A status update as we head into v3.1: we have foo_dt_spec structures for the following cases, which overlaps somewhat with the above list.

• gpio: added in gpio: add struct gpio_dt_spec #32805
• adc: added in dts: Add child bindings to ADC controller for channel configurations #43030 (not exactly io-channels, but more generally related to configuring ADC channels in DT)
• pwm: added in [RFC] drivers: pwm: API naming changes and pwm_dt_spec #44523
• spi: added in spi: introduce struct spi_dt_spec #36489
• i2c: added in i2c: introduce struct i2c_dt_spec #37359
• reset: added in Reset Controller Driver #43073
• pinmux: won't do, but we now have DT-based pinctrl since drivers: pinctrl: new state based API proposal #37572, so I'm proposing we consider that "done"

Still not done from the above list: dmas and clocks properties are usuallly phandle+specifiers in DT, but have no corresponding spec structures in their zephyr APIs.

I would argue that interrupts does not fit within the scope of this issue, as it is a plain array, not a phandle-array, in terms of its type in the bindings.

[zephyrbot]

Hi @mbolivar-nordic,

This issue, marked as an Enhancement, was opened a while ago and did not get any traction. Please confirm the issue is correctly assigned and re-assign it otherwise.

Please take a moment to review if the issue is still relevant to the project. If it is, please provide feedback and direction on how to move forward. If it is not, has already been addressed, is a duplicate, or is no longer relevant, please close it with a short comment explaining the reason.

@pabigot you are also encouraged to help moving this issue forward by providing additional information and confirming this request/issue is still relevant to you.

Thanks!