Follow and star Baiwen Technology

Embedded essentials delivered promptly

———-

Last week, I published an article on the background knowledge of Device Trees, and many colleagues in the background requested a deeper analysis of the code. Today, we will discuss the knowledge related to DTS scripts and the loading process. The article is a bit long, so it’s recommended to save it first.

Author: RadianceBlau

Source:

https://blog.csdn.net/radianceblau/article/details/70800076

1. The Loading Process of DTS

To use the Device Tree, users must first understand their hardware configuration and system operating parameters, and organize this information into a Device Tree source file. Using DTC (Device Tree Compiler), this human-readable Device Tree source file can be transformed into a machine-readable Device Tree binary file (device tree blob).

During system startup, the boot program (e.g., firmware, bootloader) can copy the DTB saved in flash to memory (it can also be loaded through other means, such as interactive commands from the bootloader, or the firmware can detect device information and organize it into a DTB saved in memory), and pass the starting address of the DTB to the client program (e.g., OS kernel, bootloader, or other special function programs).

For computer systems, the general order is firmware -> bootloader -> OS, while for embedded systems, it is generally bootloader -> OS.

2. The Description Information of DTS

The Device Tree consists of a series of named nodes and properties, and nodes can contain child nodes.

Properties are essentially pairs of name and value.

The information that can be described in the Device Tree includes (previously, most of this information was hard-coded into the kernel):

Number and type of CPUs
Base address and size of memory
Buses and bridges
Peripheral connections
Interrupt controllers and interrupt usage
GPIO controllers and GPIO usage
Clock controllers and clock usage

It essentially depicts a tree of the CPU, buses, and devices on the circuit board. The Bootloader will pass this tree to the kernel, which can then recognize the tree and expand it into platform_device, i2c_client, spi_device, etc., in the Linux kernel. The memory, IRQ, and other resources used by these devices are also passed to the kernel, which binds these resources to the corresponding expanded devices.

Does the Device Tree need to describe all hardware information in the system? The answer is no. Generally, it does not need to describe devices that can be dynamically detected, such as USB devices. However, for the USB host controller on the SoC, it cannot be dynamically identified and needs to be described in the device tree.

Similarly, in a computer system, PCI devices can be dynamically detected and do not need to be described in the device tree, but if a PCI bridge cannot be detected, it needs to be described.

.dts files are an ASCII text format for Device Tree descriptions, and this text format is very user-friendly, suitable for human reading habits.

Basically, in ARM Linux, a .dts file corresponds to one ARM machine and is generally placed in the kernel’s arch/arm/boot/dts/ directory.

Since one SoC may correspond to multiple machines (one SoC can correspond to multiple products and circuit boards), these .dts files inevitably contain many common parts. To simplify this, the Linux kernel generally extracts the common parts of the SoC or multiple machines into .dtsi files, similar to C language header files. Other .dts files corresponding to different machines can include this .dtsi.

For example, for RK3288, rk3288.dtsi is referenced by rk3288-chrome.dts, which contains the following line: #include “rk3288.dtsi”.

Similarly, for rtd1195, rtd-119x-nas.dts includes /include/ “rtd-119x.dtsi”.

Of course, like C language header files, .dtsi files can also include other .dtsi files. For instance, almost all ARM SoCs’ .dtsi files reference skeleton.dtsi, i.e., #include “skeleton.dtsi”.

Or /include/ “skeleton.dtsi”

Under normal circumstances, all .dts files and .dtsi files contain a root node “/”, so that after including, there will be many root nodes. Logically, since the device tree is a tree, it should only have one root node, and all other nodes are child nodes derived from the root node.

Actually, the Device Tree Compiler will merge the nodes of the DTS, and the final generated DTB will only have one root node.

The basic unit of the device tree is the node. These nodes are organized into a tree structure, and except for the root node, each node has only one parent. A device tree file can only have one root node. Each node contains several properties/values that describe some characteristics of that node.

