Introduce pinctrl API to support pinctrl dts nodes

[erwango]

Introduction

In order to be able to use dts defined pin configurations, zephyr needs to propose a pinctrl API allowing to configure pins based on dts dt-bindings. This API will have to co-exist with newly introduced gpio API.

This issue is the follow up of #15611. It does not suggest solution, but is meant to launch discussions.

The Devicetree side of things is here: #29369.

Problem description

Following Linux description: "modules that control pin multiplexing or configuration parameters
such as pull-up/down, tri-state, drive-strength etc are designated as pin controllers".
A pinctrl API should allow device drivers to configure pins based on data available from dts pinctrl nodes, using pinctrl bindings (cf Linux pinctrl-bindings).
Pinctrl operation may be done by pinctrl client at boot time (initial device pin configuration), but also at run time (set pins to a power saving state).

Use cases

• Pin configuration at runtime. We can support this in two different levels:
  • Set or group-based: A single firmware image supports a finite set of board variants, with the selection taking place at boot time using a runtime variable (for example checking the level of a GPIO, which will be high on the a variant and low in another one). The flexibility on the differences among board variants is to be discussed, but at the very minimum it should support removing functions (eg. an external SPI flash present on a development board, but not on the final product)
  • Support the possibility of assigning functions to pins freely at runtime cf Runtime pin configuration #11918, Support peripheral deallocation at runtime #20012.

Considerations

Impacts of following points may vary across architectures, this list intends to be exhaustive (update if needed).

• Functional overlap:

Considering dt-bindings, pinctrl operations will have a certain overlap with gpio operations:
gpio: direction(i/o/disconnect), value, bias(pull_up/down), drive(push-pull, open-drain, ..), active level(active low/high), interrupts
pinctrl: muxing, bias, drive, input, slew rate (cf Linux pincfg dt-binding)

• Shared resources:

gpio and pinctrl driver may require access to same pinctrl/gpio modules.
Aside from the pure conflict of access, impact on low power operations (controller clock switch off) should also be considered.

• Runtime pinctrl data access:

The Linux pinctrl interface has a lot of functionality to query pinctrl configuration data. This functionality should be guarded by a config option (e.g. CONFIG_PINCTRL_RUNTIME_DTS), if implemented at all, to enable pinctrl for very memory constraint devices.

• Pin controller device struct data

The way to generate the pinctrl configuration data for pin controller devices is key in the implementation of such a driver. Currently there is no adequate support in Zephyr. The tooling shall be clarified (gen_defines.py, another python script, ...).

Impact on implementation

Aside from the pure API perspective (what services to offer), on the architectures impacted by some of the above points, pinctrl API implementation will raise dilemmas to resolve ahead of implementations.
Implementing pinctrl driver fully separately from gpio driver will have impact on memory footprint and make the resource sharing complex.
Other solutions could be considered (with potential impact on performance)

• gpio devices relying on pinctrl sevices or vice versa
• gpio and pinctrl relying on services of common driver.

Steps to implement

Steps to implement and candidate PRs for the different aspects of implementation.

• Pin controller API (aka. include/drivers/pinctrl.h)

  • TBD

• Device tree pin configuration data encoding (aka. include/dts-bindings/pinctrl.h)

  • RFC: dts: stm32: Introduce linux like pinctrl bindings #20386, [WIP] NXP Kinetis DTS Pinmux rework #20398

• Pin controller device struct data format (struct config, struct data)

  • TBD

• Device tree pin configuration data extraction (tooling)

  • [RFC] edtlib: enhance for pin controller, clock controller, partitions, special nodes #22255, enhance edtlib.py for pin controller data extraction

• Pin controller device struct data generation (tooling)

  • Draft: hack to generate structs #22727

• Pin controller device implementation for all SoCs

  • TBD

EDIT:
20-02-12: Added "Runtime pinctrl data access" and "Pin controller device struct data" (@b0661)
20-02-13: Added "Steps to implement" section (@b0661)
20-10-14: Added "Runtime pin configuration" following dev-review meeting.
20-10-27: Added "usecases" section following dev-review meeting

[erwango]

@carlescufi, @galak, @MaureenHelm, @pabigot, @mnkp, @b0661, @mbolivar

