Push old Amlogic BL2 sourcesHEADmaster

1 files changed, 841 insertions, 0 deletions

diff --git a/docs/user-guide.md b/docs/user-guide.md
new file mode 100644
index 0000000..40a7955
--- /dev/null
+++ b/docs/user-guide.md
@@ -0,0 +1,841 @@
+ARM Trusted Firmware User Guide
+===============================
+
+Contents :
+
+1.  Introduction
+2.  Host machine requirements
+3.  Tools
+4.  Building the Trusted Firmware
+5.  Obtaining the normal world software
+6.  Running the software
+
+
+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 ARM
+Fixed Virtual Platform (FVP) models. It is possible to use other software
+components, configurations and platforms but that is outside the scope of this
+document.
+
+This document should be 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 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 12.04.04 (64-bit).  Packages used
+for building the software were installed from that distribution unless
+otherwise specified.
+
+
+3.  Tools
+---------
+
+The following tools are required to use the ARM Trusted Firmware:
+
+*   `git` package to obtain source code
+
+*   `ia32-libs` package
+
+*   `build-essential` and `uuid-dev` packages for building UEFI and the Firmware
+    Image Package(FIP) tool
+
+*   `bc` and `ncurses-dev` packages for building Linux
+
+*   Baremetal GNU GCC tools. Verified packages can be downloaded from [Linaro]
+    [Linaro Toolchain]. The rest of this document assumes that the
+    `gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz` tools are used.
+
+        wget http://releases.linaro.org/13.11/components/toolchain/binaries/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz
+        tar -xf gcc-linaro-aarch64-none-elf-4.8-2013.11_linux.tar.xz
+
+*   The Device Tree Compiler (DTC) included with Linux kernel 3.15-rc6 is used
+    to build the Flattened Device Tree (FDT) source files (`.dts` files)
+    provided with this software.
+
+*   (Optional) For debugging, ARM [Development Studio 5 (DS-5)][DS-5] v5.18.
+
+
+4.  Building the Trusted Firmware
+---------------------------------
+
+To build the software for the FVPs, follow these steps:
+
+1.  Clone the ARM Trusted Firmware repository from GitHub:
+
+        git clone https://github.com/ARM-software/arm-trusted-firmware.git
+
+2.  Change to the trusted firmware directory:
+
+        cd arm-trusted-firmware
+
+3.  Set the compiler path, specify a Non-trusted Firmware image (BL3-3) and
+    build:
+
+        CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- \
+        BL33=<path-to>/<bl33_image>                               \
+        make PLAT=fvp all fip
+
+    See the "Summary of build options" for information on available build
+    options.
+
+    By default this produces a release version of the build. To produce a debug
+    version instead, refer to the "Debugging options" section below. UEFI can be
+    used as the BL3-3 image, refer to the "Obtaining the normal world software"
+    section below. By default this won't compile the TSP in, refer to the
+    "Building the Test Secure Payload" 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 are 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>` currently defaults to `fvp` and `<build-type>` is
+    either `debug` or `release`. A Firmare Image Package(FIP) will be 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].
+
+4.  Copy the `bl1.bin` and `fip.bin` binary files to the directory from which
+    the FVP will be launched. Symbolic links of the same names may be created
+    instead.
+
+5.  (Optional) Build products for a specific build variant can be removed using:
+
+        make DEBUG=<D> PLAT=fvp clean
+
+    ... where `<D>` is `0` or `1`, as specified when building.
+
+    The build tree can be removed completely using:
+
+        make realclean
+
+### Summary of build options
+
+ARM Trusted Firmware build system supports the following build options. 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 dependency for build options. Therefore, if any
+of the build options are changed from a previous build, a clean build must be
+performed.
+
+*   `BL33`: Path to BL33 image in the host file system. This is mandatory for
+    `fip` target
+
+*   `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 be passed for the `fip`
+    target
+
+*   `CROSS_COMPILE`: Prefix to tool chain binaries. Please 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
+
+*   `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 be the name of one of the directories under the `plat/`
+    directory other than `common`
+
+*   `SPD`: Choose a Secure Payload Dispatcher component to be built into the
+    Trusted Firmware. The value should be the path to the directory containing
+    SPD source; the directory is expected to contain `spd.mk` makefile
+
+*   `V`: Verbose build. If assigned anything other than 0, the build commands
+    are printed. Default is 0
+
+*   `FVP_GIC_ARCH`: Choice of ARM GIC architecture version used by the FVP port
+    for implementing the platform GIC API. This API is used by the interrupt
+    management framework. Default is 2 i.e. version 2.0
+
+*   `IMF_READ_INTERRUPT_ID`: Boolean flag used by the interrupt management
+    framework to enable passing of the interrupt id to its handler. The id is
+    read using a platform GIC API. `INTR_ID_UNAVAILABLE` is passed instead if
+    this option set to 0. Default is 0.
+
+*   `RESET_TO_BL31`: Enable BL3-1 entrypoint as the CPU reset vector in place
+    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.
+
+
+### Creating a Firmware Image Package
+
+FIPs are automatically created as part of the build instructions described in
+the previous section. It is also possible to independently build the FIP
+creation tool and FIPs if required. To do this, follow these steps:
+
+Build the tool:
+
+    make -C tools/fip_create
+
+It is recommended to remove the build artifacts before rebuilding:
+
+    make -C tools/fip_create clean
+
+Create a Firmware package that contains existing FVP BL2 and BL3-1 images:
+
+    # fip_create --help to print usage information
+    # fip_create <fip_name> <images to add> [--dump to show result]
+    ./tools/fip_create/fip_create fip.bin --dump \
+       --bl2 build/fvp/debug/bl2.bin --bl31 build/fvp/debug/bl31.bin
+
+     Firmware Image Package ToC:
+    ---------------------------
+    - Trusted Boot Firmware BL2: offset=0x88, size=0x81E8
+      file: 'build/fvp/debug/bl2.bin'
+    - EL3 Runtime Firmware BL3-1: offset=0x8270, size=0xC218
+      file: 'build/fvp/debug/bl31.bin'
+    ---------------------------
+    Creating "fip.bin"
+
+View the contents of an existing Firmware package:
+
+    ./tools/fip_create/fip_create fip.bin --dump
+
+     Firmware Image Package ToC:
+    ---------------------------
+    - Trusted Boot Firmware BL2: offset=0x88, size=0x81E8
+    - EL3 Runtime Firmware BL3-1: offset=0x8270, size=0xC218
+    ---------------------------
+
+Existing package entries can be individially updated:
+
+    # Change the BL2 from Debug to Release version
+    ./tools/fip_create/fip_create fip.bin --dump \
+      --bl2 build/fvp/release/bl2.bin
+
+    Firmware Image Package ToC:
+    ---------------------------
+    - Trusted Boot Firmware BL2: offset=0x88, size=0x7240
+      file: 'build/fvp/release/bl2.bin'
+    - EL3 Runtime Firmware BL3-1: offset=0x72C8, size=0xC218
+    ---------------------------
+    Updating "fip.bin"
+
+
+### Debugging options
+
+To compile a debug version and make the build more verbose use
+
+    CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- \
+    BL33=<path-to>/<bl33_image>                               \
+    make PLAT=fvp DEBUG=1 V=1 all fip
+
+AArch64 GCC uses DWARF version 4 debugging symbols by default. Some tools (for
+example DS-5) might not support this and may need an older version of DWARF
+symbols to be emitted by GCC. This can be achieved by using the
+`-gdwarf-<version>` flag, with the version being set to 2 or 3. Setting the
+version to 2 is recommended for DS-5 versions older than 5.16.
+
+When debugging logic problems it might also be useful to disable all compiler
+optimizations by using `-O0`.
+
+NOTE: Using `-O0` could cause output images to be larger and base addresses
+might need to be recalculated (see the later memory layout section).
+
+Extra debug options can be passed to the build system by setting `CFLAGS`:
+
+    CFLAGS='-O0 -gdwarf-2'                                    \
+    CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- \
+    BL33=<path-to>/<bl33_image>                               \
+    make PLAT=fvp DEBUG=1 V=1 all fip
+
+
+NOTE: The Foundation FVP does not provide a debugger interface.
+
+
+### Building the Test Secure Payload
+
+The TSP is coupled with a companion runtime service in the BL3-1 firmware,
+called the TSPD. Therefore, if you intend to use the TSP, the BL3-1 image
+must be recompiled as well. For more information on SPs and SPDs, see the
+"Secure-EL1 Payloads and Dispatchers" section in the [Firmware Design].
+
+First clean the Trusted Firmware build directory to get rid of any previous
+BL3-1 binary. Then to build the TSP image and include it into the FIP use:
+
+    CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- \
+    BL33=<path-to>/<bl33_image>                               \
+    make PLAT=fvp SPD=tspd all fip
+
+An additional boot loader binary file is created in the `build` directory:
+
+    *   `build/<platform>/<build-type>/bl32.bin`
+
+The Firmware Package contains this new image:
+
+    Firmware Image Package ToC:
+    ---------------------------
+    - Trusted Boot Firmware BL2: offset=0xD8, size=0x6000
+      file: './build/fvp/release/bl2.bin'
+    - EL3 Runtime Firmware BL3-1: offset=0x60D8, size=0x9000
+      file: './build/fvp/release/bl31.bin'
+    - Secure Payload BL3-2 (Trusted OS): offset=0xF0D8, size=0x3000
+      file: './build/fvp/release/bl32.bin'
+    - Non-Trusted Firmware BL3-3: offset=0x120D8, size=0x280000
+      file: '../FVP_AARCH64_EFI.fd'
+    ---------------------------
+    Creating "build/fvp/release/fip.bin"
+
+On FVP, the TSP binary runs from Trusted SRAM by default. It is also possible
+to run it from Trusted DRAM. This is controlled by the build configuration
+`TSP_RAM_LOCATION`:
+
+    CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- \
+    BL33=<path-to>/<bl33_image>                               \
+    make PLAT=fvp SPD=tspd TSP_RAM_LOCATION=tdram all fip
+
+
+### 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, and to assist with this check
+the project Makefile contains 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 a copy of checkpatch.pl
+(or the full Linux source), set the CHECKPATCH environment variable to point to
+the script and build the target checkcodebase:
+
+    make CHECKPATCH=../linux/scripts/checkpatch.pl checkcodebase
+
+To just check the style on the files that differ between your local branch and
+the remote master, use:
+
+    make CHECKPATCH=../linux/scripts/checkpatch.pl checkpatch
+
+If you wish to check your patch against something other than the remote master,
+set the BASE_COMMIT variable to your desired branch.  By default, BASE_COMMIT
+is set to 'origin/master'.
+
+
+5.  Obtaining the normal world software
+---------------------------------------
+
+### Obtaining EDK2
+
+Potentially any kind of non-trusted firmware may be used with the ARM Trusted
+Firmware but the software has only been tested with the EFI Development Kit 2
+(EDK2) open source implementation of the UEFI specification.
+
+Clone the [EDK2 source code][EDK2] from GitHub. This version supports the Base
+and Foundation FVPs:
+
+    git clone -n https://github.com/tianocore/edk2.git
+    cd edk2
+    git checkout 129ff94661bd3a6c759b1e154c143d0136bedc7d
+
+
+To build the software to be compatible with Foundation and Base FVPs, follow
+these steps:
+
+1.  Copy build config templates to local workspace
+
+        # in edk2/
+        . edksetup.sh
+
+2.  Build the EDK2 host tools
+
+        make -C BaseTools clean
+        make -C BaseTools
+
+3.  Build the EDK2 software
+
+        CROSS_COMPILE=<absolute-path-to-aarch64-gcc>/bin/aarch64-none-elf- \
+        make -f ArmPlatformPkg/Scripts/Makefile EDK2_ARCH=AARCH64          \
+        EDK2_DSC=ArmPlatformPkg/ArmVExpressPkg/ArmVExpress-FVP-AArch64.dsc \
+        EDK2_TOOLCHAIN=ARMGCC EDK2_MACROS="-n 6 -D ARM_FOUNDATION_FVP=1"
+
+    The EDK2 binary for use with the ARM Trusted Firmware can then be found
+    here:
+
+        Build/ArmVExpress-FVP-AArch64/DEBUG_ARMGCC/FV/FVP_AARCH64_EFI.fd
+
+    This will build EDK2 for the default settings as used by the FVPs. The EDK2
+    binary `FVP_AARCH64_EFI.fd` should be specified as `BL33` in in the `make`
+    command line when building the Trusted Firmware. See the "Building the
+    Trusted Firmware" section above.
+
+4.  (Optional) To boot Linux using a VirtioBlock file-system, the command line
+    passed from EDK2 to the Linux kernel must be modified as described in the
+    "Obtaining a root file-system" section below.
+
+5.  (Optional) If legacy GICv2 locations are used, the EDK2 platform description
+    must be updated. This is required as EDK2 does not support probing for the
+    GIC location. To do this, first clean the EDK2 build directory.
+
+        make -f ArmPlatformPkg/Scripts/Makefile EDK2_ARCH=AARCH64          \
+        EDK2_DSC=ArmPlatformPkg/ArmVExpressPkg/ArmVExpress-FVP-AArch64.dsc \
+        EDK2_TOOLCHAIN=ARMGCC clean
+
+    Then rebuild EDK2 as described in step 3, using the following flag:
+
+        -D ARM_FVP_LEGACY_GICV2_LOCATION=1
+
+    Finally rebuild the Trusted Firmware to generate a new FIP using the
+    instructions in the "Building the Trusted Firmware" section.
+
+
+### Obtaining a Linux kernel
+
+The software has been verified using a Linux kernel based on version 3.15-rc6.
+Patches have been applied in order to enable the CPU idle feature.
+
+Preparing a Linux kernel for use on the FVPs with CPU idle support can
+be done as follows (GICv2 support only):
+
+1.  Clone Linux:
+
+        git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
+
+    Not all CPU idle features are included in the mainline kernel yet. To
+    use these, add the patches from Sudeep Holla's kernel:
+
+        cd linux
+        git remote add -f --tags arm64_idle_v3.15-rc6 git://linux-arm.org/linux-skn.git
+        git checkout -b cpuidle arm64_idle_v3.15-rc6
+
+2.  Build with the Linaro GCC tools.
+
+        # in linux/
+        make mrproper
+        make ARCH=arm64 defconfig
+
+        # Enable CPU idle
+        make ARCH=arm64 menuconfig
+        # CPU Power Management ---> CPU Idle ---> [*] CPU idle PM support
+        # CPU Power Management ---> CPU Idle ---> ARM64 CPU Idle Drivers ---> [*] Generic ARM64 CPU idle Driver
+
+        CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- \
+        make -j6 ARCH=arm64
+
+3.  Copy the Linux image `arch/arm64/boot/Image` to the working directory from
+    where the FVP is launched. Alternatively a symbolic link may be used.
+
+### Obtaining the Flattened Device Trees
+
+Depending on the FVP configuration and Linux configuration used, different
+FDT files are required. FDTs for the Foundation and Base FVPs can be found in
+the Trusted Firmware source directory under `fdts/`. The Foundation FVP has a
+subset of the Base FVP components. For example, the Foundation FVP lacks CLCD
+and MMC support, and has only one CPU cluster.
+
+*   `fvp-base-gicv2-psci.dtb`
+
+    (Default) For use with both AEMv8 and Cortex-A57-A53 Base FVPs with
+    Base memory map configuration.
+
+*   `fvp-base-gicv2legacy-psci.dtb`
+
+    For use with AEMv8 Base FVP with legacy VE GIC memory map configuration.
+
+*   `fvp-base-gicv3-psci.dtb`
+
+    For use with both AEMv8 and Cortex-A57-A53 Base FVPs with Base memory map
+    configuration and Linux GICv3 support.
+
+*   `fvp-foundation-gicv2-psci.dtb`
+
+    (Default) For use with Foundation FVP with Base memory map configuration.
+
+*   `fvp-foundation-gicv2legacy-psci.dtb`
+
+    For use with Foundation FVP with legacy VE GIC memory map configuration.
+
+*   `fvp-foundation-gicv3-psci.dtb`
+
+    For use with Foundation FVP with Base memory map configuration and Linux
+    GICv3 support.
+
+
+Copy the chosen FDT blob as `fdt.dtb` to the directory from which the FVP
+is launched. Alternatively a symbolic link may be used.
+
+### Obtaining a root file-system
+
+To prepare a Linaro LAMP based Open Embedded file-system, the following
+instructions can be used as a guide. The file-system can be provided to Linux
+via VirtioBlock or as a RAM-disk. Both methods are described below.
+
+#### Prepare VirtioBlock
+
+To prepare a VirtioBlock file-system, do the following:
+
+1.  Download and unpack the disk image.
+
+    NOTE: The unpacked disk image grows to 3 GiB in size.
+
+        wget http://releases.linaro.org/14.04/openembedded/aarch64/vexpress64-openembedded_lamp-armv8-gcc-4.8_20140417-630.img.gz
+        gunzip vexpress64-openembedded_lamp-armv8-gcc-4.8_20140417-630.img.gz
+
+2.  Make sure the Linux kernel has Virtio support enabled using
+    `make ARCH=arm64 menuconfig`.
+
+        Device Drivers  ---> Virtio drivers  ---> <*> Platform bus driver for memory mapped virtio devices
+        Device Drivers  ---> [*] Block devices  --->  <*> Virtio block driver
+        File systems    ---> <*> The Extended 4 (ext4) filesystem
+
+    If some of these configurations are missing, enable them, save the kernel
+    configuration, then rebuild the kernel image using the instructions
+    provided in the section "Obtaining a Linux kernel".
+
+3.  Change the Kernel command line to include `root=/dev/vda2`. This can either
+    be done in the EDK2 boot menu or in the platform file. Editing the platform
+    file and rebuilding EDK2 will make the change persist. To do this:
+
+    1.  In EDK2, edit the following file:
+
+            ArmPlatformPkg/ArmVExpressPkg/ArmVExpress-FVP-AArch64.dsc
+
+    2.  Add `root=/dev/vda2` to:
+
+            gArmPlatformTokenSpaceGuid.PcdDefaultBootArgument|"<Other default options>"
+
+    3.  Remove the entry:
+
+            gArmPlatformTokenSpaceGuid.PcdDefaultBootInitrdPath|""
+
+    4.  Rebuild EDK2 (see "Obtaining UEFI" section above).
+
+4.  The file-system image file should be provided to the model environment by
+    passing it the correct command line option. In the FVPs the following
+    option should be provided in addition to the ones described in the
+    "Running the software" section below.
+
+    NOTE: A symbolic link to this file cannot be used with the FVP; the path
+    to the real file must be provided.
+
+    On the Base FVPs:
+
+        -C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>"
+
+    On the Foundation FVP:
+
+        --block-device="<path-to>/<file-system-image>"
+
+
+5.  Ensure that the FVP doesn't output any error messages. If the following
+    error message is displayed:
+
+        ERROR: BlockDevice: Failed to open "<path-to>/<file-system-image>"!
+
+    then make sure the path to the file-system image in the model parameter is
+    correct and that read permission is correctly set on the file-system image
+    file.
+
+#### Prepare RAM-disk
+
+To prepare a RAM-disk root file-system, do the following:
+
+1.  Download the file-system image:
+
+        wget http://releases.linaro.org/14.04/openembedded/aarch64/linaro-image-lamp-genericarmv8-20140417-667.rootfs.tar.gz
+
+2.  Modify the Linaro image:
+
+        # Prepare for use as RAM-disk. Normally use MMC, NFS or VirtioBlock.
+        # Be careful, otherwise you could damage your host file-system.
+        mkdir tmp; cd tmp
+        sudo sh -c "zcat ../linaro-image-lamp-genericarmv8-20140417-667.rootfs.tar.gz | cpio -id"
+        sudo ln -s sbin/init .
+        sudo sh -c "echo 'devtmpfs /dev devtmpfs mode=0755,nosuid 0 0' >> etc/fstab"
+        sudo sh -c "find . | cpio --quiet -H newc -o | gzip -3 -n > ../filesystem.cpio.gz"
+        cd ..
+
+3.  Copy the resultant `filesystem.cpio.gz` to the directory where the FVP is
+    launched from. Alternatively a symbolic link may be used.
+
+
+6.  Running the software
+------------------------
+
+This version of the ARM Trusted Firmware has been tested on the following ARM
+FVPs (64-bit versions only).
+
+*   `Foundation_v8` (Version 2.0, Build 0.8.5206)
+*   `FVP_Base_AEMv8A-AEMv8A` (Version 5.6, Build 0.8.5602)
+*   `FVP_Base_Cortex-A57x4-A53x4` (Version 5.6, Build 0.8.5602)
+*   `FVP_Base_Cortex-A57x1-A53x1` (Version 5.6, Build 0.8.5602)
+*   `FVP_Base_Cortex-A57x2-A53x4` (Version 5.6, Build 0.8.5602)
+
+NOTE: The software will not work on Version 1.0 of the Foundation FVP.
+The commands below would report an `unhandled argument` error in this case.
+
+Please refer to the FVP documentation for a detailed description of the model
+parameter options. A brief description of the important ones that affect the
+ARM Trusted Firmware and normal world software behavior is provided below.
+
+The Foundation FVP is a cut down version of the AArch64 Base FVP. It can be
+downloaded for free from [ARM's website][ARM FVP website].
+
+
+### Running on the Foundation FVP with reset to BL1 entrypoint
+
+The following `Foundation_v8` parameters should be used to boot Linux with
+4 CPUs using the ARM Trusted Firmware.
+
+NOTE: Using the `--block-device` parameter is not necessary if a Linux RAM-disk
+file-system is used (see the "Obtaining a File-system" section above).
+
+NOTE: The `--data="<path to FIP binary>"@0x8000000` parameter is used to load a
+Firmware Image Package at the start of NOR FLASH0 (see the "Building the
+Trusted Firmware" section above).
+
+    <path-to>/Foundation_v8                   \
+    --cores=4                                 \
+    --no-secure-memory                        \
+    --visualization                           \
+    --gicv3                                   \
+    --data="<path-to>/<bl1-binary>"@0x0       \
+    --data="<path-to>/<FIP-binary>"@0x8000000 \
+    --block-device="<path-to>/<file-system-image>"
+
+The default use-case for the Foundation FVP is to enable the GICv3 device in
+the model but use the GICv2 FDT, in order for Linux to drive the GIC in GICv2
+emulation mode.
+
+The memory mapped addresses `0x0` and `0x8000000` correspond to the start of
+trusted ROM and NOR FLASH0 respectively.
+
+### Notes regarding Base FVP configuration options
+
+1. The `-C bp.flashloader0.fname` parameter is used to load a Firmware Image
+Package at the start of NOR FLASH0 (see the "Building the Trusted Firmware"
+section above).
+
+2. Using `cache_state_modelled=1` makes booting very slow. The software will
+still work (and run much faster) without this option but this will hide any
+cache maintenance defects in the software.
+
+3. Using the `-C bp.virtioblockdevice.image_path` parameter is not necessary
+if a Linux RAM-disk file-system is used (see the "Obtaining a root file-system"
+section above).
+
+4. Setting the `-C bp.secure_memory` parameter to `1` is only supported on
+Base FVP versions 5.4 and newer. Setting this parameter to `0` is also
+supported. The `-C bp.tzc_400.diagnostics=1` parameter is optional. It
+instructs the FVP to provide some helpful information if a secure memory
+violation occurs.
+
+5. The `--data="<path-to><bl31/bl32/bl33-binary>"@base address of binaries`
+parameter is used to load bootloader images in the Base FVP memory (see the
+"Building the Trusted Firmware" section above). The base address used to
+load the binaries with --data should match the image base addresses in
+platform_def.h used while linking the images.
+BL3-2 image is only needed if BL3-1 has been built to expect a secure-EL1
+payload.
+
+
+### Running on the AEMv8 Base FVP with reset to BL1 entrypoint
+
+Please read "Notes regarding Base FVP configuration options" section above for
+information about some of the options to run the software.
+
+The following `FVP_Base_AEMv8A-AEMv8A` parameters should be used to boot Linux
+with 8 CPUs using the ARM Trusted Firmware.
+
+    <path-to>/FVP_Base_AEMv8A-AEMv8A                       \
+    -C pctl.startup=0.0.0.0                                \
+    -C bp.secure_memory=1                                  \
+    -C bp.tzc_400.diagnostics=1                            \
+    -C cluster0.NUM_CORES=4                                \
+    -C cluster1.NUM_CORES=4                                \
+    -C cache_state_modelled=1                              \
+    -C bp.pl011_uart0.untimed_fifos=1                      \
+    -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \
+    -C bp.flashloader0.fname="<path-to>/<FIP-binary>"      \
+    -C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>"
+
+### Running on the Cortex-A57-A53 Base FVP with reset to BL1 entrypoint
+
+Please read "Notes regarding Base FVP configuration options" section above for
+information about some of the options to run the software.
+
+The following `FVP_Base_Cortex-A57x4-A53x4` model parameters should be used to
+boot Linux with 8 CPUs using the ARM Trusted Firmware.
+
+    <path-to>/FVP_Base_Cortex-A57x4-A53x4                  \
+    -C pctl.startup=0.0.0.0                                \
+    -C bp.secure_memory=1                                  \
+    -C bp.tzc_400.diagnostics=1                            \
+    -C cache_state_modelled=1                              \
+    -C bp.pl011_uart0.untimed_fifos=1                      \
+    -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \
+    -C bp.flashloader0.fname="<path-to>/<FIP-binary>"      \
+    -C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>"
+
+### Running on the AEMv8 Base FVP with reset to BL3-1 entrypoint
+
+Please read "Notes regarding Base FVP configuration options" section above for
+information about some of the options to run the software.
+
+The following `FVP_Base_AEMv8A-AEMv8A` parameters should be used to boot Linux
+with 8 CPUs using the ARM Trusted Firmware.
+
+NOTE: Uses the `-c clusterX.cpuX.RVBAR=@base address of BL3-1` where X is
+the cluster number in clusterX and cpu number in cpuX is used to set the reset
+vector for each core.
+
+    <path-to>/FVP_Base_AEMv8A-AEMv8A                             \
+    -C pctl.startup=0.0.0.0                                      \
+    -C bp.secure_memory=1                                        \
+    -C bp.tzc_400.diagnostics=1                                  \
+    -C cluster0.NUM_CORES=4                                      \
+    -C cluster1.NUM_CORES=4                                      \
+    -C cache_state_modelled=1                                    \
+    -C bp.pl011_uart0.untimed_fifos=1                            \
+    -C cluster0.cpu0.RVBAR=0x04006000                            \
+    -C cluster0.cpu1.RVBAR=0x04006000                            \
+    -C cluster0.cpu2.RVBAR=0x04006000                            \
+    -C cluster0.cpu3.RVBAR=0x04006000                            \
+    -C cluster1.cpu0.RVBAR=0x04006000                            \
+    -C cluster1.cpu1.RVBAR=0x04006000                            \
+    -C cluster1.cpu2.RVBAR=0x04006000                            \
+    -C cluster1.cpu3.RVBAR=0x04006000                            \
+    --data cluster0.cpu0="<path-to>/<bl31-binary>"@0x04006000    \
+    --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04024000    \
+    --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000    \
+    -C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>"
+
+### Running on the Cortex-A57-A53 Base FVP with reset to BL3-1 entrypoint
+
+Please read "Notes regarding Base FVP configuration options" section above for
+information about some of the options to run the software.
+
+The following `FVP_Base_Cortex-A57x4-A53x4` model parameters should be used to
+boot Linux with 8 CPUs using the ARM Trusted Firmware.
+
+NOTE: Uses the `-c clusterX.cpuX.RVBARADDR=@base address of BL3-1` where X is
+the cluster number in clusterX and cpu number in cpuX is used to set the reset
+vector for each core.
+
+    <path-to>/FVP_Base_Cortex-A57x4-A53x4                        \
+    -C pctl.startup=0.0.0.0                                      \
+    -C bp.secure_memory=1                                        \
+    -C bp.tzc_400.diagnostics=1                                  \
+    -C cache_state_modelled=1                                    \
+    -C bp.pl011_uart0.untimed_fifos=1                            \
+    -C cluster0.cpu0.RVBARADDR=0x04006000                        \
+    -C cluster0.cpu1.RVBARADDR=0x04006000                        \
+    -C cluster0.cpu2.RVBARADDR=0x04006000                        \
+    -C cluster0.cpu3.RVBARADDR=0x04006000                        \
+    -C cluster1.cpu0.RVBARADDR=0x04006000                        \
+    -C cluster1.cpu1.RVBARADDR=0x04006000                        \
+    -C cluster1.cpu2.RVBARADDR=0x04006000                        \
+    -C cluster1.cpu3.RVBARADDR=0x04006000                        \
+    --data cluster0.cpu0="<path-to>/<bl31-binary>"@0x04006000    \
+    --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04024000    \
+    --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000    \
+    -C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>"
+
+### Configuring the GICv2 memory map
+
+The Base FVP models support GICv2 with the default model parameters at the
+following addresses. The Foundation FVP also supports these addresses when
+configured for GICv3 in GICv2 emulation mode.
+
+    GICv2 Distributor Interface     0x2f000000
+    GICv2 CPU Interface             0x2c000000
+    GICv2 Virtual CPU Interface     0x2c010000
+    GICv2 Hypervisor Interface      0x2c02f000
+
+The AEMv8 Base FVP can be configured to support GICv2 at addresses
+corresponding to the legacy (Versatile Express) memory map as follows. These are
+the default addresses when using the Foundation FVP in GICv2 mode.
+
+    GICv2 Distributor Interface     0x2c001000
+    GICv2 CPU Interface             0x2c002000
+    GICv2 Virtual CPU Interface     0x2c004000
+    GICv2 Hypervisor Interface      0x2c006000
+
+The choice of memory map is reflected in the build variant field (bits[15:12])
+in the `SYS_ID` register (Offset `0x0`) in the Versatile Express System
+registers memory map (`0x1c010000`).
+
+*   `SYS_ID.Build[15:12]`
+
+    `0x1` corresponds to the presence of the Base GIC memory map. This is the
+    default value on the Base FVPs.
+
+*   `SYS_ID.Build[15:12]`
+
+    `0x0` corresponds to the presence of the Legacy VE GIC memory map. This is
+    the default value on the Foundation FVP.
+
+This register can be configured as described in the following sections.
+
+NOTE: If the legacy VE GIC memory map is used, then the corresponding FDT and
+BL3-3 images should be used.
+
+#### Configuring AEMv8 Foundation FVP GIC for legacy VE memory map
+
+The following parameters configure the Foundation FVP to use GICv2 with the
+legacy VE memory map:
+
+    <path-to>/Foundation_v8                   \
+    --cores=4                                 \
+    --no-secure-memory                        \
+    --visualization                           \
+    --no-gicv3                                \
+    --data="<path-to>/<bl1-binary>"@0x0       \
+    --data="<path-to>/<FIP-binary>"@0x8000000 \
+    --block-device="<path-to>/<file-system-image>"
+
+Explicit configuration of the `SYS_ID` register is not required.
+
+#### Configuring AEMv8 Base FVP GIC for legacy VE memory map
+
+The following parameters configure the AEMv8 Base FVP to use GICv2 with the
+legacy VE memory map. They must added to the parameters described in the
+"Running on the AEMv8 Base FVP" section above:
+
+    -C cluster0.gic.GICD-offset=0x1000                  \
+    -C cluster0.gic.GICC-offset=0x2000                  \
+    -C cluster0.gic.GICH-offset=0x4000                  \
+    -C cluster0.gic.GICH-other-CPU-offset=0x5000        \
+    -C cluster0.gic.GICV-offset=0x6000                  \
+    -C cluster0.gic.PERIPH-size=0x8000                  \
+    -C cluster1.gic.GICD-offset=0x1000                  \
+    -C cluster1.gic.GICC-offset=0x2000                  \
+    -C cluster1.gic.GICH-offset=0x4000                  \
+    -C cluster1.gic.GICH-other-CPU-offset=0x5000        \
+    -C cluster1.gic.GICV-offset=0x6000                  \
+    -C cluster1.gic.PERIPH-size=0x8000                  \
+    -C gic_distributor.GICD-alias=0x2c001000            \
+    -C bp.variant=0x0
+
+The `bp.variant` parameter corresponds to the build variant field of the
+`SYS_ID` register.  Setting this to `0x0` allows the ARM Trusted Firmware to
+detect the legacy VE memory map while configuring the GIC.
+
+
+- - - - - - - - - - - - - - - - - - - - - - - - - -
+
+_Copyright (c) 2013-2014, ARM Limited and Contributors. All rights reserved._
+
+
+[Firmware Design]:  ./firmware-design.md
+
+[ARM FVP website]:  http://www.arm.com/fvp
+[Linaro Toolchain]: http://releases.linaro.org/13.11/components/toolchain/binaries/
+[EDK2]:             http://github.com/tianocore/edk2
+[DS-5]:             http://www.arm.com/products/tools/software-tools/ds-5/index.php