Patchwork [U-Boot,RFC,v2,3/6] fdt: Add support for a separate device tree (CONFIG_OF_SEPARATE)

login
register
mail settings
Submitter Simon Glass
Date Sept. 12, 2011, 10:04 p.m.
Message ID <1315865067-1443-4-git-send-email-sjg@chromium.org>
Download mbox | patch
Permalink /patch/114424/
State New, archived
Headers show

Comments

Simon Glass - Sept. 12, 2011, 10:04 p.m.
This adds support for an FDT to be build as a separate binary file called
u-boot.dtb. This can be concatenated with the U-Boot binary to provide a
device tree located at run-time by U-Boot.

Signed-off-by: Simon Glass <sjg@chromium.org>
---
 .gitignore             |    1 +
 Makefile               |    5 ++
 README                 |   11 +++-
 doc/README.fdt-control |  168 ++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 183 insertions(+), 2 deletions(-)
 create mode 100644 doc/README.fdt-control
Grant Likely - Sept. 14, 2011, 4:48 p.m.
On Mon, Sep 12, 2011 at 03:04:24PM -0700, Simon Glass wrote:
> This adds support for an FDT to be build as a separate binary file called
> u-boot.dtb. This can be concatenated with the U-Boot binary to provide a
> device tree located at run-time by U-Boot.

Hahaha, I should the entire thread of patches before commenting.  I
strongly feel that this should be the only method and that
CONFIG_OF_EMBED should be dropped.

> 
> Signed-off-by: Simon Glass <sjg@chromium.org>
> ---
>  .gitignore             |    1 +
>  Makefile               |    5 ++
>  README                 |   11 +++-
>  doc/README.fdt-control |  168 ++++++++++++++++++++++++++++++++++++++++++++++++
>  4 files changed, 183 insertions(+), 2 deletions(-)
>  create mode 100644 doc/README.fdt-control
> 
> diff --git a/.gitignore b/.gitignore
> index dbf545f..c4ebd34 100644
> --- a/.gitignore
> +++ b/.gitignore
> @@ -34,6 +34,7 @@
>  /u-boot.dis
>  /u-boot.lds
>  /u-boot.ubl
> +/u-boot.dtb
>  
>  #
>  # Generated files
> diff --git a/Makefile b/Makefile
> index 658a622..d73efa1 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -352,9 +352,14 @@ ALL-$(CONFIG_ONENAND_U_BOOT) += $(obj)u-boot-onenand.bin
>  ONENAND_BIN ?= $(obj)onenand_ipl/onenand-ipl-2k.bin
>  ALL-$(CONFIG_MMC_U_BOOT) += $(obj)mmc_spl/u-boot-mmc-spl.bin
>  ALL-$(CONFIG_SPL) += $(obj)spl/u-boot-spl.bin
> +ALL-$(CONFIG_OF_SEPARATE) += $(obj)u-boot.dtb
>  
>  all:		$(ALL-y)
>  
> +$(obj)u-boot.dtb:	$(obj)u-boot
> +		$(MAKE) -C dts binary
> +		mv $(obj)dts/dt.dtb $@
> +
>  $(obj)u-boot.hex:	$(obj)u-boot
>  		$(OBJCOPY) ${OBJCFLAGS} -O ihex $< $@
>  
> diff --git a/README b/README
> index 5a2f060..0b8f338 100644
> --- a/README
> +++ b/README
> @@ -803,8 +803,8 @@ The following options need to be configured:
>  		experimental and only available on a few boards. The device
>  		tree is available in the global data as gd->blob.
>  
> -		U-Boot needs to get its device tree from somewhere. At present
> -		the only way is to embed it in the image with CONFIG_OF_EMBED.
> +		U-Boot needs to get its device tree from somewhere. This can
> +		be done using one of the two options below:
>  
>  		CONFIG_OF_EMBED
>  		If this variable is defined, U-Boot will embed a device tree
> @@ -813,6 +813,13 @@ The following options need to be configured:
>  		is then picked up in board_init_f() and made available through
>  		the global data structure as gd->blob.
>  
> +		CONFIG_OF_SEPARATE
> +		If this variable is defined, U-Boot will build a device tree
> +		binary. It will be called u-boot.dtb. Architecture-specific
> +		code will locate it at run-time. Generally this works by:
> +
> +			cat u-boot.bin u-boot.dtb >image.bin
> +
>  - Watchdog:
>  		CONFIG_WATCHDOG
>  		If this variable is defined, it enables watchdog
> diff --git a/doc/README.fdt-control b/doc/README.fdt-control
> new file mode 100644
> index 0000000..dfc8f06
> --- /dev/null
> +++ b/doc/README.fdt-control
> @@ -0,0 +1,168 @@
> +#
> +# 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>/<board>/<name>.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.
> +
> +
> +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
> -- 
> 1.7.3.1
>
Simon Glass - Sept. 14, 2011, 6:25 p.m.
Hi Grant,

