eea63e05d0
This adds support for a new environment variable called 'fdtcontroladdr'. If defined, the hex address is used as the address of the control fdt for U-Boot. Note: I have not changed CONFIG_PRAM section as I already have an outstanding patch on that. Signed-off-by: Simon Glass <sjg@chromium.org>
185 lines
6.1 KiB
Plaintext
185 lines
6.1 KiB
Plaintext
#
|
|
# 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
|
|
=============================
|
|
|
|
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.
|
|
|
|
|
|
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 ftdump utility for decoding 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. The name of this
|
|
is CONFIG_ARCH_DEVICE_TREE.dts.
|
|
|
|
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.
|
|
|
|
You cannot use both 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"
|
|
|
|
|
|
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
|