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
diff --git a/docs/firmware-design.md b/docs/firmware-design.md
index 6161b52..e952617 100644
--- a/docs/firmware-design.md
+++ b/docs/firmware-design.md
@@ -778,7 +778,10 @@
 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
diff --git a/docs/porting-guide.md b/docs/porting-guide.md
index ae5e720..7831a27 100644
--- a/docs/porting-guide.md
+++ b/docs/porting-guide.md
@@ -16,8 +16,9 @@
     *   PSCI implementation (in BL3-1)
     *   Interrupt Management framework (in BL3-1)
     *   Crash Reporting mechanism (in BL3-1)
-4.  C Library
-5.  Storage abstraction layer
+4.  Build flags
+5.  C Library
+6.  Storage abstraction layer
 
 - - - - - - - - - - - - - - - - - -
 
@@ -1332,7 +1333,26 @@
 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 @@
     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
diff --git a/docs/user-guide.md b/docs/user-guide.md
index 5192f9e..d3a92f9 100644
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -136,6 +136,16 @@
 
         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 @@
     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
-    `fip` target.
+*   `BL33`: Path to BL3-3 image in the host file system. This is mandatory for
+    `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.