Add support for specifying pre-built BL binaries in Makefile

This patch adds support for supplying pre-built BL binaries for BL2,
BL3-1 and BL3-2 during trusted firmware build. Specifying BLx = <path_to_BLx>
in the build command line, where 'x' is any one of BL2, BL3-1 or BL3-2, will
skip building that BL stage from source and include the specified binary in
final fip image.

This patch also makes BL3-3 binary for FIP optional depending on the
value of 'NEED_BL33' flag which is defined by the platform.

Fixes ARM-software/tf-issues#244
Fixes ARM-software/tf-issues#245

Change-Id: I3ebe1d4901f8b857e8bb51372290978a3323bfe7

Makefile

@@ -150,6 +150,9 @@ endif
 ifdef BL2_SOURCES
 NEED_BL2 := yes
 include bl2/bl2.mk
+# Using the ARM Trusted Firmware BL2 implies that a BL3-3 image also need to be supplied for the FIP.
+# This flag can be overridden by the platform.
+NEED_BL33 ?= yes
 endif
 
 ifdef BL31_SOURCES
@@ -168,9 +171,10 @@ ifneq (${SPD},none)
   $(info Including ${SPD_MAKE})
   include ${SPD_MAKE}
 
-  # If there's BL32 companion for the chosen SPD, and the SPD wants to build the
+  # If there's BL3-2 companion for the chosen SPD, and the SPD wants to build the
-  # BL2 from source, we expect that the SPD's Makefile would set NEED_BL32
+  # BL3-2 from source, we expect that the SPD's Makefile would set NEED_BL32
-  # variable to "yes"
+  # variable to "yes". In case the BL3-2 is a binary which needs to be included in
+  # fip, then the NEED_BL32 needs to be set and BL3-2 would need to point to the bin.
 endif
 
 .PHONY:			all msg_start clean realclean distclean cscope locate-checkpatch checkcodebase checkpatch fiptool fip
@@ -438,39 +442,53 @@ $(eval $(call MAKE_BL,1))
 endif
 
 ifeq (${NEED_BL2},yes)
-$(eval $(call MAKE_BL,2,in_fip))
+$(if ${BL2}, $(eval FIP_DEPS += ${BL2}) $(eval FIP_ARGS += --bl2 ${BL2}),\
+	$(eval $(call MAKE_BL,2,in_fip)))
 endif
 
 ifeq (${NEED_BL31},yes)
 BL31_SOURCES += ${SPD_SOURCES}
-$(eval $(call MAKE_BL,31,in_fip))
+$(if ${BL31}, $(eval FIP_DEPS += ${BL31}) $(eval FIP_ARGS += --bl31 ${BL31}),\
+	$(eval $(call MAKE_BL,31,in_fip)))
 endif
 
 ifeq (${NEED_BL32},yes)
-$(eval $(call MAKE_BL,32,in_fip))
+$(if ${BL32}, $(eval FIP_DEPS += ${BL32}) $(eval FIP_ARGS += --bl32 ${BL32}),\
+	$(eval $(call MAKE_BL,32,in_fip)))
 endif
 
 ifeq (${NEED_BL30},yes)
-FIP_DEPS += ${BL30}
+$(if ${BL30}, $(eval FIP_DEPS += ${BL30}) $(eval FIP_ARGS += --bl30 ${BL30}), )
-FIP_ARGS += --bl30 ${BL30}
-endif
 
-ifeq (${NEED_BL30},yes)
 # If BL3-0 is needed by the platform then 'BL30' variable must be defined.
 check_bl30:
 	$(if ${BL30},,$(error "To build a FIP for platform ${PLAT}, please set BL30 to point to the SCP firmware"))
 else
+
 # If BL3-0 is not needed by the platform but the user still specified the path
 # to a BL3-0 image then warn him that it will be ignored.
 check_bl30:
 	$(if ${BL30},$(warning "BL3-0 is not supported on platform ${PLAT}, it will just be ignored"),)
 endif
 
-${BUILD_PLAT}/fip.bin: ${FIP_DEPS} ${BL33} ${FIPTOOL} check_bl30
+ifeq (${NEED_BL33},yes)
+$(if ${BL33}, $(eval FIP_DEPS += ${BL33}) $(eval FIP_ARGS += --bl33 ${BL33}), )
+
+# If BL3-3 is needed by the platform then 'BL33' variable must be defined.
+check_bl33:
 	$(if ${BL33},,$(error "To build a FIP, please set BL33 to point to the Normal World binary, eg: BL33=../uefi/FVP_AARCH64_EFI.fd"))
+else
+
+# If BL3-3 is not needed by the platform but the user still specified the path
+# to a BL3-3 image then warn him that it will be ignored.
+check_bl33:
+	$(if ${BL33},$(warning "BL3-3 is not supported on platform ${PLAT}, it will just be ignored"),)
+endif
+
+
+${BUILD_PLAT}/fip.bin: ${FIP_DEPS} ${FIPTOOL} check_bl30 check_bl33
 			${Q}${FIPTOOL} --dump \
 				${FIP_ARGS} \
