--- /dev/null
+#
+# Copyright (c) 2011 The Chromium OS Authors.
+#
+# SPDX-License-Identifier: GPL-2.0+
+#
+
+Device Tree Control in U-Boot
+=============================
+
+This feature provides for run-time configuration of U-Boot via a flat
+device tree (fdt). U-Boot configuration has traditionally been done
+using CONFIG options in the board config file. 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 flat device
+tree (fdt). This is the approach recently taken by the ARM Linux kernel
+and has been used by PowerPC for some time.
+
+The fdt is a convenient vehicle for implementing run-time configuration
+for three reasons. Firstly it is easy to use, being a simple text file.
+It is extensible since it consists of nodes and properties in a nice
+hierarchical format.
+
+Finally, 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.
+
+The dts directory contains a Makefile for building the device tree blob
+and embedding it in your 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 device tree file, and have a single
+generic source base.
+
+To enable this feature, add CONFIG_OF_CONTROL to your board config file.
+It is currently supported on ARM, x86 and Microblaze - other architectures
+will need to add code to their arch/xxx/lib/board.c file to locate the
+FDT. Alternatively you can enable generic board support on your board
+(with CONFIG_SYS_GENERIC_BOARD) if this is available (as it is for
+PowerPC). For ARM, Tegra and Exynos5 have device trees available for
+common devices.
+
+
+What is a Flat Device Tree?
+---------------------------
+
+An fdt can be specified in source format as a text file. To read about
+the fdt syntax, take a look at the specification here:
+
+https://www.power.org/resources/downloads/Power_ePAPR_APPROVED_v1.0.pdf
+
+You also might find this section of the Linux kernel documentation
+useful: (access this in the Linux kernel source code)
+
+ Documentation/devicetree/booting-without-of.txt
+
+There is also a mailing list:
+
+ http://lists.ozlabs.org/listinfo/devicetree-discuss
+
+In case you are wondering, OF stands for Open Firmware.
+
+
+Tools
+-----
+
+To use this feature you will need to get the device tree compiler here:
+
+ git://jdl.com/software/dtc.git
+
+For example:
+
+ $ git clone git://jdl.com/software/dtc.git
+ $ cd dtc
+ $ make
+ $ sudo make install
+
+Then run the compiler (your version will vary):
+
+ $ dtc -v
+ Version: DTC 1.2.0-g2cb4b51f
+ $ make tests
+ $ cd tests
+ $ ./run_tests.sh
+ ********** TEST SUMMARY
+ * Total testcases: 1371
+ * PASS: 1371
+ * FAIL: 0
+ * Bad configuration: 0
+ * Strange test result: 0
+
+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?
+----------------------------------------
+
+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 device tree source. Then put your device tree
+file into
+
+ 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.
+
+If CONFIG_OF_EMBED is defined, then it will be picked up and built into
+the U-Boot image (including u-boot.bin).
+
+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
+join the two:
+
+ cat u-boot.bin u-boot.dtb >image.bin
+
+and then flash image.bin onto your board.
+
+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.
+
+You cannot use more than one of these options at the same time.
+
+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).
+
+To use this, put something like this in your board header file:
+
+#define CONFIG_EXTRA_ENV_SETTINGS "fdtcontroladdr=10000\0"
+
+Build:
+
+After board configuration is done, fdt supported u-boot can be build in two ways:
+1) build the default dts which is defined from CONFIG_DEFAULT_DEVICE_TREE
+ $ make
+2) build the user specified dts file
+ $ make DEVICE_TREE=<dts-file-name>
+
+
+Limitations
+-----------
+
+U-Boot is designed to build with 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 you cannot build for multiple cpu types or
+architectures.
+
+That said the complexity reduction by using fdt to support variants of
+boards which use the same SOC / CPU can be substantial.
+
+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.
+
+--
+Simon Glass <sjg@chromium.org>
+1-Sep-11
Code Review / kvmfornfv.git / blobdiff