Ideas for the ongoing pinctrl discussion #35077
-
|
Here is my input to the ongoing discussions of how to structure the upcoming pinctrl API and devicetree nodes in Zephyr. These ideas build upon the many proposals and ideas by other members of the community. The following PRs have been used as inspiration:
The discussions have focused on two different areas of implementation; the pinctrl C/C++ API for configuring pin function and pin properties at runtime, and the devicetree representation of pre-defined pin functions and pin properties. Devicetree representationMultiple ideas for devicetree representation has surfaced during the ongoing API discussions. From what I have seen, the discussions have been centred around the following concepts:
APIGiven the differences between the pin controllers/pin multiplexers present in the various SoCs, I do not see any way (or even value) of a truly common API. One option that comes close is an API that allows passing in a SoC pinctrl/pinmux specific data structure (or array of said data structure along with a length) representing the specific information needed for that given SoC pinctrl/pinmux as a void pointer. SoC pinctrl/pinmux The data structures representing the Should a user application have a need for For more advanced use-cases (e.g those outlined for CircuitPython in #11918), the above can also support run-time configuration of pinctrl/pinmux without any compile-time devicetree representation of the desired |
Beta Was this translation helpful? Give feedback.
Replies: 7 comments 13 replies
-
This is basically what we have for the clock control API. I could see some value in this, since it would allow hardware-specific overlays to configure a subsystem or application for e.g. "on" / "powersave" without cluttering the source code with board ifdefs. |
Beta Was this translation helpful? Give feedback.
-
|
For DTS, we have something like this today for NXP: In board.dts: In SOC-pinctrl.dtsi (this data is generated from vendor XML files): From #35039 for STM32: From SoC dtsi we have: |
Beta Was this translation helpful? Give feedback.
-
I have been giving this some more thought. The pinctrl DTS grouping makes sense if the pinctrl API takes an index for which group to configure. If the API does not take an index (but instead takes a pointer to a semi-opaque structure as discussed above) I do not see any gain from adding the group indirection in DTS. I therefore think DTS representation option 3. (see above) makes most sense. |
Beta Was this translation helpful? Give feedback.
-
|
Some notes/thoughts on the Devicetree representation used by Linux vs. Zephyr for the STM32 case: On Linux we have:
The Linux approach could be improved if we had the following content auto-generated: That is, if we had a ...
#define USART2_TX_PD5 STM32_PINMUX('D', 5, AF7)
#define USART2_RTS_PD4 STM32_PINMUX('D', 4, AF7)
#define USART2_RX_PD6 STM32_PINMUX('D', 6, AF7)
#define USART2_CTS_NSS_PD3 STM32_PINMUX('D', 3, AF7)
...NOTE: This can be easily done re-using parts from https://github.com/zephyrproject-rtos/hal_stm32/blob/main/scripts/genpinctrl/genpinctrl.py This way, the I'm not sure if the "pins1" and "pins2" subgroups can be extracted properly with current DT tooling, @mbolivar-nordic ? If we compare with the current approach in Zephyr:
I think that the most important difference is that if we used the Linux approach the board takes the final decision on pin settings such as the pull-up/down, slew-rate, etc. This is something that I think makes sense, it's really the board/application that has the information to make this decision. As of today the STM32 auto-generator provides common defaults, but they are not necessarily the best ones. They can certainly be overridden, though. A side note of a limitation I found when using current STM32 approach: #22748 (comment) |
Beta Was this translation helpful? Give feedback.
-
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 then the binding would be something like |
Beta Was this translation helpful? Give feedback.
-
|
@mbolivar-nordic there's actually one more level: so it's like the child binding has groups inside. |
Beta Was this translation helpful? Give feedback.
-
|
You could do this with the above binding if you give the |
Beta Was this translation helpful? Give feedback.
-
|
Some more notes and thoughts on DT representation. Feel free to edit, comment, discuss pros/cons, etc. 1. DT node for each state, containing all pins (Linux approach, e.g. for ST)
Pros:
Cons:
Notes:
2. DT node for each pin (Zephyr approach, e.g. for ST)
If the file is auto-generated and the board needs to change any of the default pin properties, it can do it like this: There is a proof of concept that introduces low power/sleep states using this approach: Pros:
Cons:
3. Variant of (2) for auto-generated casesIf the auto-generated files do not contain pin configuration, i.e. only pin routing, we'd then have:
Pros:
Cons:
4. Vendor specific approach 1 (nRF)The pinctrl API doesn't need to make any assumption on how pinctrl data is stored internally. This means that, in practice, vendors can really decide what to do in nodes referenced from For example, for nRF we could have:
Pros:
Cons:
5. Vendor specific approach 2 (nRF)Following on vendor specific approach, we could have, for nRF:
Pros:
Cons:
|
Beta Was this translation helpful? Give feedback.
-
Sure, auto-generation is required, but this doesn't answer any of these points (bloated + hard to find correct config)
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). |
Beta Was this translation helpful? Give feedback.
-
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).
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. |
Beta Was this translation helpful? Give feedback.
-
|
Examples for multiple of the approaches listed in this thread for Nordic:
Initial thoughts:
|
Beta Was this translation helpful? Give feedback.
-
|
@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 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 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. |
Beta Was this translation helpful? Give feedback.
-
|
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 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. |
Beta Was this translation helpful? Give feedback.
-
|
if at (4)
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 User still have the possibility to do below changes because properties are stored by pin individually. Not sure if this kind of flexibility should be available. |
Beta Was this translation helpful? Give feedback.
-
This would re-use names in the macro, but they'd not be DT properties as defined in
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.
This is how it's done today for the STM32 case, the flexibility is given by Devicetree itself. |
Beta Was this translation helpful? Give feedback.
-
|
I noted that loopback interfaces currently require pinctrl definitions to avoid build errors. I'm not sure if this is a valid use case. |
Beta Was this translation helpful? Give feedback.
Some more notes and thoughts on DT representation. Feel free to edit, comment, discuss pros/cons, etc.
1. DT node for each state, containing all pins (Linux approach, e.g. for ST)
board.dts:pinctrl-Nproperties reference a node that contains the whole configuration set for a given state. Nodes are defined in aboard-pinctrl.dtsifile.board-pinctrl.dtsi: contains all configurations for a givenboard.