-				--bl33 ${BL33} \
 				$@
 			@echo
 			@echo "Built $@ successfully"

docs/firmware-design.md

@@ -778,7 +778,10 @@ The ARM Trusted Firmware provides a Test Secure-EL1 Payload (TSP) and a Test
 Secure-EL1 Payload Dispatcher (TSPD) service as an example of how a Trusted OS
 is supported on a production system using the Runtime Services Framework. On
 such a system, the Test BL3-2 image and service are replaced by the Trusted OS
-and its dispatcher service.
+and its dispatcher service. The ARM Trusted Firmware build system expects that
+the dispatcher will define the build flag `NEED_BL32` to enable it to include
+the BL3-2 in the build either as a binary or to compile from source depending
+on whether the `BL32` build option is specified or not.
 
 The TSP runs in Secure-EL1. It is designed to demonstrate synchronous
 communication with the normal-world software running in EL1/EL2. Communication

docs/porting-guide.md

@@ -16,8 +16,9 @@ Contents
     *   PSCI implementation (in BL3-1)
     *   Interrupt Management framework (in BL3-1)
     *   Crash Reporting mechanism (in BL3-1)
-4.  C Library
+4.  Build flags
-5.  Storage abstraction layer
+5.  C Library
+6.  Storage abstraction layer
 
 - - - - - - - - - - - - - - - - - -
 
@@ -1332,7 +1333,26 @@ register x0.
 The FVP port designates the `PL011_UART0` as the crash console and calls the
 console_core_putc() to print the character on the console.
 
-4.  C Library
+4.  Build flags
+---------------
+
+There are some build flags which can be defined by the platform to control
+inclusion or exclusion of certain BL stages from the FIP image. These flags
+need to be defined in the platform makefile which will get included by the
+build system.
+
+*   **NEED_BL30**
+    This flag if defined by the platform mandates that a BL3-0 binary should
+    be included in the FIP image. The path to the BL3-0 binary can be specified
+    by the `BL30` build option (see build options in the [User Guide]).
+
+*   **NEED_BL33**
+    By default, this flag is defined `yes` by the build system and `BL33`
+    build option should be supplied as a build option. The platform has the option
+    of excluding the BL3-3 image in the `fip` image by defining this flag to
+    `no`.
+
+5.  C Library
 -------------
 
 To avoid subtle toolchain behavioral dependencies, the header files provided
@@ -1369,7 +1389,7 @@ A copy of the [FreeBSD] sources can be downloaded with `git`.
     git clone git://github.com/freebsd/freebsd.git -b origin/release/9.2.0
 
 
-5.  Storage abstraction layer
+6.  Storage abstraction layer
 -----------------------------
 
 In order to improve platform independence and portability an storage abstraction

docs/user-guide.md

@@ -136,6 +136,16 @@ To build the Trusted Firmware images, follow these steps:
 
         make realclean
 
+7.  (Optional) Path to binary for certain BL stages (BL2, BL3-1 and BL3-2) can be
+    provided by specifying the BLx=<path-to>/<blx_image> where BLx is the BL stage.
+    This will bypass the build of the BL component from source, but will include
+    the specified binary in the final FIP image. Please note that BL3-2 will be
+    included in the build, only if the `SPD` build option is specified.
+
+    For example, specifying BL2=<path-to>/<bl2_image> in the build option, will
+    skip compilation of BL2 source in trusted firmware, but include the BL2
+    binary specified in the final FIP image.
+
 ### Summary of build options
 
 ARM Trusted Firmware build system supports the following build options. Unless
@@ -151,8 +161,20 @@ performed.
     If a BL3-0 image is present then this option must be passed for the `fip`
     target.
 
-*   `BL33`: Path to BL33 image in the host file system. This is mandatory for
+*   `BL33`: Path to BL3-3 image in the host file system. This is mandatory for
-    `fip` target.
+    `fip` target in case the BL2 from ARM Trusted Firmware is used.
+
+*   `BL2`: This is an optional build option which specifies the path to BL2
+    image for the `fip` target. In this case, the BL2 in the ARM Trusted
+    Firmware will not be built.
+
+*   `BL31`:  This is an optional build option which specifies the path to
+    BL3-1 image for the `fip` target. In this case, the BL3-1 in the ARM
+    Trusted Firmware will not be built.
+
+*   `BL32`:  This is an optional build option which specifies the path to
+    BL3-2 image for the `fip` target. In this case, the BL3-2 in the ARM
+    Trusted Firmware will not be built.
 
 *   `CROSS_COMPILE`: Prefix to toolchain binaries. Please refer to examples in
     this document for usage.