[b0661]

Things to consider

• Runtime pinctrl data access:

The Linux pinctrl interface has a lot of functionality to query pinctrl configuration data. This functionality should be guarded by a config option (e.g. CONFIG_PINCTRL_RUNTIME_DTS), if implemented at all, to enable pinctrl for very memory constraint devices.

• Pin controller device struct data

The way to generate the pinctrl configuration data for pin controller devices is key in the implementation of such a driver. Currently there is no adequate support in Zephyr. The tooling shall be clarified (gen_defines.py, another python script, ...).

[b0661]

Steps to implement

Steps to implement and candidate PRs for the different aspects of implementation.

• Pin controller API (aka. include/drivers/pinctrl.h)

  • https:/b0661/zephyr/blob/a922f8c7f3fd88d36b6a85329d7cb22c03183105/include/pinctrl.h

• Device tree pin configuration data encoding (aka. include/dts-bindings/pinctrl.h)

  • [ ]

• Pin controller device struct data format (struct config, struct data)

  • TBD

• Device tree pin configuration data extraction (tooling)

  • [RFC] edtlib: enhance for pin controller, clock controller, partitions, special nodes #22255, enhance edtlib.py for pin controller data extraction

• Pin controller device struct data generation (tooling)

  • TBD

• Pin controller device implementation for all SoCs

  • TBD

[erwango]

@b0661 , out of curiosity, from what I understand you've already implemented pinctrl driver oot, could you share with us the solution you chose regarding gpio/pinctrl responsibilities partitioning?

[b0661]

@erwango

The solution is already in #6760. Gpio is using pinctrl as a backend for pin configuration and muxing.

The OOT pinctrl driver/gpio_pinctrl drivers are currently not adapted to the new GPIO API. I may provide this after adaptations are done. The drivers are based on inline code generation - so maybe not of interest to Zephyr.

[carlescufi]

API meeting 6th October 2020:

@erwango describes the current state of the pinctrl API and bindings today.

Usecases:

• Runtime PIN control: to what extent?
• I2C and GPIO on the same set of pins to reset the bus

What do we want to achieve?

• A generic pinctrl API for drivers to map pins to functions. The mapping could come from Devicetree or be populated at runtime by the caller

pinctrl_pin_set(P0, 12, UART_TXD);
pinctrl_pin_group_set(.. group ..);

• An API to configure a pin (pull-up, pull-down, drive strength, etc)

pinctrl_pin_flags_set(pin, PULL_UP);

• Maintain, to the max extent possible, compatibility with the Linux Devicetree bindings

[carlescufi]

API meeting 13th October 2020:

• @gmarull volunteers as long as it is a shared effort and it doesn't fall entirely on his shoulders
• @carlescufi to check with @erwango for availability
• @galak and @henrikbrixandersen also volunteer to help
• @mnkp best-effort

---

• In Linux, the pinctrl subsystem initializes the pins independently of the peripheral driver, before the driver is "probed". The driver can then change the state. In some cases however (at least power management), the driver does switch states
• In Linux there are a set of mutually exclusive predefined pin states that can be selected
• In Linux the pinctrl subsystem identifies pins using the identifiers in the actual package. This applies to things like GPIO extenders, where the pins are treated the same as the built-in SoC ones.

@mnkp asks:

• In the pinctrl API, should we use the absolute/global "package" pin numbers or have separate "namespaces" per-port.
• It is suggested that the encoding of the pin could be SoC-specific, and the API be generic enough that it can transport any representation of a pin number, typically a combination of a port and a pin.

[gmarull]

For reference, an overview of pinctrl: https://wiki.st.com/stm32mpu/wiki/Pinctrl_overview

[galak]

A few topics for thought:

• how pin params/flags (pull-up/down, slew, etc) are handled. Via gpio api, via pinctrl api, via both - leave to implementations.
• How devicetree and api that is dev, port, pin, flags works for SoCs that have pinmux at the device level (SiLabs, Nordic).

[jettr]

I think it will be confusing if both pinctrl and gpio API allow for us to configure the same information (e.g. pull up/down, drive strength, open-drain). We should pick one of them to do it (I would lean towards GPIO).

