1# SCP-firmware User Guide 2 3This document describes how to build the SCP and MCP firmware and run it with a 4tested set of other software components using defined configurations on 5supported Arm platforms. While it is possible to use other software components, 6configurations and platforms, how to do so is outside the scope of this 7document. 8 9## Host machine requirements 10 11Running SCP-firmware on Fixed Virtual Platform (FVP) models requires at least 1212GB of available memory. A multicore CPU is highly recommended to maintain 13smooth operation. 14 15This software has been tested on Ubuntu 20.04 LTS (64-bit). 16 17## Prerequisites 18 19To build the SCP/MCP firmware for a target product, the following tools are 20required: 21 22- [GNU Make] (*4.2* or later) 23- [CMake] (*3.18.4* or later) 24- [Python 3] (*3.7.9* or later) 25 26[GNU Make]: https://www.gnu.org/software/make/ 27[Python 3]: https://www.python.org/downloads/release/python-379/ 28[CMake]: https://cmake.org/ 29 30Additionally, the firmware may be built using one of three compilers: 31 32- [GNU Arm Embedded Toolchain] (*10.3-2021.10* or later) 33- [Arm Compiler 6] (*6.13* or later) 34- [LLVM Toolchain] (*13.0.1* or later) 35 36[GNU Arm Embedded Toolchain]: 37https://developer.arm.com/open-source/gnu-toolchain/gnu-rm 38[Arm Compiler 6]: 39https://developer.arm.com/tools-and-software/embedded/arm-compiler/downloads/version-6 40[LLVM Toolchain]: https://releases.llvm.org/download.html 41 42 43If building using the LLVM toolchain, the [GNU Arm Embedded Toolchain] is also 44required for the Arm standard library and headers that ship with it. When 45building for a ARMv7 target the respective Arm [Compiler-RT builtins] are 46also required. 47 48[Compiler-RT builtins]: https://compiler-rt.llvm.org/ 49 50The following tools are recommended but not required: 51 52- [Doxygen] (*1.8.13* or later): Required to generate supporting documentation 53- [AArch64 GCC toolchain] (*6.2.1* or later): To build the Trusted Firmware in 54order to run the tests suites 55- [ARM GCC GNU-A toolchain] (*7.4.0* or later): Required to build framework 56tests that run on the host system 57- [lcov] (*1.13* or later): Required to run unit test framework 58- [cppcheck] (*1.90*): Required during build process to check the code 59- [ninja-build] (*1.10.0* or later): Default build system to compile the project 60UNIX-Make is a suitable alternative if preferred. 61- [clang-format] (*10.0.0* or later): Automatic code formatter. 62 63[Doxygen]: http://www.doxygen.nl/ 64[AArch64 GCC toolchain]: 65http://releases.linaro.org/components/toolchain/binaries 66[ARM GCC GNU-A toolchain]: 67https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-a/downloads 68[Cppcheck]: https://github.com/danmar/cppcheck/tree/1.90 69[Ninja-build]: https://ninja-build.org/ 70[Clang-format]: https://clang.llvm.org/docs/ClangFormat.html 71 72If building for an Arm FVP platform, you will need to ensure you have [the 73relevant FVP]. 74 75[the relevant FVP]: https://developer.arm.com/products/system-design/fixed-virtual-platforms 76 77The FVPs also have a soft dependency on the following tools: 78 79- [xterm]: Required to view UART output 80 81[xterm]: https://invisible-island.net/xterm/ 82 83The instructions provided as a part of this guide assume you have [Git] 84(*2.17.1* or later) available in your environment. 85 86[Git]: https://git-scm.com/ 87 88Installing some of these prerequisites can be done on any standard Debian-based 89system with the following: 90 91```sh 92sudo apt install \ 93 build-essential \ 94 doxygen \ 95 git \ 96 python3 \ 97 python3-pip \ 98 device-tree-compiler \ 99 ninja-build \ 100 lcov 101``` 102 103For setting up the build system and its requirements (CMake among them), visit 104the cmake_readme.md file. 105 106For the FVP prerequisites: 107 108```sh 109sudo apt install xterm 110``` 111 112For code style checks in Python scripts (`pip3` needs to be installed): 113 114```sh 115pip3 install pycodestyle 116pip3 install --upgrade pycodestyle 117sudo apt-get install pep8 118``` 119 120## Cloning the SCP-firmware source code 121 122The SCP-firmware source code can be cloned from the official GitHub repository: 123 124```sh 125git clone --recurse-submodules https://github.com/ARM-software/SCP-firmware.git\ 126 ${SCP_PATH} 127``` 128 129### Cloning dependencies 130 131Under certain configurations the SCP-firmware has a dependency on the CMSIS-Core 132projects, which are part of the [Cortex Microcontroller System Interface 133Standard (CMSIS)] software pack. The source tree for this software is 134included with the firmware as a Git submodule. You can fetch all submodules from 135within the source directory with the following: 136 137[Cortex Microcontroller System Interface Standard (CMSIS)]: 138https://www.arm.com/why-arm/technologies/cmsis 139 140```sh 141git submodule update --init --recursive 142``` 143This command will also fetch submodules related to unit testing.For more 144information please refer to the `unit_test/user_guide.md` 145documentation. 146 147## Documentation 148 149If Doxygen is available on the host system then comprehensive documentation can 150be generated. The complete set of documentation is compiled into bundles in 151HTML, LaTeX, and XML formats and placed in the `build/doc` directory. This 152documentation includes: 153 154- A *README* section 155- The BSD-3-Clause license under which this software and supporting files are 156 distributed 157- The SCP-firmware user guide (the content of this file) 158- An overview of the framework on which SCP-firmware is written, including 159 information on how components of the software must interact with the 160 framework and with each other 161- An overview of the build system and the project directory structure 162- The project's coding style 163- Source documentation for the SCP-firmware framework 164- Source documentation for modules that are included in the currently supported 165 products 166 167From within the SCP-firmware root directory Doxygen can be invoked using the 168top-level Makefile.cmake file: 169 170```sh 171make -f Makefile.cmake doc 172``` 173## Building SCP-firmware 174 175To build SCP-firmware for a specific product the basic command format for 176invoking `make` (from within the source directory) is: 177 178```sh 179make -f Makefile.cmake PRODUCT=<PRODUCT> [OPTIONS] [TARGET] 180``` 181 182For example, to build the RAM firmware for TC2 in debug mode, use the 183following: 184 185```sh 186make -f Makefile.cmake PRODUCT=tc2 MODE=debug firmware-scp_ramfw 187``` 188 189The `all` target will be used if `[TARGET]` is omitted, which will build all the 190firmware defined by the product. 191 192The `help` target provides further information on the arguments that can be 193given: 194 195```sh 196make -f Makefile.cmake help 197``` 198 199The framework includes a suite of tests that validate its core functionality. 200If you installed the native GCC prerequisite, these can be run on the host 201system using: 202 203```sh 204make -f Makefile.cmake test 205``` 206 207For more guidance and information on the build system, refer to the full set of 208documentation included in the *Build System* chapter of the Doxygen-generated 209documentation. 210 211### Building with LLVM 212 213When building with the LLVM toolchain, it is mandatory to pass the required 214standard library and headers. These are taken from the 215[GNU Arm Embedded Toolchain]. According to the desired product and target the 216required environment variables differ. The PATH variable of the system must 217incorporate path to the required toolchain. 218 219#### ARMv7 220 221When building for an ARMv7 product the sysroot path of the GNU Arm Embedded 222Toolchain must be passed under the `SYSROOT` environment variable. 223 224```sh 225make -f Makefile.cmake PRODUCT=tc2 \ 226 LLVM_SYSROOT_CC=/path/to/sysroot 227``` 228 229The Compiler-RT builtins for baremetal are usually placed in: 230 231```sh 232/path/to/clang/resource/dir/lib/baremetal 233``` 234 235For a LLVM 13 installation on Ubuntu this could be: 236 237```sh 238/usr/lib/llvm-13/lib/clang/13.0.1/lib/baremetal 239``` 240 241You can discover the resource dir of your Clang 13 installation by running: 242 243```sh 244clang-13 -print-resource-dir 245``` 246 247#### ARMv8 248 249When building for an ARMv8 product the sysroot path of the GNU Arm Embedded 250Toolchain must be passed under the `SYSROOT` environment variable. 251 252Building example for all of the R-Car targets: 253 254```sh 255make -f Makefile.cmake PRODUCT=rcar TOOLCHAIN=GNU \ 256 LLVM_SYSROOT_CC=/path/to/sysroot 257``` 258 259## Running the SCP-firmware on Total Compute (TC) platforms 260 261For setting up the environment, installing all dependencies, configuration, 262building the system and running it on an FVP, please refer to, and follow, the 263[TC2 User Guide]. Bear in mind that the installation process might require root 264privileges. 265 266[TC2 User guide]: 267https://gitlab.arm.com/arm-reference-solutions/arm-reference-solutions-docs/-/blob/master/docs/totalcompute/tc2/user-guide.rst 268 269The instructions within this section use TC2 BSP only without Android 270(buildroot) as an example platform, but they are relevant for all TC platforms. 271 272After setting up the environment it would be desirable to set a SCP-firmware 273version, to do that please run: 274 275```sh 276cd <tc2_workspace>/src/SCP-firmware 277git fetch <remote name/url> <branch/tag/hash commit id> 278git checkout FETCH_HEAD 279``` 280 281### Build all components 282 283```sh 284export PLATFORM=tc2 285export FILESYSTEM=buildroot 286<tc2_workspace>/build-scripts/build-all.sh -p $PLATFORM -f $FILESYSTEM build 287``` 288 289### Running Buildroot 290 291When all build images are created and deployed you can run the following command 292to test the system in a FVP. 293 294```sh 295<tc2_workspace>/run-scripts/tc2/run_model.sh -m <model binary path> -d buildroot 296``` 297 298### Obtaining the TC2 FVP 299The TC2 FVP is available to partners for build and run on Linux host 300environments. Please contact Arm to have access (support@arm.com). 301 302 303## Running the SCP firmware on SGI and Neoverse Reference Design platforms 304 305For an introduction to the System Guidance for Infrastructure (SGI) platforms, 306please refer to [System Guidance for Infrastructure (SGI)]. 307 308[System Guidance for Infrastructure (SGI)]: https://community.arm.com/developer/tools-software/oss-platforms/w/docs/387/system-guidance-for-infrastructure-sgi 309 310For an introduction to the Neoverse Reference Design (RD) platforms, please 311refer to [Neoverse Reference Designs]. 312 313[Neoverse Reference Designs]: https://developer.arm.com/tools-and-software/development-boards/neoverse-reference-design 314 315The instructions within this section use SGI-575 as an example platform, but 316they are relevant for all SGI and Neoverse Reference Design platforms. 317 318### Building the images 319 320The build system generates firmware images per the `product.mk` file associated 321with the product. For SGI and Neoverse Reference Design platforms, three 322firmware images are built: 323 324- `sgi575-bl1.bin`: SCP ROM firmware image - loads the SCP RAM firmware from NOR 325 flash into private SRAM and jumps to it 326- `sgi575-bl2.bin`: SCP RAM firmware image - manages the system runtime services 327- `sgi575-mcp-bl1.bin`: MCP ROM firmware image 328 329```sh 330cd ${SCP_PATH} && \ 331 make -f Makefile.cmake PRODUCT=sgi575 MODE=debug 332 333export SCP_ROM_PATH=${SCP_PATH}/build/sgi575/GNU/debug/firmware-scp_romfw/bin/\ 334sgi575-bl1.bin 335export SCP_RAM_PATH=${SCP_PATH}/build/sgi575/GNU/debug/firmware-scp_ramfw/bin/\ 336sgi575-bl2.bin 337export MCP_ROM_PATH=${SCP_PATH}/build/sgi575/GNU/debug/firmware-mcp_romfw/bin/\ 338sgi575-mcp-bl1.bin 339``` 340 341__Note:__ If building with LLVM, make sure to pass the required environment 342variables to `make` as noted in [Building with LLVM](#building-with-llvm). 343 344### Creating the NOR flash image 345 346Unlike in the System Guidance for Mobile platforms, a secure-world application 347processor firmware is not required to load the SCP firmware. Instead, the SCP 348ROM firmware loads the SCP RAM firmware directly from NOR flash memory at a 349fixed address. 350 351To create a NOR flash image containing only the SCP RAM firmware, use: 352 353```sh 354export NOR_PATH=/tmp/nor.bin 355 356dd if=/dev/zero of=${NOR_PATH} bs=1024 count=62976 && \ 357cat ${SCP_RAM_PATH} >> ${NOR_PATH} 358``` 359 360### Booting the firmware 361 362To simulate the basic SCP boot flow on the SGI-575 FVP, use the following 363command line: 364 365```sh 366FVP_CSS_SGI-575 \ 367 -C css.scp.ROMloader.fname=${SCP_ROM_PATH} \ 368 -C css.mcp.ROMloader.fname=${MCP_ROM_PATH} \ 369 -C board.flashloader0.fname=${NOR_PATH} 370``` 371 372## Running the SCP firmware on the Juno Development Board 373 374For an introduction to the Juno Development Board, please refer to 375[the Arm Developer documentation]. 376 377[the Arm Developer documentation]: 378https://community.arm.com/developer/tools-software/oss-platforms/w/docs/485/juno 379 380### Building the images 381 382The build system generates firmware images per the `product.mk` file associated 383with the product. For Juno platform, three firmware images are built: 384 385- `juno-bl1.bin`: SCP ROM firmware image - handles the transfer of the RAM 386 firmware to private SRAM and jumps to it 387- `juno-bl1-bypass.bin`: SCP ROM bypass firmware image - an alternative ROM 388 firmware that is loaded from an external non volatile on-board memory. 389 This binary needs to be used in order to successfully load the SCP RAM 390 firmware, and is chain-loaded from the burned-in ROM on the physical board 391 (not necessary for the FVP). 392- `juno-bl2.bin`: SCP RAM firmware image - manages the system runtime services 393 394```sh 395cd ${SCP_PATH} && \ 396 make -f Makefile.cmake PRODUCT=juno MODE=debug 397 398export SCP_ROM_PATH=${SCP_PATH}/build/juno/GNU/debug/firmware-scp_romfw/\ 399bin/juno-bl1.bin 400export SCP_ROM_BYPASS_PATH=${SCP_PATH}/build/juno/GNU/debug/\ 401firmware-scp_romfw-byopass/bin/juno-bl1-bypass.bin 402export SCP_RAM_PATH=${SCP_PATH}/build/juno/GNU/debug/firmware-scp_ramfw/\ 403bin/juno-bl2.bin 404``` 405 406__Note:__ If building with LLVM, make sure to pass the required environment 407variables as noted in [Building with LLVM](#building-with-llvm). 408 409### Booting the firmware 410 411In order for the `juno-bl2.bin` firmware image to be loaded, an application 412processor secure world firmware needs to be available to load it. Arm maintains 413the [Arm Trusted Firmware-A (TF-A)] project, which handles this case. The 414remaining instructions assume you are using Trusted Firmware-A. 415 416[Arm Trusted Firmware-A (TF-A)]: 417https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git 418 419To boot the SCP firmware on Juno with TF-A, you will need at minimum 420three additional images: 421 422- `bl1`: BL1 - first-stage bootloader stored in the system ROM 423- `bl2`: BL2 - second-stage bootloader loaded by `bl1`, responsible for handing 424 over `scp_bl2` to the SCP 425- `fip`: FIP - firmware image package containing `bl2` and `scp_bl2` 426 427The FIP format acts as a container for a number of commonly-used images in the 428TF-A boot flow. Documentation for the FIP format can be found in the [TF-A 429firmware design documentation]. 430 431[TF-A firmware design documentation]: 432https://trustedfirmware-a.readthedocs.io/en/latest/design/firmware-design.html?highlight=fip#firmware-image-package-fip 433 434An example command line to build Arm Trusted Firmware-A for AArch64 is given 435below. Note that you will need to have installed [the prerequisites for building 436Arm Trusted Firmware-A for Juno]. 437 438[the prerequisites for building Arm Trusted Firmware-A for Juno]: 439https://trustedfirmware-a.readthedocs.io/en/latest/getting_started/docs-build.html 440 441 442```sh 443export TFA_PATH=<your Trusted Firmware-A path> 444 445git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git \ 446${TFA_PATH} 447 448cd ${TFA_PATH} 449 450make CROSS_COMPILE=aarch64-linux-gnu- DEBUG=1 LOG_LEVEL=30 PLAT=juno \ 451 CSS_USE_SCMI_SDS_DRIVER=1 SCP_BL2=<path to scp_bl2> \ 452 BL33=<path to bl33file> bl1 bl2 fip 453 454export BL1_PATH=${TFA_PATH}/build/juno/debug/bl1.bin 455export BL2_PATH=${TFA_PATH}/build/juno/debug/bl2.bin 456export FIP_PATH=${TFA_PATH}/build/juno/debug/fip.bin 457 458``` 459 460Before beginning, please ensure the SD card used for your Juno board has been 461set up with a Linaro release software stack. If this is not the case, you can 462follow the [Linaro software release instructions] and/or download a new SD card 463filesystem from the [Linaro releases page]. 464 465[Linaro software release instructions]: 466https://git.linaro.org/landing-teams/working/arm/arm-reference-platforms.git/about/docs/juno/user-guide.rst 467[Linaro releases page]: https://releases.linaro.org/members/arm/platforms/ 468 469Once your SD card has been set up, you can do the following to get started with 470building and running the SCP firmware: 471 472- Replace `SOFTWARE/fip.bin` with your version of `fip.bin` 473- Replace `SOFTWARE/bl1.bin` with your version of `bl1.bin` 474- Replace `SOFTWARE/scp_bl1.bin` with your version of `scp_romfw_bypass.bin` 475 476Lastly, ensure your host has synchronized any buffered data on the SD card (on 477Linux and Unix systems, this can be done with the `sync` command) and reset the 478board. 479 480You can see the progress of the boot by connecting the UART to your host PC 481(please follow the instructions in the Juno [Getting Started Guide]). 482 483[Getting Started Guide]: https://developer.arm.com/documentation/dui0928/e 484 485## Software stack 486 487Arm provides [a super-project] with guides for building and running a full 488software stack on Arm platforms. This project provides a convenient wrapper 489around the various build systems involved in the software stack, including for 490SCP-firmware. 491 492[a super-project]: 493https://git.linaro.org/landing-teams/working/arm/arm-reference-platforms.git/about/docs/user-guide.rst 494 495## Deprecated platforms 496 497This section provides some guidance for deprecating a platform. The code in 498this case remains in the repository, but support is no longer provided. 499The process involves removing the chosen platform from the build and adding it 500to the list of deprecated platforms. 501 5021. Remove the chosen-platform from the "products" list in tools/ci_cmake.py 5032. Add the chosen-platform to the "DEPRECATED_PLATFORMS" list in Makefile.cmake 5043. Submit a change to this repository 505