[Buildroot] [RFC 0/2] uboot: add u-boot.pbl support

[Buildroot] [RFC 0/2] uboot: add u-boot.pbl support

[Ryan Barnett]

This patchset introduces support for generating a u-boot.pbl image
format in u-boot. The u-boot.pbl image format is used by the Freescale???s
QorIQ series of processors for in a non-NOR flash based boot
configuration. It also adds support to u-boot to generate a Reset
Configuration Word (RCW) binary file ??? RCW.bin. Customization of the
RCW can be one of two methods ??? using Freescale???s QorIQ Configuration
Suite (QCS) or by .cfg format specified by docs/README.pblimage in the
U-Boot source.

NOTE: u-boot.pbl format doesn't work in a SD configuration for
U-Boot 2013.10.

Some notes on design decisions:

 * For generating a RCW.bin ??? BR2_TARGET_UBOOT_RCW_BIN ??? I chose to
   only support generating this file using Freescale???s QCS because that
   is the recommended way of customizing the RCW by Freescale. There is
   another tool that Freescale provides - RCW.py - which you can use to
   generate the the RCW.bin from text file configurations. I will
   eventually look to add this package to buildroot but for now
   generating a RCW.bin in buildroot will be supported by exporting a
   'Hex String' configuration file from the QCS tool.

   Freescale???s RCW.py:
   http://git.freescale.com/git/cgit.cgi/ppc/sdk/rcw.git

 * I have not decided the best location for documentation on how to use
   this feature in the buildroot manual. For now, I will just include it
   in this cover letter with the intention that I move it in future
   version of the patch to somewhere in the manual once I???ve gotten
   feedback on the location to put this. I think maybe the
   ???deploying images??? location might be best suited for this which is
   under review currently.

Documentation
================================================

Freescale U-Boot QorIQ Support
------------------------------
The Freescale QorIQ series of processors can boot directly from eSPI FLASH,
SD/MMC and NAND, etc. These SoCs use a Pre-Boot Loader (PBL) to load
Reset Configuration Word (RCW) and/or pre-initialization instructions
(PBI). In order to boot in a boot configuration other than NOR Flash, a
specially packaged u-boot binary file is need - u-boot.pbl. For more
details on the PBL, refer to chapter 5 "Pre-Boot Loader" of reference
manual P2040RM/P3041RM/P4080RM/P5020RM at link:

http://www.freescale.com/webapp/search/Serp.jsp?Reference+Manuals

For more details on u-boot.pbl, please refer to +docs/README.pbl+ in
the u-boot source:

http://git.denx.de/cgi-bin/gitweb.cgi?p=u-boot.git;a=blob_plain;f=doc/README.pblimage;hb=HEAD

Buildroot Options
~~~~~~~~~~~~~~~~~
Support for generating u-boot.pbl is available in the U-Boot package
using +BR2_TARGET_UBOOT_FORMAT_PBL+. The U-Boot also has support for
customizing the RCW/PBI utilizing one of the formats.

 * A combination of two configurations files - rcw.cfg and pbi.cfg - in
 the format specified by +docs/README.pblimage+.

 * A +Hex String+ file exported from Freescale's QCS

The U-Boot package also has support for generating a RCW.bin file when
the u-boot.bin format is selected. A custom configuration must be
specified when this option is selected. The only format that is support
is a +Hex String+ file exported from QCS.

Exporting Custom PBL from Freescale's QCS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Please refer to Freescale's documentation on "PBL Configuration Tool
User Guide" for using QCS customize the PBL settings:

http://www.freescale.com/infocenter/topic/qcs/qcspbl.html

The format that is required for the PBL to exported as is the
+Hex String+ which is specified in the Output File Type. Please refer
to Appendix B of the PBL Configuration Tool User Guide for more
information about this file type.

http://www.freescale.com/infocenter/topic/qcs_pbl_ug/4402240.html