Should pinctrl focus more on the alternate mode and grouping aspects of pins? Pinctrl could be thought of as the controller for the pinmux device/operations.

---

On a related but different note, I noticed that the gpio API does not have a way to get the current gpio flags. It would be really useful to have a getter function to determine if the gpio was currently an input/output or push-pull/open-drain. (I can create a separate issue for this, but it does seem related to this overall discussion)

[pabigot]

@jettr Please open an issue for fetching GPIO flags. I've considered this before but because information can be lost in translating from the gpio_flags_t used to configure the peripheral into the peripheral-specific register settings it's not clear that the configuration can be reconstructed, or that it's worth caching the original configuration (4 bytes RAM per GPIO pin), or that doing so would be particularly useful. Anything that configures a GPIO should be able to track out how it was configured, and it's not obvious that things that didn't configure the GPIO need to know. But that can be discussed in the proposed issue.

[nandojve]

The #28645 is an example that shows how to do it using pinctrl only. There is a variable length {0 - N} list for params. Users can complement that on board DTSI files or create their own. That shows how drivers can directly configure using pinctrl-0. Of course it is possible elaborate more and have a centralized entity to initialize all at same time. I think it is not so difficult to create a struct to store the data using DT_FOREACH like function, once params are bitfields and example shows how to handle it. It is possible inclusive store all pinctrl+flags (enabled and not at DT) that can be useful at runtime to change configurations.

[henrikbrixandersen]

I think it will be confusing if both pinctrl and gpio API allow for us to configure the same information (e.g. pull up/down, drive strength, open-drain). We should pick one of them to do it (I would lean towards GPIO).

Should pinctrl focus more on the alternate mode and grouping aspects of pins? Pinctrl could be thought of as the controller for the pinmux device/operations.

I think we need to support pull up/down, drive strength, etc. via pinctrl. If we do not, how would one specify e.g. the drive strength for a non-GPIO pin?

[galak]

Dev-Review (Nov 5):

• pincfg APIs:

  • low level API that is opaque w/regards to function param (ie its SoC specific) for pin/func/etc config
  • provide pin group setting APIs around a few common use cases (default, power-mgmt, I2C bus reset)
    [ Intent is a finite set of pin data that can be "switched" at runtime based on specific use case (power mgmt state change, i2c bus reset)]

• The ability to generically identify pin as UARTn/TX is not something we intend to support

• General feeling is to leave GPIO API as is w/regards to pin configuration. We'll have pincltr API also expose the ability to config pin parameters and leave it to implementations on how this map between the GPIO API version (ie GPIO API could call pinctrl version, or pinctrl version could call GPIO API, or no coupling, etc.)

[carlescufi]

API meeting 27.04.2021

@mnkp describes the options available to us

a) Closer to the Linux approach
b) Closer to the current Zephyr approach

a) The pinctrl driver owns an array of struct cfg with all the possible configurations that the application has defined in its Devicetree, which correspond to the actual physical connections on the board. In order to select one of the configuration one would then call pinmux_select(int select). In this case struct cfg contains a string that identifies the function for this particular configuration.
A UART driver could then call:
pinmux_find_pin_cfg('uart0'), which would return 7
pinmux_select(7) and that would configure the 4 UART pins
Example: https://elixir.bootlin.com/linux/latest/source/arch/arm/boot/dts/stm32mp15-pinctrl.dtsi#L1693
Doc: https://www.kernel.org/doc/html/latest/driver-api/pinctl.html

b) pinctrl_pin_configure(struct pinctrl_cfg *cfg) and pinctrl_pin_list_configure(struct cfg[]). The contents of struct cfg would be SoC-family dependant (pinctrl.h would include SoC-specific files). Ownership of the struct cfg instance could be owned by the caller or by the callee (TBD). Accessing the fields in struct cfg would be done via macros that each SoC family would implement. The contents of struct cfg would be mainly the required pinmux data and the GPIO configuration.
A UART driver could then call:
pinctrl_pin_list_configure(DT_PIN_CFG_LIST(uart0))
Example: https:/zephyrproject-rtos/zephyr/blob/master/boards/arm/nucleo_l4r5zi/nucleo_l4r5zi.dts#L76

[mbolivar-nordic]

