[U-Boot] [PATCH v6 09/13] binman: Automatically include a U-Boot .dtsi file

[Simon Glass]

For boards that need U-Boot-specific additions to the device tree, it is
a minor annoyance to have to add these each time the tree is synced with
upstream.

Add a means to include a file (e.g. u-boot.dtsi) automatically into the .dts
file before it is compiled.

The file uses is the first one that exists in this list:

   arch/<arch>/dts/<board.dts>-u-boot.dtsi
   arch/<arch>/dts/<soc>-u-boot.dtsi
   arch/<arch>/dts/<cpu>-u-boot.dtsi
   arch/<arch>/dts/<vendor>-u-boot.dtsi
   arch/<arch>/dts/u-boot.dtsi

Signed-off-by: Simon Glass <sjg at chromium.org>
Suggested-by: Tom Rini <trini at konsulko.com>
---

Changes in v6: None
Changes in v5:
- Add a Makefile 'warning' line for debugging
- Add documentation for this feature
- Change the Makefile variable from binman_... to u_boot_...

Changes in v4:
- Add an option to bring in an soc .dtsi file also

Changes in v3:
- Add a new patch to automatically include a U-Boot .dtsi file

Changes in v2: None

 scripts/Makefile.lib | 20 +++++++++++++++++++-
 tools/binman/README  | 39 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+), 1 deletion(-)

diff --git a/scripts/Makefile.lib b/scripts/Makefile.lib
index a237b7b..60265f4 100644
--- a/scripts/Makefile.lib
+++ b/scripts/Makefile.lib
@@ -164,6 +164,21 @@ cpp_flags      = -Wp,-MD,$(depfile) $(NOSTDINC_FLAGS) $(UBOOTINCLUDE)     \
 
 ld_flags       = $(LDFLAGS) $(ldflags-y)
 
+dts_dir = $(srctree)/arch/$(ARCH)/dts
+
+# Try these files in order to find the U-Boot-specific .dtsi include file
+u_boot_dtsi_options = $(wildcard $(dts_dir)/$(basename $(notdir $<))-u-boot.dtsi) \
+	$(wildcard $(dts_dir)/$(subst $\",,$(CONFIG_SYS_SOC))-u-boot.dtsi) \
+	$(wildcard $(dts_dir)/$(subst $\",,$(CONFIG_SYS_CPU))-u-boot.dtsi) \
+	$(wildcard $(dts_dir)/$(subst $\",,$(CONFIG_SYS_VENDOR))-u-boot.dtsi) \
+	$(wildcard $(dts_dir)/u-boot.dtsi)
+
+# Uncomment for debugging
+# $(warning u_boot_dtsi_options: $(u_boot_dtsi_options))
+
+# We use the first match
+u_boot_dtsi = $(firstword $(u_boot_dtsi_options))
+
 # Modified for U-Boot
 dtc_cpp_flags  = -Wp,-MD,$(depfile).pre.tmp -nostdinc                    \
 		 -I$(srctree)/arch/$(ARCH)/dts                           \
@@ -293,8 +308,11 @@ $(obj)/%.dtb.S: $(obj)/%.dtb
 
 quiet_cmd_dtc = DTC     $@
 # Modified for U-Boot
+# Bring in any U-Boot-specific include after the '/dts-v1/;' header
 cmd_dtc = mkdir -p $(dir ${dtc-tmp}) ; \
-	$(CPP) $(dtc_cpp_flags) -x assembler-with-cpp -o $(dtc-tmp) $< ; \
+	cat $< $(if $(u-boot-dtsi),\
+		| sed 's%^/ {$$%\#include \"$(u-boot-dtsi)\"\n&%')  | \
+		$(CPP) $(dtc_cpp_flags) -x assembler-with-cpp -o $(dtc-tmp) - ; \
 	$(DTC) -O dtb -o $@ -b 0 \
 		-i $(dir $<) $(DTC_FLAGS) \
 		-d $(depfile).dtc.tmp $(dtc-tmp) ; \
diff --git a/tools/binman/README b/tools/binman/README
index 45e741e..cb47e73 100644
--- a/tools/binman/README
+++ b/tools/binman/README
@@ -422,6 +422,45 @@ stage the position and size of entries should not be adjusted.
 step.
 
 
+Automatic .dtsi inclusion
+-------------------------
+
+It is sometimes inconvenient to add a 'binman' node to the .dts file for each
+board. This can be done by using #include to bring in a common file. Another
+approach supported by the U-Boot build system is to automatically include
+a common header. You can then put the binman node (and anything else that is
+specific to U-Boot, such as u-boot,dm-pre-reloc properies) in that header
+file.
+
+Binman will search for the following files in arch/<arch>/dts:
+
+   <dts>-u-boot.dtsi where <dts> is the base name of the .dts file
+   <CONFIG_SYS_SOC>-u-boot.dtsi
+   <CONFIG_SYS_CPU>-u-boot.dtsi
+   <CONFIG_SYS_VENDOR>-u-boot.dtsi
+   u-boot.dtsi
+
+U-Boot will only use the first one that it finds. If you need to include a
+more general file you can do that from the more specific file using #include.
+If you are having trouble figuring out what is going on, you can uncomment
+the 'warning' line in scripts/Makefile.lib to see what it has found:
+
+   # Uncomment for debugging
+   # $(warning binman_dtsi_options: $(binman_dtsi_options))
+
+
+Code coverage
+-------------
+
+Binman is a critical tool and is designed to be very testable. Entry
+implementations target 100% test coverage. Run 'binman -T' to check this.
+
+To enable Python test coverage on Debian-type distributions (e.g. Ubuntu):
+
+   $ sudo apt-get install python-pip python-pytest
+   $ sudo pip install coverage
+
+
 Advanced Features / Technical docs
 ----------------------------------
 
-- 
2.8.0.rc3.226.g39d4020