Ryan Barnett (2):
  host-xxd: new package
  uboot: introduce u-boot.pbl format

 boot/uboot/Config.in       |   94 ++++++++++++++++++++++++++++++++++++
 boot/uboot/uboot.mk        |  114 ++++++++++++++++++++++++++++++++++++++++++++
 package/Config.in.host     |    1 +
 package/xxd/Config.in.host |    6 ++
 package/xxd/xxd.mk         |   20 ++++++++
 5 files changed, 235 insertions(+), 0 deletions(-)
 create mode 100644 package/xxd/Config.in.host
 create mode 100644 package/xxd/xxd.mk

[Buildroot] [RFC 1/2] host-xxd: new package

[Ryan Barnett]

Signed-off-by: Ryan Barnett <rjbarnet@rockwellcollins.com>
---
 package/Config.in.host     |    1 +
 package/xxd/Config.in.host |    6 ++++++
 package/xxd/xxd.mk         |   20 ++++++++++++++++++++
 3 files changed, 27 insertions(+), 0 deletions(-)
 create mode 100644 package/xxd/Config.in.host
 create mode 100644 package/xxd/xxd.mk

diff --git a/package/Config.in.host b/package/Config.in.host
index 5fd2570..a80aee7 100644
--- a/package/Config.in.host
+++ b/package/Config.in.host
@@ -13,5 +13,6 @@ source "package/openocd/Config.in.host"
 source "package/sam-ba/Config.in.host"
 source "package/sunxi-tools/Config.in.host"
 source "package/uboot-tools/Config.in.host"
+source "package/xxd/Config.in.host"
 
 endmenu
diff --git a/package/xxd/Config.in.host b/package/xxd/Config.in.host
new file mode 100644
index 0000000..c2cddde
--- /dev/null
+++ b/package/xxd/Config.in.host
@@ -0,0 +1,6 @@
+config BR2_PACKAGE_XXD
+	bool "host xxd"
+	help
+	  xxd creates a hex dump of a given file or standard input
+
+	  http://linux.die.net/man/1/xxd
diff --git a/package/xxd/xxd.mk b/package/xxd/xxd.mk
new file mode 100644
index 0000000..a960f86
--- /dev/null
+++ b/package/xxd/xxd.mk
@@ -0,0 +1,20 @@
+################################################################################
+#
+# xxd
+#
+################################################################################
+
+XXD_VERSION = 1.10
+XXD_SITE    = http://grail.cba.csuohio.edu/~somos
+XXD_LICENSE = Public Domain
+XXD_LICENSE_FILES = xxd.c
+
+define HOST_XXD_BUILD_CMDS
+	$(HOST_MAKE_ENV) $(MAKE) -C $(@D)
+endef
+
+define HOST_XXD_INSTALL_CMDS
+	$(INSTALL) -m 0755 -D $(@D)/xxd $(HOST_DIR)/usr/bin/xxd
+endef
+
+$(eval $(host-generic-package))
-- 
1.7.1

[Buildroot] [RFC 2/2] uboot: introduce u-boot.pbl format

[Ryan Barnett]

This commit introduces support for the u-boot.pbl image format. The
u-boot.pbl is a special U-Boot image that supports booting directly
from eSPI FLASH, SD/MMC and NAND, etc for Freescale's CoreNet SoC's.
These SoCs use PBL (Pre-Boot Loader) to load RCW (Reset Configuration
Word) and/or pre-initialization instructions (PBI). For more details
refer section 5 Pre-boot loader specifications of reference manual
P2040RM/P3041RM/P4080RM/P5020RM at link:

http://www.freescale.com/webapp/search/Serp.jsp?Reference+Manuals

In details, this commit:

 * Introduces the BR2_TARGET_UBOOT_FORMAT_PBL menuconfig option which
   will generate a u-boot.pbl image.

 * Allows customization of the PBL through the use of menuconfig
   options - BR2_TARGET_UBOOT_PBL_CUSTOM and it sub-options. The two
   file formats that are support for customizing these files are the
   '.cfg' format which is specified by docs/README.pblimage in the
   u-boot source - BR2_TARGET_UBOOT_PBL_CUSTOM_RCW_FILE and
   BR2_TARGET_UBOOT_PBL_CUSTOM_PBI_FILE -  and a 'Hex String' file
   which has been exported from  Freescales's Processor Expert tool
   (PE Tool) - BR2_TARGET_UBOOT_PBL_CUSTOM_PE_TOOL_FILE.

 * Allows for the generatation of an RCW.bin file that can be used
   with a u-boot.bin file for NOR based booting configuration. A
   custom PBL configuration must be specified via
   BR2_TARGET_UBOOT_PBL_CUSTOM_PE_TOOL_FILE

