+# SPDX-License-Identifier: GPL-2.0+
#
# Copyright (c) 2011 The Chromium OS Authors.
-#
-# See file CREDITS for list of people who contributed to this
-# project.
-#
-# This program is free software; you can redistribute it and/or
-# modify it under the terms of the GNU General Public License as
-# published by the Free Software Foundatio; either version 2 of
-# the License, or (at your option) any later version.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with this program; if not, write to the Free Software
-# Foundation, Inc., 59 Temple Place, Suite 330, Boston,
-# MA 02111-1307 USA
-#
Device Tree Control in U-Boot
=============================
Tools
-----
-To use this feature you will need to get the device tree compiler here:
+To use this feature you will need to get the device tree compiler. This is
+provided by U-Boot automatically. If you have a system version of dtc
+(typically in the 'device-tree-compiler' package), it is currently not used.
- git://jdl.com/software/dtc.git
+If you want to build your own dtc, it is kept here:
+
+ git://git.kernel.org/pub/scm/utils/dtc/dtc.git
For example:
- $ git clone git://jdl.com/software/dtc.git
+ $ git clone git://git.kernel.org/pub/scm/utils/dtc/dtc.git
$ cd dtc
$ make
$ sudo make install
* Bad configuration: 0
* Strange test result: 0
-You will also find a useful ftdump utility for decoding a binary file.
+You will also find a useful fdtdump utility for decoding a binary file, as
+well as fdtget/fdtput for reading and writing properties in a binary file.
Where do I get an fdt file for my board?
board/<vendor>/dts/<name>.dts
This should include your CPU or SOC's device tree file, placed in
-arch/<arch>/dts, and then make any adjustments required. The name of this
-is CONFIG_ARCH_DEVICE_TREE.dts.
+arch/<arch>/dts, and then make any adjustments required.
If CONFIG_OF_EMBED is defined, then it will be picked up and built into
-the U-Boot image (including u-boot.bin).
+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.bin. A common approach is then to
+a u-boot.dtb file alongside u-boot-nodtb.bin. A common approach is then to
join the two:
- cat u-boot.bin u-boot.dtb >image.bin
+ cat u-boot-nodtb.bin u-boot.dtb >image.bin
+
+and then flash image.bin onto your board. Note that U-Boot creates
+u-boot-dtb.bin which does the above step for you also. Resulting
+u-boot.bin is a copy of u-boot-dtb.bin in this case. 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
+device tree 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.
-and then flash image.bin onto your board.
+You cannot use more than one of these options at the same time.
-You cannot use both of these options at the same time.
+To use a device tree 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
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).
+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:
$ make DEVICE_TREE=<dts-file-name>
+Relocation, SPL and TPL
+-----------------------
+
+U-Boot can be divided into three phases: TPL, SPL and U-Boot proper.
+
+The full device tree 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-initiliaze the DM subusystem using dm_uninit() and
+dm_init_and_scan().
+
+
Limitations
-----------
projects / oweals / u-boot.git / blobdiff