Introduce pinctrl API to support pinctrl dts nodes #22748
Description
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)
-
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)
-
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