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