]>
Commit | Line | Data |
---|---|---|
bbb0b128 SG |
1 | # |
2 | # Copyright (c) 2011 The Chromium OS Authors. | |
3 | # | |
4 | # See file CREDITS for list of people who contributed to this | |
5 | # project. | |
6 | # | |
7 | # This program is free software; you can redistribute it and/or | |
8 | # modify it under the terms of the GNU General Public License as | |
9 | # published by the Free Software Foundatio; either version 2 of | |
10 | # the License, or (at your option) any later version. | |
11 | # | |
12 | # This program is distributed in the hope that it will be useful, | |
13 | # but WITHOUT ANY WARRANTY; without even the implied warranty of | |
14 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
15 | # GNU General Public License for more details. | |
16 | # | |
17 | # You should have received a copy of the GNU General Public License | |
18 | # along with this program; if not, write to the Free Software | |
19 | # Foundation, Inc., 59 Temple Place, Suite 330, Boston, | |
20 | # MA 02111-1307 USA | |
21 | # | |
22 | ||
23 | Device Tree Control in U-Boot | |
24 | ============================= | |
25 | ||
26 | This feature provides for run-time configuration of U-Boot via a flat | |
27 | device tree (fdt). U-Boot configuration has traditionally been done | |
28 | using CONFIG options in the board config file. This feature aims to | |
29 | make it possible for a single U-Boot binary to support multiple boards, | |
30 | with the exact configuration of each board controlled by a flat device | |
31 | tree (fdt). This is the approach recently taken by the ARM Linux kernel | |
32 | and has been used by PowerPC for some time. | |
33 | ||
34 | The fdt is a convenient vehicle for implementing run-time configuration | |
35 | for three reasons. Firstly it is easy to use, being a simple text file. | |
36 | It is extensible since it consists of nodes and properties in a nice | |
37 | hierarchical format. | |
38 | ||
39 | Finally, there is already excellent infrastructure for the fdt: a | |
40 | compiler checks the text file and converts it to a compact binary | |
41 | format, and a library is already available in U-Boot (libfdt) for | |
42 | handling this format. | |
43 | ||
44 | The dts directory contains a Makefile for building the device tree blob | |
45 | and embedding it in your U-Boot image. This is useful since it allows | |
46 | U-Boot to configure itself according to what it finds there. If you have | |
47 | a number of similar boards with different peripherals, you can describe | |
48 | the features of each board in the device tree file, and have a single | |
49 | generic source base. | |
50 | ||
51 | To enable this feature, add CONFIG_OF_CONTROL to your board config file. | |
52 | ||
53 | ||
54 | What is a Flat Device Tree? | |
55 | --------------------------- | |
56 | ||
57 | An fdt can be specified in source format as a text file. To read about | |
58 | the fdt syntax, take a look at the specification here: | |
59 | ||
60 | https://www.power.org/resources/downloads/Power_ePAPR_APPROVED_v1.0.pdf | |
61 | ||
62 | You also might find this section of the Linux kernel documentation | |
63 | useful: (access this in the Linux kernel source code) | |
64 | ||
65 | Documentation/devicetree/booting-without-of.txt | |
66 | ||
67 | There is also a mailing list: | |
68 | ||
69 | http://lists.ozlabs.org/listinfo/devicetree-discuss | |
70 | ||
71 | In case you are wondering, OF stands for Open Firmware. | |
72 | ||
73 | ||
74 | Tools | |
75 | ----- | |
76 | ||
77 | To use this feature you will need to get the device tree compiler here: | |
78 | ||
79 | git://jdl.com/software/dtc.git | |
80 | ||
81 | For example: | |
82 | ||
83 | $ git clone git://jdl.com/software/dtc.git | |
84 | $ cd dtc | |
85 | $ make | |
86 | $ sudo make install | |
87 | ||
88 | Then run the compiler (your version will vary): | |
89 | ||
90 | $ dtc -v | |
91 | Version: DTC 1.2.0-g2cb4b51f | |
92 | $ make tests | |
93 | $ cd tests | |
94 | $ ./run_tests.sh | |
95 | ********** TEST SUMMARY | |
96 | * Total testcases: 1371 | |
97 | * PASS: 1371 | |
98 | * FAIL: 0 | |
99 | * Bad configuration: 0 | |
100 | * Strange test result: 0 | |
101 | ||
102 | You will also find a useful ftdump utility for decoding a binary file. | |
103 | ||
104 | ||
105 | Where do I get an fdt file for my board? | |
106 | ---------------------------------------- | |
107 | ||
108 | You may find that the Linux kernel has a suitable file. Look in the | |
109 | kernel source in arch/<arch>/boot/dts. | |
110 | ||
111 | If not you might find other boards with suitable files that you can | |
112 | modify to your needs. Look in the board directories for files with a | |
113 | .dts extension. | |
114 | ||
115 | Failing that, you could write one from scratch yourself! | |
116 | ||
117 | ||
118 | Configuration | |
119 | ------------- | |
120 | ||
121 | Use: | |
122 | ||
123 | #define CONFIG_DEFAULT_DEVICE_TREE "<name>" | |
124 | ||
125 | to set the filename of the device tree source. Then put your device tree | |
126 | file into | |
127 | ||
128 | board/<vendor>/dts/<name>.dts | |
129 | ||
130 | This should include your CPU or SOC's device tree file, placed in | |
131 | arch/<arch>/dts, and then make any adjustments required. The name of this | |
132 | is CONFIG_ARCH_DEVICE_TREE.dts. | |
133 | ||
134 | If CONFIG_OF_EMBED is defined, then it will be picked up and built into | |
135 | the U-Boot image (including u-boot.bin). | |
136 | ||
137 | If CONFIG_OF_SEPARATE is defined, then it will be built and placed in | |
138 | a u-boot.dtb file alongside u-boot.bin. A common approach is then to | |
139 | join the two: | |
140 | ||
141 | cat u-boot.bin u-boot.dtb >image.bin | |
142 | ||
143 | and then flash image.bin onto your board. | |
144 | ||
145 | You cannot use both of these options at the same time. | |
146 | ||
eea63e05 SG |
147 | If you wish to put the fdt at a different address in memory, you can |
148 | define the "fdtcontroladdr" environment variable. This is the hex | |
149 | address of the fdt binary blob, and will override either of the options. | |
150 | Be aware that this environment variable is checked prior to relocation, | |
151 | when only the compiled-in environment is available. Therefore it is not | |
152 | possible to define this variable in the saved SPI/NAND flash | |
153 | environment, for example (it will be ignored). | |
154 | ||
155 | To use this, put something like this in your board header file: | |
156 | ||
157 | #define CONFIG_EXTRA_ENV_SETTINGS "fdtcontroladdr=10000\0" | |
158 | ||
bbb0b128 SG |
159 | |
160 | Limitations | |
161 | ----------- | |
162 | ||
163 | U-Boot is designed to build with a single architecture type and CPU | |
164 | type. So for example it is not possible to build a single ARM binary | |
165 | which runs on your AT91 and OMAP boards, relying on an fdt to configure | |
166 | the various features. This is because you must select one of | |
167 | the CPU families within arch/arm/cpu/arm926ejs (omap or at91) at build | |
168 | time. Similarly you cannot build for multiple cpu types or | |
169 | architectures. | |
170 | ||
171 | That said the complexity reduction by using fdt to support variants of | |
172 | boards which use the same SOC / CPU can be substantial. | |
173 | ||
174 | It is important to understand that the fdt only selects options | |
175 | available in the platform / drivers. It cannot add new drivers (yet). So | |
176 | you must still have the CONFIG option to enable the driver. For example, | |
177 | you need to define CONFIG_SYS_NS16550 to bring in the NS16550 driver, | |
178 | but can use the fdt to specific the UART clock, peripheral address, etc. | |
179 | In very broad terms, the CONFIG options in general control *what* driver | |
180 | files are pulled in, and the fdt controls *how* those files work. | |
181 | ||
182 | -- | |
183 | Simon Glass <sjg@chromium.org> | |
184 | 1-Sep-11 |