include: devicetree: Generate defines for map property

[soburi]

This change introduces generating definitions corresponding to
*-map property, which was currently discarded.

The *-map data is like a two-dimensional array, so it is difficult to
handle with the existing APIs, so we will also provide new APIs.

---

Common utilities have been separated into a separate PR.
Please take a look at this first. #84190

---

I noticed this problem while developing https://github.com/zephyrproject-rtos/gsoc-2022-arduino-core.

Since map is used to associate with the physical layout, there is a need to know the "physical pin names".

Since the mapping process is performed during the generation of devicetree-generated.h, I don't think there are many cases where information about the mapping source is needed. However, there are such cases, however rare, and it is not desirable for the information written in the devicetree to be discarded, so I would like to introduce this.

[mbolivar]

Thanks for the PR, @soburi . The first 5/8 patches look good to me, with one minor comment.

I have some concerns about the last 3/8 patches. I think I understand the goal and exposing the map properties as first-class citizens makes sense to me. However, the approach using to_compound() feels a little bit error-prone and I want to discuss the implementation.

Devicetree Specification v0.4 section 2.5, "Nexus Nodes and Specifier Mapping" is where the semantics are defined. There, it says:

A nexus node shall have a #<specifier>-cells property, where <specifier> is some specifier space such as ‘gpio’, ‘clock’, ‘reset’, etc

The description of the <specifier>-map property then says:

child specifier

The specifier of the child node being mapped. The number of 32-bit cells required to specify this component is described by the #<specifier>-cells property of this node—the nexus node containing the <specifier>-map property

It also says:

parent specifier

The specifier in the parent domain. The number of 32-bit cells required to specify this component is described by the #<specifier>-cells property of the specifier parent node.

Combining these, I think that we should be able to decode each <specifier>-map property without needing to_compound(). We can make a loop like this:

1. Read #<specifier>-cells * 4 bytes from the current position in the <specifier>-map property. This is the child specifier. We can convert it to <u32> cells using existing dtlib features.
2. Read the next 4 bytes. This is the "specifier parent" phandle from section 2.5 of the specification. We can convert it to a "specifier parent node" using phandle2node.
3. Read the #<specifier>-cells property from the specifier parent node. This is the number of <u32> cells after the phandle which makes the "parent specifier"
4. Read the parent specifier bytes and convert them to cells.

What I mean is, by using the #<specifier>-cells properties in the parent and child nodes, we can iterate through the <specifier>-map property and convert it into a lookup table without to_compound().

I am concerned that to_compound() is:

• not checking the proper #<specifier>-cells values we expect to find, and instead just uses the source encoding to guess where the table entry elements are in <specifier>-map
• adding a feature for strings that does not seem to be needed to handle <speciifer>-map properties -- this feels like it might be trying to do more than it needs to, and might have to be revisited over time as we add more heuristics

I'd be more comfortable with an approach that relied on the strict definitions in section 2.5 of the specification to decode the values of <specifier>-map properties. We can be sure that this will not change and the code will stand the test of time.

[mbolivar]

I think, strictly speaking, that these are derived from the Linux iio bindings. The iio bindings are useful for ADCs but are not limited to ADCs. So perhaps this should be moved to dts/bindings/iio, and this "ADC specifier" portion should be changed to "channel specifier, e.g. ADC channel" or something similar?