a) Closer to the Linux approach

I was having audio problems when this was discussed, but I still cannot see how this can be made to work for Nordic devices in a space-efficient way.

If we require a full array of possibilities, then it will contain NPINS * NFUNCTIONS elements, which is simply impractical even if stored in flash, and anyway most of the data will never be used by 99% of applications, even the ones that want to dynamically switch between a few possibilities.

What am I missing?

[erwango]

a) Closer to the Linux approach

I was having audio problems when this was discussed, but I still cannot see how this can be made to work for Nordic devices in a space-efficient way.

I'm also concerned about "with all the possible configurations that the application may need". Is that all existing pinmux configurations (which could include all potential tx/rx combinatory) or only the ones configured in device tree by enabled nodes?

[gmarull]

I think storing all possible combinations is definitely a no-go. In SoC like ST we'd be wasting a lot of ROM for nothing. I think we definitely should avoid something like https://elixir.bootlin.com/linux/latest/source/drivers/pinctrl/stm32/pinctrl-stm32mp157.c here. If I'm not wrong, what was discussed was to store all combinations listed in a board -pinctrl.dtsi file in a single place (now it is done per-driver). In fact, we should only store nodes referenced in pinctrl-N properties.

[carlescufi]

@mbolivar-nordic and @erwango

I rephrased it with "all the possible configurations that the application has defined in its Devicetree, which correspond to the actual physical connections on the board". So that means that you have to know at build time which pins are connected where, in some cases to more than one peripheral, or a peripheral to more than one set of pins, on the board, and that's the only set of combinations that will be encoded and stored in the pinctrl driver. For example:

Pins 10 and 11 are physically wired to an FTDI chip that converts the UART signals to USB. But it turns out that there's also direct terminal access via raw UART provided in a port connector, to which pins 21 and 22 are wired. The software can, at runtime, decide when to route UART0 to either FTDI/USB or the UART connector.
It would then encode the two possible combinations in DT as such (pseudocode):

my-board-pinctrl.dts:

   uart0_pins_a: uart0-0 {
   		pinmux = <STM32_PINMUX('G', 10,  AF6)>; /* UART0_TX */
   		drive-push-pull;
   		pinmux = <STM32_PINMUX('B', 11, AF8)>; /* UART0_RX */
   		bias-disable;
   };

   uart0_pins_b: uart0-1 {
   		pinmux = <STM32_PINMUX('G', 21,  AF6)>; /* UART0_TX */
   		drive-push-pull;
   		pinmux = <STM32_PINMUX('B', 22, AF8)>; /* UART0_RX */
   		bias-disable;
   };

Now, UART0 can probably be connected to 100s of different other pins, but we don't care because this board only cares about these 2 sets of pins, and that's the only thing we encode and store.

[mbolivar-nordic]

@carlescufi that sounds more reasonable to me, but I think it is not compatible with "the Linux approach" option proposed by @mnkp . Or did I misunderstand?

Anyway, I guess we'll see when we have a real API proposal, but it seems like we all agree that the Zephyr API needs to give the user (i.e. the board or application maintainer) full control over how much ROM to allocate to pin configuration data. If so, that addresses my concern.

[carlescufi]

@carlescufi that sounds more reasonable to me, but I think it is not compatible with "the Linux approach" option proposed by @mnkp . Or did I misunderstand?

That is, to my understanding, exactly the Linux approach. Except Linux doesn't really have "boards" so they define more combos than strictly required. We can narrow it down better than them because we know exactly for which physical PCB we are building for.

[mnkp]

Just to reconfirm what @carlescufi has already stated. In case of option a) described here as "Closer to the Linux approach" the pinctrl would only store those combinations of pin configuration data that the application developer defined in the DTS for the given board they are developing their application for.

As it was already noted here, with modern hardware, it's not feasible to store all the possible combinations of different pin configurations that are supported by the hardware.

Option a) is actually more optimal regarding storage requirement since all the data are kept in one central place and made available to any interested party: driver or user application alike. In case of option b) if two different compilation modules switch pins between the same two peripherals each of the modules will keep local copies of the const struct that they will pass to pinctrl_pin_configure function.

[mkschreder]

