andrius
/
arm-trusted-firmware
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Fix documentation issues in v0.2 release 

Change-Id: I4e2a9daa97e3be3d2f53894f2ec7947ba6bb3a16
This commit is contained in:
James Morrissey 2013-10-29 10:56:46 +00:00 committed by Dan Handley
parent cff4e296be
commit ba3155bb0e
4 changed files with 154 additions and 125 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
docs/change-log.md
View File

@ -1,13 +1,19 @@
ARM Trusted Firmware - version <next> ARM Trusted Firmware
===================================== ====================
Detailed changes since last release Detailed changes since last release
----------------------------------- -----------------------------------
* Support for Foundation FVP v5.2 added. * Support for Foundation FVP Version 2.0 added.
The documented UEFI configuration disables some devices that are unavailable The documented UEFI configuration disables some devices that are unavailable
in the Foundation FVP, including MMC and CLCD. The resultant UEFI binary can in the Foundation FVP, including MMC and CLCD. The resultant UEFI binary can
be used on the AEMv8 and Cortex-A57-A53 FVPs, as well as the Foundation FVP. be used on the AEMv8 and Cortex-A57-A53 FVPs, as well as the Foundation FVP.
NOTE: The software will not work on Version 1.0 of the Foundation FVP.
* Regression-checked against latest Base FVPs (Version 5.2).
* The supplied FDTs expose the Interrupt Translation Service (ITS) available
in GICv3.
ARM Trusted Firmware - version 0.2 ARM Trusted Firmware - version 0.2
@ -53,7 +59,7 @@ releases of the ARM Trusted Firmware.
* Although support for PSCI `CPU_SUSPEND` is present, it is not yet stable * Although support for PSCI `CPU_SUSPEND` is present, it is not yet stable
and ready for use. and ready for use.
* PSCI api calls `AFFINITY_INFO` & `PSCI_VERSION` are implemented but have not * PSCI API calls `AFFINITY_INFO` & `PSCI_VERSION` are implemented but have not
been tested. been tested.
* The ARM Trusted Firmware make files result in all build artifacts being * The ARM Trusted Firmware make files result in all build artifacts being

56
docs/porting-guide.md
View File