On Wed, Sep 14, 2011 at 9:48 AM, Grant Likely <grant.likely@secretlab.ca> wrote:
> On Mon, Sep 12, 2011 at 03:04:24PM -0700, Simon Glass wrote:
>> This adds support for an FDT to be build as a separate binary file called
>> u-boot.dtb. This can be concatenated with the U-Boot binary to provide a
>> device tree located at run-time by U-Boot.
>
> Hahaha, I should the entire thread of patches before commenting.  I
> strongly feel that this should be the only method and that
> CONFIG_OF_EMBED should be dropped.

:-)

Please see my comments in the other thread.

Regards,
Simon

>
>>
>> Signed-off-by: Simon Glass <sjg@chromium.org>
>> ---
>>  .gitignore             |    1 +
>>  Makefile               |    5 ++
>>  README                 |   11 +++-
>>  doc/README.fdt-control |  168 ++++++++++++++++++++++++++++++++++++++++++++++++
>>  4 files changed, 183 insertions(+), 2 deletions(-)
>>  create mode 100644 doc/README.fdt-control
>>
>> diff --git a/.gitignore b/.gitignore
>> index dbf545f..c4ebd34 100644
>> --- a/.gitignore
>> +++ b/.gitignore
>> @@ -34,6 +34,7 @@
>>  /u-boot.dis
>>  /u-boot.lds
>>  /u-boot.ubl
>> +/u-boot.dtb
>>
>>  #
>>  # Generated files
>> diff --git a/Makefile b/Makefile
>> index 658a622..d73efa1 100644
>> --- a/Makefile
>> +++ b/Makefile
>> @@ -352,9 +352,14 @@ ALL-$(CONFIG_ONENAND_U_BOOT) += $(obj)u-boot-onenand.bin
>>  ONENAND_BIN ?= $(obj)onenand_ipl/onenand-ipl-2k.bin
>>  ALL-$(CONFIG_MMC_U_BOOT) += $(obj)mmc_spl/u-boot-mmc-spl.bin
>>  ALL-$(CONFIG_SPL) += $(obj)spl/u-boot-spl.bin
>> +ALL-$(CONFIG_OF_SEPARATE) += $(obj)u-boot.dtb
>>
>>  all:         $(ALL-y)
>>
>> +$(obj)u-boot.dtb:    $(obj)u-boot
>> +             $(MAKE) -C dts binary
>> +             mv $(obj)dts/dt.dtb $@
>> +
>>  $(obj)u-boot.hex:    $(obj)u-boot
>>               $(OBJCOPY) ${OBJCFLAGS} -O ihex $< $@
>>
>> diff --git a/README b/README
>> index 5a2f060..0b8f338 100644
>> --- a/README
>> +++ b/README
>> @@ -803,8 +803,8 @@ The following options need to be configured:
>>               experimental and only available on a few boards. The device
>>               tree is available in the global data as gd->blob.
>>
>> -             U-Boot needs to get its device tree from somewhere. At present
>> -             the only way is to embed it in the image with CONFIG_OF_EMBED.
>> +             U-Boot needs to get its device tree from somewhere. This can
>> +             be done using one of the two options below:
>>
>>               CONFIG_OF_EMBED
>>               If this variable is defined, U-Boot will embed a device tree
>> @@ -813,6 +813,13 @@ The following options need to be configured:
>>               is then picked up in board_init_f() and made available through
>>               the global data structure as gd->blob.
>>
>> +             CONFIG_OF_SEPARATE
>> +             If this variable is defined, U-Boot will build a device tree
>> +             binary. It will be called u-boot.dtb. Architecture-specific
>> +             code will locate it at run-time. Generally this works by:
>> +
>> +                     cat u-boot.bin u-boot.dtb >image.bin
>> +
>>  - Watchdog:
>>               CONFIG_WATCHDOG
>>               If this variable is defined, it enables watchdog
>> diff --git a/doc/README.fdt-control b/doc/README.fdt-control
>> new file mode 100644
>> index 0000000..dfc8f06
>> --- /dev/null
>> +++ b/doc/README.fdt-control
>> @@ -0,0 +1,168 @@
>> +#
>> +# 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>/<board>/<name>.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.
>> +
>> +
>> +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
>> --
>> 1.7.3.1
>>
>

