http://devicetree.org/Device_Tree_Usage
Device Tree Usage
From FDTWiki
Sighted
page [view draft]
(+/-)
This is the
latest sighted
revision, approved on 12 June 2010.
The draft has 21 changes awaiting review.
Accuracy
Sighted
Depth
Basic
Readability
Acceptable
Jump to: navigation,
search
This
page walks through how to write a device tree for a new machine. For a
full technical description of device tree data format, refer to the ePAPR
specification. The ePAPR specification covers a lot more detail than
the basic topics covered on this page, please refer to it for more
advanced usage that isn't covered by this page.
Contents
[hide]
1 Basic Data Format
2 Basic Concepts
2.1 Sample Machine
2.2 Initial structure
2.3 CPUs
2.4 Node Names
2.5 Devices
2.6 Understanding the
compatible Property
3 How Addressing Works
3.1 CPU addressing
3.2 Memory Mapped
Devices
3.3 Non Memory Mapped
Devices
3.4 Ranges (Address
Translation)
4 How Interrupts Work
5 Device Specific Data
6 Special Nodes
6.1 aliases Node
6.2 chosen Node
Basic Data Format
The device tree is a simple tree structure of nodes and properties.
Properties are key-value pairs, and node may contain both properties
and child nodes. For example, the following is a simple tree in the .dts
format:
/ {
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 tree is obviously pretty useless because it doesn't describe
anything, but it does show the structure of nodes an properties. There
is:
a single root node: "/"
a couple of child nodes: "node1" and "node2"
a couple of children for node1: "child-node1" and "child-node2"
a bunch of properties scattered through the tree.
Basic Concepts
To understand how the device tree is used, we will start with a
simple machine and build up a device tree to describe it step by step.
Sample Machine
Consider the following imaginary machine (loosely based on ARM
Versatile), manufactured by "Acme" and named "Coyote's Revenge":
One 32bit ARM CPU
processor local bus attached to memory mapped serial port,
spi bus controller, i2c controller, interrupt controller, and external
bus bridge
256MB of SDRAM based at 0
2 Serial ports based at 0x101F1000 and 0x101F2000
GPIO controller based at 0x101F3000
SPI controller based at 0x1017 with following devices
MMC slot with SS pin attached to GPIO #1
External bus bridge with following devices
SMC SMC9 Ethernet device attached to external bus based
at 0x1010
i2c controller based at 0x1016 with following devices
Maxim DS1338 real time clock. Responds to slave address
1101000 (0x58)
64MB of NOR flash based at 0x3000
Initial structure
The first step is to lay down a skeleton structure for the machine.
This is the bare minimum structure required for a valid device tree. At
this stage you want to uniquely identify the machine.
/ {
compatible = "acme,coyotes-revenge";
};
compatible specifies the name of the system. It
contains a string in the form "manufacturer,model. It
is important to specify the exact device, and to include the
manufacturer name to avoid namespace collisions. Since the operating
system will use the compatible value to make decisions
about how to run on the machine, it is very important to put correct
data into this property.
Theoretically, compatible is all the data an OS needs to
uniquely identify a machine. If all the machine details are hard coded,
then the OS could look specifically for "acme,coyotes-revenge" in the
top level compatible property.
CPUs
Next step is to describe for each of the CPUs. A container node
named "cpus" is added with a child node for each CPU. In this case the
system is a dual-core Cortex A9 system