@ -81,68 +81,68 @@ Each platform must export a header file of this name with the following
constants defined. In the ARM FVP port, this file is found in constants defined. In the ARM FVP port, this file is found in
[../plat/fvp/platform.h]. [../plat/fvp/platform.h].
* ** #define : PLATFORM_LINKER_FORMAT ** * **#define : PLATFORM_LINKER_FORMAT**
Defines the linker format used by the platform, for example Defines the linker format used by the platform, for example
`elf64-littleaarch64` used by the FVP. `elf64-littleaarch64` used by the FVP.
* ** #define : PLATFORM_LINKER_ARCH ** * **#define : PLATFORM_LINKER_ARCH**
Defines the processor architecture for the linker by the platform, for Defines the processor architecture for the linker by the platform, for
example `aarch64` used by the FVP. example `aarch64` used by the FVP.
* ** #define : PLATFORM_STACK_SIZE ** * **#define : PLATFORM_STACK_SIZE**
Defines the normal stack memory available to each CPU. This constant is used Defines the normal stack memory available to each CPU. This constant is used
by `platform_set_stack()`. by `platform_set_stack()`.
* ** #define : FIRMWARE_WELCOME_STR ** * **#define : FIRMWARE_WELCOME_STR**
Defines the character string printed by BL1 upon entry into the `bl1_main()` Defines the character string printed by BL1 upon entry into the `bl1_main()`
function. function.
* ** #define : BL2_IMAGE_NAME ** * **#define : BL2_IMAGE_NAME**
Name of the BL2 binary image on the host file-system. This name is used by Name of the BL2 binary image on the host file-system. This name is used by
BL1 to load BL2 into secure memory using semi-hosting. BL1 to load BL2 into secure memory using semi-hosting.
* ** #define : PLATFORM_CACHE_LINE_SIZE ** * **#define : PLATFORM_CACHE_LINE_SIZE**
Defines the size (in bytes) of the largest cache line across all the cache Defines the size (in bytes) of the largest cache line across all the cache
levels in the platform. levels in the platform.
* ** #define : PLATFORM_CLUSTER_COUNT ** * **#define : PLATFORM_CLUSTER_COUNT**
Defines the total number of clusters implemented by the platform in the Defines the total number of clusters implemented by the platform in the
system. system.
* ** #define : PLATFORM_CORE_COUNT ** * **#define : PLATFORM_CORE_COUNT**
Defines the total number of CPUs implemented by the platform across all Defines the total number of CPUs implemented by the platform across all
clusters in the system. clusters in the system.
* ** #define : PLATFORM_MAX_CPUS_PER_CLUSTER ** * **#define : PLATFORM_MAX_CPUS_PER_CLUSTER**
Defines the maximum number of CPUs that can be implemented within a cluster Defines the maximum number of CPUs that can be implemented within a cluster
on the platform. on the platform.
* ** #define : PRIMARY_CPU ** * **#define : PRIMARY_CPU**
Defines the `MPIDR` of the primary CPU on the platform. This value is used Defines the `MPIDR` of the primary CPU on the platform. This value is used
after a cold boot to distinguish between primary and secondary CPUs. after a cold boot to distinguish between primary and secondary CPUs.
* ** #define : TZROM_BASE ** * **#define : TZROM_BASE**
Defines the base address of secure ROM on the platform, where the BL1 binary Defines the base address of secure ROM on the platform, where the BL1 binary
is loaded. This constant is used by the linker scripts to ensure that the is loaded. This constant is used by the linker scripts to ensure that the
BL1 image fits into the available memory. BL1 image fits into the available memory.
* ** #define : TZROM_SIZE ** * **#define : TZROM_SIZE**
Defines the size of secure ROM on the platform. This constant is used by the Defines the size of secure ROM on the platform. This constant is used by the
linker scripts to ensure that the BL1 image fits into the available memory. linker scripts to ensure that the BL1 image fits into the available memory.
* ** #define : TZRAM_BASE ** * **#define : TZRAM_BASE**
Defines the base address of the secure RAM on platform, where the data Defines the base address of the secure RAM on platform, where the data
section of the BL1 binary is loaded. The BL2 and BL3-1 images are also section of the BL1 binary is loaded. The BL2 and BL3-1 images are also
@ -150,22 +150,22 @@ constants defined. In the ARM FVP port, this file is found in
scripts to ensure that the BL1 data section and BL2/BL3-1 binary images fit scripts to ensure that the BL1 data section and BL2/BL3-1 binary images fit
into the available memory. into the available memory.
* ** #define : TZRAM_SIZE ** * **#define : TZRAM_SIZE**
Defines the size of the secure RAM on the platform. This constant is used by Defines the size of the secure RAM on the platform. This constant is used by
the linker scripts to ensure that the BL1 data section and BL2/BL3-1 binary the linker scripts to ensure that the BL1 data section and BL2/BL3-1 binary
images fit into the available memory. images fit into the available memory.
* ** #define : SYS_CNTCTL_BASE ** * **#define : SYS_CNTCTL_BASE**
Defines the base address of the `CNTCTLBase` frame of the memory mapped Defines the base address of the `CNTCTLBase` frame of the memory mapped
counter and timer in the system level implementation of the generic timer. counter and timer in the system level implementation of the generic timer.
* ** #define : BL2_BASE ** * **#define : BL2_BASE**
Defines the base address in secure RAM where BL1 loads the BL2 binary image. Defines the base address in secure RAM where BL1 loads the BL2 binary image.
* ** #define : BL31_BASE ** * **#define : BL31_BASE**
Defines the base address in secure RAM where BL2 loads the BL3-1 binary Defines the base address in secure RAM where BL2 loads the BL3-1 binary
image. image.
@ -173,11 +173,11 @@ constants defined. In the ARM FVP port, this file is found in
### Other mandatory modifications ### Other mandatory modifications
The following following mandatory modifications may be implemented in any file The following mandatory modifications may be implemented in any file
the implementer chooses. In the ARM FVP port, they are implemented in the implementer chooses. In the ARM FVP port, they are implemented in
[../plat/fvp/aarch64/fvp_common.c]. [../plat/fvp/aarch64/fvp_common.c].
* ** Variable : unsigned char platform_normal_stacks[X][Y] ** * **Variable : unsigned char platform_normal_stacks[X][Y]**
where X = PLATFORM_STACK_SIZE where X = PLATFORM_STACK_SIZE
and Y = PLATFORM_CORE_COUNT and Y = PLATFORM_CORE_COUNT
@ -795,7 +795,7 @@ called by the primary CPU.
This function is called by the PSCI implementation both during cold and warm This function is called by the PSCI implementation both during cold and warm
boot, to determine the maximum affinity level that the power management boot, to determine the maximum affinity level that the power management
operations should apply to. ARMv8 has support for 4 affinity levels. It is operations should apply to. ARMv8-A has support for 4 affinity levels. It is
likely that hardware will implement fewer affinity levels. This function allows likely that hardware will implement fewer affinity levels. This function allows
the PSCI implementation to consider only those affinity levels in the system the PSCI implementation to consider only those affinity levels in the system
that the platform implements. For example, the Base AEM FVP implements two that the platform implements. For example, the Base AEM FVP implements two
@ -855,8 +855,8 @@ affinity level 0 (CPU), the platform port should power down affinity level 1
This function is called with coherent stacks. This allows the PSCI This function is called with coherent stacks. This allows the PSCI
implementation to flush caches at a given affinity level without running into implementation to flush caches at a given affinity level without running into
stale stack state after turning off the caches. On ARMv8 cache hits do not occur stale stack state after turning off the caches. On ARMv8-A cache hits do not
after the cache has been turned off. occur after the cache has been turned off.
#### plat_pm_ops.affinst_suspend() #### plat_pm_ops.affinst_suspend()
@ -882,8 +882,8 @@ resume execution by restoring this state when its powered on (see
This function is called with coherent stacks. This allows the PSCI This function is called with coherent stacks. This allows the PSCI
implementation to flush caches at a given affinity level without running into implementation to flush caches at a given affinity level without running into
stale stack state after turning off the caches. On ARMv8 cache hits do not occur stale stack state after turning off the caches. On ARMv8-A cache hits do not
after the cache has been turned off. occur after the cache has been turned off.
#### plat_pm_ops.affinst_on_finish() #### plat_pm_ops.affinst_on_finish()
@ -898,8 +898,8 @@ The `MPIDR` (first argument), `affinity level` (second argument) and `state`
This function is called with coherent stacks. This allows the PSCI This function is called with coherent stacks. This allows the PSCI
implementation to flush caches at a given affinity level without running into implementation to flush caches at a given affinity level without running into
stale stack state after turning off the caches. On ARMv8 cache hits do not occur stale stack state after turning off the caches. On ARMv8-A cache hits do not
after the cache has been turned off. occur after the cache has been turned off.
#### plat_pm_ops.affinst_on_suspend() #### plat_pm_ops.affinst_on_suspend()
@ -915,8 +915,8 @@ The `MPIDR` (first argument), `affinity level` (second argument) and `state`
This function is called with coherent stacks. This allows the PSCI This function is called with coherent stacks. This allows the PSCI
implementation to flush caches at a given affinity level without running into implementation to flush caches at a given affinity level without running into
stale stack state after turning off the caches. On ARMv8 cache hits do not occur stale stack state after turning off the caches. On ARMv8-A cache hits do not
after the cache has been turned off. occur after the cache has been turned off.
BL3-1 platform initialization code must also detect the system topology and BL3-1 platform initialization code must also detect the system topology and
the state of each affinity instance in the topology. This information is the state of each affinity instance in the topology. This information is

189
docs/user-guide.md
View File

@ -32,23 +32,27 @@ Convention PDD][SMCCC] [3].
### Host machine requirements ### Host machine requirements
The minimum recommended machine specification is an Intel Core2Duo clocking at The minimum recommended machine specification for building the software and
2.6GHz or above, and 12GB RAM. For best performance, use a machine with Intel running the FVP (Fixed Virtual Platform) model is a dual-core processor running
Core i7 (SandyBridge) and 16GB of RAM. 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.02 (64-bit). Packages used
for building the software were installed from that distribution unless
otherwise specified.
### Tools ### Tools
The following tools are required to use the ARM Trusted Firmware: The following tools are required to use the ARM Trusted Firmware:
* Ubuntu desktop OS. The software has been tested on Ubuntu 12.04.02 (64-bit). * `git` package to obtain source code
The following packages are also needed:
* `ia32-libs` package. * `ia32-libs` package
* `make` and `uuid-dev` packages for building UEFI. * `build-essential` and `uuid-dev` packages for building UEFI
* `bc` and `ncurses-dev` packages for building Linux. * `bc` and `ncurses-dev` packages for building Linux
* Baremetal GNU GCC tools. Verified packages can be downloaded from [Linaro] * Baremetal GNU GCC tools. Verified packages can be downloaded from [Linaro]
[Linaro Toolchain]. The rest of this document assumes that the [Linaro Toolchain]. The rest of this document assumes that the
@ -59,7 +63,7 @@ The following tools are required to use the ARM Trusted Firmware:
* The Device Tree Compiler (DTC) included with Linux kernel 3.12-rc4 is used * The Device Tree Compiler (DTC) included with Linux kernel 3.12-rc4 is used
to build the Flattened Device Tree (FDT) source files (`.dts` files) to build the Flattened Device Tree (FDT) source files (`.dts` files)
provided with this release. provided with this software.
* (Optional) For debugging, ARM [Development Studio 5 (DS-5)][DS-5] v5.16. * (Optional) For debugging, ARM [Development Studio 5 (DS-5)][DS-5] v5.16.
@ -78,7 +82,7 @@ To build the software for the FVPs, follow these steps:
3. Set the compiler path and build: 3. Set the compiler path and build:
CROSS_COMPILE=<path/to/>aarch64-none-elf- make CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- make
By default this produces a release version of the build. To produce a debug By default this produces a release version of the build. To produce a debug
version instead, refer to the "Debugging options" section below. version instead, refer to the "Debugging options" section below.
@ -102,7 +106,7 @@ To build the software for the FVPs, follow these steps:
To compile a debug version and make the build more verbose use To compile a debug version and make the build more verbose use
CROSS_COMPILE=<path/to/>aarch64-none-elf- make DEBUG=1 V=1 CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- make DEBUG=1 V=1
AArch64 GCC uses DWARF version 4 debugging symbols by default. Some tools (for 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 example DS-5) might not support this and may need an older version of DWARF
@ -118,7 +122,9 @@ might need to be recalculated (see the later memory layout section).
Extra debug options can be passed to the build system by setting `CFLAGS`: Extra debug options can be passed to the build system by setting `CFLAGS`:
CFLAGS='-O0 -gdwarf-2' CROSS_COMPILE=<path/to/>aarch64-none-elf- make DEBUG=1 V=1 CFLAGS='-O0 -gdwarf-2' \
CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- \
make DEBUG=1 V=1
NOTE: The Foundation FVP does not provide a debugger interface. NOTE: The Foundation FVP does not provide a debugger interface.
@ -156,9 +162,9 @@ these steps:
4. Build the software 4. Build the software
CROSS_COMPILE=<path/to/>bin/aarch64-none-elf- \ CROSS_COMPILE=<absolute-path-to-aarch64-gcc>/bin/aarch64-none-elf- \
build -v -d3 -a AARCH64 -t ARMGCC \ build -v -d3 -a AARCH64 -t ARMGCC \
-p ArmPlatformPkg/ArmVExpressPkg/ArmVExpress-FVP-AArch64.dsc \ -p ArmPlatformPkg/ArmVExpressPkg/ArmVExpress-FVP-AArch64.dsc \
-D ARM_FOUNDATION_FVP=1 -D ARM_FOUNDATION_FVP=1
The EDK2 binary for use with the ARM Trusted Firmware can then be found The EDK2 binary for use with the ARM Trusted Firmware can then be found
@ -168,17 +174,19 @@ these steps:
This will build EDK2 for the default settings as used by the FVPs. This will build EDK2 for the default settings as used by the FVPs.
To boot Linux using a VirtioBlock file-system, the command line passed from EDK2 To boot Linux using a VirtioBlock file-system, the command line passed from
to the Linux kernel must be modified as described in the "Obtaining a EDK2 to the Linux kernel must be modified as described in the "Obtaining a
File-system" section below. root file-system" section below.
If legacy GICv2 locations are used, the EDK2 platform description must be 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. updated. This is required as EDK2 does not support probing for the GIC
To do this, build the software as described above with the location. To do this, build the software as described above with the
`ARM_FVP_LEGACY_GICV2_LOCATION` flag. `ARM_FVP_LEGACY_GICV2_LOCATION` flag:
-D ARM_FVP_LEGACY_GICV2_LOCATION=1 -D ARM_FVP_LEGACY_GICV2_LOCATION=1
Then `make clean` before rebuilding EDK2.
The EDK2 binary `FVP_AARCH64_EFI.fd` should be loaded into FVP FLASH0 via model The EDK2 binary `FVP_AARCH64_EFI.fd` should be loaded into FVP FLASH0 via model
parameters as described in the "Running the Software" section below. parameters as described in the "Running the Software" section below.
@ -194,8 +202,9 @@ be done as follows (GICv2 support only):
git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
The CPU hotplug features are not yet included in the mainline kernel. To use The CPU hotplug features are not yet included in the mainline kernel. To
these, add the patches from Mark Rutland's kernel, based on Linux 3.12-rc4: use these, add the patches from Mark Rutland's kernel, based on
Linux 3.12-rc4:
cd linux cd linux
git remote add -f --tags markr git://linux-arm.org/linux-mr.git git remote add -f --tags markr git://linux-arm.org/linux-mr.git
@ -211,18 +220,19 @@ be done as follows (GICv2 support only):
make ARCH=arm64 menuconfig make ARCH=arm64 menuconfig
# Kernel Features ---> [*] Support for hot-pluggable CPUs # Kernel Features ---> [*] Support for hot-pluggable CPUs
CROSS_COMPILE=</path/to/>aarch64-none-elf- make -j6 ARCH=arm64 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 3. Copy the Linux image `arch/arm64/boot/Image` to the working directory from
where the FVP is launched. A symbolic link may also be created instead. where the FVP is launched. Alternatively a symbolic link may be used.
#### Obtaining the Flattened Device Trees #### Obtaining the Flattened Device Trees
Depending on the FVP configuration and Linux configuration used, different 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 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 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 subset of the Base FVP components. For example, the Foundation FVP lacks CLCD
and MMC support, and has only one CPU cluster). and MMC support, and has only one CPU cluster.
* `fvp-base-gicv2-psci.dtb` * `fvp-base-gicv2-psci.dtb`
@ -254,9 +264,9 @@ and MMC support, and has only one CPU cluster).
Copy the chosen FDT blob as `fdt.dtb` to the directory from which the FVP Copy the chosen FDT blob as `fdt.dtb` to the directory from which the FVP
is launched. A symbolic link may also be created instead. is launched. Alternatively a symbolic link may be used.
#### Obtaining a File-system #### Obtaining a root file-system
To prepare a Linaro LAMP based Open Embedded file-system, the following 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 instructions can be used as a guide. The file-system can be provided to Linux
@ -281,8 +291,8 @@ To prepare a VirtioBlock file-system, do the following:
File systems ---> <*> The Extended 4 (ext4) filesystem File systems ---> <*> The Extended 4 (ext4) filesystem
If some of these configurations are missing, enable them, save the kernel If some of these configurations are missing, enable them, save the kernel
configuration, then rebuild the kernel image using the instructions provided configuration, then rebuild the kernel image using the instructions
in the section "Obtaining a Linux kernel". provided in the section "Obtaining a Linux kernel".
3. Change the Kernel command line to include `root=/dev/vda2`. This can either 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 be done in the EDK2 boot menu or in the platform file. Editing the platform
@ -311,10 +321,10 @@ To prepare a VirtioBlock file-system, do the following:
to the real file must be provided. to the real file must be provided.
On the Base FVPs: On the Base FVPs:
-C bp.virtioblockdevice.image_path="<path/to/>vexpress64-openembedded_lamp-armv8_20130927-7.img" -C bp.virtioblockdevice.image_path="<path-to>/vexpress64-openembedded_lamp-armv8_20130927-7.img"
On the Foundation FVP: On the Foundation FVP:
--block-device="<path/to/>vexpress64-openembedded_lamp-armv8_20130927-7.img" --block-device="<path-to>/vexpress64-openembedded_lamp-armv8_20130927-7.img"
5. Ensure that the FVP doesn't output any error messages. If the following 5. Ensure that the FVP doesn't output any error messages. If the following
@ -332,7 +342,7 @@ NOTE: The RAM-disk option does not currently work with the Linux kernel version
described above; use the VirtioBlock method instead. For further information described above; use the VirtioBlock method instead. For further information
please see the "Known issues" section in the [Change Log]. please see the "Known issues" section in the [Change Log].
To Prepare a RAM-disk file-system, do the following: To prepare a RAM-disk root file-system, do the following:
1. Download the file-system image: 1. Download the file-system image:
@ -351,17 +361,20 @@ To Prepare a RAM-disk file-system, do the following:
cd .. cd ..
3. Copy the resultant `filesystem.cpio.gz` to the directory where the FVP is 3. Copy the resultant `filesystem.cpio.gz` to the directory where the FVP is
launched from. A symbolic link may also be created instead. launched from. Alternatively a symbolic link may be used.
### Running the software ### Running the software
This release of the ARM Trusted Firmware has been tested on the following ARM This version of the ARM Trusted Firmware has been tested on the following ARM
FVPs (64-bit versions only). FVPs (64-bit versions only).
* `Foundation_v8` (Version 0.8.5206) * `Foundation_v8` (Version 2.0, Build 0.8.5206)
* `FVP_Base_AEMv8A-AEMv8A` (Version 0.8.5202) * `FVP_Base_AEMv8A-AEMv8A` (Version 5.2, Build 0.8.5202)
* `FVP_Base_Cortex-A57x4-A53x4` (Version 0.8.5202) * `FVP_Base_Cortex-A57x4-A53x4` (Version 5.2, Build 0.8.5202)
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 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 parameter options. A brief description of the important ones that affect the
@ -378,17 +391,17 @@ The following `Foundation_v8` parameters should be used to boot Linux with
NOTE: Using the `--block-device` parameter is not necessary if a Linux RAM-disk 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). file-system is used (see the "Obtaining a File-system" section above).
Foundation_v8 \ <path-to>/Foundation_v8 \
--cores=4 \ --cores=4 \
--no-secure-memory \ --no-secure-memory \
--visualization \ --visualization \
--gicv3 \ --gicv3 \
--data="<path to bl1.bin>"@0x0 \ --data="<path to bl1.bin>"@0x0 \
--data="<path to UEFI binary>"@0x8000000 \ --data="<path to UEFI binary>"@0x8000000 \
--block-device="<path/to/>vexpress64-openembedded_lamp-armv8_20130927-7.img" --block-device="<path-to>/vexpress64-openembedded_lamp-armv8_20130927-7.img"
The default use-case for the Foundation FVP is to enable the GICv3 device in the The default use-case for the Foundation FVP is to enable the GICv3 device in
model but use the GICv2 FDT, in order for Linux to drive the GIC in GICv2 the model but use the GICv2 FDT, in order for Linux to drive the GIC in GICv2
emulation mode. emulation mode.
The memory mapped addresses `0x0` and `0x8000000` correspond to the start of The memory mapped addresses `0x0` and `0x8000000` correspond to the start of
@ -404,10 +417,10 @@ still work (and run much faster) without this option but this will hide any
cache maintenance defects in the software. cache maintenance defects in the software.
NOTE: Using the `-C bp.virtioblockdevice.image_path` parameter is not necessary NOTE: Using the `-C bp.virtioblockdevice.image_path` parameter is not necessary
if a Linux RAM-disk file-system is used (see the "Obtaining a File-system" if a Linux RAM-disk file-system is used (see the "Obtaining a root file-system"
section above). section above).
FVP_Base_AEMv8A-AEMv8A \ <path-to>/FVP_Base_AEMv8A-AEMv8A \
-C pctl.startup=0.0.0.0 \ -C pctl.startup=0.0.0.0 \
-C bp.secure_memory=0 \ -C bp.secure_memory=0 \
-C cluster0.NUM_CORES=4 \ -C cluster0.NUM_CORES=4 \
@ -416,7 +429,7 @@ section above).
-C bp.pl011_uart0.untimed_fifos=1 \ -C bp.pl011_uart0.untimed_fifos=1 \
-C bp.secureflashloader.fname=<path to bl1.bin> \ -C bp.secureflashloader.fname=<path to bl1.bin> \
-C bp.flashloader0.fname=<path to UEFI binary> \ -C bp.flashloader0.fname=<path to UEFI binary> \
-C bp.virtioblockdevice.image_path="<path/to/>vexpress64-openembedded_lamp-armv8_20130927-7.img" -C bp.virtioblockdevice.image_path="<path-to>/vexpress64-openembedded_lamp-armv8_20130927-7.img"
#### Running on the Cortex-A57-A53 Base FVP #### Running on the Cortex-A57-A53 Base FVP
@ -428,17 +441,17 @@ still work (and run much faster) without this option but this will hide any
cache maintenance defects in the software. cache maintenance defects in the software.
NOTE: Using the `-C bp.virtioblockdevice.image_path` parameter is not necessary NOTE: Using the `-C bp.virtioblockdevice.image_path` parameter is not necessary
if a Linux RAM-disk file-system is used (see the "Obtaining a File-system" if a Linux RAM-disk file-system is used (see the "Obtaining a root file-system"
section above). section above).
FVP_Base_Cortex-A57x4-A53x4 \ <path-to>/FVP_Base_Cortex-A57x4-A53x4 \
-C pctl.startup=0.0.0.0 \ -C pctl.startup=0.0.0.0 \
-C bp.secure_memory=0 \ -C bp.secure_memory=0 \
-C cache_state_modelled=1 \ -C cache_state_modelled=1 \
-C bp.pl011_uart0.untimed_fifos=1 \ -C bp.pl011_uart0.untimed_fifos=1 \
-C bp.secureflashloader.fname=<path to bl1.bin> \ -C bp.secureflashloader.fname=<path to bl1.bin> \
-C bp.flashloader0.fname=<path to UEFI binary> \ -C bp.flashloader0.fname=<path to UEFI binary> \
-C bp.virtioblockdevice.image_path="<path/to/>vexpress64-openembedded_lamp-armv8_20130927-7.img" -C bp.virtioblockdevice.image_path="<path-to>/vexpress64-openembedded_lamp-armv8_20130927-7.img"
### Configuring the GICv2 memory map ### Configuring the GICv2 memory map
@ -451,55 +464,61 @@ configured for GICv3 in GICv2 emulation mode.
GICv2 Virtual CPU Interface 0x2c010000 GICv2 Virtual CPU Interface 0x2c010000
GICv2 Hypervisor Interface 0x2c02f000 GICv2 Hypervisor Interface 0x2c02f000
The Base FVP models can be configured to support GICv2 at addresses corresponding The Base FVP models can be configured to support GICv2 at addresses
to the legacy (Versatile Express) memory map as follows. These are the default corresponding to the legacy (Versatile Express) memory map as follows. These are
addresses when using the Foundation FVP in GICv2 mode. the default addresses when using the Foundation FVP in GICv2 mode.
GICv2 Distributor Interface 0x2c001000 GICv2 Distributor Interface 0x2c001000
GICv2 CPU Interface 0x2c002000 GICv2 CPU Interface 0x2c002000
GICv2 Virtual CPU Interface 0x2c004000 GICv2 Virtual CPU Interface 0x2c004000
GICv2 Hypervisor Interface 0x2c006000 GICv2 Hypervisor Interface 0x2c006000
The choice of memory map is reflected in the build field (bits[15:12]) in the The choice of memory map is reflected in the build variant field (bits[15:12])
`SYS_ID` register (Offset `0x0`) in the Versatile Express System registers in the `SYS_ID` register (Offset `0x0`) in the Versatile Express System
memory map (`0x1c010000`). registers memory map (`0x1c010000`).
* `SYS_ID.Build[15:12]` * `SYS_ID.Build[15:12]`
`0x1` corresponds to the presence of the Base GIC memory map. This is the `0x1` corresponds to the presence of the Base GIC memory map. This is the
default value. default value on the Base FVPs.
* `SYS_ID.Build[15:12]` * `SYS_ID.Build[15:12]`
`0x0` corresponds to the presence of the Legacy VE GIC memory map. This `0x0` corresponds to the presence of the Legacy VE GIC memory map. This is
value can be configured as described in the next section. 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 NOTE: If the legacy VE GIC memory map is used, then the corresponding FDT and
UEFI images should be used. UEFI images should be used.
#### Configuring AEMv8 Foundation FVP GIC for legacy VE memory map #### Configuring AEMv8 Foundation FVP GIC for legacy VE memory map
The following parameters configure the Foundation FVP to use GICv2. On the The following parameters configure the Foundation FVP to use GICv2 with the
Foundation FVP only the legacy VE layout is supported in this mode: legacy VE memory map:
Foundation_v8 \ <path-to>/Foundation_v8 \
--cores=4 \ --cores=4 \
--no-secure-memory \ --no-secure-memory \
--visualization \ --visualization \
--no-gicv3 \ --no-gicv3 \
--data="<path to bl1.bin>"@0x0 \ --data="<path to bl1.bin>"@0x0 \
--data="<path to UEFI binary>"@0x8000000 \ --data="<path to UEFI binary>"@0x8000000 \
--block-device="<path/to/>vexpress64-openembedded_lamp-armv8_20130927-7.img" --block-device="<path-to>/vexpress64-openembedded_lamp-armv8_20130927-7.img"
Explicit configuration of the `SYS_ID` register is not required.
#### Configuring AEMv8 Base FVP GIC for legacy VE memory map #### Configuring AEMv8 Base FVP GIC for legacy VE memory map
The following parameters configure the GICv2 memory map in legacy VE mode: The following parameters configure the AEMv8 Base FVP to use GICv2 with the
legacy VE memory map:
NOTE: Using the `-C bp.virtioblockdevice.image_path` parameter is not necessary NOTE: Using the `-C bp.virtioblockdevice.image_path` parameter is not necessary
if a Linux RAM-disk file-system is used (see the "Obtaining a File-system" if a Linux RAM-disk file-system is used (see the "Obtaining a root file-system"
section above). section above).
FVP_Base_AEMv8A-AEMv8A \ <path-to>/FVP_Base_AEMv8A-AEMv8A \
-C cluster0.gic.GICD-offset=0x1000 \ -C cluster0.gic.GICD-offset=0x1000 \
-C cluster0.gic.GICC-offset=0x2000 \ -C cluster0.gic.GICC-offset=0x2000 \
-C cluster0.gic.GICH-offset=0x4000 \ -C cluster0.gic.GICH-offset=0x4000 \
@ -514,25 +533,27 @@ section above).
-C cluster1.gic.PERIPH-size=0x8000 \ -C cluster1.gic.PERIPH-size=0x8000 \
-C gic_distributor.GICD-alias=0x2c001000 \ -C gic_distributor.GICD-alias=0x2c001000 \
-C bp.variant=0x0 \ -C bp.variant=0x0 \
-C bp.virtioblockdevice.image_path="<path/to/>vexpress64-openembedded_lamp-armv8_20130927-7.img" -C bp.virtioblockdevice.image_path="<path-to>/vexpress64-openembedded_lamp-armv8_20130927-7.img"
The last parameter sets the build variant field of the `SYS_ID` register to The `bp.variant` parameter corresponds to the build variant field of the
`0x0`. This allows the ARM Trusted Firmware to detect the legacy VE memory map `SYS_ID` register. Setting this to `0x0` allows the ARM Trusted Firmware to
while configuring the GIC. detect the legacy VE memory map while configuring the GIC.
#### Configuring Cortex-A57-A53 Base FVP GIC for legacy VE memory map #### Configuring Cortex-A57-A53 Base FVP GIC for legacy VE memory map
Configuration of the GICv2 as per the legacy VE memory map is controlled by The following parameters configure the Cortex-A57-A53 Base FVP to use GICv2 with
the following parameter. In this case, separate configuration of the `SYS_ID` the legacy VE memory map:
register is not required.
NOTE: Using the `-C bp.virtioblockdevice.image_path` parameter is not necessary NOTE: Using the `-C bp.virtioblockdevice.image_path` parameter is not necessary
if a Linux RAM-disk file-system is used (see the "Obtaining a File-system" if a Linux RAM-disk file-system is used (see the "Obtaining a root file-system"
section above). section above).
FVP_Base_Cortex-A57x4-A53x4 \ <path-to>/FVP_Base_Cortex-A57x4-A53x4 \
-C legacy_gicv2_map=1 \ -C legacy_gicv2_map=1 \
-C bp.virtioblockdevice.image_path="<path/to/>vexpress64-openembedded_lamp-armv8_20130927-7.img" -C bp.virtioblockdevice.image_path="<path-to>/vexpress64-openembedded_lamp-armv8_20130927-7.img"
Explicit configuration of the `SYS_ID` register is not required.
3. Firmware Design 3. Firmware Design
------------------- -------------------
@ -698,7 +719,7 @@ BL1 execution continues as follows:
### BL2 ### BL2
BL1 loads and passes control to BL2 at Secure EL1. BL2 is linked against and BL1 loads and passes control to BL2 at Secure EL1. BL2 is linked against and
loaded at a platform-specific base address (more information can found later loaded at a platform-specific base address (more information can be found later
in this document). The functionality implemented by BL2 is as follows. in this document). The functionality implemented by BL2 is as follows.
#### Architectural initialization #### Architectural initialization
@ -764,7 +785,7 @@ BL2 execution continues as follows:
The image for this stage is loaded by BL2 and BL1 passes control to BL3-1 at The image for this stage is loaded by BL2 and BL1 passes control to BL3-1 at
EL3. BL3-1 executes solely in trusted SRAM. BL3-1 is linked against and EL3. BL3-1 executes solely in trusted SRAM. BL3-1 is linked against and
loaded at a platform-specific base address (more information can found later loaded at a platform-specific base address (more information can be found later
in this document). The functionality implemented by BL3-1 is as follows. in this document). The functionality implemented by BL3-1 is as follows.
#### Architectural initialization #### Architectural initialization
@ -835,7 +856,7 @@ memory address populated by BL2.
The `CPU_ON` and `CPU_OFF` functions implement the warm boot path in ARM The `CPU_ON` and `CPU_OFF` functions implement the warm boot path in ARM
Trusted Firmware. These are the only functions which have been tested. Trusted Firmware. These are the only functions which have been tested.
`AFFINITY_INFO` & `PSCI_VERSION` are present but completely untested in `AFFINITY_INFO` & `PSCI_VERSION` are present but completely untested in
this release. this version of the software.
Unsupported PSCI functions that can return, return the `NOT_SUPPORTED` Unsupported PSCI functions that can return, return the `NOT_SUPPORTED`
(`-1`) error code. Other unsupported PSCI functions that don't return, (`-1`) error code. Other unsupported PSCI functions that don't return,
@ -853,7 +874,7 @@ world software image at the highest available Exception Level (EL2 if
available, otherwise EL1). available, otherwise EL1).
### Memory layout on Base FVP ### ### Memory layout on Base FVP
The current implementation of the image loader has some limitations. It is The current implementation of the image loader has some limitations. It is
designed to load images dynamically, at a load address chosen to minimize memory designed to load images dynamically, at a load address chosen to minimize memory
@ -970,7 +991,7 @@ following view:
------------ 0x04000000 ------------ 0x04000000
### Code Structure ### ### Code Structure
Trusted Firmware code is logically divided between the three boot loader Trusted Firmware code is logically divided between the three boot loader
stages mentioned in the previous sections. The code is also divided into the stages mentioned in the previous sections. The code is also divided into the
@ -998,11 +1019,11 @@ categories. Based upon the above, the code layout looks like this:
common Yes Yes Yes common Yes Yes Yes
lib Yes Yes Yes lib Yes Yes Yes
All assembler files have the `.S` extension. The linker files for each boot All assembler files have the `.S` extension. The linker source files for each
stage has the `.ld.S` extension. These are processed by GCC to create the boot stage have the extension `.ld.S`. These are processed by GCC to create the
resultant `.ld` files used for linking. linker scripts which have the extension `.ld`.
FDTs provide a description of the hardware platform and is used by the Linux FDTs provide a description of the hardware platform and are used by the Linux
kernel at boot time. These can be found in the `fdts` directory. kernel at boot time. These can be found in the `fdts` directory.