Each node is identified by its node name (node name), and the format of the node name is node-name@unit-address.

If the node does not have a reg property (which will be described later), then the node name must not include @ and unit-address. The specific format of unit-address is related to which bus the device is connected to. For example, for CPUs, the unit-address is addressed starting from 0 and incrementing.

Specific devices, such as Ethernet controllers, have their unit-address as the register address. The root node’s node name is fixed and must be “/”.

In a hierarchical device tree, how do you reference a node? To uniquely specify a node, you must use the full path, for example, /node-name-1/node-name-2/node-name-N.

3. The Composition Structure of DTS

 {
	node1 {
		a-string-property = "A string";
		a-string-list-property = "first string", "second string";
		a-byte-data-property = [0x01 0x23 0x34 0x56];
		child-node1 {
			first-child-property;
			second-child-property = &lt;1&gt;;
			a-string-property = "Hello, world";
		};
		child-node2 {
		};
	};
	node2 {
		an-empty-property;
		a-cell-property = &lt;1 2 3 4&gt;; /* each number (cell) is a uint32 */  
		child-node1 {
		};
	};
};

The above .dts file does not have any real use, but it essentially represents the structure of a Device Tree source file: 1. One root node “/”;

2. The root node contains a series of child nodes, in this case, “node1” and “node2”;

3. The node “node1” contains a series of child nodes, in this case, “child-node1” and “child-node2”;

4. Each node has a series of properties. These properties may be empty, such as “an-empty-property”; may be strings, such as “a-string-property”; may be string arrays, such as “a-string-list-property”; may be Cells (composed of u32 integers), such as “second-child-property”; or may be binary numbers, such as “a-byte-data-property”.

Now, let’s look at how to write a .dts file for the simplest machine. Suppose the configuration of this machine is as follows: 1. One dual-core ARM Cortex-A9 32-bit processor;

2. The memory-mapped area on the ARM local bus has 2 serial ports (located at 0x101F1000 and 0x101F2000), a GPIO controller (located at 0x101F3000), an SPI controller (located at 0x10115000), an interrupt controller (located at 0x10140000), and an external bus bridge;

3. The external bus bridge connects to an SMC SMC91111 Ethernet (located at 0x10100000), an I2C controller (located at 0x10160000), and 64MB NOR Flash (located at 0x30000000);

4. The I2C controller connected to the external bus bridge has a Maxim DS1338 real-time clock (I2C address 0x58) connected to its I2C bus.

The corresponding .dts file is as follows:

 {
	compatible = "acme,coyotes-revenge";
	#address-cells = &lt;1&gt;;  
	#size-cells = &lt;1&gt;;  
	interrupt-parent = &lt;&amp;intc&gt;;


	cpus {
		#address-cells = &lt;1&gt;;  
		#size-cells = &lt;0&gt;;  
		cpu@0 {
			compatible = "arm,cortex-a9";
			reg = &lt;0&gt;;
		};
		cpu@1 {
			compatible = "arm,cortex-a9";
			reg = &lt;1&gt;;
		};
	};


	serial@101f0000 {
		compatible = "arm,pl011";
		reg = &lt;0x101f0000 0x1000 &gt;;
		interrupts = &lt; 1 0 &gt;;
	};


	serial@101f2000 {
		compatible = "arm,pl011";
		reg = &lt;0x101f2000 0x1000 &gt;;
		interrupts = &lt; 2 0 &gt;;
	};



	gpio@101f3000 {
		compatible = "arm,pl061";
		reg = &lt;0x101f3000 0x1000  
					0x101f4000 0x0010&gt;;
		interrupts = &lt; 3 0 &gt;;
	};


	intc: interrupt-controller@10140000 {
		compatible = "arm,pl190";
		reg = &lt;0x10140000 0x1000 &gt;;
		interrupt-controller;
		#interrupt-cells = &lt;2&gt;;  
	};


	spi@10115000 {
		compatible = "arm,pl022";
		reg = &lt;0x10115000 0x1000 &gt;;
		interrupts = &lt; 4 0 &gt;;
	};



	external-bus {
		#address-cells = &lt;2&gt;  
		#size-cells = &lt;1&gt;;  
		ranges = &lt;0 0  0x10100000   0x10000     // Chipselect 1, Ethernet  
							1 0  0x10160000   0x10000     // Chipselect 2, i2c controller  
							2 0  0x30000000   0x1000000&gt;; // Chipselect 3, NOR Flash  


			ethernet@0,0 {
				compatible = "smc,smc91c111";
				reg = &lt;0 0 0x1000&gt;;
				interrupts = &lt; 5 2 &gt;;
			};


		i2c@1,0 {
			compatible = "acme,a1234-i2c-bus";
			#address-cells = &lt;1&gt;;  
			#size-cells = &lt;0&gt;;  
			reg = &lt;1 0 0x1000&gt;;
			rtc@58 {
				compatible = "maxim,ds1338";
				reg = &lt;58&gt;;
				interrupts = &lt; 7 3 &gt;;
			};
		};


		flash@2,0 {
			compatible = "samsung,k8f1315ebm", "cfi-flash";
			reg = &lt;2 0 0x4000000&gt;;
		};
	};
};

