User Guide¶
This document describes how to build the Trusted Firmware-A Tests (TF-A Tests) and run them on a set of platforms. It assumes that the reader has previous experience building and running the Trusted Firmware-A (TF-A).
Host machine requirements¶
The minimum recommended machine specification for building the software and running the FVP models is a dual-core processor running at 2GHz with 12GB of RAM. For best performance, use a machine with a quad-core processor running at 2.6GHz with 16GB of RAM.
The software has been tested on Ubuntu 16.04 LTS (64-bit). Packages used for building the software were installed from that distribution unless otherwise specified.
Tools¶
Install the required packages to build TF-A Tests with the following command:
sudo apt-get install device-tree-compiler build-essential make git perl libxml-libxml-perl
Download and install the GNU cross-toolchain from developer.arm.com portal. The TF-A Tests have been tested with version 9.2-2019.12 (gcc 9.2):
In addition, the following optional packages and tools may be needed:
For debugging, Arm Development Studio 5 (DS-5).
Getting the TF-A Tests source code¶
Download the TF-A Tests source code using the following command:
git clone https://git.trustedfirmware.org/TF-A/tf-a-tests.git
Building TF-A Tests¶
Before building TF-A Tests, the environment variable
CROSS_COMPILE
must point to the cross compiler.For AArch64:
export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf-
For AArch32:
export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-none-eabi-
Change to the root directory of the TF-A Tests source tree and build.
For AArch64:
make PLAT=<platform>
For AArch32:
make PLAT=<platform> ARCH=aarch32
Notes:
If
PLAT
is not specified,fvp
is assumed by default. See the Summary of build options for more information on available build options.By default this produces a release version of the build. To produce a debug version instead, build the code with
DEBUG=1
.The build process creates products in a
build/
directory tree, building the objects and binaries for each test image in separate sub-directories. The following binary files are created from the corresponding ELF files:build/<platform>/<build-type>/tftf.bin
build/<platform>/<build-type>/ns_bl1u.bin
build/<platform>/<build-type>/ns_bl2u.bin
build/<platform>/<build-type>/el3_payload.bin
build/<platform>/<build-type>/cactus_mm.bin
build/<platform>/<build-type>/cactus.bin
build/<platform>/<build-type>/ivy.bin
build/<platform>/<build-type>/quark.bin
where
<platform>
is the name of the chosen platform and<build-type>
is eitherdebug
orrelease
. The actual number of images might differ depending on the platform.Refer to the sections below for more information about each image.
Build products for a specific build variant can be removed using:
make DEBUG=<D> PLAT=<platform> clean
… where
<D>
is0
or1
, as specified when building.The build tree can be removed completely using:
make realclean
Use the following command to list all supported build commands:
make help
TFTF test image¶
tftf.bin
is the main test image to exercise the TF-A features. The other
test images provided in this repository are optional dependencies that TFTF
needs to test some specific features.
tftf.bin
may be built independently of the other test images using the
following command:
make PLAT=<platform> tftf
In TF-A boot flow, tftf.bin
replaces the BL33
image and should be
injected in the FIP image. This might be achieved by running the following
command from the TF-A root directory:
BL33=tftf.bin make PLAT=<platform> fip
Please refer to the TF-A User guide for further details.
NS_BL1U and NS_BL2U test images¶
ns_bl1u.bin
and ns_bl2u.bin
are test images that exercise the Firmware
Update (FWU) feature of TF-A 1. Throughout this document, they will be
referred as the FWU test images.
In addition to updating the firmware, the FWU test images also embed some tests that exercise the FWU state machine implemented in the TF-A. They send valid and invalid SMC requests to the TF-A BL1 image in order to test its robustness.
NS_BL1U test image¶
The NS_BL1U
image acts as the Application Processor (AP) Firmware Update
Boot ROM. This typically is the first software agent executing on the AP in the
Normal World during a firmware update operation. Its primary purpose is to load
subsequent firmware update images from an external interface, such as NOR Flash,
and communicate with BL1
to authenticate those images.
The NS_BL1U
test image provided in this repository performs the following
tasks:
Load FWU images from external non-volatile storage (typically flash memory) to Non-Secure RAM.
Request TF-A BL1 to copy these images in Secure RAM and authenticate them.
Jump to
NS_BL2U
which carries out the next steps in the firmware update process.
This image may be built independently of the other test images using the following command:
make PLAT=<platform> ns_bl1u
NS_BL2U test image¶
The NS_BL2U
image acts as the AP Firmware Updater. Its primary
responsibility is to load a new set of firmware images from an external
interface and write them into non-volatile storage.
The NS_BL2U
test image provided in this repository overrides the original
FIP image stored in flash with the backup FIP image (see below).
This image may be built independently of the other test images using the following command:
make PLAT=<platform> ns_bl2u
Putting it all together¶
The FWU test images should be used in conjunction with the TFTF image, as the latter initiates the FWU process by corrupting the FIP image and resetting the target. Once the FWU process is complete, TFTF takes over again and checks that the firmware was successfully updated.
To sum up, 3 images must be built out of the TF-A Tests repository in order to test the TF-A Firmware Update feature:
ns_bl1u.bin
ns_bl2u.bin
tftf.bin
Once that’s done, they must be combined in the right way.
ns_bl1u.bin
is a standalone image and does not require any further processing.ns_bl2u.bin
must be injected into theFWU_FIP
image. This might be achieved by settingNS_BL2U=ns_bl2u.bin
when building theFWU_FIP
image out of the TF-A repository. Please refer to the section Building FIP images with support for Trusted Board Boot in the TF-A User Guide.tftf.bin
must be injected in the standard FIP image, as explained in section TFTF test image.
Additionally, on Juno platform, the FWU FIP must contain a SCP_BL2U
image.
This image can simply be a copy of the standard SCP_BL2
image if no specific
firmware update operations need to be carried on the SCP side.
Finally, the backup FIP image must be created. This can simply be a copy of the standard FIP image, which means that the Firmware Update process will restore the original, uncorrupted FIP image.
EL3 test payload¶
el3_payload.bin
is a test image exercising the alternative EL3 payload boot
flow in TF-A. Refer to the EL3 test payload README file for more details
about its behaviour and how to build and run it.
SPM test images¶
This repository contains 3 Secure Partitions that exercise the Secure Partition Manager (SPM) in TF-A 2. Cactus-MM is designed to test the SPM implementation based on the ARM Management Mode Interface (MM), while Cactus and Ivy can test the SPM implementation based on the SPCI and SPRT draft specifications. Note that it isn’t possible to use both communication mechanisms at once: If Cactus-MM is used Cactus and Ivy can’t be used.
They run in Secure-EL0 and perform the following tasks:
Test that TF-A has correctly setup the secure partition environment: They should be allowed to perform cache maintenance operations, access floating point registers, etc.
Test that TF-A accepts to change data access permissions and instruction permissions on behalf of the Secure Partitions for memory regions the latter owns.
Test communication with SPM through either MM, or both SPCI and SPRT.
They are only supported on AArch64 FVP. They can be built independently of the other test images using the following command:
make PLAT=fvp cactus ivy cactus_mm
In the TF-A boot flow, the partitions replace the BL32
image and should be
injected in the FIP image. To test SPM-MM with Cactus-MM, it is enough to use
cactus_mm.bin
as BL32 image. To test the SPM based on SPCI and SPRT, it is
needed to use sp_tool
to build a Secure Partition package that can be used
as BL32 image.
To run the full set of tests in the Secure Partitions, they should be used in conjunction with the TFTF image.
For SPM-MM, the following commands can be used to build the tests:
- ::
# TF-A-Tests repository:
make PLAT=fvp TESTS=spm-mm tftf cactus_mm
# TF-A repository:
make BL33=path/to/tftf.bin BL32=path/to/cactus_mm.bin PLAT=fvp EL3_EXCEPTION_HANDLING=1 ENABLE_SPM=1 all fip
For SPM based on SPCI and SPRT:
- ::
# TF-A-Tests repository:
make PLAT=fvp TESTS=spm tftf cactus ivy
# TF-A repository:
make sptool
- tools/sptool/sptool -o sp_package.bin
-i path/to/cactus.bin:path/to/cactus.dtb -i path/to/ivy.bin:path/to/ivy.dtb
make BL33=path/to/tftf.bin BL32=path/to/sp_package.bin PLAT=fvp ENABLE_SPM=1 SPM_MM=0 ARM_BL31_IN_DRAM=1 all fip
Please refer to the TF-A User guide for further details.
Summary of build options¶
As much as possible, TF-A Tests dynamically detect the platform hardware components and available features. There are a few build options to select specific features where the dynamic detection falls short. This section lists them.
Unless mentioned otherwise, these options are expected to be specified at the build command line and are not to be modified in any component makefiles.
Note that the build system doesn’t track dependencies for build options. Therefore, if any of the build options are changed from a previous build, a clean build must be performed.
TFTF build options¶
ENABLE_PAUTH
: Boolean option to enable ARMv8.3 Pointer Authentication (ARMv8.3-PAuth
) support in the Trusted Firmware-A Test Framework itself. If enabled, it is needed to use a compiler that supports the option-mbranch-protection
(GCC 9 and later). It defaults to 0.NEW_TEST_SESSION
: Choose whether a new test session should be started every time or whether the framework should determine whether a previous session was interrupted and resume it. It can take either 1 (always start new session) or 0 (resume session as appropriate). 1 is the default.TESTS
: Set of tests to run. Use the following command to list all possible sets of tests:make help_tests
If no set of tests is specified, the standard tests will be selected (see
tftf/tests/tests-standard.xml
).USE_NVM
: Used to select the location of test results. It can take either 0 (RAM) or 1 (non-volatile memory like flash) as test results storage. Default value is 0, as writing to the flash significantly slows tests down.
FWU test images build options¶
FIRMWARE_UPDATE
: Whether the Firmware Update test images (i.e.NS_BL1U
andNS_BL2U
) should be built. The default value is 0. The platform makefile is free to override this value if Firmware Update is supported on this platform.
Arm FVP platform specific build options¶
FVP_MAX_PE_PER_CPU
: Sets the maximum number of PEs implemented on any CPU in the system. It can take either 1 or 2 values. This option defaults to 1.
Checking source code style¶
When making changes to the source for submission to the project, the source must
be in compliance with the Linux style guide. To assist with this, the project
Makefile provides two targets, which both utilise the checkpatch.pl
script
that ships with the Linux source tree.
To check the entire source tree, you must first download copies of
checkpatch.pl
, spelling.txt
and const_structs.checkpatch
available
in the Linux master tree scripts directory, then set the CHECKPATCH
environment variable to point to checkpatch.pl
(with the other 2 files in
the same directory).
Then use the following command:
make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkcodebase
To limit the coding style checks to your local changes, use:
make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkpatch
By default, this will check all patches between origin/master
and your local
branch. If you wish to use a different reference commit, this can be specified
using the BASE_COMMIT
variable.
Running the TF-A Tests¶
Refer to the sections Running the software on FVP and Running the software on Juno in TF-A User Guide. The same instructions mostly apply to run the TF-A Tests on those 2 platforms. The difference is that the following images are not needed here:
Normal World bootloader. The TFTF replaces it in the boot flow;
Linux Kernel;
Device tree;
Filesystem.
In other words, only the following software images are needed:
BL1
firmware image;FIP
image containing the following images:BL2
;SCP_BL2
if required by the platform (e.g. Juno);BL31
;BL32
(optional);tftf.bin
(standing as the BL33 image).
Running the manual tests on FVP¶
The manual tests rely on storing state in non-volatile memory (NVM) across reboot. On FVP the NVM is not persistent across reboots, so the following flag must be used to write the NVM to a file when the model exits.
- ::
-C bp.flashloader0.fnameWrite=[filename]
To ensure the model exits on shutdown the following flag must be used:
- ::
-C bp.ve_sysregs.exit_on_shutdown=1
After the model has been shutdown, this file must be fed back in to continue the test. Note this flash file includes the FIP image, so the original fip.bin does not need to be passed in. The following flag is used:
-C bp.flashloader0.fname=[filename]
Running the FWU tests¶
As previously mentioned in section Putting it all together, there are a couple of extra images involved when running the FWU tests. They need to be loaded at the right addresses, which depend on the platform.
FVP¶
In addition to the usual BL1 and FIP images, the following extra images must be loaded:
NS_BL1U
image at address0x0BEB8000
(i.e. NS_BL1U_BASE macro in TF-A)FWU_FIP
image at address0x08400000
(i.e. NS_BL2U_BASE macro in TF-A)Backup FIP
image at address0x09000000
(i.e. FIP_BKP_ADDRESS macro in TF-A tests).
An example script is provided in scripts/run_fwu_fvp.sh.
Juno¶
The same set of extra images and load addresses apply for Juno as for FVP.
The new images must be programmed in flash memory by adding some entries in the
SITE1/HBI0262x/images.txt
configuration file on the Juno SD card (where
x
depends on the revision of the Juno board). Refer to the Juno Getting
Started Guide, section 2.3 “Flash memory programming” for more
information. Users should ensure these do not overlap with any other entries in
the file.
Addresses in this file are expressed as an offset from the base address of the
flash (that is, 0x08000000
).
NOR10UPDATE: AUTO ; Image Update:NONE/AUTO/FORCE
NOR10ADDRESS: 0x00400000 ; Image Flash Address
NOR10FILE: \SOFTWARE\fwu_fip.bin ; Image File Name
NOR10LOAD: 00000000 ; Image Load Address
NOR10ENTRY: 00000000 ; Image Entry Point
NOR11UPDATE: AUTO ; Image Update:NONE/AUTO/FORCE
NOR11ADDRESS: 0x03EB8000 ; Image Flash Address
NOR11FILE: \SOFTWARE\ns_bl1u.bin ; Image File Name
NOR11LOAD: 00000000 ; Image Load Address
NOR11ENTRY: 00000000 ; Image Load Address
NOR12UPDATE: AUTO ; Image Update:NONE/AUTO/FORCE
NOR12ADDRESS: 0x01000000 ; Image Flash Address
NOR12FILE: \SOFTWARE\backup_fip.bin ; Image File Name
NOR12LOAD: 00000000 ; Image Load Address
NOR12ENTRY: 00000000 ; Image Entry Point
- 1
Therefore, the Trusted Board Boot feature must be enabled in TF-A for the FWU test images to work. Please refer the TF-A User guide for further details.
- 2
Therefore, the Secure Partition Manager must be enabled in TF-A for any of the test Secure Partitions to work. Please refer to the TF-A User guide for further details.
Copyright (c) 2018-2020, Arm Limited. All rights reserved.