20
readme.md
View File

@ -2,13 +2,13 @@ ARM Trusted Firmware - version 0.2
================================== ==================================
ARM Trusted Firmware provides a reference implementation of secure world ARM Trusted Firmware provides a reference implementation of secure world
software for [ARMv8], including Exception Level 3 (EL3) software. This first software for [ARMv8-A], including Exception Level 3 (EL3) software. This first
release focuses on support for ARM's [Fixed Virtual Platforms (FVPs)] [FVP]. release focuses on support for ARM's [Fixed Virtual Platforms (FVPs)] [FVP].
The intent is to provide a reference implementation of various ARM interface The intent is to provide a reference implementation of various ARM interface
standards, such as the Power State Coordination Interface ([PSCI]), Trusted standards, such as the Power State Coordination Interface ([PSCI]), Trusted
Board Boot Requirements (TBBR) and [Secure Monitor] [TEE-SMC] code. As far as Board Boot Requirements (TBBR) and [Secure Monitor] [TEE-SMC] code. As far as
possible the code is designed for reuse or porting to other ARMv8 model and possible the code is designed for reuse or porting to other ARMv8-A model and
hardware platforms. hardware platforms.
This release is the first one as source code: an initial prototype This release is the first one as source code: an initial prototype
@ -18,7 +18,7 @@ models from ARM.
ARM will continue development in collaboration with interested parties to ARM will continue development in collaboration with interested parties to
provide a full reference implementation of PSCI, TBBR and Secure Monitor code provide a full reference implementation of PSCI, TBBR and Secure Monitor code
to the benefit of all developers working with ARMv8 TrustZone software. to the benefit of all developers working with ARMv8-A TrustZone software.
License License
@ -66,11 +66,13 @@ since the last release.
This release of the Trusted Firmware has been tested on the following ARM This release of the Trusted Firmware has been tested on the following ARM
[FVP]s (64-bit versions only): [FVP]s (64-bit versions only):
* `FVP_Base_AEMv8A-AEMv8A` (Version 5.1 build 8). * `FVP_Base_AEMv8A-AEMv8A` (Version 5.1, Build 0.8.5108).
* `FVP_Base_Cortex-A57x4-A53x4` (Version 5.1 build 8). * `FVP_Base_Cortex-A57x4-A53x4` (Version 5.1, Build 0.8.5108).
* `FVP_Base_Cortex-A57x1-A53x1` (Version 5.1 build 8). * `FVP_Base_Cortex-A57x1-A53x1` (Version 5.1, Build 0.8.5108).
These models can be licensed from ARM: see [www.arm.com/fvp] [FVP] These models can be licensed from ARM: see [www.arm.com/fvp] [FVP].
For an updated list of supported platforms, please see the [Change Log].
### Still to Come ### Still to Come
@ -96,7 +98,7 @@ See the [User Guide] for instructions on how to install, build and use
the Trusted Firmware with the ARM [FVP]s. the Trusted Firmware with the ARM [FVP]s.
See the [Porting Guide] as well for information about how to use this See the [Porting Guide] as well for information about how to use this
software on another ARMv8 platform. software on another ARMv8-A platform.
### Feedback and support ### Feedback and support
@ -117,7 +119,7 @@ _Copyright (c) 2013 ARM Ltd. All rights reserved._
[User Guide]: ./docs/user-guide.md [User Guide]: ./docs/user-guide.md
[Porting Guide]: ./docs/porting-guide.md [Porting Guide]: ./docs/porting-guide.md
[ARMv8]: http://www.arm.com/products/processors/armv8-architecture.php "ARMv8 Architecture" [ARMv8-A]: http://www.arm.com/products/processors/armv8-architecture.php "ARMv8-A Architecture"
[FVP]: http://www.arm.com/fvp "ARM's Fixed Virtual Platforms" [FVP]: http://www.arm.com/fvp "ARM's Fixed Virtual Platforms"
[PSCI]: http://infocenter.arm.com/help/topic/com.arm.doc.den0022b/index.html "Power State Coordination Interface PDD (ARM DEN 0022B.b)" [PSCI]: http://infocenter.arm.com/help/topic/com.arm.doc.den0022b/index.html "Power State Coordination Interface PDD (ARM DEN 0022B.b)"
[SMCCC]: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html "SMC Calling Convention PDD (ARM DEN 0028A)" [SMCCC]: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html "SMC Calling Convention PDD (ARM DEN 0028A)"