Replace fip_create with fiptool

fiptool provides a more consistent and intuitive interface compared to
the fip_create program.  It serves as a better base to build on more
features in the future.

fiptool supports various subcommands.  Below are the currently
supported subcommands:

1) info   - List the images contained in a FIP file.
2) create - Create a new FIP file with the given images.
3) update - Update an existing FIP with the given images.
4) unpack - Extract a selected set or all the images from a FIP file.
5) remove - Remove images from a FIP file.  This is a new command that
   was not present in fip_create.

To create a new FIP file, replace "fip_create" with "fiptool create".

To update a FIP file, replace "fip_create" with "fiptool update".

To dump the contents of a FIP file, replace "fip_create --dump" with
"fiptool info".

A compatibility script that emulates the basic functionality of
fip_create is provided.  Existing scripts might or might not work with
the compatibility script.  Users are strongly encouraged to migrate to
fiptool.

Fixes ARM-Software/tf-issues#87
Fixes ARM-Software/tf-issues#108
Fixes ARM-Software/tf-issues#361

Change-Id: I7ee4da7ac60179cc83cf46af890fd8bc61a53330

3 files changed, 40 insertions, 14 deletions

diff --git a/docs/firmware-design.md b/docs/firmware-design.md
index 294349d9..74ea5eb8 100644
--- a/docs/firmware-design.md
+++ b/docs/firmware-design.md
@@ -1511,11 +1511,16 @@ The ToC header and entry formats are described in the header file
 ARM Trusted firmware.
 
 The ToC header has the following fields:
+
     `name`: The name of the ToC. This is currently used to validate the header.
     `serial_number`: A non-zero number provided by the creation tool
-    `flags`: Flags associated with this data. None are yet defined.
+    `flags`: Flags associated with this data.
+        Bits 0-13: Reserved
+        Bits 32-47: Platform defined
+        Bits 48-63: Reserved
 
 A ToC entry has the following fields:
+
     `uuid`: All files are referred to by a pre-defined Universally Unique
         IDentifier [UUID] . The UUIDs are defined in
         `include/firmware_image_package`. The platform translates the requested
@@ -1532,7 +1537,7 @@ that can be loaded by the ARM Trusted Firmware from platform storage. The tool
 currently only supports packing bootloader images. Additional image definitions
 can be added to the tool as required.
 
-The tool can be found in `tools/fip_create`.
+The tool can be found in `tools/fiptool`.
 
 ### Loading from a Firmware Image Package (FIP)
 
diff --git a/docs/trusted-board-boot.md b/docs/trusted-board-boot.md
index f076cd3b..833b5dbf 100644
--- a/docs/trusted-board-boot.md
+++ b/docs/trusted-board-boot.md
@@ -229,7 +229,7 @@ Trusted Firmware build process when `GENERATE_COT=1`. It takes the boot loader
 images and keys as inputs (keys must be in PEM format) and generates the
 certificates (in DER format) required to establish the CoT. New keys can be
 generated by the tool in case they are not provided. The certificates are then
-passed as inputs to the `fip_create` tool for creating the FIP.
+passed as inputs to the `fiptool` utility for creating the FIP.
 
 The certificates are also stored individually in the in the output build
 directory.
diff --git a/docs/user-guide.md b/docs/user-guide.md
index 41a272fa..0f3c9994 100644
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -269,7 +269,7 @@ performed.
 
 *   `GENERATE_COT`: Boolean flag used to build and execute the `cert_create`
     tool to create certificates as per the Chain of Trust described in
-    [Trusted Board Boot].  The build system then calls the `fip_create` tool to
+    [Trusted Board Boot].  The build system then calls `fiptool` to
     include the certificates in the FIP and FWU_FIP. Default value is '0'.
 
     Specify both `TRUSTED_BOARD_BOOT=1` and `GENERATE_COT=1` to include support
@@ -628,7 +628,7 @@ steps:
 
 It is recommended to remove old artifacts before building the tool:
 
-    make -C tools/fip_create clean
+    make -C tools/fiptool clean
 
 Build the tool:
 
@@ -636,37 +636,58 @@ Build the tool:
 
 The tool binary can be located in:
 
-    ./tools/fip_create/fip_create
+    ./tools/fiptool/fiptool
 
 Invoking the tool with `--help` will print a help message with all available
 options.
 
 Example 1: create a new Firmware package `fip.bin` that contains BL2 and BL31:
 
-    ./tools/fip_create/fip_create \
+    ./tools/fiptool/fiptool create \
         --tb-fw build/<platform>/<build-type>/bl2.bin \
         --soc-fw build/<platform>/<build-type>/bl31.bin \
         fip.bin
 
 Example 2: view the contents of an existing Firmware package:
 
-    ./tools/fip_create/fip_create --dump <path-to>/fip.bin
+    ./tools/fiptool/fiptool info <path-to>/fip.bin
 
 Example 3: update the entries of an existing Firmware package:
 
     # Change the BL2 from Debug to Release version
-    ./tools/fip_create/fip_create \
+    ./tools/fiptool/fiptool update \
         --tb-fw build/<platform>/release/bl2.bin \
         build/<platform>/debug/fip.bin
 
 Example 4: unpack all entries from an existing Firmware package:
 
     # Images will be unpacked to the working directory
-    ./tools/fip_create/fip_create --unpack <path-to>/fip.bin
+    ./tools/fiptool/fiptool unpack <path-to>/fip.bin
+
+Example 5: remove an entry from an existing Firmware package:
+
+    ./tools/fiptool/fiptool remove \
+        --tb-fw build/<platform>/debug/fip.bin
+
+Note that if the destination FIP file exists, the create, update and
+remove operations will automatically overwrite it.
+
+The unpack operation will fail if the images already exist at the
+destination.  In that case, use -f or --force to continue.
 
 More information about FIP can be found in the [Firmware Design document]
 [Firmware Design].
 
+#### Migrating from fip_create to fiptool
+
+The previous version of fiptool was called fip_create.  A compatibility script
+that emulates the basic functionality of the previous fip_create is provided.
+However, users are strongly encouraged to migrate to fiptool.
+
+*   To create a new FIP file, replace "fip_create" with "fiptool create".
+*   To update a FIP file, replace "fip_create" with "fiptool update".
+*   To dump the contents of a FIP file, replace "fip_create --dump"
+    with "fiptool info".
 
 ### Building FIP images with support for Trusted Board Boot
 
@@ -798,21 +819,21 @@ corrupted binaries.
 
 2.  Obtain SCP_BL2 (Juno) and BL33 (all platforms)
 
-    Use the fip_create tool to extract the SCP_BL2 and BL33 images from the FIP
+    Use the fiptool to extract the SCP_BL2 and BL33 images from the FIP
     package included in the Linaro release:
 
-        # Build the fip_create tool
+        # Build the fiptool
         make [DEBUG=1] [V=1] fiptool
 
         # Unpack firmware images from Linaro FIP
-        ./tools/fip_create/fip_create --unpack \
+        ./tools/fiptool/fiptool unpack \
              <path/to/linaro/release>/fip.bin
 
     The unpack operation will result in a set of binary images extracted to the
     working directory. The SCP_BL2 image corresponds to `scp-fw.bin` and BL33
     corresponds to `nt-fw.bin`.
 
-    Note: the fip_create tool will complain if the images to be unpacked already
+    Note: the fiptool will complain if the images to be unpacked already
     exist in the current directory. If that is the case, either delete those
     files or use the `--force` option to overwrite.