Simon Glass | ac35c2f | 2021-08-01 18:57:10 -0600 | [diff] [blame] | 1 | .. SPDX-License-Identifier: GPL-2.0+ |
| 2 | .. sectionauthor:: Copyright 2011 The Chromium OS Authors |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 3 | |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 4 | Devicetree Control in U-Boot |
| 5 | ============================ |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 6 | |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 7 | This feature provides for run-time configuration of U-Boot via a flattened |
| 8 | devicetree (fdt). |
| 9 | |
| 10 | This feature aims to make it possible for a single U-Boot binary to support |
| 11 | multiple boards, with the exact configuration of each board controlled by |
| 12 | a flattened devicetree (fdt). This is the approach taken by Linux kernel for |
| 13 | ARM and RISC-V and has been used by PowerPC for some time. |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 14 | |
| 15 | The fdt is a convenient vehicle for implementing run-time configuration |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 16 | for three reasons: |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 17 | |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 18 | - There is already excellent infrastructure for the fdt: a compiler checks |
| 19 | the text file and converts it to a compact binary format, and a library |
| 20 | is already available in U-Boot (libfdt) for handling this format |
| 21 | - It is extensible since it consists of nodes and properties in a nice |
| 22 | hierarchical format |
| 23 | - It is fairly efficient to read incrementally |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 24 | |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 25 | The arch/<arch>/dts directories contains a Makefile for building the devicetree |
| 26 | blob and embedding it in the U-Boot image. This is useful since it allows |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 27 | U-Boot to configure itself according to what it finds there. If you have |
| 28 | a number of similar boards with different peripherals, you can describe |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 29 | the features of each board in the devicetree file, and have a single |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 30 | generic source base. |
| 31 | |
| 32 | To enable this feature, add CONFIG_OF_CONTROL to your board config file. |
| 33 | |
| 34 | |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 35 | What is a Flattened Devicetree? |
| 36 | ------------------------------- |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 37 | |
| 38 | An fdt can be specified in source format as a text file. To read about |
Simon Glass | ac35c2f | 2021-08-01 18:57:10 -0600 | [diff] [blame] | 39 | the fdt syntax, take a look at the specification (dtspec_). |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 40 | |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 41 | There is also a mailing list (dtlist_) for the compiler and associated |
| 42 | tools. |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 43 | |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 44 | In case you are wondering, OF stands for Open Firmware. This follows the |
| 45 | convention used in Linux. |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 46 | |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 47 | |
| 48 | Tools |
| 49 | ----- |
| 50 | |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 51 | To create flattened device trees the device tree compiler is used. This is |
Simon Glass | 9665f19 | 2018-10-01 12:22:16 -0600 | [diff] [blame] | 52 | provided by U-Boot automatically. If you have a system version of dtc |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 53 | (typically in the 'device-tree-compiler' package), that system version is |
| 54 | currently not used. |
Simon Glass | 9665f19 | 2018-10-01 12:22:16 -0600 | [diff] [blame] | 55 | |
Simon Glass | ac35c2f | 2021-08-01 18:57:10 -0600 | [diff] [blame] | 56 | If you want to build your own dtc, it is kept here:: |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 57 | |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 58 | git://git.kernel.org/pub/scm/utils/dtc/dtc.git |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 59 | |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 60 | You can decode a binary file with:: |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 61 | |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 62 | dtc -I dtb -O dts <filename.dtb> |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 63 | |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 64 | That repo also includes `fdtget`/`fdtput` for reading and writing properties in |
| 65 | a binary file. U-Boot adds its own `fdtgrep` for creating subsets of the file. |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 66 | |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 67 | |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 68 | Where do I get a devicetree file for my board? |
| 69 | ---------------------------------------------- |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 70 | |
| 71 | You may find that the Linux kernel has a suitable file. Look in the |
| 72 | kernel source in arch/<arch>/boot/dts. |
| 73 | |
| 74 | If not you might find other boards with suitable files that you can |
| 75 | modify to your needs. Look in the board directories for files with a |
| 76 | .dts extension. |
| 77 | |
| 78 | Failing that, you could write one from scratch yourself! |
| 79 | |
| 80 | |
| 81 | Configuration |
| 82 | ------------- |
| 83 | |
Simon Glass | ac35c2f | 2021-08-01 18:57:10 -0600 | [diff] [blame] | 84 | Use:: |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 85 | |
Simon Glass | ac35c2f | 2021-08-01 18:57:10 -0600 | [diff] [blame] | 86 | #define CONFIG_DEFAULT_DEVICE_TREE "<name>" |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 87 | |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 88 | to set the filename of the devicetree source. Then put your devicetree |
Simon Glass | ac35c2f | 2021-08-01 18:57:10 -0600 | [diff] [blame] | 89 | file into:: |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 90 | |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 91 | arch/<arch>/dts/<name>.dts |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 92 | |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 93 | This should include your CPU or SOC's devicetree file, placed in |
| 94 | `arch/<arch>/dts`, and then make any adjustments required using a u-boot-dtsi |
| 95 | file for your board. |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 96 | |
| 97 | If CONFIG_OF_EMBED is defined, then it will be picked up and built into |
Simon Glass | 67bce6b | 2014-06-02 22:04:50 -0600 | [diff] [blame] | 98 | the U-Boot image (including u-boot.bin). This is suitable for debugging |
| 99 | and development only and is not recommended for production devices. |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 100 | |
| 101 | If CONFIG_OF_SEPARATE is defined, then it will be built and placed in |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 102 | a u-boot.dtb file alongside u-boot-nodtb.bin with the combined result placed |
| 103 | in u-boot.bin so you can still just flash u-boot,bin onto your board. If you are |
| 104 | using CONFIG_SPL_FRAMEWORK, then u-boot.img will be built to include the device |
Simon Glass | 67bce6b | 2014-06-02 22:04:50 -0600 | [diff] [blame] | 105 | tree binary. |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 106 | |
Alex Deymo | 5b661ec | 2017-04-02 01:25:20 -0700 | [diff] [blame] | 107 | If CONFIG_OF_BOARD is defined, a board-specific routine will provide the |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 108 | devicetree at runtime, for example if an earlier bootloader stage creates |
Alex Deymo | 5b661ec | 2017-04-02 01:25:20 -0700 | [diff] [blame] | 109 | it and passes it to U-Boot. |
| 110 | |
Simon Glass | 1539343 | 2013-04-20 08:42:41 +0000 | [diff] [blame] | 111 | If CONFIG_OF_HOSTFILE is defined, then it will be read from a file on |
| 112 | startup. This is only useful for sandbox. Use the -d flag to U-Boot to |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 113 | specify the file to read, -D for the default and -T for the test devicetree, |
| 114 | used to run sandbox unit tests. |
Simon Glass | 1539343 | 2013-04-20 08:42:41 +0000 | [diff] [blame] | 115 | |
| 116 | You cannot use more than one of these options at the same time. |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 117 | |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 118 | To use a devicetree file that you have compiled yourself, pass |
Simon Glass | ac35c2f | 2021-08-01 18:57:10 -0600 | [diff] [blame] | 119 | EXT_DTB=<filename> to 'make', as in:: |
Simon Glass | 67bce6b | 2014-06-02 22:04:50 -0600 | [diff] [blame] | 120 | |
Simon Glass | ac35c2f | 2021-08-01 18:57:10 -0600 | [diff] [blame] | 121 | make EXT_DTB=boot/am335x-boneblack-pubkey.dtb |
Simon Glass | 67bce6b | 2014-06-02 22:04:50 -0600 | [diff] [blame] | 122 | |
| 123 | Then U-Boot will copy that file to u-boot.dtb, put it in the .img file |
| 124 | if used, and u-boot-dtb.bin. |
| 125 | |
Simon Glass | dc6fa64 | 2011-10-24 19:15:34 +0000 | [diff] [blame] | 126 | If you wish to put the fdt at a different address in memory, you can |
| 127 | define the "fdtcontroladdr" environment variable. This is the hex |
| 128 | address of the fdt binary blob, and will override either of the options. |
| 129 | Be aware that this environment variable is checked prior to relocation, |
| 130 | when only the compiled-in environment is available. Therefore it is not |
| 131 | possible to define this variable in the saved SPI/NAND flash |
Thomas Chou | 4fda281 | 2015-10-16 08:44:51 +0800 | [diff] [blame] | 132 | environment, for example (it will be ignored). After relocation, this |
| 133 | variable will be set to the address of the newly relocated fdt blob. |
| 134 | It is read-only and cannot be changed. It can optionally be used to |
| 135 | control the boot process of Linux with bootm/bootz commands. |
Simon Glass | dc6fa64 | 2011-10-24 19:15:34 +0000 | [diff] [blame] | 136 | |
Simon Glass | ac35c2f | 2021-08-01 18:57:10 -0600 | [diff] [blame] | 137 | To use this, put something like this in your board header file:: |
Simon Glass | dc6fa64 | 2011-10-24 19:15:34 +0000 | [diff] [blame] | 138 | |
Simon Glass | ac35c2f | 2021-08-01 18:57:10 -0600 | [diff] [blame] | 139 | #define CONFIG_EXTRA_ENV_SETTINGS "fdtcontroladdr=10000\0" |
Simon Glass | dc6fa64 | 2011-10-24 19:15:34 +0000 | [diff] [blame] | 140 | |
Jagannadha Sutradharudu Teki | 79e63a4 | 2013-02-28 10:20:18 +0000 | [diff] [blame] | 141 | Build: |
| 142 | |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 143 | After the board configuration is done, fdt supported u-boot can be built in two |
Simon Glass | ac35c2f | 2021-08-01 18:57:10 -0600 | [diff] [blame] | 144 | ways: |
| 145 | |
| 146 | # build the default dts which is defined from CONFIG_DEFAULT_DEVICE_TREE:: |
| 147 | |
Jagannadha Sutradharudu Teki | 79e63a4 | 2013-02-28 10:20:18 +0000 | [diff] [blame] | 148 | $ make |
Simon Glass | ac35c2f | 2021-08-01 18:57:10 -0600 | [diff] [blame] | 149 | |
| 150 | # build the user specified dts file:: |
| 151 | |
Jagannadha Sutradharudu Teki | 79e63a4 | 2013-02-28 10:20:18 +0000 | [diff] [blame] | 152 | $ make DEVICE_TREE=<dts-file-name> |
| 153 | |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 154 | |
| 155 | Adding tweaks for U-Boot |
| 156 | ------------------------ |
| 157 | |
| 158 | It is strongly recommended that devicetree files in U-Boot are an exact copy of |
| 159 | those in Linux, so that it is easy to sync them up from time to time. |
| 160 | |
| 161 | U-Boot is of course a very different project from Linux, e.g. it operates under |
| 162 | much more restrictive memory and code-size constraints. Where Linux may use a |
| 163 | full clock driver with Common Clock Format (CCF) to find the input clock to the |
| 164 | UART, U-Boot typically wants to output a banner as early as possible before too |
| 165 | much code has run. |
| 166 | |
| 167 | A second difference is that U-Boot includes different phases. For SPL, |
| 168 | constraints are even more extreme and the devicetree is shrunk to remove |
| 169 | unwanted nodes, or even turned into C code to avoid access overhead. |
| 170 | |
| 171 | U-Boot automatically looks for and includes a file with updates to the standard |
| 172 | devicetree for your board, searching for them in the same directory as the |
| 173 | main file, in this order:: |
| 174 | |
| 175 | <orig_filename>-u-boot.dtsi |
| 176 | <CONFIG_SYS_SOC>-u-boot.dtsi |
| 177 | <CONFIG_SYS_CPU>-u-boot.dtsi |
| 178 | <CONFIG_SYS_VENDOR>-u-boot.dtsi |
| 179 | u-boot.dtsi |
| 180 | |
| 181 | Only one of these is selected but of course you can #include another one within |
| 182 | that file, to create a hierarchy of shared files. |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 183 | |
Simon Glass | a31dc3d | 2018-10-01 12:22:17 -0600 | [diff] [blame] | 184 | Relocation, SPL and TPL |
| 185 | ----------------------- |
| 186 | |
| 187 | U-Boot can be divided into three phases: TPL, SPL and U-Boot proper. |
| 188 | |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 189 | The full devicetree is available to U-Boot proper, but normally only a subset |
Simon Glass | a31dc3d | 2018-10-01 12:22:17 -0600 | [diff] [blame] | 190 | (or none at all) is available to TPL and SPL. See 'Pre-Relocation Support' and |
Heinrich Schuchardt | c79f03c | 2020-02-25 21:35:39 +0100 | [diff] [blame] | 191 | 'SPL Support' in doc/driver-model/design.rst for more details. |
Simon Glass | a31dc3d | 2018-10-01 12:22:17 -0600 | [diff] [blame] | 192 | |
| 193 | |
Jean-Jacques Hiblot | 7c530e3 | 2018-12-07 14:50:52 +0100 | [diff] [blame] | 194 | Using several DTBs in the SPL (CONFIG_SPL_MULTI_DTB) |
| 195 | ---------------------------------------------------- |
| 196 | In some rare cases it is desirable to let SPL be able to select one DTB among |
| 197 | many. This usually not very useful as the DTB for the SPL is small and usually |
| 198 | fits several platforms. However the DTB sometimes include information that do |
| 199 | work on several platforms (like IO tuning parameters). |
| 200 | In this case it is possible to use CONFIG_SPL_MULTI_DTB. This option appends to |
| 201 | the SPL a FIT image containing several DTBs listed in SPL_OF_LIST. |
| 202 | board_fit_config_name_match() is called to select the right DTB. |
| 203 | |
| 204 | If board_fit_config_name_match() relies on DM (DM driver to access an EEPROM |
| 205 | containing the board ID for example), it possible to start with a generic DTB |
| 206 | and then switch over to the right DTB after the detection. For this purpose, |
| 207 | the platform code must call fdtdec_resetup(). Based on the returned flag, the |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 208 | platform may have to re-initialise the DM subsystem using dm_uninit() and |
Jean-Jacques Hiblot | 7c530e3 | 2018-12-07 14:50:52 +0100 | [diff] [blame] | 209 | dm_init_and_scan(). |
| 210 | |
| 211 | |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 212 | Limitations |
| 213 | ----------- |
| 214 | |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 215 | Devicetrees can help reduce the complexity of supporting variants of boards |
| 216 | which use the same SOC / CPU. |
| 217 | |
| 218 | However U-Boot is designed to build for a single architecture type and CPU |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 219 | type. So for example it is not possible to build a single ARM binary |
| 220 | which runs on your AT91 and OMAP boards, relying on an fdt to configure |
| 221 | the various features. This is because you must select one of |
| 222 | the CPU families within arch/arm/cpu/arm926ejs (omap or at91) at build |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 223 | time. Similarly U-Boot cannot be built for multiple cpu types or |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 224 | architectures. |
| 225 | |
Simon Glass | 38d6b8d | 2011-10-15 05:48:21 +0000 | [diff] [blame] | 226 | It is important to understand that the fdt only selects options |
| 227 | available in the platform / drivers. It cannot add new drivers (yet). So |
| 228 | you must still have the CONFIG option to enable the driver. For example, |
| 229 | you need to define CONFIG_SYS_NS16550 to bring in the NS16550 driver, |
| 230 | but can use the fdt to specific the UART clock, peripheral address, etc. |
| 231 | In very broad terms, the CONFIG options in general control *what* driver |
| 232 | files are pulled in, and the fdt controls *how* those files work. |
| 233 | |
Simon Glass | b4fbaaf | 2021-08-01 18:57:11 -0600 | [diff] [blame^] | 234 | History |
| 235 | ------- |
| 236 | |
| 237 | U-Boot configuration was previous done using CONFIG options in the board |
| 238 | config file. This eventually got out of hand with nearly 10,000 options. |
| 239 | |
| 240 | U-Boot adopted devicetrees around the same time as Linux and early boards |
| 241 | used it before Linux (e.g. snow). The two projects developed in parallel |
| 242 | and there are still some differences in the bindings for certain boards. |
| 243 | While there has been discussion of having a separate repository for devicetree |
| 244 | files, in practice the Linux kernel Git repository has become the place where |
| 245 | these are stored, with U-Boot taking copies and adding tweaks with u-boot.dtsi |
| 246 | files. |
| 247 | |
| 248 | .. _dtspec: https://www.devicetree.org/specifications/ |
| 249 | .. _dtlist: https://www.spinics.net/lists/devicetree-compiler/ |