Device Tree common methods

Device Tree common methods

The use of the device tree driver in the Linux Kernel originated from an email sent by Linus Torvalds in the ARM Linux mailing list on April 9, March 17, 2011. He declared that "this whole arm thing is a f * cking pain in the ass ", we also advocate learning the Device Tree technology that has been used by other architectures such as PowerPC. Since then, Device Tree has entered the arm community's field of view.

1. Role

Device Tree is a data structure used to describe hardware. It is similar to a board-level description language and originated from openfirmware (). In Linux kernel 2.6.x, a large number of board-level descriptive codes with poor portability exist for different platforms and hardware, to meet the special adaptation requirements for these different platforms and different hardware. However, too many platforms and different hardware lead to more and more such code, which eventually leads to Linux founder Linus's dissatisfaction and a strong appeal for change. The introduction of the device tree brings great convenience to driver adaptation. A complete set of Device Tree can present a PCB to you. The device tree can describe the CPU, and can describe any existing driver units such as clock, interrupt controller, Io controller, SPI bus controller, I2C controller, and storage device. You can describe the interrupt and memory ing space of a specific device.

2. Basic data format

The Device Tree consists of nodes and attributes. The attribute is a key-value pair. A node can contain various attributes or subnodes. Below is a simple DTS file:

/ {    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 {        };    };};

This file does not actually make any sense, but contains all the basic elements:

• 1 unique root node "/"
• 2. Some nodes: node1 node2
• 3 subnode node child-node1 and child-node2 for node1
• 4. Scattered attributes

All attributes are simple key-value pairs, where value can be empty or contain any byte stream. The basic data structure of some attributes is as follows:

• 1 double quotation marks contain character information

    string-property = "a string";

• 2 cells unit information is 32-bit unsigned integer data

    cell-property = <0xFF01 412 0x12341283>;

• 3. binary data streams

    binary-property = [0x01 0x02 0x03 0x04];

• 4. Use commas to separate mixed data

    mixed-property = "a string", [0x01 0x02 0x03 0x04], <0xFF01 412 0x12341283>;

• 5 Character List

    string-list = "string test1", "string test2";

3. Some Basic Concepts

• Each Complete DTS file must have a root node
• DTSI files are generally generic files (similar to header files in C Language) and can be included by other files.
  The following name covers a wider range. If it can be matched, it will also be initialized and started based on the DTs.
• The parent node name should be the type name, not the IC name. Generally, the naming rule for a node name is [name] @ [address]. It can only contain the name but not the content after @, but ensure that the name cannot be duplicated. If @ and address are added, the name can be the same, as long as the address is different.
• Each device node must have a compatible attribute.

• The compatible content is used to match the driver. The composition is "[manufacturer], [model]", and the vendor name is added to avoid duplicate names. Sometimes a name will be followed, for example:

    compatible = "acme,coyotes-revenge", "acmd-board";

4. Working Method A. Address

The device address features are controlled based on the following attributes:

• Reg
• # Address-Cells
• # Size-Cells

Reg indicates region, region. Format:

reg = <address1 length1 [address2 length2] [address3 length3]>;

The address-cells and size-cells of the parent class determine the number of cells to be contained in the attributes of the Child class. If the child node has special requirements, you can define it by yourself, in this way, you can get rid of the control of the parent node.
Address-cells determines that address1/2/3 contains several cells. Size-cells determine that length1/2/3 contains several cells. The local module is as follows:

[email protected] {        compatible = "arm,pl022";        reg = <0x10115000 0x1000 >;};

The application address space of the SPI device located in 0x10115000. The initial address is 0x10115000 and the length is 0x1000. That is, the address range of the SPI device is 0x10115000 ~ 0x10116000.

In practical application, another scenario is to activate the module through external Chip chip selection. For example, some modules mounted on the external bus that need to work by selecting slices:

external-bus {    #address-cells = <2>    #size-cells = <1>;    [email protected],0 {        compatible = "smc,smc91c111";        reg = <0 0 0x1000>;    };    [email protected],0 {        compatible = "acme,a1234-i2c-bus";        #address-cells = <1>;        #size-cells = <0>;        reg = <1 0 0x1000>;        [email protected] {            compatible = "maxim,ds1338";            reg = <58>;        };    };    [email protected],0 {        compatible = "samsung,k8f1315ebm", "cfi-flash";        reg = <2 0 0x4000000>;    };};

External-bus uses two cells to describe the address. One is the part sequence number and the other is the offset of the part sequence number. The length of the address space is still described by a cell. Therefore, the above sub-devices all need three cells to describe the address space attributes-chip selection, offset, and address length. In the previous example, an exception is the RTC module under the I2C controller module. The I2C device is only allocated to an address and does not need any other space. Therefore, a cell with one address can be described completely without the size-cells.

When the device to be described is not a local device, you need to describe a ing from the device address space to the CPU address space.RangesAttribute. Or the external-bus of the above side:

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

The ranges attribute is an address translation table. Each row in the table contains the Child address, parent address, and region size in the Self-address space. Their size (including cells) is determined by the address-cells value of the child node, the address-cells value of the parent node, and the size-cells of the child node. Take the first behavior as an example:

• 0 0 two cells, determined by the address-cells = <2> of the child node external-bus;
• 0x10100000 a cell is determined by the address-cells = <1> of the parent node;
• 0x10000 a cell is determined by the size-cells = <1> of the child node external-bus.
  In the end, the first line indicates 0 for slice, 0 for offset (NIC selected), and 0 for CPU address space mapped to 0x10100000 ~ In 0x10110000, the address length is 0x10000.

B. interrupted

Describes the four attributes required to interrupt a connection:
1. An empty attribute of interrupt-controller is used to declare that the node receives the interrupt signal;
2. # interrupt-cells: This is the attribute of the interrupt controller node. It is used to identify the Controller that requires several units for the Interrupt Descriptor;
3. Interrupt-parent identifies the interrupt controller of the device node. If this attribute is not set, it is automatically attached to the parent node;
4. interrupts is a list of Interrupt identifiers, indicating each interrupt output signal.

If there are two, the first is the interrupt number, and the second is the interrupt type, such as triggering features such as high level, low level, and edge triggering. For a given interrupt controller, read the relevant documentation carefully to determine how to resolve the disconnection identifier.

C. Others

In addition to the above rules, you can also add custom attributes and subnodes, but 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.

5. Advanced example

[email protected] {        compatible = "arm,versatile-pci-hostbridge", "pci";        reg = <0x10180000 0x1000>;        interrupts = <8 0>;        bus-ranges = <0 0>;        #address-cells = <3>        #size-cells = <2>;        ranges = <0x42000000 0 0x80000000 0x80000000 0 0x20000000                  0x02000000 0 0xa0000000 0xa0000000 0 0x10000000                  0x01000000 0 0x00000000 0xb0000000 0 0x01000000>;};

Like the local bus described earlier, the PCI address space is completely separated from the CPU address space. Therefore, you need to define the ranges attribute for address conversion.
# Address-cells defines that PCI uses three cells, and the PCI address range can be interpreted in two units. Therefore, the first question is why we need three 32-bit cells to describe a PCI address.

These three cells represent the high, middle, and low physical addresses respectively.:

• 1 Phys. High Cell: npt000ss bbbbbbbbbb dddddfff rrrrrr
• 2 Phys. Mid cell: hhhhhhh hhhhhhhh hhhhhhh
• 3 Phys. Low cell: llllllll

The PCI address is 64-bit in width and is encoded in phys. Mid and phys. Low. What really matters is in the space Phys. High:

N: Indicates re-applying for a space flag (not used here)
P: indicates the pre-read space (cache) mark
T: alias address flag (not used here)
SS: Space Code
00: Set Space
01: Io Space
10: 32-bit storage space
11: 64-bit storage space

Bbbbbbbb: the PCI bus number. PCI may be a hierarchical architecture, so we may need to differentiate some sub-bus
Ddddd: Device number. It is usually applied for when the initialization device selects an idsel signal for connection.
Fff: function number, which may be used by some PCI devices.
Rrrrrrrr: the registration number, which is used in the set cycle.

ranges = <0x42000000 0 0x80000000 0x80000000 0 0x20000000          0x02000000 0 0xa0000000 0xa0000000 0 0x10000000          0x01000000 0 0x00000000 0xb0000000 0 0x01000000>;

Let's look back at what this ranges sub-table represents. The parent node address-cells is 1, the child node address-cells is 3, and the child node size-cells is 2. The first line can be divided as follows:

0x42000000 0 0x80000000 subnode address | 0x80000000 parent node address | 0 0x20000000 address space length |

0x42000000 is Phys. High, the first is 01000010, then P is 1, SS is 10, that is, the 32-bit storage space is requested as the cache space. Phys. mid is 0, Phys. low is 0x80000000, which together form a PCI address, that is, a 32-bit storage space is requested from the 0x80000000 address of the PCI bus as the cache. The cell 0x80000000 0 0x20000000 behind represents the parameter after the CPU space. The requested address is mapped to the 0x80000000 address of the CPU space. The total size is 0x20000000 (512 MB ).

Device Tree common methods