This document assumes that the reader has previous experience running a fully
bootable Linux software stack on Juno or FVP using the prebuilt binaries and
-filesystems provided by `Linaro`_. Further information may be found in the
+filesystems provided by Linaro. Further information may be found in the
`Linaro instructions`_. It also assumes that the user understands the role of
the different software components required to boot a Linux system:
This document also assumes that the user is familiar with the `FVP models`_ and
the different command line options available to launch the model.
-This document should be used in conjunction with the `Firmware Design`_.
+This document should be used in conjunction with the :ref:`Firmware Design`.
Host machine requirements
-------------------------
sudo apt-get install device-tree-compiler build-essential gcc make git libssl-dev
-TF-A has been tested with Linaro Release 18.04.
-
-Download and install the AArch32 or AArch64 little-endian GCC cross compiler. If
-you would like to use the latest features available, download GCC 8.2-2019.01
-compiler from `arm Developer page`_. Otherwise, the `Linaro Release Notes`_
-documents which version of the compiler to use for a given Linaro Release. Also,
-these `Linaro instructions`_ provide further guidance and a script, which can be
-used to download Linaro deliverables automatically.
+Download and install the AArch32 (arm-eabi) or AArch64 little-endian
+(aarch64-linux-gnu) GCC 8.3-2019.03 cross compiler from `Arm Developer page`_.
Optionally, TF-A can be built using clang version 4.0 or newer or Arm
Compiler 6. See instructions below on how to switch the default compiler.
This tool can be found in most Linux distributions. Inkscape is needed to
generate the actual \*.png files.
+TF-A has been tested with pre-built binaries and file systems from
+`Linaro Release 19.06`_. Alternatively, you can build the binaries from
+source using instructions provided at the `Arm Platforms User guide`_.
+
Getting the TF-A source code
----------------------------
source, for submission to the project, the source must be in compliance with
this style guide.
-Additional, project-specific guidelines are defined in the `Trusted Firmware-A
-Coding Guidelines`_ document.
+Additional, project-specific guidelines are defined in the
+:ref:`Coding Style & Guidelines` document.
To assist with coding style compliance, the project Makefile contains two
targets which both utilise the `checkpatch.pl` script that ships with the Linux
source tree. The project also defines certain *checkpatch* options in the
``.checkpatch.conf`` file in the top-level directory.
-**Note:** Checkpatch errors will gate upstream merging of pull requests.
-Checkpatch warnings will not gate merging but should be reviewed and fixed if
-possible.
+.. note::
+ Checkpatch errors will gate upstream merging of pull requests.
+ Checkpatch warnings will not gate merging but should be reviewed and fixed if
+ possible.
To check the entire source tree, you must first download copies of
``checkpatch.pl``, ``spelling.txt`` and ``const_structs.checkpatch`` available
-------------
- Before building TF-A, the environment variable ``CROSS_COMPILE`` must point
- to the Linaro cross compiler.
+ to the cross compiler.
For AArch64:
.. code:: shell
- export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-linux-gnueabihf-
+ export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-eabi-
It is possible to build TF-A using Clang or Arm Compiler 6. To do so
``CC`` needs to point to the clang or armclang binary, which will
`Summary of build options`_ for more information on available build
options.
- - (AArch32 only) Currently only ``PLAT=fvp`` is supported.
-
- (AArch32 only) ``AARCH32_SP`` is the AArch32 EL3 Runtime Software and it
corresponds to the BL32 image. A minimal ``AARCH32_SP``, sp_min, is
provided by TF-A to demonstrate how PSCI Library can be integrated with
an AArch32 EL3 Runtime Software. Some AArch32 EL3 Runtime Software may
include other runtime services, for example Trusted OS services. A guide
to integrate PSCI library with AArch32 EL3 Runtime Software can be found
- `here`_.
+ at :ref:`PSCI Library Integration guide for Armv8-A AArch32 systems`.
- (AArch64 only) The TSP (Test Secure Payload), corresponding to the BL32
image, is not compiled in by default. Refer to the
- ``ARM_ARCH_MAJOR``: The major version of Arm Architecture to target when
compiling TF-A. Its value must be numeric, and defaults to 8 . See also,
*Armv8 Architecture Extensions* and *Armv7 Architecture Extensions* in
- `Firmware Design`_.
+ :ref:`Firmware Design`.
- ``ARM_ARCH_MINOR``: The minor version of Arm Architecture to target when
compiling TF-A. Its value must be a numeric, and defaults to 0. See also,
- *Armv8 Architecture Extensions* in `Firmware Design`_.
+ *Armv8 Architecture Extensions* in :ref:`Firmware Design`.
- ``BL2``: This is an optional build option which specifies the path to BL2
image for the ``fip`` target. In this case, the BL2 in the TF-A will not be
enable this use-case. For now, this option is only supported when BL2_AT_EL3
is set to '1'.
+- ``BL2_INV_DCACHE``: This is an optional build option which control dcache
+ invalidation upon BL2 entry. Some platform cannot handle cache operations
+ during entry as the coherency unit is not yet initialized. This may cause
+ crashing. Leaving this option to '1' (default) will allow the operation.
+ This option is only relevant when BL2_AT_EL3 is set to '1'.
+
- ``BL31``: This is an optional build option which specifies the path to
BL31 image for the ``fip`` target. In this case, the BL31 in TF-A will not
be built.
file that contains the BL33 private key in PEM format. If ``SAVE_KEYS=1``,
this file name will be used to save the key.
+- ``BRANCH_PROTECTION``: Numeric value to enable ARMv8.3 Pointer Authentication
+ and ARMv8.5 Branch Target Identification support for TF-A BL images themselves.
+ If enabled, it is needed to use a compiler (e.g GCC 9.1 and later versions) that
+ supports the option ``-mbranch-protection``.
+ Selects the branch protection features to use:
+- 0: Default value turns off all types of branch protection
+- 1: Enables all types of branch protection features
+- 2: Return address signing to its standard level
+- 3: Extend the signing to include leaf functions
+
+ The table below summarizes ``BRANCH_PROTECTION`` values, GCC compilation options
+ and resulting PAuth/BTI features.
+
+ +-------+--------------+-------+-----+
+ | Value | GCC option | PAuth | BTI |
+ +=======+==============+=======+=====+
+ | 0 | none | N | N |
+ +-------+--------------+-------+-----+
+ | 1 | standard | Y | Y |
+ +-------+--------------+-------+-----+
+ | 2 | pac-ret | Y | N |
+ +-------+--------------+-------+-----+
+ | 3 | pac-ret+leaf | Y | N |
+ +-------+--------------+-------+-----+
+
+ This option defaults to 0 and this is an experimental feature.
+ Note that Pointer Authentication is enabled for Non-secure world
+ irrespective of the value of this option if the CPU supports it.
+
- ``BUILD_MESSAGE_TIMESTAMP``: String used to identify the time and date of the
compilation of each build. It must be set to a C string (including quotes
where applicable). Defaults to a string that contains the time and date of
registers to be included when saving and restoring the CPU context. Default
is 0.
-- ``CTX_INCLUDE_PAUTH_REGS``: Boolean option that, when set to 1, allows
- Pointer Authentication for **Secure world**. This will cause the
- Armv8.3-PAuth registers to be included when saving and restoring the CPU
- context as part of a world switch. Default value is 0. Pointer Authentication
- is an experimental feature.
+- ``CTX_INCLUDE_MTE_REGS``: Enables register saving/reloading support for
+ ARMv8.5 Memory Tagging Extension. A value of 0 will disable
+ saving/reloading and restrict the use of MTE to the normal world if the
+ CPU has support, while a value of 1 enables the saving/reloading, allowing
+ the use of MTE in both the secure and non-secure worlds. Default is 0
+ (disabled) and this feature is experimental.
- Note that, if the CPU supports it, Pointer Authentication is allowed for
- Non-secure world irrespectively of the value of this flag. "Allowed" means
- that accesses to PAuth-related registers or execution of PAuth-related
- instructions will not be trapped to EL3. As such, usage or not of PAuth in
- Non-secure world images, depends on those images themselves.
+- ``CTX_INCLUDE_PAUTH_REGS``: Boolean option that, when set to 1, enables
+ Pointer Authentication for Secure world. This will cause the ARMv8.3-PAuth
+ registers to be included when saving and restoring the CPU context as
+ part of world switch. Default value is 0 and this is an experimental feature.
+ Note that Pointer Authentication is enabled for Non-secure world irrespective
+ of the value of this flag if the CPU supports it.
- ``DEBUG``: Chooses between a debug and release build. It can take either 0
(release) or 1 (debug) as values. 0 is the default.
for development platforms. ``TRUSTED_BOARD_BOOT`` flag must be set if this
flag has to be enabled. 0 is the default.
+- ``E``: Boolean option to make warnings into errors. Default is 1.
+
- ``EL3_PAYLOAD_BASE``: This option enables booting an EL3 payload instead of
the normal boot flow. It must specify the entry point address of the EL3
payload. Please refer to the "Booting an EL3 payload" section for more
partitioning in EL3, however. Platform initialisation code should configure
and use partitions in EL3 as required. This option defaults to ``0``.
-- ``ENABLE_PAUTH``: Boolean option to enable Armv8.3 Pointer Authentication
- for **TF-A BL images themselves**. If enabled, the compiler must support the
- ``-msign-return-address`` option. This flag defaults to 0. Pointer
- Authentication is an experimental feature.
-
- If this flag is enabled, ``CTX_INCLUDE_PAUTH_REGS`` must also be enabled.
-
- ``ENABLE_PIE``: Boolean option to enable Position Independent Executable(PIE)
support within generic code in TF-A. This option is currently only supported
in BL31. Default is 0.
is AArch32.
- ``ENABLE_SPM`` : Boolean option to enable the Secure Partition Manager (SPM).
- Refer to the `Secure Partition Manager Design guide`_ for more details about
+ Refer to :ref:`Secure Partition Manager` for more details about
this feature. Default is 0.
- ``ENABLE_SVE_FOR_NS``: Boolean option to enable Scalable Vector Extension
- ``GENERATE_COT``: Boolean flag used to build and execute the ``cert_create``
tool to create certificates as per the Chain of Trust described in
- `Trusted Board Boot`_. The build system then calls ``fiptool`` to
+ :ref:`Trusted Board Boot`. The build system then calls ``fiptool`` to
include the certificates in the FIP and FWU_FIP. Default value is '0'.
Specify both ``TRUSTED_BOARD_BOOT=1`` and ``GENERATE_COT=1`` to include support
- ``KEY_ALG``: This build flag enables the user to select the algorithm to be
used for generating the PKCS keys and subsequent signing of the certificate.
- It accepts 3 values: ``rsa``, ``rsa_1_5`` and ``ecdsa``. The option
- ``rsa_1_5`` is the legacy PKCS#1 RSA 1.5 algorithm which is not TBBR
- compliant and is retained only for compatibility. The default value of this
- flag is ``rsa`` which is the TBBR compliant PKCS#1 RSA 2.1 scheme.
+ It accepts 2 values: ``rsa`` and ``ecdsa``. The default value of this flag
+ is ``rsa`` which is the TBBR compliant PKCS#1 RSA 2.1 scheme.
+
+- ``KEY_SIZE``: This build flag enables the user to select the key size for
+ the algorithm specified by ``KEY_ALG``. The valid values for ``KEY_SIZE``
+ depend on the chosen algorithm.
+
+ +-----------+------------------------------------+
+ | KEY_ALG | Possible key sizes |
+ +===========+====================================+
+ | rsa | 1024, 2048 (default), 3072, 4096 |
+ +-----------+------------------------------------+
+ | ecdsa | unavailable |
+ +-----------+------------------------------------+
- ``HASH_ALG``: This build flag enables the user to select the secure hash
algorithm. It accepts 3 values: ``sha256``, ``sha384`` and ``sha512``.
file that contains the ROT private key in PEM format. If ``SAVE_KEYS=1``, this
file name will be used to save the key.
+- ``SANITIZE_UB``: This option enables the Undefined Behaviour sanitizer. It
+ can take 3 values: 'off' (default), 'on' and 'trap'. When using 'trap',
+ gcc and clang will insert calls to ``__builtin_trap`` on detected
+ undefined behaviour, which defaults to a ``brk`` instruction. When using
+ 'on', undefined behaviour is translated to a call to special handlers which
+ prints the exact location of the problem and its cause and then panics.
+
+ .. note::
+ Because of the space penalty of the Undefined Behaviour sanitizer,
+ this option will increase the size of the binary. Depending on the
+ memory constraints of the target platform, it may not be possible to
+ enable the sanitizer for all images (BL1 and BL2 are especially
+ likely to be memory constrained). We recommend that the
+ sanitizer is enabled only in debug builds.
+
- ``SAVE_KEYS``: This option is used when ``GENERATE_COT=1``. It tells the
certificate generation tool to save the keys used to establish the Chain of
Trust. Allowed options are '0' or '1'. Default is '0' (do not save).
- ``SEPARATE_CODE_AND_RODATA``: Whether code and read-only data should be
isolated on separate memory pages. This is a trade-off between security and
memory usage. See "Isolating code and read-only data on separate memory
- pages" section in `Firmware Design`_. This flag is disabled by default and
- affects all BL images.
+ pages" section in :ref:`Firmware Design`. This flag is disabled by default
+ and affects all BL images.
- ``SPD``: Choose a Secure Payload Dispatcher component to be built into TF-A.
This build option is only valid if ``ARCH=aarch64``. The value should be
of certificates in the FIP and FWU_FIP depends upon the value of the
``GENERATE_COT`` option.
- Note: This option depends on ``CREATE_KEYS`` to be enabled. If the keys
- already exist in disk, they will be overwritten without further notice.
+ .. warning::
+ This option depends on ``CREATE_KEYS`` to be enabled. If the keys
+ already exist in disk, they will be overwritten without further notice.
- ``TRUSTED_WORLD_KEY``: This option is used when ``GENERATE_COT=1``. It
specifies the file that contains the Trusted World private key in PEM
- ``TSP_INIT_ASYNC``: Choose BL32 initialization method as asynchronous or
synchronous, (see "Initializing a BL32 Image" section in
- `Firmware Design`_). It can take the value 0 (BL32 is initialized using
+ :ref:`Firmware Design`). It can take the value 0 (BL32 is initialized using
synchronous method) or 1 (BL32 is initialized using asynchronous method).
Default is 0.
interrupts to TSP allowing it to save its context and hand over
synchronously to EL3 via an SMC.
- Note: when ``EL3_EXCEPTION_HANDLING`` is ``1``, ``TSP_NS_INTR_ASYNC_PREEMPT``
- must also be set to ``1``.
+ .. note::
+ When ``EL3_EXCEPTION_HANDLING`` is ``1``, ``TSP_NS_INTR_ASYNC_PREEMPT``
+ must also be set to ``1``.
- ``USE_ARM_LINK``: This flag determines whether to enable support for ARM
linker. When the ``LINKER`` build variable points to the armlink linker,
- ``USE_COHERENT_MEM``: This flag determines whether to include the coherent
memory region in the BL memory map or not (see "Use of Coherent memory in
- TF-A" section in `Firmware Design`_). It can take the value 1
+ TF-A" section in :ref:`Firmware Design`). It can take the value 1
(Coherent memory region is included) or 0 (Coherent memory region is
excluded). Default is 1.
- ``USE_ROMLIB``: This flag determines whether library at ROM will be used.
This feature creates a library of functions to be placed in ROM and thus
- reduces SRAM usage. Refer to `Library at ROM`_ for further details. Default
- is 0.
+ reduces SRAM usage. Refer to :ref:`Library at ROM` for further details.
+ Default is 0.
+
+- ``USE_SPINLOCK_CAS``: Setting this build flag to 1 selects the spinlock
+ implementation variant using the ARMv8.1-LSE compare-and-swap instruction.
+ Notice this option is experimental and only available to AArch64 builds.
- ``V``: Verbose build. If assigned anything other than 0, the build commands
are printed. Default is 0.
Defaults to a string formed by concatenating the version number, build type
and build string.
+- ``W``: Warning level. Some compiler warning options of interest have been
+ regrouped and put in the root Makefile. This flag can take the values 0 to 3,
+ each level enabling more warning options. Default is 0.
+
- ``WARMBOOT_ENABLE_DCACHE_EARLY`` : Boolean option to enable D-cache early on
the CPU after warm boot. This is applicable for platforms which do not
require interconnect programming to enable cache coherency (eg: single
SBROM library must be specified via ``CCSBROM_LIB_PATH`` flag.
For a better understanding of these options, the Arm development platform memory
-map is explained in the `Firmware Design`_.
+map is explained in the :ref:`Firmware Design`.
Arm CSS platform specific build options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The default value is 0.
- ``FVP_HW_CONFIG_DTS`` : Specify the path to the DTS file to be compiled
- to DTB and packaged in FIP as the HW_CONFIG. See `Firmware Design`_ for
+ to DTB and packaged in FIP as the HW_CONFIG. See :ref:`Firmware Design` for
details on HW_CONFIG. By default, this is initialized to a sensible DTS
file in ``fdts/`` folder depending on other build options. But some cases,
like shifted affinity format for MPIDR, cannot be detected at build time
and this option is needed to specify the appropriate DTS file.
- ``FVP_HW_CONFIG`` : Specify the path to the HW_CONFIG blob to be packaged in
- FIP. See `Firmware Design`_ for details on HW_CONFIG. This option is
+ FIP. See :ref:`Firmware Design` for details on HW_CONFIG. This option is
similar to the ``FVP_HW_CONFIG_DTS`` option, but it directly specifies the
HW_CONFIG blob instead of the DTS file. This option is useful to override
the default HW_CONFIG selected by the build system.
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 **Memory layout on Arm development
-platforms** section in the `Firmware Design`_).
+.. warning::
+ Using ``-O0`` could cause output images to be larger and base addresses
+ might need to be recalculated (see the **Memory layout on Arm development
+ platforms** section in the :ref:`Firmware Design`).
Extra debug options can be passed to the build system by setting ``CFLAGS`` or
``LDFLAGS``:
The TSP is coupled with a companion runtime service in the BL31 firmware,
called the TSPD. Therefore, if you intend to use the TSP, the BL31 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`_.
+:ref:`Secure-EL1 Payloads and Dispatchers <firmware_design_sel1_spd>` section
+in the :ref:`Firmware Design` document.
First clean the TF-A build directory to get rid of any previous BL31 binary.
Then to build the TSP image use:
The unpack operation will fail if the images already exist at the
destination. In that case, use -f or --force to continue.
-More information about FIP can be found in the `Firmware Design`_ document.
+More information about FIP can be found in the :ref:`Firmware Design` document.
Building FIP images with support for Trusted Board Boot
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Trusted Board Boot primarily consists of the following two features:
-- Image Authentication, described in `Trusted Board Boot`_, and
-- Firmware Update, described in `Firmware Update`_
+- Image Authentication, described in :ref:`Trusted Board Boot`, and
+- Firmware Update, described in :ref:`Firmware Update (FWU)`
The following steps should be followed to build FIP and (optionally) FWU_FIP
images with support for these features:
is important to use a version that is compatible with TF-A and fixes any
known security vulnerabilities. See `mbed TLS Security Center`_ for more
information. The latest version of TF-A is tested with tag
- ``mbedtls-2.16.0``.
+ ``mbedtls-2.16.2``.
The ``drivers/auth/mbedtls/mbedtls_*.mk`` files contain the list of mbed TLS
source files the modules depend upon.
in the output build directory.
#. The optional FWU_FIP contains any additional images to be loaded from
- Non-Volatile storage during the `Firmware Update`_ process. To build the
- FWU_FIP, any FWU images required by the platform must be specified on the
- command line. On Arm development platforms like Juno, these are:
+ Non-Volatile storage during the :ref:`Firmware Update (FWU)` process. To
+ build the FWU_FIP, any FWU images required by the platform must be specified
+ on the command line. On Arm development platforms like Juno, these are:
- NS_BL2U. The AP non-secure Firmware Updater image.
- SCP_BL2U. The SCP Firmware Update Configuration image.
NS_BL2U=<path-to>/<ns_bl2u_image> \
all fip fwu_fip
- Note: The BL2U image will be built by default and added to the FWU_FIP.
- The user may override this by adding ``BL2U=<path-to>/<bl2u_image>``
- to the command line above.
+ .. note::
+ The BL2U image will be built by default and added to the FWU_FIP.
+ The user may override this by adding ``BL2U=<path-to>/<bl2u_image>``
+ to the command line above.
- Note: Building and installing the non-secure and SCP FWU images (NS_BL1U,
- NS_BL2U and SCP_BL2U) is outside the scope of this document.
+ .. note::
+ Building and installing the non-secure and SCP FWU images (NS_BL1U,
+ NS_BL2U and SCP_BL2U) is outside the scope of this document.
The result of this build will be bl1.bin, fip.bin and fwu_fip.bin binaries.
Both the FIP and FWU_FIP will include the certificates corresponding to the
Firmware, obtain the additional required firmware, and pack it all together in
a single FIP binary. It assumes that a `Linaro Release`_ has been installed.
-Note: Pre-built binaries for AArch32 are available from Linaro Release 16.12
-onwards. Before that release, pre-built binaries are only available for AArch64.
+.. note::
+ Pre-built binaries for AArch32 are available from Linaro Release 16.12
+ onwards. Before that release, pre-built binaries are only available for
+ AArch64.
-Note: Follow the full instructions for one platform before switching to a
-different one. Mixing instructions for different platforms may result in
-corrupted binaries.
+.. warning::
+ Follow the full instructions for one platform before switching to a
+ different one. Mixing instructions for different platforms may result in
+ corrupted binaries.
-Note: The uboot image downloaded by the Linaro workspace script does not always
-match the uboot image packaged as BL33 in the corresponding fip file. It is
-recommended to use the version that is packaged in the fip file using the
-instructions below.
+.. warning::
+ The uboot image downloaded by the Linaro workspace script does not always
+ match the uboot image packaged as BL33 in the corresponding fip file. It is
+ recommended to use the version that is packaged in the fip file using the
+ instructions below.
-Note: For the FVP, the kernel FDT is packaged in FIP during build and loaded
-by the firmware at runtime. See `Obtaining the Flattened Device Trees`_
-section for more info on selecting the right FDT to use.
+.. note::
+ For the FVP, the kernel FDT is packaged in FIP during build and loaded
+ by the firmware at runtime. See `Obtaining the Flattened Device Trees`_
+ section for more info on selecting the right FDT to use.
#. Clean the working directory
make [DEBUG=1] [V=1] fiptool
# Unpack firmware images from Linaro FIP
- ./tools/fiptool/fiptool unpack <path-to-linaro-release>/fip.bin
+ ./tools/fiptool/fiptool unpack <path-to-linaro-release>/[SOFTWARE]/fip.bin
The unpack operation will result in a set of binary images extracted to the
current working directory. The SCP_BL2 image corresponds to
``scp-fw.bin`` and BL33 corresponds to ``nt-fw.bin``.
- Note: The fiptool will complain if the images to be unpacked already
- exist in the current directory. If that is the case, either delete those
- files or use the ``--force`` option to overwrite.
+ .. note::
+ The fiptool will complain if the images to be unpacked already
+ exist in the current directory. If that is the case, either delete those
+ files or use the ``--force`` option to overwrite.
- Note: For AArch32, the instructions below assume that nt-fw.bin is a normal
- world boot loader that supports AArch32.
+ .. note::
+ For AArch32, the instructions below assume that nt-fw.bin is a
+ normal world boot loader that supports AArch32.
#. Build TF-A images and create a new FIP for FVP
separately for AArch32.
- Before building BL32, the environment variable ``CROSS_COMPILE`` must point
- to the AArch32 Linaro cross compiler.
+ to the AArch32 cross compiler.
.. code:: shell
- export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-linux-gnueabihf-
+ export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-eabi-
- Build BL32 in AArch32.
make realclean
- Before building BL1 and BL2, the environment variable ``CROSS_COMPILE``
- must point to the AArch64 Linaro cross compiler.
+ must point to the AArch64 cross compiler.
.. code:: shell
above. The process to load binaries to memory is the one explained in
`Booting an EL3 payload on Juno`_.
+.. _user_guide_run_fvp:
+
Running the software on FVP
---------------------------
Arm FVPs without shifted affinities, and that do not support threaded CPU cores
(64-bit host machine only).
-The FVP models used are Version 11.6 Build 45, unless otherwise stated.
+.. note::
+ The FVP models used are Version 11.6 Build 45, unless otherwise stated.
- ``FVP_Base_AEMv8A-AEMv8A``
- ``FVP_Base_AEMv8A-AEMv8A-AEMv8A-AEMv8A-CCN502``
- ``FVP_Base_Cortex-A76x4``
- ``FVP_Base_Cortex-A76AEx4``
- ``FVP_Base_Cortex-A76AEx8``
+- ``FVP_Base_Cortex-A77x4`` (Version 11.7 build 36)
- ``FVP_Base_Neoverse-N1x4``
-- ``FVP_Base_Deimos``
+- ``FVP_Base_Zeusx4``
- ``FVP_CSS_SGI-575`` (Version 11.3 build 42)
- ``FVP_CSS_SGM-775`` (Version 11.3 build 42)
- ``FVP_RD_E1Edge`` (Version 11.3 build 42)
- ``FVP_Base_AEMv8A-AEMv8A``
- ``FVP_Base_Cortex-A32x4``
-NOTE: The ``FVP_Base_RevC-2xAEMv8A`` FVP only supports shifted affinities, which
-is not compatible with legacy GIC configurations. Therefore this FVP does not
-support these legacy GIC configurations.
-
-NOTE: The build numbers quoted above are those reported by launching the FVP
-with the ``--version`` parameter.
-
-NOTE: Linaro provides a ramdisk image in prebuilt FVP configurations and full
-file systems that can be downloaded separately. To run an FVP with a virtio
-file system image an additional FVP configuration option
-``-C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>`` can be
-used.
-
-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.
-
-NOTE: FVPs can be launched with ``--cadi-server`` option such that a
-CADI-compliant debugger (for example, Arm DS-5) can connect to and control its
-execution.
-
-NOTE: Since FVP model Version 11.0 Build 11.0.34 and Version 8.5 Build 0.8.5202
-the internal synchronisation timings changed compared to older versions of the
-models. The models can be launched with ``-Q 100`` option if they are required
-to match the run time characteristics of the older versions.
+.. note::
+ The ``FVP_Base_RevC-2xAEMv8A`` FVP only supports shifted affinities, which
+ is not compatible with legacy GIC configurations. Therefore this FVP does not
+ support these legacy GIC configurations.
+
+.. note::
+ The build numbers quoted above are those reported by launching the FVP
+ with the ``--version`` parameter.
+
+.. note::
+ Linaro provides a ramdisk image in prebuilt FVP configurations and full
+ file systems that can be downloaded separately. To run an FVP with a virtio
+ file system image an additional FVP configuration option
+ ``-C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>`` can be
+ used.
+
+.. 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.
+
+.. note::
+ FVPs can be launched with ``--cadi-server`` option such that a
+ CADI-compliant debugger (for example, Arm DS-5) can connect to and control
+ its execution.
+
+.. warning::
+ Since FVP model Version 11.0 Build 11.0.34 and Version 8.5 Build 0.8.5202
+ the internal synchronisation timings changed compared to older versions of
+ the models. The models can be launched with ``-Q 100`` option if they are
+ required to match the run time characteristics of the older versions.
The Foundation FVP is a cut down version of the AArch64 Base FVP. It can be
downloaded for free from `Arm's website`_.
a subset of the Base FVP components. For example, the Foundation FVP lacks
CLCD and MMC support, and has only one CPU cluster.
-Note: It is not recommended to use the FDTs built along the kernel because not
-all FDTs are available from there.
+.. note::
+ It is not recommended to use the FDTs built along the kernel because not
+ all FDTs are available from there.
The dynamic configuration capability is enabled in the firmware for FVPs.
This means that the firmware can authenticate and load the FDT if present in
- BL1 is loaded at the start of the Trusted ROM.
- The Firmware Image Package is loaded at the start of NOR FLASH0.
- The firmware loads the FDT packaged in FIP to the DRAM. The FDT load address
- is specified via the ``hw_config_addr`` property in `TB_FW_CONFIG for FVP`_.
+ is specified via the ``hw_config_addr`` property in ``TB_FW_CONFIG`` for FVP.
- The default use-case for the Foundation FVP is to use the ``--gicv3`` option
and enable the GICv3 device in the model. Note that without this option,
the Foundation FVP defaults to legacy (Versatile Express) memory map which
--data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
--data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
-Note: The ``FVP_Base_RevC-2xAEMv8A`` has shifted affinities and requires a
-specific DTS for all the CPUs to be loaded.
+.. note::
+ The ``FVP_Base_RevC-2xAEMv8A`` has shifted affinities and requires
+ a specific DTS for all the CPUs to be loaded.
Running on the AEMv8 Base FVP (AArch32) with reset to BL1 entrypoint
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
--data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
-Note: The load address of ``<bl32-binary>`` depends on the value ``BL32_BASE``.
-It should match the address programmed into the RVBAR register as well.
+.. note::
+ The load address of ``<bl32-binary>`` depends on the value ``BL32_BASE``.
+ It should match the address programmed into the RVBAR register as well.
Running on the Cortex-A57-A53 Base FVP with reset to BL31 entrypoint
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This version of TF-A has been tested on variants r0, r1 and r2 of Juno.
-To execute the software stack on Juno, the version of the Juno board recovery
-image indicated in the `Linaro Release Notes`_ must be installed. If you have an
-earlier version installed or are unsure which version is installed, please
-re-install the recovery image by following the
-`Instructions for using Linaro's deliverables on Juno`_.
+To execute the software stack on Juno, installing the latest Arm Platforms
+software deliverables is recommended. Please install the deliverables by
+following the `Instructions for using Linaro's deliverables on Juno`_.
Preparing TF-A images
~~~~~~~~~~~~~~~~~~~~~
*Copyright (c) 2013-2019, Arm Limited and Contributors. All rights reserved.*
-.. _arm Developer page: https://developer.arm.com/open-source/gnu-toolchain/gnu-a/downloads
-.. _Linaro: `Linaro Release Notes`_
-.. _Linaro Release: `Linaro Release Notes`_
-.. _Linaro Release Notes: https://community.arm.com/dev-platforms/w/docs/226/old-release-notes
-.. _Linaro instructions: https://community.arm.com/dev-platforms/w/docs/304/arm-reference-platforms-deliverables
+.. _Arm Developer page: https://developer.arm.com/open-source/gnu-toolchain/gnu-a/downloads
+.. _Linaro Release: http://releases.linaro.org/members/arm/platforms
+.. _Linaro Release 19.06: http://releases.linaro.org/members/arm/platforms/19.06
+.. _Linaro instructions: https://git.linaro.org/landing-teams/working/arm/arm-reference-platforms.git/about
+.. _Arm Platforms User guide: https://git.linaro.org/landing-teams/working/arm/arm-reference-platforms.git/about/docs/user-guide.rst
.. _Instructions for using Linaro's deliverables on Juno: https://community.arm.com/dev-platforms/w/docs/303/juno
.. _Arm Platforms Portal: https://community.arm.com/dev-platforms/
.. _Development Studio 5 (DS-5): https://developer.arm.com/products/software-development-tools/ds-5-development-studio
.. _`Linux Coding Style`: https://www.kernel.org/doc/html/latest/process/coding-style.html
.. _Linux master tree: https://github.com/torvalds/linux/tree/master/
.. _Dia: https://wiki.gnome.org/Apps/Dia/Download
-.. _here: psci-lib-integration-guide.rst
-.. _Trusted Board Boot: trusted-board-boot.rst
-.. _TB_FW_CONFIG for FVP: ../plat/arm/board/fvp/fdts/fvp_tb_fw_config.dts
-.. _Secure-EL1 Payloads and Dispatchers: firmware-design.rst#user-content-secure-el1-payloads-and-dispatchers
-.. _Firmware Update: firmware-update.rst
-.. _Firmware Design: firmware-design.rst
.. _mbed TLS Repository: https://github.com/ARMmbed/mbedtls.git
.. _mbed TLS Security Center: https://tls.mbed.org/security
.. _Arm's website: `FVP models`_
.. _FVP models: https://developer.arm.com/products/system-design/fixed-virtual-platforms
.. _Juno Getting Started Guide: http://infocenter.arm.com/help/topic/com.arm.doc.dui0928e/DUI0928E_juno_arm_development_platform_gsg.pdf
.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
-.. _Secure Partition Manager Design guide: secure-partition-manager-design.rst
-.. _`Trusted Firmware-A Coding Guidelines`: coding-guidelines.rst
-.. _`Library at ROM`: romlib-design.rst
projects / project / bcm63xx / atf.git / blobdiff