Signed-off-by: Ryan Barnett <rjbarnet@rockwellcollins.com>
---
 boot/uboot/Config.in |   94 +++++++++++++++++++++++++++++++++++++++++
 boot/uboot/uboot.mk  |  114 ++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 208 insertions(+), 0 deletions(-)

diff --git a/boot/uboot/Config.in b/boot/uboot/Config.in
index 7a20d06..cc4ba64 100644
--- a/boot/uboot/Config.in
+++ b/boot/uboot/Config.in
@@ -108,6 +108,18 @@ config BR2_TARGET_UBOOT_FORMAT_SB
 	depends on BR2_arm
 	bool "u-boot.sb"
 
+config BR2_TARGET_UBOOT_FORMAT_PBL
+	depends on BR2_powerpc_e500mc
+	bool "u-boot.pbl"
+	help
+	  PBL (Pre-Boot Loader) is the first stage bootloader for
+	  Freescale QorIQ processors. The u-boot.pbl (RCW+PBI+UBOOT)
+	  gives the ability for the PBL to boot from a non-NOR flash
+	  configuration.
+
+	  Refer to doc/README.pblimage in the u-boot source for
+	  more details.
+
 config BR2_TARGET_UBOOT_FORMAT_CUSTOM
 	bool "Custom (specify below)"
 	help
@@ -221,6 +233,88 @@ config BR2_TARGET_UBOOT_SPL_NAME
 	  u-boot build. For most platform it is u-boot-spl.bin
 	  but not always. It is MLO on OMAP for example.
 
+config BR2_TARGET_UBOOT_RCW_BIN
+	bool "Generate Freescale RCW Binary"
+	depends on BR2_TARGET_UBOOT_FORMAT_BIN
+	depends on BR2_powerpc_e500mc
+	# Must specify the custom config files to generate a RCW.bin
+	select BR2_TARGET_UBOOT_PBL_CUSTOM
+	help
+	  Generate a Reset Configuration Word (RCW) binary file
+	  for Freescale's QorIQ series of processors. Check your
+	  chips documentation for details.
+
+	  The RCW and the Pre-Boot Loader instructions will be
+	  generated as a stand-alone binary file - RCW.bin. This
+	  format is used for NOR flash booting.
+
+	  See the buildroot manual for more information on
+	  Freescale's PBL support in buildroot.
+
+menuconfig BR2_TARGET_UBOOT_PBL_CUSTOM
+	bool "Freescale PBL Custom Configuration"
+	depends on BR2_TARGET_UBOOT_FORMAT_PBL || BR2_TARGET_UBOOT_RCW_BIN
+	help
+	  Use custom configuration files to produce an image of
+	  u-boot.pbl or PBL.bin for Freescale's QorIQ series of
+	  processors that contains the RCW and the Pre-Boot Loader
+	  instructions.
+
+	  See the buildroot manual for more information on
+	  Freescale's PBL support in buildroot.
+
+if BR2_TARGET_UBOOT_PBL_CUSTOM
+
+choice
+	prompt "Custom PBL Config Input Type"
+	default BR2_TARGET_UBOOT_PBL_CUST_FORMAT_PETOOL
+
+config BR2_TARGET_UBOOT_PBL_CUST_FORMAT_PETOOL
+	bool "Use Freescale PE Tool File Format"
+	help
+	  Freescale PBL configuration from an exported file from
+	  Freescale's Processor Expert Tool in the 'Hex String'
+	  format.
+
+config BR2_TARGET_UBOOT_PBL_CUST_FORMAT_UBOOT
+	bool "Use U-Boot PBL Config Format"
+	depends on BR2_TARGET_UBOOT_FORMAT_PBL
+	help
+	  Freescale PBL configuration done using a rcw.cfg and
+	  pbi.cfg files. The format of these files is explained
+	  by docs/README.pblimage in the U-Boot source.
+
+endchoice
+
+config BR2_TARGET_UBOOT_PBL_CUSTOM_PE_TOOL_FILE
+	string "Custom PE Tool Hex String File"
+	depends on BR2_TARGET_UBOOT_PBL_CUST_FORMAT_PETOOL
+	help
+	  Specify a custom Freescale Processor Expert exported
+	  hex string file. Please see the buildroot manual and
+	  Freescale's QorIQ Configuration Suite documentation
+	  for more information on how to export this file type.
+
+config BR2_TARGET_UBOOT_PBL_CUSTOM_RCW_FILE
+	string "Custom RCW.cfg File"
+	depends on BR2_TARGET_UBOOT_PBL_CUST_FORMAT_UBOOT
+	help
+	  The Reset Configuration Word config file - rcw.cfg
+
+	  See docs/README.pblimage for more informatin on the
+	  format of this file.
+
+config BR2_TARGET_UBOOT_PBL_CUSTOM_PBI_FILE
+	string "Custom PBI.cfg File"
+	depends on BR2_TARGET_UBOOT_PBL_CUST_FORMAT_UBOOT
+	help
+	  The Pre-Boot Loader Instructions config file - pbi.cfg
+
+	  See docs/README.pblimage for more informatin on the
+	  format of this file.
+
+endif # BR2_TARGET_UBOOT_PBL_CUSTOM
+
 menuconfig BR2_TARGET_UBOOT_ENVIMAGE
 	bool "Environment image"
 	help
