[U-Boot] [PATCH v6 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 = "ok"'.
Board device tree files should adjust only the devices they need to. If a
device should be disabled, then it should be changed to
'status = 'disabled"' to indicate this. 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 := tegra20

This means that ARCH_CPU_DTS will point to arch/arm/dts/tegra20.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.

I experimented with using dtc's asm output to avoid all the arch/oformat
ugliness in dts/Makefile as suggested by Stephen Warren
<swarren at nvidia.com>. This simplified the Makefile commands greatly by
removing the need to detect the output format and architecture. However
Grant Likely <grant.likely at secretlab.ca> explained that this feature is
not well tested and still has some big-endian-ims in it.

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

Changes in v3:
- Rename gd->blob to gd->fdt_blob
- Move fdt files into board/<vendor>/dts
- Provide access to ARCH_CPU_DTS which is the CPU's base device tree
- 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

Changes in v4:
- Fix reference to gd->blob which should be gd->fdt_blob
- Remove unused 'clean' targets in dts/Makefile (remmove *.tmp at top-level)
- Move documentation into the first 'fdt' patch in the series
- Add note about CONFIG_ARCH_DEVICE_TREE
- Add assert on sprintf() string length
- Rename addr_t to fdt_addr_t to make it more fdt-specific
- Remove gpio.h header in fdtdec.c which is not needed yet

Changes in v5:
- Corrected const nit in fdtdec.c missed in v4

Changes in v6:
- Move the fdt check into fdtdec since all archs will need it
- Use the new getenv_ulong() function

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: add decode helper library
  fdt: ARM: Implement and verify embedded and separate device tree
  fdt: ARM: Add fdtcontroladdr to set device tree address in
    environment

 .gitignore                         |    1 +
 Makefile                           |   13 +++
 README                             |   34 +++++++
 arch/arm/include/asm/global_data.h |    1 +
 arch/arm/lib/board.c               |   15 +++
 config.mk                          |    1 +
 doc/README.fdt-control             |  184 ++++++++++++++++++++++++++++++++++++
 dts/Makefile                       |  103 ++++++++++++++++++++
 include/common.h                   |    1 +
 include/fdtdec.h                   |  128 +++++++++++++++++++++++++
 lib/Makefile                       |    1 +
 lib/fdtdec.c                       |  147 ++++++++++++++++++++++++++++
 12 files changed, 629 insertions(+), 0 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