diff options
Diffstat (limited to 'doc/develop')
| -rw-r--r-- | doc/develop/devicetree/control.rst | 251 | ||||
| -rw-r--r-- | doc/develop/devicetree/index.rst | 13 | ||||
| -rw-r--r-- | doc/develop/devicetree/intro.rst | 44 | ||||
| -rw-r--r-- | doc/develop/index.rst | 1 |
4 files changed, 309 insertions, 0 deletions
diff --git a/doc/develop/devicetree/control.rst b/doc/develop/devicetree/control.rst new file mode 100644 index 0000000..e84dfb6 --- /dev/null +++ b/doc/develop/devicetree/control.rst @@ -0,0 +1,251 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Copyright 2011 The Chromium OS Authors + +Devicetree Control in U-Boot +============================ + +This feature provides for run-time configuration of U-Boot via a flattened +devicetree (fdt). + +This feature aims to make it possible for a single U-Boot binary to support +multiple boards, with the exact configuration of each board controlled by +a flattened devicetree (fdt). This is the approach taken by Linux kernel for +ARM and RISC-V and has been used by PowerPC for some time. + +The fdt is a convenient vehicle for implementing run-time configuration +for three reasons: + +- There is already excellent infrastructure for the fdt: a compiler checks + the text file and converts it to a compact binary format, and a library + is already available in U-Boot (libfdt) for handling this format +- It is extensible since it consists of nodes and properties in a nice + hierarchical format +- It is fairly efficient to read incrementally + +The arch/<arch>/dts directories contains a Makefile for building the devicetree +blob and embedding it in the U-Boot image. This is useful since it allows +U-Boot to configure itself according to what it finds there. If you have +a number of similar boards with different peripherals, you can describe +the features of each board in the devicetree file, and have a single +generic source base. + +To enable this feature, add CONFIG_OF_CONTROL to your board config file. + + +What is a Flattened Devicetree? +------------------------------- + +An fdt can be specified in source format as a text file. To read about +the fdt syntax, take a look at the specification (dtspec_). + +There is also a mailing list (dtlist_) for the compiler and associated +tools. + +In case you are wondering, OF stands for Open Firmware. This follows the +convention used in Linux. + + +Tools +----- + +To create flattened device trees the device tree compiler is used. This is +provided by U-Boot automatically. If you have a system version of dtc +(typically in the 'device-tree-compiler' package), that system version is +currently not used. + +If you want to build your own dtc, it is kept here:: + + git://git.kernel.org/pub/scm/utils/dtc/dtc.git + +You can decode a binary file with:: + + dtc -I dtb -O dts <filename.dtb> + +That repo also includes `fdtget`/`fdtput` for reading and writing properties in +a binary file. U-Boot adds its own `fdtgrep` for creating subsets of the file. + + +Where do I get a devicetree file for my board? +---------------------------------------------- + +You may find that the Linux kernel has a suitable file. Look in the +kernel source in arch/<arch>/boot/dts. + +If not you might find other boards with suitable files that you can +modify to your needs. Look in the board directories for files with a +.dts extension. + +Failing that, you could write one from scratch yourself! + + +Configuration +------------- + +Use:: + + #define CONFIG_DEFAULT_DEVICE_TREE "<name>" + +to set the filename of the devicetree source. Then put your devicetree +file into:: + + arch/<arch>/dts/<name>.dts + +This should include your CPU or SOC's devicetree file, placed in +`arch/<arch>/dts`, and then make any adjustments required using a u-boot-dtsi +file for your board. + +If CONFIG_OF_EMBED is defined, then it will be picked up and built into +the U-Boot image (including u-boot.bin). This is suitable for debugging +and development only and is not recommended for production devices. + +If CONFIG_OF_SEPARATE is defined, then it will be built and placed in +a u-boot.dtb file alongside u-boot-nodtb.bin with the combined result placed +in u-boot.bin so you can still just flash u-boot,bin onto your board. If you are +using CONFIG_SPL_FRAMEWORK, then u-boot.img will be built to include the device +tree binary. + +If CONFIG_OF_BOARD is defined, a board-specific routine will provide the +devicetree at runtime, for example if an earlier bootloader stage creates +it and passes it to U-Boot. + +If CONFIG_OF_HOSTFILE is defined, then it will be read from a file on +startup. This is only useful for sandbox. Use the -d flag to U-Boot to +specify the file to read, -D for the default and -T for the test devicetree, +used to run sandbox unit tests. + +You cannot use more than one of these options at the same time. + +To use a devicetree file that you have compiled yourself, pass +EXT_DTB=<filename> to 'make', as in:: + + make EXT_DTB=boot/am335x-boneblack-pubkey.dtb + +Then U-Boot will copy that file to u-boot.dtb, put it in the .img file +if used, and u-boot-dtb.bin. + +If you wish to put the fdt at a different address in memory, you can +define the "fdtcontroladdr" environment variable. This is the hex +address of the fdt binary blob, and will override either of the options. +Be aware that this environment variable is checked prior to relocation, +when only the compiled-in environment is available. Therefore it is not +possible to define this variable in the saved SPI/NAND flash +environment, for example (it will be ignored). After relocation, this +variable will be set to the address of the newly relocated fdt blob. +It is read-only and cannot be changed. It can optionally be used to +control the boot process of Linux with bootm/bootz commands. + +To use this, put something like this in your board header file:: + + #define CONFIG_EXTRA_ENV_SETTINGS "fdtcontroladdr=10000\0" + +Build: + +After the board configuration is done, fdt supported u-boot can be built in two +ways: + +# build the default dts which is defined from CONFIG_DEFAULT_DEVICE_TREE:: + + $ make + +# build the user specified dts file:: + + $ make DEVICE_TREE=<dts-file-name> + + +.. _dttweaks: + +Adding tweaks for U-Boot +------------------------ + +It is strongly recommended that devicetree files in U-Boot are an exact copy of +those in Linux, so that it is easy to sync them up from time to time. + +U-Boot is of course a very different project from Linux, e.g. it operates under +much more restrictive memory and code-size constraints. Where Linux may use a +full clock driver with Common Clock Format (CCF) to find the input clock to the +UART, U-Boot typically wants to output a banner as early as possible before too +much code has run. + +A second difference is that U-Boot includes different phases. For SPL, +constraints are even more extreme and the devicetree is shrunk to remove +unwanted nodes, or even turned into C code to avoid access overhead. + +U-Boot automatically looks for and includes a file with updates to the standard +devicetree for your board, searching for them in the same directory as the +main file, in this order:: + + <orig_filename>-u-boot.dtsi + <CONFIG_SYS_SOC>-u-boot.dtsi + <CONFIG_SYS_CPU>-u-boot.dtsi + <CONFIG_SYS_VENDOR>-u-boot.dtsi + u-boot.dtsi + +Only one of these is selected but of course you can #include another one within +that file, to create a hierarchy of shared files. + +Relocation, SPL and TPL +----------------------- + +U-Boot can be divided into three phases: TPL, SPL and U-Boot proper. + +The full devicetree is available to U-Boot proper, but normally only a subset +(or none at all) is available to TPL and SPL. See 'Pre-Relocation Support' and +'SPL Support' in doc/driver-model/design.rst for more details. + + +Using several DTBs in the SPL (CONFIG_SPL_MULTI_DTB) +---------------------------------------------------- +In some rare cases it is desirable to let SPL be able to select one DTB among +many. This usually not very useful as the DTB for the SPL is small and usually +fits several platforms. However the DTB sometimes include information that do +work on several platforms (like IO tuning parameters). +In this case it is possible to use CONFIG_SPL_MULTI_DTB. This option appends to +the SPL a FIT image containing several DTBs listed in SPL_OF_LIST. +board_fit_config_name_match() is called to select the right DTB. + +If board_fit_config_name_match() relies on DM (DM driver to access an EEPROM +containing the board ID for example), it possible to start with a generic DTB +and then switch over to the right DTB after the detection. For this purpose, +the platform code must call fdtdec_resetup(). Based on the returned flag, the +platform may have to re-initialise the DM subsystem using dm_uninit() and +dm_init_and_scan(). + + +Limitations +----------- + +Devicetrees can help reduce the complexity of supporting variants of boards +which use the same SOC / CPU. + +However U-Boot is designed to build for a single architecture type and CPU +type. So for example it is not possible to build a single ARM binary +which runs on your AT91 and OMAP boards, relying on an fdt to configure +the various features. This is because you must select one of +the CPU families within arch/arm/cpu/arm926ejs (omap or at91) at build +time. Similarly U-Boot cannot be built for multiple cpu types or +architectures. + +It is important to understand that the fdt only selects options +available in the platform / drivers. It cannot add new drivers (yet). So +you must still have the CONFIG option to enable the driver. For example, +you need to define CONFIG_SYS_NS16550 to bring in the NS16550 driver, +but can use the fdt to specific the UART clock, peripheral address, etc. +In very broad terms, the CONFIG options in general control *what* driver +files are pulled in, and the fdt controls *how* those files work. + +History +------- + +U-Boot configuration was previous done using CONFIG options in the board +config file. This eventually got out of hand with nearly 10,000 options. + +U-Boot adopted devicetrees around the same time as Linux and early boards +used it before Linux (e.g. snow). The two projects developed in parallel +and there are still some differences in the bindings for certain boards. +While there has been discussion of having a separate repository for devicetree +files, in practice the Linux kernel Git repository has become the place where +these are stored, with U-Boot taking copies and adding tweaks with u-boot.dtsi +files. + +.. _dtspec: https://www.devicetree.org/specifications/ +.. _dtlist: https://www.spinics.net/lists/devicetree-compiler/ diff --git a/doc/develop/devicetree/index.rst b/doc/develop/devicetree/index.rst new file mode 100644 index 0000000..fa5db3e --- /dev/null +++ b/doc/develop/devicetree/index.rst @@ -0,0 +1,13 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Devicetree in U-Boot +==================== + +The following holds information on how U-Boot makes use of devicetree for +build-time and runtime configuration. + +.. toctree:: + :maxdepth: 2 + + intro + control diff --git a/doc/develop/devicetree/intro.rst b/doc/develop/devicetree/intro.rst new file mode 100644 index 0000000..36e8cc0 --- /dev/null +++ b/doc/develop/devicetree/intro.rst @@ -0,0 +1,44 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Devicetree Introduction +======================= + +U-Boot uses a devicetree for configuration. This includes the devices used by +the board, the format of the image created with binman, which UART to use for +the console, public keys used for secure boot and many other things. + +See :doc:`control` for more information. + +Why does U-Boot put <thing> in the devicetree? +---------------------------------------------- + +This question comes up a lot with people new to U-Boot, particular those coming +from Linux who are used to quite strict rules about what can go into the +devicetree. + +U-Boot uses the same devicetree as Linux but adds more things necessary for the +bootloader environment (see :ref:`dttweaks`). + +U-Boot does not have a user space to provide policy and configuration. It cannot +do what Linux does and run programs and look up filesystems to figure out how to +boot. So configuration and runtime information goes into the devicetree in +U-Boot. + +Of course it is possible to: + +- add tables into the rodata section of the U-Boot binary +- append some info to the end of U-Boot in a different format +- modify the linker script to bring in a file with some info in it +- put things in ACPI tables +- link in a UEFI hand-off block structure and put things in there + +but *please don't*. In general, devicetree is the sane place to hold U-Boot's +configuration. + +So, please, do NOT ask why U-Boot puts <thing> in the devicetree. It is the only +place it can go. It is a highly suitable data structure for just about anything +that U-Boot needs to know at runtime. + +Note, it is possible to use platdata directly so drivers avoid devicetreee in +SPL. But of-platdata is the modern way of avoiding devicetree overhead, so +please use that instead. diff --git a/doc/develop/index.rst b/doc/develop/index.rst index 1203409..83c929b 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -11,6 +11,7 @@ Implementation ci_testing commands + devicetree/index driver-model/index global_data logging |