doc: Update user guide and version numbers

This commit updates the user guide and supporting documentation to bring
it in-line with the latest v2.5.0 release. It changes the Markdown
header syntax in order to represent deeper header levels, replaces old
links and attempts to clear up areas of potential confusion with
instructions.

Change-Id: I99b464a4bc94f4618779fbe09b1aa77bed0c318e
Signed-off-by: Chris Kay <chris.kay@arm.com>

1 files changed, 206 insertions, 209 deletions

diff --git a/user_guide.md b/user_guide.md
index 4c16c114..9cb33bfd 100644
--- a/user_guide.md
+++ b/user_guide.md
@@ -1,5 +1,4 @@
-SCP-firmware User Guide
-=======================
+# 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
@@ -7,64 +6,89 @@ 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
--------------------------
+## 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.
 
-The software has been tested on Ubuntu 16.04 LTS (64-bit). Packages used for
-building the software were installed from that distribution's official
-repositories, unless otherwise specified.
+This software has been tested on Ubuntu 16.04 LTS (64-bit).
 
-Prerequisites (tools)
----------------------
+## Prerequisites
 
 To build the SCP/MCP firmware for a target product, the following tools are
 required:
 
-- Git
-- [GNU Arm Embedded Toolchain ("6-2017-q2-update" or later)](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm)
-- GNU Make (4.2 or later)
-- Python 3 (3.5.0 or later)
+- [GNU Make](https://www.gnu.org/software/make/) (*4.2* or later)
+- [Python 3](https://www.python.org/download/releases/3.0/) (*3.5.0* or later)
 
-In addition, the following tools are recommended:
+Additionally, the firmware may be built using one of two compilers:
+- [GNU Arm Embedded Toolchain](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm)
+    (*6-2017-q2-update* or later)
+- [Arm Compiler 6](https://developer.arm.com/tools-and-software/embedded/arm-compiler/downloads/version-6)
+    (*6.10* or later)
 
-- Doxygen (1.8.0 or later): Required to build supporting documentation
-- GCC (6.0 or later): Required to build framework tests that run on the host
-    system
+The following tools are recommended but not required:
 
-Getting the SCP-firmware source code
-------------------------------------
+- [Doxygen](http://www.doxygen.nl/) (*1.8.0* or later): Required to generate
+    supporting documentation
+- [GNU GCC](https://gcc.gnu.org/) (*6.0* or later): Required to build framework
+    tests that run on the host system
 
-Download the SCP-firmware source code from Github:
+If building for an Arm FVP platform, you will need to ensure you have
+[the relevant FVP](https://developer.arm.com/products/system-design/fixed-virtual-platforms).
 
-    $> git clone https://github.com/ARM-software/SCP-firmware.git
+The FVPs also have a soft dependency on the following tools:
 
-Prerequisites (CMSIS Libraries)
--------------------------------
+- [xterm](https://invisible-island.net/xterm/): Required to view UART output
 
-SCP-firmware uses components from the Cortex Microcontroller System Interface
-Standard (CMSIS) software pack, specifically the CMSIS Core and CMSIS Real-Time
-Operating System (RTOS) components. The CMSIS software pack is included as a Git
-submodule.
+The instructions provided as a part of this guide assume you have [Git](https://git-scm.com/)
+(*2.13* or later) available in your environment.
 
-To retrieve the required version of the CMSIS software, first ensure you have an
-available Git installation, then from within the root directory of SCP-firmware
-initialize and update the submodule with:
+Installing these prerequisites can be done on any standard Debian-based system
+with the following:
 
-    $> git submodule update --init
+```sh
+sudo add-apt-repository ppa:team-gcc-arm-embedded/ppa
+sudo apt update
+sudo apt install build-essential doxygen gcc-arm-embedded git python3
+```
 
-Documentation
--------------
+For the FVP prerequisites:
+
+```sh
+sudo apt install xterm
+```
+
+## Cloning the SCP-firmware source code
+
+The SCP-firmware source code can be cloned from the official GitHub repository:
+
+```sh
+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)](https://www.arm.com/why-arm/technologies/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:
+
+```sh
+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
+HTML, LaTeX, and XML formats and placed in the `build/doc` directory. This
 documentation includes:
 
-- A *Readme* section
+- 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)
@@ -80,232 +104,205 @@ documentation includes:
 From within the SCP-firmware root directory Doxygen can be invoked using the
 top-level Makefile:
 
-    $> make doc
+```sh
+make doc
+```
 
-Building SCP-firmware
----------------------
+## Building SCP-firmware
 
 To build SCP-firmware for a specific product the basic command format for
-invoking 'make' is:
+invoking `make` (from within the source directory) is:
 
-    $> make <PRODUCT=<name>> [OPTIONS] [TARGET]
+```sh
+make CC=<COMPILER> PRODUCT=<PRODUCT> [OPTIONS] [TARGET]
+```
 
-It is not necessary to provide a firmware target as the default target for the
-product will build all the firmware contained within it.
+For example, to build the RAM firmware for SGM-775 in debug mode, use the
+following:
 
-The 'help' target provides further information on the arguments that can be
+```sh
+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
+```sh
+make help
+```
 
 The framework includes a suite of tests that validate its core functionality.
-These can be run on the host system using:
+If you installed the native GCC prerequisite, these can be run on the host
+system using:
 
-    $> make test
+```sh
+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 parameter, which should
-point to the cross-compiler. It can be set as an environment variable before
-invoking 'make', or provided as part of the build command:
+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> ...
+```sh
+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 documentation.
+documentation included in the *Build System* chapter of the Doxygen-generated
+documentation.
 
-Running the SCP firmware on System Guidance for Mobile (SGM) platforms
-----------------------------------------------------------------------
+## Running the SCP firmware on SGM platforms
 
 For an introduction to the System Guidance for Mobile (SGM) platforms, please
-refer to [System Guidance for Mobile (SGM)](https://community.arm.com/dev-platforms/w/docs/388/system-guidance-for-mobile-sgm).
-
-The build system generates the list of firmware images as defined by the
-product.mk file associated with the product. For SGM platforms, two firmware
-images are built: scp_romfw.bin and scp_ramfw.bin.
-
-The scp_romfw.bin firmware image exists in the ROM of the system. It is the
-first firmware image executed when booting an SGM platform. It does the minimal
-setup and initialization of the system, and powers on the primary application
-core. Then, it waits for the primary core to load the scp_ramfw.bin image into
-secure RAM before handing over execution to it.
-
-The scp_ramfw.bin firmware image provides all the runtime services delegated to
-the SCP as a part of the system. It is loaded by the primary core and not the
-scp_romfw.bin firmware to leverage the processing power of the application
-processor for image authentication.
-
-In order for the scp_ramfw.bin firmware image to be loaded per the boot flow
-described above, a minimal application processor firmware needs to be available.
-This typically consists of at least two images:
-
-- bl1: First-stage bootloader stored in the system ROM
-- bl2: Second-stage bootloader loaded by bl1, responsible for loading the
-    scp_ramfw.bin firmware image and other application processor firmware images
-    into system RAM
-
-For more information about application processor firmware images and how to
-build them, please refer to the [Arm Trusted Firmware-A user guide](https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/getting_started/user-guide.rst).
-
-In order for the bl2 firmware image and the scp_ramfw.bin firmware image to be
-made available to their respective loaders, they must be packaged in a Firmware
-Image Package (FIP). Please refer to the Arm Trusted Firmware-A user guide for
-instructions on building FIP packages.
-
-To run the boot flow described above on an SGM platform FVP, use:
-
-    $> <path to the SGM platform FVP> \
-        -C soc.pl011_uart0.out_file=./ap.txt \
-        -C soc.pl011_uart1.out_file=./scp.txt \
-        -C css.scp.ROMloader.fname=<path to scp_romfw.bin firmware image> \
-        -C css.trustedBootROMloader.fname=<path to bl1 firmware image> \
-        -C board.flashloader0.fname=<path to FIP> \
-        -C soc.pl011_uart1.unbuffered_output=1 \
-        -C soc.pl011_uart0.unbuffered_output=1
-
-Note:
-    - SGM platform FVPs are available on
-        [the Fixed Virtual Platforms product page](https://developer.arm.com/products/system-design/fixed-virtual-platforms).
-    - The application processor firmware images can be built using the
-        [Arm Platforms deliverables](https://community.arm.com/dev-platforms/w/docs/304/arm-platforms-deliverables).
-        See the following section.
-
-Running the SCP/MCP firmware on System Guidance for Infrastructure platforms
-----------------------------------------------------------------------------
+refer to [the Arm Developer documentation](https://community.arm.com/developer/tools-software/oss-platforms/w/docs/388/system-guidance-for-mobile-sgm).
 
-For an introduction to the System Guidance for Infrastructure (SGI) platforms,
-please refer to [System Guidance for Infrastructure (SGI)](https://community.arm.com/developer/tools-software/oss-platforms/w/docs/387/system-guidance-for-infrastructure-sgi).
+The instructions within this section use SGM-775 as an example platform, but
+they are relevant for all SGM platforms.
 
-The build system generates the list of firmware images as defined by the
-product.mk file associated with the product. For SGI platforms, three firmware
-images are built: scp_romfw.bin, mcp_romfw.bin and scp_ramfw.bin.
+### Building the images
 
-The scp_romfw.bin and mcp_romfw.bin firmware images exist in the ROM of the
-system. They are the first firmware images executed when booting an SGI
-platform.
+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
 
-The scp_romfw.bin image does the minimal setup and initialization of the system
-and then loads from the flash the scp_ramfw.bin image into secure RAM before
-handing over execution to it.
+```sh
+cd ${SCP_PATH} && \
+    make CC=arm-none-eabi-gcc PRODUCT=sgm775 MODE=debug
 
-The scp_ramfw.bin firmware image provides all the runtime services delegated to
-the SCP as a part of the system.
+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
+```
 
-The mcp_romfw.bin image initializes the MCP.
+### Booting the firmware
 
-To run the boot flow described above on an SGI platform FVP, use:
+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)](https://github.com/ARM-software/arm-trusted-firmware)
+project, which handles this case. The remaining instructions assume you are
+using Trusted Firmware-A.
 
-    $> <path to the SGI platform FVP> \
-        -C css.scp.pl011_uart_scp.out_file=./scp.txt \
-        -C css.mcp.pl011_uart0_mcp.out_file=./mcp.txt \
-        -C css.scp.ROMloader.fname=<path to scp_romfw.bin firmware image> \
-        -C board.flashloader0.fname=<path to nor.bin file (see below)> \
-        -C css.mcp.ROMloader.fname=<path to mcp_romfw.bin firmware image> \
-        -C css.mcp.pl011_uart0_mcp.unbuffered_output=1 \
-        -C css.scp.pl011_uart_scp.unbuffered_output=1
+On SGM platforms, the SCP images are given alternative names when used in the
+context of TF-A:
 
-Note:
-    - SGI platform FVPs are available on
-        [the Fixed Virtual Platforms product page](https://developer.arm.com/products/system-design/fixed-virtual-platforms).
-    - The scp_romfw.bin image expects the scp_ramfw.bin image to be located at
-      the offset 0x03D80000 in the NOR flash. The content of the NOR flash is
-      passed to the model as a nor.bin binary file. The nor.bin file can be
-      build in the current working directory as follow:
+- `scp_romfw.bin` has the alternative name `scp_bl1`
+- `scp_ramfw.bin` has the alternative name `scp_bl2`
 
-      $> dd if=/dev/zero of=nor.bin bs=1024 count=62976
-      $> cat <path to scp_ramfw.bin image> >> nor.bin
+To boot the SCP firmware on SGM platforms with TF-A, you will need at minimum
+three additional images:
 
-      The first command creates a nor.bin file of size 0x3D80000 filed in with
-      zeroes. The second command appends the scp_ramfw.bin image to the nor.bin
-      file.
+- `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`
 
-Running the SCP/MCP firmware on Neoverse reference designs
-----------------------------------------------------------
+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](https://github.com/ARM-software/arm-trusted-firmware/blob/v2.1/docs/firmware-design.rst#firmware-image-package-fip).
 
-For an introduction to the Neoverse reference designs,
-please refer to [Neoverse reference designs](https://community.arm.com/developer/tools-software/oss-platforms/w/docs/443/neoverse-reference-designs).
+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](https://github.com/ARM-software/arm-trusted-firmware/blob/v2.1/docs/user-guide.rst#tools).
 
-The build system generates the list of firmware images as defined by the
-product.mk file associated with the product. For Neoverse reference designs,
-three firmware images are built: scp_romfw.bin, mcp_romfw.bin and
-scp_ramfw.bin.
+```sh
+git clone -b v2.1 https://github.com/ARM-software/arm-trusted-firmware.git ${TFA_PATH}
 
-The scp_romfw.bin and mcp_romfw.bin firmware image exist in the ROM of the
-system. They are the first firmware images executed when booting a Neoverse
-reference design.
+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
 
-The scp_romfw.bin image does the minimal setup and initialization of the system
-and then loads the scp_ramfw.bin image into secure RAM before handing over
-execution to it.
+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 && \
+    ./tools/fiptool/fiptool create \
+        --tb-fw ${BL2_PATH} \
+        --scp-fw ${SCP_RAM_PATH} \
+            ${FIP_PATH}
+```
 
-The scp_ramfw.bin firmware image provides all the runtime services delegated to
-the SCP as a part of the system.
+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.
 
-The mcp_romfw.bin image initializes the MCP.
+To simulate the basic SCP boot flow on the SGM-775 FVP, use the following
+command line:
 
-To run the boot flow described above on an Neoverse reference design FVP, use:
+```sh
+FVP_CSS_SGM-775 \
+    -C css.trustedBootROMloader.fname=${BL1_PATH} \
+    -C css.scp.ROMloader.fname=${SCP_ROM_PATH} \
+    -C board.flashloader0.fname=${FIP_PATH}
+```
 
-    $> <path to the Neoverse reference design FVP> \
-        -C css.scp.pl011_uart_scp.out_file=./scp.txt \
-        -C css.mcp.pl011_uart0_mcp.out_file=./mcp.txt \
-        -C css.scp.ROMloader.fname=<path to scp_romfw.bin firmware image> \
-        -C board.flashloader0.fname=<path to nor.bin file (see below)> \
-        -C css.mcp.ROMloader.fname=<path to mcp_romfw.bin firmware image> \
-        -C css.mcp.pl011_uart0_mcp.unbuffered_output=1 \
-        -C css.scp.pl011_uart_scp.unbuffered_output=1
+Note that it's expected that TF-A will crash, as we have not provided the full
+bootloader image chain.
 
-Note:
-    - Neoverse reference designs FVPs are available on
-        [the Fixed Virtual Platforms product page](https://developer.arm.com/products/system-design/fixed-virtual-platforms).
+## 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)](https://community.arm.com/developer/tools-software/oss-platforms/w/docs/387/system-guidance-for-infrastructure-sgi).
 
-    - The scp_romfw.bin image expects the scp_ramfw.bin image to be located at
-      the offset 0x03D80000 in the NOR flash. The content of the NOR flash is
-      passed to the model as a nor.bin binary file. The nor.bin file can be
-      build in the current working directory as follow:
+For an introduction to the Neoverse Reference Design (RD) platforms, please
+refer to [Neoverse Reference Designs](https://community.arm.com/developer/tools-software/oss-platforms/w/docs/387/system-guidance-for-infrastructure-sgi).
 
-      $> dd if=/dev/zero of=nor.bin bs=1024 count=62976
-      $> cat <path to scp_ramfw.bin image> >> nor.bin
+The instructions within this section use SGI-575 as an example platform, but
+they are relevant for all SGI and Neoverse Reference Design platforms.
 
-      The first command creates a nor.bin file of size 0x3D80000 filed in with
-      zeroes. The second command appends the scp_ramfw.bin image to the nor.bin
-      file.
+### Building the images
 
-Booting up to the Linux prompt on Arm platforms
------------------------------------------------
+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
 
-The [Arm Reference Platforms deliverables](https://community.arm.com/dev-platforms/w/docs/304/arm-reference-platforms-deliverables)
-provide a set of source code bases and prebuilt binaries of a fully bootable
-Linux software stack on supported Arm platforms.
+```sh
+cd ${SCP_PATH} && \
+    make CC=arm-none-eabi-gcc PRODUCT=sgi575 MODE=debug
 
-This section explains how to update the SCP-firmware binaries once the full
-software stack has been fully built from source for a given configuration.
+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
+```
 
-To retrieve, build and run the software stack from source for a given Arm
-platform, please refer to [Run the Arm Platforms deliverables on an FVP](https://community.arm.com/dev-platforms/w/docs/392/run-the-arm-platforms-deliverables-on-an-fvp).
+### Creating the NOR flash image
 
-Note that the script initializing the workspace does not currently download the
-gcc-arm-none-eabi-5_4-2016q3 toolchain needed to build SCP-firmware. As
-such, you will need to download it from [here](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads)
-and extract it into the workspace/tools/gcc/gcc-arm-none-eabi-5_4-2016q3
-directory.
+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.
 
-Once the software stack has been retrieved, the SCP/MCP source code can be found
-in the 'scp' directory at the root of the workspace.
+To create a NOR flash image containing only the SCP RAM firmware, use:
 
-To rebuild the SCP-firmware binaries without rebuilding the whole software
-stack, at the root of the framework, use:
+```sh
+export NOR_PATH=/tmp/nor.bin
 
-    $> ./build-scripts/build-scp.sh build
+dd if=/dev/zero of=${NOR_PATH} bs=1024 count=62976 && \
+cat ${SCP_RAM_PATH} >> ${NOR_PATH}
+```
 
-Once the software stack has been fully built, use the following to update the
-SCP binaries in the software package to be run:
+### Booting the firmware
 
-    $> ./build-scripts/build-all.sh package
+To simulate the basic SCP boot flow on the SGI-575 FVP, use the following
+command line:
 
-As an example, to run the software stack, on the SGM-775 FVP:
+```sh
+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}
+```
 
-    $> export MODEL=/path/to/where/you/separately/installed/FVP_CSS_SGM-775
-    $> cd ./model-scripts/sgm775
-    $> ./run_model.sh -t sgm775
+## Software stack
 
-The SCP ROM/RAM firmware logs are written to the FVP terminal_s1 window, where
-the firmware tag or commit identifier can also be found.
+Arm provides [a super-project](https://git.linaro.org/landing-teams/working/arm/arm-reference-platforms.git/about/docs/user-guide.rst)
+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.