@erwango refering to the discussion on stm32l0 power management (#35183) and regarding the pinctrl related stuff for low power mode, what do you think of putting it into the stm32 pinmux driver (drivers/pinmux/stm32/pinmux_stm32.c)?

Currently the driver doesn't define an instance of device with all the callback functions but perhaps it should? Then I'm thinking we could experiment with the idea of using pm callback to put individual port instances to sleep and use gpio pinmux dts nodes for configuring what to do with different pins.

This would involve a config option for PM_GPIO that will enable GPIO power save functionality. When enabled, by default it would disconnect all GPIOs upon entering powersave - but the programmer can then set specific gpio pinmux modes for certain pins or set them to be ignored when entering power saving mode.

I can see that nxp has for example these nodes:

/dts/arm/nxp/nxp_ke1xf.dtsi: porta: pinmux@40049000 {

But I don't seem to find anything relevant for stm32.

I think low power pin configurations are something that is closely related to gpio ports as they are configured on a specific board. It makes sense to put all configuration for low power deep sleep modes in one place. Perhaps even in power-states section in the board dts file. I think it would be way too complex to go through every single device driver and try to figure out how to configure low power modes for all the pins that it is using.

[erwango]

Currently the driver doesn't define an instance of device with all the callback functions but perhaps it should?

That could be studied indeed and added if helps in pinctrl design.

/dts/arm/nxp/nxp_ke1xf.dtsi: porta: pinmux@40049000 {
But I don't seem to find anything relevant for stm32.

Well, that's a bit different indeed on NXP and STM32 as on NXP (at least kxx) they have specific/distinct hw blocks for pinmux and gpio (please someone correct me if I'm wrong) and this is not the case on STM32 as "gpio" blocks are in charge both of pinmux and gpio.

I think low power pin configurations are something that is closely related to gpio ports as they are configured on a specific board. It makes sense to put all configuration for low power deep sleep modes in one place.

I'm concerned this would no fit well with Device Power Management distributed method (PM_DEVICE_RUNTIME).

[mkschreder]

@erwango interesting. I just thought of something. What about having pinctrl-[power-state] properties for all device nodes where [power-state] corresponds to the power state as specified in power-state-name. So for example: pinctrl-suspend-to-ram.

The idea being that if these properties are present, then they would be automatically used. If not, then it is up to the device driver to manage power. This way the user has the choice to either use pinctrl or let the driver manage it - which works kindof like it does today with the pinctrl-0 property.

[gmarull]

I'd like to mention a problem with approach (b) I faced a few days ago. Let me detail the example so that the problem can be better understood.

I have a custom driver called svpwm that generates a set of PWM signals that feed an inverter circuit (sometimes part of a shield). The "SV-PWM device" should be seen as the microcontroller PWM unit + the inverter. Some driver properties depend on the connected inverter circuit, for example, some circuits have enable/disable GPIOs, some others require PWM and PWM_N (inverted)....

The question now: can I use Zephyr shields? Let's see what happens.

In the current approach, a board is defined with the shield included, as if it was a single board:

&timers1 {
	svpwm: svpwm {
		compatible = "st,stm32-svpwm";
                currsmp = <&currsmp>;

                /* These depend on the shield, some shields may also require _N channels! */
		pinctrl-0 = <&tim1_ch1_pa8 &tim1_ch2_pa9 &tim1_ch3_pa10 &tim1_ocp_pa11>;

                /* These are also shield dependent, but have a solution */
		t-dead-ns = <1000>;
		t-rise-ns = <1050>;
		enable-gpios = <&gpioc 10 GPIO_ACTIVE_HIGH>,
			       <&gpioc 11 GPIO_ACTIVE_HIGH>,
			       <&gpioc 12 GPIO_ACTIVE_HIGH>;
	};
};

But we can't easily use different shields because we have this:

/* This depends on the shield, some may also require _N channels! */
pinctrl-0 = <&tim1_ch1_pa8 &tim1_ch2_pa9 &tim1_ch3_pa10 &tim1_ocp_pa11>;

If we had pinmux groups, as Linux, the board would be able to define the following groups:

&pinctrl {
    tim1_svpwm_single: tim1_svpwm_single {
        pins1 {
            pinmux = <STM32_PINMUX('A', 0, AF1)>,
                     <STM32_PINMUX('A', 1, AF1)>;
                     <STM32_PINMUX('A', 2, AF1)>;
        };
    };

    tim1_svpwm_full: tim1_svpwm_full {
        pins1 {
            pinmux = <STM32_PINMUX('A', 0, AF1)>,
                     <STM32_PINMUX('A', 1, AF1)>,
                     <STM32_PINMUX('A', 2, AF1)>,
                     <STM32_PINMUX('A', 3, AF1)>,
                     <STM32_PINMUX('A', 4, AF1)>,
                     <STM32_PINMUX('A', 5, AF1)>;
        };
    };
};

svpwm_single: &tim1_svpwm_single {};
svpwm_full: &tim1_svpwm_full {};

and then the shield could finish the device definition like this:

&svpwm {
    pinctrl-0 = <&svpwm_single>;

    t-dead-ns = <1000>;
    t-rise-ns = <1050>;
    /* use a connector with mappings */
    enable-gpios = <&my_standard_connector 0 GPIO_ACTIVE_HIGH>,
                   <&my_standard_connector 1 GPIO_ACTIVE_HIGH>,
                   <&my_standard_connector 2 GPIO_ACTIVE_HIGH>;
};

There may be other solutions to this problem, but I thought it was worth mentioning it.

[henrikbrixandersen]

There may be other solutions to this problem, but I thought it was worth mentioning it.

Another option could be to use a board-specific shield overlay.

[nandojve]

I think @gmarull is a valid proposal and can usefull.

svpwm_single: &tim1_svpwm_single {};
svpwm_full: &tim1_svpwm_full {};

&svpwm {
    pinctrl-0 = <&svpwm_single>;
   ...
};

In this case, using approach [B], will Zephyr have only pinctrl-0 ? I mean, there is no necessity to have pinctrl-1...N, right?
I was wondering if I'm missing something related to above questions.

[gmarull]

Another option could be to use a board-specific shield overlay.

Definitely an option, even though it means duplicating the shield for every board.

[gmarull]

In this case, using approach [B], will Zephyr have only pinctrl-0 ? I mean, there is no necessity to have pinctrl-1...N, right?
I was wondering if I'm missing something related to above questions.

pinctrl-1..N would still be needed to represent other states, e.g. low-power. The only difference is that pinctrl-N would contain a single phandle and not a list of phandles.

[manoj153]

do we have any plan to support boot-time gpio direction setting capability?

Possible benefits :

• the user does not have to invoke alike API gpio_pin_configure_dt() on each pin in the source code.
• if a wrong operation is carried out, returns an error, eg: invoking gpio_pin_set() on an input pin and vice-versa

while doing some google-ing found that linux might have such a feature covered, the term called gpio-hog

https://www.kernel.org/doc/Documentation/devicetree/bindings/gpio/gpio.txt
peak from the source:

- input:      A property specifying to set the GPIO direction as input.
- output-low  A property specifying to set the GPIO direction as output with
	      the value low.
- output-high A property specifying to set the GPIO direction as output with
	      the value high.

[gmarull]

do we have any plan to support boot-time gpio direction setting capability?

Possible benefits :

• the user does not have to invoke alike API gpio_pin_configure_dt() on each pin in the source code.
• if a wrong operation is carried out, returns an error, eg: invoking gpio_pin_set() on an input pin and vice-versa

while doing some google-ing found that linux might have such a feature covered, the term called gpio-hog

https://www.kernel.org/doc/Documentation/devicetree/bindings/gpio/gpio.txt
peak from the source:

- input:      A property specifying to set the GPIO direction as input.
- output-low  A property specifying to set the GPIO direction as output with
	      the value low.
- output-high A property specifying to set the GPIO direction as output with
	      the value high.

I guess it would be a matter of adding pinctrl entries to the GPIO node itself, e.g.

gpioa_default: ... {
    /* settings for GPIOA pins */
};

&gpioa {
    pinctrl-0 = <&gpioa_default>;
    pinctrl-names = "default";
};

[adminy]

Not sure if this is the most relevant place to ask but with this can I use something like libgpiod library to list a microcontroller running zephyr via usb as a gpiochip ?