Support of device tree gpio-map

[erwango]

Introduction

Implement device tree gpio-map concept to enable the complete definition of connectors, down to individual pin assignments.

Problem description

Today, in device tree description, we miss a way to provide a reference to an individual pin.
This limitation is particularly blocking in the shield area where we need to be able to use a generic reference to a single pin, in the way we're able to use generic reference to a device like arduino_i2c.
For instance, use of arduino_spi requires the ability to refer a chip select pin, but we don't have a way to define arduino_d2 in board dts files.

Solves #15598
Required to unlock #14057

Proposed change

Implement the dts upcoming gpio-map concept described in device tree specification v0.3

Detailed RFC

Following part was earlier described in #14057 (comment), but is detailed again here for sake of clarity.

gpio-map concept provides a way to define a pin-map and adds the possibility to define GPIO flag in the shield overlay.

Basically, on board side, pin header is defined as follows:

	arduino_header: connector {
	        #gpio-cells = <2>;
	        gpio-map = <0 0 &gpiob 2 0>,
	                   <1 0 &gpiob 3 0>,
	                   <2 0 &gpiob 10 0>,
	                   <3 0 &gpiob 11 0>,
	                   <4 0 &gpioc 11 0>,
	                   <5 0 &gpioc 10 0>,
	                   <6 0 &gpioc 16 0>,
	                   <7 0 &gpioc 17 0>,
	                   <8 0 &gpiob 9 0>,
	                   <9 0 &gpioa 1 0>,
	                   <10 0 &gpiob 23 0>,
	                   <11 0 &gpioa 2 0>,
	                   <12 0 &gpioc 2 0>,
	                   <13 0 &gpioc 3 0>,
	                   <14 0 &gpioc 12 0>,
	                   <15 0 &gpioc 4 0>,
	                   <16 0 &gpiod 0 0>,
	                   <17 0 &gpiod 2 0>,
	                   <18 0 &gpiod 3 0>,
	                   <19 0 &gpiod 1 0>,
	                   <20 0 &gpioe 25 0>,
	                   <21 0 &gpioe 24 0>;
	        gpio-map-mask = <0xf 0x0>;
	        gpio-map-pass-thru = <0x0 0x1>;
	};

In shield overlay, we can refer to individual pins as follows

   	expansion_device {
   	        reset-gpios = <&arduino_header 4 0>;
   	        power-gpios = <&arduino_header 5 0>;
   	};

Processed by dtc (current zephyr supported version), this ends up in the following:

	arduino_header: connector {
		#gpio-cells = <0x02>;
		gpio-map = <0x00 0x00 0x06 0x02 0x00>, <0x01 0x00 0x06 0x03 0x00>, <0x02 0x00 0x06 0x0a 0x00>, <0x03 0x00 0x06 0x0b 0x00>, <0x04 0x00 0x03 0x0b 0x00>, <0x05 0x00 0x03 0x0a 0x00>, <0x06 0x00 0x03 0x10 0x00>, <0x07 0x00 0x03 0x11 0x00>, <0x08 0x00 0x06 0x09 0x00>, <0x09 0x00 0x07 0x01 0x00>, <0x0a 0x00 0x06 0x17 0x00>, <0x0b 0x00 0x07 0x02 0x00>, <0x0c 0x00 0x03 0x02 0x00>, <0x0d 0x00 0x03 0x03 0x00>, <0x0e 0x00 0x03 0x0c 0x00>, <0x0f 0x00 0x03 0x04 0x00>, <0x10 0x00 0x09 0x00 0x00>, <0x11 0x00 0x09 0x02 0x00>, <0x12 0x00 0x09 0x03 0x00>, <0x13 0x00 0x09 0x01 0x00>, <0x14 0x00 0x08 0x19 0x00>, <0x15 0x00 0x08 0x18 0x00>;
		gpio-map-mask = <0x0f 0x00>;
		gpio-map-pass-thru = <0x00 0x01>;
		phandle = <0x0a>;
	};

	expansion_device {
		ublox-sara-r4-0-mdm-reset-gpios = <0x0a 0x04 0x00>;
		ublox-sara-r4-0-mdm-power-gpios = <0x0a 0x05 0x00>;
	};

At this step reset-gpios as a phandle that redirect to arduino_header but not directly the gpio phandle we expect. To get this, there are some operations to be done with gpio-map-mask and gpio-map-pass-thru. These are described in device tree specification and have to be implemented in scripts/dts/extract_dts_includes.py so we can generate whatever #defines
we need.

So far I haven't dig much more and this might have some limitation in some cases.
At least, it allows to compile the dt source in a clean way and exit with a specified output.

Proposed change (Detailed)

Aside from providing the descriptions in boards and use them in shields, the required implementation is to perform the phandle resolution that still has to be done following dtc processing.

Dependencies

External dependency is on device tree.
On documentation side, we'll rely on device tree spec that should be release in coming monthes. Then, gpio-maps are already supported by dtc version required by zephyr

Concerns and Unresolved Questions

Initial proposal for the implementation of the gpio-connector phandle resolution was to be done in scripts/dts/extract_dts_includes.py.
Following discussion with @galak, an alternative would be to introduce a new step in dts processing (following dtc) and do the resolution at this step.

EDIT: It was agreed to go with extract_dts_includes as a first start.

Alternatives

Best alternative was proposed in #14057, but was showing limitations and missed compliance with dts.

[erwango]

Some details on implementation in extract_dts_includes.py:

Proposal is to instantiate a new parent<>child relationship with gpio-map node being the parent and connector being the child, similar to what is implemented for buses.