View source for Yocto: I/O Configuration and Device Tree Customization

= Overview =
Hardware devices (SoC modules, on-board peripherals etc.) and their interconnections are described in Linux O/S using data structures called Device Trees.</br>
Compulab provides default Device Trees that match the I/O interconnections and peripheral devices implemented on the Compulab System-on-Module and on the reference carrier-board.</br>
Customers designing a custom carrier-board will often need to make changes to the device tree in order to describe the I/O interconnections and peripheral devices specific to their design.</br>
This article outlines the process of Device Tree customization required for making I/O configuration changes.
== Board Functionality Configuration Process ==
Board functionality configuration will usually involve the following steps:
# Identifying configuration requirements
# Configuring required device nodes in device tree
# Configuring required pin multiplexing in device tree

= Identifying Configuration Requirements =
The first step in device tree customization is to identify the specific configuration or modification required in your design. This could include enabling or disabling peripherals, modifying pin assignments or configuring specific hardware-specific functionalities.
To determine the customization scope, refer to the documentation of your hardware components, including the System-on-Chip (SoC), System on Module (SoM), and carrier board schematics.
It is recommended to use the following Compulab resources:
* SOM technical reference manual
* Pin-mux configuration tools
* Default reference device tree

= Defaut reference device tree =
Compulab default reference device tree files are named according to '''som-name.dts''' template and can be found in /arch/arm64/boot/dts/compulab/ folder of BSP source.
For example, default device tree file for UCM-iMX8PLUS is named '''ucm-imx8m-plus.dts'''.
The default device tree file is derived from the SoC pin-multiplexing header file which is part of the SoC BSP.
Pin multiplexing configuration is controlled by SoC registers. These registers are documented in detail in the SoC technical reference manual.

= Configuring Device Tree Nodes =

Device tree nodes are segments of the device tree that contain information about a specific hardware device. The contents of each node are dictated by the driver that is responsible for handling the hardware component.</br>
Device tree nodes need to be modified or added when new hardware devices are added or functionality is changed.

The following documents contain detailed information about the Linux device tree and its structure:

* [https://www.kernel.org/doc/html/next/devicetree/usage-model.html#linux-and-the-devicetree Linux and the Devicetree]
* [https://www.devicetree.org/specifications/ Device Tree Specification]

= Configuring Pin Multiplexing =
== Pin Selection and Allocation ==
The majority of ARM-based SoC pins are multi-functional and multiplexed allowing to use a single physical pin for one of several functions.</br>
Certain functions may be available on more than one pin. Using a specific pin for a certain function will preclude using it for another peripheral module.
Carrier-board designers must select and allocate interface pins per the requirements of their design taking into account pin availability and multiplexing constraints.
Pin availability and multiplexing of Compulab System-on-Modules are described in detail in the "Signal Multiplexing Characteristics" reference manual chapter of each SOM. In addition, pin multiplexing tools can be used to simplify pin allocation process.
<!--To learn more please refer to [[Selection and Allocation of Multiplexed Pins in Compulab System-on-Modules]]-->

== Modifying the device tree ==
The device tree segment that controls pin multiplexing will typically look as shown below:
<pre>
&iomuxc {
	pinctrl-names = "default";
	pinctrl-0 = <&pinctrl_hog>;

	pinctrl_hog: hoggrp {
		fsl,pins = <
			MX8MP_IOMUXC_HDMI_DDC_SCL__HDMIMIX_HDMI_SCL	0x400001c3
			MX8MP_IOMUXC_HDMI_DDC_SDA__HDMIMIX_HDMI_SDA	0x400001c3
			MX8MP_IOMUXC_HDMI_HPD__HDMIMIX_HDMI_HPD		0x40000019
			MX8MP_IOMUXC_HDMI_CEC__HDMIMIX_HDMI_CEC		0x40000019
		>;
	};
...
};
</pre>

Each pin has up to 8 multiplexed functions. To simplify selecting the pin function, NXP provides macros for each SOC with the following naming convention: '''<SOC>_<PIN NAME>_<PIN FUNCTION>'''.</br>
For example: '''MX8MP_IOMUXC_NAND_READY_B__GPIO3_IO16''' in which SOC = MX8MP, PIN NAME = IOMUXC_NAND_READY_B_, PIN FUNCTION = GPIO3_IO16.</br>
Pin multiplexing registers and settings are documented in detail in each SoC reference manual that can be downloaded from the NXP website.

Each i.MX SoC has a pin config file with pin function macro definitions as well as documentation in the device tree bindings directory.</br>
For the i.MX family, the pinfunc files are located at ''arch/arm64/boot/dts/freescale/'' and the documentation is located at ''Documentation/devicetree/bindings/pinctrl/''

{| class="wikitable" style="text-align:center;" width=40%
|-
| align="center" | '''Header file''' 
| align="center" | '''Documentation''' 
|-
| align="" | imx8mp-pinfunc.h
| align="" | fsl,imx8mp-pinctrl.yaml
|-
| align="" | imx8mq-pinfunc.h
| align="" | fsl,imx8mq-pinctrl.yaml
|-
| align="" | imx8mm-pinfunc.h
| align="" | fsl,imx8mm-pinctrl.yaml
|-
| align="" | imx93-pinfunc.h
| align="" | fsl,imx93-pinctrl.yaml
|-
|}

=== Pin mux-mode and function ===
Each device tree pinmux entry has the following structure:

{| class="wikitable" style="text-align:center;" width=40%
|-
| align="center" | '''SW_MUX_CTRL''' 
| align="center" | ''' SW_PAD_CTRL''' 
|-
| align="" | MX8MP_IOMUXC_NAND_READY_B__GPIO3_IO16
| align="" | 0x19
|}


'''SW_MUX_CTRL''' register sets the multiplexing mode of the pin. Example:

[[File:Imx8mp_sw_mux_ctrl.png|800px]]

'''SW_PAD_CTRL''' register sets the specific operating setting of the pin. Example:

[[File:Imx8mp_sw_pad_ctrl.png|800px]]

=== Example: adding a gpio_led node ===
In this example, the '''fsl,pins''' has one pin entry: pin '''MX8MP_IOMUXC_NAND_READY_B''' is configured for function '''GPIO3_IO16'''.

<pre>
&iomuxc {
	pinctrl-names = "default";
	pinctrl-0 = <&pinctrl_hog>;

	pinctrl_hog: hoggrp {
		fsl,pins = <
			MX8MP_IOMUXC_HDMI_DDC_SCL__HDMIMIX_HDMI_SCL	0x400001c3
			MX8MP_IOMUXC_HDMI_DDC_SDA__HDMIMIX_HDMI_SDA	0x400001c3
			MX8MP_IOMUXC_HDMI_HPD__HDMIMIX_HDMI_HPD		0x40000019
			MX8MP_IOMUXC_HDMI_CEC__HDMIMIX_HDMI_CEC		0x40000019
		>;
	};
	pinctrl_gpio_led: gpioledgrp {
		fsl,pins = <
			MX8MP_IOMUXC_NAND_READY_B__GPIO3_IO16	0x19
		>;
	};
...
}
</pre>

= Interface Configuration Examples =
== UART ==
'''Pinmux'''
<pre>
pinctrl_uart2: uart2grp {
	fsl,pins = <
		MX8MP_IOMUXC_UART2_RXD__UART2_DCE_RX	0x49
		MX8MP_IOMUXC_UART2_TXD__UART2_DCE_TX	0x49
	>;
};
</pre>
'''Device Node'''
<pre>
&uart2 {
	/* console */
	pinctrl-names = "default";
	pinctrl-0 = <&pinctrl_uart2>;
	assigned-clocks = <&clk IMX8MP_CLK_UART2>;
	assigned-clock-parents = <&clk IMX8MP_SYS_PLL1_80M>;
	status = "okay";
};
</pre>

== GPIO ==
For GPIOs to be used directly by user space applications:

'''Pinmux'''
<pre>
pinctrl_uart3: uart3grp {
	fsl,pins = <
		MX8MP_IOMUXC_UART3_RXD__GPIO5_IO26	0x49 /* GPIO=(5-1)*32+26=154 */
		MX8MP_IOMUXC_UART3_TXD__GPIO5_IO27	0x49 /* GPIO=(5-1)*32+27=155 */
	>;
};
</pre>

{{note| These pinmux group must be configured by iomux driver.}}
<pre>
&iomuxc {
	pinctrl-names = "default";
	pinctrl-0 = <&pinctrl_hog> <&pinctrl_uart3>;
...
}

</pre>

For GPIOs to be used as peripheral control signals (reset, interrupt, power control etc.)</br>
'''Pinmux'''
<pre>
pinctrl_flexcan1_reg: flexcan1reggrp {
	fsl,pins = <
		MX8MP_IOMUXC_GPIO1_IO00__GPIO1_IO00	0x154	/* CAN1_STBY */
	>;
};

pinctrl_flexcan2_reg: flexcan2reggrp {
	fsl,pins = <
		MX8MP_IOMUXC_GPIO1_IO01__GPIO1_IO01	0x154	/* CAN1_STBY */
	>;
};
</pre>
'''Device nodes'''
<pre>
	reg_can1_stby: regulator-can1-stby {
		compatible = "regulator-fixed";
		regulator-name = "can1-stby";
		pinctrl-names = "default";
		pinctrl-0 = <&pinctrl_flexcan1_reg>;
		regulator-min-microvolt = <3300000>;
		regulator-max-microvolt = <3300000>;
		gpio = <&gpio1 0 GPIO_ACTIVE_HIGH>;
		enable-active-high;
	};

	reg_can2_stby: regulator-can2-stby {
		compatible = "regulator-fixed";
		regulator-name = "can2-stby";
		pinctrl-names = "default";
		pinctrl-0 = <&pinctrl_flexcan2_reg>;
		regulator-min-microvolt = <3300000>;
		regulator-max-microvolt = <3300000>;
		gpio = <&gpio1 1 GPIO_ACTIVE_HIGH>;
		enable-active-high;
	};
</pre>

<!--
=== Linux gpio tools/methods ===
==== sysfs ====
* List of defined and exported gpios
<pre>
cat /sys/kernel/debug/gpio
gpiochip0: GPIOs 0-31, parent: platform/30200000.gpio, 30200000.gpio:
 gpio-0   (                    |regulator-can1-stby ) out lo
 gpio-1   (                    |regulator-can2-stby ) out lo
 gpio-154 (                    |sysfs               ) out hi
 gpio-155 (                    |sysfs               ) out hi

......
</pre>
* List of available gpio controllers
<pre>
cd /sys/class/gpio
ls -al
total 0
drwxr-xr-x  2 root root    0 Aug 20 14:25 .
drwxr-xr-x 86 root root    0 Aug 20 14:25 ..
--w-------  1 root root 4096 Aug 20 14:25 export
lrwxrwxrwx  1 root root    0 Aug 20 14:25 gpiochip0 -> ../../devices/platform/soc@0/30000000.bus/30200000.gpio/gpio/gpiochip0
lrwxrwxrwx  1 root root    0 Aug 20 14:25 gpiochip128 -> ../../devices/platform/soc@0/30000000.bus/30240000.gpio/gpio/gpiochip128
lrwxrwxrwx  1 root root    0 Aug 20 14:25 gpiochip32 -> ../../devices/platform/soc@0/30000000.bus/30210000.gpio/gpio/gpiochip32
lrwxrwxrwx  1 root root    0 Aug 20 14:25 gpiochip496 -> ../../devices/platform/soc@0/30800000.bus/30a30000.i2c/i2c-1/1-0020/gpio/gpiochip496
lrwxrwxrwx  1 root root    0 Aug 20 14:25 gpiochip64 -> ../../devices/platform/soc@0/30000000.bus/30220000.gpio/gpio/gpiochip64
lrwxrwxrwx  1 root root    0 Aug 20 14:25 gpiochip96 -> ../../devices/platform/soc@0/30000000.bus/30230000.gpio/gpio/gpiochip96
--w-------  1 root root 4096 Aug 20 14:25 unexport
</pre>
* Export unassigned gpios
<pre>
echo 154 > export; cd gpio154
ls -al
total 0
drwxr-xr-x 3 root root    0 Aug 21 06:27 .
drwxr-xr-x 3 root root    0 Aug 21 06:27 ..
-rw-r--r-- 1 root root 4096 Aug 21 06:29 active_low
lrwxrwxrwx 1 root root    0 Aug 21 06:29 device -> ../../../gpiochip4
-rw-r--r-- 1 root root 4096 Aug 21 06:29 direction
-rw-r--r-- 1 root root 4096 Aug 21 06:29 edge
drwxr-xr-x 2 root root    0 Aug 21 06:29 power
lrwxrwxrwx 1 root root    0 Aug 21 06:29 subsystem -> ../../../../../../../../class/gpio
-rw-r--r-- 1 root root 4096 Aug 21 06:27 uevent
-rw-r--r-- 1 root root 4096 Aug 21 06:29 value
</pre>
* Change direction in/out
<pre>
echo out > direction; cat direction
</pre>
* Set/get value
<pre>
echo 1 > value ; cat value
</pre>
==== gpiolib ====
* gpiodetect
<pre>
gpiochip0 [30200000.gpio] (32 lines)
gpiochip1 [30210000.gpio] (32 lines)
gpiochip2 [30220000.gpio] (32 lines)
gpiochip3 [30230000.gpio] (32 lines)
gpiochip4 [30240000.gpio] (32 lines)
gpiochip5 [1-0020] (16 lines)
gpioinfo gpiochip0
gpiochip0 - 32 lines:
      line   0:      unnamed "regulator-can1-stby" output active-high [used]
      line   1:      unnamed "regulator-can2-stby" output active-high [used]
</pre>
-->

== SPI ==
'''Pinmux'''
<pre>
pinctrl_ecspi2: ecspi2grp {
	fsl,pins = <
		MX8MP_IOMUXC_ECSPI2_SCLK__ECSPI2_SCLK		0x82
		MX8MP_IOMUXC_ECSPI2_MOSI__ECSPI2_MOSI		0x82
		MX8MP_IOMUXC_ECSPI2_MISO__ECSPI2_MISO		0x82
	>;
};

pinctrl_ecspi2_cs: ecspi2cs {
	fsl,pins = <
		MX8MP_IOMUXC_ECSPI2_SS0__GPIO5_IO13		0x40000
	>;
};
</pre>
'''Device Node'''
<pre>
&ecspi2 {
	#address-cells = <1>;
	#size-cells = <0>;
	fsl,spi-num-chipselects = <1>;
	pinctrl-names = "default";
	pinctrl-0 = <&pinctrl_ecspi2 &pinctrl_ecspi2_cs>;
	cs-gpios = <&gpio5 13 GPIO_ACTIVE_LOW>;
	status = "okay";

	spidev1: spi@0 {
		reg = <0>;
		compatible = "rohm,dh2228fv";
		spi-max-frequency = <500000>;
	};
};
</pre>

== I2C ==
This example shows three I2C devices configured on I2C bus #2.</br>
'''Pinmux'''
<pre>
pinctrl_i2c2: i2c2grp {
	fsl,pins = <
		MX8MP_IOMUXC_I2C2_SCL__I2C2_SCL			0x400001c3
		MX8MP_IOMUXC_I2C2_SDA__I2C2_SDA			0x400001c3
	>;
};
</pre>
'''Device Node'''
<pre>
&i2c2 {
	clock-frequency = <400000>;
	pinctrl-names = "default";
	pinctrl-0 = <&pinctrl_i2c2>;
	status = "okay";

	eeprom@50 {
		compatible = "atmel,24c08";
		reg = <0x50>;
		pagesize = <16>;
	};

	eeprom@54 {
		compatible = "atmel,24c08";
		reg = <0x54>;
		pagesize = <16>;
	};

	rtc@69 {
		compatible = "ab1805";
		reg = <0x69>;
		pagesize = <16>;
		status = "okay";
	};
};
</pre>
[[Category:Yocto]]