From 819281ee23e1fd048e8385ecc708f78dff5e51d9 Mon Sep 17 00:00:00 2001 From: dp-arm Date: Wed, 25 May 2016 16:20:20 +0100 Subject: 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 --- docs/firmware-design.md | 9 +++++++-- docs/trusted-board-boot.md | 2 +- docs/user-guide.md | 43 ++++++++++++++++++++++++++++++++----------- 3 files changed, 40 insertions(+), 14 deletions(-) (limited to 'docs') 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///bl2.bin \ --soc-fw build///bl31.bin \ fip.bin Example 2: view the contents of an existing Firmware package: - ./tools/fip_create/fip_create --dump /fip.bin + ./tools/fiptool/fiptool info /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//release/bl2.bin \ build//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 /fip.bin + ./tools/fiptool/fiptool unpack /fip.bin + +Example 5: remove an entry from an existing Firmware package: + + ./tools/fiptool/fiptool remove \ + --tb-fw build//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 \ /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. -- cgit v1.2.3