The compatible property of the root node “/” in the above .dts file is compatible = “acme,coyotes-revenge”; which defines the name of the system, organized in the format: ,.

The Linux kernel can determine what machine it is starting through the compatible property of the root node “/”.

In each device of the .dts file, there is a compatible property, which is used for binding the driver and the device. The compatible property is a list of strings, where the first string represents the exact device represented by the node, in the form of “,“, and the subsequent strings represent other compatible devices. It can be said that the former is specific, while the latter covers a broader range.

For example, in the Flash node in arch/arm/boot/dts/vexpress-v2m.dtsi:

flash@0,00000000 {
	compatible = "arm,vexpress-flash", "cfi-flash";
	reg = &lt;0 0x00000000 0x04000000&gt;,
	&lt;1 0x00000000 0x04000000&gt;;
	bank-width = &lt;4&gt;;
};

The second string “cfi-flash” in the compatible property obviously covers a broader range than the first string “arm,vexpress-flash”.

Next, the cpus child node under the root node “/” contains 2 cpu child nodes, describing the 2 CPUs on this machine, and both have the compatible property as “arm,cortex-a9”.

Note: The naming of cpus and the 2 cpu child nodes follows the organizational format: [@], where is a mandatory item and [] is optional. The name is an ASCII string used to describe the type of device corresponding to the node, such as the node name for a 3com Ethernet adapter should be “ethernet”, not “3com509”.

If a node describes a device with an address, the @unit-address should be provided. Multiple nodes of the same type can have the same name as long as the unit-address is different, as in this case with cpu@0, cpu@1, and serial@101f0000 and serial@101f2000.

