Djam/arm-trusted-firmware
1
0
Fork 0
mirror of https://github.com/ARM-software/arm-trusted-firmware.git synced 2025-04-16 17:44:19 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update Arm TF references to TF-A

Browse source 
Update Arm Trusted Firmware references in the upstream documents to
Trusted Firmware-A (TF-A). This is for consistency with and
disambiguation from Trusted Firmware-M (TF-M).

Also update other Arm trademarks, e.g. ARM->Arm, ARMv8->Armv8-A.

Change-Id: I8bb0e18af29c6744eeea2dc6c08f2c10b20ede22
Signed-off-by: Dan Handley <dan.handley@arm.com>
Signed-off-by: David Cunado <david.cunado@arm.com>
This commit is contained in:
Dan Handley 2018-03-01 18:44:00 +00:00 • committed by David Cunado
parent c3e34a9e01
commit 4def07d535
34 changed files with 999 additions and 1031 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
contributing.rst
View file

@ -1,13 +1,13 @@
Contributing to ARM Trusted Firmware Contributing to Trusted Firmware-A
==================================== ==================================
Getting Started Getting Started
--------------- ---------------
- Make sure you have a `GitHub account`_. - Make sure you have a `GitHub account`_.
- Create an `issue`_ for your work if one does not already exist. This gives - Create an `issue`_ for your work if one does not already exist. This gives
everyone visibility of whether others are working on something similar. ARM everyone visibility of whether others are working on something similar. Arm
licensees may contact ARM directly via their partner managers instead if licensees may contact Arm directly via their partner managers instead if
they prefer. they prefer.
- Note that the `issue`_ tracker for this project is in a separate - Note that the `issue`_ tracker for this project is in a separate
@ -27,8 +27,8 @@ Making Changes
- Make commits of logical units. See these general `Git guidelines`_ for - Make commits of logical units. See these general `Git guidelines`_ for
contributing to a project. contributing to a project.
- Follow the `Linux coding style`_; this style is enforced for the ARM Trusted - Follow the `Linux coding style`_; this style is enforced for the TF-A
Firmware project (style errors only, not warnings). project (style errors only, not warnings).
- Use the checkpatch.pl script provided with the Linux source tree. A - Use the checkpatch.pl script provided with the Linux source tree. A
Makefile target is provided for convenience (see section 2 in the Makefile target is provided for convenience (see section 2 in the
@ -57,7 +57,7 @@ Making Changes
:: ::
Portions copyright (c) [XXXX-]YYYY, ARM Limited and Contributors. All rights reserved. Portions copyright (c) [XXXX-]YYYY, Arm Limited and Contributors. All rights reserved.
where XXXX is the year of first contribution (if different to YYYY) and where XXXX is the year of first contribution (if different to YYYY) and
YYYY is the year of most recent contribution. YYYY is the year of most recent contribution.
@ -108,7 +108,7 @@ Submitting Changes
-------------- --------------
*Copyright (c) 2013-2017, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2013-2018, Arm Limited and Contributors. All rights reserved.*
.. _GitHub account: https://github.com/signup/free .. _GitHub account: https://github.com/signup/free
.. _issue: https://github.com/ARM-software/tf-issues/issues .. _issue: https://github.com/ARM-software/tf-issues/issues

22
docs/arm-sip-service.rst
View file

@ -1,7 +1,7 @@
ARM SiP Service Arm SiP Service
=============== ===============
This document enumerates and describes the ARM SiP (Silicon Provider) services. This document enumerates and describes the Arm SiP (Silicon Provider) services.
SiP services are non-standard, platform-specific services offered by the silicon SiP services are non-standard, platform-specific services offered by the silicon
implementer or platform provider. They are accessed via. ``SMC`` ("SMC calls") implementer or platform provider. They are accessed via. ``SMC`` ("SMC calls")
@ -13,20 +13,20 @@ services:
``0xc200ffff`` for 64-bit calls, and ``0x82000000`` - ``0x8200ffff`` for 32-bit ``0xc200ffff`` for 64-bit calls, and ``0x82000000`` - ``0x8200ffff`` for 32-bit
calls. calls.
The ARM SiP implementation offers the following services: The Arm SiP implementation offers the following services:
- Performance Measurement Framework (PMF) - Performance Measurement Framework (PMF)
- Execution State Switching service - Execution State Switching service
Source definitions for ARM SiP service are located in the ``arm_sip_svc.h`` header Source definitions for Arm SiP service are located in the ``arm_sip_svc.h`` header
file. file.
Performance Measurement Framework (PMF) Performance Measurement Framework (PMF)
--------------------------------------- ---------------------------------------
The `Performance Measurement Framework`_ The `Performance Measurement Framework`_
allows callers to retrieve timestamps captured at various paths in ARM Trusted allows callers to retrieve timestamps captured at various paths in TF-A
Firmware execution. It's described in detail in `Firmware Design document`_. execution. It's described in detail in `Firmware Design document`_.
Execution State Switching service Execution State Switching service
--------------------------------- ---------------------------------
@ -35,8 +35,8 @@ Execution State Switching service provides a mechanism for a non-secure lower
Exception Level (either EL2, or NS EL1 if EL2 isn't implemented) to request to Exception Level (either EL2, or NS EL1 if EL2 isn't implemented) to request to
switch its execution state (a.k.a. Register Width), either from AArch64 to switch its execution state (a.k.a. Register Width), either from AArch64 to
AArch32, or from AArch32 to AArch64, for the calling CPU. This service is only AArch32, or from AArch32 to AArch64, for the calling CPU. This service is only
available when ARM Trusted Firmware is built for AArch64 (i.e. when build option available when Trusted Firmware-A (TF-A) is built for AArch64 (i.e. when build
``ARCH`` is set to ``aarch64``). option ``ARCH`` is set to ``aarch64``).
``ARM_SIP_SVC_EXE_STATE_SWITCH`` ``ARM_SIP_SVC_EXE_STATE_SWITCH``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -79,8 +79,8 @@ The service may return the following error codes:
- ``STATE_SW_E_PARAM``: If any of the parameters were deemed invalid for - ``STATE_SW_E_PARAM``: If any of the parameters were deemed invalid for
a specific request. a specific request.
- ``STATE_SW_E_DENIED``: If the call is not successful, or when ARM Trusted - ``STATE_SW_E_DENIED``: If the call is not successful, or when TF-A is
Firmware is built for AArch32. built for AArch32.
If the call is successful, the caller wouldn't observe the SMC returning. If the call is successful, the caller wouldn't observe the SMC returning.
Instead, execution starts at the supplied entry point, with the CPU registers 0 Instead, execution starts at the supplied entry point, with the CPU registers 0
@ -89,7 +89,7 @@ respectively.
-------------- --------------
*Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2017-2018, Arm Limited and Contributors. All rights reserved.*
.. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html .. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
.. _Performance Measurement Framework: ./firmware-design.rst#user-content-performance-measurement-framework .. _Performance Measurement Framework: ./firmware-design.rst#user-content-performance-measurement-framework

31
docs/auth-framework.rst
View file

@ -7,8 +7,9 @@ Abstracting a Chain of Trust
.. contents:: .. contents::
The aim of this document is to describe the authentication framework implemented The aim of this document is to describe the authentication framework
in the Trusted Firmware. This framework fulfills the following requirements: implemented in Trusted Firmware-A (TF-A). This framework fulfills the
following requirements:
#. It should be possible for a platform port to specify the Chain of Trust in #. It should be possible for a platform port to specify the Chain of Trust in
terms of certificate hierarchy and the mechanisms used to verify a terms of certificate hierarchy and the mechanisms used to verify a
@ -152,8 +153,8 @@ performed to verify it:
In Diagram 1, each component is responsible for one or more of these operations. In Diagram 1, each component is responsible for one or more of these operations.
The responsibilities are briefly described below. The responsibilities are briefly described below.
TF Generic code and IO framework (GEN/IO) TF-A Generic code and IO framework (GEN/IO)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
These components are responsible for initiating the authentication process for a These components are responsible for initiating the authentication process for a
particular image in BL1 or BL2. For each BL image that requires authentication, particular image in BL1 or BL2. For each BL image that requires authentication,
@ -162,8 +163,8 @@ image until either an authenticated image or the ROT is reached. Then the
Generic code calls the IO framewotk to load the image and calls the Generic code calls the IO framewotk to load the image and calls the
Authentication module to authenticate it, following the CoT from ROT to Image. Authentication module to authenticate it, following the CoT from ROT to Image.
TF Platform Port (PP) TF-A Platform Port (PP)
^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^
The platform is responsible for: The platform is responsible for:
@ -374,8 +375,8 @@ single parsing method. There has to be one IPL for every method used by the
platform. platform.
#. Raw format: This format is effectively a nop as an image using this method #. Raw format: This format is effectively a nop as an image using this method
is treated as being in raw binary format e.g. boot loader images used by ARM is treated as being in raw binary format e.g. boot loader images used by
TF. This method should only be used by data images. TF-A. This method should only be used by data images.
#. X509V3 method: This method uses industry standards like X.509 to represent #. X509V3 method: This method uses industry standards like X.509 to represent
PKI certificates (authentication images). It is expected that open source PKI certificates (authentication images). It is expected that open source
@ -631,8 +632,8 @@ array of image descriptors and it is registered in the framework using the macro
process to fail). process to fail).
The number of images participating in the boot process depends on the CoT. There The number of images participating in the boot process depends on the CoT. There
is, however, a minimum set of images that are mandatory in the Trusted Firmware is, however, a minimum set of images that are mandatory in TF-A and thus all
and thus all CoTs must present: CoTs must present:
- ``BL2`` - ``BL2``
- ``SCP_BL2`` (platform specific) - ``SCP_BL2`` (platform specific)
@ -648,7 +649,7 @@ Following the `Platform Porting Guide`_, a platform must provide unique
identifiers for all the images and certificates that will be loaded during the identifiers for all the images and certificates that will be loaded during the
boot process. If a platform is using the TBBR as a reference for trusted boot, boot process. If a platform is using the TBBR as a reference for trusted boot,
these identifiers can be obtained from ``include/common/tbbr/tbbr_img_def.h``. these identifiers can be obtained from ``include/common/tbbr/tbbr_img_def.h``.
ARM platforms include this file in ``include/plat/arm/common/arm_def.h``. Other Arm platforms include this file in ``include/plat/arm/common/arm_def.h``. Other
platforms may also include this file or provide their own identifiers. platforms may also include this file or provide their own identifiers.
**Important**: the authentication module uses these identifiers to index the **Important**: the authentication module uses these identifiers to index the
@ -880,7 +881,7 @@ extract the authentication parameters. The number and type of parser libraries
depend on the images used in the CoT. Raw images do not need a library, so depend on the images used in the CoT. Raw images do not need a library, so
only an x509v3 library is required for the TBBR CoT. only an x509v3 library is required for the TBBR CoT.
ARM platforms will use an x509v3 library based on mbed TLS. This library may be Arm platforms will use an x509v3 library based on mbed TLS. This library may be
found in ``drivers/auth/mbedtls/mbedtls_x509_parser.c``. It exports three found in ``drivers/auth/mbedtls/mbedtls_x509_parser.c``. It exports three
functions: functions:
@ -898,14 +899,14 @@ an image of type ``IMG_CERT``, it will call the corresponding function exported
in this file. in this file.
The build system must be updated to include the corresponding library and The build system must be updated to include the corresponding library and
mbed TLS sources. ARM platforms use the ``arm_common.mk`` file to pull the mbed TLS sources. Arm platforms use the ``arm_common.mk`` file to pull the
sources. sources.
The cryptographic library The cryptographic library
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~
The cryptographic module relies on a library to perform the required operations, The cryptographic module relies on a library to perform the required operations,
i.e. verify a hash or a digital signature. ARM platforms will use a library i.e. verify a hash or a digital signature. Arm platforms will use a library
based on mbed TLS, which can be found in based on mbed TLS, which can be found in
``drivers/auth/mbedtls/mbedtls_crypto.c``. This library is registered in the ``drivers/auth/mbedtls/mbedtls_crypto.c``. This library is registered in the
authentication framework using the macro ``REGISTER_CRYPTO_LIB()`` and exports authentication framework using the macro ``REGISTER_CRYPTO_LIB()`` and exports
@ -934,7 +935,7 @@ of SHA-256 with smaller memory footprint (~1.5 KB less) but slower (~30%).
-------------- --------------
*Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2017-2018, Arm Limited and Contributors. All rights reserved.*
.. _Trusted Board Boot: ./trusted-board-boot.rst .. _Trusted Board Boot: ./trusted-board-boot.rst
.. _Platform Porting Guide: ./porting-guide.rst .. _Platform Porting Guide: ./porting-guide.rst

305
docs/change-log.rst
View file

@ -4,8 +4,8 @@
.. contents:: .. contents::
ARM Trusted Firmware - version 1.4 Trusted Firmware-A - version 1.4
================================== ================================
New features New features
------------ ------------
@ -23,13 +23,13 @@ New features
- Added support for Cortex-A75 and Cortex-A55 processors. - Added support for Cortex-A75 and Cortex-A55 processors.
Both Cortex-A75 and Cortex-A55 processors use the ARM DynamIQ Shared Unit Both Cortex-A75 and Cortex-A55 processors use the Arm DynamIQ Shared Unit
(DSU). The power-down and power-up sequences are therefore mostly managed in (DSU). The power-down and power-up sequences are therefore mostly managed in
hardware, reducing complexity of the software operations. hardware, reducing complexity of the software operations.
- Introduced ARM GIC-600 driver. - Introduced Arm GIC-600 driver.
ARM GIC-600 IP complies with ARM GICv3 architecture. For FVP platforms, the Arm GIC-600 IP complies with Arm GICv3 architecture. For FVP platforms, the
GIC-600 driver is chosen when FVP_USE_GIC_DRIVER is set to FVP_GIC600. GIC-600 driver is chosen when FVP_USE_GIC_DRIVER is set to FVP_GIC600.
- Updated GICv3 support: - Updated GICv3 support:
@ -43,16 +43,16 @@ New features
- GIC driver data is flushed by the primary CPU so that secondary CPU do - GIC driver data is flushed by the primary CPU so that secondary CPU do
not read stale GIC data. not read stale GIC data.
- Added support for ARM System Control and Management Interface v1.0 (SCMI). - Added support for Arm System Control and Management Interface v1.0 (SCMI).
The SCMI driver implements the power domain management and system power The SCMI driver implements the power domain management and system power
management protocol of the SCMI specification (ARM DEN 0056ASCMI) for management protocol of the SCMI specification (Arm DEN 0056ASCMI) for
communicating with any compliant power controller. communicating with any compliant power controller.
Support is added for the Juno platform. The driver can be found in the Support is added for the Juno platform. The driver can be found in the
plat/arm/css/drivers folder. plat/arm/css/drivers folder.
- Added support to enable pre-integration of TBB with the ARM TrustZone - Added support to enable pre-integration of TBB with the Arm TrustZone
CryptoCell product, to take advantage of its hardware Root of Trust and CryptoCell product, to take advantage of its hardware Root of Trust and
crypto acceleration services. crypto acceleration services.
@ -84,12 +84,12 @@ New features
- Fixed integer overflow which addressed TFV-1: Malformed Firmware Update - Fixed integer overflow which addressed TFV-1: Malformed Firmware Update
SMC can result in copy of unexpectedly large data into secure memory. SMC can result in copy of unexpectedly large data into secure memory.
- Introduced support for ARM Compiler 6 and LLVM (clang). - Introduced support for Arm Compiler 6 and LLVM (clang).
ARM TF can now also be built with the ARM Compiler 6 or the clang compilers. TF-A can now also be built with the Arm Compiler 6 or the clang compilers.
The assembler and linker must be provided by the GNU toolchain. The assembler and linker must be provided by the GNU toolchain.
Tested with ARM CC 6.7 and clang 3.9.x and 4.0.x. Tested with Arm CC 6.7 and clang 3.9.x and 4.0.x.
- Memory footprint improvements: - Memory footprint improvements:
@ -103,30 +103,29 @@ New features
additional logging options are supported via an optional platform define additional logging options are supported via an optional platform define
`PLAT_LOG_LEVEL_ASSERT`, which controls how verbose the assert output is. `PLAT_LOG_LEVEL_ASSERT`, which controls how verbose the assert output is.
- Enhancements to Trusted Firmware support when running in AArch32 execution - Enhancements to TF-A support when running in AArch32 execution state:
state:
- Support booting SP_MIN and BL33 in AArch32 execution mode on Juno. Due to - Support booting SP_MIN and BL33 in AArch32 execution mode on Juno. Due to
hardware limitations, BL1 and BL2 boot in AArch64 state and there is hardware limitations, BL1 and BL2 boot in AArch64 state and there is
additional trampoline code to warm reset into SP_MIN in AArch32 execution additional trampoline code to warm reset into SP_MIN in AArch32 execution
state. state.
- Added support for ARM Cortex-A53/57/72 MPCore processors including the - Added support for Arm Cortex-A53/57/72 MPCore processors including the
errata workarounds that are already implemented for AArch64 execution errata workarounds that are already implemented for AArch64 execution
state. state.
- For FVP platforms, added AArch32 Trusted Board Boot support, including the - For FVP platforms, added AArch32 Trusted Board Boot support, including the
Firmware Update feature. Firmware Update feature.
- Introduced ARM SiP service for use by ARM standard platforms. - Introduced Arm SiP service for use by Arm standard platforms.
- Added new ARM SiP Service SMCs to enable the Non-secure world to read PMF - Added new Arm SiP Service SMCs to enable the Non-secure world to read PMF
timestamps. timestamps.
Added PMF instrumentation points in ARM TF in order to quantify the Added PMF instrumentation points in TF-A in order to quantify the
overall time spent in the PSCI software implementation. overall time spent in the PSCI software implementation.
- Added new ARM SiP service SMC to switch execution state. - Added new Arm SiP service SMC to switch execution state.
This allows the lower exception level to change its execution state from This allows the lower exception level to change its execution state from
AArch64 to AArch32, or vice verse, via a request to EL3. AArch64 to AArch32, or vice verse, via a request to EL3.
@ -172,7 +171,7 @@ New features
detection. For increased effectiveness of protection platforms must provide detection. For increased effectiveness of protection platforms must provide
an implementation that returns a random value. an implementation that returns a random value.
- Enhanced support for ARM platforms: - Enhanced support for Arm platforms:
- Added support for multi-threading CPUs, indicated by `MT` field in MPDIR. - Added support for multi-threading CPUs, indicated by `MT` field in MPDIR.
A new build flag `ARM_PLAT_MT` is added, and when enabled, the functions A new build flag `ARM_PLAT_MT` is added, and when enabled, the functions
@ -183,13 +182,13 @@ New features
enabled, returning the Processing Element count within the physical CPU enabled, returning the Processing Element count within the physical CPU
corresponding to `mpidr`. corresponding to `mpidr`.
- The ARM platforms migrated to use version 2 of the translation tables. - The Arm platforms migrated to use version 2 of the translation tables.
- Introduced a new ARM platform layer API `plat_arm_psci_override_pm_ops` - Introduced a new Arm platform layer API `plat_arm_psci_override_pm_ops`
which allows ARM platforms to modify `plat_arm_psci_pm_ops` and therefore which allows Arm platforms to modify `plat_arm_psci_pm_ops` and therefore
dynamically define PSCI capability. dynamically define PSCI capability.
- The ARM platforms migrated to use IMAGE_LOAD_V2 by default. - The Arm platforms migrated to use IMAGE_LOAD_V2 by default.
- Enhanced reporting of errata workaround status with the following policy: - Enhanced reporting of errata workaround status with the following policy:
@ -206,15 +205,15 @@ New features
missing. missing.
- Added build options ARM_ARCH_MAJOR and ARM_ARM_MINOR to choose the - Added build options ARM_ARCH_MAJOR and ARM_ARM_MINOR to choose the
architecture version to target ARM TF. architecture version to target TF-A.
- Updated the spin lock implementation to use the more efficient CAS (Compare - Updated the spin lock implementation to use the more efficient CAS (Compare
And Swap) instruction when available. This instruction was introduced in And Swap) instruction when available. This instruction was introduced in
ARMv8.1-A. Armv8.1-A.
- Applied errata workaround for ARM Cortex-A53: 855873. - Applied errata workaround for Arm Cortex-A53: 855873.
- Applied errata workaround for ARM-Cortex-A57: 813419. - Applied errata workaround for Arm-Cortex-A57: 813419.
- Enabled all A53 and A57 errata workarounds for Juno, both in AArch64 and - Enabled all A53 and A57 errata workarounds for Juno, both in AArch64 and
AArch32 execution states. AArch32 execution states.
@ -248,7 +247,7 @@ New features
- Essential control registers are fully initialised on EL3 start-up, when - Essential control registers are fully initialised on EL3 start-up, when
initialising the non-secure and secure context structures and when initialising the non-secure and secure context structures and when
preparing to leave EL3 for a lower EL. This gives better alignement with preparing to leave EL3 for a lower EL. This gives better alignement with
the ARM ARM which states that software must initialise RES0 and RES1 the Arm ARM which states that software must initialise RES0 and RES1
fields with 0 / 1. fields with 0 / 1.
- Enhanced PSCI support: - Enhanced PSCI support:
@ -268,12 +267,12 @@ New features
Issues resolved since last release Issues resolved since last release
---------------------------------- ----------------------------------
- ARM TF can be built with the latest mbed TLS version (v2.4.2). The earlier - TF-A can be built with the latest mbed TLS version (v2.4.2). The earlier
version 2.3.0 cannot be used due to build warnings that the ARM TF build version 2.3.0 cannot be used due to build warnings that the TF-A build
system interprets as errors. system interprets as errors.
- TBBR, including the Firmware Update feature is now supported on FVP - TBBR, including the Firmware Update feature is now supported on FVP
platforms when running Trusted Firmware in AArch32 state. platforms when running TF-A in AArch32 state.
- The version of the AEMv8 Base FVP used in this release has resolved the issue - The version of the AEMv8 Base FVP used in this release has resolved the issue
of the model executing a reset instead of terminating in response to a of the model executing a reset instead of terminating in response to a
@ -282,7 +281,7 @@ Issues resolved since last release
Known Issues Known Issues
------------ ------------
- Building TF with compiler optimisations disabled (-O0) fails. - Building TF-A with compiler optimisations disabled (-O0) fails.
- Trusted Board Boot currently does not work on Juno when running Trusted - Trusted Board Boot currently does not work on Juno when running Trusted
Firmware in AArch32 execution state due to error when loading the sp_min to Firmware in AArch32 execution state due to error when loading the sp_min to
@ -294,14 +293,14 @@ Known Issues
platform, please use GCC compiler version of at least 5.0. See `PR#1002`_ for platform, please use GCC compiler version of at least 5.0. See `PR#1002`_ for
more details. more details.
ARM Trusted Firmware - version 1.3 Trusted Firmware-A - version 1.3
================================== ================================
New features New features
------------ ------------
- Added support for running Trusted Firmware in AArch32 execution state. - Added support for running TF-A in AArch32 execution state.
The PSCI library has been refactored to allow integration with **EL3 Runtime The PSCI library has been refactored to allow integration with **EL3 Runtime
Software**. This is software that is executing at the highest secure Software**. This is software that is executing at the highest secure
@ -315,11 +314,11 @@ New features
Booting to the BL1/BL2 images as well as booting straight to the Secure Booting to the BL1/BL2 images as well as booting straight to the Secure
Payload is supported. Payload is supported.
- Improvements to the initialization framework for the PSCI service and ARM - Improvements to the initialization framework for the PSCI service and Arm
Standard Services in general. Standard Services in general.
The PSCI service is now initialized as part of ARM Standard Service The PSCI service is now initialized as part of Arm Standard Service
initialization. This consolidates the initializations of any ARM Standard initialization. This consolidates the initializations of any Arm Standard
Service that may be added in the future. Service that may be added in the future.
A new function ``get_arm_std_svc_args()`` is introduced to get arguments A new function ``get_arm_std_svc_args()`` is introduced to get arguments
@ -337,7 +336,7 @@ New features
(BL31, BL32, etc). The new mechanism is data-driven by a list of image (BL31, BL32, etc). The new mechanism is data-driven by a list of image
descriptors provided by the platform code. descriptors provided by the platform code.
ARM platforms have been updated to support the new loading mechanism. Arm platforms have been updated to support the new loading mechanism.
The new mechanism is enabled by a build flag (``LOAD_IMAGE_V2``) which is The new mechanism is enabled by a build flag (``LOAD_IMAGE_V2``) which is
currently off by default for the AArch64 build. currently off by default for the AArch64 build.
@ -345,7 +344,7 @@ New features
**Note** ``TRUSTED_BOARD_BOOT`` is currently not supported when **Note** ``TRUSTED_BOARD_BOOT`` is currently not supported when
``LOAD_IMAGE_V2`` is enabled. ``LOAD_IMAGE_V2`` is enabled.
- Updated requirements for making contributions to ARM TF. - Updated requirements for making contributions to TF-A.
Commits now must have a 'Signed-off-by:' field to certify that the Commits now must have a 'Signed-off-by:' field to certify that the
contribution has been made under the terms of the contribution has been made under the terms of the
@ -365,13 +364,13 @@ New features
- Updated PSCI support: - Updated PSCI support:
- Added support for PSCI NODE\_HW\_STATE API for ARM platforms. - Added support for PSCI NODE\_HW\_STATE API for Arm platforms.
- New optional platform hook, ``pwr_domain_pwr_down_wfi()``, in - New optional platform hook, ``pwr_domain_pwr_down_wfi()``, in
``plat_psci_ops`` to enable platforms to perform platform-specific actions ``plat_psci_ops`` to enable platforms to perform platform-specific actions
needed to enter powerdown, including the 'wfi' invocation. needed to enter powerdown, including the 'wfi' invocation.
- PSCI STAT residency and count functions have been added on ARM platforms - PSCI STAT residency and count functions have been added on Arm platforms
by using PMF. by using PMF.
- Enhancements to the translation table library: - Enhancements to the translation table library:
@ -420,13 +419,13 @@ New features
convention as specified by TBBR and already used in cert\_create tool. convention as specified by TBBR and already used in cert\_create tool.
- Refactored the TZC-400 driver to also support memory controllers that - Refactored the TZC-400 driver to also support memory controllers that
integrate TZC functionality, for example ARM CoreLink DMC-500. Also added integrate TZC functionality, for example Arm CoreLink DMC-500. Also added
DMC-500 specific support. DMC-500 specific support.
- Implemented generic delay timer based on the system generic counter and - Implemented generic delay timer based on the system generic counter and
migrated all platforms to use it. migrated all platforms to use it.
- Enhanced support for ARM platforms: - Enhanced support for Arm platforms:
- Updated image loading support to make SCP images (SCP\_BL2 and SCP\_BL2U) - Updated image loading support to make SCP images (SCP\_BL2 and SCP\_BL2U)
optional. optional.
@ -441,7 +440,7 @@ New features
the default secure SRAM. the default secure SRAM.
- Added support to use a System Security Control (SSC) Registers Unit - Added support to use a System Security Control (SSC) Registers Unit
enabling ARM TF to be compiled to support multiple ARM platforms and enabling TF-A to be compiled to support multiple Arm platforms and
then select one at runtime. then select one at runtime.
- Restricted mapping of Trusted ROM in BL1 to what is actually needed by - Restricted mapping of Trusted ROM in BL1 to what is actually needed by
@ -455,26 +454,26 @@ New features
- Added support for Mediatek MT6795 platform. - Added support for Mediatek MT6795 platform.
- Added support for QEMU virtualization ARMv8-A target. - Added support for QEMU virtualization Armv8-A target.
- Added support for Rockchip RK3368 and RK3399 platforms. - Added support for Rockchip RK3368 and RK3399 platforms.
- Added support for Xilinx Zynq UltraScale+ MPSoC platform. - Added support for Xilinx Zynq UltraScale+ MPSoC platform.
- Added support for ARM Cortex-A73 MPCore Processor. - Added support for Arm Cortex-A73 MPCore Processor.
- Added support for ARM Cortex-A72 processor. - Added support for Arm Cortex-A72 processor.
- Added support for ARM Cortex-A35 processor. - Added support for Arm Cortex-A35 processor.
- Added support for ARM Cortex-A32 MPCore Processor. - Added support for Arm Cortex-A32 MPCore Processor.
- Enabled preloaded BL33 alternative boot flow, in which BL2 does not load - Enabled preloaded BL33 alternative boot flow, in which BL2 does not load
BL33 from non-volatile storage and BL31 hands execution over to a preloaded BL33 from non-volatile storage and BL31 hands execution over to a preloaded
BL33. The User Guide has been updated with an example of how to use this BL33. The User Guide has been updated with an example of how to use this
option with a bootwrapped kernel. option with a bootwrapped kernel.
- Added support to build ARM TF on a Windows-based host machine. - Added support to build TF-A on a Windows-based host machine.
- Updated Trusted Board Boot prototype implementation: - Updated Trusted Board Boot prototype implementation:
@ -493,7 +492,7 @@ New features
- Enabled G1S or G0 interrupts to be configured independently. - Enabled G1S or G0 interrupts to be configured independently.
- Changed FVP default interrupt driver to be the GICv3-only driver. - Changed FVP default interrupt driver to be the GICv3-only driver.
**Note** the default build of Trusted Firmware will not be able to boot **Note** the default build of TF-A will not be able to boot
Linux kernel with GICv2 FDT blob. Linux kernel with GICv2 FDT blob.
- Enabled wake-up from CPU\_SUSPEND to stand-by by temporarily re-routing - Enabled wake-up from CPU\_SUSPEND to stand-by by temporarily re-routing
@ -510,26 +509,25 @@ Known issues
the PSCI ``SYSTEM_OFF`` API. This issue will be fixed in a future version of the PSCI ``SYSTEM_OFF`` API. This issue will be fixed in a future version of
the model. the model.
- Building TF with compiler optimisations disabled (``-O0``) fails. - Building TF-A with compiler optimisations disabled (``-O0``) fails.
- ARM TF cannot be built with mbed TLS version v2.3.0 due to build warnings - TF-A cannot be built with mbed TLS version v2.3.0 due to build warnings
that the ARM TF build system interprets as errors. that the TF-A build system interprets as errors.
- TBBR is not currently supported when running Trusted Firmware in AArch32 - TBBR is not currently supported when running TF-A in AArch32 state.
state.
ARM Trusted Firmware - version 1.2 Trusted Firmware-A - version 1.2
================================== ================================
New features New features
------------ ------------
- The Trusted Board Boot implementation on ARM platforms now conforms to the - The Trusted Board Boot implementation on Arm platforms now conforms to the
mandatory requirements of the TBBR specification. mandatory requirements of the TBBR specification.
In particular, the boot process is now guarded by a Trusted Watchdog, which In particular, the boot process is now guarded by a Trusted Watchdog, which
will reset the system in case of an authentication or loading error. On ARM will reset the system in case of an authentication or loading error. On Arm
platforms, a secure instance of ARM SP805 is used as the Trusted Watchdog. platforms, a secure instance of Arm SP805 is used as the Trusted Watchdog.
Also, a firmware update process has been implemented. It enables Also, a firmware update process has been implemented. It enables
authenticated firmware to update firmware images from external interfaces to authenticated firmware to update firmware images from external interfaces to
@ -563,44 +561,44 @@ New features
out, reducing the memory footprint of BL1 and BL2 by approximately out, reducing the memory footprint of BL1 and BL2 by approximately
6 KB. 6 KB.
- On ARM development platforms, each BL stage now individually defines - On Arm development platforms, each BL stage now individually defines
the number of regions that it needs to map in the MMU. the number of regions that it needs to map in the MMU.
- Added the following new design documents: - Added the following new design documents:
- `Authentication framework`_ - `Authentication framework`_
- `Firmware Update`_ - `Firmware Update`_
- `TF Reset Design`_ - `TF-A Reset Design`_
- `Power Domain Topology Design`_ - `Power Domain Topology Design`_
- Applied the new image terminology to the code base and documentation, as - Applied the new image terminology to the code base and documentation, as
described on the `TF wiki on GitHub`_. described on the `TF-A wiki on GitHub`_.
- The build system has been reworked to improve readability and facilitate - The build system has been reworked to improve readability and facilitate
adding future extensions. adding future extensions.
- On ARM standard platforms, BL31 uses the boot console during cold boot - On Arm standard platforms, BL31 uses the boot console during cold boot
but switches to the runtime console for any later logs at runtime. The TSP but switches to the runtime console for any later logs at runtime. The TSP
uses the runtime console for all output. uses the runtime console for all output.
- Implemented a basic NOR flash driver for ARM platforms. It programs the - Implemented a basic NOR flash driver for Arm platforms. It programs the
device using CFI (Common Flash Interface) standard commands. device using CFI (Common Flash Interface) standard commands.
- Implemented support for booting EL3 payloads on ARM platforms, which - Implemented support for booting EL3 payloads on Arm platforms, which
reduces the complexity of developing EL3 baremetal code by doing essential reduces the complexity of developing EL3 baremetal code by doing essential
baremetal initialization. baremetal initialization.
- Provided separate drivers for GICv3 and GICv2. These expect the entire - Provided separate drivers for GICv3 and GICv2. These expect the entire
software stack to use either GICv2 or GICv3; hybrid GIC software systems software stack to use either GICv2 or GICv3; hybrid GIC software systems
are no longer supported and the legacy ARM GIC driver has been deprecated. are no longer supported and the legacy Arm GIC driver has been deprecated.
- Added support for Juno r1 and r2. A single set of Juno TF binaries can run - Added support for Juno r1 and r2. A single set of Juno TF-A binaries can run
on Juno r0, r1 and r2 boards. Note that this TF version depends on a Linaro on Juno r0, r1 and r2 boards. Note that this TF-A version depends on a Linaro
release that does *not* contain Juno r2 support. release that does *not* contain Juno r2 support.
- Added support for MediaTek mt8173 platform. - Added support for MediaTek mt8173 platform.
- Implemented a generic driver for ARM CCN IP. - Implemented a generic driver for Arm CCN IP.
- Major rework of the PSCI implementation. - Major rework of the PSCI implementation.
@ -612,7 +610,7 @@ New features
- Better alignment with version 1.0 of the PSCI specification. - Better alignment with version 1.0 of the PSCI specification.
- Added support for the SYSTEM\_SUSPEND PSCI API on ARM platforms. When invoked - Added support for the SYSTEM\_SUSPEND PSCI API on Arm platforms. When invoked
on the last running core on a supported platform, this puts the system on the last running core on a supported platform, this puts the system
into a low power mode with memory retention. into a low power mode with memory retention.
@ -625,17 +623,17 @@ New features
- Added support for NVidia Tegra T210 and T132 SoCs. - Added support for NVidia Tegra T210 and T132 SoCs.
- Reorganised ARM platforms ports to greatly improve code shareability and - Reorganised Arm platforms ports to greatly improve code shareability and
facilitate the reuse of some of this code by other platforms. facilitate the reuse of some of this code by other platforms.
- Added support for ARM Cortex-A72 processor in the CPU specific framework. - Added support for Arm Cortex-A72 processor in the CPU specific framework.
- Provided better error handling. Platform ports can now define their own - Provided better error handling. Platform ports can now define their own
error handling, for example to perform platform specific bookkeeping or error handling, for example to perform platform specific bookkeeping or
post-error actions. post-error actions.
- Implemented a unified driver for ARM Cache Coherent Interconnects used for - Implemented a unified driver for Arm Cache Coherent Interconnects used for
both CCI-400 & CCI-500 IPs. ARM platforms ports have been migrated to this both CCI-400 & CCI-500 IPs. Arm platforms ports have been migrated to this
common driver. The standalone CCI-400 driver has been deprecated. common driver. The standalone CCI-400 driver has been deprecated.
Issues resolved since last release Issues resolved since last release
@ -668,10 +666,10 @@ Known issues
clarity and completeness. In particular, the design documentation is clarity and completeness. In particular, the design documentation is
incomplete for PSCI, the TSP(D) and the Juno platform. incomplete for PSCI, the TSP(D) and the Juno platform.
- Building TF with compiler optimisations disabled (``-O0``) fails. - Building TF-A with compiler optimisations disabled (``-O0``) fails.
ARM Trusted Firmware - version 1.1 Trusted Firmware-A - version 1.1
================================== ================================
New features New features
------------ ------------
@ -719,10 +717,10 @@ New features
applicable). Also, during a PSCI ``MIGRATE`` call, the SPD hook to migrate applicable). Also, during a PSCI ``MIGRATE`` call, the SPD hook to migrate
the Trusted OS is invoked. the Trusted OS is invoked.
- It is now possible to build Trusted Firmware without marking at least an - It is now possible to build TF-A without marking at least an extra page of
extra page of memory as coherent. The build flag ``USE_COHERENT_MEM`` can be memory as coherent. The build flag ``USE_COHERENT_MEM`` can be used to
used to choose between the two implementations. This has been made possible choose between the two implementations. This has been made possible through
through these changes. these changes.
- An implementation of Bakery locks, where the locks are not allocated in - An implementation of Bakery locks, where the locks are not allocated in
coherent memory has been added. coherent memory has been added.
@ -774,8 +772,7 @@ New features
create mappings only for areas in the memory map that it needs. create mappings only for areas in the memory map that it needs.
- A Secure Payload Dispatcher (OPTEED) for the OP-TEE Trusted OS has been - A Secure Payload Dispatcher (OPTEED) for the OP-TEE Trusted OS has been
added. Details of using it with ARM Trusted Firmware can be found in added. Details of using it with TF-A can be found in `OP-TEE Dispatcher`_
`OP-TEE Dispatcher`_
Issues resolved since last release Issues resolved since last release
---------------------------------- ----------------------------------
@ -789,7 +786,7 @@ Issues resolved since last release
- The top 16MB of the 2GB DDR-DRAM memory at 0x80000000 is configured - The top 16MB of the 2GB DDR-DRAM memory at 0x80000000 is configured
using the TZC-400 controller to be accessible only to the secure world. using the TZC-400 controller to be accessible only to the secure world.
- The ARM GIC driver is used to configure the GIC-400 instead of using a - The Arm GIC driver is used to configure the GIC-400 instead of using a
GIC driver private to the Juno port. GIC driver private to the Juno port.
- PSCI ``CPU_SUSPEND`` calls that target a standby state are now supported. - PSCI ``CPU_SUSPEND`` calls that target a standby state are now supported.
@ -823,7 +820,7 @@ Known issues
the model. the model.
- GICv3 support is experimental. There are known issues with GICv3 - GICv3 support is experimental. There are known issues with GICv3
initialization in the ARM Trusted Firmware. initialization in the TF-A.
- While this version greatly reduces the on-chip RAM requirements, there are - While this version greatly reduces the on-chip RAM requirements, there are
further RAM usage enhancements that could be made. further RAM usage enhancements that could be made.
@ -833,8 +830,8 @@ Known issues
- The Juno-specific firmware design documentation is incomplete. - The Juno-specific firmware design documentation is incomplete.
ARM Trusted Firmware - version 1.0 Trusted Firmware-A - version 1.0
================================== ================================
New features New features
------------ ------------
@ -970,14 +967,14 @@ Issues resolved since last release
- CPU idle now works on the publicized version of the Foundation FVP. - CPU idle now works on the publicized version of the Foundation FVP.
- All known issues relating to the compiler version used have now been - All known issues relating to the compiler version used have now been
resolved. This TF version uses Linaro toolchain 14.07 (based on GCC 4.9). resolved. This TF-A version uses Linaro toolchain 14.07 (based on GCC 4.9).
Known issues Known issues
------------ ------------
- GICv3 support is experimental. The Linux kernel patches to support this are - GICv3 support is experimental. The Linux kernel patches to support this are
not widely available. There are known issues with GICv3 initialization in not widely available. There are known issues with GICv3 initialization in
the ARM Trusted Firmware. the TF-A.
- While this version greatly reduces the on-chip RAM requirements, there are - While this version greatly reduces the on-chip RAM requirements, there are
further RAM usage enhancements that could be made. further RAM usage enhancements that could be made.
@ -1013,8 +1010,8 @@ Known issues
A similar change can be made to the other Cortex-A57-A53 Base FVP variants. A similar change can be made to the other Cortex-A57-A53 Base FVP variants.
ARM Trusted Firmware - version 0.4 Trusted Firmware-A - version 0.4
================================== ================================
New features New features
------------ ------------
@ -1110,41 +1107,41 @@ Issues resolved since last release
14.04) now correctly reports progress in the console. 14.04) now correctly reports progress in the console.
- Improved the Makefile structure to make it easier to separate out parts of - Improved the Makefile structure to make it easier to separate out parts of
the Trusted Firmware for re-use in platform ports. Also, improved target the TF-A for re-use in platform ports. Also, improved target dependency
dependency checking. checking.
Known issues Known issues
------------ ------------
- GICv3 support is experimental. The Linux kernel patches to support this are - GICv3 support is experimental. The Linux kernel patches to support this are
not widely available. There are known issues with GICv3 initialization in not widely available. There are known issues with GICv3 initialization in
the ARM Trusted Firmware. the TF-A.
- Dynamic image loading is not available yet. The current image loader - Dynamic image loading is not available yet. The current image loader
implementation (used to load BL2 and all subsequent images) has some implementation (used to load BL2 and all subsequent images) has some
limitations. Changing BL2 or BL3-1 load addresses in certain ways can lead limitations. Changing BL2 or BL3-1 load addresses in certain ways can lead
to loading errors, even if the images should theoretically fit in memory. to loading errors, even if the images should theoretically fit in memory.
- The ARM Trusted Firmware still uses too much on-chip Trusted SRAM. A number - TF-A still uses too much on-chip Trusted SRAM. A number of RAM usage
of RAM usage enhancements have been identified to rectify this situation. enhancements have been identified to rectify this situation.
- CPU idle does not work on the advertised version of the Foundation FVP. - CPU idle does not work on the advertised version of the Foundation FVP.
Some FVP fixes are required that are not available externally at the time Some FVP fixes are required that are not available externally at the time
of writing. This can be worked around by disabling CPU idle in the Linux of writing. This can be worked around by disabling CPU idle in the Linux
kernel. kernel.
- Various bugs in ARM Trusted Firmware, UEFI and the Linux kernel have been - Various bugs in TF-A, UEFI and the Linux kernel have been observed when
observed when using Linaro toolchain versions later than 13.11. Although using Linaro toolchain versions later than 13.11. Although most of these
most of these have been fixed, some remain at the time of writing. These have been fixed, some remain at the time of writing. These mainly seem to
mainly seem to relate to a subtle change in the way the compiler converts relate to a subtle change in the way the compiler converts between 64-bit
between 64-bit and 32-bit values (e.g. during casting operations), which and 32-bit values (e.g. during casting operations), which reveals
reveals previously hidden bugs in client code. previously hidden bugs in client code.
- The firmware design documentation for the Test Secure-EL1 Payload (TSP) and - The firmware design documentation for the Test Secure-EL1 Payload (TSP) and
its dispatcher (TSPD) is incomplete. Similarly for the PSCI section. its dispatcher (TSPD) is incomplete. Similarly for the PSCI section.
ARM Trusted Firmware - version 0.3 Trusted Firmware-A - version 0.3
================================== ================================
New features New features
------------ ------------
@ -1170,9 +1167,9 @@ New features
- The PSCI AFFINITY\_INFO api has undergone limited testing on the Base FVPs to - The PSCI AFFINITY\_INFO api has undergone limited testing on the Base FVPs to
allow experimental use. allow experimental use.
- Required C library and runtime header files are now included locally in ARM - Required C library and runtime header files are now included locally in
Trusted Firmware instead of depending on the toolchain standard include TF-A instead of depending on the toolchain standard include paths. The
paths. The local implementation has been cleaned up and reduced in scope. local implementation has been cleaned up and reduced in scope.
- Added I/O abstraction framework, primarily to allow generic code to load - Added I/O abstraction framework, primarily to allow generic code to load
images in a platform-independent way. The existing image loading code has images in a platform-independent way. The existing image loading code has
@ -1232,28 +1229,27 @@ Issues resolved since last release
- PSCI API calls ``AFFINITY_INFO`` & ``PSCI_VERSION`` have now been tested (to - PSCI API calls ``AFFINITY_INFO`` & ``PSCI_VERSION`` have now been tested (to
a limited extent). a limited extent).
- The ARM Trusted Firmware build artifacts are now placed in the ``./build`` - The TF-A build artifacts are now placed in the ``./build`` directory and
directory and sub-directories instead of being placed in the root of the sub-directories instead of being placed in the root of the project.
project.
- The ARM Trusted Firmware is now free from build warnings. Build warnings - TF-A is now free from build warnings. Build warnings are now treated as
are now treated as errors. errors.
- The ARM Trusted Firmware now provides C library support locally within the - TF-A now provides C library support locally within the project to maintain
project to maintain compatibility between toolchains/systems. compatibility between toolchains/systems.
- The PSCI locking code has been reworked so it no longer takes locks in an - The PSCI locking code has been reworked so it no longer takes locks in an
incorrect sequence. incorrect sequence.
- The RAM-disk method of loading a Linux file-system has been confirmed to - The RAM-disk method of loading a Linux file-system has been confirmed to
work with the ARM Trusted Firmware and Linux kernel version (based on work with the TF-A and Linux kernel version (based on version 3.13) used
version 3.13) used in this release, for both Foundation and Base FVPs. in this release, for both Foundation and Base FVPs.
Known issues Known issues
------------ ------------
The following is a list of issues which are expected to be fixed in the future The following is a list of issues which are expected to be fixed in the future
releases of the ARM Trusted Firmware. releases of TF-A.
- The TrustZone Address Space Controller (TZC-400) is not being programmed - The TrustZone Address Space Controller (TZC-400) is not being programmed
yet. Use of model parameter ``-C bp.secure_memory=1`` is not supported. yet. Use of model parameter ``-C bp.secure_memory=1`` is not supported.
@ -1262,28 +1258,28 @@ releases of the ARM Trusted Firmware.
- GICv3 support is experimental. The Linux kernel patches to support this are - GICv3 support is experimental. The Linux kernel patches to support this are
not widely available. There are known issues with GICv3 initialization in not widely available. There are known issues with GICv3 initialization in
the ARM Trusted Firmware. TF-A.
- Dynamic image loading is not available yet. The current image loader - Dynamic image loading is not available yet. The current image loader
implementation (used to load BL2 and all subsequent images) has some implementation (used to load BL2 and all subsequent images) has some
limitations. Changing BL2 or BL3-1 load addresses in certain ways can lead limitations. Changing BL2 or BL3-1 load addresses in certain ways can lead
to loading errors, even if the images should theoretically fit in memory. to loading errors, even if the images should theoretically fit in memory.
- The ARM Trusted Firmware uses too much on-chip Trusted SRAM. Currently the - TF-A uses too much on-chip Trusted SRAM. Currently the Test Secure-EL1
Test Secure-EL1 Payload (BL3-2) executes in Trusted DRAM since there is not Payload (BL3-2) executes in Trusted DRAM since there is not enough SRAM.
enough SRAM. A number of RAM usage enhancements have been identified to A number of RAM usage enhancements have been identified to rectify this
rectify this situation. situation.
- CPU idle does not work on the advertised version of the Foundation FVP. - CPU idle does not work on the advertised version of the Foundation FVP.
Some FVP fixes are required that are not available externally at the time Some FVP fixes are required that are not available externally at the time
of writing. of writing.
- Various bugs in ARM Trusted Firmware, UEFI and the Linux kernel have been - Various bugs in TF-A, UEFI and the Linux kernel have been observed when
observed when using Linaro toolchain versions later than 13.11. Although using Linaro toolchain versions later than 13.11. Although most of these
most of these have been fixed, some remain at the time of writing. These have been fixed, some remain at the time of writing. These mainly seem to
mainly seem to relate to a subtle change in the way the compiler converts relate to a subtle change in the way the compiler converts between 64-bit
between 64-bit and 32-bit values (e.g. during casting operations), which and 32-bit values (e.g. during casting operations), which reveals
reveals previously hidden bugs in client code. previously hidden bugs in client code.
- The tested filesystem used for this release (Linaro AArch64 OpenEmbedded - The tested filesystem used for this release (Linaro AArch64 OpenEmbedded
14.01) does not report progress correctly in the console. It only seems to 14.01) does not report progress correctly in the console. It only seems to
@ -1292,15 +1288,14 @@ releases of the ARM Trusted Firmware.
exhibit the problem. exhibit the problem.
- The Makefile structure doesn't make it easy to separate out parts of the - The Makefile structure doesn't make it easy to separate out parts of the
Trusted Firmware for re-use in platform ports, for example if only BL3-1 is TF-A for re-use in platform ports, for example if only BL3-1 is required in
required in a platform port. Also, dependency checking in the Makefile is a platform port. Also, dependency checking in the Makefile is flawed.
flawed.
- The firmware design documentation for the Test Secure-EL1 Payload (TSP) and - The firmware design documentation for the Test Secure-EL1 Payload (TSP) and
its dispatcher (TSPD) is incomplete. Similarly for the PSCI section. its dispatcher (TSPD) is incomplete. Similarly for the PSCI section.
ARM Trusted Firmware - version 0.2 Trusted Firmware-A - version 0.2
================================== ================================
New features New features
------------ ------------
@ -1320,7 +1315,7 @@ Known issues
------------ ------------
The following is a list of issues which are expected to be fixed in the future The following is a list of issues which are expected to be fixed in the future
releases of the ARM Trusted Firmware. releases of TF-A.
- The TrustZone Address Space Controller (TZC-400) is not being programmed - The TrustZone Address Space Controller (TZC-400) is not being programmed
yet. Use of model parameter ``-C bp.secure_memory=1`` is not supported. yet. Use of model parameter ``-C bp.secure_memory=1`` is not supported.
@ -1330,7 +1325,7 @@ releases of the ARM Trusted Firmware.
- GICv3 support is experimental. The Linux kernel patches to support this are - GICv3 support is experimental. The Linux kernel patches to support this are
not widely available. There are known issues with GICv3 initialization in not widely available. There are known issues with GICv3 initialization in
the ARM Trusted Firmware. TF-A.
- Dynamic image loading is not available yet. The current image loader - Dynamic image loading is not available yet. The current image loader
implementation (used to load BL2 and all subsequent images) has some implementation (used to load BL2 and all subsequent images) has some
@ -1340,42 +1335,40 @@ 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
been tested. not been tested.
- The ARM Trusted Firmware make files result in all build artifacts being - The TF-A make files result in all build artifacts being placed in the root
placed in the root of the project. These should be placed in appropriate of the project. These should be placed in appropriate sub-directories.
sub-directories.
- The compilation of ARM Trusted Firmware is not free from compilation - The compilation of TF-A is not free from compilation warnings. Some of these
warnings. Some of these warnings have not been investigated yet so they warnings have not been investigated yet so they could mask real bugs.
could mask real bugs.
- The ARM Trusted Firmware currently uses toolchain/system include files like - TF-A currently uses toolchain/system include files like stdio.h. It should
stdio.h. It should provide versions of these within the project to maintain provide versions of these within the project to maintain compatibility
compatibility between toolchains/systems. between toolchains/systems.
- The PSCI code takes some locks in an incorrect sequence. This may cause - The PSCI code takes some locks in an incorrect sequence. This may cause
problems with suspend and hotplug in certain conditions. problems with suspend and hotplug in certain conditions.
- The Linux kernel used in this release is based on version 3.12-rc4. Using - The Linux kernel used in this release is based on version 3.12-rc4. Using
this kernel with the ARM Trusted Firmware fails to start the file-system as this kernel with the TF-A fails to start the file-system as a RAM-disk. It
a RAM-disk. It fails to execute user-space ``init`` from the RAM-disk. As an fails to execute user-space ``init`` from the RAM-disk. As an alternative,
alternative, the VirtioBlock mechanism can be used to provide a file-system the VirtioBlock mechanism can be used to provide a file-system to the
to the kernel. kernel.
-------------- --------------
*Copyright (c) 2013-2016, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2013-2018, Arm Limited and Contributors. All rights reserved.*
.. _PSCI Integration Guide: psci-lib-integration-guide.rst .. _PSCI Integration Guide: psci-lib-integration-guide.rst
.. _Developer Certificate of Origin: ../dco.txt .. _Developer Certificate of Origin: ../dco.txt
.. _Contribution Guide: ../contributing.rst .. _Contribution Guide: ../contributing.rst
.. _Authentication framework: auth-framework.rst .. _Authentication framework: auth-framework.rst
.. _Firmware Update: firmware-update.rst .. _Firmware Update: firmware-update.rst
.. _TF Reset Design: reset-design.rst .. _TF-A Reset Design: reset-design.rst
.. _Power Domain Topology Design: psci-pd-tree.rst .. _Power Domain Topology Design: psci-pd-tree.rst
.. _TF wiki on GitHub: https://github.com/ARM-software/arm-trusted-firmware/wiki/ARM-Trusted-Firmware-Image-Terminology .. _TF-A wiki on GitHub: https://github.com/ARM-software/arm-trusted-firmware/wiki/ARM-Trusted-Firmware-Image-Terminology
.. _Authentication Framework: auth-framework.rst .. _Authentication Framework: auth-framework.rst
.. _OP-TEE Dispatcher: optee-dispatcher.rst .. _OP-TEE Dispatcher: optee-dispatcher.rst
.. _tf-issue#501: https://github.com/ARM-software/tf-issues/issues/501 .. _tf-issue#501: https://github.com/ARM-software/tf-issues/issues/501

19
docs/cpu-specific-build-macros.rst
View file

@ -1,4 +1,4 @@
ARM CPU Specific Build Macros Arm CPU Specific Build Macros
============================= =============================
@ -14,8 +14,8 @@ for a specific CPU on a platform.
Security Vulnerability Workarounds Security Vulnerability Workarounds
---------------------------------- ----------------------------------
ARM Trusted Firmware exports a series of build flags which control which TF-A exports a series of build flags which control which security
security vulnerability workarounds should be applied at runtime. vulnerability workarounds should be applied at runtime.
- ``WORKAROUND_CVE_2017_5715``: Enables the security workaround for - ``WORKAROUND_CVE_2017_5715``: Enables the security workaround for
`CVE-2017-5715`_. Defaults to 1. `CVE-2017-5715`_. Defaults to 1.
@ -23,10 +23,9 @@ security vulnerability workarounds should be applied at runtime.
CPU Errata Workarounds CPU Errata Workarounds
---------------------- ----------------------
ARM Trusted Firmware exports a series of build flags which control the TF-A exports a series of build flags which control the errata workarounds that
errata workarounds that are applied to each CPU by the reset handler. The are applied to each CPU by the reset handler. The errata details can be found
errata details can be found in the CPU specific errata documents published in the CPU specific errata documents published by Arm:
by ARM:
- `Cortex-A53 MPCore Software Developers Errata Notice`_ - `Cortex-A53 MPCore Software Developers Errata Notice`_
- `Cortex-A57 MPCore Software Developers Errata Notice`_ - `Cortex-A57 MPCore Software Developers Errata Notice`_
@ -135,8 +134,8 @@ architecture that can be enabled by the platform as desired.
- ``A53_DISABLE_NON_TEMPORAL_HINT``: This flag disables the cache non-temporal - ``A53_DISABLE_NON_TEMPORAL_HINT``: This flag disables the cache non-temporal
hint. The LDNP/STNP instructions as implemented on Cortex-A53 do not behave hint. The LDNP/STNP instructions as implemented on Cortex-A53 do not behave
in a way most programmers expect, and will most probably result in a in a way most programmers expect, and will most probably result in a
significant speed degradation to any code that employs them. The ARMv8-A significant speed degradation to any code that employs them. The Armv8-A
architecture (see ARM DDI 0487A.h, section D3.4.3) allows cores to ignore architecture (see Arm DDI 0487A.h, section D3.4.3) allows cores to ignore
the non-temporal hint and treat LDNP/STNP as LDP/STP instead. Enabling this the non-temporal hint and treat LDNP/STNP as LDP/STP instead. Enabling this
flag enforces this behaviour. This needs to be enabled only for revisions flag enforces this behaviour. This needs to be enabled only for revisions
<= r0p3 of the CPU and is enabled by default. <= r0p3 of the CPU and is enabled by default.
@ -149,7 +148,7 @@ architecture that can be enabled by the platform as desired.
-------------- --------------
*Copyright (c) 2014-2016, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2014-2018, Arm Limited and Contributors. All rights reserved.*
.. _CVE-2017-5715: http://www.cve.mitre.org/cgi-bin/cvename.cgi?name=2017-5715 .. _CVE-2017-5715: http://www.cve.mitre.org/cgi-bin/cvename.cgi?name=2017-5715
.. _Cortex-A53 MPCore Software Developers Errata Notice: http://infocenter.arm.com/help/topic/com.arm.doc.epm048406/Cortex_A53_MPCore_Software_Developers_Errata_Notice.pdf .. _Cortex-A53 MPCore Software Developers Errata Notice: http://infocenter.arm.com/help/topic/com.arm.doc.epm048406/Cortex_A53_MPCore_Software_Developers_Errata_Notice.pdf

456
docs/firmware-design.rst
View file

@ -1,5 +1,5 @@
ARM Trusted Firmware Design Trusted Firmware-A design
=========================== =========================
.. section-numbering:: .. section-numbering::
@ -7,30 +7,27 @@ ARM Trusted Firmware Design
.. contents:: .. contents::
The ARM Trusted Firmware implements a subset of the Trusted Board Boot Trusted Firmware-A (TF-A) implements a subset of the Trusted Board Boot
Requirements (TBBR) Platform Design Document (PDD) [1]_ for ARM reference Requirements (TBBR) Platform Design Document (PDD) [1]_ for Arm reference
platforms. The TBB sequence starts when the platform is powered on and runs up platforms. The TBB sequence starts when the platform is powered on and runs up
to the stage where it hands-off control to firmware running in the normal to the stage where it hands-off control to firmware running in the normal
world in DRAM. This is the cold boot path. world in DRAM. This is the cold boot path.
The ARM Trusted Firmware also implements the Power State Coordination Interface TF-A also implements the Power State Coordination Interface PDD [2]_ as a
PDD [2]_ as a runtime service. PSCI is the interface from normal world software runtime service. PSCI is the interface from normal world software to firmware
to firmware implementing power management use-cases (for example, secondary CPU implementing power management use-cases (for example, secondary CPU boot,
boot, hotplug and idle). Normal world software can access ARM Trusted Firmware hotplug and idle). Normal world software can access TF-A runtime services via
runtime services via the ARM SMC (Secure Monitor Call) instruction. The SMC the Arm SMC (Secure Monitor Call) instruction. The SMC instruction must be
instruction must be used as mandated by the SMC Calling Convention [3]_. used as mandated by the SMC Calling Convention [3]_.
The ARM Trusted Firmware implements a framework for configuring and managing TF-A implements a framework for configuring and managing interrupts generated
interrupts generated in either security state. The details of the interrupt in either security state. The details of the interrupt management framework
management framework and its design can be found in ARM Trusted Firmware and its design can be found in TF-A Interrupt Management Design guide [4]_.
Interrupt Management Design guide [4]_.
The ARM Trusted Firmware also implements a library for setting up and managing TF-A also implements a library for setting up and managing the translation
the translation tables. The details of this library can be found in tables. The details of this library can be found in `Xlat_tables design`_.
`Xlat_tables design`_.
The ARM Trusted Firmware can be built to support either AArch64 or AArch32 TF-A can be built to support either AArch64 or AArch32 execution state.
execution state.
Cold boot Cold boot
--------- ---------
@ -46,9 +43,8 @@ the primary CPU has performed enough initialization to boot them.
Refer to the `Reset Design`_ for more information on the effect of the Refer to the `Reset Design`_ for more information on the effect of the
``COLD_BOOT_SINGLE_CPU`` platform build option. ``COLD_BOOT_SINGLE_CPU`` platform build option.
The cold boot path in this implementation of the ARM Trusted Firmware, The cold boot path in this implementation of TF-A depends on the execution
depends on the execution state. state. For AArch64, it is divided into five steps (in order of execution):
For AArch64, it is divided into five steps (in order of execution):
- Boot Loader stage 1 (BL1) *AP Trusted ROM* - Boot Loader stage 1 (BL1) *AP Trusted ROM*
- Boot Loader stage 2 (BL2) *Trusted Boot Firmware* - Boot Loader stage 2 (BL2) *Trusted Boot Firmware*
@ -63,7 +59,7 @@ For AArch32, it is divided into four steps (in order of execution):
- Boot Loader stage 3-2 (BL32) *EL3 Runtime Software* - Boot Loader stage 3-2 (BL32) *EL3 Runtime Software*
- Boot Loader stage 3-3 (BL33) *Non-trusted Firmware* - Boot Loader stage 3-3 (BL33) *Non-trusted Firmware*
ARM development platforms (Fixed Virtual Platforms (FVPs) and Juno) implement a Arm development platforms (Fixed Virtual Platforms (FVPs) and Juno) implement a
combination of the following types of memory regions. Each bootloader stage uses combination of the following types of memory regions. Each bootloader stage uses
one or more of these memory regions. one or more of these memory regions.
@ -135,7 +131,7 @@ This stage begins execution from the platform's reset vector at EL3. The reset
address is platform dependent but it is usually located in a Trusted ROM area. address is platform dependent but it is usually located in a Trusted ROM area.
The BL1 data section is copied to trusted SRAM at runtime. The BL1 data section is copied to trusted SRAM at runtime.
On the ARM development platforms, BL1 code starts execution from the reset On the Arm development platforms, BL1 code starts execution from the reset
vector defined by the constant ``BL1_RO_BASE``. The BL1 data section is copied vector defined by the constant ``BL1_RO_BASE``. The BL1 data section is copied
to the top of trusted SRAM as defined by the constant ``BL1_RW_BASE``. to the top of trusted SRAM as defined by the constant ``BL1_RW_BASE``.
@ -205,7 +201,7 @@ BL1 performs minimal architectural initialization as follows.
0x1b : Undefined mode 0x1b : Undefined mode
0x1f : System mode 0x1f : System mode
The ``plat_report_exception()`` implementation on the ARM FVP port programs The ``plat_report_exception()`` implementation on the Arm FVP port programs
the Versatile Express System LED register in the following format to the Versatile Express System LED register in the following format to
indicate the occurence of an unexpected exception: indicate the occurence of an unexpected exception:
@ -299,7 +295,7 @@ BL1 performs minimal architectural initialization as follows.
Platform initialization Platform initialization
^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^
On ARM platforms, BL1 performs the following platform initializations: On Arm platforms, BL1 performs the following platform initializations:
- Enable the Trusted Watchdog. - Enable the Trusted Watchdog.
- Initialize the console. - Initialize the console.
@ -368,18 +364,18 @@ Architectural initialization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
For AArch64, BL2 performs the minimal architectural initialization required For AArch64, BL2 performs the minimal architectural initialization required
for subsequent stages of the ARM Trusted Firmware and normal world software. for subsequent stages of TF-A and normal world software. EL1 and EL0 are given
EL1 and EL0 are given access to Floating Point and Advanced SIMD registers access to Floating Point and Advanced SIMD registers by clearing the
by clearing the ``CPACR.FPEN`` bits. ``CPACR.FPEN`` bits.
For AArch32, the minimal architectural initialization required for subsequent For AArch32, the minimal architectural initialization required for subsequent
stages of the ARM Trusted Firmware and normal world software is taken care of stages of TF-A and normal world software is taken care of in BL1 as both BL1
in BL1 as both BL1 and BL2 execute at PL1. and BL2 execute at PL1.
Platform initialization Platform initialization
^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^
On ARM platforms, BL2 performs the following platform initializations: On Arm platforms, BL2 performs the following platform initializations:
- Initialize the console. - Initialize the console.
- Configure any required platform storage to allow loading further bootloader - Configure any required platform storage to allow loading further bootloader
@ -416,7 +412,7 @@ SCP\_BL2 (System Control Processor Firmware) image load
Some systems have a separate System Control Processor (SCP) for power, clock, Some systems have a separate System Control Processor (SCP) for power, clock,
reset and system control. BL2 loads the optional SCP\_BL2 image from platform reset and system control. BL2 loads the optional SCP\_BL2 image from platform
storage into a platform-specific region of secure memory. The subsequent storage into a platform-specific region of secure memory. The subsequent
handling of SCP\_BL2 is platform specific. For example, on the Juno ARM handling of SCP\_BL2 is platform specific. For example, on the Juno Arm
development platform port the image is transferred into SCP's internal memory development platform port the image is transferred into SCP's internal memory
using the Boot Over MHU (BOM) protocol after being loaded in the trusted SRAM using the Boot Over MHU (BOM) protocol after being loaded in the trusted SRAM
memory. The SCP executes SCP\_BL2 and signals to the Application Processor (AP) memory. The SCP executes SCP\_BL2 and signals to the Application Processor (AP)
@ -475,11 +471,11 @@ BL2 execution continues as follows:
Running BL2 at EL3 execution level Running BL2 at EL3 execution level
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Some platforms have a non-TF Boot ROM that expects the next boot stage Some platforms have a non-TF-A Boot ROM that expects the next boot stage
to execute at EL3. On these platforms, TF BL1 is a waste of memory to execute at EL3. On these platforms, TF-A BL1 is a waste of memory
as its only purpose is to ensure TF BL2 is entered at S-EL1. To avoid as its only purpose is to ensure TF-A BL2 is entered at S-EL1. To avoid
this waste, a special mode enables BL2 to execute at EL3, which allows this waste, a special mode enables BL2 to execute at EL3, which allows
a non-TF Boot ROM to load and jump directly to BL2. This mode is selected a non-TF-A Boot ROM to load and jump directly to BL2. This mode is selected
when the build flag BL2_AT_EL3 is enabled. The main differences in this when the build flag BL2_AT_EL3 is enabled. The main differences in this
mode are: mode are:
@ -566,7 +562,7 @@ Platform initialization
BL31 performs detailed platform initialization, which enables normal world BL31 performs detailed platform initialization, which enables normal world
software to function correctly. software to function correctly.
On ARM platforms, this consists of the following: On Arm platforms, this consists of the following:
- Initialize the console. - Initialize the console.
- Configure the Interconnect to enable hardware coherency. - Configure the Interconnect to enable hardware coherency.
@ -622,9 +618,9 @@ Using alternative Trusted Boot Firmware in place of BL1 & BL2 (AArch64 only)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Some platforms have existing implementations of Trusted Boot Firmware that Some platforms have existing implementations of Trusted Boot Firmware that
would like to use ARM Trusted Firmware BL31 for the EL3 Runtime Software. To would like to use TF-A BL31 for the EL3 Runtime Software. To enable this
enable this firmware architecture it is important to provide a fully documented firmware architecture it is important to provide a fully documented and stable
and stable interface between the Trusted Boot Firmware and BL31. interface between the Trusted Boot Firmware and BL31.
Future changes to the BL31 interface will be done in a backwards compatible Future changes to the BL31 interface will be done in a backwards compatible
way, and this enables these firmware components to be independently enhanced/ way, and this enables these firmware components to be independently enhanced/
@ -650,7 +646,7 @@ platform code in BL31:
:: ::
X0 : Reserved for common Trusted Firmware information X0 : Reserved for common TF-A information
X1 : Platform specific information X1 : Platform specific information
BL31 zero-init sections (e.g. ``.bss``) should not contain valid data on entry, BL31 zero-init sections (e.g. ``.bss``) should not contain valid data on entry,
@ -665,10 +661,10 @@ used by the common BL31 code.
The convention is that ``X0`` conveys information regarding the BL31, BL32 and The convention is that ``X0`` conveys information regarding the BL31, BL32 and
BL33 images from the Trusted Boot firmware and ``X1`` can be used for other BL33 images from the Trusted Boot firmware and ``X1`` can be used for other
platform specific purpose. This convention allows platforms which use ARM platform specific purpose. This convention allows platforms which use TF-A's
Trusted Firmware's BL1 and BL2 images to transfer additional platform specific BL1 and BL2 images to transfer additional platform specific information from
information from Secure Boot without conflicting with future evolution of the Secure Boot without conflicting with future evolution of TF-A using ``X0`` to
Trusted Firmware using ``X0`` to pass a ``bl31_params`` structure. pass a ``bl31_params`` structure.
BL31 common and SPD initialization code depends on image and entrypoint BL31 common and SPD initialization code depends on image and entrypoint
information about BL33 and BL32, which is provided via BL31 platform APIs. information about BL33 and BL32, which is provided via BL31 platform APIs.
@ -680,8 +676,8 @@ Cold boot Initialization parameters. This data may need to be cleaned out of
the CPU caches if it is provided by an earlier boot stage and then accessed by the CPU caches if it is provided by an earlier boot stage and then accessed by
BL31 platform code before the caches are enabled. BL31 platform code before the caches are enabled.
ARM Trusted Firmware's BL2 implementation passes a ``bl31_params`` structure in TF-A's BL2 implementation passes a ``bl31_params`` structure in
``X0`` and the ARM development platforms interpret this in the BL31 platform ``X0`` and the Arm development platforms interpret this in the BL31 platform
code. code.
MMU, Data caches & Coherency MMU, Data caches & Coherency
@ -722,12 +718,11 @@ to simplify this action.
Required CPU state for BL31 Warm boot initialization Required CPU state for BL31 Warm boot initialization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When requesting a CPU power-on, or suspending a running CPU, ARM Trusted When requesting a CPU power-on, or suspending a running CPU, TF-A provides
Firmware provides the platform power management code with a Warm boot the platform power management code with a Warm boot initialization
initialization entry-point, to be invoked by the CPU immediately after the entry-point, to be invoked by the CPU immediately after the reset handler.
reset handler. On entry to the Warm boot initialization function the calling On entry to the Warm boot initialization function the calling CPU must be in
CPU must be in AArch64 EL3, little-endian data access and all interrupt sources AArch64 EL3, little-endian data access and all interrupt sources masked:
masked:
:: ::
@ -769,7 +764,7 @@ platform code in AArch32 EL3 Runtime Software:
:: ::
R0 : Reserved for common Trusted Firmware information R0 : Reserved for common TF-A information
R1 : Platform specific information R1 : Platform specific information
Use of the R0 and R1 parameters Use of the R0 and R1 parameters
@ -778,10 +773,9 @@ Use of the R0 and R1 parameters
The parameters are platform specific and the convention is that ``R0`` conveys The parameters are platform specific and the convention is that ``R0`` conveys
information regarding the BL3x images from the Trusted Boot firmware and ``R1`` information regarding the BL3x images from the Trusted Boot firmware and ``R1``
can be used for other platform specific purpose. This convention allows can be used for other platform specific purpose. This convention allows
platforms which use ARM Trusted Firmware's BL1 and BL2 images to transfer platforms which use TF-A's BL1 and BL2 images to transfer additional platform
additional platform specific information from Secure Boot without conflicting specific information from Secure Boot without conflicting with future
with future evolution of the Trusted Firmware using ``R0`` to pass a ``bl_params`` evolution of TF-A using ``R0`` to pass a ``bl_params`` structure.
structure.
The AArch32 EL3 Runtime Software is responsible for entry into BL33. This The AArch32 EL3 Runtime Software is responsible for entry into BL33. This
information can be obtained in a platform defined manner, e.g. compiled into information can be obtained in a platform defined manner, e.g. compiled into
@ -791,7 +785,7 @@ via the Cold boot Initialization parameters. This data may need to be cleaned
out of the CPU caches if it is provided by an earlier boot stage and then out of the CPU caches if it is provided by an earlier boot stage and then
accessed by AArch32 EL3 Runtime Software before the caches are enabled. accessed by AArch32 EL3 Runtime Software before the caches are enabled.
When using AArch32 EL3 Runtime Software, the ARM development platforms pass a When using AArch32 EL3 Runtime Software, the Arm development platforms pass a
``bl_params`` structure in ``R0`` from BL2 to be interpreted by AArch32 EL3 Runtime ``bl_params`` structure in ``R0`` from BL2 to be interpreted by AArch32 EL3 Runtime
Software platform code. Software platform code.
@ -814,9 +808,9 @@ Required CPU state for warm boot initialization
When requesting a CPU power-on, or suspending a running CPU, AArch32 EL3 When requesting a CPU power-on, or suspending a running CPU, AArch32 EL3
Runtime Software must ensure execution of a warm boot initialization entrypoint. Runtime Software must ensure execution of a warm boot initialization entrypoint.
If ARM Trusted Firmware BL1 is used and the PROGRAMMABLE\_RESET\_ADDRESS build If TF-A BL1 is used and the PROGRAMMABLE\_RESET\_ADDRESS build flag is false,
flag is false, then AArch32 EL3 Runtime Software must ensure that BL1 branches then AArch32 EL3 Runtime Software must ensure that BL1 branches to the warm
to the warm boot entrypoint by arranging for the BL1 platform function, boot entrypoint by arranging for the BL1 platform function,
plat\_get\_my\_entrypoint(), to return a non-zero value. plat\_get\_my\_entrypoint(), to return a non-zero value.
In this case, the warm boot entrypoint must be in AArch32 EL3, little-endian In this case, the warm boot entrypoint must be in AArch32 EL3, little-endian
@ -827,7 +821,7 @@ data access and all interrupt sources masked:
PSTATE.AIF = 0x7 PSTATE.AIF = 0x7
SCTLR.EE = 0 SCTLR.EE = 0
The warm boot entrypoint may be implemented by using the ARM Trusted Firmware The warm boot entrypoint may be implemented by using TF-A
``psci_warmboot_entrypoint()`` function. In that case, the platform must fulfil ``psci_warmboot_entrypoint()`` function. In that case, the platform must fulfil
the pre-requisites mentioned in the `PSCI Library integration guide`_. the pre-requisites mentioned in the `PSCI Library integration guide`_.
@ -860,7 +854,7 @@ not all been instantiated in the current implementation.
This service is for management of the entire system. The Power State This service is for management of the entire system. The Power State
Coordination Interface (`PSCI`_) is the first set of standard service calls Coordination Interface (`PSCI`_) is the first set of standard service calls
defined by ARM (see PSCI section later). defined by Arm (see PSCI section later).
#. Secure-EL1 Payload Dispatcher service #. Secure-EL1 Payload Dispatcher service
@ -874,12 +868,12 @@ not all been instantiated in the current implementation.
The interface between the EL3 Runtime Software and the Secure-EL1 Payload is The interface between the EL3 Runtime Software and the Secure-EL1 Payload is
not defined by the `SMCCC`_ or any other standard. As a result, each not defined by the `SMCCC`_ or any other standard. As a result, each
Secure-EL1 Payload requires a specific Secure Monitor that runs as a runtime Secure-EL1 Payload requires a specific Secure Monitor that runs as a runtime
service - within ARM Trusted Firmware this service is referred to as the service - within TF-A this service is referred to as the Secure-EL1 Payload
Secure-EL1 Payload Dispatcher (SPD). Dispatcher (SPD).
ARM Trusted Firmware provides a Test Secure-EL1 Payload (TSP) and its TF-A provides a Test Secure-EL1 Payload (TSP) and its associated Dispatcher
associated Dispatcher (TSPD). Details of SPD design and TSP/TSPD operation (TSPD). Details of SPD design and TSP/TSPD operation are described in the
are described in the "Secure-EL1 Payloads and Dispatchers" section below. "Secure-EL1 Payloads and Dispatchers" section below.
#. CPU implementation service #. CPU implementation service
@ -887,7 +881,7 @@ not all been instantiated in the current implementation.
services for a given platform e.g. access to processor errata workarounds. services for a given platform e.g. access to processor errata workarounds.
This service is currently unimplemented. This service is currently unimplemented.
Additional services for ARM Architecture, SiP and OEM calls can be implemented. Additional services for Arm Architecture, SiP and OEM calls can be implemented.
Each implemented service handles a range of SMC function identifiers as Each implemented service handles a range of SMC function identifiers as
described in the `SMCCC`_. described in the `SMCCC`_.
@ -1060,10 +1054,10 @@ registered with the generic PSCI code to be supported.
\*\*Note : These PSCI APIs require appropriate Secure Payload Dispatcher \*\*Note : These PSCI APIs require appropriate Secure Payload Dispatcher
hooks to be registered with the generic PSCI code to be supported. hooks to be registered with the generic PSCI code to be supported.
The PSCI implementation in ARM Trusted Firmware is a library which can be The PSCI implementation in TF-A is a library which can be integrated with
integrated with AArch64 or AArch32 EL3 Runtime Software for ARMv8-A systems. AArch64 or AArch32 EL3 Runtime Software for Armv8-A systems. A guide to
A guide to integrating PSCI library with AArch32 EL3 Runtime Software integrating PSCI library with AArch32 EL3 Runtime Software can be found
can be found `here`_. `here`_.
Secure-EL1 Payloads and Dispatchers Secure-EL1 Payloads and Dispatchers
----------------------------------- -----------------------------------
@ -1072,20 +1066,20 @@ On a production system that includes a Trusted OS running in Secure-EL1/EL0,
the Trusted OS is coupled with a companion runtime service in the BL31 the Trusted OS is coupled with a companion runtime service in the BL31
firmware. This service is responsible for the initialisation of the Trusted firmware. This service is responsible for the initialisation of the Trusted
OS and all communications with it. The Trusted OS is the BL32 stage of the OS and all communications with it. The Trusted OS is the BL32 stage of the
boot flow in ARM Trusted Firmware. The firmware will attempt to locate, load boot flow in TF-A. The firmware will attempt to locate, load and execute a
and execute a BL32 image. BL32 image.
ARM Trusted Firmware uses a more general term for the BL32 software that runs TF-A uses a more general term for the BL32 software that runs at Secure-EL1 -
at Secure-EL1 - the *Secure-EL1 Payload* - as it is not always a Trusted OS. the *Secure-EL1 Payload* - as it is not always a Trusted OS.
The ARM Trusted Firmware provides a Test Secure-EL1 Payload (TSP) and a Test TF-A provides a Test Secure-EL1 Payload (TSP) and a Test Secure-EL1 Payload
Secure-EL1 Payload Dispatcher (TSPD) service as an example of how a Trusted OS Dispatcher (TSPD) service as an example of how a Trusted OS is supported on a
is supported on a production system using the Runtime Services Framework. On production system using the Runtime Services Framework. On such a system, the
such a system, the Test BL32 image and service are replaced by the Trusted OS Test BL32 image and service are replaced by the Trusted OS and its dispatcher
and its dispatcher service. The ARM Trusted Firmware build system expects that service. The TF-A build system expects that the dispatcher will define the
the dispatcher will define the build flag ``NEED_BL32`` to enable it to include build flag ``NEED_BL32`` to enable it to include the BL32 in the build either
the BL32 in the build either as a binary or to compile from source depending as a binary or to compile from source depending on whether the ``BL32`` build
on whether the ``BL32`` build option is specified or not. option is specified or not.
The TSP runs in Secure-EL1. It is designed to demonstrate synchronous The TSP runs in Secure-EL1. It is designed to demonstrate synchronous
communication with the normal-world software running in EL1/EL2. Communication communication with the normal-world software running in EL1/EL2. Communication
@ -1133,8 +1127,8 @@ prototype:
and is registered using the ``bl31_register_bl32_init()`` function. and is registered using the ``bl31_register_bl32_init()`` function.
Trusted Firmware supports two approaches for the SPD to pass control to BL32 TF-A supports two approaches for the SPD to pass control to BL32 before
before returning through EL3 and running the non-trusted firmware (BL33): returning through EL3 and running the non-trusted firmware (BL33):
#. In the BL32 setup function, use ``bl31_set_next_image_type()`` to #. In the BL32 setup function, use ``bl31_set_next_image_type()`` to
request that the exit from ``bl31_main()`` is to the BL32 entrypoint in request that the exit from ``bl31_main()`` is to the BL32 entrypoint in
@ -1153,8 +1147,8 @@ before returning through EL3 and running the non-trusted firmware (BL33):
``bl31_register_bl32_init()`` which provides a SPD-defined mechanism to ``bl31_register_bl32_init()`` which provides a SPD-defined mechanism to
invoke a 'world-switch synchronous call' to Secure-EL1 to run the BL32 invoke a 'world-switch synchronous call' to Secure-EL1 to run the BL32
entrypoint. entrypoint.
NOTE: The Test SPD service included with the Trusted Firmware provides one NOTE: The Test SPD service included with TF-A provides one implementation
implementation of such a mechanism. of such a mechanism.
On completion BL32 returns control to BL31 via a SMC, and on receipt the On completion BL32 returns control to BL31 via a SMC, and on receipt the
SPD service handler invokes the synchronous call return mechanism to return SPD service handler invokes the synchronous call return mechanism to return
@ -1260,11 +1254,11 @@ The sample crash output is shown below.
Guidelines for Reset Handlers Guidelines for Reset Handlers
----------------------------- -----------------------------
Trusted Firmware implements a framework that allows CPU and platform ports to TF-A implements a framework that allows CPU and platform ports to perform
perform actions very early after a CPU is released from reset in both the cold actions very early after a CPU is released from reset in both the cold and warm
and warm boot paths. This is done by calling the ``reset_handler()`` function in boot paths. This is done by calling the ``reset_handler()`` function in both
both the BL1 and BL31 images. It in turn calls the platform and CPU specific the BL1 and BL31 images. It in turn calls the platform and CPU specific reset
reset handling functions. handling functions.
Details for implementing a CPU specific reset handler can be found in Details for implementing a CPU specific reset handler can be found in
Section 8. Details for implementing a platform specific reset handler can be Section 8. Details for implementing a platform specific reset handler can be
@ -1330,11 +1324,11 @@ There are two ways to specify secure interrupt configuration:
CPU specific operations framework CPU specific operations framework
--------------------------------- ---------------------------------
Certain aspects of the ARMv8 architecture are implementation defined, Certain aspects of the Armv8-A architecture are implementation defined,
that is, certain behaviours are not architecturally defined, but must be defined that is, certain behaviours are not architecturally defined, but must be
and documented by individual processor implementations. The ARM Trusted defined and documented by individual processor implementations. TF-A
Firmware implements a framework which categorises the common implementation implements a framework which categorises the common implementation defined
defined behaviours and allows a processor to export its implementation of that behaviours and allows a processor to export its implementation of that
behaviour. The categories are: behaviour. The categories are:
#. Processor specific reset sequence. #. Processor specific reset sequence.
@ -1437,11 +1431,11 @@ expected by the crash reporting framework.
CPU errata status reporting CPU errata status reporting
~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
Errata workarounds for CPUs supported in ARM Trusted Firmware are applied during Errata workarounds for CPUs supported in TF-A are applied during both cold and
both cold and warm boots, shortly after reset. Individual Errata workarounds are warm boots, shortly after reset. Individual Errata workarounds are enabled as
enabled as build options. Some errata workarounds have potential run-time build options. Some errata workarounds have potential run-time implications;
implications; therefore some are enabled by default, others not. Platform ports therefore some are enabled by default, others not. Platform ports shall
shall override build options to enable or disable errata as appropriate. The CPU override build options to enable or disable errata as appropriate. The CPU
drivers take care of applying errata workarounds that are enabled and applicable drivers take care of applying errata workarounds that are enabled and applicable
to a given CPU. Refer to the section titled *CPU Errata Workarounds* in `CPUBM`_ to a given CPU. Refer to the section titled *CPU Errata Workarounds* in `CPUBM`_
for more information. for more information.
@ -1475,9 +1469,9 @@ macro, the errata reporting function, if it exists, must be named
``cpux_errata_report``. This function will always be called with MMU enabled; it ``cpux_errata_report``. This function will always be called with MMU enabled; it
must follow AAPCS and may use stack. must follow AAPCS and may use stack.
In a debug build of ARM Trusted Firmware, on a CPU that comes out of reset, both In a debug build of TF-A, on a CPU that comes out of reset, both BL1 and the
BL1 and the run time firmware (BL31 in AArch64, and BL32 in AArch32) will invoke runtime firmware (BL31 in AArch64, and BL32 in AArch32) will invoke errata
errata status reporting function, if one exists, for that type of CPU. status reporting function, if one exists, for that type of CPU.
To report the status of each errata workaround, the function shall use the To report the status of each errata workaround, the function shall use the
assembler macro ``report_errata``, passing it: assembler macro ``report_errata``, passing it:
@ -1493,9 +1487,9 @@ assembler macro ``report_errata``, passing it:
The errata status reporting function will be called once per CPU type/errata The errata status reporting function will be called once per CPU type/errata
combination during the software's active life time. combination during the software's active life time.
It's expected that whenever an errata workaround is submitted to ARM Trusted It's expected that whenever an errata workaround is submitted to TF-A, the
Firmware, the errata reporting function is appropriately extended to report its errata reporting function is appropriately extended to report its status as
status as well. well.
Reporting the status of errata workaround is for informational purpose only; it Reporting the status of errata workaround is for informational purpose only; it
has no functional significance. has no functional significance.
@ -1516,22 +1510,22 @@ Each bootloader image can be divided in 2 parts:
In the ELF terminology, they are called ``NOBITS`` sections. In the ELF terminology, they are called ``NOBITS`` sections.
All PROGBITS sections are grouped together at the beginning of the image, All PROGBITS sections are grouped together at the beginning of the image,
followed by all NOBITS sections. This is true for all Trusted Firmware images followed by all NOBITS sections. This is true for all TF-A images and it is
and it is governed by the linker scripts. This ensures that the raw binary governed by the linker scripts. This ensures that the raw binary images are
images are as small as possible. If a NOBITS section was inserted in between as small as possible. If a NOBITS section was inserted in between PROGBITS
PROGBITS sections then the resulting binary file would contain zero bytes in sections then the resulting binary file would contain zero bytes in place of
place of this NOBITS section, making the image unnecessarily bigger. Smaller this NOBITS section, making the image unnecessarily bigger. Smaller images
images allow faster loading from the FIP to the main memory. allow faster loading from the FIP to the main memory.
Linker scripts and symbols Linker scripts and symbols
~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~
Each bootloader stage image layout is described by its own linker script. The Each bootloader stage image layout is described by its own linker script. The
linker scripts export some symbols into the program symbol table. Their values linker scripts export some symbols into the program symbol table. Their values
correspond to particular addresses. The trusted firmware code can refer to these correspond to particular addresses. TF-A code can refer to these symbols to
symbols to figure out the image memory layout. figure out the image memory layout.
Linker symbols follow the following naming convention in the trusted firmware. Linker symbols follow the following naming convention in TF-A.
- ``__<SECTION>_START__`` - ``__<SECTION>_START__``
@ -1564,10 +1558,10 @@ Linker symbols follow the following naming convention in the trusted firmware.
rounding up due to some alignment constraint. In other words, rounding up due to some alignment constraint. In other words,
``__<SECTION>_UNALIGNED_SIZE__ = __<SECTION>_UNALIGNED_END__ - __<SECTION>_START__``. ``__<SECTION>_UNALIGNED_SIZE__ = __<SECTION>_UNALIGNED_END__ - __<SECTION>_START__``.
Some of the linker symbols are mandatory as the trusted firmware code relies on Some of the linker symbols are mandatory as TF-A code relies on them to be
them to be defined. They are listed in the following subsections. Some of them defined. They are listed in the following subsections. Some of them must be
must be provided for each bootloader stage and some are specific to a given provided for each bootloader stage and some are specific to a given bootloader
bootloader stage. stage.
The linker scripts define some extra, optional symbols. They are not actually The linker scripts define some extra, optional symbols. They are not actually
used by any code but they help in understanding the bootloader images' memory used by any code but they help in understanding the bootloader images' memory
@ -1622,12 +1616,11 @@ The following additional linker symbols are defined for BL1:
How to choose the right base addresses for each bootloader stage image How to choose the right base addresses for each bootloader stage image
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There is currently no support for dynamic image loading in the Trusted Firmware. There is currently no support for dynamic image loading in TF-A. This means
This means that all bootloader images need to be linked against their ultimate that all bootloader images need to be linked against their ultimate runtime
runtime locations and the base addresses of each image must be chosen carefully locations and the base addresses of each image must be chosen carefully such
such that images don't overlap each other in an undesired way. As the code that images don't overlap each other in an undesired way. As the code grows,
grows, the base addresses might need adjustments to cope with the new memory the base addresses might need adjustments to cope with the new memory layout.
layout.
The memory layout is completely specific to the platform and so there is no The memory layout is completely specific to the platform and so there is no
general recipe for choosing the right base addresses for each bootloader image. general recipe for choosing the right base addresses for each bootloader image.
@ -1655,13 +1648,13 @@ Additionally, if the platform memory layout implies some image overlaying like
on FVP, BL31 and TSP need to know the limit address that their PROGBITS on FVP, BL31 and TSP need to know the limit address that their PROGBITS
sections must not overstep. The platform code must provide those. sections must not overstep. The platform code must provide those.
When LOAD\_IMAGE\_V2 is disabled, Trusted Firmware provides a mechanism to When LOAD\_IMAGE\_V2 is disabled, TF-A provides a mechanism to verify at boot
verify at boot time that the memory to load a new image is free to prevent time that the memory to load a new image is free to prevent overwriting a
overwriting a previously loaded image. For this mechanism to work, the platform previously loaded image. For this mechanism to work, the platform must specify
must specify the memory available in the system as regions, where each region the memory available in the system as regions, where each region consists of
consists of base address, total size and the free area within it (as defined base address, total size and the free area within it (as defined in the
in the ``meminfo_t`` structure). Trusted Firmware retrieves these memory regions ``meminfo_t`` structure). TF-A retrieves these memory regions by calling the
by calling the corresponding platform API: corresponding platform API:
- ``meminfo_t *bl1_plat_sec_mem_layout(void)`` - ``meminfo_t *bl1_plat_sec_mem_layout(void)``
- ``meminfo_t *bl2_plat_sec_mem_layout(void)`` - ``meminfo_t *bl2_plat_sec_mem_layout(void)``
@ -1685,7 +1678,7 @@ corresponding processor (e.g. the SCP BL2 image).
To reduce fragmentation and simplify the tracking of free memory, all the free To reduce fragmentation and simplify the tracking of free memory, all the free
memory within a region is always located in one single buffer defined by its memory within a region is always located in one single buffer defined by its
base address and size. Trusted Firmware implements a top/bottom load approach: base address and size. TF-A implements a top/bottom load approach:
after a new image is loaded, it checks how much memory remains free above and after a new image is loaded, it checks how much memory remains free above and
below the image. The smallest area is marked as unavailable, while the larger below the image. The smallest area is marked as unavailable, while the larger
area becomes the new free memory buffer. Platforms should take this behaviour area becomes the new free memory buffer. Platforms should take this behaviour
@ -1725,10 +1718,10 @@ And the following diagram is an example of an image loaded in the top part:
| | | |
+----------+ +----------+
When LOAD\_IMAGE\_V2 is enabled, Trusted Firmware does not provide any mechanism When LOAD\_IMAGE\_V2 is enabled, TF-A does not provide any mechanism to verify
to verify at boot time that the memory to load a new image is free to prevent at boot time that the memory to load a new image is free to prevent overwriting
overwriting a previously loaded image. The platform must specify the memory a previously loaded image. The platform must specify the memory available in
available in the system for all the relevant BL images to be loaded. the system for all the relevant BL images to be loaded.
For example, in the case of BL1 loading BL2, ``bl1_plat_sec_mem_layout()`` will For example, in the case of BL1 loading BL2, ``bl1_plat_sec_mem_layout()`` will
return the region defined by the platform where BL1 intends to load BL2. The return the region defined by the platform where BL1 intends to load BL2. The
@ -1736,10 +1729,10 @@ return the region defined by the platform where BL1 intends to load BL2. The
base and maximum image size provided by the platforms. Platforms must take base and maximum image size provided by the platforms. Platforms must take
this behaviour into account when defining the base/size for each of the images. this behaviour into account when defining the base/size for each of the images.
Memory layout on ARM development platforms Memory layout on Arm development platforms
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following list describes the memory layout on the ARM development platforms: The following list describes the memory layout on the Arm development platforms:
- A 4KB page of shared memory is used for communication between Trusted - A 4KB page of shared memory is used for communication between Trusted
Firmware and the platform's power controller. This is located at the base of Firmware and the platform's power controller. This is located at the base of
@ -1799,14 +1792,13 @@ mechanism at boot time are defined as follows (shown per API):
This region is an exact copy of the region defined by This region is an exact copy of the region defined by
``bl2_plat_sec_mem_layout()``. Being a disconnected copy means that all the ``bl2_plat_sec_mem_layout()``. Being a disconnected copy means that all the
changes made to this region by the Trusted Firmware will not be propagated. changes made to this region by the TF-A will not be propagated. This
This approach is valid because the SCP BL2 image is loaded temporarily approach is valid because the SCP BL2 image is loaded temporarily while it
while it is being transferred to the SCP, so this memory is reused is being transferred to the SCP, so this memory is reused afterwards.
afterwards.
- ``void bl2_plat_get_bl32_meminfo(meminfo_t *bl32_meminfo)`` - ``void bl2_plat_get_bl32_meminfo(meminfo_t *bl32_meminfo)``
This region depends on the location of the BL32 image. Currently, ARM This region depends on the location of the BL32 image. Currently, Arm
platforms support three different locations (detailed below): Trusted SRAM, platforms support three different locations (detailed below): Trusted SRAM,
Trusted DRAM and the TZC-Secured DRAM. Trusted DRAM and the TZC-Secured DRAM.
@ -1980,11 +1972,11 @@ Firmware Image Package (FIP)
---------------------------- ----------------------------
Using a Firmware Image Package (FIP) allows for packing bootloader images (and Using a Firmware Image Package (FIP) allows for packing bootloader images (and
potentially other payloads) into a single archive that can be loaded by the ARM potentially other payloads) into a single archive that can be loaded by TF-A
Trusted Firmware from non-volatile platform storage. A driver to load images from non-volatile platform storage. A driver to load images from a FIP has
from a FIP has been added to the storage layer and allows a package to be read been added to the storage layer and allows a package to be read from supported
from supported platform storage. A tool to create Firmware Image Packages is platform storage. A tool to create Firmware Image Packages is also provided
also provided and described below. and described below.
Firmware Image Package layout Firmware Image Package layout
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -2019,7 +2011,7 @@ retrieved.
The ToC header and entry formats are described in the header file The ToC header and entry formats are described in the header file
``include/tools_share/firmware_image_package.h``. This file is used by both the ``include/tools_share/firmware_image_package.h``. This file is used by both the
tool and the ARM Trusted firmware. tool and TF-A.
The ToC header has the following fields: The ToC header has the following fields:
@ -2049,10 +2041,10 @@ A ToC entry has the following fields:
Firmware Image Package creation tool Firmware Image Package creation tool
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The FIP creation tool can be used to pack specified images into a binary package The FIP creation tool can be used to pack specified images into a binary
that can be loaded by the ARM Trusted Firmware from platform storage. The tool package that can be loaded by TF-A from platform storage. The tool currently
currently only supports packing bootloader images. Additional image definitions only supports packing bootloader images. Additional image definitions can be
can be added to the tool as required. added to the tool as required.
The tool can be found in ``tools/fiptool``. The tool can be found in ``tools/fiptool``.
@ -2060,38 +2052,37 @@ Loading from a Firmware Image Package (FIP)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Firmware Image Package (FIP) driver can load images from a binary package on The Firmware Image Package (FIP) driver can load images from a binary package on
non-volatile platform storage. For the ARM development platforms, this is non-volatile platform storage. For the Arm development platforms, this is
currently NOR FLASH. currently NOR FLASH.
Bootloader images are loaded according to the platform policy as specified by Bootloader images are loaded according to the platform policy as specified by
the function ``plat_get_image_source()``. For the ARM development platforms, this the function ``plat_get_image_source()``. For the Arm development platforms, this
means the platform will attempt to load images from a Firmware Image Package means the platform will attempt to load images from a Firmware Image Package
located at the start of NOR FLASH0. located at the start of NOR FLASH0.
The ARM development platforms' policy is to only allow loading of a known set of The Arm development platforms' policy is to only allow loading of a known set of
images. The platform policy can be modified to allow additional images. images. The platform policy can be modified to allow additional images.
Use of coherent memory in Trusted Firmware Use of coherent memory in TF-A
------------------------------------------ ------------------------------
There might be loss of coherency when physical memory with mismatched There might be loss of coherency when physical memory with mismatched
shareability, cacheability and memory attributes is accessed by multiple CPUs shareability, cacheability and memory attributes is accessed by multiple CPUs
(refer to section B2.9 of `ARM ARM`_ for more details). This possibility occurs (refer to section B2.9 of `Arm ARM`_ for more details). This possibility occurs
in Trusted Firmware during power up/down sequences when coherency, MMU and in TF-A during power up/down sequences when coherency, MMU and caches are
caches are turned on/off incrementally. turned on/off incrementally.
Trusted Firmware defines coherent memory as a region of memory with Device TF-A defines coherent memory as a region of memory with Device nGnRE attributes
nGnRE attributes in the translation tables. The translation granule size in in the translation tables. The translation granule size in TF-A is 4KB. This
Trusted Firmware is 4KB. This is the smallest possible size of the coherent is the smallest possible size of the coherent memory region.
memory region.
By default, all data structures which are susceptible to accesses with By default, all data structures which are susceptible to accesses with
mismatched attributes from various CPUs are allocated in a coherent memory mismatched attributes from various CPUs are allocated in a coherent memory
region (refer to section 2.1 of `Porting Guide`_). The coherent memory region region (refer to section 2.1 of `Porting Guide`_). The coherent memory region
accesses are Outer Shareable, non-cacheable and they can be accessed accesses are Outer Shareable, non-cacheable and they can be accessed
with the Device nGnRE attributes when the MMU is turned on. Hence, at the with the Device nGnRE attributes when the MMU is turned on. Hence, at the
expense of at least an extra page of memory, Trusted Firmware is able to work expense of at least an extra page of memory, TF-A is able to work around
around coherency issues due to mismatched memory attributes. coherency issues due to mismatched memory attributes.
The alternative to the above approach is to allocate the susceptible data The alternative to the above approach is to allocate the susceptible data
structures in Normal WriteBack WriteAllocate Inner shareable memory. This structures in Normal WriteBack WriteAllocate Inner shareable memory. This
@ -2099,12 +2090,12 @@ approach requires the data structures to be designed so that it is possible to
work around the issue of mismatched memory attributes by performing software work around the issue of mismatched memory attributes by performing software
cache maintenance on them. cache maintenance on them.
Disabling the use of coherent memory in Trusted Firmware Disabling the use of coherent memory in TF-A
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It might be desirable to avoid the cost of allocating coherent memory on It might be desirable to avoid the cost of allocating coherent memory on
platforms which are memory constrained. Trusted Firmware enables inclusion of platforms which are memory constrained. TF-A enables inclusion of coherent
coherent memory in firmware images through the build flag ``USE_COHERENT_MEM``. memory in firmware images through the build flag ``USE_COHERENT_MEM``.
This flag is enabled by default. It can be disabled to choose the second This flag is enabled by default. It can be disabled to choose the second
approach described above. approach described above.
@ -2116,9 +2107,8 @@ Coherent memory usage in PSCI implementation
The ``psci_non_cpu_pd_nodes`` data structure stores the platform's power domain The ``psci_non_cpu_pd_nodes`` data structure stores the platform's power domain
tree information for state management of power domains. By default, this data tree information for state management of power domains. By default, this data
structure is allocated in the coherent memory region in the Trusted Firmware structure is allocated in the coherent memory region in TF-A because it can be
because it can be accessed by multple CPUs, either with caches enabled or accessed by multple CPUs, either with caches enabled or disabled.
disabled.
.. code:: c .. code:: c
@ -2271,7 +2261,7 @@ operation on Lock\_N, the corresponding ``bakery_info_t`` in both CPU0 and CPU1
``bakery_lock`` section need to be fetched and appropriate cache operations need ``bakery_lock`` section need to be fetched and appropriate cache operations need
to be performed for each access. to be performed for each access.
On ARM Platforms, bakery locks are used in psci (``psci_locks``) and power controller On Arm Platforms, bakery locks are used in psci (``psci_locks``) and power controller
driver (``arm_lock``). driver (``arm_lock``).
Non Functional Impact of removing coherent memory Non Functional Impact of removing coherent memory
@ -2292,7 +2282,7 @@ The implementation has been optimized to minimize this additional overhead.
Measurements indicate that when bakery locks are allocated in Normal memory, the Measurements indicate that when bakery locks are allocated in Normal memory, the
minimum latency of acquiring a lock is on an average 3-4 micro seconds whereas minimum latency of acquiring a lock is on an average 3-4 micro seconds whereas
in Device memory the same is 2 micro seconds. The measurements were done on the in Device memory the same is 2 micro seconds. The measurements were done on the
Juno ARM development platform. Juno Arm development platform.
As mentioned earlier, almost a page of memory can be saved by disabling As mentioned earlier, almost a page of memory can be saved by disabling
``USE_COHERENT_MEM``. Each platform needs to consider these trade-offs to decide ``USE_COHERENT_MEM``. Each platform needs to consider these trade-offs to decide
@ -2304,7 +2294,7 @@ optionally define macro ``PLAT_PERCPU_BAKERY_LOCK_SIZE`` (see the
Isolating code and read-only data on separate memory pages Isolating code and read-only data on separate memory pages
---------------------------------------------------------- ----------------------------------------------------------
In the ARMv8 VMSA, translation table entries include fields that define the In the Armv8-A VMSA, translation table entries include fields that define the
properties of the target memory region, such as its access permissions. The properties of the target memory region, such as its access permissions. The
smallest unit of memory that can be addressed by a translation table entry is smallest unit of memory that can be addressed by a translation table entry is
a memory page. Therefore, if software needs to set different permissions on two a memory page. Therefore, if software needs to set different permissions on two
@ -2379,7 +2369,7 @@ With this more condensed memory layout, the separation of read-only data will
add zero or one page to the memory footprint of each BL image. Each platform add zero or one page to the memory footprint of each BL image. Each platform
should consider the trade-off between memory footprint and security. should consider the trade-off between memory footprint and security.
This build flag is disabled by default, minimising memory footprint. On ARM This build flag is disabled by default, minimising memory footprint. On Arm
platforms, it is enabled. platforms, it is enabled.
Publish and Subscribe Framework Publish and Subscribe Framework
@ -2433,11 +2423,10 @@ PE only; it won't cause handlers to execute on a different PE.
Note that publishing an event on a PE blocks until all the subscribed handlers Note that publishing an event on a PE blocks until all the subscribed handlers
finish executing on the PE. finish executing on the PE.
ARM Trusted Firmware generic code publishes and subscribes to some events TF-A generic code publishes and subscribes to some events within. Platform
within. Platform ports are discouraged from subscribing to them. These events ports are discouraged from subscribing to them. These events may be withdrawn,
may be withdrawn, renamed, or have their semantics altered in the future. renamed, or have their semantics altered in the future. Platforms may however
Platforms may however register, publish, and subscribe to platform-specific register, publish, and subscribe to platform-specific events.
events.
Publish and Subscribe Example Publish and Subscribe Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -2473,9 +2462,9 @@ Performance Measurement Framework
--------------------------------- ---------------------------------
The Performance Measurement Framework (PMF) facilitates collection of The Performance Measurement Framework (PMF) facilitates collection of
timestamps by registered services and provides interfaces to retrieve timestamps by registered services and provides interfaces to retrieve them
them from within the ARM Trusted Firmware. A platform can choose to from within TF-A. A platform can choose to expose appropriate SMCs to
expose appropriate SMCs to retrieve these collected timestamps. retrieve these collected timestamps.
By default, the global physical counter is used for the timestamp By default, the global physical counter is used for the timestamp
value and is read via ``CNTPCT_EL0``. The framework allows to retrieve value and is read via ``CNTPCT_EL0``. The framework allows to retrieve
@ -2520,9 +2509,8 @@ timestamps in a PMF specific linker section at build time.
Additionally, it defines necessary functions to capture and Additionally, it defines necessary functions to capture and
retrieve a particular timestamp for the given service at runtime. retrieve a particular timestamp for the given service at runtime.
The macro ``PMF_REGISTER_SERVICE()`` only enables capturing PMF The macro ``PMF_REGISTER_SERVICE()`` only enables capturing PMF timestamps
timestamps from within ARM Trusted Firmware. In order to retrieve from within TF-A. In order to retrieve timestamps from outside of TF-A, the
timestamps from outside of ARM Trusted Firmware, the
``PMF_REGISTER_SERVICE_SMC()`` macro must be used instead. This macro ``PMF_REGISTER_SERVICE_SMC()`` macro must be used instead. This macro
accepts the same set of arguments as the ``PMF_REGISTER_SERVICE()`` accepts the same set of arguments as the ``PMF_REGISTER_SERVICE()``
macro but additionally supports retrieving timestamps using SMCs. macro but additionally supports retrieving timestamps using SMCs.
@ -2552,13 +2540,13 @@ and store it at the determined address for later retrieval.
Retrieving a timestamp Retrieving a timestamp
~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~
From within ARM Trusted Firmware, timestamps for individual CPUs can From within TF-A, timestamps for individual CPUs can be retrieved using either
be retrieved using either ``PMF_GET_TIMESTAMP_BY_MPIDR()`` or ``PMF_GET_TIMESTAMP_BY_MPIDR()`` or ``PMF_GET_TIMESTAMP_BY_INDEX()`` macros.
``PMF_GET_TIMESTAMP_BY_INDEX()`` macros. These macros accept the CPU's MPIDR These macros accept the CPU's MPIDR value, or its ordinal position
value, or its ordinal position, respectively. respectively.
From outside ARM Trusted Firmware, timestamps for individual CPUs can be From outside TF-A, timestamps for individual CPUs can be retrieved by calling
retrieved by calling into ``pmf_smc_handler()``. into ``pmf_smc_handler()``.
.. code:: c .. code:: c
@ -2600,32 +2588,31 @@ PMF code structure
#. ``pmf_helpers.h`` is an internal header used by ``pmf.h``. #. ``pmf_helpers.h`` is an internal header used by ``pmf.h``.
ARMv8 Architecture Extensions Armv8-A Architecture Extensions
----------------------------- -------------------------------
ARM Trusted Firmware makes use of ARMv8 Architecture Extensions where TF-A makes use of Armv8-A Architecture Extensions where applicable. This
applicable. This section lists the usage of Architecture Extensions, and build section lists the usage of Architecture Extensions, and build flags
flags controlling them. controlling them.
In general, and unless individually mentioned, the build options In general, and unless individually mentioned, the build options
``ARM_ARCH_MAJOR`` and ``ARM_ARCH_MINOR`` selects the Architecture Extension to ``ARM_ARCH_MAJOR`` and ``ARM_ARCH_MINOR`` selects the Architecture Extension to
target when building ARM Trusted Firmware. Subsequent ARM Architecture target when building TF-A. Subsequent Arm Architecture Extensions are backward
Extensions are backward compatible with previous versions. compatible with previous versions.
The build system only requires that ``ARM_ARCH_MAJOR`` and ``ARM_ARCH_MINOR`` have a The build system only requires that ``ARM_ARCH_MAJOR`` and ``ARM_ARCH_MINOR`` have a
valid numeric value. These build options only control whether or not valid numeric value. These build options only control whether or not
Architecture Extension-specific code is included in the build. Otherwise, ARM Architecture Extension-specific code is included in the build. Otherwise, TF-A
Trusted Firmware targets the base ARMv8.0 architecture; i.e. as if targets the base Armv8.0-A architecture; i.e. as if ``ARM_ARCH_MAJOR`` == 8
``ARM_ARCH_MAJOR`` == 8 and ``ARM_ARCH_MINOR`` == 0, which are also their respective and ``ARM_ARCH_MINOR`` == 0, which are also their respective default values.
default values.
See also the *Summary of build options* in `User Guide`_. See also the *Summary of build options* in `User Guide`_.
For details on the Architecture Extension and available features, please refer For details on the Architecture Extension and available features, please refer
to the respective Architecture Extension Supplement. to the respective Architecture Extension Supplement.
ARMv8.1 Armv8.1-A
~~~~~~~ ~~~~~~~~~
This Architecture Extension is targeted when ``ARM_ARCH_MAJOR`` >= 8, or when This Architecture Extension is targeted when ``ARM_ARCH_MAJOR`` >= 8, or when
``ARM_ARCH_MAJOR`` == 8 and ``ARM_ARCH_MINOR`` >= 1. ``ARM_ARCH_MAJOR`` == 8 and ``ARM_ARCH_MINOR`` >= 1.
@ -2633,8 +2620,8 @@ This Architecture Extension is targeted when ``ARM_ARCH_MAJOR`` >= 8, or when
- The Compare and Swap instruction is used to implement spinlocks. Otherwise, - The Compare and Swap instruction is used to implement spinlocks. Otherwise,
the load-/store-exclusive instruction pair is used. the load-/store-exclusive instruction pair is used.
ARMv8.2 Armv8.2-A
~~~~~~~ ~~~~~~~~~
This Architecture Extension is targeted when ``ARM_ARCH_MAJOR`` == 8 and This Architecture Extension is targeted when ``ARM_ARCH_MAJOR`` == 8 and
``ARM_ARCH_MINOR`` >= 2. ``ARM_ARCH_MINOR`` >= 2.
@ -2644,23 +2631,22 @@ This Architecture Extension is targeted when ``ARM_ARCH_MAJOR`` == 8 and
translation table entries for a given stage of translation for a particular translation table entries for a given stage of translation for a particular
translation regime. translation regime.
ARMv7 Armv7-A
~~~~~ ~~~~~~~
This Architecture Extension is targeted when ``ARM_ARCH_MAJOR`` == 7. This Architecture Extension is targeted when ``ARM_ARCH_MAJOR`` == 7.
There are several ARMv7 extensions available. Obviously the TrustZone There are several Armv7-A extensions available. Obviously the TrustZone
extension is mandatory to support the ARM Trusted Firmware bootloader extension is mandatory to support the TF-A bootloader and runtime services.
and runtime services.
Platform implementing an ARMv7 system can to define from its target Platform implementing an Armv7-A system can to define from its target
Cortex-A architecture through ``ARM_CORTEX_A<X> = yes`` in their Cortex-A architecture through ``ARM_CORTEX_A<X> = yes`` in their
``plaform.mk`` script. For example ``ARM_CORTEX_A15=yes`` for a ``plaform.mk`` script. For example ``ARM_CORTEX_A15=yes`` for a
Cortex-A15 target. Cortex-A15 target.
Platform can also set ``ARM_WITH_NEON=yes`` to enable neon support. Platform can also set ``ARM_WITH_NEON=yes`` to enable neon support.
Note that using neon at runtime has constraints on non secure wolrd context. Note that using neon at runtime has constraints on non secure wolrd context.
The trusted firmware does not yet provide VFP context management. TF-A does not yet provide VFP context management.
Directive ``ARM_CORTEX_A<x>`` and ``ARM_WITH_NEON`` are used to set Directive ``ARM_CORTEX_A<x>`` and ``ARM_WITH_NEON`` are used to set
the toolchain target architecture directive. the toolchain target architecture directive.
@ -2676,9 +2662,9 @@ I.e:
Code Structure Code Structure
-------------- --------------
Trusted Firmware code is logically divided between the three boot loader TF-A code is logically divided between the three boot loader stages mentioned
stages mentioned in the previous sections. The code is also divided into the in the previous sections. The code is also divided into the following
following categories (present as directories in the source code): categories (present as directories in the source code):
- **Platform specific.** Choice of architecture specific code depends upon - **Platform specific.** Choice of architecture specific code depends upon
the platform. the platform.
@ -2708,8 +2694,8 @@ categories. Based upon the above, the code layout looks like this:
The build system provides a non configurable build option IMAGE\_BLx for each The build system provides a non configurable build option IMAGE\_BLx for each
boot loader stage (where x = BL stage). e.g. for BL1 , IMAGE\_BL1 will be boot loader stage (where x = BL stage). e.g. for BL1 , IMAGE\_BL1 will be
defined by the build system. This enables the Trusted Firmware to compile defined by the build system. This enables TF-A to compile certain code only
certain code only for specific boot loader stages for specific boot loader stages
All assembler files have the ``.S`` extension. The linker source files for each All assembler files have the ``.S`` extension. The linker source files for each
boot stage have the extension ``.ld.S``. These are processed by GCC to create the boot stage have the extension ``.ld.S``. These are processed by GCC to create the
@ -2721,15 +2707,15 @@ kernel at boot time. These can be found in the ``fdts`` directory.
References References
---------- ----------
.. [#] Trusted Board Boot Requirements CLIENT PDD (ARM DEN0006C-1). Available .. [#] Trusted Board Boot Requirements CLIENT PDD (Arm DEN0006C-1). Available
under NDA through your ARM account representative. under NDA through your Arm account representative.
.. [#] `Power State Coordination Interface PDD`_ .. [#] `Power State Coordination Interface PDD`_
.. [#] `SMC Calling Convention PDD`_ .. [#] `SMC Calling Convention PDD`_
.. [#] `ARM Trusted Firmware Interrupt Management Design guide`_. .. [#] `TF-A Interrupt Management Design guide`_.
-------------- --------------
*Copyright (c) 2013-2018, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2013-2018, Arm Limited and Contributors. All rights reserved.*
.. _Reset Design: ./reset-design.rst .. _Reset Design: ./reset-design.rst
.. _Porting Guide: ./porting-guide.rst .. _Porting Guide: ./porting-guide.rst
@ -2743,10 +2729,10 @@ References
.. _here: ./psci-lib-integration-guide.rst .. _here: ./psci-lib-integration-guide.rst
.. _cpu-specific-build-macros.rst: ./cpu-specific-build-macros.rst .. _cpu-specific-build-macros.rst: ./cpu-specific-build-macros.rst
.. _CPUBM: ./cpu-specific-build-macros.rst .. _CPUBM: ./cpu-specific-build-macros.rst
.. _ARM ARM: http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0487a.e/index.html .. _Arm ARM: http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0487a.e/index.html
.. _User Guide: ./user-guide.rst .. _User Guide: ./user-guide.rst
.. _SMC Calling Convention PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf .. _SMC Calling Convention PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
.. _ARM Trusted Firmware Interrupt Management Design guide: ./interrupt-framework-design.rst .. _TF-A Interrupt Management Design guide: ./interrupt-framework-design.rst
.. _Xlat_tables design: xlat-tables-lib-v2-design.rst .. _Xlat_tables design: xlat-tables-lib-v2-design.rst
.. |Image 1| image:: diagrams/rt-svc-descs-layout.png?raw=true .. |Image 1| image:: diagrams/rt-svc-descs-layout.png?raw=true

22
docs/firmware-update.rst
View file

@ -1,5 +1,5 @@
ARM Trusted Firmware - Firmware Update Design Guide Trusted Firmware-A - Firmware Update design guide
=================================================== =================================================
.. section-numbering:: .. section-numbering::
@ -21,9 +21,9 @@ is corrupt or missing; it therefore may be used as a recovery mode. It may also
be complemented by other, higher level firmware update software. be complemented by other, higher level firmware update software.
FWU implements a specific part of the Trusted Board Boot Requirements (TBBR) FWU implements a specific part of the Trusted Board Boot Requirements (TBBR)
specification, ARM DEN0006C-1. It should be used in conjunction with the specification, Arm DEN0006C-1. It should be used in conjunction with the
`Trusted Board Boot`_ design document, which describes the image authentication `Trusted Board Boot`_ design document, which describes the image authentication
parts of the Trusted Firmware (TF) TBBR implementation. parts of the Trusted Firmware-A (TF-A) TBBR implementation.
Scope Scope
~~~~~ ~~~~~
@ -63,11 +63,11 @@ The primary requirements of the FWU feature are:
it needs, and to enable platform specific FWU functionality. See the it needs, and to enable platform specific FWU functionality. See the
`Porting Guide`_ for details of this interface. `Porting Guide`_ for details of this interface.
TF uses abbreviated image terminology for FWU images like for other TF images. TF-A uses abbreviated image terminology for FWU images like for other TF-A
An overview of this terminology can be found `here`_. images. An overview of this terminology can be found `here`_.
The following diagram shows the FWU boot flow for ARM development platforms. The following diagram shows the FWU boot flow for Arm development platforms.
ARM CSS platforms like Juno have a System Control Processor (SCP), and these Arm CSS platforms like Juno have a System Control Processor (SCP), and these
use all defined FWU images. Other platforms may use a subset of these. use all defined FWU images. Other platforms may use a subset of these.
|Flow Diagram| |Flow Diagram|
@ -193,8 +193,8 @@ BL1\_SMC\_RUN\_IMAGE
if (ep_info not EL3) synchronous exception if (ep_info not EL3) synchronous exception
This SMC passes execution control to an EL3 image described by the provided This SMC passes execution control to an EL3 image described by the provided
``entry_point_info_t`` structure. In the normal TF boot flow, BL2 invokes this SMC ``entry_point_info_t`` structure. In the normal TF-A boot flow, BL2 invokes
for BL1 to pass execution control to BL31. this SMC for BL1 to pass execution control to BL31.
FWU\_SMC\_IMAGE\_COPY FWU\_SMC\_IMAGE\_COPY
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~
@ -400,7 +400,7 @@ This is only allowed if the image is not being executed.
-------------- --------------
*Copyright (c) 2015-2017, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2015-2018, Arm Limited and Contributors. All rights reserved.*
.. _Trusted Board Boot: ./trusted-board-boot.rst .. _Trusted Board Boot: ./trusted-board-boot.rst
.. _Porting Guide: ./porting-guide.rst .. _Porting Guide: ./porting-guide.rst

47
docs/interrupt-framework-design.rst
View file

@ -1,5 +1,5 @@
ARM Trusted Firmware Interrupt Management Design guide Trusted Firmware-A interrupt management design guide
====================================================== ====================================================
.. section-numbering:: .. section-numbering::
@ -88,8 +88,8 @@ The framework considers certain routing models for each type of interrupt to be
incorrect as they conflict with the requirements mentioned in Section 1. The incorrect as they conflict with the requirements mentioned in Section 1. The
following sub-sections describe all the possible routing models and specify following sub-sections describe all the possible routing models and specify
which ones are valid or invalid. EL3 interrupts are currently supported only which ones are valid or invalid. EL3 interrupts are currently supported only
for GIC version 3.0 (ARM GICv3) and only the Secure-EL1 and Non-secure interrupt for GIC version 3.0 (Arm GICv3) and only the Secure-EL1 and Non-secure interrupt
types are supported for GIC version 2.0 (ARM GICv2) (See 1.2). The terminology types are supported for GIC version 2.0 (Arm GICv2) (See 1.2). The terminology
used in the following sub-sections is explained below. used in the following sub-sections is explained below.
#. **CSS**. Current Security State. ``0`` when secure and ``1`` when non-secure #. **CSS**. Current Security State. ``0`` when secure and ``1`` when non-secure
@ -111,7 +111,7 @@ Secure-EL1 interrupts
#. **CSS=1, TEL3=0**. Interrupt is routed to the FEL when execution is in #. **CSS=1, TEL3=0**. Interrupt is routed to the FEL when execution is in
non-secure state. This is an invalid routing model as a secure interrupt non-secure state. This is an invalid routing model as a secure interrupt
is not visible to the secure software which violates the motivation behind is not visible to the secure software which violates the motivation behind
the ARM Security Extensions. the Arm Security Extensions.
#. **CSS=1, TEL3=1**. Interrupt is routed to EL3 when execution is in #. **CSS=1, TEL3=1**. Interrupt is routed to EL3 when execution is in
non-secure state. This is a valid routing model as secure software in EL3 non-secure state. This is a valid routing model as secure software in EL3
@ -162,7 +162,7 @@ EL3 interrupts
#. **CSS=1, TEL3=0**. Interrupt is routed to the FEL when execution is in #. **CSS=1, TEL3=0**. Interrupt is routed to the FEL when execution is in
non-secure state. This is an invalid routing model as a secure interrupt non-secure state. This is an invalid routing model as a secure interrupt
is not visible to the secure software which violates the motivation behind is not visible to the secure software which violates the motivation behind
the ARM Security Extensions. the Arm Security Extensions.
#. **CSS=1, TEL3=1**. Interrupt is routed to EL3 when execution is in #. **CSS=1, TEL3=1**. Interrupt is routed to EL3 when execution is in
non-secure state. This is a valid routing model as secure software in EL3 non-secure state. This is a valid routing model as secure software in EL3
@ -179,7 +179,7 @@ uses this information to determine whether the IRQ or the FIQ bit should be
programmed in ``SCR_EL3`` while applying the routing model for a type of programmed in ``SCR_EL3`` while applying the routing model for a type of
interrupt. The platform provides this information through the interrupt. The platform provides this information through the
``plat_interrupt_type_to_line()`` API (described in the ``plat_interrupt_type_to_line()`` API (described in the
`Porting Guide`_). For example, on the FVP port when the platform uses an ARM GICv2 `Porting Guide`_). For example, on the FVP port when the platform uses an Arm GICv2
interrupt controller, Secure-EL1 interrupts are signaled through the FIQ signal interrupt controller, Secure-EL1 interrupts are signaled through the FIQ signal
while Non-secure interrupts are signaled through the IRQ signal. This applies while Non-secure interrupts are signaled through the IRQ signal. This applies
when execution is in either security state. when execution is in either security state.
@ -194,7 +194,7 @@ that security state. This means that all the other interrupt types using the
same interrupt signal will be forced to the same routing model. This should be same interrupt signal will be forced to the same routing model. This should be
borne in mind when choosing the routing model for an interrupt type. borne in mind when choosing the routing model for an interrupt type.
For example, in ARM GICv3, when the execution context is Secure-EL1/ For example, in Arm GICv3, when the execution context is Secure-EL1/
Secure-EL0, both the EL3 and the non secure interrupt types map to the FIQ Secure-EL0, both the EL3 and the non secure interrupt types map to the FIQ
signal. So if either one of the interrupt type sets the routing model so signal. So if either one of the interrupt type sets the routing model so
that **TEL3=1** when **CSS=0**, the FIQ bit in ``SCR_EL3`` will be programmed to that **TEL3=1** when **CSS=0**, the FIQ bit in ``SCR_EL3`` will be programmed to
@ -208,8 +208,8 @@ The framework makes the following assumptions to simplify its implementation.
#. Although the framework has support for 2 types of secure interrupts (EL3 #. Although the framework has support for 2 types of secure interrupts (EL3
and Secure-EL1 interrupt), only interrupt controller architectures and Secure-EL1 interrupt), only interrupt controller architectures
like ARM GICv3 has architectural support for EL3 interrupts in the form of like Arm GICv3 has architectural support for EL3 interrupts in the form of
Group 0 interrupts. In ARM GICv2, all secure interrupts are assumed to be Group 0 interrupts. In Arm GICv2, all secure interrupts are assumed to be
handled in Secure-EL1. They can be delivered to Secure-EL1 via EL3 but they handled in Secure-EL1. They can be delivered to Secure-EL1 via EL3 but they
cannot be handled in EL3. cannot be handled in EL3.
@ -260,7 +260,7 @@ the non-secure interrupts and target them to the primary CPU. It should also
export the interface described in the `Porting Guide`_ to enable export the interface described in the `Porting Guide`_ to enable
handling of interrupts. handling of interrupts.
In the remainder of this document, for the sake of simplicity a ARM GICv2 system In the remainder of this document, for the sake of simplicity a Arm GICv2 system
is considered and it is assumed that the FIQ signal is used to generate Secure-EL1 is considered and it is assumed that the FIQ signal is used to generate Secure-EL1
interrupts and the IRQ signal is used to generate non-secure interrupts in either interrupts and the IRQ signal is used to generate non-secure interrupts in either
security state. EL3 interrupts are not considered. security state. EL3 interrupts are not considered.
@ -272,8 +272,7 @@ Roles and responsibilities for interrupt management are sub-divided between the
following components of software running in EL3 and Secure-EL1. Each component is following components of software running in EL3 and Secure-EL1. Each component is
briefly described below. briefly described below.
#. EL3 Runtime Firmware. This component is common to all ports of the ARM #. EL3 Runtime Firmware. This component is common to all ports of TF-A.
Trusted Firmware.
#. Secure Payload Dispatcher (SPD) service. This service interfaces with the #. Secure Payload Dispatcher (SPD) service. This service interfaces with the
Secure Payload (SP) software which runs in Secure-EL1/Secure-EL0 and is Secure Payload (SP) software which runs in Secure-EL1/Secure-EL0 and is
@ -282,20 +281,20 @@ briefly described below.
exported by the Context management library to implement this functionality. exported by the Context management library to implement this functionality.
Switching execution between the two security states is a requirement for Switching execution between the two security states is a requirement for
interrupt management as well. This results in a significant dependency on interrupt management as well. This results in a significant dependency on
the SPD service. ARM Trusted firmware implements an example Test Secure the SPD service. TF-A implements an example Test Secure Payload Dispatcher
Payload Dispatcher (TSPD) service. (TSPD) service.
An SPD service plugs into the EL3 runtime firmware and could be common to An SPD service plugs into the EL3 runtime firmware and could be common to
some ports of the ARM Trusted Firmware. some ports of TF-A.
#. Secure Payload (SP). On a production system, the Secure Payload corresponds #. Secure Payload (SP). On a production system, the Secure Payload corresponds
to a Secure OS which runs in Secure-EL1/Secure-EL0. It interfaces with the to a Secure OS which runs in Secure-EL1/Secure-EL0. It interfaces with the
SPD service to manage communication with non-secure software. ARM Trusted SPD service to manage communication with non-secure software. TF-A
Firmware implements an example secure payload called Test Secure Payload implements an example secure payload called Test Secure Payload (TSP)
(TSP) which runs only in Secure-EL1. which runs only in Secure-EL1.
A Secure payload implementation could be common to some ports of the ARM A Secure payload implementation could be common to some ports of TF-A,
Trusted Firmware just like the SPD service. just like the SPD service.
Interrupt registration Interrupt registration
---------------------- ----------------------
@ -515,7 +514,7 @@ the interrupt routing model is not known to the SPD service at compile time,
then the SP should pass this information to the SPD service at runtime during then the SP should pass this information to the SPD service at runtime during
its initialisation phase. its initialisation phase.
As mentioned earlier, a ARM GICv2 system is considered and it is assumed that As mentioned earlier, an Arm GICv2 system is considered and it is assumed that
the FIQ signal is used to generate Secure-EL1 interrupts and the IRQ signal the FIQ signal is used to generate Secure-EL1 interrupts and the IRQ signal
is used to generate non-secure interrupts in either security state. is used to generate non-secure interrupts in either security state.
@ -595,7 +594,7 @@ exceptions taken at the same (Secure-EL1) exception level. This table is
referenced through the ``tsp_exceptions`` variable and programmed into the referenced through the ``tsp_exceptions`` variable and programmed into the
VBAR\_EL1. It caters for the asynchronous handling model. VBAR\_EL1. It caters for the asynchronous handling model.
The TSP also programs the Secure Physical Timer in the ARM Generic Timer block The TSP also programs the Secure Physical Timer in the Arm Generic Timer block
to raise a periodic interrupt (every half a second) for the purpose of testing to raise a periodic interrupt (every half a second) for the purpose of testing
interrupt management across all the software components listed in 2.1 interrupt management across all the software components listed in 2.1
@ -999,7 +998,7 @@ TSP by returning ``SMC_UNK`` error.
-------------- --------------
*Copyright (c) 2014-2018, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2014-2018, Arm Limited and Contributors. All rights reserved.*
.. _Porting Guide: ./porting-guide.rst .. _Porting Guide: ./porting-guide.rst
.. _SMC calling convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html .. _SMC calling convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html

6
docs/plat/hikey.rst
View file

@ -11,7 +11,7 @@ How to build
Code Locations Code Locations
-------------- --------------
- ARM Trusted Firmware: - Trusted Firmware-A:
`link <https://github.com/ARM-software/arm-trusted-firmware>`__ `link <https://github.com/ARM-software/arm-trusted-firmware>`__
- OP-TEE - OP-TEE
@ -76,13 +76,13 @@ Build Procedure
export UEFI_TOOLS_DIR=${BUILD_PATH}/uefi-tools export UEFI_TOOLS_DIR=${BUILD_PATH}/uefi-tools
export EDK2_DIR=${BUILD_PATH}/edk2 export EDK2_DIR=${BUILD_PATH}/edk2
EDK2_OUTPUT_DIR=${EDK2_DIR}/Build/HiKey/${BUILD_OPTION}_${AARCH64_TOOLCHAIN} EDK2_OUTPUT_DIR=${EDK2_DIR}/Build/HiKey/${BUILD_OPTION}_${AARCH64_TOOLCHAIN}
# Build fastboot for ARM Trust Firmware. It's used for recovery mode. # Build fastboot for Trusted Firmware-A. It's used for recovery mode.
cd ${BUILD_PATH}/atf-fastboot cd ${BUILD_PATH}/atf-fastboot
CROSS_COMPILE=aarch64-linux-gnu- make PLAT=hikey DEBUG=1 CROSS_COMPILE=aarch64-linux-gnu- make PLAT=hikey DEBUG=1
# Convert DEBUG/RELEASE to debug/release # Convert DEBUG/RELEASE to debug/release
FASTBOOT_BUILD_OPTION=$(echo ${BUILD_OPTION} | tr '[A-Z]' '[a-z]') FASTBOOT_BUILD_OPTION=$(echo ${BUILD_OPTION} | tr '[A-Z]' '[a-z]')
cd ${EDK2_DIR} cd ${EDK2_DIR}
# Build UEFI & ARM Trust Firmware # Build UEFI & Trusted Firmware-A
${UEFI_TOOLS_DIR}/uefi-build.sh -b ${BUILD_OPTION} -a ../arm-trusted-firmware -s ../optee_os hikey ${UEFI_TOOLS_DIR}/uefi-build.sh -b ${BUILD_OPTION} -a ../arm-trusted-firmware -s ../optee_os hikey
- Generate l-loader.bin and partition table for aosp. The eMMC capacity is either 8GB or 4GB. Just change "aosp-8g" to "linux-8g" for debian. - Generate l-loader.bin and partition table for aosp. The eMMC capacity is either 8GB or 4GB. Just change "aosp-8g" to "linux-8g" for debian.

4
docs/plat/hikey960.rst
View file

@ -11,7 +11,7 @@ How to build
Code Locations Code Locations
-------------- --------------
- ARM Trusted Firmware: - Trusted Firmware-A:
`link <https://github.com/ARM-software/arm-trusted-firmware>`__ `link <https://github.com/ARM-software/arm-trusted-firmware>`__
- OP-TEE: - OP-TEE:
@ -73,7 +73,7 @@ Build Procedure
export EDK2_DIR=${BUILD_PATH}/edk2 export EDK2_DIR=${BUILD_PATH}/edk2
EDK2_OUTPUT_DIR=${EDK2_DIR}/Build/HiKey960/${BUILD_OPTION}_${AARCH64_TOOLCHAIN} EDK2_OUTPUT_DIR=${EDK2_DIR}/Build/HiKey960/${BUILD_OPTION}_${AARCH64_TOOLCHAIN}
cd ${EDK2_DIR} cd ${EDK2_DIR}
# Build UEFI & ARM Trust Firmware # Build UEFI & Trusted Firmware-A
${UEFI_TOOLS_DIR}/uefi-build.sh -b ${BUILD_OPTION} -a ../arm-trusted-firmware -s ../optee_os hikey960 ${UEFI_TOOLS_DIR}/uefi-build.sh -b ${BUILD_OPTION} -a ../arm-trusted-firmware -s ../optee_os hikey960
- Generate l-loader.bin and partition table. - Generate l-loader.bin and partition table.

12
docs/plat/nvidia-tegra.rst
View file

@ -4,10 +4,10 @@ Tegra SoCs - Overview
- .. rubric:: T210 - .. rubric:: T210
:name: t210 :name: t210
T210 has Quad ARM® Cortex®-A57 cores in a switched configuration with a T210 has Quad Arm® Cortex®-A57 cores in a switched configuration with a
companion set of quad ARM Cortex-A53 cores. The Cortex-A57 and A53 cores companion set of quad Arm Cortex-A53 cores. The Cortex-A57 and A53 cores
support ARMv8, executing both 64-bit Aarch64 code, and 32-bit Aarch32 code support Armv8-A, executing both 64-bit Aarch64 code, and 32-bit Aarch32 code
including legacy ARMv7 applications. The Cortex-A57 processors each have including legacy Armv7-A applications. The Cortex-A57 processors each have
48 KB Instruction and 32 KB Data Level 1 caches; and have a 2 MB shared 48 KB Instruction and 32 KB Data Level 1 caches; and have a 2 MB shared
Level 2 unified cache. The Cortex-A53 processors each have 32 KB Instruction Level 2 unified cache. The Cortex-A53 processors each have 32 KB Instruction
and 32 KB Data Level 1 caches; and have a 512 KB shared Level 2 unified cache. and 32 KB Data Level 1 caches; and have a 512 KB shared Level 2 unified cache.
@ -16,7 +16,7 @@ and 32 KB Data Level 1 caches; and have a 512 KB shared Level 2 unified cache.
:name: t132 :name: t132
Denver is NVIDIA's own custom-designed, 64-bit, dual-core CPU which is Denver is NVIDIA's own custom-designed, 64-bit, dual-core CPU which is
fully ARMv8 architecture compatible. Each of the two Denver cores fully Armv8-A architecture compatible. Each of the two Denver cores
implements a 7-way superscalar microarchitecture (up to 7 concurrent implements a 7-way superscalar microarchitecture (up to 7 concurrent
micro-ops can be executed per clock), and includes a 128KB 4-way L1 micro-ops can be executed per clock), and includes a 128KB 4-way L1
instruction cache, a 64KB 4-way L1 data cache, and a 2MB 16-way L2 instruction cache, a 64KB 4-way L1 data cache, and a 2MB 16-way L2
@ -94,5 +94,5 @@ Tegra configs
============= =============
- 'tegra\_enable\_l2\_ecc\_parity\_prot': This flag enables the L2 ECC and Parity - 'tegra\_enable\_l2\_ecc\_parity\_prot': This flag enables the L2 ECC and Parity
Protection bit, for ARM Cortex-A57 CPUs, during CPU boot. This flag will Protection bit, for Arm Cortex-A57 CPUs, during CPU boot. This flag will
be enabled by Tegrs SoCs during 'Cluster power up' or 'System Suspend' exit. be enabled by Tegrs SoCs during 'Cluster power up' or 'System Suspend' exit.

10
docs/plat/poplar.rst
View file

@ -5,7 +5,7 @@ Poplar is the first development board compliant with the 96Boards Enterprise
Edition TV Platform specification. Edition TV Platform specification.
The board features the Hi3798C V200 with an integrated quad-core 64-bit The board features the Hi3798C V200 with an integrated quad-core 64-bit
ARM Cortex A53 processor and high performance Mali T720 GPU, making it capable Arm Cortex A53 processor and high performance Mali T720 GPU, making it capable
of running any commercial set-top solution based on Linux or Android. of running any commercial set-top solution based on Linux or Android.
It supports a premium user experience with up to H.265 HEVC decoding of 4K It supports a premium user experience with up to H.265 HEVC decoding of 4K
@ -14,7 +14,7 @@ video at 60 frames per second.
:: ::
SOC Hisilicon Hi3798CV200 SOC Hisilicon Hi3798CV200
CPU Quad-core ARM Cortex-A53 64 bit CPU Quad-core Arm Cortex-A53 64 bit
DRAM DDR3/3L/4 SDRAM interface, maximum 32-bit data width 2 GB DRAM DDR3/3L/4 SDRAM interface, maximum 32-bit data width 2 GB
USB Two USB 2.0 ports One USB 3.0 ports USB Two USB 2.0 ports One USB 3.0 ports
CONSOLE USB-micro port for console support CONSOLE USB-micro port for console support
@ -28,11 +28,11 @@ video at 60 frames per second.
At the start of the boot sequence, the bootROM executes the so called l-loader At the start of the boot sequence, the bootROM executes the so called l-loader
binary whose main role is to change the processor state to 64bit mode. This binary whose main role is to change the processor state to 64bit mode. This
must happen prior invoking the arm trusted firmware: must happen prior to invoking Trusted Firmware-A:
:: ::
l-loader --> arm_trusted_firmware --> u-boot l-loader --> Trusted Firmware-A --> u-boot
How to build How to build
============ ============
@ -40,7 +40,7 @@ How to build
Code Locations Code Locations
-------------- --------------
- ARM Trusted Firmware: - Trusted Firmware-A:
`link <https://github.com/ARM-software/arm-trusted-firmware>`__ `link <https://github.com/ARM-software/arm-trusted-firmware>`__
- l-loader: - l-loader:

10
docs/plat/qemu.rst
View file

@ -1,8 +1,8 @@
ARM Trusted Firmware for QEMU virt ARMv8-A Trusted Firmware-A for QEMU virt Armv8-A
========================================== ========================================
ARM Trusted Firmware implements the EL3 firmware layer for QEMU virt Trusted Firmware-A (TF-A) implements the EL3 firmware layer for QEMU virt
ARMv8-A. BL1 is used as the BootROM, supplied with the -bios argument. Armv8-A. BL1 is used as the BootROM, supplied with the -bios argument.
When QEMU starts all CPUs are released simultaneously, BL1 selects a When QEMU starts all CPUs are released simultaneously, BL1 selects a
primary CPU to handle the boot and the secondaries are placed in a polling primary CPU to handle the boot and the secondaries are placed in a polling
loop to be released by normal world via PSCI. loop to be released by normal world via PSCI.
@ -10,7 +10,7 @@ loop to be released by normal world via PSCI.
BL2 edits the Flattened Device Tree, FDT, generated by QEMU at run-time to BL2 edits the Flattened Device Tree, FDT, generated by QEMU at run-time to
add a node describing PSCI and also enable methods for the CPUs. add a node describing PSCI and also enable methods for the CPUs.
An ARM64 defonfig v4.5 Linux kernel is known to boot, FTD doesn't need to be An ARM64 defconfig v4.5 Linux kernel is known to boot, FDT doesn't need to be
provided as it's generated by QEMU. provided as it's generated by QEMU.
Current limitations: Current limitations:

90
docs/plat/rpi3.rst
View file

@ -1,5 +1,5 @@
Arm Trusted Firmware for Raspberry Pi 3 Trusted Firmware-A for Raspberry Pi 3
======================================= =====================================
.. section-numbering:: .. section-numbering::
:suffix: . :suffix: .
@ -7,16 +7,16 @@ Arm Trusted Firmware for Raspberry Pi 3
.. contents:: .. contents::
The `Raspberry Pi 3`_ is an inexpensive single-board computer that contains four The `Raspberry Pi 3`_ is an inexpensive single-board computer that contains four
Cortex-A53 cores, which makes it possible to have a port of the Arm Trusted Arm Cortex-A53 cores, which makes it possible to have a port of Trusted
Firmware. Firmware-A (TF-A).
The following instructions explain how to use this port of the Trusted Firmware The following instructions explain how to use this port of the TF-A with the
with the default distribution of `Raspbian`_ because that's the distribution default distribution of `Raspbian`_ because that's the distribution officially
officially supported by the Raspberry Pi Foundation. At the moment of writing supported by the Raspberry Pi Foundation. At the moment of writing this, the
this, the officially supported kernel is a AArch32 kernel. This doesn't mean officially supported kernel is a AArch32 kernel. This doesn't mean that this
that this port of the Trusted Firmware can't boot a AArch64 kernel. The `Linux port of TF-A can't boot a AArch64 kernel. The `Linux tree fork`_ maintained by
tree fork`_ maintained by the Foundation can be compiled for AArch64 by the Foundation can be compiled for AArch64 by following the steps in
following the steps in `AArch64 kernel build instructions`_. `AArch64 kernel build instructions`_.
**IMPORTANT NOTE**: This port isn't secure. All of the memory used is DRAM, **IMPORTANT NOTE**: This port isn't secure. All of the memory used is DRAM,
which is available from both the Non-secure and Secure worlds. This port which is available from both the Non-secure and Secure worlds. This port
@ -46,15 +46,15 @@ The rules are simple:
the cores are powered on at the same time and start at address **0x0**. the cores are powered on at the same time and start at address **0x0**.
This means that we can use the default AArch32 kernel provided in the official This means that we can use the default AArch32 kernel provided in the official
`Raspbian`_ distribution by renaming it to ``kernel8.img``, while the Trusted `Raspbian`_ distribution by renaming it to ``kernel8.img``, while TF-A and
Firmware and anything else we need is in ``armstub8.bin``. This way we can anything else we need is in ``armstub8.bin``. This way we can forget about the
forget about the default bootstrap code. When using a AArch64 kernel, it is only default bootstrap code. When using a AArch64 kernel, it is only needed to make
needed to make sure that the name on the SD card is ``kernel8.img``. sure that the name on the SD card is ``kernel8.img``.
Ideally, we want to load the kernel and have all cores available, which means Ideally, we want to load the kernel and have all cores available, which means
that we need to make the secondary cores work in the way the kernel expects, as that we need to make the secondary cores work in the way the kernel expects, as
explained in `Secondary cores`_. In practice, a small bootstrap is needed explained in `Secondary cores`_. In practice, a small bootstrap is needed
between the Trusted Firmware and the kernel. between TF-A and the kernel.
To get the most out of a AArch32 kernel, we want to boot it in Hypervisor mode To get the most out of a AArch32 kernel, we want to boot it in Hypervisor mode
in AArch32. This means that BL33 can't be in EL2 in AArch64 mode. The in AArch32. This means that BL33 can't be in EL2 in AArch64 mode. The
@ -66,7 +66,7 @@ Placement of images
The file ``armstub8.bin`` contains BL1 and the FIP. It is needed to add padding The file ``armstub8.bin`` contains BL1 and the FIP. It is needed to add padding
between them so that the addresses they are loaded to match the ones specified between them so that the addresses they are loaded to match the ones specified
when compiling the Trusted Firmware. when compiling TF-A.
The device tree block is loaded by the VideoCore loader from an appropriate The device tree block is loaded by the VideoCore loader from an appropriate
file, but we can specify the address it is loaded to in ``config.txt``. file, but we can specify the address it is loaded to in ``config.txt``.
@ -87,8 +87,8 @@ There are no similar restrictions for AArch64 kernels, as specified in the file
``Documentation/arm64/booting.txt``. ``Documentation/arm64/booting.txt``.
This means that we need to avoid the first 128 MiB of RAM when placing the This means that we need to avoid the first 128 MiB of RAM when placing the
Trusted Firmware images (and specially the first 32 MiB, as they are directly TF-A images (and specially the first 32 MiB, as they are directly used to
used to place the uncompressed AArch32 kernel image. This way, both AArch32 and place the uncompressed AArch32 kernel image. This way, both AArch32 and
AArch64 kernels can be placed at the same address. AArch64 kernels can be placed at the same address.
In the end, the images look like the following diagram when placed in memory. In the end, the images look like the following diagram when placed in memory.
@ -143,18 +143,17 @@ different mappings than the Arm cores in which the I/O addresses don't overlap
the DRAM. The memory reserved to be used by the VideoCore is always placed at the DRAM. The memory reserved to be used by the VideoCore is always placed at
the end of the DRAM, so this space isn't wasted. the end of the DRAM, so this space isn't wasted.
Considering the 128 MiB allocated to the GPU and the 16 MiB allocated for the Considering the 128 MiB allocated to the GPU and the 16 MiB allocated for
Trusted Firmware, there are 880 MiB available for Linux. TF-A, there are 880 MiB available for Linux.
Boot sequence Boot sequence
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
The boot sequence of the Trusted Firmware is the usual one except when booting The boot sequence of TF-A is the usual one except when booting an AArch32
a AArch32 kernel. In that case, BL33 is booted in AArch32 Hypervisor mode so kernel. In that case, BL33 is booted in AArch32 Hypervisor mode so that it
that it can jump to the kernel in the same mode and let it take over that can jump to the kernel in the same mode and let it take over that privilege
privilege level. If BL33 was running in EL2 in AArch64 (as in the default level. If BL33 was running in EL2 in AArch64 (as in the default bootflow of
bootflow of the Trusted Firmware) it could only jump to the kernel in AArch32 in TF-A) it could only jump to the kernel in AArch32 in Supervisor mode.
Supervisor mode.
The `Linux kernel tree`_ has instructions on how to jump to the Linux kernel The `Linux kernel tree`_ has instructions on how to jump to the Linux kernel
in ``Documentation/arm/Booting`` and ``Documentation/arm64/booting.txt``. The in ``Documentation/arm/Booting`` and ``Documentation/arm64/booting.txt``. The
@ -168,9 +167,9 @@ use mailboxes to trap the secondary cores until they are ready to jump to the
kernel. This mailbox is located at a different address in the AArch32 default kernel. This mailbox is located at a different address in the AArch32 default
kernel than in the AArch64 kernel. kernel than in the AArch64 kernel.
Also, this port of the Trusted Firmware has another Trusted Mailbox in Shared BL Also, this port of TF-A has another Trusted Mailbox in Shared BL RAM. During
RAM. During cold boot, all secondary cores wait in a loop until they are given cold boot, all secondary cores wait in a loop until they are given given an
given an address to jump to in this Mailbox (``bl31_warm_entrypoint``). address to jump to in this Mailbox (``bl31_warm_entrypoint``).
Once BL31 has finished and the primary core has jumped to the BL33 payload, it Once BL31 has finished and the primary core has jumped to the BL33 payload, it
has to call ``PSCI_CPU_ON`` to release the secondary CPUs from the wait loop. has to call ``PSCI_CPU_ON`` to release the secondary CPUs from the wait loop.
@ -188,11 +187,10 @@ To boot a AArch32 kernel, both AArch64 and AArch32 toolchains are required. The
AArch32 toolchain is needed for the AArch32 bootstrap needed to load a 32-bit AArch32 toolchain is needed for the AArch32 bootstrap needed to load a 32-bit
kernel. kernel.
First, clone and compile `Raspberry Pi 3 Arm Trusted Firmware bootstrap`_. First, clone and compile `Raspberry Pi 3 TF-A bootstrap`_. Choose the one
Choose the one needed for the architecture of your kernel. needed for the architecture of your kernel.
Then compile the Arm Trusted Firmware. For a AArch32 kernel, use the following Then compile TF-A. For a AArch32 kernel, use the following command line:
command line:
.. code:: shell .. code:: shell
@ -219,8 +217,8 @@ by ``debug`` if you set the build option ``DEBUG=1``):
cat bl1.pad.bin build/rpi3/release/fip.bin > armstub8.bin cat bl1.pad.bin build/rpi3/release/fip.bin > armstub8.bin
The resulting file, ``armstub8.bin``, contains BL1 and the FIP in the place they The resulting file, ``armstub8.bin``, contains BL1 and the FIP in the place they
need to be for the Trusted Firmware to boot correctly. Now, follow the need to be for TF-A to boot correctly. Now, follow the instructions in
instructions in `Setup SD card`_. `Setup SD card`_.
The following build options are supported: The following build options are supported:
@ -235,17 +233,17 @@ The following build options are supported:
is reserved by the command line passed to the kernel. is reserved by the command line passed to the kernel.
- ``RPI3_BL33_IN_AARCH32``: This port can load a AArch64 or AArch32 BL33 image. - ``RPI3_BL33_IN_AARCH32``: This port can load a AArch64 or AArch32 BL33 image.
By default this option is 0, which means that the Trusted Firmware will jump By default this option is 0, which means that TF-A will jump to BL33 in EL2
to BL33 in EL2 in AArch64 mode. If set to 1, it will jump to BL33 in in AArch64 mode. If set to 1, it will jump to BL33 in Hypervisor in AArch32
Hypervisor in AArch32 mode. mode.
The following is not currently supported: The following is not currently supported:
- AArch32 for the Trusted Firmware itself. - AArch32 for TF-A itself.
- ``EL3_PAYLOAD_BASE``: The reason is that you can already load anything to any - ``EL3_PAYLOAD_BASE``: The reason is that you can already load anything to any
address by changing the file ``armstub8.bin``, so there's no point in using address by changing the file ``armstub8.bin``, so there's no point in using
the Trusted Firmware in this case. TF-A in this case.
- ``LOAD_IMAGE_V2=0``: Only version 2 is supported. - ``LOAD_IMAGE_V2=0``: Only version 2 is supported.
@ -307,16 +305,16 @@ untouched). They have been tested with the image available in 2017-09-07.
1. Insert the SD card and open the ``boot`` partition. 1. Insert the SD card and open the ``boot`` partition.
2. Rename ``kernel7.img`` to ``kernel8.img``. This tricks the VideoCore 2. Rename ``kernel7.img`` to ``kernel8.img``. This tricks the VideoCore
bootloader into booting the Arm cores in AArch64 mode, like the Trusted bootloader into booting the Arm cores in AArch64 mode, like TF-A needs,
Firmware needs, even though the kernel is not compiled for AArch64. even though the kernel is not compiled for AArch64.
3. Copy ``armstub8.bin`` here. When ``kernel8.img`` is available, The VideoCore 3. Copy ``armstub8.bin`` here. When ``kernel8.img`` is available, The VideoCore
bootloader will look for a file called ``armstub8.bin`` and load it at bootloader will look for a file called ``armstub8.bin`` and load it at
address **0x0** instead of a predefined one. address **0x0** instead of a predefined one.
4. Open ``cmdline.txt`` and add ``memmap=256M$16M`` to prevent the kernel from 4. Open ``cmdline.txt`` and add ``memmap=256M$16M`` to prevent the kernel from
using the memory needed by the Trusted Firmware. If you want to enable the using the memory needed by TF-A. If you want to enable the serial port
serial port "Mini UART", make sure that this file also contains "Mini UART", make sure that this file also contains
``console=serial0,115200 console=tty1``. ``console=serial0,115200 console=tty1``.
Note that the 16 MiB reserved this way won't be available for Linux, the same Note that the 16 MiB reserved this way won't be available for Linux, the same
@ -359,6 +357,6 @@ HDMI output won't show any text during boot.
.. _Linux kernel tree: https://github.com/torvalds/linux .. _Linux kernel tree: https://github.com/torvalds/linux
.. _Linux tree fork: https://github.com/raspberrypi/linux .. _Linux tree fork: https://github.com/raspberrypi/linux
.. _Raspberry Pi 3: https://www.raspberrypi.org/products/raspberry-pi-3-model-b/ .. _Raspberry Pi 3: https://www.raspberrypi.org/products/raspberry-pi-3-model-b/
.. _Raspberry Pi 3 Arm Trusted Firmware bootstrap: https://github.com/AntonioND/rpi3-arm-tf-bootstrap .. _Raspberry Pi 3 TF-A bootstrap: https://github.com/AntonioND/rpi3-arm-tf-bootstrap
.. _Raspberry Pi 3 documentation: https://www.raspberrypi.org/documentation/ .. _Raspberry Pi 3 documentation: https://www.raspberrypi.org/documentation/
.. _Raspbian: https://www.raspberrypi.org/downloads/raspbian/ .. _Raspbian: https://www.raspberrypi.org/downloads/raspbian/

20
docs/plat/socionext-uniphier.rst
View file

@ -1,19 +1,19 @@
ARM Trusted Firmware for Socionext UniPhier SoCs Trusted Firmware-A for Socionext UniPhier SoCs
================================================ ==============================================
Socionext UniPhier ARMv8-A SoCs use ARM Trusted Firmware as the secure world Socionext UniPhier Armv8-A SoCs use Trusted Firmware-A (TF-A) as the secure
firmware, supporting BL2 and BL31. world firmware, supporting BL2 and BL31.
UniPhier SoC family implements its internal boot ROM, which loads 64KB [1]_ UniPhier SoC family implements its internal boot ROM, which loads 64KB [1]_
image from a non-volatile storage to the on-chip SRAM, and jumps over to it. image from a non-volatile storage to the on-chip SRAM, and jumps over to it.
ARM Trusted Firmware provides a special mode, BL2-AT-EL3, which enables BL2 to TF-A provides a special mode, BL2-AT-EL3, which enables BL2 to execute at EL3.
execute at EL3. It is useful for platforms with non-TF boot ROM, like UniPhier. It is useful for platforms with non-TF-A boot ROM, like UniPhier. Here, a
Here, a problem is BL2 does not fit in the 64KB limit if `Trusted Board Boot`_ problem is BL2 does not fit in the 64KB limit if `Trusted Board Boot`_ (TBB)
(TBB) is enabled. To solve this issue, Socionext provides a first stage loader is enabled. To solve this issue, Socionext provides a first stage loader
called `UniPhier BL`_. This loader runs in the on-chip SRAM, initializes the called `UniPhier BL`_. This loader runs in the on-chip SRAM, initializes the
DRAM, expands BL2 there, and hands the control over to it. Therefore, all images DRAM, expands BL2 there, and hands the control over to it. Therefore, all images
of ARM Trusted Firmware run in DRAM. of TF-A run in DRAM.
The UniPhier platform works with/without TBB. See below for the build process The UniPhier platform works with/without TBB. See below for the build process
of each case. The image authentication for the UniPhier platform fully of each case. The image authentication for the UniPhier platform fully
@ -46,7 +46,7 @@ Boot Flow
This runs in the DRAM. It extracts more images such as BL31, BL33 (optionally This runs in the DRAM. It extracts more images such as BL31, BL33 (optionally
SCP_BL2, BL32 as well) from Firmware Image Package (FIP). If TBB is enabled, SCP_BL2, BL32 as well) from Firmware Image Package (FIP). If TBB is enabled,
they are all authenticated by the standard mechanism of ARM Trusted Firmware. they are all authenticated by the standard mechanism of TF-A.
After loading all the images, it jumps to the BL31 entry. After loading all the images, it jumps to the BL31 entry.
4. BL31, BL32, and BL33 4. BL31, BL32, and BL33

22
docs/plat/xilinx-zynqmp.rst
View file

@ -1,12 +1,12 @@
ARM Trusted Firmware for Xilinx Zynq UltraScale+ MPSoC Trusted Firmware-A for Xilinx Zynq UltraScale+ MPSoC
====================================================== ====================================================
ARM Trusted Firmware implements the EL3 firmware layer for Xilinx Zynq Trusted Firmware-A (TF-A) implements the EL3 firmware layer for Xilinx Zynq
UltraScale + MPSoC. UltraScale + MPSoC.
The platform only uses the runtime part of ATF as ZynqMP already has a The platform only uses the runtime part of TF-A as ZynqMP already has a
BootROM (BL1) and FSBL (BL2). BootROM (BL1) and FSBL (BL2).
BL31 is ATF. BL31 is TF-A.
BL32 is an optional Secure Payload. BL32 is an optional Secure Payload.
BL33 is the non-secure world software (U-Boot, Linux etc). BL33 is the non-secure world software (U-Boot, Linux etc).
@ -35,20 +35,20 @@ ZynqMP platform specific build options
- ``cadence``, ``cadence0``: Cadence UART 0 - ``cadence``, ``cadence0``: Cadence UART 0
- ``cadence1`` : Cadence UART 1 - ``cadence1`` : Cadence UART 1
FSBL->ATF Parameter Passing FSBL->TF-A Parameter Passing
=========================== ===========================
The FSBL populates a data structure with image information for the ATF. The ATF The FSBL populates a data structure with image information for TF-A. TF-A uses
uses that data to hand off to the loaded images. The address of the handoff data that data to hand off to the loaded images. The address of the handoff data
structure is passed in the ``PMU_GLOBAL.GLOBAL_GEN_STORAGE6`` register. The structure is passed in the ``PMU_GLOBAL.GLOBAL_GEN_STORAGE6`` register. The
register is free to be used by other software once the ATF is bringing up register is free to be used by other software once TF-A has brought up
further firmware images. further firmware images.
Power Domain Tree Power Domain Tree
================= =================
The following power domain tree represents the power domain model used by the The following power domain tree represents the power domain model used by TF-A
ATF for ZynqMP: for ZynqMP:
:: ::

30
docs/platform-interrupt-controller-API.rst
View file

@ -24,7 +24,7 @@ This API should return the priority of the interrupt the PE is currently
servicing. This must be be called only after an interrupt has already been servicing. This must be be called only after an interrupt has already been
acknowledged via. ``plat_ic_acknowledge_interrupt``. acknowledged via. ``plat_ic_acknowledge_interrupt``.
In the case of ARM standard platforms using GIC, the *Running Priority Register* In the case of Arm standard platforms using GIC, the *Running Priority Register*
is read to determine the priority of the interrupt. is read to determine the priority of the interrupt.
Function: int plat_ic_is_spi(unsigned int id); [optional] Function: int plat_ic_is_spi(unsigned int id); [optional]
@ -77,7 +77,7 @@ Function: unsigned int plat_ic_get_interrupt_active(unsigned int id); [optional]
This API should return the *active* status of the interrupt ID specified by the This API should return the *active* status of the interrupt ID specified by the
first parameter, ``id``. first parameter, ``id``.
In case of ARM standard platforms using GIC, the implementation of the API reads In case of Arm standard platforms using GIC, the implementation of the API reads
the GIC *Set Active Register* to read and return the active status of the the GIC *Set Active Register* to read and return the active status of the
interrupt. interrupt.
@ -92,7 +92,7 @@ Function: void plat_ic_enable_interrupt(unsigned int id); [optional]
This API should enable the interrupt ID specified by the first parameter, This API should enable the interrupt ID specified by the first parameter,
``id``. PEs in the system are expected to receive only enabled interrupts. ``id``. PEs in the system are expected to receive only enabled interrupts.
In case of ARM standard platforms using GIC, the implementation of the API In case of Arm standard platforms using GIC, the implementation of the API
inserts barrier to make memory updates visible before enabling interrupt, and inserts barrier to make memory updates visible before enabling interrupt, and
then writes to GIC *Set Enable Register* to enable the interrupt. then writes to GIC *Set Enable Register* to enable the interrupt.
@ -107,7 +107,7 @@ Function: void plat_ic_disable_interrupt(unsigned int id); [optional]
This API should disable the interrupt ID specified by the first parameter, This API should disable the interrupt ID specified by the first parameter,
``id``. PEs in the system are not expected to receive disabled interrupts. ``id``. PEs in the system are not expected to receive disabled interrupts.
In case of ARM standard platforms using GIC, the implementation of the API In case of Arm standard platforms using GIC, the implementation of the API
writes to GIC *Clear Enable Register* to disable the interrupt, and inserts writes to GIC *Clear Enable Register* to disable the interrupt, and inserts
barrier to make memory updates visible afterwards. barrier to make memory updates visible afterwards.
@ -123,7 +123,7 @@ Function: void plat_ic_set_interrupt_priority(unsigned int id, unsigned int prio
This API should set the priority of the interrupt specified by first parameter This API should set the priority of the interrupt specified by first parameter
``id`` to the value set by the second parameter ``priority``. ``id`` to the value set by the second parameter ``priority``.
In case of ARM standard platforms using GIC, the implementation of the API In case of Arm standard platforms using GIC, the implementation of the API
writes to GIC *Priority Register* set interrupt priority. writes to GIC *Priority Register* set interrupt priority.
Function: int plat_ic_has_interrupt_type(unsigned int type); [optional] Function: int plat_ic_has_interrupt_type(unsigned int type); [optional]
@ -138,10 +138,10 @@ This API should return whether the platform supports a given interrupt type. The
parameter ``type`` shall be one of ``INTR_TYPE_EL3``, ``INTR_TYPE_S_EL1``, or parameter ``type`` shall be one of ``INTR_TYPE_EL3``, ``INTR_TYPE_S_EL1``, or
``INTR_TYPE_NS``. ``INTR_TYPE_NS``.
In case of ARM standard platforms using GICv3, the implementation of the API In case of Arm standard platforms using GICv3, the implementation of the API
returns ``1`` for all interrupt types. returns ``1`` for all interrupt types.
In case of ARM standard platforms using GICv2, the API always return ``1`` for In case of Arm standard platforms using GICv2, the API always return ``1`` for
``INTR_TYPE_NS``. Return value for other types depends on the value of build ``INTR_TYPE_NS``. Return value for other types depends on the value of build
option ``GICV2_G0_FOR_EL3``: option ``GICV2_G0_FOR_EL3``:
@ -180,7 +180,7 @@ one of:
- ``INTR_TYPE_EL3``: interrupt is meant to be consumed by EL3. - ``INTR_TYPE_EL3``: interrupt is meant to be consumed by EL3.
In case of ARM standard platforms using GIC, the implementation of the API In case of Arm standard platforms using GIC, the implementation of the API
writes to the GIC *Group Register* and *Group Modifier Register* (only GICv3) to writes to the GIC *Group Register* and *Group Modifier Register* (only GICv3) to
assign the interrupt to the right group. assign the interrupt to the right group.
@ -213,7 +213,7 @@ This API should raise an EL3 SGI. The first parameter, ``sgi_num``, specifies
the ID of the SGI. The second parameter, ``target``, must be the MPIDR of the the ID of the SGI. The second parameter, ``target``, must be the MPIDR of the
target PE. target PE.
In case of ARM standard platforms using GIC, the implementation of the API In case of Arm standard platforms using GIC, the implementation of the API
inserts barrier to make memory updates visible before raising SGI, then writes inserts barrier to make memory updates visible before raising SGI, then writes
to appropriate *SGI Register* in order to raise the EL3 SGI. to appropriate *SGI Register* in order to raise the EL3 SGI.
@ -239,7 +239,7 @@ The ``routing_mode`` parameter can be one of:
- ``INTR_ROUTING_MODE_PE`` means the interrupt is routed to the PE whose MPIDR - ``INTR_ROUTING_MODE_PE`` means the interrupt is routed to the PE whose MPIDR
value is specified by the parameter ``mpidr``. value is specified by the parameter ``mpidr``.
In case of ARM standard platforms using GIC, the implementation of the API In case of Arm standard platforms using GIC, the implementation of the API
writes to the GIC *Target Register* (GICv2) or *Route Register* (GICv3) to set writes to the GIC *Target Register* (GICv2) or *Route Register* (GICv3) to set
the routing. the routing.
@ -254,7 +254,7 @@ Function: void plat_ic_set_interrupt_pending(unsigned int id); [optional]
This API should set the interrupt specified by first parameter ``id`` to This API should set the interrupt specified by first parameter ``id`` to
*Pending*. *Pending*.
In case of ARM standard platforms using GIC, the implementation of the API In case of Arm standard platforms using GIC, the implementation of the API
inserts barrier to make memory updates visible before setting interrupt pending, inserts barrier to make memory updates visible before setting interrupt pending,
and writes to the GIC *Set Pending Register* to set the interrupt pending and writes to the GIC *Set Pending Register* to set the interrupt pending
status. status.
@ -270,7 +270,7 @@ Function: void plat_ic_clear_interrupt_pending(unsigned int id); [optional]
This API should clear the *Pending* status of the interrupt specified by first This API should clear the *Pending* status of the interrupt specified by first
parameter ``id``. parameter ``id``.
In case of ARM standard platforms using GIC, the implementation of the API In case of Arm standard platforms using GIC, the implementation of the API
writes to the GIC *Clear Pending Register* to clear the interrupt pending writes to the GIC *Clear Pending Register* to clear the interrupt pending
status, and inserts barrier to make memory updates visible afterwards. status, and inserts barrier to make memory updates visible afterwards.
@ -287,7 +287,7 @@ controller such that only interrupts of higher priority than the supplied one
may be signalled to the PE. The API should return the current priority value may be signalled to the PE. The API should return the current priority value
that it's overwriting. that it's overwriting.
In case of ARM standard platforms using GIC, the implementation of the API In case of Arm standard platforms using GIC, the implementation of the API
inserts to order memory updates before updating mask, then writes to the GIC inserts to order memory updates before updating mask, then writes to the GIC
*Priority Mask Register*, and make sure memory updates are visible before *Priority Mask Register*, and make sure memory updates are visible before
potential trigger due to mask update. potential trigger due to mask update.
@ -305,9 +305,9 @@ obtained by the acknowledging the interrupt (read using
``plat_ic_acknowledge_interrupt()``). If the interrupt ID is invalid, this API ``plat_ic_acknowledge_interrupt()``). If the interrupt ID is invalid, this API
should return ``INTR_ID_UNAVAILABLE``. should return ``INTR_ID_UNAVAILABLE``.
In case of ARM standard platforms using GIC, the implementation of the API In case of Arm standard platforms using GIC, the implementation of the API
masks out the interrupt ID field from the acknowledged value from GIC. masks out the interrupt ID field from the acknowledged value from GIC.
---- ----
*Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2017-2018, Arm Limited and Contributors. All rights reserved.*

16
docs/platform-migration-guide.rst
View file

@ -12,8 +12,8 @@ Guide to migrate to new Platform porting interface
Introduction Introduction
------------ ------------
The PSCI implementation in Trusted Firmware has undergone a redesign because of The PSCI implementation in TF-A has undergone a redesign because of three
three requirements that the PSCI 1.0 specification introduced : requirements that the PSCI 1.0 specification introduced :
- Removing the framework assumption about the structure of the MPIDR, and - Removing the framework assumption about the structure of the MPIDR, and
its relation to the power topology enables support for deeper and more its relation to the power topology enables support for deeper and more
@ -217,7 +217,7 @@ layer and the platform layer.
Refer `plat/arm/board/fvp/fvp\_pm.c`_ for the implementation details of Refer `plat/arm/board/fvp/fvp\_pm.c`_ for the implementation details of
these handlers for the FVP. The commit `38dce70f51fb83b27958ba3e2ad15f5635cb1061`_ these handlers for the FVP. The commit `38dce70f51fb83b27958ba3e2ad15f5635cb1061`_
demonstrates the migration of ARM reference platforms to the new platform API. demonstrates the migration of Arm reference platforms to the new platform API.
Miscellaneous modifications Miscellaneous modifications
--------------------------- ---------------------------
@ -271,7 +271,7 @@ within its domain. It does so by storing the core index of first core
within it and number of core indexes following it. This means that core within it and number of core indexes following it. This means that core
indices returned by ``platform_get_core_pos()`` for cores within a particular indices returned by ``platform_get_core_pos()`` for cores within a particular
power domain must be consecutive. We expect that this is the case for most power domain must be consecutive. We expect that this is the case for most
platform ports including ARM reference platforms. platform ports including Arm reference platforms.
The old PSCI helpers like ``psci_get_suspend_powerstate()``, The old PSCI helpers like ``psci_get_suspend_powerstate()``,
``psci_get_suspend_stateid()``, ``psci_get_suspend_stateid_by_mpidr()``, ``psci_get_suspend_stateid()``, ``psci_get_suspend_stateid_by_mpidr()``,
@ -298,7 +298,7 @@ The mandatory macros to be defined by the platform port in ``platform_def.h``
- **#define : PLATFORM\_MAX\_AFFLVL** - **#define : PLATFORM\_MAX\_AFFLVL**
Defines the maximum affinity level that the power management operations Defines the maximum affinity level that the power management operations
should apply to. ARMv8-A has support for four affinity levels. It is likely should apply to. Armv8-A has support for four affinity levels. It is likely
that hardware will implement fewer affinity levels. This macro allows the that hardware will implement fewer affinity levels. This macro allows the
PSCI implementation to consider only those affinity levels in the system 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
@ -329,7 +329,7 @@ to handle the condition where the core has been warm reset but there is no
entrypoint to jump to. entrypoint to jump to.
This function does not follow the Procedure Call Standard used by the This function does not follow the Procedure Call Standard used by the
Application Binary Interface for the ARM 64-bit architecture. The caller should Application Binary Interface for the Arm 64-bit architecture. The caller should
not assume that callee saved registers are preserved across a call to this not assume that callee saved registers are preserved across a call to this
function. function.
@ -410,7 +410,7 @@ Modifications for Power State Coordination Interface (in BL31)
-------------------------------------------------------------- --------------------------------------------------------------
The following functions must be implemented to initialize PSCI functionality in The following functions must be implemented to initialize PSCI functionality in
the ARM Trusted Firmware. TF-A.
Function : plat\_get\_aff\_count() [mandatory] Function : plat\_get\_aff\_count() [mandatory]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -595,7 +595,7 @@ PSCI specification for the CPU\_SUSPEND API.
-------------- --------------
*Copyright (c) 2015, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2015-2018, Arm Limited and Contributors. All rights reserved.*
.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
.. _Porting Guide: porting-guide.rst#user-content-function--plat_my_core_pos .. _Porting Guide: porting-guide.rst#user-content-function--plat_my_core_pos

196
docs/porting-guide.rst
View file

@ -1,5 +1,5 @@
ARM Trusted Firmware Porting Guide Trusted Firmware-A Porting Guide
================================== ================================
.. section-numbering:: .. section-numbering::
@ -16,7 +16,7 @@ Please note that this document has been updated for the new platform API
as required by the PSCI v1.0 implementation. Please refer to the as required by the PSCI v1.0 implementation. Please refer to the
`Migration Guide`_ for the previous platform API. `Migration Guide`_ for the previous platform API.
Porting the ARM Trusted Firmware to a new platform involves making some Porting Trusted Firmware-A (TF-A) to a new platform involves making some
mandatory and optional modifications for both the cold and warm boot paths. mandatory and optional modifications for both the cold and warm boot paths.
Modifications consist of: Modifications consist of:
@ -31,20 +31,19 @@ implementations are all weakly defined; they are provided to ease the porting
effort. Each platform port can override them with its own implementation if the effort. Each platform port can override them with its own implementation if the
default implementation is inadequate. default implementation is inadequate.
Platform ports that want to be aligned with standard ARM platforms (for example Platform ports that want to be aligned with standard Arm platforms (for example
FVP and Juno) may also use `include/plat/arm/common/plat\_arm.h`_ and the FVP and Juno) may also use `include/plat/arm/common/plat\_arm.h`_ and the
corresponding source files in ``plat/arm/common/``. These provide standard corresponding source files in ``plat/arm/common/``. These provide standard
implementations for some of the required platform porting functions. However, implementations for some of the required platform porting functions. However,
using these functions requires the platform port to implement additional using these functions requires the platform port to implement additional
ARM standard platform porting functions. These additional functions are not Arm standard platform porting functions. These additional functions are not
documented here. documented here.
Some modifications are common to all Boot Loader (BL) stages. Section 2 Some modifications are common to all Boot Loader (BL) stages. Section 2
discusses these in detail. The subsequent sections discuss the remaining discusses these in detail. The subsequent sections discuss the remaining
modifications for each BL stage in detail. modifications for each BL stage in detail.
This document should be read in conjunction with the ARM Trusted Firmware This document should be read in conjunction with the TF-A `User Guide`_.
`User Guide`_.
Common modifications Common modifications
-------------------- --------------------
@ -67,11 +66,11 @@ only for re-mapping peripheral physical addresses and allows platforms with high
I/O addresses to reduce their virtual address space. All other addresses I/O addresses to reduce their virtual address space. All other addresses
corresponding to code and data must currently use an identity mapping. corresponding to code and data must currently use an identity mapping.
Also, the only translation granule size supported in Trusted Firmware is 4KB, as Also, the only translation granule size supported in TF-A is 4KB, as various
various parts of the code assume that is the case. It is not possible to switch parts of the code assume that is the case. It is not possible to switch to
to 16 KB or 64 KB granule sizes at the moment. 16 KB or 64 KB granule sizes at the moment.
In ARM standard platforms, each BL stage configures the MMU in the In Arm standard platforms, each BL stage configures the MMU in the
platform-specific architecture setup function, ``blX_plat_arch_setup()``, and uses platform-specific architecture setup function, ``blX_plat_arch_setup()``, and uses
an identity mapping for all addresses. an identity mapping for all addresses.
@ -106,14 +105,14 @@ File : platform\_def.h [mandatory]
Each platform must ensure that a header file of this name is in the system Each platform must ensure that a header file of this name is in the system
include path with the following constants defined. This may require updating the include path with the following constants defined. This may require updating the
list of ``PLAT_INCLUDES`` in the ``platform.mk`` file. In the ARM development list of ``PLAT_INCLUDES`` in the ``platform.mk`` file. In the Arm development
platforms, this file is found in ``plat/arm/board/<plat_name>/include/``. platforms, this file is found in ``plat/arm/board/<plat_name>/include/``.
Platform ports may optionally use the file `include/plat/common/common\_def.h`_, Platform ports may optionally use the file `include/plat/common/common\_def.h`_,
which provides typical values for some of the constants below. These values are which provides typical values for some of the constants below. These values are
likely to be suitable for all platform ports. likely to be suitable for all platform ports.
Platform ports that want to be aligned with standard ARM platforms (for example Platform ports that want to be aligned with standard Arm platforms (for example
FVP and Juno) may also use `include/plat/arm/common/arm\_def.h`_, which provides FVP and Juno) may also use `include/plat/arm/common/arm\_def.h`_, which provides
standard values for some of the constants below. However, this requires the standard values for some of the constants below. However, this requires the
platform port to define additional platform porting constants in platform port to define additional platform porting constants in
@ -293,9 +292,9 @@ also be defined:
- **#define : PLAT\_CRYPTOCELL\_BASE** - **#define : PLAT\_CRYPTOCELL\_BASE**
This defines the base address of ARM® TrustZone® CryptoCell and must be This defines the base address of Arm® TrustZone® CryptoCell and must be
defined if CryptoCell crypto driver is used for Trusted Board Boot. For defined if CryptoCell crypto driver is used for Trusted Board Boot. For
capable ARM platforms, this driver is used if ``ARM_CRYPTOCELL_INTEG`` is capable Arm platforms, this driver is used if ``ARM_CRYPTOCELL_INTEG`` is
set. set.
If the AP Firmware Updater Configuration image, BL2U is used, the following If the AP Firmware Updater Configuration image, BL2U is used, the following
@ -322,7 +321,7 @@ must also be defined:
SCP\_BL2U image identifier, used by BL1 to fetch an image descriptor SCP\_BL2U image identifier, used by BL1 to fetch an image descriptor
corresponding to SCP\_BL2U. corresponding to SCP\_BL2U.
NOTE: TF does not provide source code for this image. NOTE: TF-A does not provide source code for this image.
If the Non-Secure Firmware Updater ROM, NS\_BL1U is used, the following must If the Non-Secure Firmware Updater ROM, NS\_BL1U is used, the following must
also be defined: also be defined:
@ -331,7 +330,7 @@ also be defined:
Defines the base address in non-secure ROM where NS\_BL1U executes. Defines the base address in non-secure ROM where NS\_BL1U executes.
Must be aligned on a page-size boundary. Must be aligned on a page-size boundary.
NOTE: TF does not provide source code for this image. NOTE: TF-A does not provide source code for this image.
- **#define : NS\_BL1U\_IMAGE\_ID** - **#define : NS\_BL1U\_IMAGE\_ID**
@ -345,7 +344,7 @@ be defined:
Defines the base address in non-secure memory where NS\_BL2U executes. Defines the base address in non-secure memory where NS\_BL2U executes.
Must be aligned on a page-size boundary. Must be aligned on a page-size boundary.
NOTE: TF does not provide source code for this image. NOTE: TF-A does not provide source code for this image.
- **#define : NS\_BL2U\_IMAGE\_ID** - **#define : NS\_BL2U\_IMAGE\_ID**
@ -507,7 +506,7 @@ required memory within the the per-cpu data to minimize wastage.
structure for use by the platform layer. structure for use by the platform layer.
The following constants are optional. They should be defined when the platform The following constants are optional. They should be defined when the platform
memory layout implies some image overlaying like in ARM standard platforms. memory layout implies some image overlaying like in Arm standard platforms.
- **#define : BL31\_PROGBITS\_LIMIT** - **#define : BL31\_PROGBITS\_LIMIT**
@ -569,7 +568,7 @@ File : plat\_macros.S [mandatory]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Each platform must ensure a file of this name is in the system include path with Each platform must ensure a file of this name is in the system include path with
the following macro defined. In the ARM development platforms, this file is the following macro defined. In the Arm development platforms, this file is
found in ``plat/arm/board/<plat_name>/include/plat_macros.S``. found in ``plat/arm/board/<plat_name>/include/plat_macros.S``.
- **Macro : plat\_crash\_print\_regs** - **Macro : plat\_crash\_print\_regs**
@ -620,7 +619,7 @@ reset entrypoint point provided to ``plat_setup_psci_ops()`` during
BL31 initialization. If it's a cold reset then this function must return zero. BL31 initialization. If it's a cold reset then this function must return zero.
This function does not follow the Procedure Call Standard used by the This function does not follow the Procedure Call Standard used by the
Application Binary Interface for the ARM 64-bit architecture. The caller should Application Binary Interface for the Arm 64-bit architecture. The caller should
not assume that callee saved registers are preserved across a call to this not assume that callee saved registers are preserved across a call to this
function. function.
@ -644,7 +643,7 @@ for placing the executing secondary CPU in a platform-specific state until the
primary CPU performs the necessary actions to bring it out of that state and primary CPU performs the necessary actions to bring it out of that state and
allow entry into the OS. This function must not return. allow entry into the OS. This function must not return.
In the ARM FVP port, when using the normal boot flow, each secondary CPU powers In the Arm FVP port, when using the normal boot flow, each secondary CPU powers
itself off. The primary CPU is responsible for powering up the secondary CPUs itself off. The primary CPU is responsible for powering up the secondary CPUs
when normal world software requires them. When booting an EL3 payload instead, when normal world software requires them. When booting an EL3 payload instead,
they stay powered on and are put in a holding pen until their mailbox gets they stay powered on and are put in a holding pen until their mailbox gets
@ -827,9 +826,9 @@ This function validates the ``MPIDR`` of a CPU and converts it to an index,
which can be used as a CPU-specific linear index into blocks of memory. In which can be used as a CPU-specific linear index into blocks of memory. In
case the ``MPIDR`` is invalid, this function returns -1. This function will only case the ``MPIDR`` is invalid, this function returns -1. This function will only
be invoked by BL31 after the power domain topology is initialized and can be invoked by BL31 after the power domain topology is initialized and can
utilize the C runtime environment. For further details about how ARM Trusted utilize the C runtime environment. For further details about how TF-A
Firmware represents the power domain topology and how this relates to the represents the power domain topology and how this relates to the linear CPU
linear CPU index, please refer `Power Domain Topology Design`_. index, please refer `Power Domain Topology Design`_.
Common optional modifications Common optional modifications
----------------------------- -----------------------------
@ -896,8 +895,7 @@ about the way the platform displays its status information.
For AArch64, this function receives the exception type as its argument. For AArch64, this function receives the exception type as its argument.
Possible values for exceptions types are listed in the Possible values for exceptions types are listed in the
`include/common/bl\_common.h`_ header file. Note that these constants are not `include/common/bl\_common.h`_ header file. Note that these constants are not
related to any architectural exception code; they are just an ARM Trusted related to any architectural exception code; they are just a TF-A convention.
Firmware convention.
For AArch32, this function receives the exception mode as its argument. For AArch32, this function receives the exception mode as its argument.
Possible values for exception modes are listed in the Possible values for exception modes are listed in the
@ -954,8 +952,8 @@ Possible errors reported by the generic code are:
Board Boot is enabled) Board Boot is enabled)
- ``-ENOENT``: the requested image or certificate could not be found or an IO - ``-ENOENT``: the requested image or certificate could not be found or an IO
error was detected error was detected
- ``-ENOMEM``: resources exhausted. Trusted Firmware does not use dynamic - ``-ENOMEM``: resources exhausted. TF-A does not use dynamic memory, so this
memory, so this error is usually an indication of an incorrect array size error is usually an indication of an incorrect array size
The default implementation simply spins. The default implementation simply spins.
@ -996,9 +994,9 @@ Function : plat\_get\_next\_bl\_params()
Return : bl_params_t * Return : bl_params_t *
This function returns a pointer to the shared memory that the platform has This function returns a pointer to the shared memory that the platform has
kept aside to pass trusted firmware related information that next BL image kept aside to pass TF-A related information that next BL image needs. This
needs. This function is currently invoked in BL2 to pass this information to function is currently invoked in BL2 to pass this information to the next BL
the next BL image, when LOAD\_IMAGE\_V2 is enabled. image, when LOAD\_IMAGE\_V2 is enabled.
Function : plat\_get\_stack\_protector\_canary() Function : plat\_get\_stack\_protector\_canary()
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -1039,11 +1037,11 @@ Function : plat\_log\_get\_prefix()
Return : const char * Return : const char *
This function defines the prefix string corresponding to the `log_level` to be This function defines the prefix string corresponding to the `log_level` to be
prepended to all the log output from ARM Trusted Firmware. The `log_level` prepended to all the log output from TF-A. The `log_level` (argument) will
(argument) will correspond to one of the standard log levels defined in correspond to one of the standard log levels defined in debug.h. The platform
debug.h. The platform can override the common implementation to define a can override the common implementation to define a different prefix string for
different prefix string for the log output. The implementation should be the log output. The implementation should be robust to future changes that
robust to future changes that increase the number of log levels. increase the number of log levels.
Modifications specific to a Boot Loader stage Modifications specific to a Boot Loader stage
--------------------------------------------- ---------------------------------------------
@ -1101,7 +1099,7 @@ Function : bl1\_early\_platform\_setup() [mandatory]
This function executes with the MMU and data caches disabled. It is only called This function executes with the MMU and data caches disabled. It is only called
by the primary CPU. by the primary CPU.
On ARM standard platforms, this function: On Arm standard platforms, this function:
- Enables a secure instance of SP805 to act as the Trusted Watchdog. - Enables a secure instance of SP805 to act as the Trusted Watchdog.
@ -1124,7 +1122,7 @@ This function performs any platform-specific and architectural setup that the
platform requires. Platform-specific setup might include configuration of platform requires. Platform-specific setup might include configuration of
memory controllers and the interconnect. memory controllers and the interconnect.
In ARM standard platforms, this function enables the MMU. In Arm standard platforms, this function enables the MMU.
This function helps fulfill requirement 2 above. This function helps fulfill requirement 2 above.
@ -1143,7 +1141,7 @@ MMU and data cache have been enabled.
if support for multiple boot sources is required, it initializes the boot if support for multiple boot sources is required, it initializes the boot
sequence used by plat\_try\_next\_boot\_source(). sequence used by plat\_try\_next\_boot\_source().
In ARM standard platforms, this function initializes the storage abstraction In Arm standard platforms, this function initializes the storage abstraction
layer used to load the next bootloader image. layer used to load the next bootloader image.
This function helps fulfill requirement 4 above. This function helps fulfill requirement 4 above.
@ -1216,7 +1214,7 @@ loaded and executed. If the platform returns ``BL2_IMAGE_ID`` then BL1 proceeds
with the normal boot sequence, which loads and executes BL2. If the platform with the normal boot sequence, which loads and executes BL2. If the platform
returns a different image id, BL1 assumes that Firmware Update is required. returns a different image id, BL1 assumes that Firmware Update is required.
The default implementation always returns ``BL2_IMAGE_ID``. The ARM development The default implementation always returns ``BL2_IMAGE_ID``. The Arm development
platforms override this function to detect if firmware update is required, and platforms override this function to detect if firmware update is required, and
if so, return the first image in the firmware update process. if so, return the first image in the firmware update process.
@ -1231,7 +1229,7 @@ Function : bl1\_plat\_get\_image\_desc() [optional]
BL1 calls this function to get the image descriptor information ``image_desc_t`` BL1 calls this function to get the image descriptor information ``image_desc_t``
for the provided ``image_id`` from the platform. for the provided ``image_id`` from the platform.
The default implementation always returns a common BL2 image descriptor. ARM The default implementation always returns a common BL2 image descriptor. Arm
standard platforms return an image descriptor corresponding to BL2 or one of standard platforms return an image descriptor corresponding to BL2 or one of
the firmware update images defined in the Trusted Board Boot Requirements the firmware update images defined in the Trusted Board Boot Requirements
specification. specification.
@ -1371,7 +1369,7 @@ variable as the original memory may be subsequently overwritten by BL2. The
copied structure is made available to all BL2 code through the copied structure is made available to all BL2 code through the
``bl2_plat_sec_mem_layout()`` function. ``bl2_plat_sec_mem_layout()`` function.
On ARM standard platforms, this function also: On Arm standard platforms, this function also:
- Initializes a UART (PL011 console), which enables access to the ``printf`` - Initializes a UART (PL011 console), which enables access to the ``printf``
family of functions in BL2. family of functions in BL2.
@ -1394,7 +1392,7 @@ by the primary CPU.
The purpose of this function is to perform any architectural initialization The purpose of this function is to perform any architectural initialization
that varies across platforms. that varies across platforms.
On ARM standard platforms, this function enables the MMU. On Arm standard platforms, this function enables the MMU.
Function : bl2\_platform\_setup() [mandatory] Function : bl2\_platform\_setup() [mandatory]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -1411,7 +1409,7 @@ called by the primary CPU.
The purpose of this function is to perform any platform initialization The purpose of this function is to perform any platform initialization
specific to BL2. specific to BL2.
In ARM standard platforms, this function performs security setup, including In Arm standard platforms, this function performs security setup, including
configuration of the TrustZone controller to allow non-secure masters access configuration of the TrustZone controller to allow non-secure masters access
to most of DRAM. Part of DRAM is reserved for secure world use. to most of DRAM. Part of DRAM is reserved for secure world use.
@ -1526,7 +1524,7 @@ BL2 platform code returns a pointer which is used to populate the entry point
information for BL31 entry point. The location pointed by it should be information for BL31 entry point. The location pointed by it should be
accessible from BL1 while processing the synchronous exception to run to BL31. accessible from BL1 while processing the synchronous exception to run to BL31.
In ARM standard platforms this is allocated inside a bl2\_to\_bl31\_params\_mem In Arm standard platforms this is allocated inside a bl2\_to\_bl31\_params\_mem
structure in BL2 memory. structure in BL2 memory.
Function : bl2\_plat\_set\_bl31\_ep\_info() [mandatory] Function : bl2\_plat\_set\_bl31\_ep\_info() [mandatory]
@ -1664,8 +1662,8 @@ of this always returns 0.
Boot Loader Stage 2 (BL2) at EL3 Boot Loader Stage 2 (BL2) at EL3
-------------------------------- --------------------------------
When the platform has a non-TF Boot ROM it is desirable to jump When the platform has a non-TF-A Boot ROM it is desirable to jump
directly to BL2 instead of TF BL1. In this case BL2 is expected to directly to BL2 instead of TF-A BL1. In this case BL2 is expected to
execute at EL3 instead of executing at EL1. Refer to the `Firmware execute at EL3 instead of executing at EL1. Refer to the `Firmware
Design`_ for more information. Design`_ for more information.
@ -1687,7 +1685,7 @@ This function executes with the MMU and data caches disabled. It is only called
by the primary CPU. This function receives four parameters which can be used by the primary CPU. This function receives four parameters which can be used
by the platform to pass any needed information from the Boot ROM to BL2. by the platform to pass any needed information from the Boot ROM to BL2.
On ARM standard platforms, this function does the following: On Arm standard platforms, this function does the following:
- Initializes a UART (PL011 console), which enables access to the ``printf`` - Initializes a UART (PL011 console), which enables access to the ``printf``
family of functions in BL2. family of functions in BL2.
@ -1711,7 +1709,7 @@ by the primary CPU.
The purpose of this function is to perform any architectural initialization The purpose of this function is to perform any architectural initialization
that varies across platforms. that varies across platforms.
On ARM standard platforms, this function enables the MMU. On Arm standard platforms, this function enables the MMU.
Function : bl2\_el3\_plat\_prepare\_exit() [optional] Function : bl2\_el3\_plat\_prepare\_exit() [optional]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -1740,7 +1738,7 @@ process and is executed only by the primary CPU. BL1 passes control to BL2U at
If ``SCP_BL2U_BASE`` is not defined then this step is not performed. If ``SCP_BL2U_BASE`` is not defined then this step is not performed.
#. Any platform specific setup required to perform the FWU process. For #. Any platform specific setup required to perform the FWU process. For
example, ARM standard platforms initialize the TZC controller so that the example, Arm standard platforms initialize the TZC controller so that the
normal world can access DDR memory. normal world can access DDR memory.
The following functions must be implemented by the platform port to enable The following functions must be implemented by the platform port to enable
@ -1761,7 +1759,7 @@ of the ``meminfo`` structure and platform specific info provided by BL1.
The platform may copy the contents of the ``mem_info`` and ``plat_info`` into The platform may copy the contents of the ``mem_info`` and ``plat_info`` into
private storage as the original memory may be subsequently overwritten by BL2U. private storage as the original memory may be subsequently overwritten by BL2U.
On ARM CSS platforms ``plat_info`` is interpreted as an ``image_info_t`` structure, On Arm CSS platforms ``plat_info`` is interpreted as an ``image_info_t`` structure,
to extract SCP\_BL2U image information, which is then copied into a private to extract SCP\_BL2U image information, which is then copied into a private
variable. variable.
@ -1795,7 +1793,7 @@ called by the primary CPU.
The purpose of this function is to perform any platform initialization The purpose of this function is to perform any platform initialization
specific to BL2U. specific to BL2U.
In ARM standard platforms, this function performs security setup, including In Arm standard platforms, this function performs security setup, including
configuration of the TrustZone controller to allow non-secure masters access configuration of the TrustZone controller to allow non-secure masters access
to most of DRAM. Part of DRAM is reserved for secure world use. to most of DRAM. Part of DRAM is reserved for secure world use.
@ -1868,7 +1866,7 @@ sub-structures into private variables if the original memory may be
subsequently overwritten by BL31 and similarly the ``void *`` pointing subsequently overwritten by BL31 and similarly the ``void *`` pointing
to the platform data also needs to be saved. to the platform data also needs to be saved.
In ARM standard platforms, BL2 passes a pointer to a ``bl31_params`` structure In Arm standard platforms, BL2 passes a pointer to a ``bl31_params`` structure
in BL2 memory. BL31 copies the information in this pointer to internal data in BL2 memory. BL31 copies the information in this pointer to internal data
structures. It also performs the following: structures. It also performs the following:
@ -1893,7 +1891,7 @@ by the primary CPU.
The purpose of this function is to perform any architectural initialization The purpose of this function is to perform any architectural initialization
that varies across platforms. that varies across platforms.
On ARM standard platforms, this function enables the MMU. On Arm standard platforms, this function enables the MMU.
Function : bl31\_platform\_setup() [mandatory] Function : bl31\_platform\_setup() [mandatory]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -1910,7 +1908,7 @@ called by the primary CPU.
The purpose of this function is to complete platform initialization so that both The purpose of this function is to complete platform initialization so that both
BL31 runtime services and normal world software can function correctly. BL31 runtime services and normal world software can function correctly.
On ARM standard platforms, this function does the following: On Arm standard platforms, this function does the following:
- Initialize the generic interrupt controller. - Initialize the generic interrupt controller.
@ -1978,7 +1976,7 @@ Function : plat\_get\_syscnt\_freq2() [mandatory]
This function is used by the architecture setup code to retrieve the counter This function is used by the architecture setup code to retrieve the counter
frequency for the CPU's generic timer. This value will be programmed into the frequency for the CPU's generic timer. This value will be programmed into the
``CNTFRQ_EL0`` register. In ARM standard platforms, it returns the base frequency ``CNTFRQ_EL0`` register. In Arm standard platforms, it returns the base frequency
of the system counter, which is retrieved from the first entry in the frequency of the system counter, which is retrieved from the first entry in the frequency
modes table. modes table.
@ -2045,7 +2043,7 @@ argument, which is the address of the handler the SDEI client requested to
register. The function must return ``0`` for successful validation, or ``-1`` register. The function must return ``0`` for successful validation, or ``-1``
upon failure. upon failure.
The default implementation always returns ``0``. On ARM platforms, this function The default implementation always returns ``0``. On Arm platforms, this function
is implemented to translate the entry point to physical address, and further to is implemented to translate the entry point to physical address, and further to
ensure that the address is located in Non-secure DRAM. ensure that the address is located in Non-secure DRAM.
@ -2072,18 +2070,18 @@ The default implementation only prints out a warning message.
Power State Coordination Interface (in BL31) Power State Coordination Interface (in BL31)
-------------------------------------------- --------------------------------------------
The ARM Trusted Firmware's implementation of the PSCI API is based around the The TF-A implementation of the PSCI API is based around the concept of a
concept of a *power domain*. A *power domain* is a CPU or a logical group of *power domain*. A *power domain* is a CPU or a logical group of CPUs which
CPUs which share some state on which power management operations can be share some state on which power management operations can be performed as
performed as specified by `PSCI`_. Each CPU in the system is assigned a cpu specified by `PSCI`_. Each CPU in the system is assigned a cpu index which is
index which is a unique number between ``0`` and ``PLATFORM_CORE_COUNT - 1``. a unique number between ``0`` and ``PLATFORM_CORE_COUNT - 1``. The
The *power domains* are arranged in a hierarchical tree structure and *power domains* are arranged in a hierarchical tree structure and each
each *power domain* can be identified in a system by the cpu index of any CPU *power domain* can be identified in a system by the cpu index of any CPU that
that is part of that domain and a *power domain level*. A processing element is part of that domain and a *power domain level*. A processing element (for
(for example, a CPU) is at level 0. If the *power domain* node above a CPU is example, a CPU) is at level 0. If the *power domain* node above a CPU is a
a logical grouping of CPUs that share some state, then level 1 is that group logical grouping of CPUs that share some state, then level 1 is that group of
of CPUs (for example, a cluster), and level 2 is a group of clusters CPUs (for example, a cluster), and level 2 is a group of clusters (for
(for example, the system). More details on the power domain topology and its example, the system). More details on the power domain topology and its
organization can be found in `Power Domain Topology Design`_. organization can be found in `Power Domain Topology Design`_.
BL31's platform initialization code exports a pointer to the platform-specific BL31's platform initialization code exports a pointer to the platform-specific
@ -2223,12 +2221,12 @@ platform-specific psci power management actions by populating the passed
pointer with a pointer to BL31's private ``plat_psci_ops`` structure. pointer with a pointer to BL31's private ``plat_psci_ops`` structure.
A description of each member of this structure is given below. Please refer to A description of each member of this structure is given below. Please refer to
the ARM FVP specific implementation of these handlers in the Arm FVP specific implementation of these handlers in
`plat/arm/board/fvp/fvp\_pm.c`_ as an example. For each PSCI function that the `plat/arm/board/fvp/fvp\_pm.c`_ as an example. For each PSCI function that the
platform wants to support, the associated operation or operations in this platform wants to support, the associated operation or operations in this
structure must be provided and implemented (Refer section 4 of structure must be provided and implemented (Refer section 4 of
`Firmware Design`_ for the PSCI API supported in Trusted Firmware). To disable `Firmware Design`_ for the PSCI API supported in TF-A). To disable a PSCI
a PSCI function in a platform port, the operation should be removed from this function in a platform port, the operation should be removed from this
structure instead of providing an empty implementation. structure instead of providing an empty implementation.
plat\_psci\_ops.cpu\_standby() plat\_psci\_ops.cpu\_standby()
@ -2511,14 +2509,14 @@ state or EL3/S-EL1 in the secure state. The design of this framework is
described in the `IMF Design Guide`_ described in the `IMF Design Guide`_
A platform should export the following APIs to support the IMF. The following A platform should export the following APIs to support the IMF. The following
text briefly describes each api and its implementation in ARM standard text briefly describes each api and its implementation in Arm standard
platforms. The API implementation depends upon the type of interrupt controller platforms. The API implementation depends upon the type of interrupt controller
present in the platform. ARM standard platform layer supports both present in the platform. Arm standard platform layer supports both
`ARM Generic Interrupt Controller version 2.0 (GICv2)`_ `Arm Generic Interrupt Controller version 2.0 (GICv2)`_
and `3.0 (GICv3)`_. Juno builds the ARM and `3.0 (GICv3)`_. Juno builds the Arm platform layer to use GICv2 and the
Standard layer to use GICv2 and the FVP can be configured to use either GICv2 or FVP can be configured to use either GICv2 or GICv3 depending on the build flag
GICv3 depending on the build flag ``FVP_USE_GIC_DRIVER`` (See FVP platform ``FVP_USE_GIC_DRIVER`` (See FVP platform specific build options in
specific build options in `User Guide`_ for more details). `User Guide`_ for more details).
See also: `Interrupt Controller Abstraction APIs`__. See also: `Interrupt Controller Abstraction APIs`__.
@ -2532,7 +2530,7 @@ Function : plat\_interrupt\_type\_to\_line() [mandatory]
Argument : uint32_t, uint32_t Argument : uint32_t, uint32_t
Return : uint32_t Return : uint32_t
The ARM processor signals an interrupt exception either through the IRQ or FIQ The Arm processor signals an interrupt exception either through the IRQ or FIQ
interrupt line. The specific line that is signaled depends on how the interrupt interrupt line. The specific line that is signaled depends on how the interrupt
controller (IC) reports different interrupt types from an execution context in controller (IC) reports different interrupt types from an execution context in
either security state. The IMF uses this API to determine which interrupt line either security state. The IMF uses this API to determine which interrupt line
@ -2545,11 +2543,11 @@ security state of the originating execution context. The return result is the
bit position in the ``SCR_EL3`` register of the respective interrupt trap: IRQ=1, bit position in the ``SCR_EL3`` register of the respective interrupt trap: IRQ=1,
FIQ=2. FIQ=2.
In the case of ARM standard platforms using GICv2, S-EL1 interrupts are In the case of Arm standard platforms using GICv2, S-EL1 interrupts are
configured as FIQs and Non-secure interrupts as IRQs from either security configured as FIQs and Non-secure interrupts as IRQs from either security
state. state.
In the case of ARM standard platforms using GICv3, the interrupt line to be In the case of Arm standard platforms using GICv3, the interrupt line to be
configured depends on the security state of the execution context when the configured depends on the security state of the execution context when the
interrupt is signalled and are as follows: interrupt is signalled and are as follows:
@ -2574,7 +2572,7 @@ handler function. ``INTR_TYPE_INVAL`` is returned when there is no interrupt
pending. The valid interrupt types that can be returned are ``INTR_TYPE_EL3``, pending. The valid interrupt types that can be returned are ``INTR_TYPE_EL3``,
``INTR_TYPE_S_EL1`` and ``INTR_TYPE_NS``. This API must be invoked at EL3. ``INTR_TYPE_S_EL1`` and ``INTR_TYPE_NS``. This API must be invoked at EL3.
In the case of ARM standard platforms using GICv2, the *Highest Priority In the case of Arm standard platforms using GICv2, the *Highest Priority
Pending Interrupt Register* (``GICC_HPPIR``) is read to determine the id of Pending Interrupt Register* (``GICC_HPPIR``) is read to determine the id of
the pending interrupt. The type of interrupt depends upon the id value as the pending interrupt. The type of interrupt depends upon the id value as
follows. follows.
@ -2583,7 +2581,7 @@ follows.
#. id = 1022 is reported as a Non-secure interrupt. #. id = 1022 is reported as a Non-secure interrupt.
#. id = 1023 is reported as an invalid interrupt type. #. id = 1023 is reported as an invalid interrupt type.
In the case of ARM standard platforms using GICv3, the system register In the case of Arm standard platforms using GICv3, the system register
``ICC_HPPIR0_EL1``, *Highest Priority Pending group 0 Interrupt Register*, ``ICC_HPPIR0_EL1``, *Highest Priority Pending group 0 Interrupt Register*,
is read to determine the id of the pending interrupt. The type of interrupt is read to determine the id of the pending interrupt. The type of interrupt
depends upon the id value as follows. depends upon the id value as follows.
@ -2605,7 +2603,7 @@ This API returns the id of the highest priority pending interrupt at the
platform IC. ``INTR_ID_UNAVAILABLE`` is returned when there is no interrupt platform IC. ``INTR_ID_UNAVAILABLE`` is returned when there is no interrupt
pending. pending.
In the case of ARM standard platforms using GICv2, the *Highest Priority In the case of Arm standard platforms using GICv2, the *Highest Priority
Pending Interrupt Register* (``GICC_HPPIR``) is read to determine the id of the Pending Interrupt Register* (``GICC_HPPIR``) is read to determine the id of the
pending interrupt. The id that is returned by API depends upon the value of pending interrupt. The id that is returned by API depends upon the value of
the id read from the interrupt controller as follows. the id read from the interrupt controller as follows.
@ -2616,7 +2614,7 @@ the id read from the interrupt controller as follows.
This id is returned by the API. This id is returned by the API.
#. id = 1023. ``INTR_ID_UNAVAILABLE`` is returned. #. id = 1023. ``INTR_ID_UNAVAILABLE`` is returned.
In the case of ARM standard platforms using GICv3, if the API is invoked from In the case of Arm standard platforms using GICv3, if the API is invoked from
EL3, the system register ``ICC_HPPIR0_EL1``, *Highest Priority Pending Interrupt EL3, the system register ``ICC_HPPIR0_EL1``, *Highest Priority Pending Interrupt
group 0 Register*, is read to determine the id of the pending interrupt. The id group 0 Register*, is read to determine the id of the pending interrupt. The id
that is returned by API depends upon the value of the id read from the that is returned by API depends upon the value of the id read from the
@ -2651,12 +2649,12 @@ The actual interrupt number shall be extracted from this raw value using the API
.. __: platform-interrupt-controller-API.rst#function-unsigned-int-plat-ic-get-interrupt-id-unsigned-int-raw-optional .. __: platform-interrupt-controller-API.rst#function-unsigned-int-plat-ic-get-interrupt-id-unsigned-int-raw-optional
This function in ARM standard platforms using GICv2, reads the *Interrupt This function in Arm standard platforms using GICv2, reads the *Interrupt
Acknowledge Register* (``GICC_IAR``). This changes the state of the highest Acknowledge Register* (``GICC_IAR``). This changes the state of the highest
priority pending interrupt from pending to active in the interrupt controller. priority pending interrupt from pending to active in the interrupt controller.
It returns the value read from the ``GICC_IAR``, unmodified. It returns the value read from the ``GICC_IAR``, unmodified.
In the case of ARM standard platforms using GICv3, if the API is invoked In the case of Arm standard platforms using GICv3, if the API is invoked
from EL3, the function reads the system register ``ICC_IAR0_EL1``, *Interrupt from EL3, the function reads the system register ``ICC_IAR0_EL1``, *Interrupt
Acknowledge Register group 0*. If the API is invoked from S-EL1, the function Acknowledge Register group 0*. If the API is invoked from S-EL1, the function
reads the system register ``ICC_IAR1_EL1``, *Interrupt Acknowledge Register reads the system register ``ICC_IAR1_EL1``, *Interrupt Acknowledge Register
@ -2680,7 +2678,7 @@ the interrupt corresponding to the id (passed as the parameter) has
finished. The id should be the same as the id returned by the finished. The id should be the same as the id returned by the
``plat_ic_acknowledge_interrupt()`` API. ``plat_ic_acknowledge_interrupt()`` API.
ARM standard platforms write the id to the *End of Interrupt Register* Arm standard platforms write the id to the *End of Interrupt Register*
(``GICC_EOIR``) in case of GICv2, and to ``ICC_EOIR0_EL1`` or ``ICC_EOIR1_EL1`` (``GICC_EOIR``) in case of GICv2, and to ``ICC_EOIR0_EL1`` or ``ICC_EOIR1_EL1``
system register in case of GICv3 depending on where the API is invoked from, system register in case of GICv3 depending on where the API is invoked from,
EL3 or S-EL1. This deactivates the corresponding interrupt in the interrupt EL3 or S-EL1. This deactivates the corresponding interrupt in the interrupt
@ -2703,12 +2701,12 @@ interrupt type (one of ``INTR_TYPE_EL3``, ``INTR_TYPE_S_EL1`` and ``INTR_TYPE_NS
returned depending upon how the interrupt has been configured by the platform returned depending upon how the interrupt has been configured by the platform
IC. This API must be invoked at EL3. IC. This API must be invoked at EL3.
ARM standard platforms using GICv2 configures S-EL1 interrupts as Group0 interrupts Arm standard platforms using GICv2 configures S-EL1 interrupts as Group0 interrupts
and Non-secure interrupts as Group1 interrupts. It reads the group value and Non-secure interrupts as Group1 interrupts. It reads the group value
corresponding to the interrupt id from the relevant *Interrupt Group Register* corresponding to the interrupt id from the relevant *Interrupt Group Register*
(``GICD_IGROUPRn``). It uses the group value to determine the type of interrupt. (``GICD_IGROUPRn``). It uses the group value to determine the type of interrupt.
In the case of ARM standard platforms using GICv3, both the *Interrupt Group In the case of Arm standard platforms using GICv3, both the *Interrupt Group
Register* (``GICD_IGROUPRn``) and *Interrupt Group Modifier Register* Register* (``GICD_IGROUPRn``) and *Interrupt Group Modifier Register*
(``GICD_IGRPMODRn``) is read to figure out whether the interrupt is configured (``GICD_IGRPMODRn``) is read to figure out whether the interrupt is configured
as Group 0 secure interrupt, Group 1 secure interrupt or Group 1 NS interrupt. as Group 0 secure interrupt, Group 1 secure interrupt or Group 1 NS interrupt.
@ -2829,10 +2827,10 @@ C Library
To avoid subtle toolchain behavioral dependencies, the header files provided To avoid subtle toolchain behavioral dependencies, the header files provided
by the compiler are not used. The software is built with the ``-nostdinc`` flag by the compiler are not used. The software is built with the ``-nostdinc`` flag
to ensure no headers are included from the toolchain inadvertently. Instead the to ensure no headers are included from the toolchain inadvertently. Instead the
required headers are included in the ARM Trusted Firmware source tree. The required headers are included in the TF-A source tree. The library only
library only contains those C library definitions required by the local contains those C library definitions required by the local implementation. If
implementation. If more functionality is required, the needed library functions more functionality is required, the needed library functions will need to be
will need to be added to the local implementation. added to the local implementation.
Versions of `FreeBSD`_ headers can be found in ``include/lib/stdlib``. Some of Versions of `FreeBSD`_ headers can be found in ``include/lib/stdlib``. Some of
these headers have been cut down in order to simplify the implementation. In these headers have been cut down in order to simplify the implementation. In
@ -2873,7 +2871,7 @@ required in their respective ``blx_platform_setup()`` functions. Currently
storage access is only required by BL1 and BL2 phases. The ``load_image()`` storage access is only required by BL1 and BL2 phases. The ``load_image()``
function uses the storage layer to access non-volatile platform storage. function uses the storage layer to access non-volatile platform storage.
It is mandatory to implement at least one storage driver. For the ARM It is mandatory to implement at least one storage driver. For the Arm
development platforms the Firmware Image Package (FIP) driver is provided as development platforms the Firmware Image Package (FIP) driver is provided as
the default means to load data from storage (see the "Firmware Image Package" the default means to load data from storage (see the "Firmware Image Package"
section in the `User Guide`_). The storage layer is described in the header file section in the `User Guide`_). The storage layer is described in the header file
@ -2913,7 +2911,7 @@ amount of open resources per driver.
-------------- --------------
*Copyright (c) 2013-2017, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2013-2018, Arm Limited and Contributors. All rights reserved.*
.. _Migration Guide: platform-migration-guide.rst .. _Migration Guide: platform-migration-guide.rst
.. _include/plat/common/platform.h: ../include/plat/common/platform.h .. _include/plat/common/platform.h: ../include/plat/common/platform.h
@ -2931,6 +2929,6 @@ amount of open resources per driver.
.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
.. _plat/arm/board/fvp/fvp\_pm.c: ../plat/arm/board/fvp/fvp_pm.c .. _plat/arm/board/fvp/fvp\_pm.c: ../plat/arm/board/fvp/fvp_pm.c
.. _IMF Design Guide: interrupt-framework-design.rst .. _IMF Design Guide: interrupt-framework-design.rst
.. _ARM Generic Interrupt Controller version 2.0 (GICv2): http://infocenter.arm.com/help/topic/com.arm.doc.ihi0048b/index.html .. _Arm Generic Interrupt Controller version 2.0 (GICv2): http://infocenter.arm.com/help/topic/com.arm.doc.ihi0048b/index.html
.. _3.0 (GICv3): http://infocenter.arm.com/help/topic/com.arm.doc.ihi0069b/index.html .. _3.0 (GICv3): http://infocenter.arm.com/help/topic/com.arm.doc.ihi0069b/index.html
.. _FreeBSD: http://www.freebsd.org .. _FreeBSD: http://www.freebsd.org

22
docs/psci-lib-integration-guide.rst
View file

@ -1,4 +1,4 @@
PSCI Library Integration guide for ARMv8-A AArch32 systems PSCI Library Integration guide for Armv8-A AArch32 systems
========================================================== ==========================================================
@ -8,7 +8,7 @@ PSCI Library Integration guide for ARMv8-A AArch32 systems
.. contents:: .. contents::
This document describes the PSCI library interface with a focus on how to This document describes the PSCI library interface with a focus on how to
integrate with a suitable Trusted OS for an ARMv8-A AArch32 system. The PSCI integrate with a suitable Trusted OS for an Armv8-A AArch32 system. The PSCI
Library implements the PSCI Standard as described in `PSCI spec`_ and is meant Library implements the PSCI Standard as described in `PSCI spec`_ and is meant
to be integrated with EL3 Runtime Software which invokes the PSCI Library to be integrated with EL3 Runtime Software which invokes the PSCI Library
interface appropriately. **EL3 Runtime Software** refers to software executing interface appropriately. **EL3 Runtime Software** refers to software executing
@ -17,9 +17,10 @@ Monitor mode in AArch32, and provides runtime services to the non-secure world.
The runtime service request is made via SMC (Secure Monitor Call) and the call The runtime service request is made via SMC (Secure Monitor Call) and the call
must adhere to `SMCCC`_. In AArch32, EL3 Runtime Software may additionally must adhere to `SMCCC`_. In AArch32, EL3 Runtime Software may additionally
include Trusted OS functionality. A minimal AArch32 Secure Payload, SP-MIN, is include Trusted OS functionality. A minimal AArch32 Secure Payload, SP-MIN, is
provided in ARM Trusted Firmware to illustrate the usage and integration of the provided in Trusted Firmware-A (TF-A) to illustrate the usage and integration
PSCI library. The description of PSCI library interface and its integration of the PSCI library. The description of PSCI library interface and its
with EL3 Runtime Software in this document is targeted towards AArch32 systems. integration with EL3 Runtime Software in this document is targeted towards
AArch32 systems.
Generic call sequence for PSCI Library interface (AArch32) Generic call sequence for PSCI Library interface (AArch32)
---------------------------------------------------------- ----------------------------------------------------------
@ -315,7 +316,7 @@ Software must provide an SMC handling framework capable of MP adhering to
The EL3 Runtime Software must also export cache maintenance primitives The EL3 Runtime Software must also export cache maintenance primitives
and some helper utilities for assert, print and memory operations as listed and some helper utilities for assert, print and memory operations as listed
below. The ARM Trusted Firmware source tree provides implementations for all below. The TF-A source tree provides implementations for all
these functions but the EL3 Runtime Software may use its own implementation. these functions but the EL3 Runtime Software may use its own implementation.
**Functions : assert(), memcpy(), memset** **Functions : assert(), memcpy(), memset**
@ -355,10 +356,10 @@ failure that cannot be recovered from. This function **must not** return.
**Function : tf\_printf()** **Function : tf\_printf()**
This is printf-compatible function, but unlike printf, it does not return any This is printf-compatible function, but unlike printf, it does not return any
value. The ARM Trusted Firmware source tree provides an implementation which value. The TF-A source tree provides an implementation which
is optimized for stack usage and supports only a subset of format specifiers. is optimized for stack usage and supports only a subset of format specifiers.
The details of the format specifiers supported can be found in the The details of the format specifiers supported can be found in the
``tf_printf.c`` file in ARM Trusted Firmware source tree. ``tf_printf.c`` file in the TF-A source tree.
CPU Context management API CPU Context management API
~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -537,7 +538,8 @@ CPU operations
~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~
The CPU operations (cpu\_ops) framework implement power down sequence specific The CPU operations (cpu\_ops) framework implement power down sequence specific
to the CPU and the details of which can be found in the ``CPU specific operations framework`` section of `Firmware Design`_. The ARM Trusted Firmware to the CPU and the details of which can be found in the
``CPU specific operations framework`` section of `Firmware Design`_. The TF-A
tree implements the ``cpu_ops`` for various supported CPUs and the EL3 Runtime tree implements the ``cpu_ops`` for various supported CPUs and the EL3 Runtime
Software needs to include the required ``cpu_ops`` in its build. The start and Software needs to include the required ``cpu_ops`` in its build. The start and
end of the ``cpu_ops`` descriptors must be exported by the EL3 Runtime Software end of the ``cpu_ops`` descriptors must be exported by the EL3 Runtime Software
@ -550,7 +552,7 @@ workarounds.
-------------- --------------
*Copyright (c) 2016, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2016-2018, Arm Limited and Contributors. All rights reserved.*
.. _PSCI spec: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf .. _PSCI spec: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
.. _SMCCC: https://silver.arm.com/download/ARM_and_AMBA_Architecture/AR570-DA-80002-r0p0-00rel0/ARM_DEN0028A_SMC_Calling_Convention.pdf .. _SMCCC: https://silver.arm.com/download/ARM_and_AMBA_Architecture/AR570-DA-80002-r0p0-00rel0/ARM_DEN0028A_SMC_Calling_Convention.pdf

4
docs/psci-pd-tree.rst
View file

@ -1,4 +1,4 @@
PSCI Library Integration guide for ARMv8-A AArch32 systems PSCI Library Integration guide for Armv8-A AArch32 systems
========================================================== ==========================================================
@ -309,4 +309,4 @@ domain nodes do not need to be identified.
-------------- --------------
*Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2017-2018, Arm Limited and Contributors. All rights reserved.*

42
docs/reset-design.rst
View file

@ -1,5 +1,5 @@
ARM Trusted Firmware Reset Design Trusted Firmware-A reset design
================================= ===============================
.. section-numbering:: .. section-numbering::
@ -8,9 +8,9 @@ ARM Trusted Firmware Reset Design
.. contents:: .. contents::
This document describes the high-level design of the framework to handle CPU This document describes the high-level design of the framework to handle CPU
resets in ARM Trusted Firmware. It also describes how the platform integrator resets in Trusted Firmware-A (TF-A). It also describes how the platform
can tailor this code to the system configuration to some extent, resulting in a integrator can tailor this code to the system configuration to some extent,
simplified and more optimised boot flow. resulting in a simplified and more optimised boot flow.
This document should be used in conjunction with the `Firmware Design`_, which This document should be used in conjunction with the `Firmware Design`_, which
provides greater implementation details around the reset code, specifically provides greater implementation details around the reset code, specifically
@ -19,8 +19,8 @@ for the cold boot path.
General reset code flow General reset code flow
----------------------- -----------------------
The ARM Trusted Firmware (TF) reset code is implemented in BL1 by default. The The TF-A reset code is implemented in BL1 by default. The following high-level
following high-level diagram illustrates this: diagram illustrates this:
|Default reset code flow| |Default reset code flow|
@ -29,15 +29,15 @@ configuration, some of these steps might be unnecessary. The following sections
guide the platform integrator by indicating which build options exclude which guide the platform integrator by indicating which build options exclude which
steps, depending on the capability of the platform. steps, depending on the capability of the platform.
Note: If BL31 is used as the Trusted Firmware entry point instead of BL1, the Note: If BL31 is used as the TF-A entry point instead of BL1, the diagram
diagram above is still relevant, as all these operations will occur in BL31 in above is still relevant, as all these operations will occur in BL31 in
this case. Please refer to section 6 "Using BL31 entrypoint as the reset this case. Please refer to section 6 "Using BL31 entrypoint as the reset
address" for more information. address" for more information.
Programmable CPU reset address Programmable CPU reset address
------------------------------ ------------------------------
By default, the TF assumes that the CPU reset address is not programmable. By default, TF-A assumes that the CPU reset address is not programmable.
Therefore, all CPUs start at the same address (typically address 0) whenever Therefore, all CPUs start at the same address (typically address 0) whenever
they reset. Further logic is then required to identify whether it is a cold or they reset. Further logic is then required to identify whether it is a cold or
warm boot to direct CPUs to the right execution path. warm boot to direct CPUs to the right execution path.
@ -49,8 +49,8 @@ detection can be skipped, resulting in the following boot flow:
|Reset code flow with programmable reset address| |Reset code flow with programmable reset address|
To enable this boot flow, compile the TF with ``PROGRAMMABLE_RESET_ADDRESS=1``. To enable this boot flow, compile TF-A with ``PROGRAMMABLE_RESET_ADDRESS=1``.
This option only affects the TF reset image, which is BL1 by default or BL31 if This option only affects the TF-A reset image, which is BL1 by default or BL31 if
``RESET_TO_BL31=1``. ``RESET_TO_BL31=1``.
On both the FVP and Juno platforms, the reset vector address is not programmable On both the FVP and Juno platforms, the reset vector address is not programmable
@ -59,7 +59,7 @@ so both ports use ``PROGRAMMABLE_RESET_ADDRESS=0``.
Cold boot on a single CPU Cold boot on a single CPU
------------------------- -------------------------
By default, the TF assumes that several CPUs may be released out of reset. By default, TF-A assumes that several CPUs may be released out of reset.
Therefore, the cold boot code has to arbitrate access to hardware resources Therefore, the cold boot code has to arbitrate access to hardware resources
shared amongst CPUs. This is done by nominating one of the CPUs as the primary, shared amongst CPUs. This is done by nominating one of the CPUs as the primary,
which is responsible for initialising shared hardware and coordinating the boot which is responsible for initialising shared hardware and coordinating the boot
@ -71,8 +71,8 @@ applies. This results in the following boot flow:
|Reset code flow with single CPU released out of reset| |Reset code flow with single CPU released out of reset|
To enable this boot flow, compile the TF with ``COLD_BOOT_SINGLE_CPU=1``. This To enable this boot flow, compile TF-A with ``COLD_BOOT_SINGLE_CPU=1``. This
option only affects the TF reset image, which is BL1 by default or BL31 if option only affects the TF-A reset image, which is BL1 by default or BL31 if
``RESET_TO_BL31=1``. ``RESET_TO_BL31=1``.
On both the FVP and Juno platforms, although only one core is powered up by On both the FVP and Juno platforms, although only one core is powered up by
@ -89,8 +89,8 @@ This results in the following boot flow:
|Reset code flow with programmable reset address and single CPU released out of reset| |Reset code flow with programmable reset address and single CPU released out of reset|
To enable this boot flow, compile the TF with both ``COLD_BOOT_SINGLE_CPU=1`` To enable this boot flow, compile TF-A with both ``COLD_BOOT_SINGLE_CPU=1``
and ``PROGRAMMABLE_RESET_ADDRESS=1``. These options only affect the TF reset and ``PROGRAMMABLE_RESET_ADDRESS=1``. These options only affect the TF-A reset
image, which is BL1 by default or BL31 if ``RESET_TO_BL31=1``. image, which is BL1 by default or BL31 if ``RESET_TO_BL31=1``.
Using BL31 entrypoint as the reset address Using BL31 entrypoint as the reset address
@ -102,7 +102,7 @@ on the SoC, rather than by BL1 and BL2 running on the primary application
processor. For this type of SoC it is desirable for the application processor processor. For this type of SoC it is desirable for the application processor
to always reset to BL31 which eliminates the need for BL1 and BL2. to always reset to BL31 which eliminates the need for BL1 and BL2.
TF provides a build-time option ``RESET_TO_BL31`` that includes some additional TF-A provides a build-time option ``RESET_TO_BL31`` that includes some additional
logic in the BL31 entry point to support this use case. logic in the BL31 entry point to support this use case.
In this configuration, the platform's Trusted Boot Firmware must ensure that In this configuration, the platform's Trusted Boot Firmware must ensure that
@ -112,10 +112,10 @@ Additionally, platform software is responsible for loading the other BL3x images
required and providing entry point information for them to BL31. Loading these required and providing entry point information for them to BL31. Loading these
images might be done by the Trusted Boot Firmware or by platform code in BL31. images might be done by the Trusted Boot Firmware or by platform code in BL31.
Although the ARM FVP platform does not support programming the reset base Although the Arm FVP platform does not support programming the reset base
address dynamically at run-time, it is possible to set the initial value of the address dynamically at run-time, it is possible to set the initial value of the
``RVBAR_EL3`` register at start-up. This feature is provided on the Base FVP only. ``RVBAR_EL3`` register at start-up. This feature is provided on the Base FVP only.
It allows the ARM FVP port to support the ``RESET_TO_BL31`` configuration, in It allows the Arm FVP port to support the ``RESET_TO_BL31`` configuration, in
which case the ``bl31.bin`` image must be loaded to its run address in Trusted which case the ``bl31.bin`` image must be loaded to its run address in Trusted
SRAM and all CPU reset vectors be changed from the default ``0x0`` to this run SRAM and all CPU reset vectors be changed from the default ``0x0`` to this run
address. See the `User Guide`_ for details of running the FVP models in this way. address. See the `User Guide`_ for details of running the FVP models in this way.
@ -155,7 +155,7 @@ This might be done by the Trusted Boot Firmware or by platform code in BL31.
-------------- --------------
*Copyright (c) 2015, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2015-2018, Arm Limited and Contributors. All rights reserved.*
.. _Firmware Design: firmware-design.rst .. _Firmware Design: firmware-design.rst
.. _User Guide: user-guide.rst .. _User Guide: user-guide.rst

25
docs/rt-svc-writers-guide.rst
View file

@ -1,5 +1,5 @@
EL3 Runtime Service Writers Guide for ARM Trusted Firmware Trusted Firmware-A EL3 runtime service writer's guide
========================================================== =====================================================
.. section-numbering:: .. section-numbering::
@ -13,7 +13,7 @@ Introduction
------------ ------------
This document describes how to add a runtime service to the EL3 Runtime This document describes how to add a runtime service to the EL3 Runtime
Firmware component of ARM Trusted Firmware (BL31). Firmware component of Trusted Firmware-A (TF-A), BL31.
Software executing in the normal world and in the trusted world at exception Software executing in the normal world and in the trusted world at exception
levels lower than EL3 will request runtime services using the Secure Monitor levels lower than EL3 will request runtime services using the Secure Monitor
@ -27,7 +27,7 @@ example a subset of the Function IDs are designated as "OEM Calls" (see `SMCCC`_
for full details). The EL3 runtime services framework in BL31 enables the for full details). The EL3 runtime services framework in BL31 enables the
independent implementation of services for each group, which are then compiled independent implementation of services for each group, which are then compiled
into the BL31 image. This simplifies the integration of common software from into the BL31 image. This simplifies the integration of common software from
ARM to support `PSCI`_, Secure Monitor for a Trusted OS and SoC specific Arm to support `PSCI`_, Secure Monitor for a Trusted OS and SoC specific
software. The common runtime services framework ensures that SMC Functions are software. The common runtime services framework ensures that SMC Functions are
dispatched to their respective service implementation - the `Firmware Design`_ dispatched to their respective service implementation - the `Firmware Design`_
provides details of how this is achieved. provides details of how this is achieved.
@ -53,7 +53,7 @@ legacy 32-bit software that predates the `SMCCC`_.
:: ::
Type OEN Service Type OEN Service
Fast 0 ARM Architecture calls Fast 0 Arm Architecture calls
Fast 1 CPU Service calls Fast 1 CPU Service calls
Fast 2 SiP Service calls Fast 2 SiP Service calls
Fast 3 OEM Service calls Fast 3 OEM Service calls
@ -62,7 +62,7 @@ legacy 32-bit software that predates the `SMCCC`_.
Fast 48-49 Trusted Application calls Fast 48-49 Trusted Application calls
Fast 50-63 Trusted OS calls Fast 50-63 Trusted OS calls
Yielding 0- 1 Reserved for existing ARMv7 calls Yielding 0- 1 Reserved for existing Armv7-A calls
Yielding 2-63 Trusted OS Standard Calls Yielding 2-63 Trusted OS Standard Calls
*Table 1: Service types and their corresponding Owning Entity Numbers* *Table 1: Service types and their corresponding Owning Entity Numbers*
@ -72,7 +72,7 @@ range as they need - it is not necessary to coordinate with other entities of
the same type. For example, two SoC providers can use the same Function ID the same type. For example, two SoC providers can use the same Function ID
within the SiP Service calls OEN range to mean different things - as these within the SiP Service calls OEN range to mean different things - as these
calls should be specific to the SoC. The Standard Runtime Calls OEN is used for calls should be specific to the SoC. The Standard Runtime Calls OEN is used for
services defined by ARM standards, such as `PSCI`_. services defined by Arm standards, such as `PSCI`_.
The SMC Function ID also indicates whether the call has followed the SMC32 The SMC Function ID also indicates whether the call has followed the SMC32
calling convention, where all parameters are 32-bit, or the SMC64 calling calling convention, where all parameters are 32-bit, or the SMC64 calling
@ -87,7 +87,7 @@ handler will be responsible for all SMC Functions within a given service type.
Getting started Getting started
--------------- ---------------
ARM Trusted Firmware has a `services`_ directory in the source tree under which TF-A has a `services`_ directory in the source tree under which
each owning entity can place the implementation of its runtime service. The each owning entity can place the implementation of its runtime service. The
`PSCI`_ implementation is located here in the `lib/psci`_ directory. `PSCI`_ implementation is located here in the `lib/psci`_ directory.
@ -250,8 +250,7 @@ The handler is responsible for:
UID and Revision Details for each service documented in section 6 of the UID and Revision Details for each service documented in section 6 of the
`SMCCC`_. `SMCCC`_.
The ARM Trusted Firmware expects owning entities to follow this TF-A expects owning entities to follow this recommendation.
recommendation.
#. Returning the result to the caller. The `SMCCC`_ allows for up to 256 bits #. Returning the result to the caller. The `SMCCC`_ allows for up to 256 bits
of return value in SMC64 using X0-X3 and 128 bits in SMC32 using W0-W3. The of return value in SMC64 using X0-X3 and 128 bits in SMC32 using W0-W3. The
@ -286,8 +285,8 @@ service which perform independent functions.
In this situation it may be valuable to introduce a second level framework to In this situation it may be valuable to introduce a second level framework to
enable independent implementation of sub-services. Such a framework might look enable independent implementation of sub-services. Such a framework might look
very similar to the current runtime services framework, but using a different very similar to the current runtime services framework, but using a different
part of the SMC Function ID to identify the sub-service. Trusted Firmware does part of the SMC Function ID to identify the sub-service. TF-A does not provide
not provide such a framework at present. such a framework at present.
Secure-EL1 Payload Dispatcher service (SPD) Secure-EL1 Payload Dispatcher service (SPD)
------------------------------------------- -------------------------------------------
@ -304,7 +303,7 @@ provide this information....
-------------- --------------
*Copyright (c) 2014-2015, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2014-2018, Arm Limited and Contributors. All rights reserved.*
.. _SMCCC: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html .. _SMCCC: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf

14
docs/sdei.rst
View file

@ -8,13 +8,13 @@ Software Delegated Exception Interface
.. contents:: .. contents::
:depth: 2 :depth: 2
This document provides an overview of the SDEI dispatcher implementation in ARM This document provides an overview of the SDEI dispatcher implementation in
Trusted Firmware. Trusted Firmware-A (TF-A).
Introduction Introduction
------------ ------------
`Software Delegated Exception Interface`_ (SDEI) is an ARM specification for `Software Delegated Exception Interface`_ (SDEI) is an Arm specification for
Non-secure world to register handlers with firmware to receive notifications Non-secure world to register handlers with firmware to receive notifications
about system events. Firmware will first receive the system events by way of about system events. Firmware will first receive the system events by way of
asynchronous exceptions and, in response, arranges for the registered handler to asynchronous exceptions and, in response, arranges for the registered handler to
@ -52,8 +52,8 @@ SDEI events can be explicitly dispatched in response to other asynchronous
exceptions. See `Explicit dispatch of events`_. exceptions. See `Explicit dispatch of events`_.
The remainder of this document only discusses the design and implementation of The remainder of this document only discusses the design and implementation of
SDEI dispatcher in ARM Trusted Firmware, and assumes that the reader is familiar SDEI dispatcher in TF-A, and assumes that the reader is familiar with the SDEI
with the SDEI specification, the interfaces, and their requirements. specification, the interfaces, and their requirements.
.. [#std-event] Except event 0, which is defined by the SDEI specification as a .. [#std-event] Except event 0, which is defined by the SDEI specification as a
standard event. standard event.
@ -314,7 +314,7 @@ Note on writing SDEI event handlers
----------------------------------- -----------------------------------
*This section pertains to SDEI event handlers in general, not just when using *This section pertains to SDEI event handlers in general, not just when using
ARM Trusted Firmware SDEI dispatcher.* the TF-A SDEI dispatcher.*
The SDEI specification requires that event handlers preserve the contents of all The SDEI specification requires that event handlers preserve the contents of all
registers except ``x0`` to ``x17``. This has significance if event handler is registers except ``x0`` to ``x17``. This has significance if event handler is
@ -364,7 +364,7 @@ implemented in assembly, following a similar pattern as below:
---- ----
*Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2017-2018, Arm Limited and Contributors. All rights reserved.*
.. _SDEI specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf .. _SDEI specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf
.. _SDEI porting requirements: porting-guide.rst#sdei-porting-requirements .. _SDEI porting requirements: porting-guide.rst#sdei-porting-requirements

81
docs/secure-partition-manager-design.rst
View file

@ -18,8 +18,8 @@ used by Non-secure world applications to access these services. A Trusted OS
fulfils the requirements of a security service as described above. fulfils the requirements of a security service as described above.
Management services are typically implemented at the highest level of privilege Management services are typically implemented at the highest level of privilege
in the system (i.e. EL3 in Arm Trusted Firmware). The service requirements are in the system, i.e. EL3 in Trusted Firmware-A (TF-A). The service requirements are
fulfilled by the execution environment provided by Arm Trusted Firmware. fulfilled by the execution environment provided by TF-A.
The following diagram illustrates the corresponding software stack: The following diagram illustrates the corresponding software stack:
@ -41,10 +41,10 @@ Introduction
A **Secure Partition** is a software execution environment instantiated in A **Secure Partition** is a software execution environment instantiated in
S-EL0 that can be used to implement simple management and security services. S-EL0 that can be used to implement simple management and security services.
Since S-EL0 is an unprivileged Exception Level, a Secure Partition relies on Since S-EL0 is an unprivileged Exception Level, a Secure Partition relies on
privileged firmware (i.e. Arm Trusted Firmware) to be granted access to system privileged firmware (i.e. TF-A) to be granted access to system and processor
and processor resources. Essentially, it is a software sandbox in the Secure resources. Essentially, it is a software sandbox in the Secure world that runs
world that runs under the control of privileged software, provides one or more under the control of privileged software, provides one or more services and
services and accesses the following system resources: accesses the following system resources:
- Memory and device regions in the system address map. - Memory and device regions in the system address map.
@ -52,25 +52,24 @@ services and accesses the following system resources:
- A range of synchronous exceptions (e.g. SMC function identifiers). - A range of synchronous exceptions (e.g. SMC function identifiers).
Note that currently the Arm Trusted Firmware only supports handling one Secure Note that currently TF-A only supports handling one Secure Partition.
Partition.
A Secure Partition enables Arm Trusted Firmware to implement only the essential A Secure Partition enables TF-A to implement only the essential secure
secure services in EL3 and instantiate the rest in a partition in S-EL0. services in EL3 and instantiate the rest in a partition in S-EL0.
Furthermore, multiple Secure Partitions can be used to isolate unrelated Furthermore, multiple Secure Partitions can be used to isolate unrelated
services from each other. services from each other.
The following diagram illustrates the place of a Secure Partition in a typical The following diagram illustrates the place of a Secure Partition in a typical
ARMv8-A software stack. A single or multiple Secure Partitions provide secure Armv8-A software stack. A single or multiple Secure Partitions provide secure
services to software components in the Non-secure world and other Secure services to software components in the Non-secure world and other Secure
Partitions. Partitions.
|Image 2| |Image 2|
The Arm Trusted Firmware build system is responsible for including the Secure The TF-A build system is responsible for including the Secure Partition image
Partition image in the FIP. During boot, BL2 includes support to authenticate in the FIP. During boot, BL2 includes support to authenticate and load the
and load the Secure Partition image. A BL31 component called **Secure Partition Secure Partition image. A BL31 component called **Secure Partition Manager
Manager (SPM)** is responsible for managing the partition. This is semantically (SPM)** is responsible for managing the partition. This is semantically
similar to a hypervisor managing a virtual machine. similar to a hypervisor managing a virtual machine.
The SPM is responsible for the following actions during boot: The SPM is responsible for the following actions during boot:
@ -105,8 +104,8 @@ made in the current implementation of this software architecture. Subsequent
revisions of the implementation will include a richer set of features that revisions of the implementation will include a richer set of features that
enable a more flexible architecture. enable a more flexible architecture.
Building Arm Trusted Firmware with Secure Partition support Building TF-A with Secure Partition support
----------------------------------------------------------- -------------------------------------------
SPM is supported on the Arm FVP exclusively at the moment. The current SPM is supported on the Arm FVP exclusively at the moment. The current
implementation supports inclusion of only a single Secure Partition in which a implementation supports inclusion of only a single Secure Partition in which a
@ -125,7 +124,7 @@ the UEFI specification (see the PI v1.6 Volume 4: Management Mode Core
Interface). This will be referred to as the *Standalone MM Secure Partition* in Interface). This will be referred to as the *Standalone MM Secure Partition* in
the rest of this document. the rest of this document.
To enable SPM support in the TF, the source code must be compiled with the build To enable SPM support in TF-A, the source code must be compiled with the build
flag ``ENABLE_SPM=1``. On Arm platforms the build option ``ARM_BL31_IN_DRAM`` flag ``ENABLE_SPM=1``. On Arm platforms the build option ``ARM_BL31_IN_DRAM``
can be used to select the location of BL31, both SRAM and DRAM are supported. can be used to select the location of BL31, both SRAM and DRAM are supported.
Also, the location of the binary that contains the BL32 image Also, the location of the binary that contains the BL32 image
@ -134,7 +133,7 @@ Also, the location of the binary that contains the BL32 image
First, build the Standalone MM Secure Partition. To build it, refer to the First, build the Standalone MM Secure Partition. To build it, refer to the
`instructions in the EDK2 repository`_. `instructions in the EDK2 repository`_.
Then build TF with SPM support and include the Standalone MM Secure Partition Then build TF-A with SPM support and include the Standalone MM Secure Partition
image in the FIP: image in the FIP:
:: ::
@ -145,10 +144,10 @@ image in the FIP:
Describing Secure Partition resources Describing Secure Partition resources
------------------------------------- -------------------------------------
Arm Trusted Firmware exports a porting interface that enables a platform to TF-A exports a porting interface that enables a platform to specify the system
specify the system resources required by the Secure Partition. Some instructions resources required by the Secure Partition. Some instructions are given below.
are given below. However, this interface is under development and it may change However, this interface is under development and it may change as new features
as new features are implemented. are implemented.
- A Secure Partition is considered a BL32 image, so the same defines that apply - A Secure Partition is considered a BL32 image, so the same defines that apply
to BL32 images apply to a Secure Partition: ``BL32_BASE`` and ``BL32_LIMIT``. to BL32 images apply to a Secure Partition: ``BL32_BASE`` and ``BL32_LIMIT``.
@ -176,9 +175,9 @@ For an example of all the changes in context, you may refer to commit
Accessing Secure Partition services Accessing Secure Partition services
----------------------------------- -----------------------------------
The `SMC Calling Convention`_ (*ARM DEN 0028B*) describes SMCs as a conduit for The `SMC Calling Convention`_ (*Arm DEN 0028B*) describes SMCs as a conduit for
accessing services implemented in the Secure world. The ``MM_COMMUNICATE`` accessing services implemented in the Secure world. The ``MM_COMMUNICATE``
interface defined in the `Management Mode Interface Specification`_ (*ARM DEN interface defined in the `Management Mode Interface Specification`_ (*Arm DEN
0060A*) is used to invoke a Secure Partition service as a Fast Call. 0060A*) is used to invoke a Secure Partition service as a Fast Call.
The mechanism used to identify a service within the partition depends on the The mechanism used to identify a service within the partition depends on the
@ -208,11 +207,11 @@ e.g. ACPI table or device tree. It is possible for the Non-secure world to
exchange data with a partition only if it has been populated in this shared exchange data with a partition only if it has been populated in this shared
memory area. The shared memory area is implemented as per the guidelines memory area. The shared memory area is implemented as per the guidelines
specified in Section 3.2.3 of the `Management Mode Interface Specification`_ specified in Section 3.2.3 of the `Management Mode Interface Specification`_
(*ARM DEN 0060A*). (*Arm DEN 0060A*).
The format of data structures used to encapsulate data in the shared memory is The format of data structures used to encapsulate data in the shared memory is
agreed between the Non-secure world and the Secure Partition. For example, in agreed between the Non-secure world and the Secure Partition. For example, in
the `Management Mode Interface specification`_ (*ARM DEN 0060A*), Section 4 the `Management Mode Interface specification`_ (*Arm DEN 0060A*), Section 4
describes that the communication buffer shared between the Non-secure world and describes that the communication buffer shared between the Non-secure world and
the Management Mode (MM) in the Secure world must be of the type the Management Mode (MM) in the Secure world must be of the type
``EFI_MM_COMMUNICATE_HEADER``. This data structure is defined in *Volume 4: ``EFI_MM_COMMUNICATE_HEADER``. This data structure is defined in *Volume 4:
@ -246,7 +245,7 @@ interfaces are not accessible from the Non-secure world.
Conduit Conduit
^^^^^^^ ^^^^^^^
The `SMC Calling Convention`_ (*ARM DEN 0028B*) specification describes the SMC The `SMC Calling Convention`_ (*Arm DEN 0028B*) specification describes the SMC
and HVC conduits for accessing firmware services and their availability and HVC conduits for accessing firmware services and their availability
depending on the implemented Exception levels. In S-EL0, the Supervisor Call depending on the implemented Exception levels. In S-EL0, the Supervisor Call
exception (SVC) is the only architectural mechanism available for unprivileged exception (SVC) is the only architectural mechanism available for unprivileged
@ -254,16 +253,16 @@ software to make a request for an operation implemented in privileged software.
Hence, the SVC conduit must be used by the Secure Partition to access interfaces Hence, the SVC conduit must be used by the Secure Partition to access interfaces
implemented by the SPM. implemented by the SPM.
A SVC causes an exception to be taken to S-EL1. Arm Trusted Firmware assumes A SVC causes an exception to be taken to S-EL1. TF-A assumes ownership of S-EL1
ownership of S-EL1 and installs a simple exception vector table in S-EL1 that and installs a simple exception vector table in S-EL1 that relays a SVC request
relays a SVC request from a Secure Partition as a SMC request to the SPM in EL3. from a Secure Partition as a SMC request to the SPM in EL3. Upon servicing the
Upon servicing the SMC request, Arm Trusted Firmware returns control directly to SMC request, Arm Trusted Firmware returns control directly to S-EL0 through an
S-EL0 through an ERET instruction. ERET instruction.
Calling conventions Calling conventions
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
The `SMC Calling Convention`_ (*ARM DEN 0028B*) specification describes the The `SMC Calling Convention`_ (*Arm DEN 0028B*) specification describes the
32-bit and 64-bit calling conventions for the SMC and HVC conduits. The SVC 32-bit and 64-bit calling conventions for the SMC and HVC conduits. The SVC
conduit introduces the concept of SVC32 and SVC64 calling conventions. The SVC32 conduit introduces the concept of SVC32 and SVC64 calling conventions. The SVC32
and SVC64 calling conventions are equivalent to the 32-bit (SMC32) and the and SVC64 calling conventions are equivalent to the 32-bit (SMC32) and the
@ -285,8 +284,8 @@ Communication initiated by Secure Partition
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A request is initiated from the Secure Partition by executing a SVC instruction. A request is initiated from the Secure Partition by executing a SVC instruction.
An ERET instruction is used by Arm Trusted Firmware to return to S-EL0 with the An ERET instruction is used by TF-A to return to S-EL0 with the result of the
result of the request. request.
For instance, a request to perform privileged operations on behalf of a For instance, a request to perform privileged operations on behalf of a
partition (e.g. management of memory attributes in the translation tables for partition (e.g. management of memory attributes in the translation tables for
@ -296,7 +295,7 @@ Interfaces
^^^^^^^^^^ ^^^^^^^^^^
The current implementation reserves function IDs for Fast Calls in the Standard The current implementation reserves function IDs for Fast Calls in the Standard
Secure Service calls range (see `SMC Calling Convention`_ (*ARM DEN 0028B*) Secure Service calls range (see `SMC Calling Convention`_ (*Arm DEN 0028B*)
specification) for each API exported by the SPM. This section defines the specification) for each API exported by the SPM. This section defines the
function prototypes for each function ID. The function IDs specify whether one function prototypes for each function ID. The function IDs specify whether one
or both of the SVC32 and SVC64 calling conventions can be used to invoke the or both of the SVC32 and SVC64 calling conventions can be used to invoke the
@ -461,7 +460,7 @@ This transition into S-EL0 is special since it is not in response to a previous
request through a SVC instruction. This is the first entry into S-EL0. The request through a SVC instruction. This is the first entry into S-EL0. The
general purpose register usage at the time of entry will be as specified in the general purpose register usage at the time of entry will be as specified in the
"Return State" column of Table 3-1 in Section 3.1 "Register use in AArch64 SMC "Return State" column of Table 3-1 in Section 3.1 "Register use in AArch64 SMC
calls" of the `SMC Calling Convention`_ (*ARM DEN 0028B*) specification. In calls" of the `SMC Calling Convention`_ (*Arm DEN 0028B*) specification. In
addition, certain other restrictions will be applied as described below. addition, certain other restrictions will be applied as described below.
1. ``SP_EL0`` 1. ``SP_EL0``
@ -601,7 +600,7 @@ address map from a Secure Partition. This is done by mapping these regions in
the Secure EL1&0 Translation regime with appropriate memory attributes. the Secure EL1&0 Translation regime with appropriate memory attributes.
Attributes refer to memory type, permission, cacheability and shareability Attributes refer to memory type, permission, cacheability and shareability
attributes used in the Translation tables. The definitions of these attributes attributes used in the Translation tables. The definitions of these attributes
and their usage can be found in the `ARMv8 ARM`_ (*ARM DDI 0487*). and their usage can be found in the `Armv8-A ARM`_ (*Arm DDI 0487*).
All memory required by the Secure Partition is allocated upfront in the SPM, All memory required by the Secure Partition is allocated upfront in the SPM,
even before handing over to the Secure Partition for the first time. The initial even before handing over to the Secure Partition for the first time. The initial
@ -813,9 +812,9 @@ Error Codes
-------------- --------------
*Copyright (c) 2017, Arm Limited and Contributors. All rights reserved.* *Copyright (c) 2017-2018, Arm Limited and Contributors. All rights reserved.*
.. _ARMv8 ARM: https://developer.arm.com/docs/ddi0487/latest/arm-architecture-reference-manual-armv8-for-armv8-a-architecture-profile .. _Armv8-A ARM: https://developer.arm.com/docs/ddi0487/latest/arm-architecture-reference-manual-armv8-for-armv8-a-architecture-profile
.. _instructions in the EDK2 repository: https://github.com/tianocore/edk2-staging/blob/AArch64StandaloneMm/HowtoBuild.MD .. _instructions in the EDK2 repository: https://github.com/tianocore/edk2-staging/blob/AArch64StandaloneMm/HowtoBuild.MD
.. _Management Mode Interface Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0060a/DEN0060A_ARM_MM_Interface_Specification.pdf .. _Management Mode Interface Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0060a/DEN0060A_ARM_MM_Interface_Specification.pdf
.. _SDEI Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf .. _SDEI Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf

2
docs/spd/optee-dispatcher.rst
View file

@ -8,7 +8,7 @@ To build and execute OP-TEE follow the instructions at
-------------- --------------
*Copyright (c) 2014-2017, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2014-2018, Arm Limited and Contributors. All rights reserved.*
.. _OP-TEE OS: https://github.com/OP-TEE/build .. _OP-TEE OS: https://github.com/OP-TEE/build
.. _OP-TEE build.git: https://github.com/OP-TEE/build .. _OP-TEE build.git: https://github.com/OP-TEE/build

12
docs/spd/tlk-dispatcher.rst
View file

@ -1,10 +1,10 @@
Trusted Little Kernel (TLK) Dispatcher Trusted Little Kernel (TLK) Dispatcher
====================================== ======================================
TLK dispatcher adds support for NVIDIA's Trusted Little Kernel (TLK) to work TLK dispatcher (TLK-D) adds support for NVIDIA's Trusted Little Kernel (TLK)
with the Trusted Firmware. TLK-D can be compiled by including it in the to work with Trusted Firmware-A (TF-A). TLK-D can be compiled by including it
platform's makefile. TLK is primarily meant to work with Tegra SoCs, so until in the platform's makefile. TLK is primarily meant to work with Tegra SoCs,
Trusted Firmware starts supporting Tegra, the dispatcher code can only be so while TF-A only supports TLK on Tegra, the dispatcher code can only be
compiled for other platforms. compiled for other platforms.
In order to compile TLK-D, we need a BL32 image to be present. Since, TLKD In order to compile TLK-D, we need a BL32 image to be present. Since, TLKD
@ -20,7 +20,7 @@ Trusted Little Kernel (TLK)
TLK is a Trusted OS running as Secure EL1. It is a Free Open Source Software TLK is a Trusted OS running as Secure EL1. It is a Free Open Source Software
(FOSS) release of the NVIDIA® Trusted Little Kernel (TLK) technology, which (FOSS) release of the NVIDIA® Trusted Little Kernel (TLK) technology, which
extends technology made available with the development of the Little Kernel (LK). extends technology made available with the development of the Little Kernel (LK).
You can download the LK modular embedded preemptive kernel for use on ARM, You can download the LK modular embedded preemptive kernel for use on Arm,
x86, and AVR32 systems from https://github.com/travisg/lk x86, and AVR32 systems from https://github.com/travisg/lk
NVIDIA implemented its Trusted Little Kernel (TLK) technology, designed as a NVIDIA implemented its Trusted Little Kernel (TLK) technology, designed as a
@ -72,5 +72,5 @@ Example:
:: ::
bl32_ep_info->args.arg0 = TZDRAM size available for BL32 bl32_ep_info->args.arg0 = TZDRAM size available for BL32
bl32_ep_info->args.arg1 = unused (used only on ARMv7) bl32_ep_info->args.arg1 = unused (used only on Armv7-A)
bl32_ep_info->args.arg2 = pointer to boot args bl32_ep_info->args.arg2 = pointer to boot args

2
docs/spd/trusty-dispatcher.rst
View file

@ -28,5 +28,5 @@ should then be set to the size of that block.
Supported platforms Supported platforms
=================== ===================
Out of all the platforms supported by the ARM Trusted Firmware, Trusty is Out of all the platforms supported by Trusted Firmware-A, Trusty is only
verified and supported by NVIDIA's Tegra SoCs. verified and supported by NVIDIA's Tegra SoCs.

26
docs/trusted-board-boot.rst
View file

@ -12,16 +12,16 @@ the platform by authenticating all firmware images up to and including the
normal world bootloader. It does this by establishing a Chain of Trust using normal world bootloader. It does this by establishing a Chain of Trust using
Public-Key-Cryptography Standards (PKCS). Public-Key-Cryptography Standards (PKCS).
This document describes the design of ARM Trusted Firmware TBB, which is an This document describes the design of Trusted Firmware-A (TF-A) TBB, which is
implementation of the Trusted Board Boot Requirements (TBBR) specification, an implementation of the Trusted Board Boot Requirements (TBBR) specification,
ARM DEN0006C-1. It should be used in conjunction with the `Firmware Update`_ Arm DEN0006C-1. It should be used in conjunction with the `Firmware Update`_
design document, which implements a specific aspect of the TBBR. design document, which implements a specific aspect of the TBBR.
Chain of Trust Chain of Trust
-------------- --------------
A Chain of Trust (CoT) starts with a set of implicitly trusted components. On A Chain of Trust (CoT) starts with a set of implicitly trusted components. On
the ARM development platforms, these components are: the Arm development platforms, these components are:
- A SHA-256 hash of the Root of Trust Public Key (ROTPK). It is stored in the - A SHA-256 hash of the Root of Trust Public Key (ROTPK). It is stored in the
trusted root-key storage registers. trusted root-key storage registers.
@ -39,7 +39,7 @@ Certificate Authority (CA) because the CoT is not established by verifying the
validity of a certificate's issuer but by the content of the certificate validity of a certificate's issuer but by the content of the certificate
extensions. To sign the certificates, the PKCS#1 SHA-256 with RSA Encryption extensions. To sign the certificates, the PKCS#1 SHA-256 with RSA Encryption
signature scheme is used with a RSA key length of 2048 bits. Future version of signature scheme is used with a RSA key length of 2048 bits. Future version of
Trusted Firmware will support additional cryptographic algorithms. TF-A will support additional cryptographic algorithms.
The certificates are categorised as "Key" and "Content" certificates. Key The certificates are categorised as "Key" and "Content" certificates. Key
certificates are used to verify public keys which have been used to sign content certificates are used to verify public keys which have been used to sign content
@ -148,7 +148,7 @@ if any of the steps fail.
registers. If they match, the BL2 hash is read from the certificate. registers. If they match, the BL2 hash is read from the certificate.
Note: the matching operation is platform specific and is currently Note: the matching operation is platform specific and is currently
unimplemented on the ARM development platforms. unimplemented on the Arm development platforms.
- BL1 loads the BL2 image. Its hash is calculated and compared with the hash - BL1 loads the BL2 image. Its hash is calculated and compared with the hash
read from the certificate. Control is transferred to the BL2 image if all read from the certificate. Control is transferred to the BL2 image if all
@ -196,7 +196,7 @@ enabled through use of specific build flags as described in the `User Guide`_.
On the host machine, a tool generates the certificates, which are included in On the host machine, a tool generates the certificates, which are included in
the FIP along with the boot loader images. These certificates are loaded in the FIP along with the boot loader images. These certificates are loaded in
Trusted SRAM using the IO storage framework. They are then verified by an Trusted SRAM using the IO storage framework. They are then verified by an
Authentication module included in the Trusted Firmware. Authentication module included in TF-A.
The mechanism used for generating the FIP and the Authentication module are The mechanism used for generating the FIP and the Authentication module are
described in the following sections. described in the following sections.
@ -204,9 +204,9 @@ described in the following sections.
Authentication Framework Authentication Framework
------------------------ ------------------------
The authentication framework included in the Trusted Firmware provides support The authentication framework included in TF-A provides support to implement
to implement the desired trusted boot sequence. ARM platforms use this framework the desired trusted boot sequence. Arm platforms use this framework to
to implement the boot requirements specified in the TBBR-client document. implement the boot requirements specified in the TBBR-client document.
More information about the authentication framework can be found in the More information about the authentication framework can be found in the
`Auth Framework`_ document. `Auth Framework`_ document.
@ -215,8 +215,8 @@ Certificate Generation Tool
--------------------------- ---------------------------
The ``cert_create`` tool is built and runs on the host machine as part of the The ``cert_create`` tool is built and runs on the host machine as part of the
Trusted Firmware build process when ``GENERATE_COT=1``. It takes the boot loader TF-A build process when ``GENERATE_COT=1``. It takes the boot loader images
images and keys as inputs (keys must be in PEM format) and generates the and keys as inputs (keys must be in PEM format) and generates the
certificates (in DER format) required to establish the CoT. New keys can be certificates (in DER format) required to establish the CoT. New keys can be
generated by the tool in case they are not provided. The certificates are then generated by the tool in case they are not provided. The certificates are then
passed as inputs to the ``fiptool`` utility for creating the FIP. passed as inputs to the ``fiptool`` utility for creating the FIP.
@ -230,7 +230,7 @@ for building and using the tool can be found in the `User Guide`_.
-------------- --------------
*Copyright (c) 2015, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2015-2018, Arm Limited and Contributors. All rights reserved.*
.. _Firmware Update: firmware-update.rst .. _Firmware Update: firmware-update.rst
.. _X.509 v3: http://www.ietf.org/rfc/rfc5280.txt .. _X.509 v3: http://www.ietf.org/rfc/rfc5280.txt

376
docs/user-guide.rst
View file

@ -1,5 +1,5 @@
ARM Trusted Firmware User Guide Trusted Firmware-A User Guide
=============================== =============================
.. section-numbering:: .. section-numbering::
@ -7,9 +7,9 @@ ARM Trusted Firmware User Guide
.. contents:: .. contents::
This document describes how to build ARM Trusted Firmware (TF) and run it with a This document describes how to build Trusted Firmware-A (TF-A) and run it with a
tested set of other software components using defined configurations on the Juno tested set of other software components using defined configurations on the Juno
ARM development platform and ARM Fixed Virtual Platform (FVP) models. It is Arm development platform and Arm Fixed Virtual Platform (FVP) models. It is
possible to use other software components, configurations and platforms but that possible to use other software components, configurations and platforms but that
is outside the scope of this document. is outside the scope of this document.
@ -48,14 +48,13 @@ Cygwin, and Msys (MinGW) shells, using version 5.3.1 of the GNU toolchain.
Tools Tools
----- -----
Install the required packages to build Trusted Firmware with the following Install the required packages to build TF-A with the following command:
command:
:: ::
sudo apt-get install build-essential gcc make git libssl-dev sudo apt-get install build-essential gcc make git libssl-dev
ARM TF has been tested with `Linaro Release 17.10`_. TF-A has been tested with `Linaro Release 17.10`_.
Download and install the AArch32 or AArch64 little-endian GCC cross compiler. Download and install the AArch32 or AArch64 little-endian GCC cross compiler.
The `Linaro Release Notes`_ documents which version of the compiler to use for a The `Linaro Release Notes`_ documents which version of the compiler to use for a
@ -63,7 +62,7 @@ given Linaro Release. Also, these `Linaro instructions`_ provide further
guidance and a script, which can be used to download Linaro deliverables guidance and a script, which can be used to download Linaro deliverables
automatically. automatically.
Optionally, Trusted Firmware can be built using clang or ARM Compiler 6. Optionally, TF-A can be built using clang or Arm Compiler 6.
See instructions below on how to switch the default compiler. See instructions below on how to switch the default compiler.
In addition, the following optional packages and tools may be needed: In addition, the following optional packages and tools may be needed:
@ -71,26 +70,26 @@ In addition, the following optional packages and tools may be needed:
- ``device-tree-compiler`` package if you need to rebuild the Flattened Device - ``device-tree-compiler`` package if you need to rebuild the Flattened Device
Tree (FDT) source files (``.dts`` files) provided with this software. Tree (FDT) source files (``.dts`` files) provided with this software.
- For debugging, ARM `Development Studio 5 (DS-5)`_. - For debugging, Arm `Development Studio 5 (DS-5)`_.
- To create and modify the diagram files included in the documentation, `Dia`_. - To create and modify the diagram files included in the documentation, `Dia`_.
This tool can be found in most Linux distributions. Inkscape is needed to This tool can be found in most Linux distributions. Inkscape is needed to
generate the actual *.png files. generate the actual *.png files.
Getting the Trusted Firmware source code Getting the TF-A source code
---------------------------------------- ----------------------------
Download the Trusted Firmware source code from Github: Download the TF-A source code from Github:
:: ::
git clone https://github.com/ARM-software/arm-trusted-firmware.git git clone https://github.com/ARM-software/arm-trusted-firmware.git
Building the Trusted Firmware Building TF-A
----------------------------- -------------
- Before building Trusted Firmware, the environment variable ``CROSS_COMPILE`` - Before building TF-A, the environment variable ``CROSS_COMPILE`` must point
must point to the Linaro cross compiler. to the Linaro cross compiler.
For AArch64: For AArch64:
@ -104,15 +103,15 @@ Building the Trusted Firmware
export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-linux-gnueabihf- export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-linux-gnueabihf-
It is possible to build Trusted Firmware using clang or ARM Compiler 6. It is possible to build TF-A using clang or Arm Compiler 6. To do so
To do so ``CC`` needs to point to the clang or armclang binary. Only the ``CC`` needs to point to the clang or armclang binary. Only the compiler
compiler is switched; the assembler and linker need to be provided by is switched; the assembler and linker need to be provided by the GNU
the GNU toolchain, thus ``CROSS_COMPILE`` should be set as described above. toolchain, thus ``CROSS_COMPILE`` should be set as described above.
ARM Compiler 6 will be selected when the base name of the path assigned Arm Compiler 6 will be selected when the base name of the path assigned
to ``CC`` matches the string 'armclang'. to ``CC`` matches the string 'armclang'.
For AArch64 using ARM Compiler 6: For AArch64 using Arm Compiler 6:
:: ::
@ -130,7 +129,7 @@ Building the Trusted Firmware
export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu- export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
make CC=<path-to-clang>/bin/clang PLAT=<platform> all make CC=<path-to-clang>/bin/clang PLAT=<platform> all
- Change to the root directory of the Trusted Firmware source tree and build. - Change to the root directory of the TF-A source tree and build.
For AArch64: For AArch64:
@ -154,11 +153,11 @@ Building the Trusted Firmware
- (AArch32 only) ``AARCH32_SP`` is the AArch32 EL3 Runtime Software and it - (AArch32 only) ``AARCH32_SP`` is the AArch32 EL3 Runtime Software and it
corresponds to the BL32 image. A minimal ``AARCH32_SP``, sp\_min, is corresponds to the BL32 image. A minimal ``AARCH32_SP``, sp\_min, is
provided by ARM Trusted Firmware to demonstrate how PSCI Library can provided by TF-A to demonstrate how PSCI Library can be integrated with
be integrated with an AArch32 EL3 Runtime Software. Some AArch32 EL3 an AArch32 EL3 Runtime Software. Some AArch32 EL3 Runtime Software may
Runtime Software may include other runtime services, for example include other runtime services, for example Trusted OS services. A guide
Trusted OS services. A guide to integrate PSCI library with AArch32 to integrate PSCI library with AArch32 EL3 Runtime Software can be found
EL3 Runtime Software can be found `here`_. `here`_.
- (AArch64 only) The TSP (Test Secure Payload), corresponding to the BL32 - (AArch64 only) The TSP (Test Secure Payload), corresponding to the BL32
image, is not compiled in by default. Refer to the image, is not compiled in by default. Refer to the
@ -198,11 +197,11 @@ Building the Trusted Firmware
Summary of build options Summary of build options
~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~
ARM Trusted Firmware build system supports the following build options. Unless The TF-A build system supports the following build options. Unless mentioned
mentioned otherwise, these options are expected to be specified at the build otherwise, these options are expected to be specified at the build command
command line and are not to be modified in any component makefiles. Note that line and are not to be modified in any component makefiles. Note that the
the build system doesn't track dependency for build options. Therefore, if any build system doesn't track dependency for build options. Therefore, if any of
of the build options are changed from a previous build, a clean build must be the build options are changed from a previous build, a clean build must be
performed. performed.
Common build options Common build options
@ -213,52 +212,51 @@ Common build options
directory containing the SP source, relative to the ``bl32/``; the directory directory containing the SP source, relative to the ``bl32/``; the directory
is expected to contain a makefile called ``<aarch32_sp-value>.mk``. is expected to contain a makefile called ``<aarch32_sp-value>.mk``.
- ``ARCH`` : Choose the target build architecture for ARM Trusted Firmware. - ``ARCH`` : Choose the target build architecture for TF-A. It can take either
It can take either ``aarch64`` or ``aarch32`` as values. By default, it is ``aarch64`` or ``aarch32`` as values. By default, it is defined to
defined to ``aarch64``. ``aarch64``.
- ``ARM_ARCH_MAJOR``: The major version of ARM Architecture to target when - ``ARM_ARCH_MAJOR``: The major version of Arm Architecture to target when
compiling ARM Trusted Firmware. Its value must be numeric, and defaults to compiling TF-A. Its value must be numeric, and defaults to 8 . See also,
8 . See also, *ARMv8 Architecture Extensions* and *Armv8 Architecture Extensions* and *Armv7 Architecture Extensions* in
*ARMv7 Architecture Extensions* in `Firmware Design`_. `Firmware Design`_.
- ``ARM_ARCH_MINOR``: The minor version of ARM Architecture to target when - ``ARM_ARCH_MINOR``: The minor version of Arm Architecture to target when
compiling ARM Trusted Firmware. Its value must be a numeric, and defaults compiling TF-A. Its value must be a numeric, and defaults to 0. See also,
to 0. See also, *ARMv8 Architecture Extensions* in `Firmware Design`_. *Armv8 Architecture Extensions* in `Firmware Design`_.
- ``ARM_GIC_ARCH``: Choice of ARM GIC architecture version used by the ARM - ``ARM_GIC_ARCH``: Choice of Arm GIC architecture version used by the Arm
Legacy GIC driver for implementing the platform GIC API. This API is used Legacy GIC driver for implementing the platform GIC API. This API is used
by the interrupt management framework. Default is 2 (that is, version 2.0). by the interrupt management framework. Default is 2 (that is, version 2.0).
This build option is deprecated. This build option is deprecated.
- ``ARM_PLAT_MT``: This flag determines whether the ARM platform layer has to - ``ARM_PLAT_MT``: This flag determines whether the Arm platform layer has to
cater for the multi-threading ``MT`` bit when accessing MPIDR. When this flag cater for the multi-threading ``MT`` bit when accessing MPIDR. When this flag
is set, the functions which deal with MPIDR assume that the ``MT`` bit in is set, the functions which deal with MPIDR assume that the ``MT`` bit in
MPIDR is set and access the bit-fields in MPIDR accordingly. Default value of MPIDR is set and access the bit-fields in MPIDR accordingly. Default value of
this flag is 0. Note that this option is not used on FVP platforms. this flag is 0. Note that this option is not used on FVP platforms.
- ``BL2``: This is an optional build option which specifies the path to BL2 - ``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 ARM Trusted image for the ``fip`` target. In this case, the BL2 in the TF-A will not be
Firmware will not be built. built.
- ``BL2U``: This is an optional build option which specifies the path to - ``BL2U``: This is an optional build option which specifies the path to
BL2U image. In this case, the BL2U in the ARM Trusted Firmware will not BL2U image. In this case, the BL2U in TF-A will not be built.
be built.
- ``BL2_AT_EL3``: This is an optional build option that enables the use of - ``BL2_AT_EL3``: This is an optional build option that enables the use of
BL2 at EL3 execution level. BL2 at EL3 execution level.
- ``BL31``: This is an optional build option which specifies the path to - ``BL31``: This is an optional build option which specifies the path to
BL31 image for the ``fip`` target. In this case, the BL31 in the ARM BL31 image for the ``fip`` target. In this case, the BL31 in TF-A will not
Trusted Firmware will not be built. be built.
- ``BL31_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the - ``BL31_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the
file that contains the BL31 private key in PEM format. If ``SAVE_KEYS=1``, file that contains the BL31 private key in PEM format. If ``SAVE_KEYS=1``,
this file name will be used to save the key. this file name will be used to save the key.
- ``BL32``: This is an optional build option which specifies the path to - ``BL32``: This is an optional build option which specifies the path to
BL32 image for the ``fip`` target. In this case, the BL32 in the ARM BL32 image for the ``fip`` target. In this case, the BL32 in TF-A will not
Trusted Firmware will not be built. be built.
- ``BL32_EXTRA1``: This is an optional build option which specifies the path to - ``BL32_EXTRA1``: This is an optional build option which specifies the path to
Trusted OS Extra1 image for the ``fip`` target. Trusted OS Extra1 image for the ``fip`` target.
@ -271,7 +269,7 @@ Common build options
this file name will be used to save the key. this file name will be used to save the key.
- ``BL33``: Path to BL33 image in the host file system. This is mandatory for - ``BL33``: Path to BL33 image in the host file system. This is mandatory for
``fip`` target in case the BL2 from ARM Trusted Firmware is used. ``fip`` target in case TF-A BL2 is used.
- ``BL33_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the - ``BL33_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the
file that contains the BL33 private key in PEM format. If ``SAVE_KEYS=1``, file that contains the BL33 private key in PEM format. If ``SAVE_KEYS=1``,
@ -282,8 +280,8 @@ Common build options
where applicable). Defaults to a string that contains the time and date of where applicable). Defaults to a string that contains the time and date of
the compilation. the compilation.
- ``BUILD_STRING``: Input string for VERSION\_STRING, which allows the TF build - ``BUILD_STRING``: Input string for VERSION\_STRING, which allows the TF-A
to be uniquely identified. Defaults to the current git commit id. build to be uniquely identified. Defaults to the current git commit id.
- ``CFLAGS``: Extra user options appended on the compiler's command line in - ``CFLAGS``: Extra user options appended on the compiler's command line in
addition to the options set by the build system. addition to the options set by the build system.
@ -347,10 +345,10 @@ Common build options
software. software.
- ``ENABLE_RUNTIME_INSTRUMENTATION``: Boolean option to enable runtime - ``ENABLE_RUNTIME_INSTRUMENTATION``: Boolean option to enable runtime
instrumentation which injects timestamp collection points into instrumentation which injects timestamp collection points into TF-A to
Trusted Firmware to allow runtime performance to be measured. allow runtime performance to be measured. Currently, only PSCI is
Currently, only PSCI is instrumented. Enabling this option enables instrumented. Enabling this option enables the ``ENABLE_PMF`` build option
the ``ENABLE_PMF`` build option as well. Default is 0. as well. Default is 0.
- ``ENABLE_SPE_FOR_LOWER_ELS`` : Boolean option to enable Statistical Profiling - ``ENABLE_SPE_FOR_LOWER_ELS`` : Boolean option to enable Statistical Profiling
extensions. This is an optional architectural feature for AArch64. extensions. This is an optional architectural feature for AArch64.
@ -427,15 +425,15 @@ Common build options
- ``HANDLE_EA_EL3_FIRST``: When defined External Aborts and SError Interrupts - ``HANDLE_EA_EL3_FIRST``: When defined External Aborts and SError Interrupts
will be always trapped in EL3 i.e. in BL31 at runtime. will be always trapped in EL3 i.e. in BL31 at runtime.
- ``HW_ASSISTED_COHERENCY``: On most ARM systems to-date, platform-specific - ``HW_ASSISTED_COHERENCY``: On most Arm systems to-date, platform-specific
software operations are required for CPUs to enter and exit coherency. software operations are required for CPUs to enter and exit coherency.
However, there exists newer systems where CPUs' entry to and exit from However, there exists newer systems where CPUs' entry to and exit from
coherency is managed in hardware. Such systems require software to only coherency is managed in hardware. Such systems require software to only
initiate the operations, and the rest is managed in hardware, minimizing initiate the operations, and the rest is managed in hardware, minimizing
active software management. In such systems, this boolean option enables ARM active software management. In such systems, this boolean option enables
Trusted Firmware to carry out build and run-time optimizations during boot TF-A to carry out build and run-time optimizations during boot and power
and power management operations. This option defaults to 0 and if it is management operations. This option defaults to 0 and if it is enabled,
enabled, then it implies ``WARMBOOT_ENABLE_DCACHE_EARLY`` is also enabled. then it implies ``WARMBOOT_ENABLE_DCACHE_EARLY`` is also enabled.
- ``JUNO_AARCH32_EL3_RUNTIME``: This build flag enables you to execute EL3 - ``JUNO_AARCH32_EL3_RUNTIME``: This build flag enables you to execute EL3
runtime software in AArch32 mode, which is required to run AArch32 on Juno. runtime software in AArch32 mode, which is required to run AArch32 on Juno.
@ -497,10 +495,10 @@ Common build options
any register that is not part of the SBSA generic UART specification. any register that is not part of the SBSA generic UART specification.
Default value is 0 (a full PL011 compliant UART is present). Default value is 0 (a full PL011 compliant UART is present).
- ``PLAT``: Choose a platform to build ARM Trusted Firmware for. The chosen - ``PLAT``: Choose a platform to build TF-A for. The chosen platform name
platform name must be subdirectory of any depth under ``plat/``, and must must be subdirectory of any depth under ``plat/``, and must contain a
contain a platform makefile named ``platform.mk``. For example to build ARM platform makefile named ``platform.mk``. For example, to build TF-A for the
Trusted Firmware for ARM Juno board select PLAT=juno. Arm Juno board, select PLAT=juno.
- ``PRELOADED_BL33_BASE``: This option enables booting a preloaded BL33 image - ``PRELOADED_BL33_BASE``: This option enables booting a preloaded BL33 image
instead of the normal boot flow. When defined, it must specify the entry instead of the normal boot flow. When defined, it must specify the entry
@ -524,7 +522,7 @@ Common build options
means by default the original power-state format is used by the PSCI means by default the original power-state format is used by the PSCI
implementation. This flag should be specified by the platform makefile implementation. This flag should be specified by the platform makefile
and it governs the return value of PSCI\_FEATURES API for CPU\_SUSPEND and it governs the return value of PSCI\_FEATURES API for CPU\_SUSPEND
smc function id. When this option is enabled on ARM platforms, the smc function id. When this option is enabled on Arm platforms, the
option ``ARM_RECOM_STATE_ID_ENC`` needs to be set to 1 as well. option ``ARM_RECOM_STATE_ID_ENC`` needs to be set to 1 as well.
- ``RESET_TO_BL31``: Enable BL31 entrypoint as the CPU reset vector instead - ``RESET_TO_BL31``: Enable BL31 entrypoint as the CPU reset vector instead
@ -532,11 +530,10 @@ Common build options
entrypoint) or 1 (CPU reset to BL31 entrypoint). entrypoint) or 1 (CPU reset to BL31 entrypoint).
The default value is 0. The default value is 0.
- ``RESET_TO_SP_MIN``: SP\_MIN is the minimal AArch32 Secure Payload provided in - ``RESET_TO_SP_MIN``: SP\_MIN is the minimal AArch32 Secure Payload provided
ARM Trusted Firmware. This flag configures SP\_MIN entrypoint as the CPU in TF-A. This flag configures SP\_MIN entrypoint as the CPU reset vector
reset vector instead of the BL1 entrypoint. It can take the value 0 (CPU instead of the BL1 entrypoint. It can take the value 0 (CPU reset to BL1
reset to BL1 entrypoint) or 1 (CPU reset to SP\_MIN entrypoint). The default entrypoint) or 1 (CPU reset to SP\_MIN entrypoint). The default value is 0.
value is 0.
- ``ROT_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the - ``ROT_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the
file that contains the ROT private key in PEM format. If ``SAVE_KEYS=1``, this file that contains the ROT private key in PEM format. If ``SAVE_KEYS=1``, this
@ -570,11 +567,11 @@ Common build options
pages" section in `Firmware Design`_. This flag is disabled by default and pages" section in `Firmware Design`_. This flag is disabled by default and
affects all BL images. affects all BL images.
- ``SPD``: Choose a Secure Payload Dispatcher component to be built into the - ``SPD``: Choose a Secure Payload Dispatcher component to be built into TF-A.
Trusted Firmware. This build option is only valid if ``ARCH=aarch64``. The This build option is only valid if ``ARCH=aarch64``. The value should be
value should be the path to the directory containing the SPD source, the path to the directory containing the SPD source, relative to
relative to ``services/spd/``; the directory is expected to ``services/spd/``; the directory is expected to contain a makefile called
contain a makefile called ``<spd-value>.mk``. ``<spd-value>.mk``.
- ``SPIN_ON_BL1_EXIT``: This option introduces an infinite loop in BL1. It can - ``SPIN_ON_BL1_EXIT``: This option introduces an infinite loop in BL1. It can
take either 0 (no loop) or 1 (add a loop). 0 is the default. This loop stops take either 0 (no loop) or 1 (add a loop). 0 is the default. This loop stops
@ -622,16 +619,16 @@ Common build options
- ``USE_COHERENT_MEM``: This flag determines whether to include the coherent - ``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 memory region in the BL memory map or not (see "Use of Coherent memory in
Trusted Firmware" section in `Firmware Design`_). It can take the value 1 TF-A" section in `Firmware Design`_). It can take the value 1
(Coherent memory region is included) or 0 (Coherent memory region is (Coherent memory region is included) or 0 (Coherent memory region is
excluded). Default is 1. excluded). Default is 1.
- ``V``: Verbose build. If assigned anything other than 0, the build commands - ``V``: Verbose build. If assigned anything other than 0, the build commands
are printed. Default is 0. are printed. Default is 0.
- ``VERSION_STRING``: String used in the log output for each TF image. Defaults - ``VERSION_STRING``: String used in the log output for each TF-A image.
to a string formed by concatenating the version number, build type and build Defaults to a string formed by concatenating the version number, build type
string. and build string.
- ``WARMBOOT_ENABLE_DCACHE_EARLY`` : Boolean option to enable D-cache early on - ``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 the CPU after warm boot. This is applicable for platforms which do not
@ -639,7 +636,7 @@ Common build options
cluster platforms). If this option is enabled, then warm boot path cluster platforms). If this option is enabled, then warm boot path
enables D-caches immediately after enabling MMU. This option defaults to 0. enables D-caches immediately after enabling MMU. This option defaults to 0.
ARM development platform specific build options Arm development platform specific build options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- ``ARM_BL31_IN_DRAM``: Boolean option to select loading of BL31 in TZC secured - ``ARM_BL31_IN_DRAM``: Boolean option to select loading of BL31 in TZC secured
@ -652,7 +649,7 @@ ARM development platform specific build options
of the memory reserved for each image. This affects the maximum size of each of the memory reserved for each image. This affects the maximum size of each
BL image as well as the number of allocated memory regions and translation BL image as well as the number of allocated memory regions and translation
tables. By default this flag is 0, which means it uses the default tables. By default this flag is 0, which means it uses the default
unoptimised values for these macros. ARM development platforms that wish to unoptimised values for these macros. Arm development platforms that wish to
optimise memory usage need to set this flag to 1 and must override the optimise memory usage need to set this flag to 1 and must override the
related macros. related macros.
@ -663,7 +660,7 @@ ARM development platform specific build options
Default is true (access to the frame is allowed). Default is true (access to the frame is allowed).
- ``ARM_DISABLE_TRUSTED_WDOG``: boolean option to disable the Trusted Watchdog. - ``ARM_DISABLE_TRUSTED_WDOG``: boolean option to disable the Trusted Watchdog.
By default, ARM platforms use a watchdog to trigger a system reset in case By default, Arm platforms use a watchdog to trigger a system reset in case
an error is encountered during the boot process (for example, when an image an error is encountered during the boot process (for example, when an image
could not be loaded or authenticated). The watchdog is enabled in the early could not be loaded or authenticated). The watchdog is enabled in the early
platform setup hook at BL1 and disabled in the BL1 prepare exit hook. The platform setup hook at BL1 and disabled in the BL1 prepare exit hook. The
@ -680,7 +677,7 @@ ARM development platform specific build options
- ``ARM_ROTPK_LOCATION``: used when ``TRUSTED_BOARD_BOOT=1``. It specifies the - ``ARM_ROTPK_LOCATION``: used when ``TRUSTED_BOARD_BOOT=1``. It specifies the
location of the ROTPK hash returned by the function ``plat_get_rotpk_info()`` location of the ROTPK hash returned by the function ``plat_get_rotpk_info()``
for ARM platforms. Depending on the selected option, the proper private key for Arm platforms. Depending on the selected option, the proper private key
must be specified using the ``ROT_KEY`` option when building the Trusted must be specified using the ``ROT_KEY`` option when building the Trusted
Firmware. This private key will be used by the certificate generation tool Firmware. This private key will be used by the certificate generation tool
to sign the BL2 and Trusted Key certificates. Available options for to sign the BL2 and Trusted Key certificates. Available options for
@ -707,27 +704,26 @@ ARM development platform specific build options
- ``dram`` : Secure region in DRAM (default option when TBB is enabled, - ``dram`` : Secure region in DRAM (default option when TBB is enabled,
configured by the TrustZone controller) configured by the TrustZone controller)
- ``ARM_XLAT_TABLES_LIB_V1``: boolean option to compile the Trusted Firmware - ``ARM_XLAT_TABLES_LIB_V1``: boolean option to compile TF-A with version 1
with version 1 of the translation tables library instead of version 2. It is of the translation tables library instead of version 2. It is set to 0 by
set to 0 by default, which selects version 2. default, which selects version 2.
- ``ARM_CRYPTOCELL_INTEG`` : bool option to enable Trusted Firmware to invoke - ``ARM_CRYPTOCELL_INTEG`` : bool option to enable TF-A to invoke Arm®
ARM® TrustZone® CryptoCell functionality for Trusted Board Boot on capable TrustZone® CryptoCell functionality for Trusted Board Boot on capable Arm
ARM platforms. If this option is specified, then the path to the CryptoCell platforms. If this option is specified, then the path to the CryptoCell
SBROM library must be specified via ``CCSBROM_LIB_PATH`` flag. SBROM library must be specified via ``CCSBROM_LIB_PATH`` flag.
For a better understanding of these options, the ARM development platform memory For a better understanding of these options, the Arm development platform memory
map is explained in the `Firmware Design`_. map is explained in the `Firmware Design`_.
ARM CSS platform specific build options Arm CSS platform specific build options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- ``CSS_DETECT_PRE_1_7_0_SCP``: Boolean flag to detect SCP version - ``CSS_DETECT_PRE_1_7_0_SCP``: Boolean flag to detect SCP version
incompatibility. Version 1.7.0 of the SCP firmware made a non-backwards incompatibility. Version 1.7.0 of the SCP firmware made a non-backwards
compatible change to the MTL protocol, used for AP/SCP communication. compatible change to the MTL protocol, used for AP/SCP communication.
Trusted Firmware no longer supports earlier SCP versions. If this option is TF-A no longer supports earlier SCP versions. If this option is set to 1
set to 1 then Trusted Firmware will detect if an earlier version is in use. then TF-A will detect if an earlier version is in use. Default is 1.
Default is 1.
- ``CSS_LOAD_SCP_IMAGES``: Boolean flag, which when set, adds SCP\_BL2 and - ``CSS_LOAD_SCP_IMAGES``: Boolean flag, which when set, adds SCP\_BL2 and
SCP\_BL2U to the FIP and FWU\_FIP respectively, and enables them to be loaded SCP\_BL2U to the FIP and FWU\_FIP respectively, and enables them to be loaded
@ -738,13 +734,12 @@ ARM CSS platform specific build options
management operations and for SCP RAM Firmware transfer. If this option management operations and for SCP RAM Firmware transfer. If this option
is set to 1, then SCMI/SDS drivers will be used. Default is 0. is set to 1, then SCMI/SDS drivers will be used. Default is 0.
ARM FVP platform specific build options Arm FVP platform specific build options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- ``FVP_CLUSTER_COUNT`` : Configures the cluster count to be used to - ``FVP_CLUSTER_COUNT`` : Configures the cluster count to be used to
build the topology tree within Trusted Firmware. By default the build the topology tree within TF-A. By default TF-A is configured for dual
Trusted Firmware is configured for dual cluster topology and this option cluster topology and this option can be used to override the default value.
can be used to override the default value.
- ``FVP_INTERCONNECT_DRIVER``: Selects the interconnect driver to be built. The - ``FVP_INTERCONNECT_DRIVER``: Selects the interconnect driver to be built. The
default interconnect driver depends on the value of ``FVP_CLUSTER_COUNT`` as default interconnect driver depends on the value of ``FVP_CLUSTER_COUNT`` as
@ -768,9 +763,8 @@ ARM FVP platform specific build options
- ``FVP_GICV2`` : The GICv2 only driver is selected - ``FVP_GICV2`` : The GICv2 only driver is selected
- ``FVP_GICV3`` : The GICv3 only driver is selected (default option) - ``FVP_GICV3`` : The GICv3 only driver is selected (default option)
- ``FVP_GICV3_LEGACY``: The Legacy GICv3 driver is selected (deprecated) - ``FVP_GICV3_LEGACY``: The Legacy GICv3 driver is selected (deprecated)
Note: If Trusted Firmware is compiled with this option on FVPs with Note: If TF-A is compiled with this option on FVPs with GICv3 hardware,
GICv3 hardware, then it configures the hardware to run in GICv2 then it configures the hardware to run in GICv2 emulation mode
emulation mode
- ``FVP_USE_SP804_TIMER`` : Use the SP804 timer instead of the Generic Timer - ``FVP_USE_SP804_TIMER`` : Use the SP804 timer instead of the Generic Timer
for functions that wait for an arbitrary time length (udelay and mdelay). for functions that wait for an arbitrary time length (udelay and mdelay).
@ -808,7 +802,7 @@ When debugging logic problems it might also be useful to disable all compiler
optimizations by using ``-O0``. optimizations by using ``-O0``.
NOTE: Using ``-O0`` could cause output images to be larger and base addresses 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 might need to be recalculated (see the **Memory layout on Arm development
platforms** section in the `Firmware Design`_). platforms** section in the `Firmware Design`_).
Extra debug options can be passed to the build system by setting ``CFLAGS`` or Extra debug options can be passed to the build system by setting ``CFLAGS`` or
@ -823,8 +817,8 @@ Note that using ``-Wl,`` style compilation driver options in ``CFLAGS`` will be
ignored as the linker is called directly. ignored as the linker is called directly.
It is also possible to introduce an infinite loop to help in debugging the It is also possible to introduce an infinite loop to help in debugging the
post-BL2 phase of the Trusted Firmware. This can be done by rebuilding BL1 with post-BL2 phase of TF-A. This can be done by rebuilding BL1 with the
the ``SPIN_ON_BL1_EXIT=1`` build flag. Refer to the `Summary of build options`_ ``SPIN_ON_BL1_EXIT=1`` build flag. Refer to the `Summary of build options`_
section. In this case, the developer may take control of the target using a section. In this case, the developer may take control of the target using a
debugger when indicated by the console output. When using DS-5, the following debugger when indicated by the console output. When using DS-5, the following
commands can be used: commands can be used:
@ -852,8 +846,8 @@ 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 must be recompiled as well. For more information on SPs and SPDs, see the
`Secure-EL1 Payloads and Dispatchers`_ section in the `Firmware Design`_. `Secure-EL1 Payloads and Dispatchers`_ section in the `Firmware Design`_.
First clean the Trusted Firmware build directory to get rid of any previous First clean the TF-A build directory to get rid of any previous BL31 binary.
BL31 binary. Then to build the TSP image use: Then to build the TSP image use:
:: ::
@ -895,17 +889,17 @@ is set to ``origin/master``.
Building and using the FIP tool Building and using the FIP tool
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Firmware Image Package (FIP) is a packaging format used by the Trusted Firmware Firmware Image Package (FIP) is a packaging format used by TF-A to package
project to package firmware images in a single binary. The number and type of firmware images in a single binary. The number and type of images that should
images that should be packed in a FIP is platform specific and may include TF be packed in a FIP is platform specific and may include TF-A images and other
images and other firmware images required by the platform. For example, most firmware images required by the platform. For example, most platforms require
platforms require a BL33 image which corresponds to the normal world bootloader a BL33 image which corresponds to the normal world bootloader (e.g. UEFI or
(e.g. UEFI or U-Boot). U-Boot).
The TF build system provides the make target ``fip`` to create a FIP file for the The TF-A build system provides the make target ``fip`` to create a FIP file
specified platform using the FIP creation tool included in the TF project. for the specified platform using the FIP creation tool included in the TF-A
Examples below show how to build a FIP file for FVP, packaging TF images and a project. Examples below show how to build a FIP file for FVP, packaging TF-A
BL33 image. and BL33 images.
For AArch64: For AArch64:
@ -1026,9 +1020,10 @@ images with support for these features:
#. Fulfill the dependencies of the ``mbedtls`` cryptographic and image parser #. Fulfill the dependencies of the ``mbedtls`` cryptographic and image parser
modules by checking out a recent version of the `mbed TLS Repository`_. It modules by checking out a recent version of the `mbed TLS Repository`_. It
is important to use a version that is compatible with TF and fixes any 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 known security vulnerabilities. See `mbed TLS Security Center`_ for more
information. The latest version of TF is tested with tag ``mbedtls-2.6.0``. information. The latest version of TF-A is tested with tag
``mbedtls-2.6.0``.
The ``drivers/auth/mbedtls/mbedtls_*.mk`` files contain the list of mbed TLS The ``drivers/auth/mbedtls/mbedtls_*.mk`` files contain the list of mbed TLS
source files the modules depend upon. source files the modules depend upon.
@ -1036,17 +1031,17 @@ images with support for these features:
options required to build the mbed TLS sources. options required to build the mbed TLS sources.
Note that the mbed TLS library is licensed under the Apache version 2.0 Note that the mbed TLS library is licensed under the Apache version 2.0
license. Using mbed TLS source code will affect the licensing of license. Using mbed TLS source code will affect the licensing of TF-A
Trusted Firmware binaries that are built using this library. binaries that are built using this library.
#. To build the FIP image, ensure the following command line variables are set #. To build the FIP image, ensure the following command line variables are set
while invoking ``make`` to build Trusted Firmware: while invoking ``make`` to build TF-A:
- ``MBEDTLS_DIR=<path of the directory containing mbed TLS sources>`` - ``MBEDTLS_DIR=<path of the directory containing mbed TLS sources>``
- ``TRUSTED_BOARD_BOOT=1`` - ``TRUSTED_BOARD_BOOT=1``
- ``GENERATE_COT=1`` - ``GENERATE_COT=1``
In the case of ARM platforms, the location of the ROTPK hash must also be In the case of Arm platforms, the location of the ROTPK hash must also be
specified at build time. Two locations are currently supported (see specified at build time. Two locations are currently supported (see
``ARM_ROTPK_LOCATION`` build option): ``ARM_ROTPK_LOCATION`` build option):
@ -1060,11 +1055,11 @@ images with support for these features:
available. available.
- ``ARM_ROTPK_LOCATION=devel_rsa``: use the ROTPK hash that is hardcoded - ``ARM_ROTPK_LOCATION=devel_rsa``: use the ROTPK hash that is hardcoded
in the ARM platform port. The private/public RSA key pair may be in the Arm platform port. The private/public RSA key pair may be
found in ``plat/arm/board/common/rotpk``. found in ``plat/arm/board/common/rotpk``.
- ``ARM_ROTPK_LOCATION=devel_ecdsa``: use the ROTPK hash that is hardcoded - ``ARM_ROTPK_LOCATION=devel_ecdsa``: use the ROTPK hash that is hardcoded
in the ARM platform port. The private/public ECDSA key pair may be in the Arm platform port. The private/public ECDSA key pair may be
found in ``plat/arm/board/common/rotpk``. found in ``plat/arm/board/common/rotpk``.
Example of command line using RSA development keys: Example of command line using RSA development keys:
@ -1086,7 +1081,7 @@ images with support for these features:
#. The optional FWU\_FIP contains any additional images to be loaded from #. The optional FWU\_FIP contains any additional images to be loaded from
Non-Volatile storage during the `Firmware Update`_ process. To build the 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 FWU\_FIP, any FWU images required by the platform must be specified on the
command line. On ARM development platforms like Juno, these are: command line. On Arm development platforms like Juno, these are:
- NS\_BL2U. The AP non-secure Firmware Updater image. - NS\_BL2U. The AP non-secure Firmware Updater image.
- SCP\_BL2U. The SCP Firmware Update Configuration image. - SCP\_BL2U. The SCP Firmware Update Configuration image.
@ -1121,9 +1116,10 @@ images with support for these features:
Building the Certificate Generation Tool Building the Certificate Generation Tool
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``cert_create`` tool is built as part of the TF build process when the ``fip`` The ``cert_create`` tool is built as part of the TF-A build process when the
make target is specified and TBB is enabled (as described in the previous ``fip`` make target is specified and TBB is enabled (as described in the
section), but it can also be built separately with the following command: previous section), but it can also be built separately with the following
command:
:: ::
@ -1188,7 +1184,7 @@ corrupted binaries.
Note for AArch32, the instructions below assume that nt-fw.bin is a custom Note for AArch32, the instructions below assume that nt-fw.bin is a custom
Normal world boot loader that supports AArch32. Normal world boot loader that supports AArch32.
#. Build TF images and create a new FIP for FVP #. Build TF-A images and create a new FIP for FVP
:: ::
@ -1198,7 +1194,7 @@ corrupted binaries.
# AArch32 # AArch32
make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=nt-fw.bin all fip make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=nt-fw.bin all fip
#. Build TF images and create a new FIP for Juno #. Build TF-A images and create a new FIP for Juno
For AArch64: For AArch64:
@ -1322,16 +1318,16 @@ scratch, this is a complex task on some platforms, depending on the level of
configuration required to put the system in the expected state. configuration required to put the system in the expected state.
Rather than booting a baremetal application, a possible compromise is to boot Rather than booting a baremetal application, a possible compromise is to boot
``EL3 payloads`` through the Trusted Firmware instead. This is implemented as an ``EL3 payloads`` through TF-A instead. This is implemented as an alternative
alternative boot flow, where a modified BL2 boots an EL3 payload, instead of boot flow, where a modified BL2 boots an EL3 payload, instead of loading the
loading the other BL images and passing control to BL31. It reduces the other BL images and passing control to BL31. It reduces the complexity of
complexity of developing EL3 baremetal code by: developing EL3 baremetal code by:
- putting the system into a known architectural state; - putting the system into a known architectural state;
- taking care of platform secure world initialization; - taking care of platform secure world initialization;
- loading the SCP\_BL2 image if required by the platform. - loading the SCP\_BL2 image if required by the platform.
When booting an EL3 payload on ARM standard platforms, the configuration of the When booting an EL3 payload on Arm standard platforms, the configuration of the
TrustZone controller is simplified such that only region 0 is enabled and is TrustZone controller is simplified such that only region 0 is enabled and is
configured to permit secure access only. This gives full access to the whole configured to permit secure access only. This gives full access to the whole
DRAM to the EL3 payload. DRAM to the EL3 payload.
@ -1350,11 +1346,11 @@ Booting an EL3 payload
~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~
The EL3 payload image is a standalone image and is not part of the FIP. It is The EL3 payload image is a standalone image and is not part of the FIP. It is
not loaded by the Trusted Firmware. Therefore, there are 2 possible scenarios: not loaded by TF-A. Therefore, there are 2 possible scenarios:
- The EL3 payload may reside in non-volatile memory (NVM) and execute in - The EL3 payload may reside in non-volatile memory (NVM) and execute in
place. In this case, booting it is just a matter of specifying the right place. In this case, booting it is just a matter of specifying the right
address in NVM through ``EL3_PAYLOAD_BASE`` when building the TF. address in NVM through ``EL3_PAYLOAD_BASE`` when building TF-A.
- The EL3 payload needs to be loaded in volatile memory (e.g. DRAM) at - The EL3 payload needs to be loaded in volatile memory (e.g. DRAM) at
run-time. run-time.
@ -1423,7 +1419,7 @@ used:
--data="/path/to/el3-payload"@address [Foundation FVP] --data="/path/to/el3-payload"@address [Foundation FVP]
The address provided to the FVP must match the ``EL3_PAYLOAD_BASE`` address The address provided to the FVP must match the ``EL3_PAYLOAD_BASE`` address
used when building the Trusted Firmware. used when building TF-A.
Booting an EL3 payload on Juno Booting an EL3 payload on Juno
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -1441,15 +1437,14 @@ Preloaded BL33 alternative boot flow
------------------------------------ ------------------------------------
Some platforms have the ability to preload BL33 into memory instead of relying Some platforms have the ability to preload BL33 into memory instead of relying
on Trusted Firmware to load it. This may simplify packaging of the normal world on TF-A to load it. This may simplify packaging of the normal world code and
code and improve performance in a development environment. When secure world improve performance in a development environment. When secure world cold boot
cold boot is complete, Trusted Firmware simply jumps to a BL33 base address is complete, TF-A simply jumps to a BL33 base address provided at build time.
provided at build time.
For this option to be used, the ``PRELOADED_BL33_BASE`` build option has to be For this option to be used, the ``PRELOADED_BL33_BASE`` build option has to be
used when compiling the Trusted Firmware. For example, the following command used when compiling TF-A. For example, the following command will create a FIP
will create a FIP without a BL33 and prepare to jump to a BL33 image loaded at without a BL33 and prepare to jump to a BL33 image loaded at address
address 0x80000000: 0x80000000:
:: ::
@ -1459,8 +1454,8 @@ Boot of a preloaded bootwrapped kernel image on Base FVP
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following example uses the AArch64 boot wrapper. This simplifies normal The following example uses the AArch64 boot wrapper. This simplifies normal
world booting while also making use of TF features. It can be obtained from its world booting while also making use of TF-A features. It can be obtained from
repository with: its repository with:
:: ::
@ -1494,8 +1489,8 @@ to load the ELF file over JTAG on Juno.
Running the software on FVP Running the software on FVP
--------------------------- ---------------------------
The latest version of the AArch64 build of ARM Trusted Firmware has been tested The latest version of the AArch64 build of TF-A has been tested on the
on the following ARM FVPs (64-bit host machine only). following Arm FVPs (64-bit host machine only).
NOTE: Unless otherwise stated, the model version is Version 11.2 Build 11.2.33. NOTE: Unless otherwise stated, the model version is Version 11.2 Build 11.2.33.
@ -1510,8 +1505,8 @@ NOTE: Unless otherwise stated, the model version is Version 11.2 Build 11.2.33.
- ``FVP_Base_Cortex-A73x4-A53x4`` - ``FVP_Base_Cortex-A73x4-A53x4``
- ``FVP_Base_Cortex-A73x4`` - ``FVP_Base_Cortex-A73x4``
The latest version of the AArch32 build of ARM Trusted Firmware has been tested The latest version of the AArch32 build of TF-A has been tested on the
on the following ARM FVPs (64-bit host machine only). following Arm FVPs (64-bit host machine only).
- ``FVP_Base_AEMv8A-AEMv8A`` (Version 9.0, Build 0.8.9005) - ``FVP_Base_AEMv8A-AEMv8A`` (Version 9.0, Build 0.8.9005)
- ``FVP_Base_Cortex-A32x4`` - ``FVP_Base_Cortex-A32x4``
@ -1529,7 +1524,7 @@ 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. The commands below would report an ``unhandled argument`` error in this case.
NOTE: FVPs can be launched with ``--cadi-server`` option such that a 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 CADI-compliant debugger (for example, Arm DS-5) can connect to and control its
execution. execution.
NOTE: Since FVP model Version 11.0 Build 11.0.34 and Version 8.5 Build 0.8.5202 NOTE: Since FVP model Version 11.0 Build 11.0.34 and Version 8.5 Build 0.8.5202
@ -1538,23 +1533,23 @@ models. The models can be launched with ``-Q 100`` option if they are required
to match the run time characteristics of the older versions. 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 The Foundation FVP is a cut down version of the AArch64 Base FVP. It can be
downloaded for free from `ARM's website`_. downloaded for free from `Arm's website`_.
The Cortex-A models listed above are also available to download from The Cortex-A models listed above are also available to download from
`ARM's website`_. `Arm's website`_.
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 ARM parameter options. A brief description of the important ones that affect TF-A
Trusted Firmware and normal world software behavior is provided below. and normal world software behavior is provided below.
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 TF-A source directory under ``fdts/``. The Foundation FVP has a subset of
subset of the Base FVP components. For example, the Foundation FVP lacks CLCD the Base FVP components. For example, the Foundation FVP lacks CLCD and MMC
and MMC support, and has only one CPU cluster. support, and has only one CPU cluster.
Note: It is not recommended to use the FDTs built along the kernel because not Note: It is not recommended to use the FDTs built along the kernel because not
all FDTs are available from there. all FDTs are available from there.
@ -1592,7 +1587,7 @@ Running on the Foundation FVP with reset to BL1 entrypoint
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following ``Foundation_Platform`` parameters should be used to boot Linux with The following ``Foundation_Platform`` parameters should be used to boot Linux with
4 CPUs using the AArch64 build of ARM Trusted Firmware. 4 CPUs using the AArch64 build of TF-A.
:: ::
@ -1616,19 +1611,19 @@ Notes:
- The default use-case for the Foundation FVP is to use the ``--gicv3`` option - 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, and enable the GICv3 device in the model. Note that without this option,
the Foundation FVP defaults to legacy (Versatile Express) memory map which the Foundation FVP defaults to legacy (Versatile Express) memory map which
is not supported by ARM Trusted Firmware. is not supported by TF-A.
- In order for the Arm Trusted Firmware to run correctly on the Foundation - In order for TF-A to run correctly on the Foundation FVP, the architecture
Model the architecture versions must match. The Foundation FVP defaults to versions must match. The Foundation FVP defaults to the highest v8.x
the highest v8.x version it supports but the default build for Arm Trusted version it supports but the default build for TF-A is for v8.0. To avoid
Firmware is for v8.0. To avoid issues either start the Foundation Model to issues either start the Foundation FVP to use v8.0 architecture using the
use v8.0 architecture using the ``--arm-v8.0`` option or build Arm Trusted ``--arm-v8.0`` option, or build TF-A with an appropriate value for
Firmware with an appropriate value for ``ARM_ARCH_MINOR``. ``ARM_ARCH_MINOR``.
Running on the AEMv8 Base FVP with reset to BL1 entrypoint Running on the AEMv8 Base FVP with reset to BL1 entrypoint
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux
with 8 CPUs using the AArch64 build of ARM Trusted Firmware. with 8 CPUs using the AArch64 build of TF-A.
:: ::
@ -1649,7 +1644,7 @@ Running on the AEMv8 Base FVP (AArch32) with reset to BL1 entrypoint
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux
with 8 CPUs using the AArch32 build of ARM Trusted Firmware. with 8 CPUs using the AArch32 build of TF-A.
:: ::
@ -1678,7 +1673,7 @@ Running on the Cortex-A57-A53 Base FVP with reset to BL1 entrypoint
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following ``FVP_Base_Cortex-A57x4-A53x4`` model parameters should be used to The following ``FVP_Base_Cortex-A57x4-A53x4`` model parameters should be used to
boot Linux with 8 CPUs using the AArch64 build of ARM Trusted Firmware. boot Linux with 8 CPUs using the AArch64 build of TF-A.
:: ::
@ -1697,7 +1692,7 @@ Running on the Cortex-A32 Base FVP (AArch32) with reset to BL1 entrypoint
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following ``FVP_Base_Cortex-A32x4`` model parameters should be used to The following ``FVP_Base_Cortex-A32x4`` model parameters should be used to
boot Linux with 4 CPUs using the AArch32 build of ARM Trusted Firmware. boot Linux with 4 CPUs using the AArch32 build of TF-A.
:: ::
@ -1716,7 +1711,7 @@ Running on the AEMv8 Base FVP with reset to BL31 entrypoint
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux
with 8 CPUs using the AArch64 build of ARM Trusted Firmware. with 8 CPUs using the AArch64 build of TF-A.
:: ::
@ -1763,7 +1758,7 @@ Running on the AEMv8 Base FVP (AArch32) with reset to SP\_MIN entrypoint
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux
with 8 CPUs using the AArch32 build of ARM Trusted Firmware. with 8 CPUs using the AArch32 build of TF-A.
:: ::
@ -1803,7 +1798,7 @@ Running on the Cortex-A57-A53 Base FVP with reset to BL31 entrypoint
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following ``FVP_Base_Cortex-A57x4-A53x4`` model parameters should be used to The following ``FVP_Base_Cortex-A57x4-A53x4`` model parameters should be used to
boot Linux with 8 CPUs using the AArch64 build of ARM Trusted Firmware. boot Linux with 8 CPUs using the AArch64 build of TF-A.
:: ::
@ -1831,7 +1826,7 @@ Running on the Cortex-A32 Base FVP (AArch32) with reset to SP\_MIN entrypoint
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following ``FVP_Base_Cortex-A32x4`` model parameters should be used to The following ``FVP_Base_Cortex-A32x4`` model parameters should be used to
boot Linux with 4 CPUs using the AArch32 build of ARM Trusted Firmware. boot Linux with 4 CPUs using the AArch32 build of TF-A.
:: ::
@ -1853,8 +1848,7 @@ boot Linux with 4 CPUs using the AArch32 build of ARM Trusted Firmware.
Running the software on Juno Running the software on Juno
---------------------------- ----------------------------
This version of the ARM Trusted Firmware has been tested on variants r0, r1 and This version of TF-A has been tested on variants r0, r1 and r2 of Juno.
r2 of Juno.
To execute the software stack on Juno, the version of the Juno board recovery 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 image indicated in the `Linaro Release Notes`_ must be installed. If you have an
@ -1862,18 +1856,18 @@ earlier version installed or are unsure which version is installed, please
re-install the recovery image by following the re-install the recovery image by following the
`Instructions for using Linaro's deliverables on Juno`_. `Instructions for using Linaro's deliverables on Juno`_.
Preparing Trusted Firmware images Preparing TF-A images
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~
After building Trusted Firmware, the files ``bl1.bin`` and ``fip.bin`` need copying After building TF-A, the files ``bl1.bin`` and ``fip.bin`` need copying to the
to the ``SOFTWARE/`` directory of the Juno SD card. ``SOFTWARE/`` directory of the Juno SD card.
Other Juno software information Other Juno software information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Please visit the `ARM Platforms Portal`_ to get support and obtain any other Juno Please visit the `Arm Platforms Portal`_ to get support and obtain any other Juno
software information. Please also refer to the `Juno Getting Started Guide`_ to software information. Please also refer to the `Juno Getting Started Guide`_ to
get more detailed information about the Juno ARM development platform and how to get more detailed information about the Juno Arm development platform and how to
configure it. configure it.
Testing SYSTEM SUSPEND on Juno Testing SYSTEM SUSPEND on Juno
@ -1893,7 +1887,7 @@ wakeup interrupt from RTC.
-------------- --------------
*Copyright (c) 2013-2018, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2013-2018, Arm Limited and Contributors. All rights reserved.*
.. _Linaro: `Linaro Release Notes`_ .. _Linaro: `Linaro Release Notes`_
.. _Linaro Release: `Linaro Release Notes`_ .. _Linaro Release: `Linaro Release Notes`_
@ -1901,7 +1895,7 @@ wakeup interrupt from RTC.
.. _Linaro Release 17.10: https://community.arm.com/dev-platforms/w/docs/226/old-linaro-release-notes#1710 .. _Linaro Release 17.10: https://community.arm.com/dev-platforms/w/docs/226/old-linaro-release-notes#1710
.. _Linaro instructions: https://community.arm.com/dev-platforms/w/docs/304/linaro-software-deliverables .. _Linaro instructions: https://community.arm.com/dev-platforms/w/docs/304/linaro-software-deliverables
.. _Instructions for using Linaro's deliverables on Juno: https://community.arm.com/dev-platforms/w/docs/303/juno .. _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/ .. _Arm Platforms Portal: https://community.arm.com/dev-platforms/
.. _Development Studio 5 (DS-5): http://www.arm.com/products/tools/software-tools/ds-5/index.php .. _Development Studio 5 (DS-5): http://www.arm.com/products/tools/software-tools/ds-5/index.php
.. _Dia: https://wiki.gnome.org/Apps/Dia/Download .. _Dia: https://wiki.gnome.org/Apps/Dia/Download
.. _here: psci-lib-integration-guide.rst .. _here: psci-lib-integration-guide.rst
@ -1911,7 +1905,7 @@ wakeup interrupt from RTC.
.. _Firmware Design: firmware-design.rst .. _Firmware Design: firmware-design.rst
.. _mbed TLS Repository: https://github.com/ARMmbed/mbedtls.git .. _mbed TLS Repository: https://github.com/ARMmbed/mbedtls.git
.. _mbed TLS Security Center: https://tls.mbed.org/security .. _mbed TLS Security Center: https://tls.mbed.org/security
.. _ARM's website: `FVP models`_ .. _Arm's website: `FVP models`_
.. _FVP models: https://developer.arm.com/products/system-design/fixed-virtual-platforms .. _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 .. _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 .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf

12
docs/xlat-tables-lib-v2-design.rst
View file

@ -9,7 +9,7 @@ Translation Tables Library Design
This document describes the design of the translation tables library (version 2) This document describes the design of the translation tables library (version 2)
used by the ARM Trusted Firmware. This library provides APIs to create page used by Trusted Firmware-A (TF-A). This library provides APIs to create page
tables based on a description of the memory layout, as well as setting up system tables based on a description of the memory layout, as well as setting up system
registers related to the Memory Management Unit (MMU) and performing the registers related to the Memory Management Unit (MMU) and performing the
required Translation Lookaside Buffer (TLB) maintenance operations. required Translation Lookaside Buffer (TLB) maintenance operations.
@ -329,7 +329,7 @@ The memory mapping algorithm
^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The mapping function is implemented as a recursive algorithm. It is however The mapping function is implemented as a recursive algorithm. It is however
bound by the level of depth of the translation tables (the ARMv8-A architecture bound by the level of depth of the translation tables (the Armv8-A architecture
allows up to 4 lookup levels). allows up to 4 lookup levels).
By default [#granularity-ref]_, the algorithm will attempt to minimize the By default [#granularity-ref]_, the algorithm will attempt to minimize the
@ -376,7 +376,7 @@ changes are visible to subsequent execution, including speculative execution,
that uses the changed translation table entries. that uses the changed translation table entries.
A counter-example is the initialization of translation tables. In this case, A counter-example is the initialization of translation tables. In this case,
explicit TLB maintenance is not required. The ARMv8-A architecture guarantees explicit TLB maintenance is not required. The Armv8-A architecture guarantees
that all TLBs are disabled from reset and their contents have no effect on that all TLBs are disabled from reset and their contents have no effect on
address translation at reset [#tlb-reset-ref]_. Therefore, the TLBs invalidation address translation at reset [#tlb-reset-ref]_. Therefore, the TLBs invalidation
is deferred to the ``enable_mmu*()`` family of functions, just before the MMU is is deferred to the ``enable_mmu*()`` family of functions, just before the MMU is
@ -391,9 +391,9 @@ descriptor. Given that the TLBs are not architecturally permitted to hold any
invalid translation table entry [#tlb-no-invalid-entry]_, this means that this invalid translation table entry [#tlb-no-invalid-entry]_, this means that this
mapping cannot be cached in the TLBs. mapping cannot be cached in the TLBs.
.. [#tlb-reset-ref] See section D4.8 `Translation Lookaside Buffers (TLBs)`, subsection `TLB behavior at reset` in ARMv8-A, rev B.a. .. [#tlb-reset-ref] See section D4.8 `Translation Lookaside Buffers (TLBs)`, subsection `TLB behavior at reset` in Armv8-A, rev B.a.
.. [#tlb-no-invalid-entry] See section D4.9.1 `General TLB maintenance requirements` in ARMv8-A, rev B.a. .. [#tlb-no-invalid-entry] See section D4.9.1 `General TLB maintenance requirements` in Armv8-A, rev B.a.
Architectural module Architectural module
~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~
@ -405,7 +405,7 @@ translation context to work on.
-------------- --------------
*Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2017-2018, Arm Limited and Contributors. All rights reserved.*
.. _lib/xlat\_tables\_v2: ../lib/xlat_tables_v2 .. _lib/xlat\_tables\_v2: ../lib/xlat_tables_v2
.. _lib/xlat\_tables: ../lib/xlat_tables .. _lib/xlat\_tables: ../lib/xlat_tables

4
license.rst
View file

@ -1,4 +1,4 @@
Copyright (c) 2013-2017, ARM Limited and Contributors. All rights reserved. Copyright (c) 2013-2018, Arm Limited and Contributors. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met: are permitted provided that the following conditions are met:
@ -10,7 +10,7 @@ are permitted provided that the following conditions are met:
list of conditions and the following disclaimer in the documentation and/or list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution. other materials provided with the distribution.
- Neither the name of ARM nor the names of its contributors may be used to - Neither the name of Arm nor the names of its contributors may be used to
endorse or promote products derived from this software without specific prior endorse or promote products derived from this software without specific prior
written permission. written permission.

10
maintainers.rst
View file

@ -1,7 +1,7 @@
ARM Trusted Firmware Maintainers Trusted Firmware-A maintainers
================================ ==============================
ARM Trusted Firmware is an ARM maintained project. All contributions are Trusted Firmware-A (TF-A) is an Arm maintained project. All contributions are
ultimately merged by the maintainers listed below. Technical ownership of some ultimately merged by the maintainers listed below. Technical ownership of some
parts of the codebase is delegated to the sub-maintainers listed below. An parts of the codebase is delegated to the sub-maintainers listed below. An
acknowledgement from these sub-maintainers may be required before the acknowledgement from these sub-maintainers may be required before the
@ -123,8 +123,8 @@ Files:
- docs/plat/xilinx-zynqmp.rst - docs/plat/xilinx-zynqmp.rst
- plat/xilinx/\* - plat/xilinx/\*
ARMv7 architecture sub-maintainer Armv7-A architecture sub-maintainer
--------------------------------- -----------------------------------
Etienne Carriere (etienne.carriere@linaro.org, `etienne-lms`_) Etienne Carriere (etienne.carriere@linaro.org, `etienne-lms`_)

64
readme.rst
View file

@ -1,21 +1,21 @@
ARM Trusted Firmware - version 1.4 Trusted Firmware-A - version 1.4
================================== ================================
ARM Trusted Firmware provides a reference implementation of secure world Trusted Firmware-A (TF-A) provides a reference implementation of secure world
software for `ARMv8-A`_, including a `Secure Monitor`_ executing at software for `Armv8-A`_, including a `Secure Monitor`_ executing at Exception
Exception Level 3 (EL3). It implements various ARM interface standards, such as: Level 3 (EL3). It implements various Arm interface standards, such as:
- The `Power State Coordination Interface (PSCI)`_ - The `Power State Coordination Interface (PSCI)`_
- Trusted Board Boot Requirements (TBBR, ARM DEN0006C-1) - Trusted Board Boot Requirements (TBBR, Arm DEN0006C-1)
- `SMC Calling Convention`_ - `SMC Calling Convention`_
- `System Control and Management Interface`_ - `System Control and Management Interface`_
As far as possible the code is designed for reuse or porting to other ARMv8-A As far as possible the code is designed for reuse or porting to other Armv8-A
model and hardware platforms. model and hardware platforms.
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 Secure Monitor code and ARM standards provide a full reference implementation of Secure Monitor code and Arm standards
to the benefit of all developers working with ARMv8-A TrustZone technology. to the benefit of all developers working with Armv8-A TrustZone technology.
License License
------- -------
@ -45,7 +45,7 @@ world boot and runtime firmware, in either the AArch32 or AArch64 execution
state. state.
Users are encouraged to do their own security validation, including penetration Users are encouraged to do their own security validation, including penetration
testing, on any secure world code derived from ARM Trusted Firmware. testing, on any secure world code derived from TF-A.
Functionality Functionality
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
@ -54,15 +54,15 @@ Functionality
registers and interrupts for the platform. registers and interrupts for the platform.
- Library support for CPU specific reset and power down sequences. This - Library support for CPU specific reset and power down sequences. This
includes support for errata workarounds and the latest ARM DynamIQ CPUs. includes support for errata workarounds and the latest Arm DynamIQ CPUs.
- Drivers to enable standard initialization of ARM System IP, for example - Drivers to enable standard initialization of Arm System IP, for example
Generic Interrupt Controller (GIC), Cache Coherent Interconnect (CCI), Generic Interrupt Controller (GIC), Cache Coherent Interconnect (CCI),
Cache Coherent Network (CCN), Network Interconnect (NIC) and TrustZone Cache Coherent Network (CCN), Network Interconnect (NIC) and TrustZone
Controller (TZC). Controller (TZC).
- A generic `SCMI`_ driver to interface with conforming power controllers, for - A generic `SCMI`_ driver to interface with conforming power controllers, for
example the ARM System Control Processor (SCP). example the Arm System Control Processor (SCP).
- SMC (Secure Monitor Call) handling, conforming to the `SMC Calling - SMC (Secure Monitor Call) handling, conforming to the `SMC Calling
Convention`_ using an EL3 runtime services framework. Convention`_ using an EL3 runtime services framework.
@ -93,14 +93,14 @@ Functionality
recovery mode), and packaging of the various firmware images into a recovery mode), and packaging of the various firmware images into a
Firmware Image Package (FIP). Firmware Image Package (FIP).
- Pre-integration of TBB with the ARM TrustZone CryptoCell product, to take - Pre-integration of TBB with the Arm TrustZone CryptoCell product, to take
advantage of its hardware Root of Trust and crypto acceleration services. advantage of its hardware Root of Trust and crypto acceleration services.
- Support for alternative boot flows, for example to support platforms where - Support for alternative boot flows, for example to support platforms where
the EL3 Runtime Software is loaded using other firmware or a separate the EL3 Runtime Software is loaded using other firmware or a separate
secure system processor. secure system processor.
- Support for the GCC, LLVM and ARM Compiler 6 toolchains. - Support for the GCC, LLVM and Arm Compiler 6 toolchains.
For a full description of functionality and implementation details, please For a full description of functionality and implementation details, please
see the `Firmware Design`_ and supporting documentation. The `Change Log`_ see the `Firmware Design`_ and supporting documentation. The `Change Log`_
@ -110,9 +110,9 @@ Platforms
~~~~~~~~~ ~~~~~~~~~
Various AArch32 and AArch64 builds of this release has been tested on variants Various AArch32 and AArch64 builds of this release has been tested on variants
r0, r1 and r2 of the `Juno ARM Development Platform`_. r0, r1 and r2 of the `Juno Arm Development Platform`_.
Various AArch64 builds of this release have been tested on the following ARM Various AArch64 builds of this release have been tested on the following Arm
`FVP`_\ s (64-bit host machine only): `FVP`_\ s (64-bit host machine only):
NOTE: Unless otherwise stated, the FVP Version is 11.0, Build 11.0.34. NOTE: Unless otherwise stated, the FVP Version is 11.0, Build 11.0.34.
@ -129,14 +129,14 @@ NOTE: Unless otherwise stated, the FVP Version is 11.0, Build 11.0.34.
- ``FVP_Base_Cortex-A73x4`` - ``FVP_Base_Cortex-A73x4``
- ``FVP_CSS_SGM-775`` (Version 11.0, Build 11.0.36) - ``FVP_CSS_SGM-775`` (Version 11.0, Build 11.0.36)
Various AArch32 builds of this release has been tested on the following ARM Various AArch32 builds of this release has been tested on the following Arm
`FVP`_\ s (64-bit host machine only): `FVP`_\ s (64-bit host machine only):
- ``FVP_Base_AEMv8A-AEMv8A`` (Version 8.5, Build 0.8.8502) - ``FVP_Base_AEMv8A-AEMv8A`` (Version 8.5, Build 0.8.8502)
- ``FVP_Base_Cortex-A32x4`` - ``FVP_Base_Cortex-A32x4``
The Foundation FVP can be downloaded free of charge. The Base FVPs can be The Foundation FVP can be downloaded free of charge. The Base FVPs can be
licensed from ARM. See the `ARM FVP website`_. licensed from Arm. See the `Arm FVP website`_.
All the above platforms have been tested with `Linaro Release 17.04`_. All the above platforms have been tested with `Linaro Release 17.04`_.
@ -167,15 +167,15 @@ Log`_ and the `GitHub issue tracker`_.
Getting Started Getting Started
--------------- ---------------
Get the Trusted Firmware source code from `GitHub`_. Get the TF-A source code from `GitHub`_.
See the `User Guide`_ for instructions on how to install, build and use See the `User Guide`_ for instructions on how to install, build and use
the Trusted Firmware with the ARM `FVP`_\ s. the TF-A with the Arm `FVP`_\ s.
See the `Firmware Design`_ for information on how the Trusted Firmware works. See the `Firmware Design`_ for information on how the TF-A works.
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-A platform. software on another Armv8-A platform.
See the `Contributing Guidelines`_ for information on how to contribute to this See the `Contributing Guidelines`_ for information on how to contribute to this
project and the `Acknowledgments`_ file for a list of contributors to the project and the `Acknowledgments`_ file for a list of contributors to the
@ -184,26 +184,26 @@ project.
Feedback and support Feedback and support
~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~
ARM welcomes any feedback on Trusted Firmware. If you think you have found a Arm welcomes any feedback on TF-A. If you think you have found a security
security vulnerability, please report this using the process defined in the vulnerability, please report this using the process defined in the TF-A
Trusted Firmware `Security Centre`_. For all other feedback, please use the `Security Centre`_. For all other feedback, please use the
`GitHub issue tracker`_. `GitHub issue tracker`_.
ARM licensees may contact ARM directly via their partner managers. Arm licensees may contact Arm directly via their partner managers.
-------------- --------------
*Copyright (c) 2013-2017, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2013-2018, Arm Limited and Contributors. All rights reserved.*
.. _ARMv8-A: http://www.arm.com/products/processors/armv8-architecture.php .. _Armv8-A: http://www.arm.com/products/processors/armv8-architecture.php
.. _Secure Monitor: http://www.arm.com/products/processors/technologies/trustzone/tee-smc.php .. _Secure Monitor: http://www.arm.com/products/processors/technologies/trustzone/tee-smc.php
.. _Power State Coordination Interface (PSCI): PSCI_ .. _Power State Coordination Interface (PSCI): PSCI_
.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
.. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf .. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
.. _System Control and Management Interface: SCMI_ .. _System Control and Management Interface: SCMI_
.. _SCMI: http://infocenter.arm.com/help/topic/com.arm.doc.den0056a/DEN0056A_System_Control_and_Management_Interface.pdf .. _SCMI: http://infocenter.arm.com/help/topic/com.arm.doc.den0056a/DEN0056A_System_Control_and_Management_Interface.pdf
.. _Juno ARM Development Platform: http://www.arm.com/products/tools/development-boards/versatile-express/juno-arm-development-platform.php .. _Juno Arm Development Platform: http://www.arm.com/products/tools/development-boards/versatile-express/juno-arm-development-platform.php
.. _ARM FVP website: FVP_ .. _Arm FVP website: FVP_
.. _FVP: https://developer.arm.com/products/system-design/fixed-virtual-platforms .. _FVP: https://developer.arm.com/products/system-design/fixed-virtual-platforms
.. _Linaro Release 17.04: https://community.arm.com/dev-platforms/b/documents/posts/linaro-release-notes-deprecated#LinaroRelease17.04 .. _Linaro Release 17.04: https://community.arm.com/dev-platforms/b/documents/posts/linaro-release-notes-deprecated#LinaroRelease17.04
.. _OP-TEE Secure OS: https://github.com/OP-TEE/optee_os .. _OP-TEE Secure OS: https://github.com/OP-TEE/optee_os