[U-Boot] [PATCH v3 0/6] Run-time configuration of U-Boot via a flat device tree (fdt)

[Simon Glass]

At present in U-Boot configuration is mostly done using CONFIG options in the
board file. This patch set makes 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.

In other words, manufacturers can potentially use a single U-Boot binary
across an entire product line, with one fdt per model.

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.

To read about fdts, 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

To use this patch set you will need to get the device tree compiler here:

git://jdl.com/software/dtc.git

and add some defines to your board (only ARM is currently supported):

 #define CONFIG_OF_CONTROL       (to enable run-time config control via fdt)
 #define CONFIG_OF_EMBED or CONFIG_OF_SEPARATE
 (either build the fdt blob into U-Boot, or create a separate u-boot.dtb
  and u-boot-dtb.bin)
 #define CONFIG_DEFAULT_DEVICE_TREE	"<your name>"
 (to specify the name of the device tree file is
  board/<vendor>/dts/<your name>.dts)

Typically a CPU device tree include file is provided which defines all the
devices available on that CPU/SOC, with each set to 'status = "disabled"'.
Board device tree files should adjust only the devices they use, setting
'status = 'ok"' in each case, and leaving the existing devices alone and
disabled. To facilitate this, a CPU/SOC device tree header is supported in
arch/<arch>/dts. The name of this is defined by CONFIG_ARCH_DEVICE_TREE,
typically defined in arch/<arch>/cpu/.../config.mk. You can use the
following line within the board device tree file to include this header:

	/include/ ARCH_CPU_DTS

For example, for Tegra2 we might have in arch/arm/cpu/armv7/tegra2/config.mk
these lines:

CONFIG_ARCH_DEVICE_TREE := tegra250

This means that ARCH_CPU_DTS will point to arch/arm/dts/tegra250.dtsi.

This patch set does not include any drivers which actually use the fdt, but
there is a basic fdt decode library (fdtdec) to simplify this process. I
have provided an example i2c implementation previously:

http://patchwork.ozlabs.org/patch/114425/

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.

While only ARM is supported in this patch series, it should be easy enough to
add support for other architectures.

Changes in v2:
- Add example proposed decode helper library
- Modify Makefile to create combined U-boot/fdt (u-boot-dtb.bin)
- Add note about CONFIG_ARCH_DEVICE_TREE

Changes in v3:
- Simplify decode library to remove provide only primitive functions
- Remove i2c decode function
- Rename fdt_decode to fdtdec, since it will be used a lot
- Moved fdt_decode.c to /lib
- Export almost all functions from fdtdec, to allow widespread use
- Remove use of FDT_ERR_MISSING which is not strictly needed now
- Add fdtcontroladdr environment variable
- Add note about CONFIG_ARCH_DEVICE_TREE
- Move fdt files into board/<vendor>/dts
- Provide access to ARCH_CPU_DTS which is the CPU's base device tree
- Rename gd->blob to gd->fdt_blob

Simon Glass (6):
  fdt: ARM: Add device tree control of U-Boot (CONFIG_OF_CONTROL)
  fdt: Add support for embedded device tree (CONFIG_OF_EMBED)
  fdt: Add support for a separate device tree (CONFIG_OF_SEPARATE)
  fdt: ARM: Implement embedded and separate device tree
  fdt: ARM: Add fdtcontroladdr to set device tree address in
    environment
  fdt: add decode helper library

 .gitignore                         |    1 +
 Makefile                           |   12 +++
 README                             |   34 +++++++
 arch/arm/include/asm/global_data.h |    1 +
 arch/arm/lib/board.c               |   52 +++++++++--
 config.mk                          |    1 +
 doc/README.fdt-control             |  184 ++++++++++++++++++++++++++++++++++++
 dts/Makefile                       |  109 +++++++++++++++++++++
 include/common.h                   |    1 +
 include/fdtdec.h                   |  122 ++++++++++++++++++++++++
 lib/Makefile                       |    1 +
 lib/fdtdec.c                       |  131 +++++++++++++++++++++++++
 12 files changed, 642 insertions(+), 7 deletions(-)
 create mode 100644 doc/README.fdt-control
 create mode 100644 dts/Makefile
 create mode 100644 include/fdtdec.h
 create mode 100644 lib/fdtdec.c

-- 
1.7.3.1