ARM Trusted Firmware User Guide

1. Introduction

This document describes how to build ARM Trusted Firmware and run it with a tested set of other software components using Defined configurations on the Juno arm development platform and ARM Fixed Virtual Platform (FVP) models. It is possible-to-use other software components, configurations and platforms but that's outside the scope of this Docume Nt.

This document should is used in conjunction with the Firmware Design. 2. Host Machine Requirements

The minimum recommended machine specification for building the software and running the FVP models is a dual-core processo R 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 have been tested on Ubuntu 12.04.04 (64-bit). Packages used for building the software were installed from that distribution unless otherwise specified. 3. Tools

The following tools is required to use the ARM Trusted Firmware:

Git package to obtain source code.

Build-essential, Uuid-dev and IASL packages for building UEFI and the Firmware Image package (FIP) tool.

BC and Ncurses-dev packages for building Linux.

Device-tree-compiler package for building the flattened Device tree (FDT) source files (. dts files) provided with this SOF Tware.

BareMetal GNU GCC Tools. Verified packages can is downloaded from Linaro. The rest of this document assumes the GCC-LINARO-AARCH64-NONE-ELF-4.9-2014.07_LINUX.TAR.XZ tools is used.

wget http://releases.linaro.org/14.07/components/toolchain/binaries/gcc-linaro-aarch64-none-elf-4.9-2014.07_ Linux.tar.xz
tar-xf Gcc-linaro-aarch64-none-elf-4.9-2014.07_linux.tar.xz

(Optional) For debugging, ARM Development Studio 5 (DS-5) v5.19. 4. Building the Trusted Firmware

To build the Trusted Firmware images, follow these steps:

Clone the ARM Trusted Firmware repository from GitHub:

git clone https://github.com/ARM-software/arm-trusted-firmware.git

Change to the trusted firmware directory:

CD Arm-trusted-firmware

Set the compiler path, specify a non-trusted Firmware image (bl3-3) and a valid platform, and then build:

cross_compile=<path-to-aarch64-gcc>/bin/aarch64-none-elf-\
bl33=<path-to>/<bl33_image>                               \ Make
plat=<platform> all FIP

If PLAT is not specified, FVP are assumed by default. See the ' Summary of build options ' for more information on available build options.

The bl3-3 image corresponds to the software was executed after switching to the Non-secure world. UEFI can be used as the bl3-3 image. Refer to the ' obtaining the normal World Software ' section below.

The TSP (Test Secure Payload), corresponding to the bl3-2 image, are not compiled in by default. Refer to the ' Building the Test Secure Payload ' section below.

By default this produces a release version of the build. To produce a debug version instead, refer to the ' Debugging Options ' section below.

The build process creates products in a build directory tree, building the objects and binaries for each boot loader stage In separate sub-directories. The following boot loader binary files is created from the corresponding ELF Files:build/<platform>/<build-type >/bl1.bin Build/<platform>/<build-type>/bl2.bin build/<platform>/<build-type>/ Bl31.bin

Where <platform> is the name of the chosen platform and <build-type> is either Debug or release. A firmare Image Package (FIP) is created as part of the build. It contains all boot loader images except for Bl1.bin. Build/<platform>/<build-type>/fip.bin

For more information on FIPs, see the ' Firmware Image Package ' section in the Firmware Design.

(Optional) Some platforms may require a bl3-0 an image to boot. This image can be included in the FIPS when building the Trusted Firmware by specifying the BL30 build option:

Bl30=<path-to>/<bl30_image>

Output binary files Bl1.bin and Fip.bin is both required to boot the system. How these files was used is platform specific. Refer to the platform documentation the "to" use the firmware images.

(Optional) Build products for a specific build variant can removed using:

Make debug=<d> plat=<platform> Clean

... where <D> is 0 or 1, as specified when building.

The build tree can be removed completely using:

Make Realclean

(Optional) Path to binary for certain BL stages (BL2, bl3-1 and Bl3-2) can being provided by specifying the blx=/where BLx is the BL St Age. This would bypass the build of the BL component from source, but would include the specified binary in the final FIP image. Please note that Bl3-2 would be included in the build and only if the SPD build option is specified.