Patch

diff --git a/.gitignore b/.gitignore
index dbf545f..c4ebd34 100644
--- a/.gitignore
+++ b/.gitignore
@@ -34,6 +34,7 @@ 
 /u-boot.dis
 /u-boot.lds
 /u-boot.ubl
+/u-boot.dtb
 
 #
 # Generated files
diff --git a/Makefile b/Makefile
index 658a622..d73efa1 100644
--- a/Makefile
+++ b/Makefile
@@ -352,9 +352,14 @@  ALL-$(CONFIG_ONENAND_U_BOOT) += $(obj)u-boot-onenand.bin
 ONENAND_BIN ?= $(obj)onenand_ipl/onenand-ipl-2k.bin
 ALL-$(CONFIG_MMC_U_BOOT) += $(obj)mmc_spl/u-boot-mmc-spl.bin
 ALL-$(CONFIG_SPL) += $(obj)spl/u-boot-spl.bin
+ALL-$(CONFIG_OF_SEPARATE) += $(obj)u-boot.dtb
 
 all:		$(ALL-y)
 
+$(obj)u-boot.dtb:	$(obj)u-boot
+		$(MAKE) -C dts binary
+		mv $(obj)dts/dt.dtb $@
+
 $(obj)u-boot.hex:	$(obj)u-boot
 		$(OBJCOPY) ${OBJCFLAGS} -O ihex $< $@
 
diff --git a/README b/README
index 5a2f060..0b8f338 100644
--- a/README
+++ b/README
@@ -803,8 +803,8 @@  The following options need to be configured:
 		experimental and only available on a few boards. The device
 		tree is available in the global data as gd->blob.
 
-		U-Boot needs to get its device tree from somewhere. At present
-		the only way is to embed it in the image with CONFIG_OF_EMBED.
+		U-Boot needs to get its device tree from somewhere. This can
+		be done using one of the two options below:
 
 		CONFIG_OF_EMBED
 		If this variable is defined, U-Boot will embed a device tree
@@ -813,6 +813,13 @@  The following options need to be configured:
 		is then picked up in board_init_f() and made available through
 		the global data structure as gd->blob.
 
+		CONFIG_OF_SEPARATE
+		If this variable is defined, U-Boot will build a device tree
+		binary. It will be called u-boot.dtb. Architecture-specific
+		code will locate it at run-time. Generally this works by:
+
+			cat u-boot.bin u-boot.dtb >image.bin
+
 - Watchdog:
 		CONFIG_WATCHDOG
 		If this variable is defined, it enables watchdog
diff --git a/doc/README.fdt-control b/doc/README.fdt-control
new file mode 100644
index 0000000..dfc8f06
--- /dev/null
+++ b/doc/README.fdt-control
@@ -0,0 +1,168 @@ 
+#
+# 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>/<board>/<name>.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.
+
+
+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