diff options
Diffstat (limited to 'qemu/roms/u-boot/doc/README.fdt-control')
| -rw-r--r-- | qemu/roms/u-boot/doc/README.fdt-control | 186 |
1 files changed, 186 insertions, 0 deletions
diff --git a/qemu/roms/u-boot/doc/README.fdt-control b/qemu/roms/u-boot/doc/README.fdt-control new file mode 100644 index 000000000..86bae6816 --- /dev/null +++ b/qemu/roms/u-boot/doc/README.fdt-control @@ -0,0 +1,186 @@ +# +# 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 |