The reg structure is reg = <address1 length1 [address2 length2][address3 length3] … >, where each address-length pair indicates an address range used by the device. The address is one or more 32-bit integers (i.e., cells), and length is a list of cells or empty (if #size-cells = 0).

The address and length fields are variable in length, and the parent node’s #address-cells and #size-cells determine the lengths of the address and length fields in the child node’s reg property.

In this example, the root node’s #address-cells = <1>; and #size-cells = <1>; determine that the address and length fields of the nodes serial, gpio, spi, etc. are all 1.

The cpus node’s #address-cells = <1>, and #size-cells = <0> determine that the address of the 2 cpu child nodes is 1, while the length is empty, resulting in the 2 cpus having reg = <0> and reg = <1>;

The external-bus node’s #address-cells = <2> and #size-cells = <1>; determine that the reg fields of ethernet, i2c, flash under it are structured as reg = <0 00×1000>; reg = <1 00×1000>; and reg = <2 00×4000000>;

Here, the address field length is 0, the first cell (0, 1, 2) corresponds to the chip select, the second cell (0, 0, 0) is the base address relative to that chip select, and the third cell (0x1000, 0x1000, 0x4000000) is the length.

Special attention should be paid to the #address-cells = <1> and #size-cells = <0> defined in the i2c node, which also applies to the RTC connected to the I2C bus, where its address field is 0x58, which is the device’s I2C address.

The child nodes of the root node describe the view of the CPU, so the address area of the root child nodes is directly located in the CPU’s memory area. However, the address after the bus bridge often needs to be converted to correspond to the CPU’s memory mapping.

The ranges property of the external-bus node defines how the address range after the external-bus bridge maps to the CPU’s memory area.

ranges = <0 0 0x10100000 0x10000 // Chipselect 1, Ethernet

1 0 0x10160000 0x10000 // Chipselect 2, i2c controller

2 0 0x30000000 0x1000000>; // Chipselect 3, NOR Flash

Ranges is an address translation table, where each entry is a mapping of a sub-address, parent address, and size in the sub-address space. The sub-address and parent address in the mapping table use the sizes of #address-cells from the sub-address space and parent address space respectively.

In this example, the sub-address space’s #address-cells is 2, and the parent address space’s #address-cells value is 1, so the first 2 cells of 0 0 0x10100000 0x10000 indicate the offset of chip select 0 in the external-bus, the third cell indicates that the address space offset of chip select 0 in the external-bus is mapped to the CPU’s 0x10100000 position, and the fourth cell indicates the size of the mapping is 0x10000. The meanings of the last 2 entries in the ranges can be inferred similarly.

The Device Tree can also contain interrupt connection information. For interrupt controllers, it provides the following properties: interrupt-controller – this property is empty, and the interrupt controller should add this property to indicate its identity; #interrupt-cells – similar to #address-cells and #size-cells, it indicates the cell size of the interrupts property of devices connected to this interrupt controller.

In the entire Device Tree, interrupt-related properties also include: interrupt-parent – device nodes specify the phandle of the interrupt controller they are attached to through this property. When a node does not specify interrupt-parent, it inherits from the parent node.

In this example, the root node specifies interrupt-parent= <&intc>; corresponding to intc: interrupt-controller@10140000, and since the root node’s child nodes do not specify interrupt-parent, they all inherit intc, which is located at 0x10140000, the interrupt controller.

Interrupts – devices that use interrupts specify interrupt numbers, trigger methods, etc., through this property. The number of cells contained in this property is determined by the #interrupt-cells property of the interrupt controller node it is attached to. The specific meaning of each cell is generally determined by the implementation of the driver and will also be specified in the Device Tree binding documentation.

For example, for the ARM GIC interrupt controller, #interrupt-cells is 3, and the specific meanings of the 3 cells are described in kernel/Documentation/devicetree/bindings/arm/gic.txt:

PPI(Private peripheral interrupt) SPI(Shared peripheral interrupt)

A device may also use multiple interrupt numbers. For ARM GIC, if a device uses SPI interrupt numbers 168 and 169, both are level-triggered, the device node’s interrupts property can be defined as: interrupts =<0 168 4>, <0 169 4>;

4. Changes in BSP and Drivers Caused by DTS

BSP and drivers before using DTS

Drivers after using DTS

Regarding the above DTS, note the following points:

(1) rtk_gpio_ctl_mlk is the name of the node, which can be defined arbitrarily, but it is best to be self-explanatory. You can print the currently used device tree node through the driver program.

printk(“now dts node name is %s\n”, pdev->dev.of_node->name);

(2). The compatible option is used to match with the compatible field in the of_device_id structure pointed to by the of_match_table pointer in the driver program. Only when the name in the compatible field of the DTS matches the name in the compatible field of the of_device_id in the driver program can the driver enter the probe function.

(3) For the gpios field, first, &rtk_iso_gpio indicates that this GPIO is connected to rtk_iso_gpio. The number 8 is the GPIO number offset, based on rtk_iso_gpiobase. The next field indicates that the currently configured GPIO number is set to input (0) or output (1), and the last field (1) indicates that this GPIO defaults to high (0 indicates low).

(4) If the driver only uses the compatible field to match and enter the probe function, then the gpios field is not required. However, if the driver uses methods related to the device tree to operate and obtain the GPIO number, then the gpios field must be used. The gpios field is named by default by the of_get_gpio_flags function.

The function to obtain the GPIO number is as follows:

of_get_named_gpio_flags()

of_get_gpio_flags()

Register i2c_board_info, specify IRQ and other board-level information.

In the form:

static struct i2c_board_info __initdata afeb9260_i2c_devices[] = {
	{
		I2C_BOARD_INFO("tlv320aic23", 0x1a),
	}, {
		I2C_BOARD_INFO("fm3130", 0x68),
	}, {
		I2C_BOARD_INFO("24c64", 0x50),
	}
};

Such i2c_board_info code is no longer needed. Now, you just need to fill in the devices tlv320aic23, fm3130, 24c64 as child nodes of the corresponding I2C controller nodes, similar to the previous example.

i2c@1,0 {
	compatible = "acme,a1234-i2c-bus";
	…
	rtc@58 {
		compatible = "maxim,ds1338";
		reg = &lt;58&gt;;
		interrupts = &lt; 7 3 &gt;;
	};
};

The I2C client in the Device Tree will automatically expand through the probe() function of the I2C host driver by calling of_i2c_register_devices(&i2c_dev->adapter);.

5. Common DTS Functions

Currently, all DTS-related functions in the Linux kernel start with the prefix of_ and are implemented in the kernel source code under drivers/of.

void __iomem*of_iomap(struct device_node *node, int index)

This function directly performs ioremap() on the memory region of the device node, where index is the index of the memory segment. If the device node’s reg property has multiple segments, the index indicates which segment to ioremap; if there is only one segment, index is 0.

After adopting the Device Tree, a large number of device drivers map through of_iomap() rather than the traditional ioremap.

int of_get_named_gpio_flags(struct device_node *np,const char *propname,

int index, enum of_gpio_flags *flags)

static inline int of_get_gpio_flags(structdevice_node *np, int index,

enum of_gpio_flags *flags)

{

return of_get_named_gpio_flags(np, “gpios”, index,flags);

}

This function reads the GPIO configuration number and flags from the device tree, returning the GPIO number.

6. DTC (Device Tree Compiler)

This tool compiles .dts into .dtb. The source code of DTC is located in the kernel’s scripts/dtc directory. When the Linux kernel enables Device Tree, the host tool dtc will be compiled, corresponding to the “hostprogs-y := dtc” target in scripts/dtc/Makefile.

The Makefile in arch/arm/boot/dts in the Linux kernel describes which .dtb files will be compiled when a certain SoC is selected. For example, the .dtb files corresponding to VEXPRESS include:

dtb-$(CONFIG_ARCH_VEXPRESS) += vexpress-v2p-ca5s.dtb \
vexpress-v2p-ca9.dtb \
vexpress-v2p-ca15-tc1.dtb \
vexpress-v2p-ca15_a7.dtb \
xenvm-4.2.dtb

When we run make dtbs in the Linux kernel, if we previously selected ARCH_VEXPRESS, the above .dtb files will be compiled from the corresponding .dts. This is because arch/arm/Makefile contains a dtbs compile target. Of course, Device Tree files can also be compiled separately. The command can be found by the reader themselves.

—end—

We have organized all the essential technical articles into a directory. If you reply “Directory” in this public account’s dialog box, I will send it to you.

Detailed Explanation of Device Trees (Part 2)

WeChat/Phone: 13266630429, Verification: Public Account

I will invite you to join the Weidongshan WeChat group, with limited spots, provided you have purchased a product.