Skip to content

Latest commit

 

History

History
473 lines (329 loc) · 16.5 KB

user_guide.md

File metadata and controls

473 lines (329 loc) · 16.5 KB
Raw

SCP-firmware User Guide

This document describes how to build the SCP and MCP firmware and run it with a tested set of other software components using defined configurations on supported Arm platforms. While it is possible to use other software components, configurations and platforms, how to do so is outside the scope of this document.

Host machine requirements

Running SCP-firmware on Fixed Virtual Platform (FVP) models requires at least 12GB of available memory. A multicore CPU is highly recommended to maintain smooth operation.

This software has been tested on Ubuntu 18.04 LTS (64-bit).

Prerequisites

To build the SCP/MCP firmware for a target product, the following tools are required:

Additionally, the firmware may be built using one of three compilers:

For Juno, it is required to have a more recent of GNU Arm embedded toolchain. We recommend to use at least the following release: 9-2019-q4-major.

If building using the LLVM toolchain, the GNU Arm Embedded Toolchain is also required for the Arm standard library and headers that ship with it. When building for a ARMv7 target the respective Arm Compiler-RT builtins are also required.

The following tools are recommended but not required:

  • Doxygen (1.8.13 or later): Required to generate supporting documentation
  • GNU GCC (7.4.0 or later): Required to build framework tests that run on the host system

If building for an Arm FVP platform, you will need to ensure you have the relevant FVP.

The FVPs also have a soft dependency on the following tools:

  • xterm: Required to view UART output

The instructions provided as a part of this guide assume you have Git (2.17.1 or later) available in your environment.

Installing these prerequisites can be done on any standard Debian-based system with the following:

sudo add-apt-repository ppa:team-gcc-arm-embedded/ppa
sudo apt update
sudo apt install build-essential doxygen gcc-arm-embedded git python3

For the FVP prerequisites:

sudo apt install xterm

Cloning the SCP-firmware source code

The SCP-firmware source code can be cloned from the official GitHub repository:

git clone --recurse-submodules https://github.com/ARM-software/SCP-firmware.git ${SCP_PATH}

Cloning dependencies

Under certain configurations the SCP-firmware has a dependency on the CMSIS-Core and CMSIS-RTOS2 projects, which are part of the Cortex Microcontroller System Interface Standard (CMSIS) software pack. The source tree for this software is included with the firmware as a Git submodule. You can fetch all submodules from within the source directory with the following:

git submodule update --init

Documentation

If Doxygen is available on the host system then comprehensive documentation can be generated. The complete set of documentation is compiled into bundles in HTML, LaTeX, and XML formats and placed in the build/doc directory. This documentation includes:

  • A README section
  • The BSD-3-Clause license under which this software and supporting files are distributed
  • The SCP-firmware user guide (the content of this file)
  • An overview of the framework on which SCP-firmware is written, including information on how components of the software must interact with the framework and with each other
  • An overview of the build system and the project directory structure
  • The project's coding style
  • Source documentation for the SCP-firmware framework
  • Source documentation for modules that are included in the currently supported products

From within the SCP-firmware root directory Doxygen can be invoked using the top-level Makefile:

make doc

Building SCP-firmware

To build SCP-firmware for a specific product the basic command format for invoking make (from within the source directory) is:

make CC=<COMPILER> PRODUCT=<PRODUCT> [OPTIONS] [TARGET]

For example, to build the RAM firmware for SGM-775 in debug mode, use the following:

make CC=arm-none-eabi-gcc PRODUCT=sgm775 MODE=debug firmware-scp_ramfw

The all target will be used if [TARGET] is omitted, which will build all the firmware defined by the product.

The help target provides further information on the arguments that can be given:

make help

The framework includes a suite of tests that validate its core functionality. If you installed the native GCC prerequisite, these can be run on the host system using:

make test

For all products other than host, the code needs to be compiled by a cross-compiler. The toolchain is derived from the CC variable, which should point to the cross-compiler executable. It can be set as an environment variable before invoking make, or provided as part of the build command:

make CC=<path to the cross compiler> ...

For more guidance and information on the build system, refer to the full set of documentation included in the Build System chapter of the Doxygen-generated documentation.

Building with LLVM

When building with the LLVM toolchain, it is mandatory to pass the required standard library and headers. These are taken from the GNU Arm Embedded Toolchain. According to the desired product and target the required environment variables differ.

ARMv7

When building for an ARMv7 product the GNU Arm Embedded Toolchain compiler must be passed under the SYSROOT_CC environment variable.

Building example for all of the SGM-775 targets:

make SYSROOT_CC=arm-none-eabi-gcc CC=clang-11 PRODUCT=sgm775

Note: if the Compiler-RT builtins are placed in a non conventional folder, their absolute path must be passed to LDFLAGS as follows:

make LDFLAGS=-L/path/to/compiler-rt-builtins SYSROOT_CC=arm-none-eabi-gcc CC=clang-11 PRODUCT=sgm775

Otherwise, the Compiler-RT builtins for baremetal are usually placed in:

/path/to/clang/resource/dir/lib/baremetal

For a LLVM 11 installation on Ubuntu this could be:

/usr/lib/llvm-11/lib/clang/11.0.1/lib/baremetal

You can discover the resource dir of your Clang 11 installation by running:

clang-11 -print-resource-dir

ARMv8

When building for an ARMv8 product the sysroot path of the GNU Arm Embedded Toolchain must be passed under the SYSROOT environment variable.

Building example for all of the R-Car targets:

make SYSROOT=/opt/gcc-arm-9.2-2019.12-x86_64-aarch64-none-elf/aarch64-none-elf CC=clang-11 PRODUCT=rcar

Running the SCP firmware on SGM platforms

For an introduction to the System Guidance for Mobile (SGM) platforms, please refer to the Arm Developer documentation.

The instructions within this section use SGM-775 as an example platform, but they are relevant for all SGM platforms.

Building the images

The build system generates firmware images per the product.mk file associated with the product. For SGM platforms, two firmware images are built:

  • scp_romfw.bin: SCP ROM firmware image - handles the transfer of the RAM firmware to private SRAM and jumps to it
  • scp_ramfw.bin: SCP RAM firmware image - manages the system runtime services
cd ${SCP_PATH} && \
    make CC=arm-none-eabi-gcc PRODUCT=sgm775 MODE=debug

export SCP_ROM_PATH=${SCP_PATH}/build/product/sgm775/scp_romfw/debug/bin/scp_romfw.bin
export SCP_RAM_PATH=${SCP_PATH}/build/product/sgm775/scp_ramfw/debug/bin/scp_ramfw.bin

Note: If building with LLVM, make sure to pass the required environment variables to make as noted in Building with LLVM.

Booting the firmware

In order for the scp_ramfw.bin firmware image to be loaded, an application processor secure world firmware needs to be available to load it. Arm maintains the Arm Trusted Firmware-A (TF-A) project, which handles this case. The remaining instructions assume you are using Trusted Firmware-A.

On SGM platforms, the SCP images are given alternative names when used in the context of TF-A:

  • scp_romfw.bin has the alternative name scp_bl1
  • scp_ramfw.bin has the alternative name scp_bl2

To boot the SCP firmware on SGM platforms with TF-A, you will need at minimum three additional images:

  • bl1: BL1 - first-stage bootloader stored in the system ROM
  • bl2: BL2 - second-stage bootloader loaded by bl1, responsible for handing over scp_bl2 to the SCP
  • fip: FIP - firmware image package containing bl2 and scp_bl2

The FIP format acts as a container for a number of commonly-used images in the TF-A boot flow. Documentation for the FIP format can be found in the TF-A firmware design documentation.

An example command line to build Arm Trusted Firmware-A for AArch64 is given below. Note that you will need to have installed the prerequisites for building Arm Trusted Firmware-A for SGM-775.

export TFA_PATH=<your Trusted Firmware-A path>

git clone -b v2.1 https://github.com/ARM-software/arm-trusted-firmware.git ${TFA_PATH}

cd ${TFA_PATH}

make CROSS_COMPILE=aarch64-linux-gnu- DEBUG=1 LOG_LEVEL=30 PLAT=sgm775 CSS_USE_SCMI_SDS_DRIVER=1 \
    bl1 bl2 fiptool

export BL1_PATH=${TFA_PATH}/build/sgm775/debug/bl1.bin
export BL2_PATH=${TFA_PATH}/build/sgm775/debug/bl2.bin
export FIP_PATH=/tmp/fip.bin

./tools/fiptool/fiptool create \
    --tb-fw ${BL2_PATH} \
    --scp-fw ${SCP_RAM_PATH} \
        ${FIP_PATH}

Note that CSS_USE_SCMI_SDS_DRIVER is a work-around for the fact that the v2.1 utilises SCPI instead of SCMI by default, which is not a supported configuration for SCP-firmware.

To simulate the basic SCP boot flow on the SGM-775 FVP, use the following command line:

FVP_CSS_SGM-775 \
    -C css.trustedBootROMloader.fname=${BL1_PATH} \
    -C css.scp.ROMloader.fname=${SCP_ROM_PATH} \
    -C board.flashloader0.fname=${FIP_PATH}

Note that it's expected that TF-A will crash, as we have not provided the full bootloader image chain.

Running the SCP firmware on SGI and Neoverse Reference Design platforms

For an introduction to the System Guidance for Infrastructure (SGI) platforms, please refer to System Guidance for Infrastructure (SGI).

For an introduction to the Neoverse Reference Design (RD) platforms, please refer to Neoverse Reference Designs.

The instructions within this section use SGI-575 as an example platform, but they are relevant for all SGI and Neoverse Reference Design platforms.

Building the images

The build system generates firmware images per the product.mk file associated with the product. For SGI and Neoverse Reference Design platforms, three firmware images are built:

  • scp_romfw.bin: SCP ROM firmware image - loads the SCP RAM firmware from NOR flash into private SRAM and jumps to it
  • scp_ramfw.bin: SCP RAM firmware image - manages the system runtime services
  • mcp_romfw.bin: MCP ROM firmware image
cd ${SCP_PATH} && \
    make CC=arm-none-eabi-gcc PRODUCT=sgi575 MODE=debug

export SCP_ROM_PATH=${SCP_PATH}/build/product/sgi575/scp_romfw/debug/bin/scp_romfw.bin
export SCP_RAM_PATH=${SCP_PATH}/build/product/sgi575/scp_ramfw/debug/bin/scp_ramfw.bin
export MCP_ROM_PATH=${SCP_PATH}/build/product/sgi575/mcp_romfw/debug/bin/mcp_romfw.bin

Note: If building with LLVM, make sure to pass the required environment variables to make as noted in Building with LLVM.

Creating the NOR flash image

Unlike in the System Guidance for Mobile platforms, a secure-world application processor firmware is not required to load the SCP firmware. Instead, the SCP ROM firmware loads the SCP RAM firmware directly from NOR flash memory at a fixed address.

To create a NOR flash image containing only the SCP RAM firmware, use:

export NOR_PATH=/tmp/nor.bin

dd if=/dev/zero of=${NOR_PATH} bs=1024 count=62976 && \
cat ${SCP_RAM_PATH} >> ${NOR_PATH}

Booting the firmware

To simulate the basic SCP boot flow on the SGI-575 FVP, use the following command line:

FVP_CSS_SGI-575 \
    -C css.scp.ROMloader.fname=${SCP_ROM_PATH} \
    -C css.mcp.ROMloader.fname=${MCP_ROM_PATH} \
    -C board.flashloader0.fname=${NOR_PATH}

Running the SCP firmware on the Juno Development Board

For an introduction to the Juno Development Board, please refer to the Arm Developer documentation.

The instructions within this section are similar to those used for SGM platforms, with minor differences.

Building the images

Like for SGM platforms, the build system generates two images. For Juno, an additional binary is generated:

  • scp_romfw_bypass.bin: SCP ROM bypass firmware image - an alternative ROM firmware that is loaded from an external non volatile on-board memory. This binary needs to be used in order to successfully load the SCP RAM firmware, and is chain-loaded from the burned-in ROM on the physical board (not necessary for the FVP).

We recommend using the latest release of Trusted Firmware-A (2.3 or later).

Booting the firmware

The same steps for creating the FIP binary described by the SGM platforms sections can be applied here. When invoking make for TF-A, make sure you replace PLAT=sgm775 with PLAT=juno.

Before proceeding with the boot on Juno, make sure you have all of the following binaries:

  • scp_romfw_bypass.bin
  • fip.bin
  • bl1.bin

Before beginning, please ensure the SD card used for your Juno board has been set up with a Linaro release software stack. If this is not the case, you can follow the Linaro software release instructions and/or download a new SD card filesystem from the Linaro releases page.

Once your SD card has been set up, you can do the following to get started with building and running the SCP firmware:

  • Replace SOFTWARE/fip.bin with your version of fip.bin
  • Replace SOFTWARE/bl1.bin with your version of bl1.bin
  • Replace SOFTWARE/scp_bl1.bin with your version of scp_romfw_bypass.bin

Lastly, ensure your host has synchronized any buffered data on the SD card (on Linux and Unix systems, this can be done with the sync command) and reset the board.

You can see the progress of the boot by connecting the UART to your host PC (please follow the instructions in the Juno Getting Started Guide).

Software stack

Arm provides a super-project with guides for building and running a full software stack on Arm platforms. This project provides a convenient wrapper around the various build systems involved in the software stack, including for SCP-firmware.