devicetree: tree-wide: add nexus map properties for arduino headers

[pabigot]

We need to be able to specify GPIO flags in devicetree without that preventing translation from the Arduino specifier to the host GPIO specifier. Set up to ignore the low 6 bits of the flags field when matching the child specifier, and to copy those bits to the parent specifier.

This is a blocking capability for topic-gpio where we need to be able to specify the active level of signals from sensors connected through Arduino shields.

To preemptively answer a question: the low 6 bits are defined for devicetree in Linux although Zephyr currently does not use bit 3. Bit 3 is used to signal suspend/resume/reset persistance, so may be needed in the future.

[ulfalizer]

The old devicetree scripts do not handle *-map-mask and *-map-pass-thru by the way, but it might not matter as long as they don't crash on them, since they're only used to generate some deprecated #defines.

[erwango]

Should we add some test in order this is not omitted when new connector type is added?
(#19751 for instance)

[pabigot]

Should we add some test in order this is not omitted when new connector type is added?
(#19751 for instance)

That could perhaps be done in the devicetree scripting if it were possible to determine that the nexus map is associated with GPIOs. IMO its lack shouldn't slow incorporation of this change.

[ulfalizer]

That could perhaps be done in the devicetree scripting if it were possible to determine that the nexus map is associated with GPIOs. IMO its lack shouldn't slow incorporation of this change.

_check_dt() in edtlib.py is meant for random devicetree checks like that btw, so could add something there if you want.

If it doesn't need to look at low-level devicetree stuff, it could be added to gen_defines.py instead. Might be cleaner if it's very Zephyr-specific too.

[erwango]

I'm fine with the change, but it is a tricky one, so I'd like to see some documentation explaining the "trick" with some details.
Motivations:

• Doc is always welcome
• This is only described in V0.3 device tree spec, and it hasn't been released yet
• Even though v0.3 would be the current release, device tree spec explanations are abstruse

[pabigot]

I'm fine with the change, but it is a tricky one, so I'd like to see some documentation explaining the "trick" with some details.

Wonderful.

@ulfalizer since you maintain the devicetree documentation could you provide a patch with this that I can add to this PR? If you can point me to it in a branch I can cherry-pick it into this.

[pabigot]

@erwango @ulfalizer @dbkinder please review the newly added documentation on this feature.

[zephyrbot]

All checks are passing now.

Tip: The bot edits this comment instead of posting a new one, so you can check the comment's history to see earlier messages.

Need approval of added documentation

[erwango]

I don't know if there is a kind of bitmap drawing available we can point to but it would be nice.
(To do later since it is a different branch)

[erwango]

Much clearer than dts specification!

[ulfalizer]

Sorry, didn't notice the update until now.

Looks good to me.

[pabigot]

@dbkinder Could you please check the documentation addition to this for acceptability? This PR blocks work on driver conversion to the new gpio API. Thanks.

[dbkinder]

While I'd prefer the gpio_nexus.inc content to be put in the rst file directly, it's OK as is.

[dbkinder]

The reason to use an include file would be if this content were placed in more than one part of our documentation. If you don't see that as a possibility (there isn't a second reference today) then I'd recommend putting this addition into the index.rst file instead of a separate .inc file.

[pabigot]

OK, I'll integrate it into the file. I need to rebase and add a shippable override to get CI to pass anyway.

[pabigot]

@galak all tests pass via https://app.shippable.com/github/zephyrproject-rtos/zephyr/runs/54062/summary/console

I've now removed the shippable override. This should be good for merge.