diff --git a/boot/uboot/uboot.mk b/boot/uboot/uboot.mk
index dc8e26f..f4a4001 100644
--- a/boot/uboot/uboot.mk
+++ b/boot/uboot/uboot.mk
@@ -46,6 +46,9 @@ else ifeq ($(BR2_TARGET_UBOOT_FORMAT_SB),y)
 UBOOT_BIN          = u-boot.sb
 UBOOT_MAKE_TARGET  = $(UBOOT_BIN)
 UBOOT_DEPENDENCIES += host-elftosb
+else ifeq ($(BR2_TARGET_UBOOT_FORMAT_PBL),y)
+UBOOT_BIN          = u-boot.pbl
+UBOOT_MAKE_TARGET  = $(UBOOT_BIN)
 else ifeq ($(BR2_TARGET_UBOOT_FORMAT_CUSTOM),y)
 UBOOT_BIN          = $(call qstrip,$(BR2_TARGET_UBOOT_FORMAT_CUSTOM_NAME))
 else
@@ -139,6 +142,117 @@ UBOOT_POST_BUILD_HOOKS += UBOOT_BUILD_OMAP_IFT
 UBOOT_POST_INSTALL_IMAGES_HOOKS += UBOOT_INSTALL_OMAP_IFT_IMAGE
 endif
 
