DT: new pinctrl helpers

[mbolivar-nordic]

The commit which introduces new pin control helper macros to devicetree.h is:

devicetree: add devicetree/pinctrl.h

This contains accessor macros for getting phandles out of pinctrl
properties by name and index. As usual, the representation in C for a
phandle is a node identifier.

Add these new macros:

- DT_PINCTRL_BY_IDX(node_id, pc_idx, idx): phandle at index idx
  in the pinctrl-<pc_idx> property

- DT_PINCTRL_0(node_id, idx): pinctrl-0 convenience for the same

- DT_PINCTRL_BY_NAME(node_id, name, idx): phandle at index idx
  in the pinctrl property named 'name'

- DT_PINCTRL_NAME_TO_IDX(node_id, name): convert a pinctrl property
  name to its index number

- DT_NUM_PINCTRLS_BY_IDX(node_id, pc_idx): number of phandles in
  pinctrl-<pc_idx>

- DT_NUM_PINCTRLS_BY_NAME(node_id, name): number of phandles in a
  named pinctrl property

- DT_NUM_PINCTRL_STATES(node_id): total number of pinctrl-<pc_idx>
  properties

- DT_PINCTRL_HAS_IDX(node_id, pc_idx): does pinctrl-<pc_idx> exist?

- DT_PINCTRL_HAS_NAME(node_id, name): does a named pinctrl property
  exist?

- DT_PINCTRL_IDX_TO_NAME_TOKEN(node_id, pc_idx): convert a pinctrl
  index to its name as a token, similar to DT_STRING_TOKEN()

- DT_PINCTRL_IDX_TO_NAME_UPPER_TOKEN(node_id, pc_idx): like
  DT_PINCTRL_IDX_TO_NAME_TOKEN, but with an uppercase result

As well as DT_DRV_INST equivalents, which take inst wherever node_id
appears above:

- DT_INST_PINCTRL_BY_IDX()
- DT_INST_PINCTRL_0()
- DT_INST_PINCTRL_BY_NAME()
- DT_INST_PINCTRL_NAME_TO_IDX()
- DT_INST_NUM_PINCTRLS_BY_IDX()
- DT_INST_NUM_PINCTRLS_BY_NAME()
- DT_INST_NUM_PINCTRL_STATES()
- DT_INST_PINCTRL_HAS_IDX()
- DT_INST_PINCTRL_HAS_NAME()
- DT_INST_PINCTRL_IDX_TO_NAME_TOKEN()
- DT_INST_PINCTRL_IDX_TO_NAME_UPPER_TOKEN()


Signed-off-by: Martí Bolívar <[email protected]>

The rest of the PR is prep work, bookkeeping, and documentation.

---

This change is 

[gmarull]

Some initial thoughts, thanks for this DT update

[galak]

Looks good, one comment on what _BY_IDX means and impact on PINCTRL_0 api variants.

[gmarull]

A few needs that I've found while implementing #37572 that may be considered in this PR:

• Get the number of states: https://github.com/zephyrproject-rtos/zephyr/pull/37572/files#diff-dedbb4b6ad2a7cb3dd130a96c39262ab8aab28e19f7d1a755cc494098bb8ce0dR60
• Check if a node has pinctrl-N entry: https://github.com/zephyrproject-rtos/zephyr/pull/37572/files#diff-dedbb4b6ad2a7cb3dd130a96c39262ab8aab28e19f7d1a755cc494098bb8ce0dR87
• Check if a node has any pinctrl- entry: https://github.com/zephyrproject-rtos/zephyr/pull/37572/files#diff-dedbb4b6ad2a7cb3dd130a96c39262ab8aab28e19f7d1a755cc494098bb8ce0dR112
• DT_PROP_LEN_BY_PHANDLE would be useful: https://github.com/zephyrproject-rtos/zephyr/pull/37572/files#diff-f34d2a68c76fae0b08749a3c887049e61c5e1fc23cbb0d86221e323e5f5b1037R102-R103

[brockus-zephyr]

Reviewed 2 of 3 files at r1, 18 of 18 files at r2, all commit messages.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on @ABOSTM, @FRASTM, @henrikbrixandersen, @ioannisg, @jackrosenthal, @katsuster, @keith-zephyr, @kgugala, @MaureenHelm, @mgielda, @nandojve, @nashif, @pgielda, and @sjg20)

[mbolivar-nordic]

Rebased and removed DNM. I'm going to leave it up to @galak to decide if we want this in for LTS.

[cfriedt]

@galak - feel free to merge or if you would like to hold off apply the DNM label again

[brockus-zephyr]

Reviewed 4 of 4 files at r3, all commit messages.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on @ABOSTM, @FRASTM, @henrikbrixandersen, @ioannisg, @jackrosenthal, @katsuster, @keith-zephyr, @kgugala, @MaureenHelm, @mgielda, @nashif, @pgielda, and @sjg20)