Merge pull request #661 from dp-arm/master

Replace fip_create with fiptool

.gitignore

@@ -10,13 +10,14 @@ build/
 
 # Ignore build products from tools
 tools/**/*.o
-tools/fip_create/fip_create
-tools/fip_create/fip_create.exe
+tools/fip_create/
+tools/fiptool/fiptool
+tools/fiptool/fiptool.exe
 tools/cert_create/src/*.o
 tools/cert_create/src/**/*.o
 tools/cert_create/cert_create
 tools/cert_create/cert_create.exe
 
 # Ignore header files copied.
-tools/fip_create/firmware_image_package.h
-tools/fip_create/uuid.h
+tools/fiptool/firmware_image_package.h
+tools/fiptool/uuid.h

Makefile

@@ -390,16 +390,16 @@ ENABLE_PMF			:= 1
 endif
 
 ################################################################################
-# Auxiliary tools (fip_create, cert_create, etc)
+# Auxiliary tools (fiptool, cert_create, etc)
 ################################################################################
 
 # Variables for use with Certificate Generation Tool
 CRTTOOLPATH		?=	tools/cert_create
 CRTTOOL			?=	${CRTTOOLPATH}/cert_create${BIN_EXT}
 
 # Variables for use with Firmware Image Package
-FIPTOOLPATH		?=	tools/fip_create
-FIPTOOL			?=	${FIPTOOLPATH}/fip_create${BIN_EXT}
+FIPTOOLPATH		?=	tools/fiptool
+FIPTOOL			?=	${FIPTOOLPATH}/fiptool${BIN_EXT}
 
 
 ################################################################################
@@ -613,7 +613,8 @@ certificates: ${CRT_DEPS} ${CRTTOOL}
 endif
 
 ${BUILD_PLAT}/${FIP_NAME}: ${FIP_DEPS} ${FIPTOOL}
-	${Q}${FIPTOOL} --dump ${FIP_ARGS} $@
+	${Q}${FIPTOOL} create ${FIP_ARGS} $@
+	${Q}${FIPTOOL} info $@
 	@${ECHO_BLANK_LINE}
 	@echo "Built $@ successfully"
 	@${ECHO_BLANK_LINE}
@@ -628,7 +629,8 @@ fwu_certificates: ${FWU_CRT_DEPS} ${CRTTOOL}
 endif
 
 ${BUILD_PLAT}/${FWU_FIP_NAME}: ${FWU_FIP_DEPS} ${FIPTOOL}
-	${Q}${FIPTOOL} --dump ${FWU_FIP_ARGS} $@
+	${Q}${FIPTOOL} create ${FWU_FIP_ARGS} $@
+	${Q}${FIPTOOL} info $@
 	@echo
 	@echo "Built $@ successfully"
 	@echo
@@ -639,7 +641,7 @@ fwu_fip: ${BUILD_PLAT}/${FWU_FIP_NAME}
 
 .PHONY: ${FIPTOOL}
 ${FIPTOOL}:
-	${Q}${MAKE} --no-print-directory -C ${FIPTOOLPATH}
+	${Q}${MAKE} CPPFLAGS="-DVERSION='\"${VERSION_STRING}\"'" --no-print-directory -C ${FIPTOOLPATH}
 
 cscope:
 	@echo "  CSCOPE"

docs/firmware-design.md

@@ -1513,11 +1513,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
@@ -1534,7 +1539,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)
 

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.

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
@@ -635,45 +635,66 @@ 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:
 
     make [DEBUG=1] [V=1] fiptool
 
 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
 
@@ -805,21 +826,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.
 

make_helpers/build_macros.mk

@@ -112,7 +112,7 @@ define IMG_BIN
     ${BUILD_PLAT}/bl$(1).bin
 endef
 
-# FIP_ADD_PAYLOAD appends the command line arguments required by the FIP tool
+# FIP_ADD_PAYLOAD appends the command line arguments required by fiptool
 # to package a new payload. Optionally, it adds the dependency on this payload
 #   $(1) = payload filename (i.e. bl31.bin)
 #   $(2) = command line option for the specified payload (i.e. --bl31)
@@ -135,7 +135,7 @@ endef
 # using a build option. It also adds a dependency on the image file, aborting
 # the build if the file does not exist.
 #   $(1) = build option to specify the image filename (SCP_BL2, BL33, etc)
-#   $(2) = command line option for the fip_create tool (scp_bl2, bl33, etc)
+#   $(2) = command line option for fiptool (scp_bl2, bl33, etc)
 # Example:
 #   $(eval $(call FIP_ADD_IMG,BL33,--bl33))
 define FIP_ADD_IMG
@@ -147,7 +147,7 @@ check_$(1):
 	$$(if $(value $(1)),,$$(error "Platform '${PLAT}' requires $(1). Please set $(1) to point to the right file"))
 endef
 
-# FWU_FIP_ADD_PAYLOAD appends the command line arguments required by the FIP tool
+# FWU_FIP_ADD_PAYLOAD appends the command line arguments required by fiptool
 # to package a new FWU payload. Optionally, it  adds the dependency on this payload
 #   $(1) = payload filename (e.g. ns_bl2u.bin)
 #   $(2) = command line option for the specified payload (e.g. --fwu)
@@ -168,7 +168,7 @@ endef
 
 # FWU_FIP_ADD_IMG allows the platform to pack a binary image in the FWU FIP
 #   $(1) build option to specify the image filename (BL2U, NS_BL2U, etc)
-#   $(2) command line option for the fip_create tool (bl2u, ns_bl2u, etc)
+#   $(2) command line option for fiptool (bl2u, ns_bl2u, etc)
 # Example:
 #   $(eval $(call FWU_FIP_ADD_IMG,BL2U,--bl2u))
 define FWU_FIP_ADD_IMG
@@ -301,7 +301,7 @@ define SOURCES_TO_OBJS
 endef
 
 
-# MAKE_TOOL_ARGS macro defines the command line arguments for the FIP tool for
+# MAKE_TOOL_ARGS macro defines the command line arguments for fiptool for
 # each BL image. Arguments:
 #   $(1) = BL stage (2, 30, 31, 32, 33)
 #   $(2) = Binary file

make_helpers/tbbr/tbbr_tools.mk

@@ -30,7 +30,7 @@
 
 # This file defines the keys and certificates that must be created to establish
 # a Chain of Trust following the TBBR document. These definitions include the
-# command line options passed to the cert_create and fip_create tools.
+# command line options passed to the cert_create and fiptool commands.
 #
 # Expected environment:
 #
@@ -66,11 +66,11 @@ NTFW_NVCTR_VAL		?=	0
 $(eval $(call CERT_ADD_CMD_OPT,${TFW_NVCTR_VAL},--tfw-nvctr))
 $(eval $(call CERT_ADD_CMD_OPT,${NTFW_NVCTR_VAL},--ntfw-nvctr))
 
-# Add Trusted Key certificate to the fip_create and cert_create command line options
+# Add Trusted Key certificate to the fiptool and cert_create command line options
 $(eval $(call FIP_ADD_PAYLOAD,${TRUSTED_KEY_CERT},--trusted-key-cert))
 $(eval $(call CERT_ADD_CMD_OPT,${TRUSTED_KEY_CERT},--trusted-key-cert))
 
-# Add fwu certificate to the fip_create and cert_create command line options
+# Add fwu certificate to the fiptool and cert_create command line options
 $(eval $(call FWU_FIP_ADD_PAYLOAD,${FWU_CERT},--fwu-cert))
 $(eval $(call FWU_CERT_ADD_CMD_OPT,${FWU_CERT},--fwu-cert))