+# Handling for the customization of the PBL file format.
+ifeq ($(BR2_TARGET_UBOOT_PBL_CUSTOM),y)
+# qstrip versions of menuconfig options
+UBOOT_CUST_RCW_FILE    = $(call qstrip,$(BR2_TARGET_UBOOT_PBL_CUSTOM_RCW_FILE))
+UBOOT_CUST_PBI_FILE    = $(call qstrip,$(BR2_TARGET_UBOOT_PBL_CUSTOM_PBI_FILE))
+UBOOT_CUST_PETOOL_FILE = $(call qstrip,$(BR2_TARGET_UBOOT_PBL_CUSTOM_PE_TOOL_FILE))
+
+# Temporary location of the PBL configuration files
+UBOOT_PBLRCW_FILE = $(@D)/rcw.cfg
+UBOOT_PBLPBI_FILE = $(@D)/pbi.cfg
+UBOOT_RCWBIN_FILE = $(@D)/RCW.bin
+
+# Handle custom u-boot pbl config files
+ifeq ($(BR2_TARGET_UBOOT_PBL_CUST_FORMAT_UBOOT),y)
+
+# we NEED config files unless we're at make source
+ifeq ($(filter source,$(MAKECMDGOALS)),)
+ifeq ($(UBOOT_CUST_RCW_FILE),)
+$(error No rcw.cfg config file. Check your BR2_TARGET_UBOOT_PBL_CUSTOM_RCW_FILE setting)
+endif
+ifeq ($(wildcard $(UBOOT_CUST_RCW_FILE)),)
+$(error rcw.cfg config file $(BR2_TARGET_UBOOT_PBL_CUSTOM_RCW_FILE) not found. Check your BR2_TARGET_UBOOT_PBL_CUSTOM_RCW_FILE setting)
+endif
+ifeq ($(UBOOT_CUST_PBI_FILE),)
+$(error No pbi.cfg config file. Check your BR2_TARGET_UBOOT_PBL_CUSTOM_PBI_FILE setting)
+endif
+ifeq ($(wildcard $(UBOOT_CUST_PBI_FILE)),)
+$(error pbi.cfg config file $(BR2_TARGET_UBOOT_PBL_CUSTOM_PBI_FILE) not found. Check your BR2_TARGET_UBOOT_PBL_CUSTOM_PBI_FILE setting)
+endif
+endif # MAKECMDGOALS
+
+# Copy the specified configuration files to holding location
+define UBOOT_CONFIGURE_COPY_CUST_FILES
+	@$(call MESSAGE,"Pre-Configure Hook: Copy Custom PBL Configs")
+	cp -dpf "$(UBOOT_CUST_RCW_FILE)" "$(UBOOT_PBLRCW_FILE)"
+	cp -dpf "$(UBOOT_CUST_PBI_FILE)" "$(UBOOT_PBLPBI_FILE)"
+endef
+UBOOT_PRE_CONFIGURE_HOOKS += UBOOT_CONFIGURE_COPY_CUST_FILES
+endif # BR2_TARGET_UBOOT_PBL_CUST_FORMAT_UBOOT
+
+# Handle custom PBL config file from PE Tool
+ifeq ($(BR2_TARGET_UBOOT_PBL_CUST_FORMAT_PETOOL),y)
+
+# we NEED config file unless we're at make source
+ifeq ($(filter source,$(MAKECMDGOALS)),)
+ifeq ($(UBOOT_CUST_PETOOL_FILE),)
+$(error No PE Tool config file. Check your BR2_TARGET_UBOOT_PBL_CUSTOM_PE_TOOL_FILE setting)
+endif
+ifeq ($(wildcard $(UBOOT_CUST_PETOOL_FILE)),)
+$(error PE Tool config file $(BR2_TARGET_UBOOT_PBL_CUSTOM_PE_TOOL_FILE) not found. Check your BR2_TARGET_UBOOT_PBL_CUSTOM_PE_TOOL_FILE setting)
+endif
+endif # MAKECMDGOALS
+
+# Generate U-Boot PBL config file format from PE Tool Config
+define UBOOT_CONFIGURE_GEN_UBOOT_PBL_CONFIG
+	@$(call MESSAGE,"Pre-Configure Hook: Generate U-Boot PBL Config from PE Tool")
+	@# Extracting the first 144 bytes as they are the RCW
+	cat "$(UBOOT_CUST_PETOOL_FILE)" | sed '/^$$/d' | cut -c 1-144 | \
+		sed 's/\(.\{8\}\)/\1 /g' > $(UBOOT_PBLRCW_FILE)
+	@# The next bytes are the Pre-Boot Initialization commands which
+	@# start at the after byte 144. However, the HEX string contains
+	@# a checksum at the end (16 characters) + 1 line feed char, remove
+	@# them and what is left are the PBI commands.
+	pbi=$$(cat "$(UBOOT_CUST_PETOOL_FILE)" | sed '/^$$/d' | cut -c 145- | \
+		sed 's/.\{17\}$$//' | sed 's/\(.\{8\}\)/\1 /g'); \
+	if [ ! -z "$$pbi" ]; then \
+		echo $$pbi > $(UBOOT_PBLPBI_FILE); \
+	else \
+		rm -f $(UBOOT_PBLPBI_FILE); \
+		touch $(UBOOT_PBLPBI_FILE); \
+	fi
+endef # UBOOT_CONFIGURE_GEN_UBOOT_PBL_CONFIG
+UBOOT_PRE_CONFIGURE_HOOKS += UBOOT_CONFIGURE_GEN_UBOOT_PBL_CONFIG
+
+endif # BR2_TARGET_UBOOT_PBL_CUST_FORMAT_PETOOL
+
+# Insert custom config files to to config.h since u-boot.pbl is used
+ifeq ($(BR2_TARGET_UBOOT_FORMAT_PBL),y)
+# We need to have u-boot use our custom PBL config files
+define UBOOT_CONFIGURE_PBL_CUST_FILE
+	@$(call MESSAGE,"Post-Configure Hook: Add new PBL config files")
+	$(call insert_define,CONFIG_PBLPBI_CONFIG,$(UBOOT_PBLPBI_FILE))
+	$(call insert_define,CONFIG_PBLRCW_CONFIG,$(UBOOT_PBLRCW_FILE))
+endef
+UBOOT_POST_CONFIGURE_HOOKS += UBOOT_CONFIGURE_PBL_CUST_FILE
+endif # BR2_TARGET_UBOOT_FORMAT_PBL
+
+# Handling the building of the RCW.bin (seperate from u-boot)
+ifeq ($(BR2_TARGET_UBOOT_RCW_BIN),y)
+
+# Build RCW.bin
+# The assumption can be made that the configuraiton file type
+# will be in the PE Tool format since menuconfig restricts this
+define UBOOT_BUILD_RCW_BIN
+	@$(call MESSAGE, "Post-Build Hook: Generate RCW.bin")
+	cat "$(UBOOT_CUST_PETOOL_FILE)" | \
+		 $(HOST_DIR)/usr/bin/xxd -r -p > $(UBOOT_RCWBIN_FILE)
+endef
+UBOOT_DEPENDENCIES += host-xxd
+UBOOT_POST_BUILD_HOOKS += UBOOT_BUILD_RCW_BIN
+
+# Install the RCW.bin to binaries dir
+define UBOOT_INSTALL_PBL_BIN
+	$(INSTALL) -D -m 0644 $(UBOOT_RCWBIN_FILE) $(BINARIES_DIR)/RCW.bin
+endef
+UBOOT_POST_INSTALL_IMAGES_HOOKS += UBOOT_INSTALL_PBL_BIN
+
+endif # BR2_TARGET_UBOOT_RCW_BIN
+
+endif # BR2_TARGET_UBOOT_PBL_CUSTOM
+
 ifeq ($(BR2_TARGET_UBOOT_ENVIMAGE),y)
 # we NEED a environment settings unless we're at make source
 ifeq ($(filter source,$(MAKECMDGOALS)),)