For example, specifying bl2=/in the build option, would skip compilation of BL2 source in trusted firmware, but include th e BL2 binary specified in the final FIP image. Summary of Build options

ARM Trusted Firmware Build system supports the following build options. Unless mentioned otherwise, these options is expected to being specified at the build command line and is not to be modifie D in any component makefiles. Note that the build system doesn ' t track dependency for build options. Therefore, if any of the build options is changed from a previous build, a clean build must be performed. Common Build Options

Bl30:path to bl3-0 image in the host file system. This image is optional. If a bl3-0 image is present then this option must being passed for the FIP target.

Bl33:path to bl3-3 image in the host file system. This was mandatory for FIPS target in case the BL2 from ARM Trusted Firmware is used.

Bl2:this is a optional build option which specifies the path to BL2 image for the FIP target. The BL2 in the ARM Trusted Firmware is not being built.

Bl31:this is a optional build option which specifies the path to bl3-1 image for the FIP target. The bl3-1 in the ARM Trusted Firmware is not being built.

Bl32:this is a optional build option which specifies the path to bl3-2 image for the FIP target. The bl3-2 in the ARM Trusted Firmware is not being built.

Cross_compile:prefix to toolchain binaries. Refer to examples in this document for usage.

Debug:chooses between a debug and release build. It can take either 0 (release) or 1 (debug) as values. 0 is the default.

Log_level:chooses the log level, which controls the amount of the console log output compiled into the build. This should is one of the following:

0 (  log_level_none) (
log_level_notice) (
log_level_error) (
log_level_warning) (
Log_ Level_info)
(log_level_verbose)

All logs output up to and including the log level are compiled into the build. The default value is at the debug builds and in release builds.

Ns_timer_switch:enable save and restore for Non-secure TIMER Register contents upon world SWITCH. It can take either 0 (don ' t save and Restore) or 1 (Do save and restore). 0 is the default. An SPD could set this to 1 if it wants the timer registers to be saved and restored.

Plat:choose a platform to build ARM Trusted Firmware for. The chosen platform name must is the name of the one of the directories under the plat/directory other than common.

Spd:choose a Secure Payload Dispatcher component to being built into the Trusted Firmware. The value should is the path to the directory containing the SPD source, relative to services/spd/; The directory is expected to contain a makefile called <SPD-VALUE>.MK.

V:verbose build. If assigned anything other than 0, the build commands is printed. Default is 0.

Arm_gic_arch:choice of ARM GIC architecture version used by the arm GIC driver for implementing the platform GIC API. This API was used by the interrupt management framework. Default is 2 (which is, version 2.0).

Imf_read_interrupt_id:boolean flag used by the INTERRUPT management framework to enable passing of the INTERRUPT ID to it S handler. The ID is read using a platform GIC API. Intr_id_unavailable is passed instead if the this option set to 0. Default is 0.

Reset_to_bl31:enable bl3-1 entrypoint as the CPU reset vector instead of the BL1 entrypoint. It can take the value 0 (CPU reset to BL1 entrypoint) or 1 (CPU reset to Bl3-1 entrypoint). The default value is 0.

Crash_reporting:a Non-zero value enables A console dump of processor register state if an unexpected exception occurs D uring execution of Bl3-1. This option, defaults to the value of debug-i.e. By default, this is only enabled for a DEBUG build of the firmware.

Asm_assertion:this flag Determines whether the assertion checks within assembly source files is enabled or not. This option defaults to the value of Debug-that are, by default, the "only" enabled for a DEBUG build of the firmware.

Tsp_init_async:choose Bl3-2 initialization method as asynchronous or synchronous, (see "Initializing a bl3-2 Image" secti On Firmware Design). It can take the value 0 (Bl3-2 are initialized using synchronous method) or 1 (bl3-2 is initialized using asynchronous meth OD). Default is 0. FVP Specific Build Options Fvp_tsp_ram_location:location of the TSP binary. Options:tsram (default): Trusted SRAM tdram:trusted DRAM

For a better understanding of FVP options, the FVP memory map are explained in the Firmware Design.