(DT Series II) Writing specification of Device Tree

Writing specifications for devicetree

 

The writing specifications of devicetree are described in the following aspects: node, attribute, Reg, ranges, and interrupt controller.

1. Basic Elements of DTs: Nodes

The basic elements of. DTS (or its include. DTSI) are nodes and attributes. The following is an example of the concept of a node:

/ {    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 = <1>;            a-string-property = "Hello, world";        };        child-node2 {        };    };    node2 {        an-empty-property;        a-cell-property = <1 2 3 4>; /* each number (cell) is a uint32 */        child-node1 {        };    };};

1 root node "/"; the root node contains a series of child nodes, in this example, "node1" and "node2 ";

Node "node1" contains a series of sub-nodes, this example is "child-node1" and "child-node2 ";

Each node has a series of attributes. These properties may be empty, such as "an-empty-property"; may be strings, such as "a-string-property"; may be string arrays, for example, "a-string-list-property"; may be cells (consisting of u32 integers), for example, "second-child-property", may be binary, for example, "a-byte-data-property ".

The sub-node naming follows the following organizational form: <Name> [@ <unit-address>], the content in <> is mandatory, and the content in [] is optional. Name is an ASCII string used to describe the device type corresponding to the node. For example, the node name corresponding to the 3comethernet Adapter should be Ethernet rather than 3com509. If the device described by a node has an address, @ unit-address should be given. The names of multiple device nodes of the same type can be the same, as long as the unit-address is different. The Unit-address of a device is often given in the reg attribute of its corresponding node.

2. Basic Element of DTs: compatible attribute

Each device in the. DTS file has a compatible attribute, which binds the user driver to the device. The compatible attribute is a string list. The first string in the list represents the exact device represented by the node, in the form of "<manufacturer>, <model> ", the subsequent string represents other devices that are compatible. It can be said that the previous one is specific, and the latter one covers a wider range.

For example, the freescalempc8349 SOC contains a serial port device, which implements the ns16550 register interface of the National Semiconductor (nationalsemicondu. The compatible attribute of the mpc8349 serial port device is compatible = "FSL, mpc8349-uart", "ns16550 ". Among them, FSL, mpc8349-uart refers to the exact device, ns16550 represents the device and nationalsemicondu16550uart maintains register compatibility.

3. Other parts of DTs: Reg

An addressable device uses the following information to encode the address information in devicetree:

• Reg

• # Address-Cells

• # Size-Cells

The reg format is Reg = <address1 length1 [address2 leng2] [address3 length3]...>. Each group of addresslength indicates an address range used by the device. Address is one or more 32-bit integer (cell), while length is the cell list or empty (if # size-cells = 0 ). The address and length fields are variable-length. The # address-cells and # size-cells of the parent node determine the length of the address and length fields of the reg attribute of the child node.

4. other parts of DTs: ranges

Ranges is an address translation table, where each project is a child address, parent address, and ing of the size of the Child address space. The child address and parent address in the ing table use the # address-cells of the Child address space and the # address-cells of the parent address space respectively. Example:

 ranges = <0 0  0x10100000   0x10000     // Chipselect 1, Ethernet                1 0  0x10160000   0x10000     // Chipselect 2, i2c controller                2 0  0x30000000   0x1000000>; // Chipselect 3, NOR Flash

In this example, the # address-cells of the Child address space is 2, and the # address-cells value of the parent address space is 1, therefore, the first two cells of 00 0x10000000x10000 are 0 on the external-bus rear part, 3rd cells indicate that the address space with an offset of 0 after the external-bus is mapped to the 0 x 4th position of the CPU, and 10000 cells indicate that the ing size is 0 x. The meanings of the two following ranges projects can be similar.

5. other parts of DTs: Interrupt Controller

Devicetree can also interrupt the connection information. For the interrupt controller, it provides the following attributes: interrupt-controller-this attribute is empty, and the interrupt controller should add this attribute to indicate its identity; # interrupt-cells-similar to # address-cells and # size-cells, it indicates the cell size of the interrupts attribute of the device connecting to the interrupt controller.

In the entire devicetree, the interrupt-related attributes also include: interrupt-parent-the device node uses it to specify the phandle of the interrupt controller it is attached, when the node does not specify interrupt-parent, it inherits from the parent node.

Interrupts-the device node that uses the interrupt to specify the interrupt number and trigger method. How many cells are contained in this attribute, it is determined by the # interrupt-cells attribute of the interrupt controller node it is attached. The specific meaning of each cell is generally determined by the implementation of the driver, and will also be described in the binding document of devicetree. It is worth noting that a device may also use multiple interrupt numbers. In addition to interruptions, clock, gpio, and pinmux in armlinux can be described through the nodes and attributes in. DTS.

6. other parts of DTs: Notes

In addition to the above rules, DTS can also add custom attributes and subnodes, but it must comply with the following rules:

(1) The new device attributes must be prefixed with the manufacturer name, so that they can avoid conflicts with the current standard attributes;

(2) the specific meaning of the newly added attributes and the sub-nodes must be described in the document so that the device driver developer can understand how to interpret the data. The description document must specifically describe the meaning of compatible values, the attributes, the subnodes that can be included, and the devices that represent compatible. Each Independent compatible should be explained separately.

(3) the newly added items will be sent to the [email protected] email list for review, and check whether other problems will be caused in the future.

In the devicetree of a tree structure, how do I reference a node? To specify a unique node, you must use fullpath, for example,/node-name-1/node-name-2/node-name-n.

A property value identifies a device's characteristics. Its values are diverse:

1. It may be null, that is, there is no value definition. For example, in 64-bit, this attribute is not assigned a value.

2. It may be a u32 or u64 value (it is worth mentioning that the cell term represents a 32-bit unit of information in devicetree ). For example, # address-cells = <1>. Of course, it may be an array. For example, <0x000000000x00000000 0x00000000x20000000>

3. It may be a string. For example, device_type = "Memory" may also be a stringlist. For example, "PowerPC, 970"

When describing the structure of devicetree, those devices that can be detected dynamically do not need to be described, such as USB device. However, the USB Host Controller on the SOC cannot be dynamically identified and must be described in devicetree. Likewise, in computersystem, pcidevice can be dynamically detected and does not need to be described in devicetree. However, if pcibridge cannot be detected, You need to describe it.

 

(DT Series II) Writing specification of Device Tree