-- 
1.7.1

[Buildroot] [RFC 0/2] uboot: add u-boot.pbl support

[Thomas Petazzoni]

Hello all,

On Thu, 24 Oct 2013 10:24:24 -0500, Ryan Barnett wrote:
> This patchset introduces support for generating a u-boot.pbl image
> format in u-boot. The u-boot.pbl image format is used by the Freescale?s
> QorIQ series of processors for in a non-NOR flash based boot
> configuration. It also adds support to u-boot to generate a Reset
> Configuration Word (RCW) binary file ? RCW.bin. Customization of the
> RCW can be one of two methods ? using Freescale?s QorIQ Configuration
> Suite (QCS) or by .cfg format specified by docs/README.pblimage in the
> U-Boot source.

[...]

FWIW, I've looked at this code and discussed it with Ryan. The first
thing is that it adds too much stuff in uboot/uboot.mk and
uboot/Config.in, so I've created a patch that moves platform-specific
stuff into other .mk and Config.in files within boot/uboot/, on top of
which I've changed Ryan's patch. It makes things more reasonable I
believe.

See:

   http://git.free-electrons.com/users/thomas-petazzoni/buildroot/log/?h=uboot-arch-spec

However, I've asked Ryan to take some significant portions of his cover
letter, and use that to extend the Config.in help text to explain how
this thing can/should be used, and under what conditions.

I guess Ryan will resubmit the set of 3 patches when he is done with
this Config.in help text writing.

Best regards,

Thomas
-- 
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com