Skip to content

GitLab

Commit 7cefb56d authored by danh-arm's avatar danh-arm Committed by GitHub
Browse files

Merge pull request #1011 from douglas-raillard-arm/dr/doc_convert_to_rst 

Convert Markdown to reStructuredText
parents aa5b843f 06fb4278
Show whitespace changes
Inline Side-by-side
acknowledgements.md → acknowledgements.rst
View file @ 7cefb56d
......@@ -3,6 +3,7 @@ Contributor Acknowledgements
Companies
---------
Linaro Limited
NVIDIA Corporation
......
contributing.md deleted 100644 → 0
View file @ aa5b843f
Contributing to ARM Trusted Firmware
====================================
Getting Started
---------------
* Make sure you have a [GitHub account].
* 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
licensees may contact ARM directly via their partner managers instead if
they prefer.
* Note that the [issue] tracker for this project is in a separate
[issue tracking repository]. Please follow the guidelines in that
repository.
* If you intend to include Third Party IP in your contribution, please
raise a separate [issue] for this and ensure that the changes that
include Third Party IP are made on a separate topic branch.
* [Fork][] [arm-trusted-firmware][] on GitHub.
* Clone the fork to your own machine.
* Create a local topic branch based on the [arm-trusted-firmware][] `master`
branch.
Making Changes
--------------
* Make commits of logical units. See these general [Git guidelines] for
contributing to a project.
* Follow the [Linux coding style]; this style is enforced for the ARM Trusted
Firmware project (style errors only, not warnings).
* Use the checkpatch.pl script provided with the Linux source tree. A
Makefile target is provided for convenience (see section 2 in the
[User Guide]).
* Keep the commits on topic. If you need to fix another bug or make another
enhancement, please create a separate [issue] and address it on a separate
topic branch.
* Avoid long commit series. If you do have a long series, consider whether
some commits should be squashed together or addressed in a separate topic.
* Make sure your commit messages are in the proper format. If a commit fixes
a GitHub [issue], include a reference (e.g.
"fixes arm-software/tf-issues#45"); this ensures the [issue] is
[automatically closed] when merged into the [arm-trusted-firmware] `master`
branch.
* Where appropriate, please update the documentation.
* Consider whether the [User Guide], [Porting Guide], [Firmware Design] or
other in-source documentation needs updating.
* Ensure that each changed file has the correct copyright and license
information. Files that entirely consist of contributions to this
project should have the copyright notice and BSD-3-Clause SPDX license
identifier as shown in [license.md](./license.md). Files that contain
changes to imported Third Party IP should contain a notice as follows,
with the original copyright and license text retained:
```
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
YYYY is the year of most recent contribution.
* If not done previously, you may add your name or your company name to
the [Acknowledgements] file.
* If you are submitting new files that you intend to be the technical
sub-maintainer for (for example, a new platform port), then also update
the [Maintainers] file.
* For topics with multiple commits, you should make all documentation
changes (and nothing else) in the last commit of the series. Otherwise,
include the documentation changes within the single commit.
* Please test your changes. As a minimum, ensure UEFI boots to the shell on
the Foundation FVP. See the "[Running the software]" section of the
[User Guide] for more information.
Submitting Changes
------------------
* Ensure that each commit in the series has at least one `Signed-off-by:`
line, using your real name and email address. The names in the
`Signed-off-by:` and `Author:` lines must match. If anyone else contributes
to the commit, they must also add their own `Signed-off-by:` line.
By adding this line the contributor certifies the contribution is made under
the terms of the [Developer Certificate of Origin (DCO)][DCO].
* Push your local changes to your fork of the repository.
* Submit a [pull request] to the [arm-trusted-firmware] `integration` branch.
* The changes in the [pull request] will then undergo further review and
testing by the [Maintainers]. Any review comments will be made as
comments on the [pull request]. This may require you to do some rework.
* When the changes are accepted, the [Maintainers] will integrate them.
* Typically, the [Maintainers] will merge the [pull request] into the
`integration` branch within the GitHub UI, creating a merge commit.
* Please avoid creating merge commits in the [pull request] itself.
* If the [pull request] is not based on a recent commit, the [Maintainers]
may rebase it onto the `master` branch first, or ask you to do this.
* If the [pull request] cannot be automatically merged, the [Maintainers]
will ask you to rebase it onto the `master` branch.
* After final integration testing, the [Maintainers] will push your merge
commit to the `master` branch. If a problem is found during integration,
the merge commit will be removed from the `integration` branch and the
[Maintainers] will ask you to create a new pull request to resolve the
problem.
* Please do not delete your topic branch until it is safely merged into
the `master` branch.
- - - - - - - - - - - - - - - - - - - - - - - - - -
_Copyright (c) 2013-2017, ARM Limited and Contributors. All rights reserved._
[User Guide]: ./docs/user-guide.md
[Running the software]: ./docs/user-guide.md#6--running-the-software
[Porting Guide]: ./docs/porting-guide.md
[Firmware Design]: ./docs/firmware-design.md
[Acknowledgements]: ./acknowledgements.md "Contributor acknowledgements"
[DCO]: ./dco.txt
[Maintainers]: ./maintainers.md
[GitHub account]: https://github.com/signup/free
[Fork]: https://help.github.com/articles/fork-a-repo
[issue tracking repository]: https://github.com/ARM-software/tf-issues
[issue]: https://github.com/ARM-software/tf-issues/issues
[pull request]: https://help.github.com/articles/using-pull-requests
[automatically closed]: https://help.github.com/articles/closing-issues-via-commit-messages
[Git guidelines]: http://git-scm.com/book/ch5-2.html
[Linux coding style]: https://www.kernel.org/doc/Documentation/CodingStyle
[arm-trusted-firmware]: https://github.com/ARM-software/arm-trusted-firmware
contributing.rst 0 → 100644
View file @ 7cefb56d
Contributing to ARM Trusted Firmware
====================================
Getting Started
---------------
- Make sure you have a `GitHub account`_.
- 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
licensees may contact ARM directly via their partner managers instead if
they prefer.
- Note that the `issue`_ tracker for this project is in a separate
`issue tracking repository`_. Please follow the guidelines in that
repository.
- If you intend to include Third Party IP in your contribution, please
raise a separate `issue`_ for this and ensure that the changes that
include Third Party IP are made on a separate topic branch.
- `Fork`_ `arm-trusted-firmware`_ on GitHub.
- Clone the fork to your own machine.
- Create a local topic branch based on the `arm-trusted-firmware`_ ``master``
branch.
Making Changes
--------------
- Make commits of logical units. See these general `Git guidelines`_ for
contributing to a project.
- Follow the `Linux coding style`_; this style is enforced for the ARM Trusted
Firmware project (style errors only, not warnings).
- Use the checkpatch.pl script provided with the Linux source tree. A
Makefile target is provided for convenience (see section 2 in the
`User Guide`_).
- Keep the commits on topic. If you need to fix another bug or make another
enhancement, please create a separate `issue`_ and address it on a separate
topic branch.
- Avoid long commit series. If you do have a long series, consider whether
some commits should be squashed together or addressed in a separate topic.
- Make sure your commit messages are in the proper format. If a commit fixes
a GitHub `issue`_, include a reference (e.g.
"fixes arm-software/tf-issues#45"); this ensures the `issue`_ is
`automatically closed`_ when merged into the `arm-trusted-firmware`_ ``master``
branch.
- Where appropriate, please update the documentation.
- Consider whether the `User Guide`_, `Porting Guide`_, `Firmware Design`_ or
other in-source documentation needs updating.
- Ensure that each changed file has the correct copyright and license
information. Files that entirely consist of contributions to this
project should have the copyright notice and BSD-3-Clause SPDX license
identifier as shown in `license.rst`_. Files that contain
changes to imported Third Party IP should contain a notice as follows,
with the original copyright and license text retained:
::
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
YYYY is the year of most recent contribution.
- If not done previously, you may add your name or your company name to
the `Acknowledgements`_ file.
- If you are submitting new files that you intend to be the technical
sub-maintainer for (for example, a new platform port), then also update
the `Maintainers`_ file.
- For topics with multiple commits, you should make all documentation
changes (and nothing else) in the last commit of the series. Otherwise,
include the documentation changes within the single commit.
- Please test your changes. As a minimum, ensure UEFI boots to the shell on
the Foundation FVP. See `Running the software on FVP`_ for more information.
Submitting Changes
------------------
- Ensure that each commit in the series has at least one ``Signed-off-by:``
line, using your real name and email address. The names in the
``Signed-off-by:`` and ``Author:`` lines must match. If anyone else contributes
to the commit, they must also add their own ``Signed-off-by:`` line.
By adding this line the contributor certifies the contribution is made under
the terms of the `Developer Certificate of Origin (DCO)`_.
- Push your local changes to your fork of the repository.
- Submit a `pull request`_ to the `arm-trusted-firmware`_ ``integration`` branch.
- The changes in the `pull request`_ will then undergo further review and
testing by the `Maintainers`_. Any review comments will be made as
comments on the `pull request`_. This may require you to do some rework.
- When the changes are accepted, the `Maintainers`_ will integrate them.
- Typically, the `Maintainers`_ will merge the `pull request`_ into the
``integration`` branch within the GitHub UI, creating a merge commit.
- Please avoid creating merge commits in the `pull request`_ itself.
- If the `pull request`_ is not based on a recent commit, the `Maintainers`_
may rebase it onto the ``master`` branch first, or ask you to do this.
- If the `pull request`_ cannot be automatically merged, the `Maintainers`_
will ask you to rebase it onto the ``master`` branch.
- After final integration testing, the `Maintainers`_ will push your merge
commit to the ``master`` branch. If a problem is found during integration,
the merge commit will be removed from the ``integration`` branch and the
`Maintainers`_ will ask you to create a new pull request to resolve the
problem.
- Please do not delete your topic branch until it is safely merged into
the ``master`` branch.
--------------
*Copyright (c) 2013-2017, ARM Limited and Contributors. All rights reserved.*
.. _GitHub account: https://github.com/signup/free
.. _issue: https://github.com/ARM-software/tf-issues/issues
.. _issue tracking repository: https://github.com/ARM-software/tf-issues
.. _Fork: https://help.github.com/articles/fork-a-repo
.. _arm-trusted-firmware: https://github.com/ARM-software/arm-trusted-firmware
.. _Git guidelines: http://git-scm.com/book/ch5-2.html
.. _Linux coding style: https://www.kernel.org/doc/Documentation/CodingStyle
.. _User Guide: ./docs/user-guide.rst
.. _automatically closed: https://help.github.com/articles/closing-issues-via-commit-messages
.. _Porting Guide: ./docs/porting-guide.rst
.. _Firmware Design: ./docs/firmware-design.rst
.. _license.rst: ./license.rst
.. _Acknowledgements: ./acknowledgements.rst
.. _Maintainers: ./maintainers.rst
.. _Running the software on FVP: ./docs/user-guide.rst#user-content-running-the-software-on-fvp
.. _Developer Certificate of Origin (DCO): ./dco.txt
.. _pull request: https://help.github.com/articles/using-pull-requests
docs/arm-sip-service.md → docs/arm-sip-service.rst
View file @ 7cefb56d
ARM SiP Service
===============
This document enumerates and describes the ARM SiP (Silicon Provider) services.
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")
instruction executed from Exception Levels below EL3. SMC calls for SiP
services:
* Follow [SMC Calling Convention][SMCCC];
* Use SMC function IDs that fall in the SiP range, which are `0xc2000000` -
`0xc200ffff` for 64-bit calls, and `0x82000000` - `0x8200ffff` for 32-bit
- Follow `SMC Calling Convention`_;
- Use SMC function IDs that fall in the SiP range, which are ``0xc2000000`` -
``0xc200ffff`` for 64-bit calls, and ``0x82000000`` - ``0x8200ffff`` for 32-bit
calls.
The ARM SiP implementation offers the following services:
* Performance Measurement Framework (PMF)
* Execution State Switching service
- Performance Measurement Framework (PMF)
- 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.
Performance Measurement Framework (PMF)
---------------------------------------
The [Performance Measurement Framework](./firmware-design.md#13--performance-measurement-framework)
The `Performance Measurement Framework`_
allows callers to retrieve timestamps captured at various paths in ARM Trusted
Firmware execution. It's described in detail in [Firmware Design document][Firmware Design].
Firmware execution. It's described in detail in `Firmware Design document`_.
Execution State Switching service
---------------------------------
......@@ -37,9 +36,12 @@ 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
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
`ARCH` is set to `aarch64`).
``ARCH`` is set to ``aarch64``).
``ARM_SIP_SVC_EXE_STATE_SWITCH``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### `ARM_SIP_SVC_EXE_STATE_SWITCH`
::
Arguments:
uint32_t Function ID
......@@ -51,19 +53,19 @@ available when ARM Trusted Firmware is built for AArch64 (i.e. when build option
Return:
uint32_t
The function ID parameter must be `0x82000020`. It uniquely identifies the
The function ID parameter must be ``0x82000020``. It uniquely identifies the
Execution State Switching service being requested.
The parameters _PC hi_ and _PC lo_ defines upper and lower words, respectively,
The parameters *PC hi* and *PC lo* defines upper and lower words, respectively,
of the entry point (physical address) at which execution should start, after
Execution State has been switched. When calling from AArch64, _PC hi_ must be 0.
Execution State has been switched. When calling from AArch64, *PC hi* must be 0.
When execution starts at the supplied entry point after Execution State has been
switched, the parameters _Cookie hi_ and _Cookie lo_ are passed in CPU registers
0 and 1, respectively. When calling from AArch64, _Cookie hi_ must be 0.
switched, the parameters *Cookie hi* and *Cookie lo* are passed in CPU registers
0 and 1, respectively. When calling from AArch64, *Cookie hi* must be 0.
This call can only be made on the primary CPU, before any secondaries were
brought up with `CPU_ON` PSCI call. Otherwise, the call will always fail.
brought up with ``CPU_ON`` PSCI call. Otherwise, the call will always fail.
The effect of switching execution state is as if the Exception Level were
entered for the first time, following power on. This means CPU registers that
......@@ -71,21 +73,24 @@ have a defined reset value by the Architecture will assume that value. Other
registers should not be expected to hold their values before the call was made.
CPU endianness, however, is preserved from the previous execution state. Note
that this switches the execution state of the calling CPU only. This is not a
substitute for PSCI `SYSTEM_RESET`.
substitute for PSCI ``SYSTEM_RESET``.
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.
- `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 ARM Trusted
Firmware is built for AArch32.
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
and 1 populated with the supplied _Cookie hi_ and _Cookie lo_ values,
and 1 populated with the supplied *Cookie hi* and *Cookie lo* values,
respectively.
- - - - - - - - - - - - - - - - - - - - - - - - - -
--------------
*Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.*
[Firmware Design]: ./firmware-design.md
[SMCCC]: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html "SMC Calling Convention PDD (ARM DEN 0028A)"
.. _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
.. _Firmware Design document: ./firmware-design.rst
docs/auth-framework.md → docs/auth-framework.rst
View file @ 7cefb56d
Abstracting a Chain of Trust
============================
Contents :
1. [Introduction](#1--introduction)
2. [Framework design](#2--framework-design)
3. [Specifying a Chain of Trust](#3--specifying-a-chain-of-trust)
4. [Implementation example](#4--implementation-example)
.. section-numbering::
:suffix: .
1. Introduction
----------------
.. contents::
The aim of this document is to describe the authentication framework implemented
in the Trusted Firmware. This framework fulfills the following requirements:
1. 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
particular image/certificate.
2. The framework should distinguish between:
#. The framework should distinguish between:
- The mechanism used to encode and transport information, e.g. DER encoded
X.509v3 certificates to ferry Subject Public Keys, hashes and non-volatile
......@@ -31,7 +26,8 @@ in the Trusted Firmware. This framework fulfills the following requirements:
The framework has been designed following a modular approach illustrated in the
next diagram:
```
::
+---------------+---------------+------------+
| Trusted | Trusted | Trusted |
| Firmware | Firmware | Firmware |
......@@ -67,26 +63,26 @@ next diagram:
+-----------------+
DIAGRAM 1.
```
This document describes the inner details of the authentication framework and
the abstraction mechanisms available to specify a Chain of Trust.
2. Framework design
--------------------
Framework design
----------------
This section describes some aspects of the framework design and the rationale
behind them. These aspects are key to verify a Chain of Trust.
### 2.1 Chain of Trust
Chain of Trust
~~~~~~~~~~~~~~
A CoT is basically a sequence of authentication images which usually starts with
a root of trust and culminates in a single data image. The following diagram
illustrates how this maps to a CoT for the BL31 image described in the
TBBR-Client specification.
```
::
+------------------+ +-------------------+
| ROTPK/ROTPK Hash |------>| Trusted Key |
+------------------+ | Certificate |
......@@ -124,39 +120,40 @@ TBBR-Client specification.
+-------------------+
DIAGRAM 2.
```
The root of trust is usually a public key (ROTPK) that has been burnt in the
platform and cannot be modified.
### 2.2 Image types
Image types
~~~~~~~~~~~
Images in a CoT are categorised as authentication and data images. An
authentication image contains information to authenticate a data image or
another authentication image. A data image is usually a boot loader binary, but
it could be any other data that requires authentication.
### 2.3 Component responsibilities
Component responsibilities
~~~~~~~~~~~~~~~~~~~~~~~~~~
For every image in a Chain of Trust, the following high level operations are
performed to verify it:
1. Allocate memory for the image either statically or at runtime.
#. Allocate memory for the image either statically or at runtime.
2. Identify the image and load it in the allocated memory.
#. Identify the image and load it in the allocated memory.
3. Check the integrity of the image as per its type.
#. Check the integrity of the image as per its type.
4. Authenticate the image as per the cryptographic algorithms used.
#. Authenticate the image as per the cryptographic algorithms used.
5. If the image is an authentication image, extract the information that will
#. If the image is an authentication image, extract the information that will
be used to authenticate the next image in the CoT.
In Diagram 1, each component is responsible for one or more of these operations.
The responsibilities are briefly described below.
#### 2.2.1 TF Generic code and IO framework (GEN/IO)
TF Generic code and IO framework (GEN/IO)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
These components are responsible for initiating the authentication process for a
particular image in BL1 or BL2. For each BL image that requires authentication,
......@@ -165,57 +162,57 @@ 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
Authentication module to authenticate it, following the CoT from ROT to Image.
#### 2.2.2 TF Platform Port (PP)
TF Platform Port (PP)
^^^^^^^^^^^^^^^^^^^^^
The platform is responsible for:
1. Specifying the CoT for each image that needs to be authenticated. Details of
#. Specifying the CoT for each image that needs to be authenticated. Details of
how a CoT can be specified by the platform are explained later. The platform
also specifies the authentication methods and the parsing method used for
each image.
2. Statically allocating memory for each parameter in each image which is
#. Statically allocating memory for each parameter in each image which is
used for verifying the CoT, e.g. memory for public keys, hashes etc.
3. Providing the ROTPK or a hash of it.
#. Providing the ROTPK or a hash of it.
4. Providing additional information to the IPM to enable it to identify and
#. Providing additional information to the IPM to enable it to identify and
extract authentication parameters contained in an image, e.g. if the
parameters are stored as X509v3 extensions, the corresponding OID must be
provided.
5. Fulfill any other memory requirements of the IPM and the CM (not currently
#. Fulfill any other memory requirements of the IPM and the CM (not currently
described in this document).
6. Export functions to verify an image which uses an authentication method that
#. Export functions to verify an image which uses an authentication method that
cannot be interpreted by the CM, e.g. if an image has to be verified using a
NV counter, then the value of the counter to compare with can only be
provided by the platform.
7. Export a custom IPM if a proprietary image format is being used (described
#. Export a custom IPM if a proprietary image format is being used (described
later).
#### 2.2.3 Authentication Module (AM)
Authentication Module (AM)
^^^^^^^^^^^^^^^^^^^^^^^^^^
It is responsible for:
1. Providing the necessary abstraction mechanisms to describe a CoT. Amongst
#. Providing the necessary abstraction mechanisms to describe a CoT. Amongst
other things, the authentication and image parsing methods must be specified
by the PP in the CoT.
2. Verifying the CoT passed by GEN by utilising functionality exported by the
#. Verifying the CoT passed by GEN by utilising functionality exported by the
PP, IPM and CM.
3. Tracking which images have been verified. In case an image is a part of
#. Tracking which images have been verified. In case an image is a part of
multiple CoTs then it should be verified only once e.g. the Trusted World
Key Certificate in the TBBR-Client spec. contains information to verify
SCP_BL2, BL31, BL32 each of which have a separate CoT. (This
SCP\_BL2, BL31, BL32 each of which have a separate CoT. (This
responsibility has not been described in this document but should be
trivial to implement).
4. Reusing memory meant for a data image to verify authentication images e.g.
#. Reusing memory meant for a data image to verify authentication images e.g.
in the CoT described in Diagram 2, each certificate can be loaded and
verified in the memory reserved by the platform for the BL31 image. By the
time BL31 (the data image) is loaded, all information to authenticate it
......@@ -224,43 +221,45 @@ It is responsible for:
never exceed the size of a data image. It should be possible to verify this
at build time using asserts.
#### 2.2.4 Cryptographic Module (CM)
Cryptographic Module (CM)
^^^^^^^^^^^^^^^^^^^^^^^^^
The CM is responsible for providing an API to:
1. Verify a digital signature.
2. Verify a hash.
#. Verify a digital signature.
#. Verify a hash.
The CM does not include any cryptography related code, but it relies on an
external library to perform the cryptographic operations. A Crypto-Library (CL)
linking the CM and the external library must be implemented. The following
functions must be provided by the CL:
```
void (*init)(void);
int (*verify_signature)(void *data_ptr, unsigned int data_len,
.. code:: c
void (*init)(void);
int (*verify_signature)(void *data_ptr, unsigned int data_len,
void *sig_ptr, unsigned int sig_len,
void *sig_alg, unsigned int sig_alg_len,
void *pk_ptr, unsigned int pk_len);
int (*verify_hash)(void *data_ptr, unsigned int data_len,
int (*verify_hash)(void *data_ptr, unsigned int data_len,
void *digest_info_ptr, unsigned int digest_info_len);
```
These functions are registered in the CM using the macro:
```
REGISTER_CRYPTO_LIB(_name, _init, _verify_signature, _verify_hash);
```
`_name` must be a string containing the name of the CL. This name is used for
.. code:: c
REGISTER_CRYPTO_LIB(_name, _init, _verify_signature, _verify_hash);
``_name`` must be a string containing the name of the CL. This name is used for
debugging purposes.
#### 2.2.5 Image Parser Module (IPM)
Image Parser Module (IPM)
^^^^^^^^^^^^^^^^^^^^^^^^^
The IPM is responsible for:
1. Checking the integrity of each image loaded by the IO framework.
2. Extracting parameters used for authenticating an image based upon a
#. Checking the integrity of each image loaded by the IO framework.
#. Extracting parameters used for authenticating an image based upon a
description provided by the platform in the CoT descriptor.
Images may have different formats (for example, authentication images could be
......@@ -273,13 +272,13 @@ check the image integrity and extract the authentication parameters.
See Section "Describing the image parsing methods" for more details about the
mechanism the IPM provides to define and register IPLs.
### 2.3 Authentication methods
Authentication methods
~~~~~~~~~~~~~~~~~~~~~~
The AM supports the following authentication methods:
1. Hash
2. Digital signature
#. Hash
#. Digital signature
The platform may specify these methods in the CoT in case it decides to define
a custom CoT instead of reusing a predefined one.
......@@ -288,71 +287,71 @@ If a data image uses multiple methods, then all the methods must be a part of
the same CoT. The number and type of parameters are method specific. These
parameters should be obtained from the parent image using the IPM.
1. Hash
#. Hash
Parameters:
1. A pointer to data to hash
2. Length of the data
4. A pointer to the hash
5. Length of the hash
#. A pointer to data to hash
#. Length of the data
#. A pointer to the hash
#. Length of the hash
The hash will be represented by the DER encoding of the following ASN.1
type:
```
::
DigestInfo ::= SEQUENCE {
digestAlgorithm DigestAlgorithmIdentifier,
digest Digest
}
```
This ASN.1 structure makes it possible to remove any assumption about the
type of hash algorithm used as this information accompanies the hash. This
should allow the Cryptography Library (CL) to support multiple hash
algorithm implementations.
2. Digital Signature
#. Digital Signature
Parameters:
1. A pointer to data to sign
2. Length of the data
3. Public Key Algorithm
4. Public Key value
5. Digital Signature Algorithm
6. Digital Signature value
#. A pointer to data to sign
#. Length of the data
#. Public Key Algorithm
#. Public Key value
#. Digital Signature Algorithm
#. Digital Signature value
The Public Key parameters will be represented by the DER encoding of the
following ASN.1 type:
```
::
SubjectPublicKeyInfo ::= SEQUENCE {
algorithm AlgorithmIdentifier{PUBLIC-KEY,{PublicKeyAlgorithms}},
subjectPublicKey BIT STRING }
```
The Digital Signature Algorithm will be represented by the DER encoding of
the following ASN.1 types.
```
::
AlgorithmIdentifier {ALGORITHM:IOSet } ::= SEQUENCE {
algorithm ALGORITHM.&id({IOSet}),
parameters ALGORITHM.&Type({IOSet}{@algorithm}) OPTIONAL
}
```
The digital signature will be represented by:
```
::
signature ::= BIT STRING
```
The authentication framework will use the image descriptor to extract all the
information related to authentication.
3. Specifying a Chain of Trust
-------------------------------
Specifying a Chain of Trust
---------------------------
A CoT can be described as a set of image descriptors linked together in a
particular order. The order dictates the sequence in which they must be
......@@ -363,8 +362,8 @@ The PP is responsible for defining a single or multiple CoTs for a data image.
Unless otherwise specified, the data structures described in the following
sections are populated by the PP statically.
### 3.1 Describing the image parsing methods
Describing the image parsing methods
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The parsing method refers to the format of a particular image. For example, an
authentication image that represents a certificate could be in the X.509v3
......@@ -374,17 +373,17 @@ of the three methods described below. An IPL is responsible for interpreting a
single parsing method. There has to be one IPL for every method used by the
platform.
1. 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
TF. This method should only be used by data images.
2. 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
libraries will be available which can be used to parse an image represented
by this method. Such libraries can be used to write the corresponding IPL
e.g. the X.509 parsing library code in mbed TLS.
3. Platform defined method: This method caters for platform specific
#. Platform defined method: This method caters for platform specific
proprietary standards to represent authentication or data images. For
example, The signature of a data image could be appended to the data image
raw binary. A header could be prepended to the combined blob to specify the
......@@ -393,158 +392,158 @@ platform.
The following enum can be used to define these three methods.
```
typedef enum img_type_enum {
.. code:: c
typedef enum img_type_enum {
IMG_RAW, /* Binary image */
IMG_PLAT, /* Platform specific format */
IMG_CERT, /* X509v3 certificate */
IMG_MAX_TYPES,
} img_type_t;
```
} img_type_t;
An IPL must provide functions with the following prototypes:
```
void init(void);
int check_integrity(void *img, unsigned int img_len);
int get_auth_param(const auth_param_type_desc_t *type_desc,
.. code:: c
void init(void);
int check_integrity(void *img, unsigned int img_len);
int get_auth_param(const auth_param_type_desc_t *type_desc,
void *img, unsigned int img_len,
void **param, unsigned int *param_len);
```
An IPL for each type must be registered using the following macro:
```
REGISTER_IMG_PARSER_LIB(_type, _name, _init, _check_int, _get_param)
```
::
REGISTER_IMG_PARSER_LIB(_type, _name, _init, _check_int, _get_param)
* `_type`: one of the types described above.
* `_name`: a string containing the IPL name for debugging purposes.
* `_init`: initialization function pointer.
* `_check_int`: check image integrity function pointer.
* `_get_param`: extract authentication parameter funcion pointer.
- ``_type``: one of the types described above.
- ``_name``: a string containing the IPL name for debugging purposes.
- ``_init``: initialization function pointer.
- ``_check_int``: check image integrity function pointer.
- ``_get_param``: extract authentication parameter funcion pointer.
The `init()` function will be used to initialize the IPL.
The ``init()`` function will be used to initialize the IPL.
The `check_integrity()` function is passed a pointer to the memory where the
The ``check_integrity()`` function is passed a pointer to the memory where the
image has been loaded by the IO framework and the image length. It should ensure
that the image is in the format corresponding to the parsing method and has not
been tampered with. For example, RFC-2459 describes a validation sequence for an
X.509 certificate.
The `get_auth_param()` function is passed a parameter descriptor containing
information about the parameter (`type_desc` and `cookie`) to identify and
The ``get_auth_param()`` function is passed a parameter descriptor containing
information about the parameter (``type_desc`` and ``cookie``) to identify and
extract the data corresponding to that parameter from an image. This data will
be used to verify either the current or the next image in the CoT sequence.
Each image in the CoT will specify the parsing method it uses. This information
will be used by the IPM to find the right parser descriptor for the image.
### 3.2 Describing the authentication method(s)
Describing the authentication method(s)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As part of the CoT, each image has to specify one or more authentication methods
which will be used to verify it. As described in the Section "Authentication
methods", there are three methods supported by the AM.
```
typedef enum {
.. code:: c
typedef enum {
AUTH_METHOD_NONE,
AUTH_METHOD_HASH,
AUTH_METHOD_SIG,
AUTH_METHOD_NUM
} auth_method_type_t;
```
} auth_method_type_t;
The AM defines the type of each parameter used by an authentication method. It
uses this information to:
1. Specify to the `get_auth_param()` function exported by the IPM, which
#. Specify to the ``get_auth_param()`` function exported by the IPM, which
parameter should be extracted from an image.
2. Correctly marshall the parameters while calling the verification function
#. Correctly marshall the parameters while calling the verification function
exported by the CM and PP.
3. Extract authentication parameters from a parent image in order to verify a
#. Extract authentication parameters from a parent image in order to verify a
child image e.g. to verify the certificate image, the public key has to be
obtained from the parent image.
```
typedef enum {
.. code:: c
typedef enum {
AUTH_PARAM_NONE,
AUTH_PARAM_RAW_DATA, /* Raw image data */
AUTH_PARAM_SIG, /* The image signature */
AUTH_PARAM_SIG_ALG, /* The image signature algorithm */
AUTH_PARAM_HASH, /* A hash (including the algorithm) */
AUTH_PARAM_PUB_KEY, /* A public key */
} auth_param_type_t;
```
} auth_param_type_t;
The AM defines the following structure to identify an authentication parameter
required to verify an image.
```
typedef struct auth_param_type_desc_s {
.. code:: c
typedef struct auth_param_type_desc_s {
auth_param_type_t type;
void *cookie;
} auth_param_type_desc_t;
```
} auth_param_type_desc_t;
`cookie` is used by the platform to specify additional information to the IPM
``cookie`` is used by the platform to specify additional information to the IPM
which enables it to uniquely identify the parameter that should be extracted
from an image. For example, the hash of a BL3x image in its corresponding
content certificate is stored in an X509v3 custom extension field. An extension
field can only be identified using an OID. In this case, the `cookie` could
field can only be identified using an OID. In this case, the ``cookie`` could
contain the pointer to the OID defined by the platform for the hash extension
field while the `type` field could be set to `AUTH_PARAM_HASH`. A value of 0 for
the `cookie` field means that it is not used.
field while the ``type`` field could be set to ``AUTH_PARAM_HASH``. A value of 0 for
the ``cookie`` field means that it is not used.
For each method, the AM defines a structure with the parameters required to
verify the image.
```
/*
.. code:: c
/*
* Parameters for authentication by hash matching
*/
typedef struct auth_method_param_hash_s {
typedef struct auth_method_param_hash_s {
auth_param_type_desc_t *data; /* Data to hash */
auth_param_type_desc_t *hash; /* Hash to match with */
} auth_method_param_hash_t;
} auth_method_param_hash_t;
/*
/*
* Parameters for authentication by signature
*/
typedef struct auth_method_param_sig_s {
typedef struct auth_method_param_sig_s {
auth_param_type_desc_t *pk; /* Public key */
auth_param_type_desc_t *sig; /* Signature to check */
auth_param_type_desc_t *alg; /* Signature algorithm */
auth_param_type_desc_t *tbs; /* Data signed */
} auth_method_param_sig_t;
```
} auth_method_param_sig_t;
The AM defines the following structure to describe an authentication method for
verifying an image
```
/*
.. code:: c
/*
* Authentication method descriptor
*/
typedef struct auth_method_desc_s {
typedef struct auth_method_desc_s {
auth_method_type_t type;
union {
auth_method_param_hash_t hash;
auth_method_param_sig_t sig;
} param;
} auth_method_desc_t;
```
} auth_method_desc_t;
Using the method type specified in the `type` field, the AM finds out what field
needs to access within the `param` union.
Using the method type specified in the ``type`` field, the AM finds out what field
needs to access within the ``param`` union.
### 3.3 Storing Authentication parameters
Storing Authentication parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A parameter described by `auth_param_type_desc_t` to verify an image could be
A parameter described by ``auth_param_type_desc_t`` to verify an image could be
obtained from either the image itself or its parent image. The memory allocated
for loading the parent image will be reused for loading the child image. Hence
parameters which are obtained from the parent for verifying a child image need
......@@ -554,77 +553,80 @@ memory must be statically allocated by the platform port.
The AM defines the following structure to store the data corresponding to an
authentication parameter.
```
typedef struct auth_param_data_desc_s {
.. code:: c
typedef struct auth_param_data_desc_s {
void *auth_param_ptr;
unsigned int auth_param_len;
} auth_param_data_desc_t;
```
} auth_param_data_desc_t;
The `auth_param_ptr` field is initialized by the platform. The `auth_param_len`
The ``auth_param_ptr`` field is initialized by the platform. The ``auth_param_len``
field is used to specify the length of the data in the memory.
For parameters that can be obtained from the child image itself, the IPM is
responsible for populating the `auth_param_ptr` and `auth_param_len` fields
while executing the `img_get_auth_param()` function.
responsible for populating the ``auth_param_ptr`` and ``auth_param_len`` fields
while executing the ``img_get_auth_param()`` function.
The AM defines the following structure to enable an image to describe the
parameters that should be extracted from it and used to verify the next image
(child) in a CoT.
```
typedef struct auth_param_desc_s {
.. code:: c
typedef struct auth_param_desc_s {
auth_param_type_desc_t type_desc;
auth_param_data_desc_t data;
} auth_param_desc_t;
```
} auth_param_desc_t;
### 3.4 Describing an image in a CoT
Describing an image in a CoT
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
An image in a CoT is a consolidation of the following aspects of a CoT described
above.
1. A unique identifier specified by the platform which allows the IO framework
#. A unique identifier specified by the platform which allows the IO framework
to locate the image in a FIP and load it in the memory reserved for the data
image in the CoT.
2. A parsing method which is used by the AM to find the appropriate IPM.
#. A parsing method which is used by the AM to find the appropriate IPM.
3. Authentication methods and their parameters as described in the previous
#. Authentication methods and their parameters as described in the previous
section. These are used to verify the current image.
4. Parameters which are used to verify the next image in the current CoT. These
#. Parameters which are used to verify the next image in the current CoT. These
parameters are specified only by authentication images and can be extracted
from the current image once it has been verified.
The following data structure describes an image in a CoT.
```
typedef struct auth_img_desc_s {
.. code:: c
typedef struct auth_img_desc_s {
unsigned int img_id;
const struct auth_img_desc_s *parent;
img_type_t img_type;
auth_method_desc_t img_auth_methods[AUTH_METHOD_NUM];
auth_param_desc_t authenticated_data[COT_MAX_VERIFIED_PARAMS];
} auth_img_desc_t;
```
A CoT is defined as an array of `auth_image_desc_t` structures linked together
by the `parent` field. Those nodes with no parent must be authenticated using
the ROTPK stored in the platform.
} auth_img_desc_t;
A CoT is defined as an array of ``auth_image_desc_t`` structures linked together
by the ``parent`` field. Those nodes with no parent must be authenticated using
the ROTPK stored in the platform.
4. Implementation example
--------------------------
Implementation example
----------------------
This section is a detailed guide explaining a trusted boot implementation using
the authentication framework. This example corresponds to the Applicative
Functional Mode (AFM) as specified in the TBBR-Client document. It is
recommended to read this guide along with the source code.
### 4.1 The TBBR CoT
The TBBR CoT
~~~~~~~~~~~~
The CoT can be found in `drivers/auth/tbbr/tbbr_cot.c`. This CoT consists of an
The CoT can be found in ``drivers/auth/tbbr/tbbr_cot.c``. This CoT consists of an
array of image descriptors and it is registered in the framework using the macro
`REGISTER_COT(cot_desc)`, where 'cot_desc' must be the name of the array
``REGISTER_COT(cot_desc)``, where 'cot\_desc' must be the name of the array
(passing a pointer or any other type of indirection will cause the registration
process to fail).
......@@ -632,21 +634,21 @@ 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
and thus all CoTs must present:
* `BL2`
* `SCP_BL2` (platform specific)
* `BL31`
* `BL32` (optional)
* `BL33`
- ``BL2``
- ``SCP_BL2`` (platform specific)
- ``BL31``
- ``BL32`` (optional)
- ``BL33``
The TBBR specifies the additional certificates that must accompany these images
for a proper authentication. Details about the TBBR CoT may be found in the
[Trusted Board Boot] document.
`Trusted Board Boot`_ document.
Following the [Platform Porting Guide], a platform must provide unique
Following the `Platform Porting Guide`_, a platform must provide unique
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,
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
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
platforms may also include this file or provide their own identifiers.
**Important**: the authentication module uses these identifiers to index the
......@@ -654,22 +656,24 @@ CoT array, so the descriptors location in the array must match the identifiers.
Each image descriptor must specify:
* `img_id`: the corresponding image unique identifier defined by the platform.
* `img_type`: the image parser module uses the image type to call the proper
- ``img_id``: the corresponding image unique identifier defined by the platform.
- ``img_type``: the image parser module uses the image type to call the proper
parsing library to check the image integrity and extract the required
authentication parameters. Three types of images are currently supported:
* `IMG_RAW`: image is a raw binary. No parsing functions are available,
- ``IMG_RAW``: image is a raw binary. No parsing functions are available,
other than reading the whole image.
* `IMG_PLAT`: image format is platform specific. The platform may use this
- ``IMG_PLAT``: image format is platform specific. The platform may use this
type for custom images not directly supported by the authentication
framework.
* `IMG_CERT`: image is an x509v3 certificate.
* `parent`: pointer to the parent image descriptor. The parent will contain
- ``IMG_CERT``: image is an x509v3 certificate.
- ``parent``: pointer to the parent image descriptor. The parent will contain
the information required to authenticate the current image. If the parent
is NULL, the authentication parameters will be obtained from the platform
(i.e. the BL2 and Trusted Key certificates are signed with the ROT private
key, whose public part is stored in the platform).
* `img_auth_methods`: this array defines the authentication methods that must
- ``img_auth_methods``: this array defines the authentication methods that must
be checked to consider an image authenticated. Each method consists of a
type and a list of parameter descriptors. A parameter descriptor consists of
a type and a cookie which will point to specific information required to
......@@ -677,26 +681,31 @@ Each image descriptor must specify:
x509v3 extension, the cookie will point to the extension OID). Depending on
the method type, a different number of parameters must be specified.
Supported methods are:
* `AUTH_METHOD_HASH`: the hash of the image must match the hash extracted
- ``AUTH_METHOD_HASH``: the hash of the image must match the hash extracted
from the parent image. The following parameter descriptors must be
specified:
* `data`: data to be hashed (obtained from current image)
* `hash`: reference hash (obtained from parent image)
* `AUTH_METHOD_SIG`: the image (usually a certificate) must be signed with
- ``data``: data to be hashed (obtained from current image)
- ``hash``: reference hash (obtained from parent image)
- ``AUTH_METHOD_SIG``: the image (usually a certificate) must be signed with
the private key whose public part is extracted from the parent image (or
the platform if the parent is NULL). The following parameter descriptors
must be specified:
* `pk`: the public key (obtained from parent image)
* `sig`: the digital signature (obtained from current image)
* `alg`: the signature algorithm used (obtained from current image)
* `data`: the data to be signed (obtained from current image)
* `authenticated_data`: this array indicates what authentication parameters
- ``pk``: the public key (obtained from parent image)
- ``sig``: the digital signature (obtained from current image)
- ``alg``: the signature algorithm used (obtained from current image)
- ``data``: the data to be signed (obtained from current image)
- ``authenticated_data``: this array indicates what authentication parameters
must be extracted from an image once it has been authenticated. Each
parameter consists of a parameter descriptor and the buffer address/size
to store the parameter. The CoT is responsible for allocating the required
memory to store the parameters.
In the `tbbr_cot.c` file, a set of buffers are allocated to store the parameters
In the ``tbbr_cot.c`` file, a set of buffers are allocated to store the parameters
extracted from the certificates. In the case of the TBBR CoT, these parameters
are hashes and public keys. In DER format, an RSA-2048 public key requires 294
bytes, and a hash requires 51 bytes. Depending on the CoT and the authentication
......@@ -705,12 +714,14 @@ process, some of the buffers may be reused at different stages during the boot.
Next in that file, the parameter descriptors are defined. These descriptors will
be used to extract the parameter data from the corresponding image.
#### 4.1.1 Example: the BL31 Chain of Trust
Example: the BL31 Chain of Trust
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Four image descriptors form the BL31 Chain of Trust:
```
[TRUSTED_KEY_CERT_ID] = {
.. code:: asm
[TRUSTED_KEY_CERT_ID] = {
.img_id = TRUSTED_KEY_CERT_ID,
.img_type = IMG_CERT,
.parent = NULL,
......@@ -741,8 +752,8 @@ Four image descriptors form the BL31 Chain of Trust:
}
}
}
},
[SOC_FW_KEY_CERT_ID] = {
},
[SOC_FW_KEY_CERT_ID] = {
.img_id = SOC_FW_KEY_CERT_ID,
.img_type = IMG_CERT,
.parent = &cot_desc[TRUSTED_KEY_CERT_ID],
......@@ -766,8 +777,8 @@ Four image descriptors form the BL31 Chain of Trust:
}
}
}
},
[SOC_FW_CONTENT_CERT_ID] = {
},
[SOC_FW_CONTENT_CERT_ID] = {
.img_id = SOC_FW_CONTENT_CERT_ID,
.img_type = IMG_CERT,
.parent = &cot_desc[SOC_FW_KEY_CERT_ID],
......@@ -791,8 +802,8 @@ Four image descriptors form the BL31 Chain of Trust:
}
}
}
},
[BL31_IMAGE_ID] = {
},
[BL31_IMAGE_ID] = {
.img_id = BL31_IMAGE_ID,
.img_type = IMG_RAW,
.parent = &cot_desc[SOC_FW_CONTENT_CERT_ID],
......@@ -805,63 +816,64 @@ Four image descriptors form the BL31 Chain of Trust:
}
}
}
}
```
}
The **Trusted Key certificate** is signed with the ROT private key and contains
the Trusted World public key and the Non-Trusted World public key as x509v3
extensions. This must be specified in the image descriptor using the
`img_auth_methods` and `authenticated_data` arrays, respectively.
``img_auth_methods`` and ``authenticated_data`` arrays, respectively.
The Trusted Key certificate is authenticated by checking its digital signature
using the ROTPK. Four parameters are required to check a signature: the public
key, the algorithm, the signature and the data that has been signed. Therefore,
four parameter descriptors must be specified with the authentication method:
* `subject_pk`: parameter descriptor of type `AUTH_PARAM_PUB_KEY`. This type
- ``subject_pk``: parameter descriptor of type ``AUTH_PARAM_PUB_KEY``. This type
is used to extract a public key from the parent image. If the cookie is an
OID, the key is extracted from the corresponding x509v3 extension. If the
cookie is NULL, the subject public key is retrieved. In this case, because
the parent image is NULL, the public key is obtained from the platform
(this key will be the ROTPK).
* `sig`: parameter descriptor of type `AUTH_PARAM_SIG`. It is used to extract
- ``sig``: parameter descriptor of type ``AUTH_PARAM_SIG``. It is used to extract
the signature from the certificate.
* `sig_alg`: parameter descriptor of type `AUTH_PARAM_SIG`. It is used to
- ``sig_alg``: parameter descriptor of type ``AUTH_PARAM_SIG``. It is used to
extract the signature algorithm from the certificate.
* `raw_data`: parameter descriptor of type `AUTH_PARAM_RAW_DATA`. It is used
- ``raw_data``: parameter descriptor of type ``AUTH_PARAM_RAW_DATA``. It is used
to extract the data to be signed from the certificate.
Once the signature has been checked and the certificate authenticated, the
Trusted World public key needs to be extracted from the certificate. A new entry
is created in the `authenticated_data` array for that purpose. In that entry,
is created in the ``authenticated_data`` array for that purpose. In that entry,
the corresponding parameter descriptor must be specified along with the buffer
address to store the parameter value. In this case, the `tz_world_pk` descriptor
address to store the parameter value. In this case, the ``tz_world_pk`` descriptor
is used to extract the public key from an x509v3 extension with OID
`TRUSTED_WORLD_PK_OID`. The BL31 key certificate will use this descriptor as
``TRUSTED_WORLD_PK_OID``. The BL31 key certificate will use this descriptor as
parameter in the signature authentication method. The key is stored in the
`plat_tz_world_pk_buf` buffer.
``plat_tz_world_pk_buf`` buffer.
The **BL31 Key certificate** is authenticated by checking its digital signature
using the Trusted World public key obtained previously from the Trusted Key
certificate. In the image descriptor, we specify a single authentication method
by signature whose public key is the `tz_world_pk`. Once this certificate has
by signature whose public key is the ``tz_world_pk``. Once this certificate has
been authenticated, we have to extract the BL31 public key, stored in the
extension specified by `bl31_content_pk`. This key will be copied to the
`plat_content_pk` buffer.
extension specified by ``bl31_content_pk``. This key will be copied to the
``plat_content_pk`` buffer.
The **BL31 certificate** is authenticated by checking its digital signature
using the BL31 public key obtained previously from the BL31 Key certificate.
We specify the authentication method using `bl31_content_pk` as public key.
We specify the authentication method using ``bl31_content_pk`` as public key.
After authentication, we need to extract the BL31 hash, stored in the extension
specified by `bl31_hash`. This hash will be copied to the `plat_bl31_hash_buf`
specified by ``bl31_hash``. This hash will be copied to the ``plat_bl31_hash_buf``
buffer.
The **BL31 image** is authenticated by calculating its hash and matching it
with the hash obtained from the BL31 certificate. The image descriptor contains
a single authentication method by hash. The parameters to the hash method are
the reference hash, `bl31_hash`, and the data to be hashed. In this case, it is
the whole image, so we specify `raw_data`.
the reference hash, ``bl31_hash``, and the data to be hashed. In this case, it is
the whole image, so we specify ``raw_data``.
### 4.2 The image parser library
The image parser library
~~~~~~~~~~~~~~~~~~~~~~~~
The image parser module relies on libraries to check the image integrity and
extract the authentication parameters. The number and type of parser libraries
......@@ -869,57 +881,57 @@ 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.
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:
```
void init(void);
int check_integrity(void *img, unsigned int img_len);
int get_auth_param(const auth_param_type_desc_t *type_desc,
.. code:: c
void init(void);
int check_integrity(void *img, unsigned int img_len);
int get_auth_param(const auth_param_type_desc_t *type_desc,
void *img, unsigned int img_len,
void **param, unsigned int *param_len);
```
The library is registered in the framework using the macro
`REGISTER_IMG_PARSER_LIB()`. Each time the image parser module needs to access
an image of type `IMG_CERT`, it will call the corresponding function exported
``REGISTER_IMG_PARSER_LIB()``. Each time the image parser module needs to access
an image of type ``IMG_CERT``, it will call the corresponding function exported
in this file.
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.
### 4.3 The cryptographic library
The cryptographic library
~~~~~~~~~~~~~~~~~~~~~~~~~
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
based on mbed TLS, which can be found in
`drivers/auth/mbedtls/mbedtls_crypto.c`. This library is registered in the
authentication framework using the macro `REGISTER_CRYPTO_LIB()` and exports
``drivers/auth/mbedtls/mbedtls_crypto.c``. This library is registered in the
authentication framework using the macro ``REGISTER_CRYPTO_LIB()`` and exports
three functions:
```
void init(void);
int verify_signature(void *data_ptr, unsigned int data_len,
.. code:: c
void init(void);
int verify_signature(void *data_ptr, unsigned int data_len,
void *sig_ptr, unsigned int sig_len,
void *sig_alg, unsigned int sig_alg_len,
void *pk_ptr, unsigned int pk_len);
int verify_hash(void *data_ptr, unsigned int data_len,
int verify_hash(void *data_ptr, unsigned int data_len,
void *digest_info_ptr, unsigned int digest_info_len);
```
The key algorithm (rsa, ecdsa) must be specified in the build system using the
`TF_MBEDTLS_KEY_ALG` variable, so the Makefile can include the corresponding
``TF_MBEDTLS_KEY_ALG`` variable, so the Makefile can include the corresponding
sources in the build.
Note: If code size is a concern, the build option `MBEDTLS_SHA256_SMALLER` can
Note: If code size is a concern, the build option ``MBEDTLS_SHA256_SMALLER`` can
be defined in the platform Makefile. It will make mbed TLS use an implementation
of SHA-256 with smaller memory footprint (~1.5 KB less) but slower (~30%).
- - - - - - - - - - - - - - - - - - - - - - - - - -
_Copyright (c) 2015, ARM Limited and Contributors. All rights reserved._
--------------
*Copyright (c) 2015, ARM Limited and Contributors. All rights reserved.*
[Trusted Board Boot]: ./trusted-board-boot.md
[Platform Porting Guide]: ./porting-guide.md
.. _Trusted Board Boot: ./trusted-board-boot.rst
.. _Platform Porting Guide: ./porting-guide.rst
docs/change-log.md deleted 100644 → 0
View file @ aa5b843f
ARM Trusted Firmware - version 1.3
==================================
New features
------------
* Added support for running Trusted Firmware in AArch32 execution state.
The PSCI library has been refactored to allow integration with **EL3 Runtime
Software**. This is software that is executing at the highest secure
privilege which is EL3 in AArch64 or Secure SVC/Monitor mode in AArch32. See
[PSCI Integration Guide].
Included is a minimal AArch32 Secure Payload, **SP-MIN**, that illustrates
the usage and integration of the PSCI library with EL3 Runtime Software
running in AArch32 state.
Booting to the BL1/BL2 images as well as booting straight to the Secure
Payload is supported.
* Improvements to the initialization framework for the PSCI service and ARM
Standard Services in general.
The PSCI service is now initialized as part of ARM Standard Service
initialization. This consolidates the initializations of any ARM Standard
Service that may be added in the future.
A new function `get_arm_std_svc_args()` is introduced to get arguments
corresponding to each standard service and must be implemented by the EL3
Runtime Software.
For PSCI, a new versioned structure `psci_lib_args_t` is introduced to
initialize the PSCI Library. **Note** this is a compatibility break due to
the change in the prototype of `psci_setup()`.
* To support AArch32 builds of BL1 and BL2, implemented a new, alternative
firmware image loading mechanism that adds flexibility.
The current mechanism has a hard-coded set of images and execution order
(BL31, BL32, etc). The new mechanism is data-driven by a list of image
descriptors provided by the platform code.
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
currently off by default for the AArch64 build.
**Note** `TRUSTED_BOARD_BOOT` is currently not supported when
`LOAD_IMAGE_V2` is enabled.
* Updated requirements for making contributions to ARM TF.
Commits now must have a 'Signed-off-by:' field to certify that the
contribution has been made under the terms of the
[Developer Certificate of Origin].
A signed CLA is no longer required.
The [Contribution Guide] has been updated to reflect this change.
* Introduced Performance Measurement Framework (PMF) which provides support
for capturing, storing, dumping and retrieving time-stamps to measure the
execution time of critical paths in the firmware. This relies on defining
fixed sample points at key places in the code.
* To support the QEMU platform port, imported libfdt v1.4.1 from
https://git.kernel.org/cgit/utils/dtc/dtc.git
* Updated PSCI support:
* Added support for PSCI NODE_HW_STATE API for ARM platforms.
* New optional platform hook, `pwr_domain_pwr_down_wfi()`, in
`plat_psci_ops` to enable platforms to perform platform-specific actions
needed to enter powerdown, including the 'wfi' invocation.
* PSCI STAT residency and count functions have been added on ARM platforms
by using PMF.
* Enhancements to the translation table library:
* Limited memory mapping support for region overlaps to only allow regions
to overlap that are identity mapped or have the same virtual to physical
address offset, and overlap completely but must not cover the same area.
This limitation will enable future enhancements without having to
support complex edge cases that may not be necessary.
* The initial translation lookup level is now inferred from the virtual
address space size. Previously, it was hard-coded.
* Added support for mapping Normal, Inner Non-cacheable, Outer
Non-cacheable memory in the translation table library.
This can be useful to map a non-cacheable memory region, such as a DMA
buffer.
* Introduced the MT_EXECUTE/MT_EXECUTE_NEVER memory mapping attributes to
specify the access permissions for instruction execution of a memory
region.
* Enabled support to isolate code and read-only data on separate memory pages,
allowing independent access control to be applied to each.
* Enabled SCR_EL3.SIF (Secure Instruction Fetch) bit in BL1 and BL31 common
architectural setup code, preventing fetching instructions from non-secure
memory when in secure state.
* Enhancements to FIP support:
* Replaced `fip_create` with `fiptool` which provides a more consistent
and intuitive interface as well as additional support to remove an image
from a FIP file.
* Enabled printing the SHA256 digest with info command, allowing quick
verification of an image within a FIP without having to extract the
image and running sha256sum on it.
* Added support for unpacking the contents of an existing FIP file into
the working directory.
* Aligned command line options for specifying images to use same naming
convention as specified by TBBR and already used in cert_create tool.
* Refactored the TZC-400 driver to also support memory controllers that
integrate TZC functionality, for example ARM CoreLink DMC-500. Also added
DMC-500 specific support.
* Implemented generic delay timer based on the system generic counter and
migrated all platforms to use it.
* Enhanced support for ARM platforms:
* Updated image loading support to make SCP images (SCP_BL2 and SCP_BL2U)
optional.
* Enhanced topology description support to allow multi-cluster topology
definitions.
* Added interconnect abstraction layer to help platform ports select the
right interconnect driver, CCI or CCN, for the platform.
* Added support to allow loading BL31 in the TZC-secured DRAM instead of
the default secure SRAM.
* Added support to use a System Security Control (SSC) Registers Unit
enabling ARM TF to be compiled to support multiple ARM platforms and
then select one at runtime.
* Restricted mapping of Trusted ROM in BL1 to what is actually needed by
BL1 rather than entire Trusted ROM region.
* Flash is now mapped as execute-never by default. This increases security
by restricting the executable region to what is strictly needed.
* Applied following erratum workarounds for Cortex-A57: 833471, 826977,
829520, 828024 and 826974.
* Added support for Mediatek MT6795 platform.
* Added support for QEMU virtualization ARMv8-A target.
* Added support for Rockchip RK3368 and RK3399 platforms.
* Added support for Xilinx Zynq UltraScale+ MPSoC platform.
* Added support for ARM Cortex-A73 MPCore Processor.
* Added support for ARM Cortex-A72 processor.
* Added support for ARM Cortex-A35 processor.
* Added support for ARM Cortex-A32 MPCore Processor.
* 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. The User Guide has been updated with an example of how to use this
option with a bootwrapped kernel.
* Added support to build ARM TF on a Windows-based host machine.
* Updated Trusted Board Boot prototype implementation:
* Enabled the ability for a production ROM with TBBR enabled to boot test
software before a real ROTPK is deployed (e.g. manufacturing mode).
Added support to use ROTPK in certificate without verifying against the
platform value when `ROTPK_NOT_DEPLOYED` bit is set.
* Added support for non-volatile counter authentication to the
Authentication Module to protect against roll-back.
* Updated GICv3 support:
* Enabled processor power-down and automatic power-on using GICv3.
* Enabled G1S or G0 interrupts to be configured independently.
* Changed FVP default interrupt driver to be the GICv3-only driver.
**Note** the default build of Trusted Firmware will not be able to boot
Linux kernel with GICv2 FDT blob.
* Enabled wake-up from CPU_SUSPEND to stand-by by temporarily re-routing
interrupts and then restoring after resume.
Issues resolved since last release
----------------------------------
Known issues
------------
* The version of the AEMv8 Base FVP used in this release resets the model
instead of terminating its execution in response to a shutdown request using
the PSCI `SYSTEM_OFF` API. This issue will be fixed in a future version of
the model.
* Building TF with compiler optimisations disabled (`-O0`) fails.
* ARM TF cannot be built with mbed TLS version v2.3.0 due to build warnings
that the ARM TF build system interprets as errors.
* TBBR is not currently supported when running Trusted Firmware in AArch32
state.
ARM Trusted Firmware - version 1.2
==================================
New features
------------
* The Trusted Board Boot implementation on ARM platforms now conforms to the
mandatory requirements of the TBBR specification.
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
platforms, a secure instance of ARM SP805 is used as the Trusted Watchdog.
Also, a firmware update process has been implemented. It enables
authenticated firmware to update firmware images from external interfaces to
SoC Non-Volatile memories. This feature functions even when the current
firmware in the system is corrupt or missing; it therefore may be used as
a recovery mode.
* Improvements have been made to the Certificate Generation Tool
(`cert_create`) as follows.
* Added support for the Firmware Update process by extending the Chain
of Trust definition in the tool to include the Firmware Update
certificate and the required extensions.
* Introduced a new API that allows one to specify command line options in
the Chain of Trust description. This makes the declaration of the tool's
arguments more flexible and easier to extend.
* The tool has been reworked to follow a data driven approach, which
makes it easier to maintain and extend.
* Extended the FIP tool (`fip_create`) to support the new set of images
involved in the Firmware Update process.
* Various memory footprint improvements. In particular:
* The bakery lock structure for coherent memory has been optimised.
* The mbed TLS SHA1 functions are not needed, as SHA256 is used to
generate the certificate signature. Therefore, they have been compiled
out, reducing the memory footprint of BL1 and BL2 by approximately
6 KB.
* On ARM development platforms, each BL stage now individually defines
the number of regions that it needs to map in the MMU.
* Added the following new design documents:
* [Authentication framework]
* [Firmware Update]
* [TF Reset Design]
* [Power Domain Topology Design]
* Applied the new image terminology to the code base and documentation, as
described on the [TF wiki on GitHub][TF Image Terminology].
* The build system has been reworked to improve readability and facilitate
adding future extensions.
* 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
uses the runtime console for all output.
* Implemented a basic NOR flash driver for ARM platforms. It programs the
device using CFI (Common Flash Interface) standard commands.
* Implemented support for booting EL3 payloads on ARM platforms, which
reduces the complexity of developing EL3 baremetal code by doing essential
baremetal initialization.
* Provided separate drivers for GICv3 and GICv2. These expect the entire
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.
* Added support for Juno r1 and r2. A single set of Juno TF binaries can run
on Juno r0, r1 and r2 boards. Note that this TF version depends on a Linaro
release that does *not* contain Juno r2 support.
* Added support for MediaTek mt8173 platform.
* Implemented a generic driver for ARM CCN IP.
* Major rework of the PSCI implementation.
* Added framework to handle composite power states.
* Decoupled the notions of affinity instances (which describes the
hierarchical arrangement of cores) and of power domain topology, instead
of assuming a one-to-one mapping.
* Better alignment with version 1.0 of the PSCI specification.
* 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
into a low power mode with memory retention.
* Unified the reset handling code as much as possible across BL stages.
Also introduced some build options to enable optimization of the reset path
on platforms that support it.
* Added a simple delay timer API, as well as an SP804 timer driver, which is
enabled on FVP.
* Added support for NVidia Tegra T210 and T132 SoCs.
* Reorganised ARM platforms ports to greatly improve code shareability and
facilitate the reuse of some of this code by other platforms.
* Added support for ARM Cortex-A72 processor in the CPU specific framework.
* Provided better error handling. Platform ports can now define their own
error handling, for example to perform platform specific bookkeeping or
post-error actions.
* 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
common driver. The standalone CCI-400 driver has been deprecated.
Issues resolved since last release
----------------------------------
* The Trusted Board Boot implementation has been redesigned to provide greater
modularity and scalability. See the [Authentication Framework] document.
All missing mandatory features are now implemented.
* The FVP and Juno ports may now use the hash of the ROTPK stored in the
Trusted Key Storage registers to verify the ROTPK. Alternatively, a
development public key hash embedded in the BL1 and BL2 binaries might be
used instead. The location of the ROTPK is chosen at build-time using the
`ARM_ROTPK_LOCATION` build option.
* GICv3 is now fully supported and stable.
Known issues
------------
* The version of the AEMv8 Base FVP used in this release resets the model
instead of terminating its execution in response to a shutdown request using
the PSCI `SYSTEM_OFF` API. This issue will be fixed in a future version of
the model.
* While this version has low on-chip RAM requirements, there are further
RAM usage enhancements that could be made.
* The upstream documentation could be improved for structural consistency,
clarity and completeness. In particular, the design documentation is
incomplete for PSCI, the TSP(D) and the Juno platform.
* Building TF with compiler optimisations disabled (`-O0`) fails.
ARM Trusted Firmware - version 1.1
==================================
New features
------------
* A prototype implementation of Trusted Board Boot has been added. Boot
loader images are verified by BL1 and BL2 during the cold boot path. BL1 and
BL2 use the PolarSSL SSL library to verify certificates and images. The
OpenSSL library is used to create the X.509 certificates. Support has been
added to `fip_create` tool to package the certificates in a FIP.
* Support for calling CPU and platform specific reset handlers upon entry into
BL3-1 during the cold and warm boot paths has been added. This happens after
another Boot ROM `reset_handler()` has already run. This enables a developer
to perform additional actions or undo actions already performed during the
first call of the reset handlers e.g. apply additional errata workarounds.
* Support has been added to demonstrate routing of IRQs to EL3 instead of
S-EL1 when execution is in secure world.
* The PSCI implementation now conforms to version 1.0 of the PSCI
specification. All the mandatory APIs and selected optional APIs are
supported. In particular, support for the `PSCI_FEATURES` API has been
added. A capability variable is constructed during initialization by
examining the `plat_pm_ops` and `spd_pm_ops` exported by the platform and
the Secure Payload Dispatcher. This is used by the PSCI FEATURES function
to determine which PSCI APIs are supported by the platform.
* Improvements have been made to the PSCI code as follows.
* The code has been refactored to remove redundant parameters from
internal functions.
* Changes have been made to the code for PSCI `CPU_SUSPEND`, `CPU_ON` and
`CPU_OFF` calls to facilitate an early return to the caller in case a
failure condition is detected. For example, a PSCI `CPU_SUSPEND` call
returns `SUCCESS` to the caller if a pending interrupt is detected early
in the code path.
* Optional platform APIs have been added to validate the `power_state` and
`entrypoint` parameters early in PSCI `CPU_ON` and `CPU_SUSPEND` code
paths.
* PSCI migrate APIs have been reworked to invoke the SPD hook to determine
the type of Trusted OS and the CPU it is resident on (if
applicable). Also, during a PSCI `MIGRATE` call, the SPD hook to migrate
the Trusted OS is invoked.
* It is now possible to build Trusted Firmware without marking at least an
extra page of memory as coherent. The build flag `USE_COHERENT_MEM` can be
used to choose between the two implementations. This has been made possible
through these changes.
* An implementation of Bakery locks, where the locks are not allocated in
coherent memory has been added.
* Memory which was previously marked as coherent is now kept coherent
through the use of software cache maintenance operations.
Approximately, 4K worth of memory is saved for each boot loader stage when
`USE_COHERENT_MEM=0`. Enabling this option increases the latencies
associated with acquire and release of locks. It also requires changes to
the platform ports.
* It is now possible to specify the name of the FIP at build time by defining
the `FIP_NAME` variable.
* Issues with depedencies on the 'fiptool' makefile target have been
rectified. The `fip_create` tool is now rebuilt whenever its source files
change.
* The BL3-1 runtime console is now also used as the crash console. The crash
console is changed to SoC UART0 (UART2) from the previous FPGA UART0 (UART0)
on Juno. In FVP, it is changed from UART0 to UART1.
* CPU errata workarounds are applied only when the revision and part number
match. This behaviour has been made consistent across the debug and release
builds. The debug build additionally prints a warning if a mismatch is
detected.
* It is now possible to issue cache maintenance operations by set/way for a
particular level of data cache. Levels 1-3 are currently supported.
* The following improvements have been made to the FVP port.
* The build option `FVP_SHARED_DATA_LOCATION` which allowed relocation of
shared data into the Trusted DRAM has been deprecated. Shared data is
now always located at the base of Trusted SRAM.
* BL2 Translation tables have been updated to map only the region of
DRAM which is accessible to normal world. This is the region of the 2GB
DDR-DRAM memory at 0x80000000 excluding the top 16MB. The top 16MB is
accessible to only the secure world.
* BL3-2 can now reside in the top 16MB of DRAM which is accessible only to
the secure world. This can be done by setting the build flag
`FVP_TSP_RAM_LOCATION` to the value `dram`.
* Separate transation tables are created for each boot loader image. The
`IMAGE_BLx` build options are used to do this. This allows each stage to
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
added. Details of using it with ARM Trusted Firmware can be found in
[OP-TEE Dispatcher]
Issues resolved since last release
----------------------------------
* The Juno port has been aligned with the FVP port as follows.
* Support for reclaiming all BL1 RW memory and BL2 memory by overlaying
the BL3-1/BL3-2 NOBITS sections on top of them has been added to the
Juno port.
* 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.
* The ARM GIC driver is used to configure the GIC-400 instead of using a
GIC driver private to the Juno port.
* PSCI `CPU_SUSPEND` calls that target a standby state are now supported.
* The TZC-400 driver is used to configure the controller instead of direct
accesses to the registers.
* The Linux kernel version referred to in the user guide has DVFS and HMP
support enabled.
* DS-5 v5.19 did not detect Version 5.8 of the Cortex-A57-A53 Base FVPs in
CADI server mode. This issue is not seen with DS-5 v5.20 and Version 6.2 of
the Cortex-A57-A53 Base FVPs.
Known issues
------------
* The Trusted Board Boot implementation is a prototype. There are issues with
the modularity and scalability of the design. Support for a Trusted
Watchdog, firmware update mechanism, recovery images and Trusted debug is
absent. These issues will be addressed in future releases.
* The FVP and Juno ports do not use the hash of the ROTPK stored in the
Trusted Key Storage registers to verify the ROTPK in the
`plat_match_rotpk()` function. This prevents the correct establishment of
the Chain of Trust at the first step in the Trusted Board Boot process.
* The version of the AEMv8 Base FVP used in this release resets the model
instead of terminating its execution in response to a shutdown request using
the PSCI `SYSTEM_OFF` API. This issue will be fixed in a future version of
the model.
* GICv3 support is experimental. There are known issues with GICv3
initialization in the ARM Trusted Firmware.
* While this version greatly reduces the on-chip RAM requirements, there are
further RAM usage enhancements that could be made.
* The firmware design documentation for the Test Secure-EL1 Payload (TSP) and
its dispatcher (TSPD) is incomplete. Similarly for the PSCI section.
* The Juno-specific firmware design documentation is incomplete.
ARM Trusted Firmware - version 1.0
==================================
New features
------------
* It is now possible to map higher physical addresses using non-flat virtual
to physical address mappings in the MMU setup.
* Wider use is now made of the per-CPU data cache in BL3-1 to store:
* Pointers to the non-secure and secure security state contexts.
* A pointer to the CPU-specific operations.
* A pointer to PSCI specific information (for example the current power
state).
* A crash reporting buffer.
* The following RAM usage improvements result in a BL3-1 RAM usage reduction
from 96KB to 56KB (for FVP with TSPD), and a total RAM usage reduction
across all images from 208KB to 88KB, compared to the previous release.
* Removed the separate `early_exception` vectors from BL3-1 (2KB code size
saving).
* Removed NSRAM from the FVP memory map, allowing the removal of one
(4KB) translation table.
* Eliminated the internal `psci_suspend_context` array, saving 2KB.
* Correctly dimensioned the PSCI `aff_map_node` array, saving 1.5KB in the
FVP port.
* Removed calling CPU mpidr from the bakery lock API, saving 160 bytes.
* Removed current CPU mpidr from PSCI common code, saving 160 bytes.
* Inlined the mmio accessor functions, saving 360 bytes.
* Fully reclaimed all BL1 RW memory and BL2 memory on the FVP port by
overlaying the BL3-1/BL3-2 NOBITS sections on top of these at runtime.
* Made storing the FP register context optional, saving 0.5KB per context
(8KB on the FVP port, with TSPD enabled and running on 8 CPUs).
* Implemented a leaner `tf_printf()` function, allowing the stack to be
greatly reduced.
* Removed coherent stacks from the codebase. Stacks allocated in normal
memory are now used before and after the MMU is enabled. This saves 768
bytes per CPU in BL3-1.
* Reworked the crash reporting in BL3-1 to use less stack.
* Optimized the EL3 register state stored in the `cpu_context` structure
so that registers that do not change during normal execution are
re-initialized each time during cold/warm boot, rather than restored
from memory. This saves about 1.2KB.
* As a result of some of the above, reduced the runtime stack size in all
BL images. For BL3-1, this saves 1KB per CPU.
* PSCI SMC handler improvements to correctly handle calls from secure states
and from AArch32.
* CPU contexts are now initialized from the `entry_point_info`. BL3-1 fully
determines the exception level to use for the non-trusted firmware (BL3-3)
based on the SPSR value provided by the BL2 platform code (or otherwise
provided to BL3-1). This allows platform code to directly run non-trusted
firmware payloads at either EL2 or EL1 without requiring an EL2 stub or OS
loader.
* Code refactoring improvements:
* Refactored `fvp_config` into a common platform header.
* Refactored the fvp gic code to be a generic driver that no longer has an
explicit dependency on platform code.
* Refactored the CCI-400 driver to not have dependency on platform code.
* Simplified the IO driver so it's no longer necessary to call `io_init()`
and moved all the IO storage framework code to one place.
* Simplified the interface the the TZC-400 driver.
* Clarified the platform porting interface to the TSP.
* Reworked the TSPD setup code to support the alternate BL3-2
intialization flow where BL3-1 generic code hands control to BL3-2,
rather than expecting the TSPD to hand control directly to BL3-2.
* Considerable rework to PSCI generic code to support CPU specific
operations.
* Improved console log output, by:
* Adding the concept of debug log levels.
* Rationalizing the existing debug messages and adding new ones.
* Printing out the version of each BL stage at runtime.
* Adding support for printing console output from assembler code,
including when a crash occurs before the C runtime is initialized.
* Moved up to the latest versions of the FVPs, toolchain, EDK2, kernel, Linaro
file system and DS-5.
* On the FVP port, made the use of the Trusted DRAM region optional at build
time (off by default). Normal platforms will not have such a "ready-to-use"
DRAM area so it is not a good example to use it.
* Added support for PSCI `SYSTEM_OFF` and `SYSTEM_RESET` APIs.
* Added support for CPU specific reset sequences, power down sequences and
register dumping during crash reporting. The CPU specific reset sequences
include support for errata workarounds.
* Merged the Juno port into the master branch. Added support for CPU hotplug
and CPU idle. Updated the user guide to describe how to build and run on the
Juno platform.
Issues resolved since last release
----------------------------------
* Removed the concept of top/bottom image loading. The image loader now
automatically detects the position of the image inside the current memory
layout and updates the layout to minimize fragementation. This resolves the
image loader limitations of previously releases. There are currently no
plans to support dynamic image loading.
* CPU idle now works on the publicized version of the Foundation FVP.
* 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).
Known issues
------------
* GICv3 support is experimental. The Linux kernel patches to support this are
not widely available. There are known issues with GICv3 initialization in
the ARM Trusted Firmware.
* While this version greatly reduces the on-chip RAM requirements, there are
further RAM usage enhancements that could be made.
* The firmware design documentation for the Test Secure-EL1 Payload (TSP) and
its dispatcher (TSPD) is incomplete. Similarly for the PSCI section.
* The Juno-specific firmware design documentation is incomplete.
* Some recent enhancements to the FVP port have not yet been translated into
the Juno port. These will be tracked via the tf-issues project.
* The Linux kernel version referred to in the user guide has DVFS and HMP
support disabled due to some known instabilities at the time of this
release. A future kernel version will re-enable these features.
* DS-5 v5.19 does not detect Version 5.8 of the Cortex-A57-A53 Base FVPs in
CADI server mode. This is because the `<SimName>` reported by the FVP in
this version has changed. For example, for the Cortex-A57x4-A53x4 Base FVP,
the `<SimName>` reported by the FVP is `FVP_Base_Cortex_A57x4_A53x4`, while
DS-5 expects it to be `FVP_Base_A57x4_A53x4`.
The temporary fix to this problem is to change the name of the FVP in
`sw/debugger/configdb/Boards/ARM FVP/Base_A57x4_A53x4/cadi_config.xml`.
Change the following line:
<SimName>System Generator:FVP_Base_A57x4_A53x4</SimName>
to
<SimName>System Generator:FVP_Base_Cortex-A57x4_A53x4</SimName>
A similar change can be made to the other Cortex-A57-A53 Base FVP variants.
ARM Trusted Firmware - version 0.4
==================================
New features
------------
* Makefile improvements:
* Improved dependency checking when building.
* Removed `dump` target (build now always produces dump files).
* Enabled platform ports to optionally make use of parts of the Trusted
Firmware (e.g. BL3-1 only), rather than being forced to use all parts.
Also made the `fip` target optional.
* Specified the full path to source files and removed use of the `vpath`
keyword.
* Provided translation table library code for potential re-use by platforms
other than the FVPs.
* Moved architectural timer setup to platform-specific code.
* Added standby state support to PSCI cpu_suspend implementation.
* SRAM usage improvements:
* Started using the `-ffunction-sections`, `-fdata-sections` and
`--gc-sections` compiler/linker options to remove unused code and data
from the images. Previously, all common functions were being built into
all binary images, whether or not they were actually used.
* Placed all assembler functions in their own section to allow more unused
functions to be removed from images.
* Updated BL1 and BL2 to use a single coherent stack each, rather than one
per CPU.
* Changed variables that were unnecessarily declared and initialized as
non-const (i.e. in the .data section) so they are either uninitialized
(zero init) or const.
* Moved the Test Secure-EL1 Payload (BL3-2) to execute in Trusted SRAM by
default. The option for it to run in Trusted DRAM remains.
* Implemented a TrustZone Address Space Controller (TZC-400) driver. A
default configuration is provided for the Base FVPs. This means the model
parameter `-C bp.secure_memory=1` is now supported.
* Started saving the PSCI cpu_suspend 'power_state' parameter prior to
suspending a CPU. This allows platforms that implement multiple power-down
states at the same affinity level to identify a specific state.
* Refactored the entire codebase to reduce the amount of nesting in header
files and to make the use of system/user includes more consistent. Also
split platform.h to separate out the platform porting declarations from the
required platform porting definitions and the definitions/declarations
specific to the platform port.
* Optimized the data cache clean/invalidate operations.
* Improved the BL3-1 unhandled exception handling and reporting. Unhandled
exceptions now result in a dump of registers to the console.
* Major rework to the handover interface between BL stages, in particular the
interface to BL3-1. The interface now conforms to a specification and is
more future proof.
* Added support for optionally making the BL3-1 entrypoint a reset handler
(instead of BL1). This allows platforms with an alternative image loading
architecture to re-use BL3-1 with fewer modifications to generic code.
* Reserved some DDR DRAM for secure use on FVP platforms to avoid future
compatibility problems with non-secure software.
* Added support for secure interrupts targeting the Secure-EL1 Payload (SP)
(using GICv2 routing only). Demonstrated this working by adding an interrupt
target and supporting test code to the TSP. Also demonstrated non-secure
interrupt handling during TSP processing.
Issues resolved since last release
----------------------------------
* Now support use of the model parameter `-C bp.secure_memory=1` in the Base
FVPs (see **New features**).
* Support for secure world interrupt handling now available (see **New
features**).
* Made enough SRAM savings (see **New features**) to enable the Test Secure-EL1
Payload (BL3-2) to execute in Trusted SRAM by default.
* The tested filesystem used for this release (Linaro AArch64 OpenEmbedded
14.04) now correctly reports progress in the console.
* 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
dependency checking.
Known issues
------------
* GICv3 support is experimental. The Linux kernel patches to support this are
not widely available. There are known issues with GICv3 initialization in
the ARM Trusted Firmware.
* Dynamic image loading is not available yet. The current image loader
implementation (used to load BL2 and all subsequent images) has some
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.
* The ARM Trusted Firmware still uses too much on-chip Trusted SRAM. A number
of RAM usage enhancements have been identified to rectify this situation.
* 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
of writing. This can be worked around by disabling CPU idle in the Linux
kernel.
* Various bugs in ARM Trusted Firmware, UEFI and the Linux kernel have been
observed when using Linaro toolchain versions later than 13.11. Although
most of these have been fixed, some remain at the time of writing. These
mainly seem to relate to a subtle change in the way the compiler converts
between 64-bit and 32-bit values (e.g. during casting operations), which
reveals previously hidden bugs in client code.
* The firmware design documentation for the Test Secure-EL1 Payload (TSP) and
its dispatcher (TSPD) is incomplete. Similarly for the PSCI section.
ARM Trusted Firmware - version 0.3
==================================
New features
------------
* Support for Foundation FVP Version 2.0 added.
The documented UEFI configuration disables some devices that are unavailable
in the Foundation FVP, including MMC and CLCD. The resultant UEFI binary can
be used on the AEMv8 and Cortex-A57-A53 Base FVPs, as well as the Foundation
FVP.
NOTE: The software will not work on Version 1.0 of the Foundation FVP.
* Enabled third party contributions. Added a new contributing.md containing
instructions for how to contribute and updated copyright text in all files
to acknowledge contributors.
* The PSCI CPU_SUSPEND API has been stabilised to the extent where it can be
used for entry into power down states with the following restrictions:
- Entry into standby states is not supported.
- The API is only supported on the AEMv8 and Cortex-A57-A53 Base FVPs.
* The PSCI AFFINITY_INFO api has undergone limited testing on the Base FVPs to
allow experimental use.
* Required C library and runtime header files are now included locally in ARM
Trusted Firmware instead of depending on the toolchain standard include
paths. The local implementation has been cleaned up and reduced in scope.
* Added I/O abstraction framework, primarily to allow generic code to load
images in a platform-independent way. The existing image loading code has
been reworked to use the new framework. Semi-hosting and NOR flash I/O
drivers are provided.
* Introduced Firmware Image Package (FIP) handling code and tools. A FIP
combines multiple firmware images with a Table of Contents (ToC) into a
single binary image. The new FIP driver is another type of I/O driver. The
Makefile builds a FIP by default and the FVP platform code expect to load a
FIP from NOR flash, although some support for image loading using semi-
hosting is retained.
NOTE: Building a FIP by default is a non-backwards-compatible change.
NOTE: Generic BL2 code now loads a BL3-3 (non-trusted firmware) image into
DRAM instead of expecting this to be pre-loaded at known location. This is
also a non-backwards-compatible change.
NOTE: Some non-trusted firmware (e.g. UEFI) will need to be rebuilt so that
it knows the new location to execute from and no longer needs to copy
particular code modules to DRAM itself.
* Reworked BL2 to BL3-1 handover interface. A new composite structure
(bl31_args) holds the superset of information that needs to be passed from
BL2 to BL3-1, including information on how handover execution control to
BL3-2 (if present) and BL3-3 (non-trusted firmware).
* Added library support for CPU context management, allowing the saving and
restoring of
- Shared system registers between Secure-EL1 and EL1.
- VFP registers.
- Essential EL3 system registers.
* Added a framework for implementing EL3 runtime services. Reworked the PSCI
implementation to be one such runtime service.
* Reworked the exception handling logic, making use of both SP_EL0 and SP_EL3
stack pointers for determining the type of exception, managing general
purpose and system register context on exception entry/exit, and handling
SMCs. SMCs are directed to the correct EL3 runtime service.
* Added support for a Test Secure-EL1 Payload (TSP) and a corresponding
Dispatcher (TSPD), which is loaded as an EL3 runtime service. The TSPD
implements Secure Monitor functionality such as world switching and
EL1 context management, and is responsible for communication with the TSP.
NOTE: The TSPD does not yet contain support for secure world interrupts.
NOTE: The TSP/TSPD is not built by default.
Issues resolved since last release
----------------------------------
* Support has been added for switching context between secure and normal
worlds in EL3.
* PSCI API calls `AFFINITY_INFO` & `PSCI_VERSION` have now been tested (to
a limited extent).
* The ARM Trusted Firmware build artifacts are now placed in the `./build`
directory and sub-directories instead of being placed in the root of the
project.
* The ARM Trusted Firmware is now free from build warnings. Build warnings
are now treated as errors.
* The ARM Trusted Firmware now provides C library support locally within the
project to maintain compatibility between toolchains/systems.
* The PSCI locking code has been reworked so it no longer takes locks in an
incorrect sequence.
* 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
version 3.13) used in this release, for both Foundation and Base FVPs.
Known issues
------------
The following is a list of issues which are expected to be fixed in the future
releases of the ARM Trusted Firmware.
* The TrustZone Address Space Controller (TZC-400) is not being programmed
yet. Use of model parameter `-C bp.secure_memory=1` is not supported.
* No support yet for secure world interrupt handling.
* GICv3 support is experimental. The Linux kernel patches to support this are
not widely available. There are known issues with GICv3 initialization in
the ARM Trusted Firmware.
* Dynamic image loading is not available yet. The current image loader
implementation (used to load BL2 and all subsequent images) has some
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.
* The ARM Trusted Firmware uses too much on-chip Trusted SRAM. Currently the
Test Secure-EL1 Payload (BL3-2) executes in Trusted DRAM since there is not
enough SRAM. A number of RAM usage enhancements have been identified to
rectify this situation.
* 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
of writing.
* Various bugs in ARM Trusted Firmware, UEFI and the Linux kernel have been
observed when using Linaro toolchain versions later than 13.11. Although
most of these have been fixed, some remain at the time of writing. These
mainly seem to relate to a subtle change in the way the compiler converts
between 64-bit and 32-bit values (e.g. during casting operations), which
reveals previously hidden bugs in client code.
* The tested filesystem used for this release (Linaro AArch64 OpenEmbedded
14.01) does not report progress correctly in the console. It only seems to
produce error output, not standard output. It otherwise appears to function
correctly. Other filesystem versions on the same software stack do not
exhibit the problem.
* 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
required in a platform port. Also, dependency checking in the Makefile is
flawed.
* The firmware design documentation for the Test Secure-EL1 Payload (TSP) and
its dispatcher (TSPD) is incomplete. Similarly for the PSCI section.
ARM Trusted Firmware - version 0.2
==================================
New features
------------
* First source release.
* Code for the PSCI suspend feature is supplied, although this is not enabled
by default since there are known issues (see below).
Issues resolved since last release
----------------------------------
* The "psci" nodes in the FDTs provided in this release now fully comply
with the recommendations made in the PSCI specification.
Known issues
------------
The following is a list of issues which are expected to be fixed in the future
releases of the ARM Trusted Firmware.
* The TrustZone Address Space Controller (TZC-400) is not being programmed
yet. Use of model parameter `-C bp.secure_memory=1` is not supported.
* No support yet for secure world interrupt handling or for switching context
between secure and normal worlds in EL3.
* GICv3 support is experimental. The Linux kernel patches to support this are
not widely available. There are known issues with GICv3 initialization in
the ARM Trusted Firmware.
* Dynamic image loading is not available yet. The current image loader
implementation (used to load BL2 and all subsequent images) has some
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.
* Although support for PSCI `CPU_SUSPEND` is present, it is not yet stable
and ready for use.
* PSCI API calls `AFFINITY_INFO` & `PSCI_VERSION` are implemented but have not
been tested.
* The ARM Trusted Firmware make files result in all build artifacts being
placed in the root of the project. These should be placed in appropriate
sub-directories.
* The compilation of ARM Trusted Firmware is not free from compilation
warnings. Some of these warnings have not been investigated yet so they
could mask real bugs.
* The ARM Trusted Firmware currently uses toolchain/system include files like
stdio.h. It should provide versions of these within the project to maintain
compatibility between toolchains/systems.
* The PSCI code takes some locks in an incorrect sequence. This may cause
problems with suspend and hotplug in certain conditions.
* 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
a RAM-disk. It fails to execute user-space `init` from the RAM-disk. As an
alternative, the VirtioBlock mechanism can be used to provide a file-system
to the kernel.
- - - - - - - - - - - - - - - - - - - - - - - - - -
_Copyright (c) 2013-2016, ARM Limited and Contributors. All rights reserved._
[OP-TEE Dispatcher]: optee-dispatcher.md
[Power Domain Topology Design]: psci-pd-tree.md
[TF Image Terminology]: https://github.com/ARM-software/arm-trusted-firmware/wiki/ARM-Trusted-Firmware-Image-Terminology
[Authentication Framework]: auth-framework.md
[Firmware Update]: firmware-update.md
[TF Reset Design]: reset-design.md
[PSCI Integration Guide]: psci-lib-integration-guide.md
[Firmware Design]: firmware-design.md
[CPU Specific Build Macros]: cpu-specific-build-macros.md
[User Guide]: user-guide.md
[Porting Guide]: porting-guide.md
[Developer Certificate of Origin]: ../dco.txt
[Contribution Guide]: ../contributing.md
docs/change-log.rst 0 → 100644
View file @ 7cefb56d
.. section-numbering::
:suffix: .
.. contents::
ARM Trusted Firmware - version 1.3
==================================
New features
------------
- Added support for running Trusted Firmware in AArch32 execution state.
The PSCI library has been refactored to allow integration with **EL3 Runtime
Software**. This is software that is executing at the highest secure
privilege which is EL3 in AArch64 or Secure SVC/Monitor mode in AArch32. See
`PSCI Integration Guide`_.
Included is a minimal AArch32 Secure Payload, **SP-MIN**, that illustrates
the usage and integration of the PSCI library with EL3 Runtime Software
running in AArch32 state.
Booting to the BL1/BL2 images as well as booting straight to the Secure
Payload is supported.
- Improvements to the initialization framework for the PSCI service and ARM
Standard Services in general.
The PSCI service is now initialized as part of ARM Standard Service
initialization. This consolidates the initializations of any ARM Standard
Service that may be added in the future.
A new function ``get_arm_std_svc_args()`` is introduced to get arguments
corresponding to each standard service and must be implemented by the EL3
Runtime Software.
For PSCI, a new versioned structure ``psci_lib_args_t`` is introduced to
initialize the PSCI Library. **Note** this is a compatibility break due to
the change in the prototype of ``psci_setup()``.
- To support AArch32 builds of BL1 and BL2, implemented a new, alternative
firmware image loading mechanism that adds flexibility.
The current mechanism has a hard-coded set of images and execution order
(BL31, BL32, etc). The new mechanism is data-driven by a list of image
descriptors provided by the platform code.
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
currently off by default for the AArch64 build.
**Note** ``TRUSTED_BOARD_BOOT`` is currently not supported when
``LOAD_IMAGE_V2`` is enabled.
- Updated requirements for making contributions to ARM TF.
Commits now must have a 'Signed-off-by:' field to certify that the
contribution has been made under the terms of the
`Developer Certificate of Origin`_.
A signed CLA is no longer required.
The `Contribution Guide`_ has been updated to reflect this change.
- Introduced Performance Measurement Framework (PMF) which provides support
for capturing, storing, dumping and retrieving time-stamps to measure the
execution time of critical paths in the firmware. This relies on defining
fixed sample points at key places in the code.
- To support the QEMU platform port, imported libfdt v1.4.1 from
https://git.kernel.org/cgit/utils/dtc/dtc.git
- Updated PSCI support:
- Added support for PSCI NODE\_HW\_STATE API for ARM platforms.
- New optional platform hook, ``pwr_domain_pwr_down_wfi()``, in
``plat_psci_ops`` to enable platforms to perform platform-specific actions
needed to enter powerdown, including the 'wfi' invocation.
- PSCI STAT residency and count functions have been added on ARM platforms
by using PMF.
- Enhancements to the translation table library:
- Limited memory mapping support for region overlaps to only allow regions
to overlap that are identity mapped or have the same virtual to physical
address offset, and overlap completely but must not cover the same area.
This limitation will enable future enhancements without having to
support complex edge cases that may not be necessary.
- The initial translation lookup level is now inferred from the virtual
address space size. Previously, it was hard-coded.
- Added support for mapping Normal, Inner Non-cacheable, Outer
Non-cacheable memory in the translation table library.
This can be useful to map a non-cacheable memory region, such as a DMA
buffer.
- Introduced the MT\_EXECUTE/MT\_EXECUTE\_NEVER memory mapping attributes to
specify the access permissions for instruction execution of a memory
region.
- Enabled support to isolate code and read-only data on separate memory pages,
allowing independent access control to be applied to each.
- Enabled SCR\_EL3.SIF (Secure Instruction Fetch) bit in BL1 and BL31 common
architectural setup code, preventing fetching instructions from non-secure
memory when in secure state.
- Enhancements to FIP support:
- Replaced ``fip_create`` with ``fiptool`` which provides a more consistent
and intuitive interface as well as additional support to remove an image
from a FIP file.
- Enabled printing the SHA256 digest with info command, allowing quick
verification of an image within a FIP without having to extract the
image and running sha256sum on it.
- Added support for unpacking the contents of an existing FIP file into
the working directory.
- Aligned command line options for specifying images to use same naming
convention as specified by TBBR and already used in cert\_create tool.
- Refactored the TZC-400 driver to also support memory controllers that
integrate TZC functionality, for example ARM CoreLink DMC-500. Also added
DMC-500 specific support.
- Implemented generic delay timer based on the system generic counter and
migrated all platforms to use it.
- Enhanced support for ARM platforms:
- Updated image loading support to make SCP images (SCP\_BL2 and SCP\_BL2U)
optional.
- Enhanced topology description support to allow multi-cluster topology
definitions.
- Added interconnect abstraction layer to help platform ports select the
right interconnect driver, CCI or CCN, for the platform.
- Added support to allow loading BL31 in the TZC-secured DRAM instead of
the default secure SRAM.
- Added support to use a System Security Control (SSC) Registers Unit
enabling ARM TF to be compiled to support multiple ARM platforms and
then select one at runtime.
- Restricted mapping of Trusted ROM in BL1 to what is actually needed by
BL1 rather than entire Trusted ROM region.
- Flash is now mapped as execute-never by default. This increases security
by restricting the executable region to what is strictly needed.
- Applied following erratum workarounds for Cortex-A57: 833471, 826977,
829520, 828024 and 826974.
- Added support for Mediatek MT6795 platform.
- Added support for QEMU virtualization ARMv8-A target.
- Added support for Rockchip RK3368 and RK3399 platforms.
- Added support for Xilinx Zynq UltraScale+ MPSoC platform.
- Added support for ARM Cortex-A73 MPCore Processor.
- Added support for ARM Cortex-A72 processor.
- Added support for ARM Cortex-A35 processor.
- Added support for ARM Cortex-A32 MPCore Processor.
- 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. The User Guide has been updated with an example of how to use this
option with a bootwrapped kernel.
- Added support to build ARM TF on a Windows-based host machine.
- Updated Trusted Board Boot prototype implementation:
- Enabled the ability for a production ROM with TBBR enabled to boot test
software before a real ROTPK is deployed (e.g. manufacturing mode).
Added support to use ROTPK in certificate without verifying against the
platform value when ``ROTPK_NOT_DEPLOYED`` bit is set.
- Added support for non-volatile counter authentication to the
Authentication Module to protect against roll-back.
- Updated GICv3 support:
- Enabled processor power-down and automatic power-on using GICv3.
- Enabled G1S or G0 interrupts to be configured independently.
- Changed FVP default interrupt driver to be the GICv3-only driver.
**Note** the default build of Trusted Firmware will not be able to boot
Linux kernel with GICv2 FDT blob.
- Enabled wake-up from CPU\_SUSPEND to stand-by by temporarily re-routing
interrupts and then restoring after resume.
Issues resolved since last release
----------------------------------
Known issues
------------
- The version of the AEMv8 Base FVP used in this release resets the model
instead of terminating its execution in response to a shutdown request using
the PSCI ``SYSTEM_OFF`` API. This issue will be fixed in a future version of
the model.
- Building TF with compiler optimisations disabled (``-O0``) fails.
- ARM TF cannot be built with mbed TLS version v2.3.0 due to build warnings
that the ARM TF build system interprets as errors.
- TBBR is not currently supported when running Trusted Firmware in AArch32
state.
ARM Trusted Firmware - version 1.2
==================================
New features
------------
- The Trusted Board Boot implementation on ARM platforms now conforms to the
mandatory requirements of the TBBR specification.
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
platforms, a secure instance of ARM SP805 is used as the Trusted Watchdog.
Also, a firmware update process has been implemented. It enables
authenticated firmware to update firmware images from external interfaces to
SoC Non-Volatile memories. This feature functions even when the current
firmware in the system is corrupt or missing; it therefore may be used as
a recovery mode.
- Improvements have been made to the Certificate Generation Tool
(``cert_create``) as follows.
- Added support for the Firmware Update process by extending the Chain
of Trust definition in the tool to include the Firmware Update
certificate and the required extensions.
- Introduced a new API that allows one to specify command line options in
the Chain of Trust description. This makes the declaration of the tool's
arguments more flexible and easier to extend.
- The tool has been reworked to follow a data driven approach, which
makes it easier to maintain and extend.
- Extended the FIP tool (``fip_create``) to support the new set of images
involved in the Firmware Update process.
- Various memory footprint improvements. In particular:
- The bakery lock structure for coherent memory has been optimised.
- The mbed TLS SHA1 functions are not needed, as SHA256 is used to
generate the certificate signature. Therefore, they have been compiled
out, reducing the memory footprint of BL1 and BL2 by approximately
6 KB.
- On ARM development platforms, each BL stage now individually defines
the number of regions that it needs to map in the MMU.
- Added the following new design documents:
- `Authentication framework`_
- `Firmware Update`_
- `TF Reset Design`_
- `Power Domain Topology Design`_
- Applied the new image terminology to the code base and documentation, as
described on the `TF wiki on GitHub`_.
- The build system has been reworked to improve readability and facilitate
adding future extensions.
- 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
uses the runtime console for all output.
- Implemented a basic NOR flash driver for ARM platforms. It programs the
device using CFI (Common Flash Interface) standard commands.
- Implemented support for booting EL3 payloads on ARM platforms, which
reduces the complexity of developing EL3 baremetal code by doing essential
baremetal initialization.
- Provided separate drivers for GICv3 and GICv2. These expect the entire
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.
- Added support for Juno r1 and r2. A single set of Juno TF binaries can run
on Juno r0, r1 and r2 boards. Note that this TF version depends on a Linaro
release that does *not* contain Juno r2 support.
- Added support for MediaTek mt8173 platform.
- Implemented a generic driver for ARM CCN IP.
- Major rework of the PSCI implementation.
- Added framework to handle composite power states.
- Decoupled the notions of affinity instances (which describes the
hierarchical arrangement of cores) and of power domain topology, instead
of assuming a one-to-one mapping.
- Better alignment with version 1.0 of the PSCI specification.
- 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
into a low power mode with memory retention.
- Unified the reset handling code as much as possible across BL stages.
Also introduced some build options to enable optimization of the reset path
on platforms that support it.
- Added a simple delay timer API, as well as an SP804 timer driver, which is
enabled on FVP.
- Added support for NVidia Tegra T210 and T132 SoCs.
- Reorganised ARM platforms ports to greatly improve code shareability and
facilitate the reuse of some of this code by other platforms.
- Added support for ARM Cortex-A72 processor in the CPU specific framework.
- Provided better error handling. Platform ports can now define their own
error handling, for example to perform platform specific bookkeeping or
post-error actions.
- 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
common driver. The standalone CCI-400 driver has been deprecated.
Issues resolved since last release
----------------------------------
- The Trusted Board Boot implementation has been redesigned to provide greater
modularity and scalability. See the `Authentication Framework`_ document.
All missing mandatory features are now implemented.
- The FVP and Juno ports may now use the hash of the ROTPK stored in the
Trusted Key Storage registers to verify the ROTPK. Alternatively, a
development public key hash embedded in the BL1 and BL2 binaries might be
used instead. The location of the ROTPK is chosen at build-time using the
``ARM_ROTPK_LOCATION`` build option.
- GICv3 is now fully supported and stable.
Known issues
------------
- The version of the AEMv8 Base FVP used in this release resets the model
instead of terminating its execution in response to a shutdown request using
the PSCI ``SYSTEM_OFF`` API. This issue will be fixed in a future version of
the model.
- While this version has low on-chip RAM requirements, there are further
RAM usage enhancements that could be made.
- The upstream documentation could be improved for structural consistency,
clarity and completeness. In particular, the design documentation is
incomplete for PSCI, the TSP(D) and the Juno platform.
- Building TF with compiler optimisations disabled (``-O0``) fails.
ARM Trusted Firmware - version 1.1
==================================
New features
------------
- A prototype implementation of Trusted Board Boot has been added. Boot
loader images are verified by BL1 and BL2 during the cold boot path. BL1 and
BL2 use the PolarSSL SSL library to verify certificates and images. The
OpenSSL library is used to create the X.509 certificates. Support has been
added to ``fip_create`` tool to package the certificates in a FIP.
- Support for calling CPU and platform specific reset handlers upon entry into
BL3-1 during the cold and warm boot paths has been added. This happens after
another Boot ROM ``reset_handler()`` has already run. This enables a developer
to perform additional actions or undo actions already performed during the
first call of the reset handlers e.g. apply additional errata workarounds.
- Support has been added to demonstrate routing of IRQs to EL3 instead of
S-EL1 when execution is in secure world.
- The PSCI implementation now conforms to version 1.0 of the PSCI
specification. All the mandatory APIs and selected optional APIs are
supported. In particular, support for the ``PSCI_FEATURES`` API has been
added. A capability variable is constructed during initialization by
examining the ``plat_pm_ops`` and ``spd_pm_ops`` exported by the platform and
the Secure Payload Dispatcher. This is used by the PSCI FEATURES function
to determine which PSCI APIs are supported by the platform.
- Improvements have been made to the PSCI code as follows.
- The code has been refactored to remove redundant parameters from
internal functions.
- Changes have been made to the code for PSCI ``CPU_SUSPEND``, ``CPU_ON`` and
``CPU_OFF`` calls to facilitate an early return to the caller in case a
failure condition is detected. For example, a PSCI ``CPU_SUSPEND`` call
returns ``SUCCESS`` to the caller if a pending interrupt is detected early
in the code path.
- Optional platform APIs have been added to validate the ``power_state`` and
``entrypoint`` parameters early in PSCI ``CPU_ON`` and ``CPU_SUSPEND`` code
paths.
- PSCI migrate APIs have been reworked to invoke the SPD hook to determine
the type of Trusted OS and the CPU it is resident on (if
applicable). Also, during a PSCI ``MIGRATE`` call, the SPD hook to migrate
the Trusted OS is invoked.
- It is now possible to build Trusted Firmware without marking at least an
extra page of memory as coherent. The build flag ``USE_COHERENT_MEM`` can be
used to choose between the two implementations. This has been made possible
through these changes.
- An implementation of Bakery locks, where the locks are not allocated in
coherent memory has been added.
- Memory which was previously marked as coherent is now kept coherent
through the use of software cache maintenance operations.
Approximately, 4K worth of memory is saved for each boot loader stage when
``USE_COHERENT_MEM=0``. Enabling this option increases the latencies
associated with acquire and release of locks. It also requires changes to
the platform ports.
- It is now possible to specify the name of the FIP at build time by defining
the ``FIP_NAME`` variable.
- Issues with depedencies on the 'fiptool' makefile target have been
rectified. The ``fip_create`` tool is now rebuilt whenever its source files
change.
- The BL3-1 runtime console is now also used as the crash console. The crash
console is changed to SoC UART0 (UART2) from the previous FPGA UART0 (UART0)
on Juno. In FVP, it is changed from UART0 to UART1.
- CPU errata workarounds are applied only when the revision and part number
match. This behaviour has been made consistent across the debug and release
builds. The debug build additionally prints a warning if a mismatch is
detected.
- It is now possible to issue cache maintenance operations by set/way for a
particular level of data cache. Levels 1-3 are currently supported.
- The following improvements have been made to the FVP port.
- The build option ``FVP_SHARED_DATA_LOCATION`` which allowed relocation of
shared data into the Trusted DRAM has been deprecated. Shared data is
now always located at the base of Trusted SRAM.
- BL2 Translation tables have been updated to map only the region of
DRAM which is accessible to normal world. This is the region of the 2GB
DDR-DRAM memory at 0x80000000 excluding the top 16MB. The top 16MB is
accessible to only the secure world.
- BL3-2 can now reside in the top 16MB of DRAM which is accessible only to
the secure world. This can be done by setting the build flag
``FVP_TSP_RAM_LOCATION`` to the value ``dram``.
- Separate transation tables are created for each boot loader image. The
``IMAGE_BLx`` build options are used to do this. This allows each stage to
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
added. Details of using it with ARM Trusted Firmware can be found in
`OP-TEE Dispatcher`_
Issues resolved since last release
----------------------------------
- The Juno port has been aligned with the FVP port as follows.
- Support for reclaiming all BL1 RW memory and BL2 memory by overlaying
the BL3-1/BL3-2 NOBITS sections on top of them has been added to the
Juno port.
- 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.
- The ARM GIC driver is used to configure the GIC-400 instead of using a
GIC driver private to the Juno port.
- PSCI ``CPU_SUSPEND`` calls that target a standby state are now supported.
- The TZC-400 driver is used to configure the controller instead of direct
accesses to the registers.
- The Linux kernel version referred to in the user guide has DVFS and HMP
support enabled.
- DS-5 v5.19 did not detect Version 5.8 of the Cortex-A57-A53 Base FVPs in
CADI server mode. This issue is not seen with DS-5 v5.20 and Version 6.2 of
the Cortex-A57-A53 Base FVPs.
Known issues
------------
- The Trusted Board Boot implementation is a prototype. There are issues with
the modularity and scalability of the design. Support for a Trusted
Watchdog, firmware update mechanism, recovery images and Trusted debug is
absent. These issues will be addressed in future releases.
- The FVP and Juno ports do not use the hash of the ROTPK stored in the
Trusted Key Storage registers to verify the ROTPK in the
``plat_match_rotpk()`` function. This prevents the correct establishment of
the Chain of Trust at the first step in the Trusted Board Boot process.
- The version of the AEMv8 Base FVP used in this release resets the model
instead of terminating its execution in response to a shutdown request using
the PSCI ``SYSTEM_OFF`` API. This issue will be fixed in a future version of
the model.
- GICv3 support is experimental. There are known issues with GICv3
initialization in the ARM Trusted Firmware.
- While this version greatly reduces the on-chip RAM requirements, there are
further RAM usage enhancements that could be made.
- The firmware design documentation for the Test Secure-EL1 Payload (TSP) and
its dispatcher (TSPD) is incomplete. Similarly for the PSCI section.
- The Juno-specific firmware design documentation is incomplete.
ARM Trusted Firmware - version 1.0
==================================
New features
------------
- It is now possible to map higher physical addresses using non-flat virtual
to physical address mappings in the MMU setup.
- Wider use is now made of the per-CPU data cache in BL3-1 to store:
- Pointers to the non-secure and secure security state contexts.
- A pointer to the CPU-specific operations.
- A pointer to PSCI specific information (for example the current power
state).
- A crash reporting buffer.
- The following RAM usage improvements result in a BL3-1 RAM usage reduction
from 96KB to 56KB (for FVP with TSPD), and a total RAM usage reduction
across all images from 208KB to 88KB, compared to the previous release.
- Removed the separate ``early_exception`` vectors from BL3-1 (2KB code size
saving).
- Removed NSRAM from the FVP memory map, allowing the removal of one
(4KB) translation table.
- Eliminated the internal ``psci_suspend_context`` array, saving 2KB.
- Correctly dimensioned the PSCI ``aff_map_node`` array, saving 1.5KB in the
FVP port.
- Removed calling CPU mpidr from the bakery lock API, saving 160 bytes.
- Removed current CPU mpidr from PSCI common code, saving 160 bytes.
- Inlined the mmio accessor functions, saving 360 bytes.
- Fully reclaimed all BL1 RW memory and BL2 memory on the FVP port by
overlaying the BL3-1/BL3-2 NOBITS sections on top of these at runtime.
- Made storing the FP register context optional, saving 0.5KB per context
(8KB on the FVP port, with TSPD enabled and running on 8 CPUs).
- Implemented a leaner ``tf_printf()`` function, allowing the stack to be
greatly reduced.
- Removed coherent stacks from the codebase. Stacks allocated in normal
memory are now used before and after the MMU is enabled. This saves 768
bytes per CPU in BL3-1.
- Reworked the crash reporting in BL3-1 to use less stack.
- Optimized the EL3 register state stored in the ``cpu_context`` structure
so that registers that do not change during normal execution are
re-initialized each time during cold/warm boot, rather than restored
from memory. This saves about 1.2KB.
- As a result of some of the above, reduced the runtime stack size in all
BL images. For BL3-1, this saves 1KB per CPU.
- PSCI SMC handler improvements to correctly handle calls from secure states
and from AArch32.
- CPU contexts are now initialized from the ``entry_point_info``. BL3-1 fully
determines the exception level to use for the non-trusted firmware (BL3-3)
based on the SPSR value provided by the BL2 platform code (or otherwise
provided to BL3-1). This allows platform code to directly run non-trusted
firmware payloads at either EL2 or EL1 without requiring an EL2 stub or OS
loader.
- Code refactoring improvements:
- Refactored ``fvp_config`` into a common platform header.
- Refactored the fvp gic code to be a generic driver that no longer has an
explicit dependency on platform code.
- Refactored the CCI-400 driver to not have dependency on platform code.
- Simplified the IO driver so it's no longer necessary to call ``io_init()``
and moved all the IO storage framework code to one place.
- Simplified the interface the the TZC-400 driver.
- Clarified the platform porting interface to the TSP.
- Reworked the TSPD setup code to support the alternate BL3-2
intialization flow where BL3-1 generic code hands control to BL3-2,
rather than expecting the TSPD to hand control directly to BL3-2.
- Considerable rework to PSCI generic code to support CPU specific
operations.
- Improved console log output, by:
- Adding the concept of debug log levels.
- Rationalizing the existing debug messages and adding new ones.
- Printing out the version of each BL stage at runtime.
- Adding support for printing console output from assembler code,
including when a crash occurs before the C runtime is initialized.
- Moved up to the latest versions of the FVPs, toolchain, EDK2, kernel, Linaro
file system and DS-5.
- On the FVP port, made the use of the Trusted DRAM region optional at build
time (off by default). Normal platforms will not have such a "ready-to-use"
DRAM area so it is not a good example to use it.
- Added support for PSCI ``SYSTEM_OFF`` and ``SYSTEM_RESET`` APIs.
- Added support for CPU specific reset sequences, power down sequences and
register dumping during crash reporting. The CPU specific reset sequences
include support for errata workarounds.
- Merged the Juno port into the master branch. Added support for CPU hotplug
and CPU idle. Updated the user guide to describe how to build and run on the
Juno platform.
Issues resolved since last release
----------------------------------
- Removed the concept of top/bottom image loading. The image loader now
automatically detects the position of the image inside the current memory
layout and updates the layout to minimize fragementation. This resolves the
image loader limitations of previously releases. There are currently no
plans to support dynamic image loading.
- CPU idle now works on the publicized version of the Foundation FVP.
- 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).
Known issues
------------
- GICv3 support is experimental. The Linux kernel patches to support this are
not widely available. There are known issues with GICv3 initialization in
the ARM Trusted Firmware.
- While this version greatly reduces the on-chip RAM requirements, there are
further RAM usage enhancements that could be made.
- The firmware design documentation for the Test Secure-EL1 Payload (TSP) and
its dispatcher (TSPD) is incomplete. Similarly for the PSCI section.
- The Juno-specific firmware design documentation is incomplete.
- Some recent enhancements to the FVP port have not yet been translated into
the Juno port. These will be tracked via the tf-issues project.
- The Linux kernel version referred to in the user guide has DVFS and HMP
support disabled due to some known instabilities at the time of this
release. A future kernel version will re-enable these features.
- DS-5 v5.19 does not detect Version 5.8 of the Cortex-A57-A53 Base FVPs in
CADI server mode. This is because the ``<SimName>`` reported by the FVP in
this version has changed. For example, for the Cortex-A57x4-A53x4 Base FVP,
the ``<SimName>`` reported by the FVP is ``FVP_Base_Cortex_A57x4_A53x4``, while
DS-5 expects it to be ``FVP_Base_A57x4_A53x4``.
The temporary fix to this problem is to change the name of the FVP in
``sw/debugger/configdb/Boards/ARM FVP/Base_A57x4_A53x4/cadi_config.xml``.
Change the following line:
::
<SimName>System Generator:FVP_Base_A57x4_A53x4</SimName>
to
System Generator:FVP\_Base\_Cortex-A57x4\_A53x4
A similar change can be made to the other Cortex-A57-A53 Base FVP variants.
ARM Trusted Firmware - version 0.4
==================================
New features
------------
- Makefile improvements:
- Improved dependency checking when building.
- Removed ``dump`` target (build now always produces dump files).
- Enabled platform ports to optionally make use of parts of the Trusted
Firmware (e.g. BL3-1 only), rather than being forced to use all parts.
Also made the ``fip`` target optional.
- Specified the full path to source files and removed use of the ``vpath``
keyword.
- Provided translation table library code for potential re-use by platforms
other than the FVPs.
- Moved architectural timer setup to platform-specific code.
- Added standby state support to PSCI cpu\_suspend implementation.
- SRAM usage improvements:
- Started using the ``-ffunction-sections``, ``-fdata-sections`` and
``--gc-sections`` compiler/linker options to remove unused code and data
from the images. Previously, all common functions were being built into
all binary images, whether or not they were actually used.
- Placed all assembler functions in their own section to allow more unused
functions to be removed from images.
- Updated BL1 and BL2 to use a single coherent stack each, rather than one
per CPU.
- Changed variables that were unnecessarily declared and initialized as
non-const (i.e. in the .data section) so they are either uninitialized
(zero init) or const.
- Moved the Test Secure-EL1 Payload (BL3-2) to execute in Trusted SRAM by
default. The option for it to run in Trusted DRAM remains.
- Implemented a TrustZone Address Space Controller (TZC-400) driver. A
default configuration is provided for the Base FVPs. This means the model
parameter ``-C bp.secure_memory=1`` is now supported.
- Started saving the PSCI cpu\_suspend 'power\_state' parameter prior to
suspending a CPU. This allows platforms that implement multiple power-down
states at the same affinity level to identify a specific state.
- Refactored the entire codebase to reduce the amount of nesting in header
files and to make the use of system/user includes more consistent. Also
split platform.h to separate out the platform porting declarations from the
required platform porting definitions and the definitions/declarations
specific to the platform port.
- Optimized the data cache clean/invalidate operations.
- Improved the BL3-1 unhandled exception handling and reporting. Unhandled
exceptions now result in a dump of registers to the console.
- Major rework to the handover interface between BL stages, in particular the
interface to BL3-1. The interface now conforms to a specification and is
more future proof.
- Added support for optionally making the BL3-1 entrypoint a reset handler
(instead of BL1). This allows platforms with an alternative image loading
architecture to re-use BL3-1 with fewer modifications to generic code.
- Reserved some DDR DRAM for secure use on FVP platforms to avoid future
compatibility problems with non-secure software.
- Added support for secure interrupts targeting the Secure-EL1 Payload (SP)
(using GICv2 routing only). Demonstrated this working by adding an interrupt
target and supporting test code to the TSP. Also demonstrated non-secure
interrupt handling during TSP processing.
Issues resolved since last release
----------------------------------
- Now support use of the model parameter ``-C bp.secure_memory=1`` in the Base
FVPs (see **New features**).
- Support for secure world interrupt handling now available (see **New
features**).
- Made enough SRAM savings (see **New features**) to enable the Test Secure-EL1
Payload (BL3-2) to execute in Trusted SRAM by default.
- The tested filesystem used for this release (Linaro AArch64 OpenEmbedded
14.04) now correctly reports progress in the console.
- 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
dependency checking.
Known issues
------------
- GICv3 support is experimental. The Linux kernel patches to support this are
not widely available. There are known issues with GICv3 initialization in
the ARM Trusted Firmware.
- Dynamic image loading is not available yet. The current image loader
implementation (used to load BL2 and all subsequent images) has some
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.
- The ARM Trusted Firmware still uses too much on-chip Trusted SRAM. A number
of RAM usage enhancements have been identified to rectify this situation.
- 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
of writing. This can be worked around by disabling CPU idle in the Linux
kernel.
- Various bugs in ARM Trusted Firmware, UEFI and the Linux kernel have been
observed when using Linaro toolchain versions later than 13.11. Although
most of these have been fixed, some remain at the time of writing. These
mainly seem to relate to a subtle change in the way the compiler converts
between 64-bit and 32-bit values (e.g. during casting operations), which
reveals previously hidden bugs in client code.
- The firmware design documentation for the Test Secure-EL1 Payload (TSP) and
its dispatcher (TSPD) is incomplete. Similarly for the PSCI section.
ARM Trusted Firmware - version 0.3
==================================
New features
------------
- Support for Foundation FVP Version 2.0 added.
The documented UEFI configuration disables some devices that are unavailable
in the Foundation FVP, including MMC and CLCD. The resultant UEFI binary can
be used on the AEMv8 and Cortex-A57-A53 Base FVPs, as well as the Foundation
FVP.
NOTE: The software will not work on Version 1.0 of the Foundation FVP.
- Enabled third party contributions. Added a new contributing.md containing
instructions for how to contribute and updated copyright text in all files
to acknowledge contributors.
- The PSCI CPU\_SUSPEND API has been stabilised to the extent where it can be
used for entry into power down states with the following restrictions:
- Entry into standby states is not supported.
- The API is only supported on the AEMv8 and Cortex-A57-A53 Base FVPs.
- The PSCI AFFINITY\_INFO api has undergone limited testing on the Base FVPs to
allow experimental use.
- Required C library and runtime header files are now included locally in ARM
Trusted Firmware instead of depending on the toolchain standard include
paths. The local implementation has been cleaned up and reduced in scope.
- Added I/O abstraction framework, primarily to allow generic code to load
images in a platform-independent way. The existing image loading code has
been reworked to use the new framework. Semi-hosting and NOR flash I/O
drivers are provided.
- Introduced Firmware Image Package (FIP) handling code and tools. A FIP
combines multiple firmware images with a Table of Contents (ToC) into a
single binary image. The new FIP driver is another type of I/O driver. The
Makefile builds a FIP by default and the FVP platform code expect to load a
FIP from NOR flash, although some support for image loading using semi-
hosting is retained.
NOTE: Building a FIP by default is a non-backwards-compatible change.
NOTE: Generic BL2 code now loads a BL3-3 (non-trusted firmware) image into
DRAM instead of expecting this to be pre-loaded at known location. This is
also a non-backwards-compatible change.
NOTE: Some non-trusted firmware (e.g. UEFI) will need to be rebuilt so that
it knows the new location to execute from and no longer needs to copy
particular code modules to DRAM itself.
- Reworked BL2 to BL3-1 handover interface. A new composite structure
(bl31\_args) holds the superset of information that needs to be passed from
BL2 to BL3-1, including information on how handover execution control to
BL3-2 (if present) and BL3-3 (non-trusted firmware).
- Added library support for CPU context management, allowing the saving and
restoring of
- Shared system registers between Secure-EL1 and EL1.
- VFP registers.
- Essential EL3 system registers.
- Added a framework for implementing EL3 runtime services. Reworked the PSCI
implementation to be one such runtime service.
- Reworked the exception handling logic, making use of both SP\_EL0 and SP\_EL3
stack pointers for determining the type of exception, managing general
purpose and system register context on exception entry/exit, and handling
SMCs. SMCs are directed to the correct EL3 runtime service.
- Added support for a Test Secure-EL1 Payload (TSP) and a corresponding
Dispatcher (TSPD), which is loaded as an EL3 runtime service. The TSPD
implements Secure Monitor functionality such as world switching and
EL1 context management, and is responsible for communication with the TSP.
NOTE: The TSPD does not yet contain support for secure world interrupts.
NOTE: The TSP/TSPD is not built by default.
Issues resolved since last release
----------------------------------
- Support has been added for switching context between secure and normal
worlds in EL3.
- PSCI API calls ``AFFINITY_INFO`` & ``PSCI_VERSION`` have now been tested (to
a limited extent).
- The ARM Trusted Firmware build artifacts are now placed in the ``./build``
directory and sub-directories instead of being placed in the root of the
project.
- The ARM Trusted Firmware is now free from build warnings. Build warnings
are now treated as errors.
- The ARM Trusted Firmware now provides C library support locally within the
project to maintain compatibility between toolchains/systems.
- The PSCI locking code has been reworked so it no longer takes locks in an
incorrect sequence.
- 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
version 3.13) used in this release, for both Foundation and Base FVPs.
Known issues
------------
The following is a list of issues which are expected to be fixed in the future
releases of the ARM Trusted Firmware.
- The TrustZone Address Space Controller (TZC-400) is not being programmed
yet. Use of model parameter ``-C bp.secure_memory=1`` is not supported.
- No support yet for secure world interrupt handling.
- GICv3 support is experimental. The Linux kernel patches to support this are
not widely available. There are known issues with GICv3 initialization in
the ARM Trusted Firmware.
- Dynamic image loading is not available yet. The current image loader
implementation (used to load BL2 and all subsequent images) has some
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.
- The ARM Trusted Firmware uses too much on-chip Trusted SRAM. Currently the
Test Secure-EL1 Payload (BL3-2) executes in Trusted DRAM since there is not
enough SRAM. A number of RAM usage enhancements have been identified to
rectify this situation.
- 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
of writing.
- Various bugs in ARM Trusted Firmware, UEFI and the Linux kernel have been
observed when using Linaro toolchain versions later than 13.11. Although
most of these have been fixed, some remain at the time of writing. These
mainly seem to relate to a subtle change in the way the compiler converts
between 64-bit and 32-bit values (e.g. during casting operations), which
reveals previously hidden bugs in client code.
- The tested filesystem used for this release (Linaro AArch64 OpenEmbedded
14.01) does not report progress correctly in the console. It only seems to
produce error output, not standard output. It otherwise appears to function
correctly. Other filesystem versions on the same software stack do not
exhibit the problem.
- 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
required in a platform port. Also, dependency checking in the Makefile is
flawed.
- The firmware design documentation for the Test Secure-EL1 Payload (TSP) and
its dispatcher (TSPD) is incomplete. Similarly for the PSCI section.
ARM Trusted Firmware - version 0.2
==================================
New features
------------
- First source release.
- Code for the PSCI suspend feature is supplied, although this is not enabled
by default since there are known issues (see below).
Issues resolved since last release
----------------------------------
- The "psci" nodes in the FDTs provided in this release now fully comply
with the recommendations made in the PSCI specification.
Known issues
------------
The following is a list of issues which are expected to be fixed in the future
releases of the ARM Trusted Firmware.
- The TrustZone Address Space Controller (TZC-400) is not being programmed
yet. Use of model parameter ``-C bp.secure_memory=1`` is not supported.
- No support yet for secure world interrupt handling or for switching context
between secure and normal worlds in EL3.
- GICv3 support is experimental. The Linux kernel patches to support this are
not widely available. There are known issues with GICv3 initialization in
the ARM Trusted Firmware.
- Dynamic image loading is not available yet. The current image loader
implementation (used to load BL2 and all subsequent images) has some
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.
- Although support for PSCI ``CPU_SUSPEND`` is present, it is not yet stable
and ready for use.
- PSCI API calls ``AFFINITY_INFO`` & ``PSCI_VERSION`` are implemented but have not
been tested.
- The ARM Trusted Firmware make files result in all build artifacts being
placed in the root of the project. These should be placed in appropriate
sub-directories.
- The compilation of ARM Trusted Firmware is not free from compilation
warnings. Some of these warnings have not been investigated yet so they
could mask real bugs.
- The ARM Trusted Firmware currently uses toolchain/system include files like
stdio.h. It should provide versions of these within the project to maintain
compatibility between toolchains/systems.
- The PSCI code takes some locks in an incorrect sequence. This may cause
problems with suspend and hotplug in certain conditions.
- 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
a RAM-disk. It fails to execute user-space ``init`` from the RAM-disk. As an
alternative, the VirtioBlock mechanism can be used to provide a file-system
to the kernel.
--------------
*Copyright (c) 2013-2016, ARM Limited and Contributors. All rights reserved.*
.. _PSCI Integration Guide: psci-lib-integration-guide.rst
.. _Developer Certificate of Origin: ../dco.txt
.. _Contribution Guide: ../contributing.rst
.. _Authentication framework: auth-framework.rst
.. _Firmware Update: firmware-update.rst
.. _TF Reset Design: reset-design.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
.. _Authentication Framework: auth-framework.rst
.. _OP-TEE Dispatcher: optee-dispatcher.rst
docs/cpu-specific-build-macros.md deleted 100644 → 0
View file @ aa5b843f
ARM CPU Specific Build Macros
=============================
Contents
--------
1. [Introduction](#1--introduction)
2. [CPU Errata Workarounds](#2--cpu-errata-workarounds)
3. [CPU Specific optimizations](#3--cpu-specific-optimizations)
1. Introduction
----------------
This document describes the various build options present in the CPU specific
operations framework to enable errata workarounds and to enable optimizations
for a specific CPU on a platform.
2. CPU Errata Workarounds
--------------------------
ARM Trusted Firmware exports a series of build flags which control the
errata workarounds that are applied to each CPU by the reset handler. The
errata details can be found in the CPU specific errata documents published
by ARM:
* [Cortex-A53 MPCore Software Developers Errata Notice][A53 Errata Notice]
* [Cortex-A57 MPCore Software Developers Errata Notice][A57 Errata Notice]
The errata workarounds are implemented for a particular revision or a set of
processor revisions. This is checked by the reset handler at runtime. Each
errata workaround is identified by its `ID` as specified in the processor's
errata notice document. The format of the define used to enable/disable the
errata workaround is `ERRATA_<Processor name>_<ID>`, where the `Processor name`
is for example `A57` for the `Cortex_A57` CPU.
Refer to the section _CPU errata status reporting_ in [Firmware Design
guide][Firmware Design] for information on to write errata workaround functions.
All workarounds are disabled by default. The platform is responsible for
enabling these workarounds according to its requirement by defining the
errata workaround build flags in the platform specific makefile. In case
these workarounds are enabled for the wrong CPU revision then the errata
workaround is not applied. In the DEBUG build, this is indicated by
printing a warning to the crash console.
In the current implementation, a platform which has more than 1 variant
with different revisions of a processor has no runtime mechanism available
for it to specify which errata workarounds should be enabled or not.
The value of the build flags are 0 by default, that is, disabled. Any other
value will enable it.
For Cortex-A53, following errata build flags are defined :
* `ERRATA_A53_826319`: This applies errata 826319 workaround to Cortex-A53
CPU. This needs to be enabled only for revision <= r0p2 of the CPU.
* `ERRATA_A53_836870`: This applies errata 836870 workaround to Cortex-A53
CPU. This needs to be enabled only for revision <= r0p3 of the CPU. From
r0p4 and onwards, this errata is enabled by default in hardware.
* `ERRATA_A53_855873`: This applies errata 855873 workaround to Cortex-A53
CPUs. Though the erratum is present in every revision of the CPU,
this workaround is only applied to CPUs from r0p3 onwards, which feature
a chicken bit in CPUACTLR_EL1 to enable a hardware workaround.
Earlier revisions of the CPU have other errata which require the same
workaround in software, so they should be covered anyway.
For Cortex-A57, following errata build flags are defined :
* `ERRATA_A57_806969`: This applies errata 806969 workaround to Cortex-A57
CPU. This needs to be enabled only for revision r0p0 of the CPU.
* `ERRATA_A57_813419`: This applies errata 813419 workaround to Cortex-A57
CPU. This needs to be enabled only for revision r0p0 of the CPU.
* `ERRATA_A57_813420`: This applies errata 813420 workaround to Cortex-A57
CPU. This needs to be enabled only for revision r0p0 of the CPU.
* `ERRATA_A57_826974`: This applies errata 826974 workaround to Cortex-A57
CPU. This needs to be enabled only for revision <= r1p1 of the CPU.
* `ERRATA_A57_826977`: This applies errata 826977 workaround to Cortex-A57
CPU. This needs to be enabled only for revision <= r1p1 of the CPU.
* `ERRATA_A57_828024`: This applies errata 828024 workaround to Cortex-A57
CPU. This needs to be enabled only for revision <= r1p1 of the CPU.
* `ERRATA_A57_829520`: This applies errata 829520 workaround to Cortex-A57
CPU. This needs to be enabled only for revision <= r1p2 of the CPU.
* `ERRATA_A57_833471`: This applies errata 833471 workaround to Cortex-A57
CPU. This needs to be enabled only for revision <= r1p2 of the CPU.
3. CPU Specific optimizations
------------------------------
This section describes some of the optimizations allowed by the CPU micro
architecture that can be enabled by the platform as desired.
* `SKIP_A57_L1_FLUSH_PWR_DWN`: This flag enables an optimization in the
Cortex-A57 cluster power down sequence by not flushing the Level 1 data
cache. The L1 data cache and the L2 unified cache are inclusive. A flush
of the L2 by set/way flushes any dirty lines from the L1 as well. This
is a known safe deviation from the Cortex-A57 TRM defined power down
sequence. Each Cortex-A57 based platform must make its own decision on
whether to use the optimization.
* `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
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
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
flag enforces this behaviour. This needs to be enabled only for revisions
<= r0p3 of the CPU and is enabled by default.
* `A57_DISABLE_NON_TEMPORAL_HINT`: This flag has the same behaviour as
`A53_DISABLE_NON_TEMPORAL_HINT` but for Cortex-A57. This needs to be
enabled only for revisions <= r1p2 of the CPU and is enabled by default,
as recommended in section "4.7 Non-Temporal Loads/Stores" of the
[Cortex-A57 Software Optimization Guide][A57 SW Optimization Guide].
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
_Copyright (c) 2014-2016, ARM Limited and Contributors. All rights reserved._
[A57 SW Optimization Guide]: http://infocenter.arm.com/help/topic/com.arm.doc.uan0015b/Cortex_A57_Software_Optimization_Guide_external.pdf
[A53 Errata Notice]: http://infocenter.arm.com/help/topic/com.arm.doc.epm048406/index.html
[A57 Errata Notice]: http://infocenter.arm.com/help/topic/com.arm.doc.epm049219/cortex_a57_mpcore_software_developers_errata_notice.pdf
[Firmware Design]: firmware-design.md
docs/cpu-specific-build-macros.rst 0 → 100644
View file @ 7cefb56d
ARM CPU Specific Build Macros
=============================
.. section-numbering::
:suffix: .
.. contents::
This document describes the various build options present in the CPU specific
operations framework to enable errata workarounds and to enable optimizations
for a specific CPU on a platform.
CPU Errata Workarounds
----------------------
ARM Trusted Firmware exports a series of build flags which control the
errata workarounds that are applied to each CPU by the reset handler. The
errata details can be found in the CPU specific errata documents published
by ARM:
- `Cortex-A53 MPCore Software Developers Errata Notice`_
- `Cortex-A57 MPCore Software Developers Errata Notice`_
The errata workarounds are implemented for a particular revision or a set of
processor revisions. This is checked by the reset handler at runtime. Each
errata workaround is identified by its ``ID`` as specified in the processor's
errata notice document. The format of the define used to enable/disable the
errata workaround is ``ERRATA_<Processor name>_<ID>``, where the ``Processor name``
is for example ``A57`` for the ``Cortex_A57`` CPU.
Refer to the section *CPU errata status reporting* in
`Firmware Design guide`_ for information on to write errata workaround functions.
All workarounds are disabled by default. The platform is responsible for
enabling these workarounds according to its requirement by defining the
errata workaround build flags in the platform specific makefile. In case
these workarounds are enabled for the wrong CPU revision then the errata
workaround is not applied. In the DEBUG build, this is indicated by
printing a warning to the crash console.
In the current implementation, a platform which has more than 1 variant
with different revisions of a processor has no runtime mechanism available
for it to specify which errata workarounds should be enabled or not.
The value of the build flags are 0 by default, that is, disabled. Any other
value will enable it.
For Cortex-A53, following errata build flags are defined :
- ``ERRATA_A53_826319``: This applies errata 826319 workaround to Cortex-A53
CPU. This needs to be enabled only for revision <= r0p2 of the CPU.
- ``ERRATA_A53_836870``: This applies errata 836870 workaround to Cortex-A53
CPU. This needs to be enabled only for revision <= r0p3 of the CPU. From
r0p4 and onwards, this errata is enabled by default in hardware.
- ``ERRATA_A53_855873``: This applies errata 855873 workaround to Cortex-A53
CPUs. Though the erratum is present in every revision of the CPU,
this workaround is only applied to CPUs from r0p3 onwards, which feature
a chicken bit in CPUACTLR\_EL1 to enable a hardware workaround.
Earlier revisions of the CPU have other errata which require the same
workaround in software, so they should be covered anyway.
For Cortex-A57, following errata build flags are defined :
- ``ERRATA_A57_806969``: This applies errata 806969 workaround to Cortex-A57
CPU. This needs to be enabled only for revision r0p0 of the CPU.
- ``ERRATA_A57_813419``: This applies errata 813419 workaround to Cortex-A57
CPU. This needs to be enabled only for revision r0p0 of the CPU.
- ``ERRATA_A57_813420``: This applies errata 813420 workaround to Cortex-A57
CPU. This needs to be enabled only for revision r0p0 of the CPU.
- ``ERRATA_A57_826974``: This applies errata 826974 workaround to Cortex-A57
CPU. This needs to be enabled only for revision <= r1p1 of the CPU.
- ``ERRATA_A57_826977``: This applies errata 826977 workaround to Cortex-A57
CPU. This needs to be enabled only for revision <= r1p1 of the CPU.
- ``ERRATA_A57_828024``: This applies errata 828024 workaround to Cortex-A57
CPU. This needs to be enabled only for revision <= r1p1 of the CPU.
- ``ERRATA_A57_829520``: This applies errata 829520 workaround to Cortex-A57
CPU. This needs to be enabled only for revision <= r1p2 of the CPU.
- ``ERRATA_A57_833471``: This applies errata 833471 workaround to Cortex-A57
CPU. This needs to be enabled only for revision <= r1p2 of the CPU.
CPU Specific optimizations
--------------------------
This section describes some of the optimizations allowed by the CPU micro
architecture that can be enabled by the platform as desired.
- ``SKIP_A57_L1_FLUSH_PWR_DWN``: This flag enables an optimization in the
Cortex-A57 cluster power down sequence by not flushing the Level 1 data
cache. The L1 data cache and the L2 unified cache are inclusive. A flush
of the L2 by set/way flushes any dirty lines from the L1 as well. This
is a known safe deviation from the Cortex-A57 TRM defined power down
sequence. Each Cortex-A57 based platform must make its own decision on
whether to use the optimization.
- ``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
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
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
flag enforces this behaviour. This needs to be enabled only for revisions
<= r0p3 of the CPU and is enabled by default.
- ``A57_DISABLE_NON_TEMPORAL_HINT``: This flag has the same behaviour as
``A53_DISABLE_NON_TEMPORAL_HINT`` but for Cortex-A57. This needs to be
enabled only for revisions <= r1p2 of the CPU and is enabled by default,
as recommended in section "4.7 Non-Temporal Loads/Stores" of the
`Cortex-A57 Software Optimization Guide`_.
--------------
*Copyright (c) 2014-2016, ARM Limited and Contributors. All rights reserved.*
.. _Cortex-A53 MPCore Software Developers Errata Notice: http://infocenter.arm.com/help/topic/com.arm.doc.epm048406/index.html
.. _Cortex-A57 MPCore Software Developers Errata Notice: http://infocenter.arm.com/help/topic/com.arm.doc.epm049219/cortex_a57_mpcore_software_developers_errata_notice.pdf
.. _Firmware Design guide: firmware-design.rst
.. _Cortex-A57 Software Optimization Guide: http://infocenter.arm.com/help/topic/com.arm.doc.uan0015b/Cortex_A57_Software_Optimization_Guide_external.pdf
docs/firmware-design.md → docs/firmware-design.rst
View file @ 7cefb56d
ARM Trusted Firmware Design
===========================
Contents :
1. [Introduction](#1--introduction)
2. [Cold boot](#2--cold-boot)
3. [EL3 runtime services framework](#3--el3-runtime-services-framework)
4. [Power State Coordination Interface](#4--power-state-coordination-interface)
5. [Secure-EL1 Payloads and Dispatchers](#5--secure-el1-payloads-and-dispatchers)
6. [Crash Reporting in BL31](#6--crash-reporting-in-bl31)
7. [Guidelines for Reset Handlers](#7--guidelines-for-reset-handlers)
8. [CPU specific operations framework](#8--cpu-specific-operations-framework)
9. [Memory layout of BL images](#9-memory-layout-of-bl-images)
10. [Firmware Image Package (FIP)](#10--firmware-image-package-fip)
11. [Use of coherent memory in Trusted Firmware](#11--use-of-coherent-memory-in-trusted-firmware)
12. [Isolating code and read-only data on separate memory pages](#12--isolating-code-and-read-only-data-on-separate-memory-pages)
13. [Performance Measurement Framework](#13--performance-measurement-framework)
14. [ARMv8 Architecture Extensions](#14--armv8-architecture-extensions)
15. [Code Structure](#15--code-structure)
16. [References](#16--references)
1. Introduction
----------------
.. section-numbering::
:suffix: .
.. contents::
The ARM Trusted Firmware 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
to the stage where it hands-off control to firmware running in the normal
world in DRAM. This is the cold boot path.
The ARM Trusted Firmware also implements the Power State Coordination Interface
([PSCI]) PDD [2] as a runtime service. PSCI is the interface from normal world
software to firmware implementing power management use-cases (for example,
secondary CPU boot, hotplug and idle). Normal world software can access ARM
Trusted Firmware runtime services via the ARM SMC (Secure Monitor Call)
instruction. The SMC instruction must be used as mandated by the [SMC Calling
Convention PDD][SMCCC] [3].
PDD [2]_ as a runtime service. PSCI is the interface from normal world software
to firmware implementing power management use-cases (for example, secondary CPU
boot, hotplug and idle). Normal world software can access ARM Trusted Firmware
runtime services via the ARM SMC (Secure Monitor Call) instruction. The SMC
instruction must be used as mandated by the SMC Calling Convention [3]_.
The ARM Trusted Firmware implements a framework for configuring and managing
interrupts generated in either security state. The details of the interrupt
management framework and its design can be found in [ARM Trusted
Firmware Interrupt Management Design guide][INTRG] [4].
management framework and its design can be found in ARM Trusted Firmware
Interrupt Management Design guide [4]_.
The ARM Trusted Firmware can be built to support either AArch64 or AArch32
execution state.
2. Cold boot
-------------
Cold boot
---------
The cold boot path starts when the platform is physically turned on. If
`COLD_BOOT_SINGLE_CPU=0`, one of the CPUs released from reset is chosen as the
``COLD_BOOT_SINGLE_CPU=0``, one of the CPUs released from reset is chosen as the
primary CPU, and the remaining CPUs are considered secondary CPUs. The primary
CPU is chosen through platform-specific means. The cold boot path is mainly
executed by the primary CPU, other than essential CPU initialization executed by
all CPUs. The secondary CPUs are kept in a safe platform-specific state until
the primary CPU has performed enough initialization to boot them.
Refer to the [Reset Design] for more information on the effect of the
`COLD_BOOT_SINGLE_CPU` platform build option.
Refer to the `Reset Design`_ for more information on the effect of the
``COLD_BOOT_SINGLE_CPU`` platform build option.
The cold boot path in this implementation of the ARM Trusted Firmware,
depends on the execution state.
For AArch64, it is divided into five steps (in order of execution):
* Boot Loader stage 1 (BL1) _AP Trusted ROM_
* Boot Loader stage 2 (BL2) _Trusted Boot Firmware_
* Boot Loader stage 3-1 (BL31) _EL3 Runtime Software_
* Boot Loader stage 3-2 (BL32) _Secure-EL1 Payload_ (optional)
* Boot Loader stage 3-3 (BL33) _Non-trusted Firmware_
- Boot Loader stage 1 (BL1) *AP Trusted ROM*
- Boot Loader stage 2 (BL2) *Trusted Boot Firmware*
- Boot Loader stage 3-1 (BL31) *EL3 Runtime Software*
- Boot Loader stage 3-2 (BL32) *Secure-EL1 Payload* (optional)
- Boot Loader stage 3-3 (BL33) *Non-trusted Firmware*
For AArch32, it is divided into four steps (in order of execution):
* Boot Loader stage 1 (BL1) _AP Trusted ROM_
* Boot Loader stage 2 (BL2) _Trusted Boot Firmware_
* Boot Loader stage 3-2 (BL32) _EL3 Runtime Software_
* Boot Loader stage 3-3 (BL33) _Non-trusted Firmware_
- Boot Loader stage 1 (BL1) *AP Trusted ROM*
- Boot Loader stage 2 (BL2) *Trusted Boot Firmware*
- Boot Loader stage 3-2 (BL32) *EL3 Runtime Software*
- Boot Loader stage 3-3 (BL33) *Non-trusted Firmware*
ARM development platforms (Fixed Virtual Platforms (FVPs) and Juno) implement a
combination of the following types of memory regions. Each bootloader stage uses
one or more of these memory regions.
* Regions accessible from both non-secure and secure states. For example,
- Regions accessible from both non-secure and secure states. For example,
non-trusted SRAM, ROM and DRAM.
* Regions accessible from only the secure state. For example, trusted SRAM and
- Regions accessible from only the secure state. For example, trusted SRAM and
ROM. The FVPs also implement the trusted DRAM which is statically
configured. Additionally, the Base FVPs and Juno development platform
configure the TrustZone Controller (TZC) to create a region in the DRAM
which is accessible only from the secure state.
The sections below provide the following details:
* initialization and execution of the first three stages during cold boot
* specification of the EL3 Runtime Software (BL31 for AArch64 and BL32 for
- initialization and execution of the first three stages during cold boot
- specification of the EL3 Runtime Software (BL31 for AArch64 and BL32 for
AArch32) entrypoint requirements for use by alternative Trusted Boot
Firmware in place of the provided BL1 and BL2
### BL1
BL1
~~~
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.
The BL1 data section is copied to trusted SRAM at runtime.
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
to the top of trusted SRAM as defined by the constant `BL1_RW_BASE`.
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``.
The functionality implemented by this stage is as follows.
#### Determination of boot path
Determination of boot path
^^^^^^^^^^^^^^^^^^^^^^^^^^
Whenever a CPU is released from reset, BL1 needs to distinguish between a warm
boot and a cold boot. This is done using platform-specific mechanisms (see the
`plat_get_my_entrypoint()` function in the [Porting Guide]). In the case of a
``plat_get_my_entrypoint()`` function in the `Porting Guide`_). In the case of a
warm boot, a CPU is expected to continue execution from a separate
entrypoint. In the case of a cold boot, the secondary CPUs are placed in a safe
platform-specific state (see the `plat_secondary_cold_boot_setup()` function in
the [Porting Guide]) while the primary CPU executes the remaining cold boot path
platform-specific state (see the ``plat_secondary_cold_boot_setup()`` function in
the `Porting Guide`_) while the primary CPU executes the remaining cold boot path
as described in the following sections.
This step only applies when `PROGRAMMABLE_RESET_ADDRESS=0`. Refer to the
[Reset Design] for more information on the effect of the
`PROGRAMMABLE_RESET_ADDRESS` platform build option.
This step only applies when ``PROGRAMMABLE_RESET_ADDRESS=0``. Refer to the
`Reset Design`_ for more information on the effect of the
``PROGRAMMABLE_RESET_ADDRESS`` platform build option.
#### Architectural initialization
Architectural initialization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
BL1 performs minimal architectural initialization as follows.
* Exception vectors
- Exception vectors
BL1 sets up simple exception vectors for both synchronous and asynchronous
exceptions. The default behavior upon receiving an exception is to populate
a status code in the general purpose register `X0/R0` and call the
`plat_report_exception()` function (see the [Porting Guide]). The status
a status code in the general purpose register ``X0/R0`` and call the
``plat_report_exception()`` function (see the `Porting Guide`_). The status
code is one of:
For AArch64:
::
0x0 : Synchronous exception from Current EL with SP_EL0
0x1 : IRQ exception from Current EL with SP_EL0
0x2 : FIQ exception from Current EL with SP_EL0
......@@ -158,6 +143,8 @@ BL1 performs minimal architectural initialization as follows.
For AArch32:
::
0x10 : User mode
0x11 : FIQ mode
0x12 : IRQ mode
......@@ -168,10 +155,12 @@ BL1 performs minimal architectural initialization as follows.
0x1b : Undefined 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
indicate the occurence of an unexpected exception:
::
SYS_LED[0] - Security state (Secure=0/Non-Secure=1)
SYS_LED[2:1] - Exception Level (EL3=0x3, EL2=0x2, EL1=0x1, EL0=0x0)
For AArch32 it is always 0x0
......@@ -184,115 +173,125 @@ BL1 performs minimal architectural initialization as follows.
BL1 does not expect to receive any exceptions other than the SMC exception.
For the latter, BL1 installs a simple stub. The stub expects to receive a
limited set of SMC types (determined by their function IDs in the general
purpose register `X0/R0`):
- `BL1_SMC_RUN_IMAGE`: This SMC is raised by BL2 to make BL1 pass control
purpose register ``X0/R0``):
- ``BL1_SMC_RUN_IMAGE``: This SMC is raised by BL2 to make BL1 pass control
to EL3 Runtime Software.
- All SMCs listed in section "BL1 SMC Interface" in the [Firmware Update]
- All SMCs listed in section "BL1 SMC Interface" in the `Firmware Update`_
Design Guide are supported for AArch64 only. These SMCs are currently
not supported when BL1 is built for AArch32.
Any other SMC leads to an assertion failure.
* CPU initialization
- CPU initialization
BL1 calls the `reset_handler()` function which in turn calls the CPU
BL1 calls the ``reset_handler()`` function which in turn calls the CPU
specific reset handler function (see the section: "CPU specific operations
framework").
* Control register setup (for AArch64)
- `SCTLR_EL3`. Instruction cache is enabled by setting the `SCTLR_EL3.I`
- Control register setup (for AArch64)
- ``SCTLR_EL3``. Instruction cache is enabled by setting the ``SCTLR_EL3.I``
bit. Alignment and stack alignment checking is enabled by setting the
`SCTLR_EL3.A` and `SCTLR_EL3.SA` bits. Exception endianness is set to
little-endian by clearing the `SCTLR_EL3.EE` bit.
``SCTLR_EL3.A`` and ``SCTLR_EL3.SA`` bits. Exception endianness is set to
little-endian by clearing the ``SCTLR_EL3.EE`` bit.
- `SCR_EL3`. The register width of the next lower exception level is set
to AArch64 by setting the `SCR.RW` bit. The `SCR.EA` bit is set to trap
both External Aborts and SError Interrupts in EL3. The `SCR.SIF` bit is
- ``SCR_EL3``. The register width of the next lower exception level is set
to AArch64 by setting the ``SCR.RW`` bit. The ``SCR.EA`` bit is set to trap
both External Aborts and SError Interrupts in EL3. The ``SCR.SIF`` bit is
also set to disable instruction fetches from Non-secure memory when in
secure state.
- `CPTR_EL3`. Accesses to the `CPACR_EL1` register from EL1 or EL2, or the
`CPTR_EL2` register from EL2 are configured to not trap to EL3 by
clearing the `CPTR_EL3.TCPAC` bit. Access to the trace functionality is
configured not to trap to EL3 by clearing the `CPTR_EL3.TTA` bit.
- ``CPTR_EL3``. Accesses to the ``CPACR_EL1`` register from EL1 or EL2, or the
``CPTR_EL2`` register from EL2 are configured to not trap to EL3 by
clearing the ``CPTR_EL3.TCPAC`` bit. Access to the trace functionality is
configured not to trap to EL3 by clearing the ``CPTR_EL3.TTA`` bit.
Instructions that access the registers associated with Floating Point
and Advanced SIMD execution are configured to not trap to EL3 by
clearing the `CPTR_EL3.TFP` bit.
clearing the ``CPTR_EL3.TFP`` bit.
- `DAIF`. The SError interrupt is enabled by clearing the SError interrupt
- ``DAIF``. The SError interrupt is enabled by clearing the SError interrupt
mask bit.
- `MDCR_EL3`. The trap controls, `MDCR_EL3.TDOSA`, `MDCR_EL3.TDA` and
`MDCR_EL3.TPM`, are set so that accesses to the registers they control
- ``MDCR_EL3``. The trap controls, ``MDCR_EL3.TDOSA``, ``MDCR_EL3.TDA`` and
``MDCR_EL3.TPM``, are set so that accesses to the registers they control
do not trap to EL3. AArch64 Secure self-hosted debug is disabled by
setting the `MDCR_EL3.SDD` bit. Also `MDCR_EL3.SPD32` is set to
setting the ``MDCR_EL3.SDD`` bit. Also ``MDCR_EL3.SPD32`` is set to
disable AArch32 Secure self-hosted privileged debug from S-EL1.
* Control register setup (for AArch32)
- `SCTLR`. Instruction cache is enabled by setting the `SCTLR.I` bit.
Alignment checking is enabled by setting the `SCTLR.A` bit.
- Control register setup (for AArch32)
- ``SCTLR``. Instruction cache is enabled by setting the ``SCTLR.I`` bit.
Alignment checking is enabled by setting the ``SCTLR.A`` bit.
Exception endianness is set to little-endian by clearing the
`SCTLR.EE` bit.
``SCTLR.EE`` bit.
- `SCR`. The `SCR.SIF` bit is set to disable instruction fetches from
- ``SCR``. The ``SCR.SIF`` bit is set to disable instruction fetches from
Non-secure memory when in secure state.
- `CPACR`. Allow execution of Advanced SIMD instructions at PL0 and PL1,
by clearing the `CPACR.ASEDIS` bit. Access to the trace functionality
- ``CPACR``. Allow execution of Advanced SIMD instructions at PL0 and PL1,
by clearing the ``CPACR.ASEDIS`` bit. Access to the trace functionality
is configured not to trap to undefined mode by clearing the
`CPACR.TRCDIS` bit.
``CPACR.TRCDIS`` bit.
- `NSACR`. Enable non-secure access to Advanced SIMD functionality and
- ``NSACR``. Enable non-secure access to Advanced SIMD functionality and
system register access to implemented trace registers.
- `FPEXC`. Enable access to the Advanced SIMD and floating-point
- ``FPEXC``. Enable access to the Advanced SIMD and floating-point
functionality from all Exception levels.
- `CPSR.A`. The Asynchronous data abort interrupt is enabled by clearing
- ``CPSR.A``. The Asynchronous data abort interrupt is enabled by clearing
the Asynchronous data abort interrupt mask bit.
- `SDCR`. The `SDCR.SPD` field is set to disable AArch32 Secure
- ``SDCR``. The ``SDCR.SPD`` field is set to disable AArch32 Secure
self-hosted privileged debug.
#### Platform initialization
Platform initialization
^^^^^^^^^^^^^^^^^^^^^^^
On ARM platforms, BL1 performs the following platform initializations:
* Enable the Trusted Watchdog.
* Initialize the console.
* Configure the Interconnect to enable hardware coherency.
* Enable the MMU and map the memory it needs to access.
* Configure any required platform storage to load the next bootloader image
- Enable the Trusted Watchdog.
- Initialize the console.
- Configure the Interconnect to enable hardware coherency.
- Enable the MMU and map the memory it needs to access.
- Configure any required platform storage to load the next bootloader image
(BL2).
#### Firmware Update detection and execution
Firmware Update detection and execution
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
After performing platform setup, BL1 common code calls
`bl1_plat_get_next_image_id()` to determine if [Firmware Update] is required or
``bl1_plat_get_next_image_id()`` to determine if `Firmware Update`_ is required or
to proceed with the normal boot process. If the platform code returns
`BL2_IMAGE_ID` then the normal boot sequence is executed as described in the
next section, else BL1 assumes that [Firmware Update] is required and execution
passes to the first image in the [Firmware Update] process. In either case, BL1
retrieves a descriptor of the next image by calling `bl1_plat_get_image_desc()`.
The image descriptor contains an `entry_point_info_t` structure, which BL1
``BL2_IMAGE_ID`` then the normal boot sequence is executed as described in the
next section, else BL1 assumes that `Firmware Update`_ is required and execution
passes to the first image in the `Firmware Update`_ process. In either case, BL1
retrieves a descriptor of the next image by calling ``bl1_plat_get_image_desc()``.
The image descriptor contains an ``entry_point_info_t`` structure, which BL1
uses to initialize the execution state of the next image.
#### BL2 image load and execution
BL2 image load and execution
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In the normal boot flow, BL1 execution continues as follows:
1. BL1 prints the following string from the primary CPU to indicate successful
#. BL1 prints the following string from the primary CPU to indicate successful
execution of the BL1 stage:
::
"Booting Trusted Firmware"
2. BL1 determines the amount of free trusted SRAM memory available by
#. BL1 determines the amount of free trusted SRAM memory available by
calculating the extent of its own data section, which also resides in
trusted SRAM. BL1 loads a BL2 raw binary image from platform storage, at a
platform-specific base address. If the BL2 image file is not present or if
there is not enough free trusted SRAM the following error message is
printed:
::
"Failed to load BL2 firmware."
BL1 calculates the amount of Trusted SRAM that can be used by the BL2
......@@ -300,122 +299,131 @@ In the normal boot flow, BL1 execution continues as follows:
in the platform header. Further description of the memory layout can be
found later in this document.
3. BL1 passes control to the BL2 image at Secure EL1 (for AArch64) or at
#. BL1 passes control to the BL2 image at Secure EL1 (for AArch64) or at
Secure SVC mode (for AArch32), starting from its load address.
4. BL1 also passes information about the amount of trusted SRAM used and
#. BL1 also passes information about the amount of trusted SRAM used and
available for use. This information is populated at a platform-specific
memory address.
### BL2
BL2
~~~
BL1 loads and passes control to BL2 at Secure-EL1 (for AArch64) or at Secure
SVC mode (for AArch32) . BL2 is linked against and loaded at a platform-specific
base address (more information can be found later in this document).
The functionality implemented by BL2 is as follows.
#### Architectural initialization
Architectural initialization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
For AArch64, BL2 performs the minimal architectural initialization required
for subsequent stages of the ARM Trusted Firmware and normal world software.
EL1 and EL0 are given access to Floating Point and Advanced SIMD registers
by clearing the `CPACR.FPEN` bits.
by clearing the ``CPACR.FPEN`` bits.
For AArch32, the minimal architectural initialization required for subsequent
stages of the ARM Trusted Firmware and normal world software is taken care of
in BL1 as both BL1 and BL2 execute at PL1.
#### Platform initialization
Platform initialization
^^^^^^^^^^^^^^^^^^^^^^^
On ARM platforms, BL2 performs the following platform initializations:
* Initialize the console.
* Configure any required platform storage to allow loading further bootloader
- Initialize the console.
- Configure any required platform storage to allow loading further bootloader
images.
* Enable the MMU and map the memory it needs to access.
* Perform platform security setup to allow access to controlled components.
* Reserve some memory for passing information to the next bootloader image
- Enable the MMU and map the memory it needs to access.
- Perform platform security setup to allow access to controlled components.
- Reserve some memory for passing information to the next bootloader image
EL3 Runtime Software and populate it.
* Define the extents of memory available for loading each subsequent
- Define the extents of memory available for loading each subsequent
bootloader image.
#### Image loading in BL2
Image loading in BL2
^^^^^^^^^^^^^^^^^^^^
Image loading scheme in BL2 depends on `LOAD_IMAGE_V2` build option. If the
Image loading scheme in BL2 depends on ``LOAD_IMAGE_V2`` build option. If the
flag is disabled, the BLxx images are loaded, by calling the respective
load_blxx() function from BL2 generic code. If the flag is enabled, the BL2
load\_blxx() function from BL2 generic code. If the flag is enabled, the BL2
generic code loads the images based on the list of loadable images provided
by the platform. BL2 passes the list of executable images provided by the
platform to the next handover BL image. By default, this flag is disabled for
AArch64 and the AArch32 build is supported only if this flag is enabled.
#### SCP_BL2 (System Control Processor Firmware) image load
SCP\_BL2 (System Control Processor Firmware) image load
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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
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
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)
for BL2 execution to continue.
#### EL3 Runtime Software image load
EL3 Runtime Software image load
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
BL2 loads the EL3 Runtime Software image from platform storage into a platform-
specific address in trusted SRAM. If there is not enough memory to load the
image or image is missing it leads to an assertion failure. If `LOAD_IMAGE_V2`
image or image is missing it leads to an assertion failure. If ``LOAD_IMAGE_V2``
is disabled and if image loads successfully, BL2 updates the amount of trusted
SRAM used and available for use by EL3 Runtime Software. This information is
populated at a platform-specific memory address.
#### AArch64 BL32 (Secure-EL1 Payload) image load
AArch64 BL32 (Secure-EL1 Payload) image load
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
BL2 loads the optional BL32 image from platform storage into a platform-
specific region of secure memory. The image executes in the secure world. BL2
relies on BL31 to pass control to the BL32 image, if present. Hence, BL2
populates a platform-specific area of memory with the entrypoint/load-address
of the BL32 image. The value of the Saved Processor Status Register (`SPSR`)
of the BL32 image. The value of the Saved Processor Status Register (``SPSR``)
for entry into BL32 is not determined by BL2, it is initialized by the
Secure-EL1 Payload Dispatcher (see later) within BL31, which is responsible for
managing interaction with BL32. This information is passed to BL31.
#### BL33 (Non-trusted Firmware) image load
BL33 (Non-trusted Firmware) image load
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
BL2 loads the BL33 image (e.g. UEFI or other test or boot software) from
platform storage into non-secure memory as defined by the platform.
BL2 relies on EL3 Runtime Software to pass control to BL33 once secure state
initialization is complete. Hence, BL2 populates a platform-specific area of
memory with the entrypoint and Saved Program Status Register (`SPSR`) of the
memory with the entrypoint and Saved Program Status Register (``SPSR``) of the
normal world software image. The entrypoint is the load address of the BL33
image. The `SPSR` is determined as specified in Section 5.13 of the [PSCI PDD]
[PSCI]. This information is passed to the EL3 Runtime Software.
image. The ``SPSR`` is determined as specified in Section 5.13 of the
`PSCI PDD`_. This information is passed to the EL3 Runtime Software.
#### AArch64 BL31 (EL3 Runtime Software) execution
AArch64 BL31 (EL3 Runtime Software) execution
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
BL2 execution continues as follows:
1. BL2 passes control back to BL1 by raising an SMC, providing BL1 with the
#. BL2 passes control back to BL1 by raising an SMC, providing BL1 with the
BL31 entrypoint. The exception is handled by the SMC exception handler
installed by BL1.
2. BL1 turns off the MMU and flushes the caches. It clears the
`SCTLR_EL3.M/I/C` bits, flushes the data cache to the point of coherency
#. BL1 turns off the MMU and flushes the caches. It clears the
``SCTLR_EL3.M/I/C`` bits, flushes the data cache to the point of coherency
and invalidates the TLBs.
3. BL1 passes control to BL31 at the specified entrypoint at EL3.
#. BL1 passes control to BL31 at the specified entrypoint at EL3.
### AArch64 BL31
AArch64 BL31
~~~~~~~~~~~~
The image for this stage is loaded by BL2 and BL1 passes control to BL31 at
EL3. BL31 executes solely in trusted SRAM. BL31 is linked against and
loaded at a platform-specific base address (more information can be found later
in this document). The functionality implemented by BL31 is as follows.
#### Architectural initialization
Architectural initialization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Currently, BL31 performs a similar architectural initialization to BL1 as
far as system register settings are concerned. Since BL1 code resides in ROM,
......@@ -431,35 +439,37 @@ It then replaces the exception vectors populated by BL1 with its own. BL31
exception vectors implement more elaborate support for handling SMCs since this
is the only mechanism to access the runtime services implemented by BL31 (PSCI
for example). BL31 checks each SMC for validity as specified by the
[SMC calling convention PDD][SMCCC] before passing control to the required SMC
`SMC calling convention PDD`_ before passing control to the required SMC
handler routine.
BL31 programs the `CNTFRQ_EL0` register with the clock frequency of the system
BL31 programs the ``CNTFRQ_EL0`` register with the clock frequency of the system
counter, which is provided by the platform.
#### Platform initialization
Platform initialization
^^^^^^^^^^^^^^^^^^^^^^^
BL31 performs detailed platform initialization, which enables normal world
software to function correctly.
On ARM platforms, this consists of the following:
* Initialize the console.
* Configure the Interconnect to enable hardware coherency.
* Enable the MMU and map the memory it needs to access.
* Initialize the generic interrupt controller.
* Initialize the power controller device.
* Detect the system topology.
- Initialize the console.
- Configure the Interconnect to enable hardware coherency.
- Enable the MMU and map the memory it needs to access.
- Initialize the generic interrupt controller.
- Initialize the power controller device.
- Detect the system topology.
#### Runtime services initialization
Runtime services initialization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
BL31 is responsible for initializing the runtime services. One of them is PSCI.
As part of the PSCI initializations, BL31 detects the system topology. It also
initializes the data structures that implement the state machine used to track
the state of power domain nodes. The state can be one of `OFF`, `RUN` or
`RETENTION`. All secondary CPUs are initially in the `OFF` state. The cluster
that the primary CPU belongs to is `ON`; any other cluster is `OFF`. It also
the state of power domain nodes. The state can be one of ``OFF``, ``RUN`` or
``RETENTION``. All secondary CPUs are initially in the ``OFF`` state. The cluster
that the primary CPU belongs to is ``ON``; any other cluster is ``OFF``. It also
initializes the locks that protect them. BL31 accesses the state of a CPU or
cluster immediately after reset and before the data cache is enabled in the
warm boot path. It is not currently possible to use 'exclusive' based spinlocks,
......@@ -471,7 +481,8 @@ detail in the "EL3 runtime services framework" section below.
Details about the status of the PSCI implementation are provided in the
"Power State Coordination Interface" section below.
#### AArch64 BL32 (Secure-EL1 Payload) image initialization
AArch64 BL32 (Secure-EL1 Payload) image initialization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If a BL32 image is present then there must be a matching Secure-EL1 Payload
Dispatcher (SPD) service (see later for details). During initialization
......@@ -483,7 +494,8 @@ is not necessary for AArch32 SPs.
Details on BL32 initialization and the SPD's role are described in the
"Secure-EL1 Payloads and Dispatchers" section below.
#### BL33 (Non-trusted Firmware) execution
BL33 (Non-trusted Firmware) execution
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
EL3 Runtime Software initializes the EL2 or EL1 processor context for normal-
world cold boot, ensuring that no secure state information finds its way into
......@@ -491,7 +503,8 @@ the non-secure execution state. EL3 Runtime Software uses the entrypoint
information provided by BL2 to jump to the Non-trusted firmware image (BL33)
at the highest available Exception Level (EL2 if available, otherwise EL1).
### Using alternative Trusted Boot Firmware in place of BL1 & BL2 (AArch64 only)
Using alternative Trusted Boot Firmware in place of BL1 & BL2 (AArch64 only)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Some platforms have existing implementations of Trusted Boot Firmware that
would like to use ARM Trusted Firmware BL31 for the EL3 Runtime Software. To
......@@ -502,13 +515,16 @@ Future changes to the BL31 interface will be done in a backwards compatible
way, and this enables these firmware components to be independently enhanced/
updated to develop and exploit new functionality.
#### Required CPU state when calling `bl31_entrypoint()` during cold boot
Required CPU state when calling ``bl31_entrypoint()`` during cold boot
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This function must only be called by the primary CPU.
On entry to this function the calling primary CPU must be executing in AArch64
EL3, little-endian data access, and all interrupt sources masked:
::
PSTATE.EL = 3
PSTATE.RW = 1
PSTATE.DAIF = 0xf
......@@ -517,24 +533,27 @@ EL3, little-endian data access, and all interrupt sources masked:
X0 and X1 can be used to pass information from the Trusted Boot Firmware to the
platform code in BL31:
::
X0 : Reserved for common Trusted Firmware 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,
these will be zero filled prior to invoking platform setup code.
##### Use of the X0 and X1 parameters
Use of the X0 and X1 parameters
'''''''''''''''''''''''''''''''
The parameters are platform specific and passed from `bl31_entrypoint()` to
`bl31_early_platform_setup()`. The value of these parameters is never directly
The parameters are platform specific and passed from ``bl31_entrypoint()`` to
``bl31_early_platform_setup()``. The value of these parameters is never directly
used by the common BL31 code.
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
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
platform specific purpose. This convention allows platforms which use ARM
Trusted Firmware's BL1 and BL2 images to transfer additional platform specific
information from Secure Boot without conflicting with future evolution of the
Trusted Firmware using `X0` to pass a `bl31_params` structure.
Trusted Firmware using ``X0`` to pass a ``bl31_params`` structure.
BL31 common and SPD initialization code depends on image and entrypoint
information about BL33 and BL32, which is provided via BL31 platform APIs.
......@@ -546,28 +565,32 @@ 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
BL31 platform code before the caches are enabled.
ARM Trusted Firmware's BL2 implementation passes a `bl31_params` structure in
`X0` and the ARM development platforms interpret this in the BL31 platform
ARM Trusted Firmware's BL2 implementation passes a ``bl31_params`` structure in
``X0`` and the ARM development platforms interpret this in the BL31 platform
code.
##### MMU, Data caches & Coherency
MMU, Data caches & Coherency
''''''''''''''''''''''''''''
BL31 does not depend on the enabled state of the MMU, data caches or
interconnect coherency on entry to `bl31_entrypoint()`. If these are disabled
on entry, these should be enabled during `bl31_plat_arch_setup()`.
interconnect coherency on entry to ``bl31_entrypoint()``. If these are disabled
on entry, these should be enabled during ``bl31_plat_arch_setup()``.
##### Data structures used in the BL31 cold boot interface
Data structures used in the BL31 cold boot interface
''''''''''''''''''''''''''''''''''''''''''''''''''''
These structures are designed to support compatibility and independent
evolution of the structures and the firmware images. For example, a version of
BL31 that can interpret the BL3x image information from different versions of
BL2, a platform that uses an extended entry_point_info structure to convey
BL2, a platform that uses an extended entry\_point\_info structure to convey
additional register information to BL31, or a ELF image loader that can convey
more details about the firmware images.
To support these scenarios the structures are versioned and sized, which enables
BL31 to detect which information is present and respond appropriately. The
`param_header` is defined to capture this information:
``param_header`` is defined to capture this information:
.. code:: c
typedef struct param_header {
uint8_t type; /* type of the structure */
......@@ -576,12 +599,13 @@ BL31 to detect which information is present and respond appropriately. The
uint32_t attr; /* attributes: unused bits SBZ */
} param_header_t;
The structures using this format are `entry_point_info`, `image_info` and
`bl31_params`. The code that allocates and populates these structures must set
the header fields appropriately, and the `SET_PARAM_HEAD()` a macro is defined
The structures using this format are ``entry_point_info``, ``image_info`` and
``bl31_params``. The code that allocates and populates these structures must set
the header fields appropriately, and the ``SET_PARAM_HEAD()`` a macro is defined
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
Firmware provides the platform power management code with a Warm boot
......@@ -590,6 +614,8 @@ reset handler. On entry to the Warm boot initialization function the calling
CPU must be in AArch64 EL3, little-endian data access and all interrupt sources
masked:
::
PSTATE.EL = 3
PSTATE.RW = 1
PSTATE.DAIF = 0xf
......@@ -599,7 +625,8 @@ The PSCI implementation will initialize the processor state and ensure that the
platform power management code is then invoked as required to initialize all
necessary system, cluster and CPU resources.
### AArch32 EL3 Runtime Software entrypoint interface
AArch32 EL3 Runtime Software entrypoint interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To enable this firmware architecture it is important to provide a fully
documented and stable interface between the Trusted Boot Firmware and the
......@@ -609,30 +636,36 @@ Future changes to the entrypoint interface will be done in a backwards
compatible way, and this enables these firmware components to be independently
enhanced/updated to develop and exploit new functionality.
#### Required CPU state when entering during cold boot
Required CPU state when entering during cold boot
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This function must only be called by the primary CPU.
On entry to this function the calling primary CPU must be executing in AArch32
EL3, little-endian data access, and all interrupt sources masked:
::
PSTATE.AIF = 0x7
SCTLR.EE = 0
R0 and R1 are used to pass information from the Trusted Boot Firmware to the
platform code in AArch32 EL3 Runtime Software:
::
R0 : Reserved for common Trusted Firmware information
R1 : Platform specific information
##### Use of the R0 and R1 parameters
Use of the R0 and R1 parameters
'''''''''''''''''''''''''''''''
The parameters are platform specific and the convention is that `R0` conveys
information regarding the BL3x images from the Trusted Boot firmware and `R1`
The parameters are platform specific and the convention is that ``R0`` conveys
information regarding the BL3x images from the Trusted Boot firmware and ``R1``
can be used for other platform specific purpose. This convention allows
platforms which use ARM Trusted Firmware's BL1 and BL2 images to transfer
additional platform specific information from Secure Boot without conflicting
with future evolution of the Trusted Firmware using `R0` to pass a `bl_params`
with future evolution of the Trusted Firmware using ``R0`` to pass a ``bl_params``
structure.
The AArch32 EL3 Runtime Software is responsible for entry into BL33. This
......@@ -644,48 +677,52 @@ 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.
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.
##### MMU, Data caches & Coherency
MMU, Data caches & Coherency
''''''''''''''''''''''''''''
AArch32 EL3 Runtime Software must not depend on the enabled state of the MMU,
data caches or interconnect coherency in its entrypoint. They must be explicitly
enabled if required.
##### Data structures used in cold boot interface
Data structures used in cold boot interface
'''''''''''''''''''''''''''''''''''''''''''
The AArch32 EL3 Runtime Software cold boot interface uses `bl_params` instead
of `bl31_params`. The `bl_params` structure is based on the convention
The AArch32 EL3 Runtime Software cold boot interface uses ``bl_params`` instead
of ``bl31_params``. The ``bl_params`` structure is based on the convention
described in AArch64 BL31 cold boot interface section.
#### Required CPU state for warm boot initialization
Required CPU state for warm boot initialization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When requesting a CPU power-on, or suspending a running CPU, AArch32 EL3
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 ARM Trusted Firmware BL1 is used and the PROGRAMMABLE\_RESET\_ADDRESS build
flag is false, then AArch32 EL3 Runtime Software must ensure that BL1 branches
to the warm 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
data access and all interrupt sources masked:
::
PSTATE.AIF = 0x7
SCTLR.EE = 0
The warm boot entrypoint may be implemented by using the ARM Trusted Firmware
`psci_warmboot_entrypoint()` function. In that case, the platform must fulfil
the pre-requisites mentioned in the [PSCI Library integration guide]
[PSCI Lib guide].
``psci_warmboot_entrypoint()`` function. In that case, the platform must fulfil
the pre-requisites mentioned in the `PSCI Library integration guide`_.
3. EL3 runtime services framework
----------------------------------
EL3 runtime services framework
------------------------------
Software executing in the non-secure state and in the secure state at exception
levels lower than EL3 will request runtime services using the Secure Monitor
Call (SMC) instruction. These requests will follow the convention described in
the SMC Calling Convention PDD ([SMCCC]). The [SMCCC] assigns function
the SMC Calling Convention PDD (`SMCCC`_). The `SMCCC`_ assigns function
identifiers to each SMC request and describes how arguments are passed and
returned.
......@@ -696,7 +733,7 @@ registration, initialization and use of runtime services in EL3 Runtime
Software (BL31).
The design of the runtime services depends heavily on the concepts and
definitions described in the [SMCCC], in particular SMC Function IDs, Owning
definitions described in the `SMCCC`_, in particular SMC Function IDs, Owning
Entity Numbers (OEN), Fast and Yielding calls, and the SMC32 and SMC64 calling
conventions. Please refer to that document for more detailed explanation of
these terms.
......@@ -704,23 +741,23 @@ these terms.
The following runtime services are expected to be implemented first. They have
not all been instantiated in the current implementation.
1. Standard service calls
#. Standard service calls
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).
2. Secure-EL1 Payload Dispatcher service
#. Secure-EL1 Payload Dispatcher service
If a system runs a Trusted OS or other Secure-EL1 Payload (SP) then
it also requires a _Secure Monitor_ at EL3 to switch the EL1 processor
it also requires a *Secure Monitor* at EL3 to switch the EL1 processor
context between the normal world (EL1/EL2) and trusted world (Secure-EL1).
The Secure Monitor will make these world switches in response to SMCs. The
[SMCCC] provides for such SMCs with the Trusted OS Call and Trusted
`SMCCC`_ provides for such SMCs with the Trusted OS Call and Trusted
Application Call OEN ranges.
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
service - within ARM Trusted Firmware this service is referred to as the
Secure-EL1 Payload Dispatcher (SPD).
......@@ -729,7 +766,7 @@ not all been instantiated in the current implementation.
associated Dispatcher (TSPD). Details of SPD design and TSP/TSPD operation
are described in the "Secure-EL1 Payloads and Dispatchers" section below.
3. CPU implementation service
#. CPU implementation service
This service will provide an interface to CPU implementation specific
services for a given platform e.g. access to processor errata workarounds.
......@@ -737,16 +774,15 @@ not all been instantiated in the current implementation.
Additional services for ARM Architecture, SiP and OEM calls can be implemented.
Each implemented service handles a range of SMC function identifiers as
described in the [SMCCC].
described in the `SMCCC`_.
### Registration
Registration
~~~~~~~~~~~~
A runtime service is registered using the `DECLARE_RT_SVC()` macro, specifying
A runtime service is registered using the ``DECLARE_RT_SVC()`` macro, specifying
the name of the service, the range of OENs covered, the type of service and
initialization and call handler functions. This macro instantiates a `const
struct rt_svc_desc` for the service with these details (see `runtime_svc.h`).
This structure is allocated in a special ELF section `rt_svc_descs`, enabling
initialization and call handler functions. This macro instantiates a ``const struct rt_svc_desc`` for the service with these details (see ``runtime_svc.h``).
This structure is allocated in a special ELF section ``rt_svc_descs``, enabling
the framework to find all service descriptors included into BL31.
The specific service for a SMC Function is selected based on the OEN and call
......@@ -765,10 +801,10 @@ service handler is invoked.
Details of the parameters, requirements and behavior of the initialization and
call handling functions are provided in the following sections.
Initialization
~~~~~~~~~~~~~~
### Initialization
`runtime_svc_init()` in `runtime_svc.c` initializes the runtime services
``runtime_svc_init()`` in ``runtime_svc.c`` initializes the runtime services
framework running on the primary CPU during cold boot as part of the BL31
initialization. This happens prior to initializing a Trusted OS and running
Normal world boot firmware that might in turn use these services.
......@@ -785,16 +821,16 @@ initialization if service declaration errors are detected. The framework does
not check descriptors for the following error conditions, and may behave in an
unpredictable manner under such scenarios:
1. Overlapping OEN ranges
2. Multiple descriptors for the same range of OENs and `call_type`
3. Incorrect range of owning entity numbers for a given `call_type`
#. Overlapping OEN ranges
#. Multiple descriptors for the same range of OENs and ``call_type``
#. Incorrect range of owning entity numbers for a given ``call_type``
Once validated, the service `init()` callback is invoked. This function carries
out any essential EL3 initialization before servicing requests. The `init()`
Once validated, the service ``init()`` callback is invoked. This function carries
out any essential EL3 initialization before servicing requests. The ``init()``
function is only invoked on the primary CPU during cold boot. If the service
uses per-CPU data this must either be initialized for all CPUs during this call,
or be done lazily when a CPU first issues an SMC call to that service. If
`init()` returns anything other than `0`, this is treated as an initialization
``init()`` returns anything other than ``0``, this is treated as an initialization
error and the service is ignored: this does not cause the firmware to halt.
The OEN and call type fields present in the SMC Function ID cover a total of
......@@ -802,97 +838,114 @@ The OEN and call type fields present in the SMC Function ID cover a total of
OENs, e.g. SMCs to call a Trusted OS function. To optimize the lookup of a
service handler, the framework uses an array of 128 indices that map every
distinct OEN/call-type combination either to one of the declared services or to
indicate the service is not handled. This `rt_svc_descs_indices[]` array is
populated for all of the OENs covered by a service after the service `init()`
indicate the service is not handled. This ``rt_svc_descs_indices[]`` array is
populated for all of the OENs covered by a service after the service ``init()``
function has reported success. So a service that fails to initialize will never
have it's `handle()` function invoked.
have it's ``handle()`` function invoked.
The following figure shows how the `rt_svc_descs_indices[]` index maps the SMC
The following figure shows how the ``rt_svc_descs_indices[]`` index maps the SMC
Function ID call type and OEN onto a specific service handler in the
`rt_svc_descs[]` array.
``rt_svc_descs[]`` array.
![Image 1](diagrams/rt-svc-descs-layout.png?raw=true)
|Image 1|
### Handling an SMC
Handling an SMC
~~~~~~~~~~~~~~~
When the EL3 runtime services framework receives a Secure Monitor Call, the SMC
Function ID is passed in W0 from the lower exception level (as per the
[SMCCC]). If the calling register width is AArch32, it is invalid to invoke an
`SMCCC`_). If the calling register width is AArch32, it is invalid to invoke an
SMC Function which indicates the SMC64 calling convention: such calls are
ignored and return the Unknown SMC Function Identifier result code `0xFFFFFFFF`
ignored and return the Unknown SMC Function Identifier result code ``0xFFFFFFFF``
in R0/X0.
Bit[31] (fast/yielding call) and bits[29:24] (owning entity number) of the SMC
Function ID are combined to index into the `rt_svc_descs_indices[]` array. The
Function ID are combined to index into the ``rt_svc_descs_indices[]`` array. The
resulting value might indicate a service that has no handler, in this case the
framework will also report an Unknown SMC Function ID. Otherwise, the value is
used as a further index into the `rt_svc_descs[]` array to locate the required
used as a further index into the ``rt_svc_descs[]`` array to locate the required
service and handler.
The service's `handle()` callback is provided with five of the SMC parameters
The service's ``handle()`` callback is provided with five of the SMC parameters
directly, the others are saved into memory for retrieval (if needed) by the
handler. The handler is also provided with an opaque `handle` for use with the
handler. The handler is also provided with an opaque ``handle`` for use with the
supporting library for parameter retrieval, setting return values and context
manipulation; and with `flags` indicating the security state of the caller. The
manipulation; and with ``flags`` indicating the security state of the caller. The
framework finally sets up the execution stack for the handler, and invokes the
services `handle()` function.
services ``handle()`` function.
On return from the handler the result registers are populated in X0-X3 before
restoring the stack and CPU state and returning from the original SMC.
4. Power State Coordination Interface
--------------------------------------
Power State Coordination Interface
----------------------------------
TODO: Provide design walkthrough of PSCI implementation.
The PSCI v1.0 specification categorizes APIs as optional and mandatory. All the
mandatory APIs in PSCI v1.0 and all the APIs in PSCI v0.2 draft specification
[Power State Coordination Interface PDD] [PSCI] are implemented. The table lists
`Power State Coordination Interface PDD`_ are implemented. The table lists
the PSCI v1.0 APIs and their support in generic code.
An API implementation might have a dependency on platform code e.g. CPU_SUSPEND
An API implementation might have a dependency on platform code e.g. CPU\_SUSPEND
requires the platform to export a part of the implementation. Hence the level
of support of the mandatory APIs depends upon the support exported by the
platform port as well. The Juno and FVP (all variants) platforms export all the
required support.
| PSCI v1.0 API |Supported| Comments |
|:----------------------|:--------|:------------------------------------------|
|`PSCI_VERSION` | Yes | The version returned is 1.0 |
|`CPU_SUSPEND` | Yes* | |
|`CPU_OFF` | Yes* | |
|`CPU_ON` | Yes* | |
|`AFFINITY_INFO` | Yes | |
|`MIGRATE` | Yes** | |
|`MIGRATE_INFO_TYPE` | Yes** | |
|`MIGRATE_INFO_CPU` | Yes** | |
|`SYSTEM_OFF` | Yes* | |
|`SYSTEM_RESET` | Yes* | |
|`PSCI_FEATURES` | Yes | |
|`CPU_FREEZE` | No | |
|`CPU_DEFAULT_SUSPEND` | No | |
|`NODE_HW_STATE` | Yes* | |
|`SYSTEM_SUSPEND` | Yes* | |
|`PSCI_SET_SUSPEND_MODE`| No | |
|`PSCI_STAT_RESIDENCY` | Yes* | |
|`PSCI_STAT_COUNT` | Yes* | |
*Note : These PSCI APIs require platform power management hooks to be
+-----------------------------+-------------+-------------------------------+
| PSCI v1.0 API | Supported | Comments |
+=============================+=============+===============================+
| ``PSCI_VERSION`` | Yes | The version returned is 1.0 |
+-----------------------------+-------------+-------------------------------+
| ``CPU_SUSPEND`` | Yes\* | |
+-----------------------------+-------------+-------------------------------+
| ``CPU_OFF`` | Yes\* | |
+-----------------------------+-------------+-------------------------------+
| ``CPU_ON`` | Yes\* | |
+-----------------------------+-------------+-------------------------------+
| ``AFFINITY_INFO`` | Yes | |
+-----------------------------+-------------+-------------------------------+
| ``MIGRATE`` | Yes\*\* | |
+-----------------------------+-------------+-------------------------------+
| ``MIGRATE_INFO_TYPE`` | Yes\*\* | |
+-----------------------------+-------------+-------------------------------+
| ``MIGRATE_INFO_CPU`` | Yes\*\* | |
+-----------------------------+-------------+-------------------------------+
| ``SYSTEM_OFF`` | Yes\* | |
+-----------------------------+-------------+-------------------------------+
| ``SYSTEM_RESET`` | Yes\* | |
+-----------------------------+-------------+-------------------------------+
| ``PSCI_FEATURES`` | Yes | |
+-----------------------------+-------------+-------------------------------+
| ``CPU_FREEZE`` | No | |
+-----------------------------+-------------+-------------------------------+
| ``CPU_DEFAULT_SUSPEND`` | No | |
+-----------------------------+-------------+-------------------------------+
| ``NODE_HW_STATE`` | Yes\* | |
+-----------------------------+-------------+-------------------------------+
| ``SYSTEM_SUSPEND`` | Yes\* | |
+-----------------------------+-------------+-------------------------------+
| ``PSCI_SET_SUSPEND_MODE`` | No | |
+-----------------------------+-------------+-------------------------------+
| ``PSCI_STAT_RESIDENCY`` | Yes\* | |
+-----------------------------+-------------+-------------------------------+
| ``PSCI_STAT_COUNT`` | Yes\* | |
+-----------------------------+-------------+-------------------------------+
\*Note : These PSCI APIs require platform power management hooks to be
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.
The PSCI implementation in ARM Trusted Firmware is a library which can be
integrated with AArch64 or AArch32 EL3 Runtime Software for ARMv8-A systems.
A guide to integrating PSCI library with AArch32 EL3 Runtime Software
can be found [here][PSCI Lib guide].
can be found `here`_.
5. Secure-EL1 Payloads and Dispatchers
---------------------------------------
Secure-EL1 Payloads and Dispatchers
-----------------------------------
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
......@@ -902,43 +955,46 @@ boot flow in ARM Trusted Firmware. The firmware will attempt to locate, load
and execute a BL32 image.
ARM Trusted Firmware uses a more general term for the BL32 software that runs
at Secure-EL1 - the _Secure-EL1 Payload_ - as it is not always a Trusted OS.
at Secure-EL1 - 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
Secure-EL1 Payload Dispatcher (TSPD) service as an example of how a Trusted OS
is supported on a production system using the Runtime Services Framework. On
such a system, the Test BL32 image and service are replaced by the Trusted OS
and its dispatcher service. The ARM Trusted Firmware build system expects that
the dispatcher will define the build flag `NEED_BL32` to enable it to include
the dispatcher will define the build flag ``NEED_BL32`` to enable it to include
the BL32 in the build either as a binary or to compile from source depending
on whether the `BL32` build option is specified or not.
on whether the ``BL32`` build option is specified or not.
The TSP runs in Secure-EL1. It is designed to demonstrate synchronous
communication with the normal-world software running in EL1/EL2. Communication
is initiated by the normal-world software
* either directly through a Fast SMC (as defined in the [SMCCC])
- either directly through a Fast SMC (as defined in the `SMCCC`_)
* or indirectly through a [PSCI] SMC. The [PSCI] implementation in turn
- or indirectly through a `PSCI`_ SMC. The `PSCI`_ implementation in turn
informs the TSPD about the requested power management operation. This allows
the TSP to prepare for or respond to the power state change
The TSPD service is responsible for.
* Initializing the TSP
- Initializing the TSP
* Routing requests and responses between the secure and the non-secure
- Routing requests and responses between the secure and the non-secure
states during the two types of communications just described
### Initializing a BL32 Image
Initializing a BL32 Image
~~~~~~~~~~~~~~~~~~~~~~~~~
The Secure-EL1 Payload Dispatcher (SPD) service is responsible for initializing
the BL32 image. It needs access to the information passed by BL2 to BL31 to do
so. This is provided by:
.. code:: c
entry_point_info_t *bl31_plat_get_next_image_ep_info(uint32_t);
which returns a reference to the `entry_point_info` structure corresponding to
which returns a reference to the ``entry_point_info`` structure corresponding to
the image which will be run in the specified security state. The SPD uses this
API to get entry point information for the SECURE image, BL32.
......@@ -950,28 +1006,30 @@ To do this the SPD has to register a BL32 initialization function during
initialization of the SPD service. The BL32 initialization function has this
prototype:
.. code:: c
int32_t init(void);
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
before returning through EL3 and running the non-trusted firmware (BL33):
1. 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
#. 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
Secure-EL1. BL31 will exit to BL32 using the asynchronous method by
calling `bl31_prepare_next_image_entry()` and `el3_exit()`.
calling ``bl31_prepare_next_image_entry()`` and ``el3_exit()``.
When the BL32 has completed initialization at Secure-EL1, it returns to
BL31 by issuing an SMC, using a Function ID allocated to the SPD. On
receipt of this SMC, the SPD service handler should switch the CPU context
from trusted to normal world and use the `bl31_set_next_image_type()` and
`bl31_prepare_next_image_entry()` functions to set up the initial return to
from trusted to normal world and use the ``bl31_set_next_image_type()`` and
``bl31_prepare_next_image_entry()`` functions to set up the initial return to
the normal world firmware BL33. On return from the handler the framework
will exit to EL2 and run BL33.
2. The BL32 setup function registers an initialization function using
`bl31_register_bl32_init()` which provides a SPD-defined mechanism to
#. The BL32 setup function registers an initialization function using
``bl31_register_bl32_init()`` which provides a SPD-defined mechanism to
invoke a 'world-switch synchronous call' to Secure-EL1 to run the BL32
entrypoint.
NOTE: The Test SPD service included with the Trusted Firmware provides one
......@@ -980,12 +1038,11 @@ before returning through EL3 and running the non-trusted firmware (BL33):
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
to the BL32 initialization function. On return from this function,
`bl31_main()` will set up the return to the normal world firmware BL33 and
``bl31_main()`` will set up the return to the normal world firmware BL33 and
continue the boot process in the normal world.
6. Crash Reporting in BL31
----------------------------
#. .. rubric:: Crash Reporting in BL31
:name: crash-reporting-in-bl31
BL31 implements a scheme for reporting the processor state when an unhandled
exception is encountered. The reporting mechanism attempts to preserve all the
......@@ -994,11 +1051,13 @@ reports the general purpose, EL3, Secure EL1 and some EL2 state registers.
A dedicated per-CPU crash stack is maintained by BL31 and this is retrieved via
the per-CPU pointer cache. The implementation attempts to minimise the memory
required for this feature. The file `crash_reporting.S` contains the
required for this feature. The file ``crash_reporting.S`` contains the
implementation for crash reporting.
The sample crash output is shown below.
::
x0 :0x000000004F00007C
x1 :0x0000000007FFFFFF
x2 :0x0000000004014D50
......@@ -1078,18 +1137,18 @@ The sample crash output is shown below.
fpexc32_el2 :0x0000000004000700
sp_el0 :0x0000000004010780
7. Guidelines for Reset Handlers
---------------------------------
Guidelines for Reset Handlers
-----------------------------
Trusted Firmware implements a framework that allows CPU and platform ports to
perform actions very early after a CPU is released from reset in both the cold
and warm boot paths. This is done by calling the `reset_handler()` function in
and warm boot paths. This is done by calling the ``reset_handler()`` function in
both the BL1 and BL31 images. It in turn calls the platform and CPU specific
reset handling functions.
Details for implementing a CPU specific reset handler can be found in
Section 8. Details for implementing a platform specific reset handler can be
found in the [Porting Guide] (see the `plat_reset_handler()` function).
found in the `Porting Guide`_ (see the ``plat_reset_handler()`` function).
When adding functionality to a reset handler, keep in mind that if a different
reset handling behavior is required between the first and the subsequent
......@@ -1098,8 +1157,8 @@ In other words, the reset handler should be able to detect whether an action has
already been performed and act as appropriate. Possible courses of actions are,
e.g. skip the action the second time, or undo/redo it.
8. CPU specific operations framework
-------------------------------------
CPU specific operations framework
---------------------------------
Certain aspects of the ARMv8 architecture are implementation defined,
that is, certain behaviours are not architecturally defined, but must be defined
......@@ -1108,28 +1167,28 @@ Firmware implements a framework which categorises the common implementation
defined behaviours and allows a processor to export its implementation of that
behaviour. The categories are:
1. Processor specific reset sequence.
#. Processor specific reset sequence.
2. Processor specific power down sequences.
#. Processor specific power down sequences.
3. Processor specific register dumping as a part of crash reporting.
#. Processor specific register dumping as a part of crash reporting.
4. Errata status reporting.
#. Errata status reporting.
Each of the above categories fulfils a different requirement.
1. allows any processor specific initialization before the caches and MMU
#. allows any processor specific initialization before the caches and MMU
are turned on, like implementation of errata workarounds, entry into
the intra-cluster coherency domain etc.
2. allows each processor to implement the power down sequence mandated in
#. allows each processor to implement the power down sequence mandated in
its Technical Reference Manual (TRM).
3. allows a processor to provide additional information to the developer
#. allows a processor to provide additional information to the developer
in the event of a crash, for example Cortex-A53 has registers which
can expose the data cache contents.
4. allows a processor to define a function that inspects and reports the status
#. allows a processor to define a function that inspects and reports the status
of all errata workarounds on that processor.
Please note that only 2. is mandated by the TRM.
......@@ -1139,53 +1198,55 @@ different CPUs during power down and reset handling. The platform can specify
any CPU optimization it wants to enable for each CPU. It can also specify
the CPU errata workarounds to be applied for each CPU type during reset
handling by defining CPU errata compile time macros. Details on these macros
can be found in the [cpu-specific-build-macros.md][CPUBM] file.
can be found in the `cpu-specific-build-macros.rst`_ file.
The CPU specific operations framework depends on the `cpu_ops` structure which
The CPU specific operations framework depends on the ``cpu_ops`` structure which
needs to be exported for each type of CPU in the platform. It is defined in
`include/lib/cpus/aarch64/cpu_macros.S` and has the following fields : `midr`,
`reset_func()`, `cpu_pwr_down_ops` (array of power down functions) and
`cpu_reg_dump()`.
``include/lib/cpus/aarch64/cpu_macros.S`` and has the following fields : ``midr``,
``reset_func()``, ``cpu_pwr_down_ops`` (array of power down functions) and
``cpu_reg_dump()``.
The CPU specific files in `lib/cpus` export a `cpu_ops` data structure with
suitable handlers for that CPU. For example, `lib/cpus/aarch64/cortex_a53.S`
exports the `cpu_ops` for Cortex-A53 CPU. According to the platform
The CPU specific files in ``lib/cpus`` export a ``cpu_ops`` data structure with
suitable handlers for that CPU. For example, ``lib/cpus/aarch64/cortex_a53.S``
exports the ``cpu_ops`` for Cortex-A53 CPU. According to the platform
configuration, these CPU specific files must be included in the build by
the platform makefile. The generic CPU specific operations framework code exists
in `lib/cpus/aarch64/cpu_helpers.S`.
in ``lib/cpus/aarch64/cpu_helpers.S``.
### CPU specific Reset Handling
CPU specific Reset Handling
~~~~~~~~~~~~~~~~~~~~~~~~~~~
After a reset, the state of the CPU when it calls generic reset handler is:
MMU turned off, both instruction and data caches turned off and not part
of any coherency domain.
The BL entrypoint code first invokes the `plat_reset_handler()` to allow
The BL entrypoint code first invokes the ``plat_reset_handler()`` to allow
the platform to perform any system initialization required and any system
errata workarounds that needs to be applied. The `get_cpu_ops_ptr()` reads
the current CPU midr, finds the matching `cpu_ops` entry in the `cpu_ops`
errata workarounds that needs to be applied. The ``get_cpu_ops_ptr()`` reads
the current CPU midr, finds the matching ``cpu_ops`` entry in the ``cpu_ops``
array and returns it. Note that only the part number and implementer fields
in midr are used to find the matching `cpu_ops` entry. The `reset_func()` in
the returned `cpu_ops` is then invoked which executes the required reset
in midr are used to find the matching ``cpu_ops`` entry. The ``reset_func()`` in
the returned ``cpu_ops`` is then invoked which executes the required reset
handling for that CPU and also any errata workarounds enabled by the platform.
This function must preserve the values of general purpose registers x20 to x29.
Refer to Section "Guidelines for Reset Handlers" for general guidelines
regarding placement of code in a reset handler.
### CPU specific power down sequence
CPU specific power down sequence
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
During the BL31 initialization sequence, the pointer to the matching `cpu_ops`
entry is stored in per-CPU data by `init_cpu_ops()` so that it can be quickly
During the BL31 initialization sequence, the pointer to the matching ``cpu_ops``
entry is stored in per-CPU data by ``init_cpu_ops()`` so that it can be quickly
retrieved during power down sequences.
Various CPU drivers register handlers to perform power down at certain power
levels for that specific CPU. The PSCI service, upon receiving a power down
request, determines the highest power level at which to execute power down
sequence for a particular CPU. It uses the `prepare_cpu_pwr_dwn()` function to
sequence for a particular CPU. It uses the ``prepare_cpu_pwr_dwn()`` function to
pick the right power down handler for the requested level. The function
retrieves `cpu_ops` pointer member of per-CPU data, and from that, further
retrieves `cpu_pwr_down_ops` array, and indexes into the required level. If the
retrieves ``cpu_ops`` pointer member of per-CPU data, and from that, further
retrieves ``cpu_pwr_down_ops`` array, and indexes into the required level. If the
requested power level is higher than what a CPU driver supports, the handler
registered for highest level is invoked.
......@@ -1193,16 +1254,18 @@ At runtime the platform hooks for power down are invoked by the PSCI service to
perform platform specific operations during a power down sequence, for example
turning off CCI coherency during a cluster power down.
### CPU specific register reporting during crash
CPU specific register reporting during crash
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If the crash reporting is enabled in BL31, when a crash occurs, the crash
reporting framework calls `do_cpu_reg_dump` which retrieves the matching
`cpu_ops` using `get_cpu_ops_ptr()` function. The `cpu_reg_dump()` in
`cpu_ops` is invoked, which then returns the CPU specific register values to
reporting framework calls ``do_cpu_reg_dump`` which retrieves the matching
``cpu_ops`` using ``get_cpu_ops_ptr()`` function. The ``cpu_reg_dump()`` in
``cpu_ops`` is invoked, which then returns the CPU specific register values to
be reported and a pointer to the ASCII list of register names in a format
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
both cold and warm boots, shortly after reset. Individual Errata workarounds are
......@@ -1210,7 +1273,7 @@ enabled as build options. Some errata workarounds have potential run-time
implications; therefore some are enabled by default, others not. Platform ports
shall override build options to enable or disable errata as appropriate. The CPU
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.
Functions in CPU drivers that apply errata workaround must follow the
......@@ -1218,28 +1281,28 @@ conventions listed below.
The errata workaround must be authored as two separate functions:
* One that checks for errata. This function must determine whether that errata
- One that checks for errata. This function must determine whether that errata
applies to the current CPU. Typically this involves matching the current
CPUs revision and variant against a value that's known to be affected by the
errata. If the function determines that the errata applies to this CPU, it
must return `ERRATA_APPLIES`; otherwise, it must return
`ERRATA_NOT_APPLIES`. The utility functions `cpu_get_rev_var` and
`cpu_rev_var_ls` functions may come in handy for this purpose.
must return ``ERRATA_APPLIES``; otherwise, it must return
``ERRATA_NOT_APPLIES``. The utility functions ``cpu_get_rev_var`` and
``cpu_rev_var_ls`` functions may come in handy for this purpose.
For an errata identified as `E`, the check function must be named
`check_errata_E`.
For an errata identified as ``E``, the check function must be named
``check_errata_E``.
This function will be invoked at different times, both from assembly and from
C run time. Therefore it must follow AAPCS, and must not use stack.
This function will be invoked at different times, both from assembly and from
C run time. Therefore it must follow AAPCS, and must not use stack.
* Another one that applies the errata workaround. This function would call the
- Another one that applies the errata workaround. This function would call the
check function described above, and applies errata workaround if required.
CPU drivers that apply errata workaround can optionally implement an assembly
function that report the status of errata workarounds pertaining to that CPU.
For a driver that registers the CPU, for example, `cpux` via. `declare_cpu_ops`
For a driver that registers the CPU, for example, ``cpux`` via. ``declare_cpu_ops``
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.
In a debug build of ARM Trusted Firmware, on a CPU that comes out of reset, both
......@@ -1247,14 +1310,14 @@ BL1 and the run time firmware (BL31 in AArch64, and BL32 in AArch32) will invoke
errata status reporting function, if one exists, for that type of CPU.
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:
* The build option that enables the errata;
- The build option that enables the errata;
* The name of the CPU: this must be the same identifier that CPU driver
registered itself with, using `declare_cpu_ops`;
- The name of the CPU: this must be the same identifier that CPU driver
registered itself with, using ``declare_cpu_ops``;
* And the errata identifier: the identifier must match what's used in the
- And the errata identifier: the identifier must match what's used in the
errata's check function described above.
The errata status reporting function will be called once per CPU type/errata
......@@ -1267,20 +1330,20 @@ status as well.
Reporting the status of errata workaround is for informational purpose only; it
has no functional significance.
9. Memory layout of BL images
-----------------------------
Memory layout of BL images
--------------------------
Each bootloader image can be divided in 2 parts:
* the static contents of the image. These are data actually stored in the
binary on the disk. In the ELF terminology, they are called `PROGBITS`
- the static contents of the image. These are data actually stored in the
binary on the disk. In the ELF terminology, they are called ``PROGBITS``
sections;
* the run-time contents of the image. These are data that don't occupy any
- the run-time contents of the image. These are data that don't occupy any
space in the binary on the disk. The ELF binary just contains some
metadata indicating where these data will be stored at run-time and the
corresponding sections need to be allocated and initialized at run-time.
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,
followed by all NOBITS sections. This is true for all Trusted Firmware images
......@@ -1290,7 +1353,8 @@ PROGBITS sections then the resulting binary file would contain zero bytes in
place of this NOBITS section, making the image unnecessarily bigger. Smaller
images 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
linker scripts export some symbols into the program symbol table. Their values
......@@ -1299,38 +1363,36 @@ symbols to figure out the image memory layout.
Linker symbols follow the following naming convention in the trusted firmware.
* `__<SECTION>_START__`
- ``__<SECTION>_START__``
Start address of a given section named `<SECTION>`.
Start address of a given section named ``<SECTION>``.
* `__<SECTION>_END__`
- ``__<SECTION>_END__``
End address of a given section named `<SECTION>`. If there is an alignment
constraint on the section's end address then `__<SECTION>_END__` corresponds
End address of a given section named ``<SECTION>``. If there is an alignment
constraint on the section's end address then ``__<SECTION>_END__`` corresponds
to the end address of the section's actual contents, rounded up to the right
boundary. Refer to the value of `__<SECTION>_UNALIGNED_END__` to know the
boundary. Refer to the value of ``__<SECTION>_UNALIGNED_END__`` to know the
actual end address of the section's contents.
* `__<SECTION>_UNALIGNED_END__`
- ``__<SECTION>_UNALIGNED_END__``
End address of a given section named `<SECTION>` without any padding or
End address of a given section named ``<SECTION>`` without any padding or
rounding up due to some alignment constraint.
* `__<SECTION>_SIZE__`
- ``__<SECTION>_SIZE__``
Size (in bytes) of a given section named `<SECTION>`. If there is an
alignment constraint on the section's end address then `__<SECTION>_SIZE__`
Size (in bytes) of a given section named ``<SECTION>``. If there is an
alignment constraint on the section's end address then ``__<SECTION>_SIZE__``
corresponds to the size of the section's actual contents, rounded up to the
right boundary. In other words, `__<SECTION>_SIZE__ = __<SECTION>_END__ -
_<SECTION>_START__`. Refer to the value of `__<SECTION>_UNALIGNED_SIZE__`
right boundary. In other words, ``__<SECTION>_SIZE__ = __<SECTION>_END__ - _<SECTION>_START__``. Refer to the value of ``__<SECTION>_UNALIGNED_SIZE__``
to know the actual size of the section's contents.
* `__<SECTION>_UNALIGNED_SIZE__`
- ``__<SECTION>_UNALIGNED_SIZE__``
Size (in bytes) of a given section named `<SECTION>` without any padding or
Size (in bytes) of a given section named ``<SECTION>`` without any padding or
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
them to be defined. They are listed in the following subsections. Some of them
......@@ -1341,52 +1403,54 @@ 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
layout as they are easy to spot in the link map files.
#### Common linker symbols
Common linker symbols
^^^^^^^^^^^^^^^^^^^^^
All BL images share the following requirements:
* The BSS section must be zero-initialised before executing any C code.
* The coherent memory section (if enabled) must be zero-initialised as well.
* The MMU setup code needs to know the extents of the coherent and read-only
- The BSS section must be zero-initialised before executing any C code.
- The coherent memory section (if enabled) must be zero-initialised as well.
- The MMU setup code needs to know the extents of the coherent and read-only
memory regions to set the right memory attributes. When
`SEPARATE_CODE_AND_RODATA=1`, it needs to know more specifically how the
``SEPARATE_CODE_AND_RODATA=1``, it needs to know more specifically how the
read-only memory region is divided between code and data.
The following linker symbols are defined for this purpose:
* `__BSS_START__`
* `__BSS_SIZE__`
* `__COHERENT_RAM_START__` Must be aligned on a page-size boundary.
* `__COHERENT_RAM_END__` Must be aligned on a page-size boundary.
* `__COHERENT_RAM_UNALIGNED_SIZE__`
* `__RO_START__`
* `__RO_END__`
* `__TEXT_START__`
* `__TEXT_END__`
* `__RODATA_START__`
* `__RODATA_END__`
#### BL1's linker symbols
- ``__BSS_START__``
- ``__BSS_SIZE__``
- ``__COHERENT_RAM_START__`` Must be aligned on a page-size boundary.
- ``__COHERENT_RAM_END__`` Must be aligned on a page-size boundary.
- ``__COHERENT_RAM_UNALIGNED_SIZE__``
- ``__RO_START__``
- ``__RO_END__``
- ``__TEXT_START__``
- ``__TEXT_END__``
- ``__RODATA_START__``
- ``__RODATA_END__``
BL1's linker symbols
^^^^^^^^^^^^^^^^^^^^
BL1 being the ROM image, it has additional requirements. BL1 resides in ROM and
it is entirely executed in place but it needs some read-write memory for its
mutable data. Its `.data` section (i.e. its allocated read-write data) must be
mutable data. Its ``.data`` section (i.e. its allocated read-write data) must be
relocated from ROM to RAM before executing any C code.
The following additional linker symbols are defined for BL1:
* `__BL1_ROM_END__` End address of BL1's ROM contents, covering its code
and `.data` section in ROM.
* `__DATA_ROM_START__` Start address of the `.data` section in ROM. Must be
- ``__BL1_ROM_END__`` End address of BL1's ROM contents, covering its code
and ``.data`` section in ROM.
- ``__DATA_ROM_START__`` Start address of the ``.data`` section in ROM. Must be
aligned on a 16-byte boundary.
* `__DATA_RAM_START__` Address in RAM where the `.data` section should be
- ``__DATA_RAM_START__`` Address in RAM where the ``.data`` section should be
copied over. Must be aligned on a 16-byte boundary.
* `__DATA_SIZE__` Size of the `.data` section (in ROM or RAM).
* `__BL1_RAM_START__` Start address of BL1 read-write data.
* `__BL1_RAM_END__` End address of BL1 read-write data.
- ``__DATA_SIZE__`` Size of the ``.data`` section (in ROM or RAM).
- ``__BL1_RAM_START__`` Start address of BL1 read-write data.
- ``__BL1_RAM_END__`` End address of BL1 read-write data.
### 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.
This means that all bootloader images need to be linked against their ultimate
......@@ -1398,44 +1462,46 @@ layout.
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.
However, there are tools to aid in understanding the memory layout. These are
the link map files: `build/<platform>/<build-type>/bl<x>/bl<x>.map`, with `<x>`
the link map files: ``build/<platform>/<build-type>/bl<x>/bl<x>.map``, with ``<x>``
being the stage bootloader. They provide a detailed view of the memory usage of
each image. Among other useful information, they provide the end address of
each image.
* `bl1.map` link map file provides `__BL1_RAM_END__` address.
* `bl2.map` link map file provides `__BL2_END__` address.
* `bl31.map` link map file provides `__BL31_END__` address.
* `bl32.map` link map file provides `__BL32_END__` address.
- ``bl1.map`` link map file provides ``__BL1_RAM_END__`` address.
- ``bl2.map`` link map file provides ``__BL2_END__`` address.
- ``bl31.map`` link map file provides ``__BL31_END__`` address.
- ``bl32.map`` link map file provides ``__BL32_END__`` address.
For each bootloader image, the platform code must provide its start address
as well as a limit address that it must not overstep. The latter is used in the
linker scripts to check that the image doesn't grow past that address. If that
happens, the linker will issue a message similar to the following:
::
aarch64-none-elf-ld: BLx has exceeded its limit.
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
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, Trusted Firmware provides a mechanism to
verify at boot time that the memory to load a new image is free to prevent
overwriting a previously loaded image. For this mechanism to work, the platform
must specify the memory available in the system as regions, where each region
consists of base address, total size and the free area within it (as defined
in the `meminfo_t` structure). Trusted Firmware retrieves these memory regions
in the ``meminfo_t`` structure). Trusted Firmware retrieves these memory regions
by calling the corresponding platform API:
* `meminfo_t *bl1_plat_sec_mem_layout(void)`
* `meminfo_t *bl2_plat_sec_mem_layout(void)`
* `void bl2_plat_get_scp_bl2_meminfo(meminfo_t *scp_bl2_meminfo)`
* `void bl2_plat_get_bl32_meminfo(meminfo_t *bl32_meminfo)`
* `void bl2_plat_get_bl33_meminfo(meminfo_t *bl33_meminfo)`
- ``meminfo_t *bl1_plat_sec_mem_layout(void)``
- ``meminfo_t *bl2_plat_sec_mem_layout(void)``
- ``void bl2_plat_get_scp_bl2_meminfo(meminfo_t *scp_bl2_meminfo)``
- ``void bl2_plat_get_bl32_meminfo(meminfo_t *bl32_meminfo)``
- ``void bl2_plat_get_bl33_meminfo(meminfo_t *bl33_meminfo)``
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
`load_image()` function will check that the memory where BL2 will be loaded is
``load_image()`` function will check that the memory where BL2 will be loaded is
within the specified region and marked as free.
The actual number of regions and their base addresses and sizes is platform
......@@ -1461,6 +1527,8 @@ unexpected memory layout.
The following diagram is an example of an image loaded in the bottom part of
the memory region. The region is initially free (nothing has been loaded yet):
::
Memory region
+----------+
| |
......@@ -1474,6 +1542,8 @@ the memory region. The region is initially free (nothing has been loaded yet):
And the following diagram is an example of an image loaded in the top part:
::
Memory region
+----------+
| xxxxxxxx | <<<<<<<<<<<<< Marked as unavailable
......@@ -1485,23 +1555,23 @@ 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, Trusted Firmware does not provide any mechanism
to verify at boot time that the memory to load a new image is free to prevent
overwriting a previously loaded image. The platform must specify the memory
available in 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
`load_image()` function performs bounds check for the image size based on the
``load_image()`` function performs bounds check for the image size based on the
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.
#### Memory layout on ARM development platforms
Memory layout on 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
Trusted SRAM. The amount of Trusted SRAM available to load the bootloader
images is reduced by the size of the shared memory.
......@@ -1510,67 +1580,67 @@ The following list describes the memory layout on the ARM development platforms:
this is also used for the MHU payload when passing messages to and from the
SCP.
* On FVP, BL1 is originally sitting in the Trusted ROM at address `0x0`. On
Juno, BL1 resides in flash memory at address `0x0BEC0000`. BL1 read-write
- On FVP, BL1 is originally sitting in the Trusted ROM at address ``0x0``. On
Juno, BL1 resides in flash memory at address ``0x0BEC0000``. BL1 read-write
data are relocated to the top of Trusted SRAM at runtime.
* EL3 Runtime Software, BL31 for AArch64 and BL32 for AArch32 (e.g. SP_MIN),
- EL3 Runtime Software, BL31 for AArch64 and BL32 for AArch32 (e.g. SP\_MIN),
is loaded at the top of the Trusted SRAM, such that its NOBITS sections will
overwrite BL1 R/W data. This implies that BL1 global variables remain valid
only until execution reaches the EL3 Runtime Software entry point during a
cold boot.
* BL2 is loaded below EL3 Runtime Software.
- BL2 is loaded below EL3 Runtime Software.
* On Juno, SCP_BL2 is loaded temporarily into the EL3 Runtime Software memory
- On Juno, SCP\_BL2 is loaded temporarily into the EL3 Runtime Software memory
region and transfered to the SCP before being overwritten by EL3 Runtime
Software.
* BL32 (for AArch64) can be loaded in one of the following locations:
- BL32 (for AArch64) can be loaded in one of the following locations:
* Trusted SRAM
* Trusted DRAM (FVP only)
* Secure region of DRAM (top 16MB of DRAM configured by the TrustZone
- Trusted SRAM
- Trusted DRAM (FVP only)
- Secure region of DRAM (top 16MB of DRAM configured by the TrustZone
controller)
When BL32 (for AArch64) is loaded into Trusted SRAM, its NOBITS sections
are allowed to overlay BL2. This memory layout is designed to give the
BL32 image as much memory as possible when it is loaded into Trusted SRAM.
When LOAD_IMAGE_V2 is disabled the memory regions for the overlap detection
When LOAD\_IMAGE\_V2 is disabled the memory regions for the overlap detection
mechanism at boot time are defined as follows (shown per API):
* `meminfo_t *bl1_plat_sec_mem_layout(void)`
- ``meminfo_t *bl1_plat_sec_mem_layout(void)``
This region corresponds to the whole Trusted SRAM except for the shared
memory at the base. This region is initially free. At boot time, BL1 will
mark the BL1(rw) section within this region as occupied. The BL1(rw) section
is placed at the top of Trusted SRAM.
* `meminfo_t *bl2_plat_sec_mem_layout(void)`
- ``meminfo_t *bl2_plat_sec_mem_layout(void)``
This region corresponds to the whole Trusted SRAM as defined by
`bl1_plat_sec_mem_layout()`, but with the BL1(rw) section marked as
``bl1_plat_sec_mem_layout()``, but with the BL1(rw) section marked as
occupied. This memory region is used to check that BL2 and BL31 do not
overlap with each other. BL2_BASE and BL1_RW_BASE are carefully chosen so
overlap with each other. BL2\_BASE and BL1\_RW\_BASE are carefully chosen so
that the memory for BL31 is top loaded above BL2.
* `void bl2_plat_get_scp_bl2_meminfo(meminfo_t *scp_bl2_meminfo)`
- ``void bl2_plat_get_scp_bl2_meminfo(meminfo_t *scp_bl2_meminfo)``
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.
This approach is valid because the SCP BL2 image is loaded temporarily
while it is being transferred to the SCP, so this memory is reused
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
platforms support three different locations (detailed below): Trusted SRAM,
Trusted DRAM and the TZC-Secured DRAM.
* `void bl2_plat_get_bl33_meminfo(meminfo_t *bl33_meminfo)`
- ``void bl2_plat_get_bl33_meminfo(meminfo_t *bl33_meminfo)``
This region corresponds to the Non-Secure DDR-DRAM, excluding the
TZC-Secured area.
......@@ -1585,6 +1655,8 @@ layout of the other images in Trusted SRAM.
**FVP with TSP in Trusted SRAM (default option):**
(These diagrams only cover the AArch64 case)
::
Trusted SRAM
0x04040000 +----------+ loaded by BL2 ------------------
| BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS |
......@@ -1603,9 +1675,10 @@ layout of the other images in Trusted SRAM.
| BL1 (ro) |
0x00000000 +----------+
**FVP with TSP in Trusted DRAM:**
::
Trusted DRAM
0x08000000 +----------+
| BL32 |
......@@ -1631,6 +1704,8 @@ layout of the other images in Trusted SRAM.
**FVP with TSP in TZC-Secured DRAM:**
::
DRAM
0xffffffff +----------+
| BL32 | (secure)
......@@ -1658,9 +1733,10 @@ layout of the other images in Trusted SRAM.
| BL1 (ro) |
0x00000000 +----------+
**Juno with BL32 in Trusted SRAM (default option):**
::
Flash0
0x0C000000 +----------+
: :
......@@ -1683,9 +1759,10 @@ layout of the other images in Trusted SRAM.
| MHU |
0x04000000 +----------+
**Juno with BL32 in TZC-secured DRAM:**
::
DRAM
0xFFE00000 +----------+
| BL32 | (secure)
......@@ -1717,9 +1794,8 @@ layout of the other images in Trusted SRAM.
| MHU |
0x04000000 +----------+
10. Firmware Image Package (FIP)
---------------------------------
Firmware Image Package (FIP)
----------------------------
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
......@@ -1728,7 +1804,8 @@ from a FIP has been added to the storage layer and allows a package to be read
from supported platform storage. A tool to create Firmware Image Packages is
also provided and described below.
### Firmware Image Package layout
Firmware Image Package layout
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The FIP layout consists of a table of contents (ToC) followed by payload data.
The ToC itself has a header followed by one or more table entries. The ToC is
......@@ -1736,6 +1813,8 @@ terminated by an end marker entry. All ToC entries describe some payload data
that has been appended to the end of the binary package. With the information
provided in the ToC entry the corresponding payload data can be retrieved.
::
------------------
| ToC Header |
|----------------|
......@@ -1755,11 +1834,13 @@ provided in the ToC entry the corresponding payload data can be retrieved.
------------------
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.
The ToC header has the following fields:
::
`name`: The name of the ToC. This is currently used to validate the header.
`serial_number`: A non-zero number provided by the creation tool
`flags`: Flags associated with this data.
......@@ -1769,6 +1850,8 @@ The ToC header has the following fields:
A ToC entry has the following fields:
::
`uuid`: All files are referred to by a pre-defined Universally Unique
IDentifier [UUID] . The UUIDs are defined in
`include/tools_share/firmware_image_package.h`. The platform translates
......@@ -1779,36 +1862,37 @@ A ToC entry has the following fields:
`size`: The size of the corresponding payload data in bytes.
`flags`: Flags associated with this entry. Non are yet defined.
### 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
that can be loaded by the ARM Trusted Firmware from platform storage. The tool
currently only supports packing bootloader images. Additional image definitions
can be added to the tool as required.
The tool can be found in `tools/fiptool`.
The tool can be found in ``tools/fiptool``.
### Loading from a Firmware Image Package (FIP)
Loading from a Firmware Image Package (FIP)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
currently NOR FLASH.
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
located at the start of NOR FLASH0.
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.
11. Use of coherent memory in Trusted Firmware
-----------------------------------------------
Use of coherent memory in Trusted Firmware
------------------------------------------
There might be loss of coherency when physical memory with mismatched
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
caches are turned on/off incrementally.
......@@ -1819,7 +1903,7 @@ memory region.
By default, all data structures which are susceptible to accesses with
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
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
......@@ -1831,25 +1915,29 @@ 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
cache maintenance on them.
### Disabling the use of coherent memory in Trusted Firmware
Disabling the use of coherent memory in Trusted Firmware
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It might be desirable to avoid the cost of allocating coherent memory on
platforms which are memory constrained. Trusted Firmware enables inclusion of
coherent memory in firmware images through the build flag `USE_COHERENT_MEM`.
coherent 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
approach described above.
The below sections analyze the data structures allocated in the coherent memory
region and the changes required to allocate them in normal memory.
### Coherent memory usage in PSCI implementation
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
structure is allocated in the coherent memory region in the Trusted Firmware
because it can be accessed by multple CPUs, either with caches enabled or
disabled.
.. code:: c
typedef struct non_cpu_pwr_domain_node {
/*
* Index of the first CPU power domain node level 0 which has this node
......@@ -1879,22 +1967,25 @@ disabled.
} non_cpu_pd_node_t;
In order to move this data structure to normal memory, the use of each of its
fields must be analyzed. Fields like `cpu_start_idx`, `ncpus`, `parent_node`
`level` and `lock_index` are only written once during cold boot. Hence removing
fields must be analyzed. Fields like ``cpu_start_idx``, ``ncpus``, ``parent_node``
``level`` and ``lock_index`` are only written once during cold boot. Hence removing
them from coherent memory involves only doing a clean and invalidate of the
cache lines after these fields are written.
The field `local_state` can be concurrently accessed by multiple CPUs in
different cache states. A Lamport's Bakery lock `psci_locks` is used to ensure
The field ``local_state`` can be concurrently accessed by multiple CPUs in
different cache states. A Lamport's Bakery lock ``psci_locks`` is used to ensure
mutual exlusion to this field and a clean and invalidate is needed after it
is written.
### Bakery lock data
Bakery lock data
~~~~~~~~~~~~~~~~
The bakery lock data structure `bakery_lock_t` is allocated in coherent memory
and is accessed by multiple CPUs with mismatched attributes. `bakery_lock_t` is
The bakery lock data structure ``bakery_lock_t`` is allocated in coherent memory
and is accessed by multiple CPUs with mismatched attributes. ``bakery_lock_t`` is
defined as follows:
.. code:: c
typedef struct bakery_lock {
/*
* The lock_data is a bit-field of 2 members:
......@@ -1909,7 +2000,7 @@ It is a characteristic of Lamport's Bakery algorithm that the volatile per-CPU
fields can be read by all CPUs but only written to by the owning CPU.
Depending upon the data cache line size, the per-CPU fields of the
`bakery_lock_t` structure for multiple CPUs may exist on a single cache line.
``bakery_lock_t`` structure for multiple CPUs may exist on a single cache line.
These per-CPU fields can be read and written during lock contention by multiple
CPUs with mismatched memory attributes. Since these fields are a part of the
lock implementation, they do not have access to any other locking primitive to
......@@ -1919,23 +2010,25 @@ the following example.
CPU0 updates its per-CPU field with data cache enabled. This write updates a
local cache line which contains a copy of the fields for other CPUs as well. Now
CPU1 updates its per-CPU field of the `bakery_lock_t` structure with data cache
CPU1 updates its per-CPU field of the ``bakery_lock_t`` structure with data cache
disabled. CPU1 then issues a DCIVAC operation to invalidate any stale copies of
its field in any other cache line in the system. This operation will invalidate
the update made by CPU0 as well.
To use bakery locks when `USE_COHERENT_MEM` is disabled, the lock data structure
To use bakery locks when ``USE_COHERENT_MEM`` is disabled, the lock data structure
has been redesigned. The changes utilise the characteristic of Lamport's Bakery
algorithm mentioned earlier. The bakery_lock structure only allocates the memory
for a single CPU. The macro `DEFINE_BAKERY_LOCK` allocates all the bakery locks
needed for a CPU into a section `bakery_lock`. The linker allocates the memory
for other cores by using the total size allocated for the bakery_lock section
and multiplying it with (PLATFORM_CORE_COUNT - 1). This enables software to
algorithm mentioned earlier. The bakery\_lock structure only allocates the memory
for a single CPU. The macro ``DEFINE_BAKERY_LOCK`` allocates all the bakery locks
needed for a CPU into a section ``bakery_lock``. The linker allocates the memory
for other cores by using the total size allocated for the bakery\_lock section
and multiplying it with (PLATFORM\_CORE\_COUNT - 1). This enables software to
perform software cache maintenance on the lock data structure without running
into coherency issues associated with mismatched attributes.
The bakery lock data structure `bakery_info_t` is defined for use when
`USE_COHERENT_MEM` is disabled as follows:
The bakery lock data structure ``bakery_info_t`` is defined for use when
``USE_COHERENT_MEM`` is disabled as follows:
.. code:: c
typedef struct bakery_info {
/*
......@@ -1947,11 +2040,13 @@ The bakery lock data structure `bakery_info_t` is defined for use when
volatile uint16_t lock_data;
} bakery_info_t;
The `bakery_info_t` represents a single per-CPU field of one lock and
the combination of corresponding `bakery_info_t` structures for all CPUs in the
The ``bakery_info_t`` represents a single per-CPU field of one lock and
the combination of corresponding ``bakery_info_t`` structures for all CPUs in the
system represents the complete bakery lock. The view in memory for a system
with n bakery locks are:
::
bakery_lock section start
|----------------|
| `bakery_info_t`| <-- Lock_0 per-CPU field
......@@ -1988,15 +2083,15 @@ with n bakery locks are:
------------------
Consider a system of 2 CPUs with 'N' bakery locks as shown above. For an
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
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
to be performed for each access.
On ARM Platforms, bakery locks are used in psci (`psci_locks`) and power controller
driver (`arm_lock`).
On ARM Platforms, bakery locks are used in psci (``psci_locks``) and power controller
driver (``arm_lock``).
### Non Functional Impact of removing coherent memory
Non Functional Impact of removing coherent memory
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Removal of the coherent memory region leads to the additional software overhead
of performing cache maintenance for the affected data structures. However, since
......@@ -2004,8 +2099,9 @@ the memory where the data structures are allocated is cacheable, the overhead is
mostly mitigated by an increase in performance.
There is however a performance impact for bakery locks, due to:
* Additional cache maintenance operations, and
* Multiple cache line reads for each lock operation, since the bakery locks
- Additional cache maintenance operations, and
- Multiple cache line reads for each lock operation, since the bakery locks
for each CPU are distributed across different cache lines.
The implementation has been optimized to minimize this additional overhead.
......@@ -2015,15 +2111,14 @@ in Device memory the same is 2 micro seconds. The measurements were done on the
Juno ARM development platform.
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
whether coherent memory should be used. If a platform disables
`USE_COHERENT_MEM` and needs to use bakery locks in the porting layer, it can
optionally define macro `PLAT_PERCPU_BAKERY_LOCK_SIZE` (see the [Porting
Guide]). Refer to the reference platform code for examples.
``USE_COHERENT_MEM`` and needs to use bakery locks in the porting layer, it can
optionally define macro ``PLAT_PERCPU_BAKERY_LOCK_SIZE`` (see the
`Porting Guide`_). Refer to the reference platform code for examples.
12. 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
properties of the target memory region, such as its access permissions. The
......@@ -2033,6 +2128,8 @@ memory regions then it needs to map them using different memory pages.
The default memory layout for each BL image is as follows:
::
| ... |
+-------------------+
| Read-write data |
......@@ -2063,7 +2160,7 @@ means that the read-only data stored on the same memory page as the code are
executable as well. This could potentially be exploited as part of a security
attack.
TF provides the build flag `SEPARATE_CODE_AND_RODATA` to isolate the code and
TF provides the build flag ``SEPARATE_CODE_AND_RODATA`` to isolate the code and
read-only data on separate memory pages. This in turn allows independent control
of the access permissions for the code and read-only data. In this case,
platform code gets a finer-grained view of the image layout and can
......@@ -2075,6 +2172,8 @@ between the code and read-only data to ensure the segragation of the two. To
limit the memory cost, this flag also changes the memory layout such that the
code and exception vectors are now contiguous, like so:
::
| ... |
+-------------------+
| Read-write data |
......@@ -2099,9 +2198,8 @@ should consider the trade-off between memory footprint and security.
This build flag is disabled by default, minimising memory footprint. On ARM
platforms, it is enabled.
13. Performance Measurement Framework
--------------------------------------
Performance Measurement Framework
---------------------------------
The Performance Measurement Framework (PMF) facilitates collection of
timestamps by registered services and provides interfaces to retrieve
......@@ -2109,79 +2207,89 @@ them from within the ARM Trusted Firmware. A platform can choose to
expose appropriate SMCs to retrieve these collected timestamps.
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
timestamps captured by other CPUs.
### Timestamp identifier format
Timestamp identifier format
~~~~~~~~~~~~~~~~~~~~~~~~~~~
A PMF timestamp is uniquely identified across the system via the
timestamp ID or `tid`. The `tid` is composed as follows:
timestamp ID or ``tid``. The ``tid`` is composed as follows:
::
Bits 0-7: The local timestamp identifier.
Bits 8-9: Reserved.
Bits 10-15: The service identifier.
Bits 16-31: Reserved.
1. The service identifier. Each PMF service is identified by a
#. The service identifier. Each PMF service is identified by a
service name and a service identifier. Both the service name and
identifier are unique within the system as a whole.
2. The local timestamp identifier. This identifier is unique within a given
#. The local timestamp identifier. This identifier is unique within a given
service.
### Registering a PMF service
Registering a PMF service
~~~~~~~~~~~~~~~~~~~~~~~~~
To register a PMF service, the `PMF_REGISTER_SERVICE()` macro from `pmf.h`
To register a PMF service, the ``PMF_REGISTER_SERVICE()`` macro from ``pmf.h``
is used. The arguments required are the service name, the service ID,
the total number of local timestamps to be captured and a set of flags.
The `flags` field can be specified as a bitwise-OR of the following values:
The ``flags`` field can be specified as a bitwise-OR of the following values:
::
PMF_STORE_ENABLE: The timestamp is stored in memory for later retrieval.
PMF_DUMP_ENABLE: The timestamp is dumped on the serial console.
The `PMF_REGISTER_SERVICE()` reserves memory to store captured
The ``PMF_REGISTER_SERVICE()`` reserves memory to store captured
timestamps in a PMF specific linker section at build time.
Additionally, it defines necessary functions to capture and
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 from within ARM Trusted Firmware. In order to retrieve
timestamps from outside of ARM Trusted Firmware, the
`PMF_REGISTER_SERVICE_SMC()` macro must be used instead. This macro
accepts the same set of arguments as the `PMF_REGISTER_SERVICE()`
``PMF_REGISTER_SERVICE_SMC()`` macro must be used instead. This macro
accepts the same set of arguments as the ``PMF_REGISTER_SERVICE()``
macro but additionally supports retrieving timestamps using SMCs.
### Capturing a timestamp
Capturing a timestamp
~~~~~~~~~~~~~~~~~~~~~
PMF timestamps are stored in a per-service timestamp region. On a
system with multiple CPUs, each timestamp is captured and stored
in a per-CPU cache line aligned memory region.
Having registered the service, the `PMF_CAPTURE_TIMESTAMP()` macro can be
Having registered the service, the ``PMF_CAPTURE_TIMESTAMP()`` macro can be
used to capture a timestamp at the location where it is used. The macro
takes the service name, a local timestamp identifier and a flag as arguments.
The `flags` field argument can be zero, or `PMF_CACHE_MAINT` which
The ``flags`` field argument can be zero, or ``PMF_CACHE_MAINT`` which
instructs PMF to do cache maintenance following the capture. Cache
maintenance is required if any of the service's timestamps are captured
with data cache disabled.
To capture a timestamp in assembly code, the caller should use
`pmf_calc_timestamp_addr` macro (defined in `pmf_asm_macros.S`) to
``pmf_calc_timestamp_addr`` macro (defined in ``pmf_asm_macros.S``) to
calculate the address of where the timestamp would be stored. The
caller should then read `CNTPCT_EL0` register to obtain the timestamp
caller should then read ``CNTPCT_EL0`` register to obtain the timestamp
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
be retrieved using either `PMF_GET_TIMESTAMP_BY_MPIDR()` or
`PMF_GET_TIMESTAMP_BY_INDEX()` macros. These macros accept the CPU's MPIDR
be retrieved using either ``PMF_GET_TIMESTAMP_BY_MPIDR()`` or
``PMF_GET_TIMESTAMP_BY_INDEX()`` macros. These macros accept the CPU's MPIDR
value, or its ordinal position, respectively.
From outside ARM Trusted Firmware, timestamps for individual CPUs can be
retrieved by calling into `pmf_smc_handler()`.
retrieved by calling into ``pmf_smc_handler()``.
.. code:: c
Interface : pmf_smc_handler()
Argument : unsigned int smc_fid, u_register_t x1,
......@@ -2203,77 +2311,80 @@ retrieved by calling into `pmf_smc_handler()`.
cache invalidate before reading the timestamp. This ensures
an updated copy is returned.
The remaining arguments, `x4`, `cookie`, `handle` and `flags` are unused
The remaining arguments, ``x4``, ``cookie``, ``handle`` and ``flags`` are unused
in this implementation.
### PMF code structure
PMF code structure
~~~~~~~~~~~~~~~~~~
1. `pmf_main.c` consists of core functions that implement service registration,
#. ``pmf_main.c`` consists of core functions that implement service registration,
initialization, storing, dumping and retrieving timestamps.
2. `pmf_smc.c` contains the SMC handling for registered PMF services.
#. ``pmf_smc.c`` contains the SMC handling for registered PMF services.
3. `pmf.h` contains the public interface to Performance Measurement Framework.
#. ``pmf.h`` contains the public interface to Performance Measurement Framework.
4. `pmf_asm_macros.S` consists of macros to facilitate capturing timestamps in
#. ``pmf_asm_macros.S`` consists of macros to facilitate capturing timestamps in
assembly code.
5. `pmf_helpers.h` is an internal header used by `pmf.h`.
#. ``pmf_helpers.h`` is an internal header used by ``pmf.h``.
14. ARMv8 Architecture Extensions
----------------------------------
#. .. rubric:: ARMv8 Architecture Extensions
:name: armv8-architecture-extensions
ARM Trusted Firmware makes use of ARMv8 Architecture Extensions where
applicable. This section lists the usage of Architecture Extensions, and build
flags controlling them.
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
Extensions are backward 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
Architecture Extension-specific code is included in the build. Otherwise, ARM
Trusted Firmware targets the base ARMv8.0 architecture; i.e. as if
`ARM_ARCH_MAJOR` == 8 and `ARM_ARCH_MINOR` == 0, which are also their respective
``ARM_ARCH_MAJOR`` == 8 and ``ARM_ARCH_MINOR`` == 0, which are also their respective
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
to the respective Architecture Extension Supplement.
### ARMv8.1
ARMv8.1
~~~~~~~
This Architecture Extension is targeted when `ARM_ARCH_MAJOR` >= 8, or when
`ARM_ARCH_MAJOR` == 8 and `ARM_ARCH_MINOR` >= 1.
This Architecture Extension is targeted when ``ARM_ARCH_MAJOR`` >= 8, or when
``ARM_ARCH_MAJOR`` == 8 and ``ARM_ARCH_MINOR`` >= 1.
* 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.
15. Code Structure
-------------------
Code Structure
--------------
Trusted Firmware code is logically divided between the three boot loader
stages mentioned in the previous sections. The code is also divided into the
following 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.
* **Common code.** This is platform and architecture agnostic code.
* **Library code.** This code comprises of functionality commonly used by all
- **Common code.** This is platform and architecture agnostic code.
- **Library code.** This code comprises of functionality commonly used by all
other code. The PSCI implementation and other EL3 runtime frameworks reside
as Library components.
* **Stage specific.** Code specific to a boot stage.
* **Drivers.**
* **Services.** EL3 runtime services (eg: SPD). Specific SPD services
reside in the `services/spd` directory (e.g. `services/spd/tspd`).
- **Stage specific.** Code specific to a boot stage.
- **Drivers.**
- **Services.** EL3 runtime services (eg: SPD). Specific SPD services
reside in the ``services/spd`` directory (e.g. ``services/spd/tspd``).
Each boot loader stage uses code from one or more of the above mentioned
categories. Based upon the above, the code layout looks like this:
::
Directory Used by BL1? Used by BL2? Used by BL31?
bl1 Yes No No
bl2 No Yes No
......@@ -2284,43 +2395,46 @@ categories. Based upon the above, the code layout looks like this:
lib Yes Yes Yes
services No No Yes
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
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
defined by the build system. This enables the Trusted Firmware to compile
certain code only for specific boot loader stages
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
linker scripts which have the extension `.ld`.
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
linker scripts which have the extension ``.ld``.
FDTs provide a description of the hardware platform and are used by the Linux
kernel at boot time. These can be found in the `fdts` directory.
kernel at boot time. These can be found in the ``fdts`` directory.
References
----------
16. References
---------------
1. Trusted Board Boot Requirements CLIENT PDD (ARM DEN 0006B-5). Available
.. [#] Trusted Board Boot Requirements CLIENT PDD (ARM DEN 0006B-5). Available
under NDA through your ARM account representative.
2. [Power State Coordination Interface PDD (ARM DEN 0022B.b)][PSCI].
3. [SMC Calling Convention PDD (ARM DEN 0028A)][SMCCC].
4. [ARM Trusted Firmware Interrupt Management Design guide][INTRG].
- - - - - - - - - - - - - - - - - - - - - - - - - -
_Copyright (c) 2013-2016, ARM Limited and Contributors. All rights reserved._
[ARM ARM]: http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0487a.e/index.html "ARMv8-A Reference Manual (ARM DDI0487A.E)"
[PSCI]: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf "Power State Coordination Interface PDD (ARM DEN 0022C)"
[SMCCC]: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html "SMC Calling Convention PDD (ARM DEN 0028A)"
[UUID]: https://tools.ietf.org/rfc/rfc4122.txt "A Universally Unique IDentifier (UUID) URN Namespace"
[User Guide]: ./user-guide.md
[Porting Guide]: ./porting-guide.md
[Reset Design]: ./reset-design.md
[INTRG]: ./interrupt-framework-design.md
[CPUBM]: ./cpu-specific-build-macros.md
[Firmware Update]: ./firmware-update.md
[PSCI Lib guide]: ./psci-lib-integration-guide.md
.. [#] `Power State Coordination Interface PDD`_
.. [#] `SMC Calling Convention PDD`_
.. [#] `ARM Trusted Firmware Interrupt Management Design guide`_.
--------------
*Copyright (c) 2013-2016, ARM Limited and Contributors. All rights reserved.*
.. _Reset Design: ./reset-design.rst
.. _Porting Guide: ./porting-guide.rst
.. _Firmware Update: ./firmware-update.rst
.. _PSCI PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
.. _SMC calling convention PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
.. _PSCI Library integration guide: ./psci-lib-integration-guide.rst
.. _SMCCC: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
.. _Power State Coordination Interface PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
.. _here: ./psci-lib-integration-guide.rst
.. _cpu-specific-build-macros.rst: ./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
.. _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
.. _ARM Trusted Firmware Interrupt Management Design guide: ./interrupt-framework-design.rst
.. |Image 1| image:: diagrams/rt-svc-descs-layout.png?raw=true
docs/firmware-update.md → docs/firmware-update.rst
View file @ 7cefb56d
ARM Trusted Firmware - Firmware Update Design Guide
===================================================
Contents :
1. [Introduction](#1--introduction)
2. [FWU Overview](#2--fwu-overview)
3. [Image Identification](#3--image-identification)
4. [FWU State Machine](#4--fwu-state-machine)
5. [BL1 SMC Interface](#5--bl1-smc-interface)
.. section-numbering::
:suffix: .
- - - - - - - - - - - - - - - - - -
.. contents::
1. Introduction
----------------
--------------
Introduction
------------
This document describes the design of the Firmware Update (FWU) feature, which
enables authenticated firmware to update firmware images from external
......@@ -24,19 +22,19 @@ be complemented by other, higher level firmware update software.
FWU implements a specific part of the Trusted Board Boot Requirements (TBBR)
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.
### Scope
Scope
~~~~~
This document describes the secure world FWU design. It is beyond its scope to
describe how normal world FWU images should operate. To implement normal world
FWU images, please refer to the "Non-Trusted Firmware Updater" requirements in
the TBBR.
2. FWU Overview
----------------
FWU Overview
------------
The FWU boot flow is primarily mediated by BL1. Since BL1 executes in ROM, and
it is usually desirable to minimize the amount of ROM code, the design allows
......@@ -44,65 +42,65 @@ some parts of FWU to be implemented in other secure and normal world images.
Platform code may choose which parts are implemented in which images but the
general expectation is:
* BL1 handles:
* Detection and initiation of the FWU boot flow.
* Copying images from non-secure to secure memory
* FWU image authentication
* Context switching between the normal and secure world during the FWU
- BL1 handles:
- Detection and initiation of the FWU boot flow.
- Copying images from non-secure to secure memory
- FWU image authentication
- Context switching between the normal and secure world during the FWU
process.
* Other secure world FWU images handle platform initialization required by
- Other secure world FWU images handle platform initialization required by
the FWU process.
* Normal world FWU images handle loading of firmware images from external
- Normal world FWU images handle loading of firmware images from external
interfaces to non-secure memory.
The primary requirements of the FWU feature are:
1. Export a BL1 SMC interface to interoperate with other FWU images executing
#. Export a BL1 SMC interface to interoperate with other FWU images executing
at other Exception Levels.
2. Export a platform interface to provide FWU common code with the information
#. Export a platform interface to provide FWU common code with the information
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.
An overview of this terminology can be found [here][TF Image Terminology].
An overview of this terminology can be found `here`_.
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
use all defined FWU images. Other platforms may use a subset of these.
![Flow Diagram](diagrams/fwu_flow.png?raw=true)
|Flow Diagram|
3. Image Identification
------------------------
Image Identification
--------------------
Each FWU image and certificate is identified by a unique ID, defined by the
platform, which BL1 uses to fetch an image descriptor (`image_desc_t`) via a
call to `bl1_plat_get_image_desc()`. The same ID is also used to prepare the
Chain of Trust (Refer to the [Authentication Framework Design][Auth Framework]
platform, which BL1 uses to fetch an image descriptor (``image_desc_t``) via a
call to ``bl1_plat_get_image_desc()``. The same ID is also used to prepare the
Chain of Trust (Refer to the `Authentication Framework Design`_
for more information).
The image descriptor includes the following information:
* Executable or non-executable image. This indicates whether the normal world
- Executable or non-executable image. This indicates whether the normal world
is permitted to request execution of a secure world FWU image (after
authentication). Secure world certificates and non-AP images are examples
of non-executable images.
* Secure or non-secure image. This indicates whether the image is
- Secure or non-secure image. This indicates whether the image is
authenticated/executed in secure or non-secure memory.
* Image base address and size.
* Image entry point configuration (an `entry_point_info_t`).
* FWU image state.
- Image base address and size.
- Image entry point configuration (an ``entry_point_info_t``).
- FWU image state.
BL1 uses the FWU image descriptors to:
* Validate the arguments of FWU SMCs
* Manage the state of the FWU process
* Initialize the execution state of the next FWU image.
- Validate the arguments of FWU SMCs
- Manage the state of the FWU process
- Initialize the execution state of the next FWU image.
4. FWU State Machine
---------------------
FWU State Machine
-----------------
BL1 maintains state for each FWU image during FWU execution. FWU images at lower
Exception Levels raise SMCs to invoke FWU functionality in BL1, which causes
......@@ -110,35 +108,37 @@ BL1 to update its FWU image state. The BL1 image states and valid state
transitions are shown in the diagram below. Note that secure images have a more
complex state machine than non-secure images.
![FWU state machine](diagrams/fwu_states.png?raw=true)
|FWU state machine|
The following is a brief description of the supported states:
* RESET: This is the initial state of every image at the start of FWU.
- RESET: This is the initial state of every image at the start of FWU.
Authentication failure also leads to this state. A secure
image may yield to this state if it has completed execution.
It can also be reached by using `FWU_SMC_IMAGE_RESET`.
It can also be reached by using ``FWU_SMC_IMAGE_RESET``.
* COPYING: This is the state of a secure image while BL1 is copying it
- COPYING: This is the state of a secure image while BL1 is copying it
in blocks from non-secure to secure memory.
* COPIED: This is the state of a secure image when BL1 has completed
- COPIED: This is the state of a secure image when BL1 has completed
copying it to secure memory.
* AUTHENTICATED: This is the state of an image when BL1 has successfully
- AUTHENTICATED: This is the state of an image when BL1 has successfully
authenticated it.
* EXECUTED: This is the state of a secure, executable image when BL1 has
- EXECUTED: This is the state of a secure, executable image when BL1 has
passed execution control to it.
* INTERRUPTED: This is the state of a secure, executable image after it has
- INTERRUPTED: This is the state of a secure, executable image after it has
requested BL1 to resume normal world execution.
BL1 SMC Interface
-----------------
5. BL1 SMC Interface
---------------------
BL1\_SMC\_CALL\_COUNT
~~~~~~~~~~~~~~~~~~~~~
### BL1_SMC_CALL_COUNT
::
Arguments:
uint32_t function ID : 0x0
......@@ -148,7 +148,10 @@ The following is a brief description of the supported states:
This SMC returns the number of SMCs supported by BL1.
### BL1_SMC_UID
BL1\_SMC\_UID
~~~~~~~~~~~~~
::
Arguments:
uint32_t function ID : 0x1
......@@ -156,10 +159,13 @@ This SMC returns the number of SMCs supported by BL1.
Return:
UUID : 32 bits in each of w0-w3 (or r0-r3 for AArch32 callers)
This SMC returns the 128-bit [Universally Unique Identifier][UUID] for the
This SMC returns the 128-bit `Universally Unique Identifier`_ for the
BL1 SMC service.
### BL1_SMC_VERSION
BL1\_SMC\_VERSION
~~~~~~~~~~~~~~~~~
::
Argument:
uint32_t function ID : 0x3
......@@ -170,7 +176,10 @@ BL1 SMC service.
This SMC returns the current version of the BL1 SMC service.
### BL1_SMC_RUN_IMAGE
BL1\_SMC\_RUN\_IMAGE
~~~~~~~~~~~~~~~~~~~~
::
Arguments:
uint32_t function ID : 0x4
......@@ -184,11 +193,13 @@ This SMC returns the current version of the BL1 SMC service.
if (ep_info not EL3) synchronous exception
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 boot flow, BL2 invokes this SMC
for BL1 to pass execution control to BL31.
FWU\_SMC\_IMAGE\_COPY
~~~~~~~~~~~~~~~~~~~~~
### FWU_SMC_IMAGE_COPY
::
Arguments:
uint32_t function ID : 0x10
......@@ -214,16 +225,16 @@ for BL1 to pass execution control to BL31.
if (image_size > free secure memory) return -ENOMEM
if (image overlaps another image) return -EPERM
This SMC copies the secure image indicated by `image_id` from non-secure memory
This SMC copies the secure image indicated by ``image_id`` from non-secure memory
to secure memory for later authentication. The image may be copied in a single
block or multiple blocks. In either case, the total size of the image must be
provided in `image_size` when invoking this SMC for the first time for each
provided in ``image_size`` when invoking this SMC for the first time for each
image; it is ignored in subsequent calls (if any) for the same image.
The `image_addr` and `block_size` specify the source memory block to copy from.
The ``image_addr`` and ``block_size`` specify the source memory block to copy from.
The destination address is provided by the platform code.
If `block_size` is greater than the amount of remaining bytes to copy for this
If ``block_size`` is greater than the amount of remaining bytes to copy for this
image then the former is truncated to the latter. The copy operation is then
considered as complete and the FWU state machine transitions to the "COPIED"
state. If there is still more to copy, the FWU state machine stays in or
......@@ -234,8 +245,10 @@ contiguous memory.
Once the SMC is handled, BL1 returns from exception to the normal world caller.
FWU\_SMC\_IMAGE\_AUTH
~~~~~~~~~~~~~~~~~~~~~
### FWU_SMC_IMAGE_AUTH
::
Arguments:
uint32_t function ID : 0x11
......@@ -262,9 +275,9 @@ Once the SMC is handled, BL1 returns from exception to the normal world caller.
if (image_addr/image_size is in secure memory) return -ENOMEM
if (image_addr/image_size not mappped into BL1) return -ENOMEM
This SMC authenticates the image specified by `image_id`. If the image is in the
RESET state, BL1 authenticates the image in place using the provided
`image_addr` and `image_size`. If the image is a secure image in the COPIED
This SMC authenticates the image specified by ``image_id``. If the image is in the
RESET state, BL1 authenticates the image in place using the provided
``image_addr`` and ``image_size``. If the image is a secure image in the COPIED
state, BL1 authenticates the image from the secure memory that BL1 previously
copied the image into.
......@@ -272,8 +285,10 @@ BL1 returns from exception to the caller. If authentication succeeds then BL1
sets the image state to AUTHENTICATED. If authentication fails then BL1 returns
the -EAUTH error and sets the image state back to RESET.
FWU\_SMC\_IMAGE\_EXECUTE
~~~~~~~~~~~~~~~~~~~~~~~~
### FWU_SMC_IMAGE_EXECUTE
::
Arguments:
uint32_t function ID : 0x12
......@@ -291,15 +306,17 @@ the -EAUTH error and sets the image state back to RESET.
if (image_id state is not AUTHENTICATED) return -EPERM
This SMC initiates execution of a previously authenticated image specified by
`image_id`, in the other security world to the caller. The current
``image_id``, in the other security world to the caller. The current
implementation only supports normal world callers initiating execution of a
secure world image.
BL1 saves the normal world caller's context, sets the secure image state to
EXECUTED, and returns from exception to the secure image.
FWU\_SMC\_IMAGE\_RESUME
~~~~~~~~~~~~~~~~~~~~~~~
### FWU_SMC_IMAGE_RESUME
::
Arguments:
uint32_t function ID : 0x13
......@@ -320,11 +337,13 @@ to EXECUTED. For secure world callers, BL1 sets the previously executing secure
image state to INTERRUPTED. In either case, BL1 saves the calling world's
context, restores the resuming world's context and returns from exception into
the resuming world. If the call is successful then the caller provided
`image_param` is returned to the resumed world, otherwise an error code is
``image_param`` is returned to the resumed world, otherwise an error code is
returned to the caller.
FWU\_SMC\_SEC\_IMAGE\_DONE
~~~~~~~~~~~~~~~~~~~~~~~~~~
### FWU_SMC_SEC_IMAGE_DONE
::
Arguments:
uint32_t function ID : 0x14
......@@ -342,8 +361,10 @@ BL1 sets the previously executing secure image state to the RESET state,
restores the normal world context and returns from exception into the normal
world.
FWU\_SMC\_UPDATE\_DONE
~~~~~~~~~~~~~~~~~~~~~~
### FWU_SMC_UPDATE_DONE
::
Arguments:
uint32_t function ID : 0x15
......@@ -353,11 +374,13 @@ world.
N/A
This SMC completes the firmware update process. BL1 calls the platform specific
function `bl1_plat_fwu_done`, passing the optional argument `client_cookie` as
a `void *`. The SMC does not return.
function ``bl1_plat_fwu_done``, passing the optional argument ``client_cookie`` as
a ``void *``. The SMC does not return.
FWU\_SMC\_IMAGE\_RESET
~~~~~~~~~~~~~~~~~~~~~~
### FWU_SMC_IMAGE_RESET
::
Arguments:
uint32_t function ID : 0x16
......@@ -375,14 +398,15 @@ This SMC sets the state of an image to RESET and zeroes the memory used by it.
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-2017, ARM Limited and Contributors. All rights reserved.*
.. _Trusted Board Boot: ./trusted-board-boot.rst
.. _Porting Guide: ./porting-guide.rst
.. _here: https://github.com/ARM-software/arm-trusted-firmware/wiki/ARM-Trusted-Firmware-Image-Terminology
.. _Authentication Framework Design: ./auth-framework.rst
.. _Universally Unique Identifier: https://tools.ietf.org/rfc/rfc4122.txt
[Porting Guide]: ./porting-guide.md
[Auth Framework]: ./auth-framework.md
[Trusted Board Boot]: ./trusted-board-boot.md
[TF Image Terminology]: https://github.com/ARM-software/arm-trusted-firmware/wiki/ARM-Trusted-Firmware-Image-Terminology
[UUID]: https://tools.ietf.org/rfc/rfc4122.txt "A Universally Unique IDentifier (UUID) URN Namespace"
.. |Flow Diagram| image:: diagrams/fwu_flow.png?raw=true
.. |FWU state machine| image:: diagrams/fwu_states.png?raw=true
docs/interrupt-framework-design.md → docs/interrupt-framework-design.rst
View file @ 7cefb56d
ARM Trusted Firmware Interrupt Management Design guide
======================================================
Contents :
1. [Introduction](#1-introduction)
* [Concepts](#11-concepts)
- [Interrupt Types](#111-interrupt-types)
- [Routing Model](#112-routing-model)
- [Valid Routing Models](#113-valid-routing-models)
+ [Secure-EL1 Interrupts](#1131-secure-el1-interrupts)
+ [Non-secure Interrupts](#1132-non-secure-interrupts)
+ [EL3 interrupts](#1133-el3-interrupts)
- [Mapping of Interrupt Type to Signal](#114-mapping-of-interrupt-type-to-signal)
+ [Effect of mapping of several interrupt types to one signal](#1141-effect-of-mapping-of-several-interrupt-types-to-one-signal)
- [Assumptions in Interrupt Management Framework](#12-assumptions-in-interrupt-management-framework)
2. [Interrupt Management](#2-interrupt-management)
* [Software Components](#21-software-components)
* [Interrupt Registration](#22-interrupt-registration)
- [EL3 Runtime Firmware](#221-el3-runtime-firmware)
- [Secure Payload Dispatcher](#222-secure-payload-dispatcher)
+ [Test Secure Payload Dispatcher behavior](#2221-test-secure-payload-dispatcher-behavior)
- [Secure Payload](#223-secure-payload)
+ [Secure Payload IHF design w.r.t Secure-EL1 interrupts](#2231-secure-payload-ihf-design-wrt-secure-el1-interrupts)
+ [Secure Payload IHF design w.r.t Non-secure interrupts](#2232-secure-payload-ihf-design-wrt-non-secure-interrupts)
+ [Test Secure Payload behavior](#2233-test-secure-payload-behavior)
* [Interrupt Handling](#23-interrupt-handling)
- [EL3 Runtime Firmware](#231-el3-runtime-firmware)
- [Secure Payload Dispatcher](#232-secure-payload-dispatcher)
+ [Interrupt Entry](#2321-interrupt-entry)
+ [Interrupt Exit](#2322-interrupt-exit)
+ [Test secure payload dispatcher Secure-EL1 interrupt handling](#2323-test-secure-payload-dispatcher-secure-el1-interrupt-handling)
+ [Test secure payload dispatcher non-secure interrupt handling](#2324-test-secure-payload-dispatcher-non-secure-interrupt-handling)
- [Secure Payload](#233-secure-payload)
+ [Test Secure Payload behavior](#2331-test-secure-payload-behavior)
3. [Other considerations](#3-other-considerations)
* [Implication of preempted SMC on Non-Secure Software](#31-implication-of-preempted-smc-on-non-secure-software)
1. Introduction
----------------
This document describes the design of the Interrupt management framework in ARM
Trusted Firmware. This section briefly describes the requirements from this
framework. It also briefly explains some concepts and assumptions. They will
help in understanding the implementation of the framework explained in
subsequent sections.
.. section-numbering::
:suffix: .
.. contents::
This framework is responsible for managing interrupts routed to EL3. It also
allows EL3 software to configure the interrupt routing behavior. Its main
objective is to implement the following two requirements.
1. It should be possible to route interrupts meant to be handled by secure
#. It should be possible to route interrupts meant to be handled by secure
software (Secure interrupts) to EL3, when execution is in non-secure state
(normal world). The framework should then take care of handing control of
the interrupt to either software in EL3 or Secure-EL1 depending upon the
......@@ -60,7 +20,7 @@ objective is to implement the following two requirements.
respect to their delivery and handling without the possibility of
intervention from non-secure software.
2. It should be possible to route interrupts meant to be handled by
#. It should be possible to route interrupts meant to be handled by
non-secure software (Non-secure interrupts) to the last executed exception
level in the normal world when the execution is in secure world at
exception levels lower than EL3. This could be done with or without the
......@@ -69,54 +29,61 @@ objective is to implement the following two requirements.
ensures that non-secure software is able to execute in tandem with the
secure software without overriding it.
### 1.1 Concepts
Concepts
--------
Interrupt types
~~~~~~~~~~~~~~~
#### 1.1.1 Interrupt types
The framework categorises an interrupt to be one of the following depending upon
the exception level(s) it is handled in.
1. Secure EL1 interrupt. This type of interrupt can be routed to EL3 or
#. Secure EL1 interrupt. This type of interrupt can be routed to EL3 or
Secure-EL1 depending upon the security state of the current execution
context. It is always handled in Secure-EL1.
2. Non-secure interrupt. This type of interrupt can be routed to EL3,
#. Non-secure interrupt. This type of interrupt can be routed to EL3,
Secure-EL1, Non-secure EL1 or EL2 depending upon the security state of the
current execution context. It is always handled in either Non-secure EL1
or EL2.
3. EL3 interrupt. This type of interrupt can be routed to EL3 or Secure-EL1
#. EL3 interrupt. This type of interrupt can be routed to EL3 or Secure-EL1
depending upon the security state of the current execution context. It is
always handled in EL3.
The following constants define the various interrupt types in the framework
implementation.
::
#define INTR_TYPE_S_EL1 0
#define INTR_TYPE_EL3 1
#define INTR_TYPE_NS 2
Routing model
~~~~~~~~~~~~~
#### 1.1.2 Routing model
A type of interrupt can be either generated as an FIQ or an IRQ. The target
exception level of an interrupt type is configured through the FIQ and IRQ bits
in the Secure Configuration Register at EL3 (`SCR_EL3.FIQ` and `SCR_EL3.IRQ`
bits). When `SCR_EL3.FIQ`=1, FIQs are routed to EL3. Otherwise they are routed
in the Secure Configuration Register at EL3 (``SCR_EL3.FIQ`` and ``SCR_EL3.IRQ``
bits). When ``SCR_EL3.FIQ``\ =1, FIQs are routed to EL3. Otherwise they are routed
to the First Exception Level (FEL) capable of handling interrupts. When
`SCR_EL3.IRQ`=1, IRQs are routed to EL3. Otherwise they are routed to the
``SCR_EL3.IRQ``\ =1, IRQs are routed to EL3. Otherwise they are routed to the
FEL. This register is configured independently by EL3 software for each security
state prior to entry into a lower exception level in that security state.
A routing model for a type of interrupt (generated as FIQ or IRQ) is defined as
its target exception level for each security state. It is represented by a
single bit for each security state. A value of `0` means that the interrupt
should be routed to the FEL. A value of `1` means that the interrupt should be
single bit for each security state. A value of ``0`` means that the interrupt
should be routed to the FEL. A value of ``1`` means that the interrupt should be
routed to EL3. A routing model is applicable only when execution is not in EL3.
The default routing model for an interrupt type is to route it to the FEL in
either security state.
Valid routing models
~~~~~~~~~~~~~~~~~~~~
#### 1.1.3 Valid routing models
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
following sub-sections describe all the possible routing models and specify
......@@ -125,97 +92,99 @@ 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
used in the following sub-sections is explained below.
1. __CSS__. Current Security State. `0` when secure and `1` when non-secure
#. **CSS**. Current Security State. ``0`` when secure and ``1`` when non-secure
2. __TEL3__. Target Exception Level 3. `0` when targeted to the FEL. `1` when
#. **TEL3**. Target Exception Level 3. ``0`` when targeted to the FEL. ``1`` when
targeted to EL3.
Secure-EL1 interrupts
^^^^^^^^^^^^^^^^^^^^^
##### 1.1.3.1 Secure-EL1 interrupts
1. __CSS=0, TEL3=0__. Interrupt is routed to the FEL when execution is in
#. **CSS=0, TEL3=0**. Interrupt is routed to the FEL when execution is in
secure state. This is a valid routing model as secure software is in
control of handling secure interrupts.
2. __CSS=0, TEL3=1__. Interrupt is routed to EL3 when execution is in secure
#. **CSS=0, TEL3=1**. Interrupt is routed to EL3 when execution is in secure
state. This is a valid routing model as secure software in EL3 can
handover the interrupt to Secure-EL1 for handling.
3. __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
is not visible to the secure software which violates the motivation behind
the ARM Security Extensions.
4. __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
can handover the interrupt to Secure-EL1 for handling.
Non-secure interrupts
^^^^^^^^^^^^^^^^^^^^^
##### 1.1.3.2 Non-secure interrupts
1. __CSS=0, TEL3=0__. Interrupt is routed to the FEL when execution is in
#. **CSS=0, TEL3=0**. Interrupt is routed to the FEL when execution is in
secure state. This allows the secure software to trap non-secure
interrupts, perform its book-keeping and hand the interrupt to the
non-secure software through EL3. This is a valid routing model as secure
software is in control of how its execution is preempted by non-secure
interrupts.
2. __CSS=0, TEL3=1__. Interrupt is routed to EL3 when execution is in secure
#. **CSS=0, TEL3=1**. Interrupt is routed to EL3 when execution is in secure
state. This is a valid routing model as secure software in EL3 can save
the state of software in Secure-EL1/Secure-EL0 before handing the
interrupt to non-secure software. This model requires additional
coordination between Secure-EL1 and EL3 software to ensure that the
former's state is correctly saved by the latter.
3. __CSS=1, TEL3=0__. Interrupt is routed to FEL when execution is in
#. **CSS=1, TEL3=0**. Interrupt is routed to FEL when execution is in
non-secure state. This is an valid routing model as a non-secure interrupt
is handled by non-secure software.
4. __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 an invalid routing model as there is no valid
reason to route the interrupt to EL3 software and then hand it back to
non-secure software for handling.
EL3 interrupts
^^^^^^^^^^^^^^
##### 1.1.3.3 EL3 interrupts
1. __CSS=0, TEL3=0__. Interrupt is routed to the FEL when execution is in
#. **CSS=0, TEL3=0**. Interrupt is routed to the FEL when execution is in
Secure-EL1/Secure-EL0. This is a valid routing model as secure software
in Secure-EL1/Secure-EL0 is in control of how its execution is preempted
by EL3 interrupt and can handover the interrupt to EL3 for handling.
2. __CSS=0, TEL3=1__. Interrupt is routed to EL3 when execution is in
#. **CSS=0, TEL3=1**. Interrupt is routed to EL3 when execution is in
Secure-EL1/Secure-EL0. This is a valid routing model as secure software
in EL3 can handle the interrupt.
3. __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
is not visible to the secure software which violates the motivation behind
the ARM Security Extensions.
4. __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
can handle the interrupt.
Mapping of interrupt type to signal
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#### 1.1.4 Mapping of interrupt type to signal
The framework is meant to work with any interrupt controller implemented by a
platform. A interrupt controller could generate a type of interrupt as either an
FIQ or IRQ signal to the CPU depending upon the current security state. The
mapping between the type and signal is known only to the platform. The framework
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
`plat_interrupt_type_to_line()` API (described in the [Porting
Guide]). For example, on the FVP port when the platform uses an ARM GICv2
``plat_interrupt_type_to_line()`` API (described in the
`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
while Non-secure interrupts are signaled through the IRQ signal. This applies
when execution is in either security state.
Effect of mapping of several interrupt types to one signal
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
##### 1.1.4.1 Effect of mapping of several interrupt types to one signal
It should be noted that if more than one interrupt type maps to a single
interrupt signal, and if any one of the interrupt type sets __TEL3=1__ for a
interrupt signal, and if any one of the interrupt type sets **TEL3=1** for a
particular security state, then interrupt signal will be routed to EL3 when in
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
......@@ -224,34 +193,35 @@ borne in mind when choosing the routing model for an interrupt type.
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
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
route the FIQ signal to EL3 when executing in Secure-EL1/Secure-EL0, thereby
effectively routing the other interrupt type also to EL3.
Assumptions in Interrupt Management Framework
---------------------------------------------
### 1.2 Assumptions in Interrupt Management Framework
The framework makes the following assumptions to simplify its implementation.
1. 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
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
handled in Secure-EL1. They can be delivered to Secure-EL1 via EL3 but they
cannot be handled in EL3.
2. Interrupt exceptions (`PSTATE.I` and `F` bits) are masked during execution
#. Interrupt exceptions (``PSTATE.I`` and ``F`` bits) are masked during execution
in EL3.
#. .. rubric:: Interrupt management
:name: interrupt-management
2. Interrupt management
-----------------------
The following sections describe how interrupts are managed by the interrupt
handling framework. This entails:
The following sections describe how interrupts are managed by the interrupt
handling framework. This entails:
1. Providing an interface to allow registration of a handler and specification
#. Providing an interface to allow registration of a handler and specification
of the routing model for a type of interrupt.
2. Implementing support to hand control of an interrupt type to its registered
#. Implementing support to hand control of an interrupt type to its registered
handler when the interrupt is generated.
Both aspects of interrupt management involve various components in the secure
......@@ -259,25 +229,25 @@ software stack spanning from EL3 to Secure-EL1. These components are described
in the section 2.1. The framework stores information associated with each type
of interrupt in the following data structure.
```
typedef struct intr_type_desc {
.. code:: c
typedef struct intr_type_desc {
interrupt_type_handler_t handler;
uint32_t flags;
uint32_t scr_el3[2];
} intr_type_desc_t;
```
} intr_type_desc_t;
The `flags` field stores the routing model for the interrupt type in
The ``flags`` field stores the routing model for the interrupt type in
bits[1:0]. Bit[0] stores the routing model when execution is in the secure
state. Bit[1] stores the routing model when execution is in the non-secure
state. As mentioned in Section 1.2.2, a value of `0` implies that the interrupt
should be targeted to the FEL. A value of `1` implies that it should be targeted
state. As mentioned in Section 1.2.2, a value of ``0`` implies that the interrupt
should be targeted to the FEL. A value of ``1`` implies that it should be targeted
to EL3. The remaining bits are reserved and SBZ. The helper macro
`set_interrupt_rm_flag()` should be used to set the bits in the `flags`
``set_interrupt_rm_flag()`` should be used to set the bits in the ``flags``
parameter.
The `scr_el3[2]` field also stores the routing model but as a mapping of the
model in the `flags` field to the corresponding bit in the `SCR_EL3` for each
The ``scr_el3[2]`` field also stores the routing model but as a mapping of the
model in the ``flags`` field to the corresponding bit in the ``SCR_EL3`` for each
security state.
The framework also depends upon the platform port to configure the interrupt
......@@ -286,7 +256,7 @@ is expected to be aware of the secure devices present in the system and their
associated interrupt numbers. It should configure the interrupt controller to
enable the secure interrupts, ensure that their priority is always higher than
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.
In the remainder of this document, for the sake of simplicity a ARM GICv2 system
......@@ -294,16 +264,17 @@ is considered and it is assumed that the FIQ signal is used to generate Secure-E
interrupts and the IRQ signal is used to generate non-secure interrupts in either
security state. EL3 interrupts are not considered.
Software components
-------------------
### 2.1 Software components
Roles and responsibilities for interrupt management are sub-divided between the
following components of software running in EL3 and Secure-EL1. Each component is
briefly described below.
1. EL3 Runtime Firmware. This component is common to all ports of the ARM
#. EL3 Runtime Firmware. This component is common to all ports of the ARM
Trusted Firmware.
2. 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
responsible for switching execution between secure and non-secure states.
A switch is triggered by a Secure Monitor Call and it uses the APIs
......@@ -316,7 +287,7 @@ briefly described below.
An SPD service plugs into the EL3 runtime firmware and could be common to
some ports of the ARM Trusted Firmware.
3. 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
SPD service to manage communication with non-secure software. ARM Trusted
Firmware implements an example secure payload called Test Secure Payload
......@@ -325,43 +296,47 @@ briefly described below.
A Secure payload implementation could be common to some ports of the ARM
Trusted Firmware just like the SPD service.
Interrupt registration
----------------------
### 2.2 Interrupt registration
This section describes in detail the role of each software component (see 2.1)
during the registration of a handler for an interrupt type.
EL3 runtime firmware
~~~~~~~~~~~~~~~~~~~~
#### 2.2.1 EL3 runtime firmware
This component declares the following prototype for a handler of an interrupt type.
.. code:: c
typedef uint64_t (*interrupt_type_handler_t)(uint32_t id,
uint32_t flags,
void *handle,
void *cookie);
The `id` is parameter is reserved and could be used in the future for passing
The ``id`` is parameter is reserved and could be used in the future for passing
the interrupt id of the highest pending interrupt only if there is a foolproof
way of determining the id. Currently it contains `INTR_ID_UNAVAILABLE`.
way of determining the id. Currently it contains ``INTR_ID_UNAVAILABLE``.
The `flags` parameter contains miscellaneous information as follows.
The ``flags`` parameter contains miscellaneous information as follows.
1. Security state, bit[0]. This bit indicates the security state of the lower
exception level when the interrupt was generated. A value of `1` means
that it was in the non-secure state. A value of `0` indicates that it was
#. Security state, bit[0]. This bit indicates the security state of the lower
exception level when the interrupt was generated. A value of ``1`` means
that it was in the non-secure state. A value of ``0`` indicates that it was
in the secure state. This bit can be used by the handler to ensure that
interrupt was generated and routed as per the routing model specified
during registration.
2. Reserved, bits[31:1]. The remaining bits are reserved for future use.
#. Reserved, bits[31:1]. The remaining bits are reserved for future use.
The `handle` parameter points to the `cpu_context` structure of the current CPU
for the security state specified in the `flags` parameter.
The ``handle`` parameter points to the ``cpu_context`` structure of the current CPU
for the security state specified in the ``flags`` parameter.
Once the handler routine completes, execution will return to either the secure
or non-secure state. The handler routine must return a pointer to
`cpu_context` structure of the current CPU for the target security state. On
``cpu_context`` structure of the current CPU for the target security state. On
AArch64, this return value is currently ignored by the caller as the
appropriate `cpu_context` to be used is expected to be set by the handler
appropriate ``cpu_context`` to be used is expected to be set by the handler
via the context management library APIs.
A portable interrupt handler implementation must set the target context both in
the structure pointed to by the returned pointer and via the context management
......@@ -375,102 +350,109 @@ this API to register a handler for Secure-EL1 and optionally for non-secure
interrupts. This API also requires the caller to specify the routing model for
the type of interrupt.
.. code:: c
int32_t register_interrupt_type_handler(uint32_t type,
interrupt_type_handler handler,
uint64_t flags);
The `type` parameter can be one of the three interrupt types listed above i.e.
`INTR_TYPE_S_EL1`, `INTR_TYPE_NS` & `INTR_TYPE_EL3`. The `flags` parameter
The ``type`` parameter can be one of the three interrupt types listed above i.e.
``INTR_TYPE_S_EL1``, ``INTR_TYPE_NS`` & ``INTR_TYPE_EL3``. The ``flags`` parameter
is as described in Section 2.
The function will return `0` upon a successful registration. It will return
`-EALREADY` in case a handler for the interrupt type has already been
registered. If the `type` is unrecognised or the `flags` or the `handler` are
invalid it will return `-EINVAL`.
The function will return ``0`` upon a successful registration. It will return
``-EALREADY`` in case a handler for the interrupt type has already been
registered. If the ``type`` is unrecognised or the ``flags`` or the ``handler`` are
invalid it will return ``-EINVAL``.
Interrupt routing is governed by the configuration of the `SCR_EL3.FIQ/IRQ` bits
Interrupt routing is governed by the configuration of the ``SCR_EL3.FIQ/IRQ`` bits
prior to entry into a lower exception level in either security state. The
context management library maintains a copy of the `SCR_EL3` system register for
each security state in the `cpu_context` structure of each CPU. It exports the
context management library maintains a copy of the ``SCR_EL3`` system register for
each security state in the ``cpu_context`` structure of each CPU. It exports the
following APIs to let EL3 Runtime Firmware program and retrieve the routing
model for each security state for the current CPU. The value of `SCR_EL3` stored
in the `cpu_context` is used by the `el3_exit()` function to program the
`SCR_EL3` register prior to returning from the EL3 exception level.
model for each security state for the current CPU. The value of ``SCR_EL3`` stored
in the ``cpu_context`` is used by the ``el3_exit()`` function to program the
``SCR_EL3`` register prior to returning from the EL3 exception level.
.. code:: c
uint32_t cm_get_scr_el3(uint32_t security_state);
void cm_write_scr_el3_bit(uint32_t security_state,
uint32_t bit_pos,
uint32_t value);
`cm_get_scr_el3()` returns the value of the `SCR_EL3` register for the specified
security state of the current CPU. `cm_write_scr_el3()` writes a `0` or `1` to
the bit specified by `bit_pos`. `register_interrupt_type_handler()` invokes
`set_routing_model()` API which programs the `SCR_EL3` according to the routing
model using the `cm_get_scr_el3()` and `cm_write_scr_el3_bit()` APIs.
``cm_get_scr_el3()`` returns the value of the ``SCR_EL3`` register for the specified
security state of the current CPU. ``cm_write_scr_el3()`` writes a ``0`` or ``1`` to
the bit specified by ``bit_pos``. ``register_interrupt_type_handler()`` invokes
``set_routing_model()`` API which programs the ``SCR_EL3`` according to the routing
model using the ``cm_get_scr_el3()`` and ``cm_write_scr_el3_bit()`` APIs.
It is worth noting that in the current implementation of the framework, the EL3
runtime firmware is responsible for programming the routing model. The SPD is
responsible for ensuring that the routing model has been adhered to upon
receiving an interrupt.
Secure payload dispatcher
~~~~~~~~~~~~~~~~~~~~~~~~~
#### 2.2.2 Secure payload dispatcher
A SPD service is responsible for determining and maintaining the interrupt
routing model supported by itself and the Secure Payload. It is also responsible
for ferrying interrupts between secure and non-secure software depending upon
the routing model. It could determine the routing model at build time or at
runtime. It must use this information to register a handler for each interrupt
type using the `register_interrupt_type_handler()` API in EL3 runtime firmware.
type using the ``register_interrupt_type_handler()`` API in EL3 runtime firmware.
If the routing model is not known to the SPD service at build time, then it must
be provided by the SP as the result of its initialisation. The SPD should
program the routing model only after SP initialisation has completed e.g. in the
SPD initialisation function pointed to by the `bl32_init` variable.
SPD initialisation function pointed to by the ``bl32_init`` variable.
The SPD should determine the mechanism to pass control to the Secure Payload
after receiving an interrupt from the EL3 runtime firmware. This information
could either be provided to the SPD service at build time or by the SP at
runtime.
Test secure payload dispatcher behavior
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#### 2.2.2.1 Test secure payload dispatcher behavior
The TSPD only handles Secure-EL1 interrupts and is provided with the following
routing model at build time.
* Secure-EL1 interrupts are routed to EL3 when execution is in non-secure
- Secure-EL1 interrupts are routed to EL3 when execution is in non-secure
state and are routed to the FEL when execution is in the secure state
i.e __CSS=0, TEL3=0__ & __CSS=1, TEL3=1__ for Secure-EL1 interrupts
i.e **CSS=0, TEL3=0** & **CSS=1, TEL3=1** for Secure-EL1 interrupts
* When the build flag `TSP_NS_INTR_ASYNC_PREEMPT` is zero, the default routing
- When the build flag ``TSP_NS_INTR_ASYNC_PREEMPT`` is zero, the default routing
model is used for non-secure interrupts. They are routed to the FEL in
either security state i.e __CSS=0, TEL3=0__ & __CSS=1, TEL3=0__ for
either security state i.e **CSS=0, TEL3=0** & **CSS=1, TEL3=0** for
Non-secure interrupts.
* When the build flag `TSP_NS_INTR_ASYNC_PREEMPT` is defined to 1, then the
- When the build flag ``TSP_NS_INTR_ASYNC_PREEMPT`` is defined to 1, then the
non secure interrupts are routed to EL3 when execution is in secure state
i.e __CSS=0, TEL3=1__ for non-secure interrupts. This effectively preempts
i.e **CSS=0, TEL3=1** for non-secure interrupts. This effectively preempts
Secure-EL1. The default routing model is used for non secure interrupts in
non-secure state. i.e __CSS=1, TEL3=0__.
non-secure state. i.e **CSS=1, TEL3=0**.
It performs the following actions in the `tspd_init()` function to fulfill the
It performs the following actions in the ``tspd_init()`` function to fulfill the
requirements mentioned earlier.
1. It passes control to the Test Secure Payload to perform its
#. It passes control to the Test Secure Payload to perform its
initialisation. The TSP provides the address of the vector table
`tsp_vectors` in the SP which also includes the handler for Secure-EL1
interrupts in the `sel1_intr_entry` field. The TSPD passes control to the TSP at
``tsp_vectors`` in the SP which also includes the handler for Secure-EL1
interrupts in the ``sel1_intr_entry`` field. The TSPD passes control to the TSP at
this address when it receives a Secure-EL1 interrupt.
The handover agreement between the TSP and the TSPD requires that the TSPD
masks all interrupts (`PSTATE.DAIF` bits) when it calls
`tsp_sel1_intr_entry()`. The TSP has to preserve the callee saved general
purpose, SP_EL1/Secure-EL0, LR, VFP and system registers. It can use
`x0-x18` to enable its C runtime.
masks all interrupts (``PSTATE.DAIF`` bits) when it calls
``tsp_sel1_intr_entry()``. The TSP has to preserve the callee saved general
purpose, SP\_EL1/Secure-EL0, LR, VFP and system registers. It can use
``x0-x18`` to enable its C runtime.
2. The TSPD implements a handler function for Secure-EL1 interrupts. This
#. The TSPD implements a handler function for Secure-EL1 interrupts. This
function is registered with the EL3 runtime firmware using the
`register_interrupt_type_handler()` API as follows
``register_interrupt_type_handler()`` API as follows
.. code:: c
/* Forward declaration */
interrupt_type_handler tspd_secure_el1_interrupt_handler;
......@@ -482,10 +464,12 @@ requirements mentioned earlier.
if (rc)
panic();
3. When the build flag `TSP_NS_INTR_ASYNC_PREEMPT` is defined to 1, the TSPD
#. When the build flag ``TSP_NS_INTR_ASYNC_PREEMPT`` is defined to 1, the TSPD
implements a handler function for non-secure interrupts. This function is
registered with the EL3 runtime firmware using the
`register_interrupt_type_handler()` API as follows
``register_interrupt_type_handler()`` API as follows
.. code:: c
/* Forward declaration */
interrupt_type_handler tspd_ns_interrupt_handler;
......@@ -497,25 +481,26 @@ requirements mentioned earlier.
if (rc)
panic();
Secure payload
~~~~~~~~~~~~~~
#### 2.2.3 Secure payload
A Secure Payload must implement an interrupt handling framework at Secure-EL1
(Secure-EL1 IHF) to support its chosen interrupt routing model. Secure payload
execution will alternate between the below cases.
1. In the code where IRQ, FIQ or both interrupts are enabled, if an interrupt
#. In the code where IRQ, FIQ or both interrupts are enabled, if an interrupt
type is targeted to the FEL, then it will be routed to the Secure-EL1
exception vector table. This is defined as the __asynchronous mode__ of
exception vector table. This is defined as the **asynchronous mode** of
handling interrupts. This mode applies to both Secure-EL1 and non-secure
interrupts.
2. In the code where both interrupts are disabled, if an interrupt type is
#. In the code where both interrupts are disabled, if an interrupt type is
targeted to the FEL, then execution will eventually migrate to the
non-secure state. Any non-secure interrupts will be handled as described
in the routing model where __CSS=1 and TEL3=0__. Secure-EL1 interrupts
will be routed to EL3 (as per the routing model where __CSS=1 and
TEL3=1__) where the SPD service will hand them to the SP. This is defined
as the __synchronous mode__ of handling interrupts.
in the routing model where **CSS=1 and TEL3=0**. Secure-EL1 interrupts
will be routed to EL3 (as per the routing model where **CSS=1 and
TEL3=1**) where the SPD service will hand them to the SP. This is defined
as the **synchronous mode** of handling interrupts.
The interrupt handling framework implemented by the SP should support one or
both these interrupt handling models depending upon the chosen routing model.
......@@ -530,35 +515,37 @@ As mentioned earlier, a ARM GICv2 system 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 security state.
Secure payload IHF design w.r.t secure-EL1 interrupts
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
##### 2.2.3.1 Secure payload IHF design w.r.t secure-EL1 interrupts
1. __CSS=0, TEL3=0__. If `PSTATE.F=0`, Secure-EL1 interrupts will be
#. **CSS=0, TEL3=0**. If ``PSTATE.F=0``, Secure-EL1 interrupts will be
triggered at one of the Secure-EL1 FIQ exception vectors. The Secure-EL1
IHF should implement support for handling FIQ interrupts asynchronously.
If `PSTATE.F=1` then Secure-EL1 interrupts will be handled as per the
If ``PSTATE.F=1`` then Secure-EL1 interrupts will be handled as per the
synchronous interrupt handling model. The SP could implement this scenario
by exporting a separate entrypoint for Secure-EL1 interrupts to the SPD
service during the registration phase. The SPD service would also need to
know the state of the system, general purpose and the `PSTATE` registers
know the state of the system, general purpose and the ``PSTATE`` registers
in which it should arrange to return execution to the SP. The SP should
provide this information in an implementation defined way during the
registration phase if it is not known to the SPD service at build time.
2. __CSS=1, TEL3=1__. Interrupts are routed to EL3 when execution is in
#. **CSS=1, TEL3=1**. Interrupts are routed to EL3 when execution is in
non-secure state. They should be handled through the synchronous interrupt
handling model as described in 1. above.
3. __CSS=0, TEL3=1__. Secure-EL1 interrupts are routed to EL3 when execution
is in secure state. They will not be visible to the SP. The `PSTATE.F` bit
#. **CSS=0, TEL3=1**. Secure-EL1 interrupts are routed to EL3 when execution
is in secure state. They will not be visible to the SP. The ``PSTATE.F`` bit
in Secure-EL1/Secure-EL0 will not mask FIQs. The EL3 runtime firmware will
call the handler registered by the SPD service for Secure-EL1 interrupts.
Secure-EL1 IHF should then handle all Secure-EL1 interrupt through the
synchronous interrupt handling model described in 1. above.
Secure payload IHF design w.r.t non-secure interrupts
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
##### 2.2.3.2 Secure payload IHF design w.r.t non-secure interrupts
1. __CSS=0, TEL3=0__. If `PSTATE.I=0`, non-secure interrupts will be
#. **CSS=0, TEL3=0**. If ``PSTATE.I=0``, non-secure interrupts will be
triggered at one of the Secure-EL1 IRQ exception vectors . The Secure-EL1
IHF should co-ordinate with the SPD service to transfer execution to the
non-secure state where the interrupt should be handled e.g the SP could
......@@ -568,17 +555,17 @@ is used to generate non-secure interrupts in either security state.
service at compile time then the SP could provide it during the
registration phase.
If `PSTATE.I=1` then the non-secure interrupt will pend until execution
If ``PSTATE.I=1`` then the non-secure interrupt will pend until execution
resumes in the non-secure state.
2. __CSS=0, TEL3=1__. Non-secure interrupts are routed to EL3. They will not
be visible to the SP. The `PSTATE.I` bit in Secure-EL1/Secure-EL0 will
#. **CSS=0, TEL3=1**. Non-secure interrupts are routed to EL3. They will not
be visible to the SP. The ``PSTATE.I`` bit in Secure-EL1/Secure-EL0 will
have not effect. The SPD service should register a non-secure interrupt
handler which should save the SP state correctly and resume execution in
the non-secure state where the interrupt will be handled. The Secure-EL1
IHF does not need to take any action.
3. __CSS=1, TEL3=0__. Non-secure interrupts are handled in the FEL in
#. **CSS=1, TEL3=0**. Non-secure interrupts are handled in the FEL in
non-secure state (EL1/EL2) and are not visible to the SP. This routing
model does not affect the SP behavior.
......@@ -587,104 +574,113 @@ configured at the interrupt controller by the platform port of the EL3 runtime
firmware. It should configure any additional Secure-EL1 interrupts which the EL3
runtime firmware is not aware of through its platform port.
Test secure payload behavior
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#### 2.2.3.3 Test secure payload behavior
The routing model for Secure-EL1 and non-secure interrupts chosen by the TSP is
described in Section 2.2.2. It is known to the TSPD service at build time.
The TSP implements an entrypoint (`tsp_sel1_intr_entry()`) for handling Secure-EL1
The TSP implements an entrypoint (``tsp_sel1_intr_entry()``) for handling Secure-EL1
interrupts taken in non-secure state and routed through the TSPD service
(synchronous handling model). It passes the reference to this entrypoint via
`tsp_vectors` to the TSPD service.
``tsp_vectors`` to the TSPD service.
The TSP also replaces the default exception vector table referenced through the
`early_exceptions` variable, with a vector table capable of handling FIQ and IRQ
``early_exceptions`` variable, with a vector table capable of handling FIQ and IRQ
exceptions taken at the same (Secure-EL1) exception level. This table is
referenced through the `tsp_exceptions` variable and programmed into the
VBAR_EL1. It caters for the asynchronous handling model.
referenced through the ``tsp_exceptions`` variable and programmed into the
VBAR\_EL1. It caters for the asynchronous handling model.
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
interrupt management across all the software components listed in 2.1
Interrupt handling
------------------
### 2.3 Interrupt handling
This section describes in detail the role of each software component (see
Section 2.1) in handling an interrupt of a particular type.
EL3 runtime firmware
~~~~~~~~~~~~~~~~~~~~
#### 2.3.1 EL3 runtime firmware
The EL3 runtime firmware populates the IRQ and FIQ exception vectors referenced
by the `runtime_exceptions` variable as follows.
by the ``runtime_exceptions`` variable as follows.
1. IRQ and FIQ exceptions taken from the current exception level with
`SP_EL0` or `SP_EL3` are reported as irrecoverable error conditions. As
#. IRQ and FIQ exceptions taken from the current exception level with
``SP_EL0`` or ``SP_EL3`` are reported as irrecoverable error conditions. As
mentioned earlier, EL3 runtime firmware always executes with the
`PSTATE.I` and `PSTATE.F` bits set.
``PSTATE.I`` and ``PSTATE.F`` bits set.
2. The following text describes how the IRQ and FIQ exceptions taken from a
#. The following text describes how the IRQ and FIQ exceptions taken from a
lower exception level using AArch64 or AArch32 are handled.
When an interrupt is generated, the vector for each interrupt type is
responsible for:
1. Saving the entire general purpose register context (x0-x30) immediately
upon exception entry. The registers are saved in the per-cpu `cpu_context`
data structure referenced by the `SP_EL3`register.
#. Saving the entire general purpose register context (x0-x30) immediately
upon exception entry. The registers are saved in the per-cpu ``cpu_context``
data structure referenced by the ``SP_EL3``\ register.
2. Saving the `ELR_EL3`, `SP_EL0` and `SPSR_EL3` system registers in the
per-cpu `cpu_context` data structure referenced by the `SP_EL3` register.
#. Saving the ``ELR_EL3``, ``SP_EL0`` and ``SPSR_EL3`` system registers in the
per-cpu ``cpu_context`` data structure referenced by the ``SP_EL3`` register.
3. Switching to the C runtime stack by restoring the `CTX_RUNTIME_SP` value
from the per-cpu `cpu_context` data structure in `SP_EL0` and
executing the `msr spsel, #0` instruction.
#. Switching to the C runtime stack by restoring the ``CTX_RUNTIME_SP`` value
from the per-cpu ``cpu_context`` data structure in ``SP_EL0`` and
executing the ``msr spsel, #0`` instruction.
4. Determining the type of interrupt. Secure-EL1 interrupts will be signaled
#. Determining the type of interrupt. Secure-EL1 interrupts will be signaled
at the FIQ vector. Non-secure interrupts will be signaled at the IRQ
vector. The platform should implement the following API to determine the
type of the pending interrupt.
.. code:: c
uint32_t plat_ic_get_interrupt_type(void);
It should return either `INTR_TYPE_S_EL1` or `INTR_TYPE_NS`.
It should return either ``INTR_TYPE_S_EL1`` or ``INTR_TYPE_NS``.
5. Determining the handler for the type of interrupt that has been generated.
#. Determining the handler for the type of interrupt that has been generated.
The following API has been added for this purpose.
.. code:: c
interrupt_type_handler get_interrupt_type_handler(uint32_t interrupt_type);
It returns the reference to the registered handler for this interrupt
type. The `handler` is retrieved from the `intr_type_desc_t` structure as
described in Section 2. `NULL` is returned if no handler has been
type. The ``handler`` is retrieved from the ``intr_type_desc_t`` structure as
described in Section 2. ``NULL`` is returned if no handler has been
registered for this type of interrupt. This scenario is reported as an
irrecoverable error condition.
6. Calling the registered handler function for the interrupt type generated.
The `id` parameter is set to `INTR_ID_UNAVAILABLE` currently. The id along
with the current security state and a reference to the `cpu_context_t`
#. Calling the registered handler function for the interrupt type generated.
The ``id`` parameter is set to ``INTR_ID_UNAVAILABLE`` currently. The id along
with the current security state and a reference to the ``cpu_context_t``
structure for the current security state are passed to the handler function
as its arguments.
The handler function returns a reference to the per-cpu `cpu_context_t`
The handler function returns a reference to the per-cpu ``cpu_context_t``
structure for the target security state.
7. Calling `el3_exit()` to return from EL3 into a lower exception level in
the security state determined by the handler routine. The `el3_exit()`
#. Calling ``el3_exit()`` to return from EL3 into a lower exception level in
the security state determined by the handler routine. The ``el3_exit()``
function is responsible for restoring the register context from the
`cpu_context_t` data structure for the target security state.
``cpu_context_t`` data structure for the target security state.
Secure payload dispatcher
~~~~~~~~~~~~~~~~~~~~~~~~~
#### 2.3.2 Secure payload dispatcher
Interrupt entry
^^^^^^^^^^^^^^^
##### 2.3.2.1 Interrupt entry
The SPD service begins handling an interrupt when the EL3 runtime firmware calls
the handler function for that type of interrupt. The SPD service is responsible
for the following:
1. Validating the interrupt. This involves ensuring that the interrupt was
#. Validating the interrupt. This involves ensuring that the interrupt was
generating according to the interrupt routing model specified by the SPD
service during registration. It should use the security state of the
exception level (passed in the `flags` parameter of the handler) where
exception level (passed in the ``flags`` parameter of the handler) where
the interrupt was taken from to determine this. If the interrupt is not
recognised then the handler should treat it as an irrecoverable error
condition.
......@@ -696,23 +692,23 @@ for the following:
S-EL1 interrupt should never be routed to EL3 from secure state. The handler
could use the security state flag to check this.
2. Determining whether a context switch is required. This depends upon the
#. Determining whether a context switch is required. This depends upon the
routing model and interrupt type. For non secure and S-EL1 interrupt,
if the security state of the execution context where the interrupt was
generated is not the same as the security state required for handling
the interrupt, a context switch is required. The following 2 cases
require a context switch from secure to non-secure or vice-versa:
1. A Secure-EL1 interrupt taken from the non-secure state should be
#. A Secure-EL1 interrupt taken from the non-secure state should be
routed to the Secure Payload.
2. A non-secure interrupt taken from the secure state should be routed
#. A non-secure interrupt taken from the secure state should be routed
to the last known non-secure exception level.
The SPD service must save the system register context of the current
security state. It must then restore the system register context of the
target security state. It should use the `cm_set_next_eret_context()` API
to ensure that the next `cpu_context` to be restored is of the target
target security state. It should use the ``cm_set_next_eret_context()`` API
to ensure that the next ``cpu_context`` to be restored is of the target
security state.
If the target state is secure then execution should be handed to the SP as
......@@ -723,7 +719,7 @@ for the following:
service should be able to handle this preemption or manage secure interrupt
priorities before handing control to the SP.
3. Setting the return value of the handler to the per-cpu `cpu_context` if
#. Setting the return value of the handler to the per-cpu ``cpu_context`` if
the interrupt has been successfully validated and ready to be handled at a
lower exception level.
......@@ -734,47 +730,49 @@ exception level in the non-secure state. The former should save the SP context,
restore the non-secure context and arrange for entry into the non-secure state
so that the interrupt can be handled.
Interrupt exit
^^^^^^^^^^^^^^
##### 2.3.2.2 Interrupt exit
When the Secure Payload has finished handling a Secure-EL1 interrupt, it could
return control back to the SPD service through a SMC32 or SMC64. The SPD service
should handle this secure monitor call so that execution resumes in the
exception level and the security state from where the Secure-EL1 interrupt was
originally taken.
Test secure payload dispatcher Secure-EL1 interrupt handling
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
##### 2.3.2.3 Test secure payload dispatcher Secure-EL1 interrupt handling
The example TSPD service registers a handler for Secure-EL1 interrupts taken
from the non-secure state. During execution in S-EL1, the TSPD expects that the
Secure-EL1 interrupts are handled in S-EL1 by TSP. Its handler
`tspd_secure_el1_interrupt_handler()` expects only to be invoked for Secure-EL1
``tspd_secure_el1_interrupt_handler()`` expects only to be invoked for Secure-EL1
originating from the non-secure state. It takes the following actions upon being
invoked.
1. It uses the security state provided in the `flags` parameter to ensure
#. It uses the security state provided in the ``flags`` parameter to ensure
that the secure interrupt originated from the non-secure state. It asserts
if this is not the case.
2. It saves the system register context for the non-secure state by calling
`cm_el1_sysregs_context_save(NON_SECURE);`.
#. It saves the system register context for the non-secure state by calling
``cm_el1_sysregs_context_save(NON_SECURE);``.
3. It sets the `ELR_EL3` system register to `tsp_sel1_intr_entry` and sets the
`SPSR_EL3.DAIF` bits in the secure CPU context. It sets `x0` to
`TSP_HANDLE_SEL1_INTR_AND_RETURN`. If the TSP was preempted earlier by a non
secure interrupt during `yielding` SMC processing, save the registers that
will be trashed, which is the `ELR_EL3` and `SPSR_EL3`, in order to be able
#. It sets the ``ELR_EL3`` system register to ``tsp_sel1_intr_entry`` and sets the
``SPSR_EL3.DAIF`` bits in the secure CPU context. It sets ``x0`` to
``TSP_HANDLE_SEL1_INTR_AND_RETURN``. If the TSP was preempted earlier by a non
secure interrupt during ``yielding`` SMC processing, save the registers that
will be trashed, which is the ``ELR_EL3`` and ``SPSR_EL3``, in order to be able
to re-enter TSP for Secure-EL1 interrupt processing. It does not need to
save any other secure context since the TSP is expected to preserve it
(see Section 2.2.2.1).
4. It restores the system register context for the secure state by calling
`cm_el1_sysregs_context_restore(SECURE);`.
#. It restores the system register context for the secure state by calling
``cm_el1_sysregs_context_restore(SECURE);``.
5. It ensures that the secure CPU context is used to program the next
exception return from EL3 by calling `cm_set_next_eret_context(SECURE);`.
#. It ensures that the secure CPU context is used to program the next
exception return from EL3 by calling ``cm_set_next_eret_context(SECURE);``.
6. It returns the per-cpu `cpu_context` to indicate that the interrupt can
now be handled by the SP. `x1` is written with the value of `elr_el3`
#. It returns the per-cpu ``cpu_context`` to indicate that the interrupt can
now be handled by the SP. ``x1`` is written with the value of ``elr_el3``
register for the non-secure state. This information is used by the SP for
debugging purposes.
......@@ -782,113 +780,115 @@ The figure below describes how the interrupt handling is implemented by the TSPD
when a Secure-EL1 interrupt is generated when execution is in the non-secure
state.
![Image 1](diagrams/sec-int-handling.png?raw=true)
|Image 1|
The TSP issues an SMC with `TSP_HANDLED_S_EL1_INTR` as the function identifier to
The TSP issues an SMC with ``TSP_HANDLED_S_EL1_INTR`` as the function identifier to
signal completion of interrupt handling.
The TSPD service takes the following actions in `tspd_smc_handler()` function
upon receiving an SMC with `TSP_HANDLED_S_EL1_INTR` as the function identifier:
The TSPD service takes the following actions in ``tspd_smc_handler()`` function
upon receiving an SMC with ``TSP_HANDLED_S_EL1_INTR`` as the function identifier:
1. It ensures that the call originated from the secure state otherwise
execution returns to the non-secure state with `SMC_UNK` in `x0`.
#. It ensures that the call originated from the secure state otherwise
execution returns to the non-secure state with ``SMC_UNK`` in ``x0``.
2. It restores the saved `ELR_EL3` and `SPSR_EL3` system registers back to
#. It restores the saved ``ELR_EL3`` and ``SPSR_EL3`` system registers back to
the secure CPU context (see step 3 above) in case the TSP had been preempted
by a non secure interrupt earlier.
3. It restores the system register context for the non-secure state by
calling `cm_el1_sysregs_context_restore(NON_SECURE)`.
#. It restores the system register context for the non-secure state by
calling ``cm_el1_sysregs_context_restore(NON_SECURE)``.
4. It ensures that the non-secure CPU context is used to program the next
exception return from EL3 by calling `cm_set_next_eret_context(NON_SECURE)`.
#. It ensures that the non-secure CPU context is used to program the next
exception return from EL3 by calling ``cm_set_next_eret_context(NON_SECURE)``.
5. `tspd_smc_handler()` returns a reference to the non-secure `cpu_context`
#. ``tspd_smc_handler()`` returns a reference to the non-secure ``cpu_context``
as the return value.
Test secure payload dispatcher non-secure interrupt handling
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
##### 2.3.2.4 Test secure payload dispatcher non-secure interrupt handling
The TSP in Secure-EL1 can be preempted by a non-secure interrupt during
`yielding` SMC processing or by a higher priority EL3 interrupt during
``yielding`` SMC processing or by a higher priority EL3 interrupt during
Secure-EL1 interrupt processing. Currently only non-secure interrupts can
cause preemption of TSP since there are no EL3 interrupts in the
system.
It should be noted that while TSP is preempted, the TSPD only allows entry into
the TSP either for Secure-EL1 interrupt handling or for resuming the preempted
`yielding` SMC in response to the `TSP_FID_RESUME` SMC from the normal world.
``yielding`` SMC in response to the ``TSP_FID_RESUME`` SMC from the normal world.
(See Section 3).
The non-secure interrupt triggered in Secure-EL1 during `yielding` SMC processing
The non-secure interrupt triggered in Secure-EL1 during ``yielding`` SMC processing
can be routed to either EL3 or Secure-EL1 and is controlled by build option
`TSP_NS_INTR_ASYNC_PREEMPT` (see Section 2.2.2.1). If the build option is set,
``TSP_NS_INTR_ASYNC_PREEMPT`` (see Section 2.2.2.1). If the build option is set,
the TSPD will set the routing model for the non-secure interrupt to be routed to
EL3 from secure state i.e. __TEL3=1, CSS=0__ and registers
`tspd_ns_interrupt_handler()` as the non-secure interrupt handler. The
`tspd_ns_interrupt_handler()` on being invoked ensures that the interrupt
EL3 from secure state i.e. **TEL3=1, CSS=0** and registers
``tspd_ns_interrupt_handler()`` as the non-secure interrupt handler. The
``tspd_ns_interrupt_handler()`` on being invoked ensures that the interrupt
originated from the secure state and disables routing of non-secure interrupts
from secure state to EL3. This is to prevent further preemption (by a non-secure
interrupt) when TSP is reentered for handling Secure-EL1 interrupts that
triggered while execution was in the normal world. The
`tspd_ns_interrupt_handler()` then invokes `tspd_handle_sp_preemption()` for
``tspd_ns_interrupt_handler()`` then invokes ``tspd_handle_sp_preemption()`` for
further handling.
If the `TSP_NS_INTR_ASYNC_PREEMPT` build option is zero (default), the default
If the ``TSP_NS_INTR_ASYNC_PREEMPT`` build option is zero (default), the default
routing model for non-secure interrupt in secure state is in effect
i.e. __TEL3=0, CSS=0__. During `yielding` SMC processing, the IRQ
exceptions are unmasked i.e. `PSTATE.I=0`, and a non-secure interrupt will
i.e. **TEL3=0, CSS=0**. During ``yielding`` SMC processing, the IRQ
exceptions are unmasked i.e. ``PSTATE.I=0``, and a non-secure interrupt will
trigger at Secure-EL1 IRQ exception vector. The TSP saves the general purpose
register context and issues an SMC with `TSP_PREEMPTED` as the function
register context and issues an SMC with ``TSP_PREEMPTED`` as the function
identifier to signal preemption of TSP. The TSPD SMC handler,
`tspd_smc_handler()`, ensures that the SMC call originated from the
``tspd_smc_handler()``, ensures that the SMC call originated from the
secure state otherwise execution returns to the non-secure state with
`SMC_UNK` in `x0`. It then invokes `tspd_handle_sp_preemption()` for
``SMC_UNK`` in ``x0``. It then invokes ``tspd_handle_sp_preemption()`` for
further handling.
The `tspd_handle_sp_preemption()` takes the following actions upon being
The ``tspd_handle_sp_preemption()`` takes the following actions upon being
invoked:
1. It saves the system register context for the secure state by calling
`cm_el1_sysregs_context_save(SECURE)`.
#. It saves the system register context for the secure state by calling
``cm_el1_sysregs_context_save(SECURE)``.
2. It restores the system register context for the non-secure state by
calling `cm_el1_sysregs_context_restore(NON_SECURE)`.
#. It restores the system register context for the non-secure state by
calling ``cm_el1_sysregs_context_restore(NON_SECURE)``.
3. It ensures that the non-secure CPU context is used to program the next
exception return from EL3 by calling `cm_set_next_eret_context(NON_SECURE)`.
#. It ensures that the non-secure CPU context is used to program the next
exception return from EL3 by calling ``cm_set_next_eret_context(NON_SECURE)``.
4. `SMC_PREEMPTED` is set in x0 and return to non secure state after
#. ``SMC_PREEMPTED`` is set in x0 and return to non secure state after
restoring non secure context.
The Normal World is expected to resume the TSP after the `yielding` SMC preemption
by issuing an SMC with `TSP_FID_RESUME` as the function identifier (see section 3).
The TSPD service takes the following actions in `tspd_smc_handler()` function
The Normal World is expected to resume the TSP after the ``yielding`` SMC preemption
by issuing an SMC with ``TSP_FID_RESUME`` as the function identifier (see section 3).
The TSPD service takes the following actions in ``tspd_smc_handler()`` function
upon receiving this SMC:
1. It ensures that the call originated from the non secure state. An
#. It ensures that the call originated from the non secure state. An
assertion is raised otherwise.
2. Checks whether the TSP needs a resume i.e check if it was preempted. It
#. Checks whether the TSP needs a resume i.e check if it was preempted. It
then saves the system register context for the non-secure state by calling
`cm_el1_sysregs_context_save(NON_SECURE)`.
``cm_el1_sysregs_context_save(NON_SECURE)``.
3. Restores the secure context by calling
`cm_el1_sysregs_context_restore(SECURE)`
#. Restores the secure context by calling
``cm_el1_sysregs_context_restore(SECURE)``
4. It ensures that the secure CPU context is used to program the next
exception return from EL3 by calling `cm_set_next_eret_context(SECURE)`.
#. It ensures that the secure CPU context is used to program the next
exception return from EL3 by calling ``cm_set_next_eret_context(SECURE)``.
5. `tspd_smc_handler()` returns a reference to the secure `cpu_context` as the
#. ``tspd_smc_handler()`` returns a reference to the secure ``cpu_context`` as the
return value.
The figure below describes how the TSP/TSPD handle a non-secure interrupt when
it is generated during execution in the TSP with `PSTATE.I` = 0 when the
`TSP_NS_INTR_ASYNC_PREEMPT` build flag is 0.
it is generated during execution in the TSP with ``PSTATE.I`` = 0 when the
``TSP_NS_INTR_ASYNC_PREEMPT`` build flag is 0.
![Image 2](diagrams/non-sec-int-handling.png?raw=true)
|Image 2|
Secure payload
~~~~~~~~~~~~~~
#### 2.3.3 Secure payload
The SP should implement one or both of the synchronous and asynchronous
interrupt handling models depending upon the interrupt routing model it has
chosen (as described in 2.2.3).
......@@ -897,76 +897,80 @@ In the synchronous model, it should begin handling a Secure-EL1 interrupt after
receiving control from the SPD service at an entrypoint agreed upon during build
time or during the registration phase. Before handling the interrupt, the SP
should save any Secure-EL1 system register context which is needed for resuming
normal execution in the SP later e.g. `SPSR_EL1, `ELR_EL1`. After handling the
normal execution in the SP later e.g. ``SPSR_EL1,``\ ELR\_EL1\`. After handling the
interrupt, the SP could return control back to the exception level and security
state where the interrupt was originally taken from. The SP should use an SMC32
or SMC64 to ask the SPD service to do this.
In the asynchronous model, the Secure Payload is responsible for handling
non-secure and Secure-EL1 interrupts at the IRQ and FIQ vectors in its exception
vector table when `PSTATE.I` and `PSTATE.F` bits are 0. As described earlier,
vector table when ``PSTATE.I`` and ``PSTATE.F`` bits are 0. As described earlier,
when a non-secure interrupt is generated, the SP should coordinate with the SPD
service to pass control back to the non-secure state in the last known exception
level. This will allow the non-secure interrupt to be handled in the non-secure
state.
Test secure payload behavior
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
##### 2.3.3.1 Test secure payload behavior
The TSPD hands control of a Secure-EL1 interrupt to the TSP at the
`tsp_sel1_intr_entry()`. The TSP handles the interrupt while ensuring that the
``tsp_sel1_intr_entry()``. The TSP handles the interrupt while ensuring that the
handover agreement described in Section 2.2.2.1 is maintained. It updates some
statistics by calling `tsp_update_sync_sel1_intr_stats()`. It then calls
`tsp_common_int_handler()` which.
statistics by calling ``tsp_update_sync_sel1_intr_stats()``. It then calls
``tsp_common_int_handler()`` which.
1. Checks whether the interrupt is the secure physical timer interrupt. It
uses the platform API `plat_ic_get_pending_interrupt_id()` to get the
#. Checks whether the interrupt is the secure physical timer interrupt. It
uses the platform API ``plat_ic_get_pending_interrupt_id()`` to get the
interrupt number. If it is not the secure physical timer interrupt, then
that means that a higher priority interrupt has preempted it. Invoke
`tsp_handle_preemption()` to handover control back to EL3 by issuing
an SMC with `TSP_PREEMPTED` as the function identifier.
``tsp_handle_preemption()`` to handover control back to EL3 by issuing
an SMC with ``TSP_PREEMPTED`` as the function identifier.
2. Handles the secure timer interrupt interrupt by acknowledging it using the
`plat_ic_acknowledge_interrupt()` platform API, calling
`tsp_generic_timer_handler()` to reprogram the secure physical generic
timer and calling the `plat_ic_end_of_interrupt()` platform API to signal
#. Handles the secure timer interrupt interrupt by acknowledging it using the
``plat_ic_acknowledge_interrupt()`` platform API, calling
``tsp_generic_timer_handler()`` to reprogram the secure physical generic
timer and calling the ``plat_ic_end_of_interrupt()`` platform API to signal
end of interrupt processing.
The TSP passes control back to the TSPD by issuing an SMC64 with
`TSP_HANDLED_S_EL1_INTR` as the function identifier.
``TSP_HANDLED_S_EL1_INTR`` as the function identifier.
The TSP handles interrupts under the asynchronous model as follows.
1. Secure-EL1 interrupts are handled by calling the `tsp_common_int_handler()`
#. Secure-EL1 interrupts are handled by calling the ``tsp_common_int_handler()``
function. The function has been described above.
2. Non-secure interrupts are handled by by calling the `tsp_common_int_handler()`
function which ends up invoking `tsp_handle_preemption()` and issuing an
SMC64 with `TSP_PREEMPTED` as the function identifier. Execution resumes at
#. Non-secure interrupts are handled by by calling the ``tsp_common_int_handler()``
function which ends up invoking ``tsp_handle_preemption()`` and issuing an
SMC64 with ``TSP_PREEMPTED`` as the function identifier. Execution resumes at
the instruction that follows this SMC instruction when the TSPD hands
control to the TSP in response to an SMC with `TSP_FID_RESUME` as the
control to the TSP in response to an SMC with ``TSP_FID_RESUME`` as the
function identifier from the non-secure state (see section 2.3.2.4).
#. .. rubric:: Other considerations
:name: other-considerations
3. Other considerations
-----------------------
Implication of preempted SMC on Non-Secure Software
---------------------------------------------------
### 3.1 Implication of preempted SMC on Non-Secure Software
A `yielding` SMC call to Secure payload can be preempted by a non-secure
A ``yielding`` SMC call to Secure payload can be preempted by a non-secure
interrupt and the execution can return to the non-secure world for handling
the interrupt (For details on `yielding` SMC refer [SMC calling convention]).
the interrupt (For details on ``yielding`` SMC refer `SMC calling convention`_).
In this case, the SMC call has not completed its execution and the execution
must return back to the secure payload to resume the preempted SMC call.
This can be achieved by issuing an SMC call which instructs to resume the
preempted SMC.
A `fast` SMC cannot be preempted and hence this case will not happen for
A ``fast`` SMC cannot be preempted and hence this case will not happen for
a fast SMC call.
In the Test Secure Payload implementation, `TSP_FID_RESUME` is designated
as the resume SMC FID. It is important to note that `TSP_FID_RESUME` is a
`yielding` SMC which means it too can be be preempted. The typical non
secure software sequence for issuing a `yielding` SMC would look like this,
assuming `P.STATE.I=0` in the non secure state :
In the Test Secure Payload implementation, ``TSP_FID_RESUME`` is designated
as the resume SMC FID. It is important to note that ``TSP_FID_RESUME`` is a
``yielding`` SMC which means it too can be be preempted. The typical non
secure software sequence for issuing a ``yielding`` SMC would look like this,
assuming ``P.STATE.I=0`` in the non secure state :
.. code:: c
int rc;
rc = smc(TSP_YIELD_SMC_FID, ...); /* Issue a Yielding SMC call */
......@@ -976,22 +980,24 @@ assuming `P.STATE.I=0` in the non secure state :
rc = smc(TSP_FID_RESUME); /* Issue resume SMC call */
}
The `TSP_YIELD_SMC_FID` is any `yielding` SMC function identifier and the smc()
The ``TSP_YIELD_SMC_FID`` is any ``yielding`` SMC function identifier and the smc()
function invokes a SMC call with the required arguments. The pending non-secure
interrupt causes an IRQ exception and the IRQ handler registered at the
exception vector handles the non-secure interrupt and returns. The return value
from the SMC call is tested for `SMC_PREEMPTED` to check whether it is
preempted. If it is, then the resume SMC call `TSP_FID_RESUME` is issued. The
from the SMC call is tested for ``SMC_PREEMPTED`` to check whether it is
preempted. If it is, then the resume SMC call ``TSP_FID_RESUME`` is issued. The
return value of the SMC call is tested again to check if it is preempted.
This is done in a loop till the SMC call succeeds or fails. If a `yielding`
SMC is preempted, until it is resumed using `TSP_FID_RESUME` SMC and
This is done in a loop till the SMC call succeeds or fails. If a ``yielding``
SMC is preempted, until it is resumed using ``TSP_FID_RESUME`` SMC and
completed, the current TSPD prevents any other SMC call from re-entering
TSP by returning `SMC_UNK` error.
TSP by returning ``SMC_UNK`` error.
--------------
- - - - - - - - - - - - - - - - - - - - - - - - - -
*Copyright (c) 2014-2015, ARM Limited and Contributors. All rights reserved.*
_Copyright (c) 2014-2015, ARM Limited and Contributors. All rights reserved._
.. _Porting Guide: ./porting-guide.rst
.. _SMC calling convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
[Porting Guide]: ./porting-guide.md
[SMC calling convention]: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html "SMC Calling Convention PDD (ARM DEN 0028A)"
.. |Image 1| image:: diagrams/sec-int-handling.png?raw=true
.. |Image 2| image:: diagrams/non-sec-int-handling.png?raw=true
docs/plat/hikey.md deleted 100644 → 0
View file @ aa5b843f
Description
====================
HiKey is one of 96boards. Hisilicon Kirin6220 processor is installed on HiKey.
More information are listed in [link](https://github.com/96boards/documentation/blob/master/ConsumerEdition/HiKey/Quickstart/README.md).
How to build
====================
1. Code Locations
-----------------
* ARM Trusted Firmware:
[link](https://github.com/ARM-software/arm-trusted-firmware)
* edk2:
[link](https://github.com/96boards-hikey/edk2/tree/testing/hikey960_v2.5)
* OpenPlatformPkg:
[link](https://github.com/96boards-hikey/OpenPlatformPkg/tree/testing/hikey960_v1.3.4)
* l-loader:
[link](https://github.com/96boards-hikey/l-loader/tree/testing/hikey960_v1.2)
* uefi-tools:
[link](https://github.com/96boards-hikey/uefi-tools/tree/testing/hikey960_v1)
* atf-fastboot:
[link](https://github.com/96boards-hikey/atf-fastboot/tree/master)
2. Build Procedure
------------------
* Fetch all the above repositories into local host.
Make all the repositories in the same ${BUILD_PATH}.
* Create the symbol link to OpenPlatformPkg in edk2.
<br>`$cd ${BUILD_PATH}/edk2`</br>
<br>`$ln -sf ../OpenPlatformPkg`</br>
* Prepare AARCH64 && AARCH32 toolchain. Prepare python.
* If your hikey hardware is built by CircuitCo, update _uefi-tools/platform.config_ first. _(optional)_
<br>__Uncomment the below sentence. Otherwise, UEFI can't output messages on serial
console on hikey.__</br>
<br>`BUILDFLAGS=-DSERIAL_BASE=0xF8015000`</br>
<br>If your hikey hardware is built by LeMarker, nothing to do.</br>
* Build it as debug mode. Create your own build script file or you could refer to __build_uefi.sh__ in l-loader git repository.
<br>`BUILD_OPTION=DEBUG`</br>
<br>`export AARCH64_TOOLCHAIN=GCC5`</br>
<br>`export UEFI_TOOLS_DIR=${BUILD_PATH}/uefi-tools`<br>
<br>`export EDK2_DIR=${BUILD_PATH}/edk2`</br>
<br>`EDK2_OUTPUT_DIR=${EDK2_DIR}/Build/HiKey/${BUILD_OPTION}_${AARCH64_TOOLCHAIN}`</br>
<br>`# Build fastboot for ARM Trust Firmware. It's used for recovery mode.`</br>
<br>`cd ${BUILD_PATH}/atf-fastboot`</br>
<br>`CROSS_COMPILE=aarch64-linux-gnu- make PLAT=hikey DEBUG=1`</br>
<br>`# Convert DEBUG/RELEASE to debug/release`</br>
<br>`FASTBOOT_BUILD_OPTION=$(echo ${BUILD_OPTION} | tr '[A-Z]' '[a-z]')`</br>
<br>`cd ${EDK2_DIR}`</br>
<br>`# Build UEFI & ARM Trust Firmware`</br>
<br>`${UEFI_TOOLS_DIR}/uefi-build.sh -b ${BUILD_OPTION} -a ../arm-trusted-firmware hikey`</br>
<br>`# Generate l-loader.bin`</br>
<br>`cd ${BUILD_PATH}/l-loader`</br>
<br>`ln -sf ${EDK2_OUTPUT_DIR}/FV/bl1.bin`</br>
<br>`ln -sf ${EDK2_OUTPUT_DIR}/FV/fip.bin`</br>
<br>`ln -sf ${BUILD_PATH}/atf-fastboot/build/hikey/${FASTBOOT_BUILD_OPTION}/bl1.bin fastboot.bin`</br>
<br>`python gen_loader.py -o l-loader.bin --img_bl1=bl1.bin --img_ns_bl1u=BL33_AP_UEFI.fd`</br>
<br>`arm-linux-gnueabihf-gcc -c -o start.o start.S`</br>
<br>`arm-linux-gnueabihf-ld -Bstatic -Tl-loader.lds -Ttext 0xf9800800 start.o -o loader`</br>
<br>`arm-linux-gnueabihf-objcopy -O binary loader temp`</br>
<br>`python gen_loader_hikey.py -o l-loader.bin --img_loader=temp --img_bl1=bl1.bin --img_ns_bl1u=fastboot.bin`</br>
* Generate partition table for aosp. The eMMC capacity is either 4GB or 8GB. Just change "aosp-4g" to "linux-4g" for debian.
<br>`$PTABLE=aosp-4g SECTOR_SIZE=512 bash -x generate_ptable.sh`</br>
3. Setup Console
----------------
* Install ser2net. Use telnet as the console since UEFI fails to display Boot Manager GUI in minicom. __If you don't need Boot Manager GUI, just ignore this section.__
<br>`$sudo apt-get install ser2net`</br>
* Configure ser2net.
<br>`$sudo vi /etc/ser2net.conf`</br>
<br>Append one line for serial-over-USB in below.</br>
<br>_#ser2net.conf_</br>
<br>`2004:telnet:0:/dev/ttyUSB0:115200 8DATABITS NONE 1STOPBIT banner`</br>
* Open the console.
<br>`$telnet localhost 2004`</br>
<br>And you could open the console remotely, too.</br>
4. Flush images in recovery mode
-----------------------------
* Make sure Pin3-Pin4 on J15 are connected for recovery mode. Then power on HiKey.
* Remove the modemmanager package. This package may cause the idt tool failure.
<br>`$sudo apt-get purge modemmanager`</br>
* Run the command to download l-loader.bin into HiKey.
<br>`$sudo python hisi-idt.py -d /dev/ttyUSB1 --img1 l-loader.bin`</br>
* Update images. All aosp or debian images could be fetched from [link](https://builds.96boards.org/).
<br>`$sudo fastboot flash ptable prm_ptable.img`</br>
<br>`$sudo fastboot flash fastboot fip.bin`</br>
<br>`$sudo fastboot flash boot boot.img`</br>
<br>`$sudo fastboot flash cache cache.img`</br>
<br>`$sudo fastboot flash system system.img`</br>
<br>`$sudo fastboot flash userdata userdata.img`</br>
5. Boot UEFI in normal mode
-----------------------------
* Make sure Pin3-Pin4 on J15 are open for normal boot mode. Then power on HiKey.
* Reference [link](https://github.com/96boards-hikey/tools-images-hikey960/blob/master/build-from-source/README-ATF-UEFI-build-from-source.md)
docs/plat/hikey.rst 0 → 100644
View file @ 7cefb56d
Description
===========
HiKey is one of 96boards. Hisilicon Kirin6220 processor is installed on HiKey.
More information are listed in `link`_.
How to build
============
Code Locations
--------------
- ARM Trusted Firmware:
`link <https://github.com/ARM-software/arm-trusted-firmware>`__
- edk2:
`link <https://github.com/96boards-hikey/edk2/tree/testing/hikey960_v2.5>`__
- OpenPlatformPkg:
`link <https://github.com/96boards-hikey/OpenPlatformPkg/tree/testing/hikey960_v1.3.4>`__
- l-loader:
`link <https://github.com/96boards-hikey/l-loader/tree/testing/hikey960_v1.2>`__
- uefi-tools:
`link <https://github.com/96boards-hikey/uefi-tools/tree/testing/hikey960_v1>`__
- atf-fastboot:
`link <https://github.com/96boards-hikey/atf-fastboot/tree/master>`__
Build Procedure
---------------
- Fetch all the above repositories into local host.
Make all the repositories in the same ${BUILD\_PATH}.
- Create the symbol link to OpenPlatformPkg in edk2.
.. code:: shell
$cd ${BUILD_PATH}/edk2
$ln -sf ../OpenPlatformPkg
- Prepare AARCH64 && AARCH32 toolchain. Prepare python.
- If your hikey hardware is built by CircuitCo, update *uefi-tools/platform.config* first. *(optional)*
**Uncomment the below sentence. Otherwise, UEFI can't output messages on serial
console on hikey.**
.. code:: shell
BUILDFLAGS=-DSERIAL_BASE=0xF8015000
If your hikey hardware is built by LeMarker, nothing to do.
- Build it as debug mode. Create your own build script file or you could refer to **build\_uefi.sh** in l-loader git repository.
.. code:: shell
BUILD_OPTION=DEBUG
export AARCH64_TOOLCHAIN=GCC5
export UEFI_TOOLS_DIR=${BUILD_PATH}/uefi-tools
export EDK2_DIR=${BUILD_PATH}/edk2
EDK2_OUTPUT_DIR=${EDK2_DIR}/Build/HiKey/${BUILD_OPTION}_${AARCH64_TOOLCHAIN}
# Build fastboot for ARM Trust Firmware. It's used for recovery mode.
cd ${BUILD_PATH}/atf-fastboot
CROSS_COMPILE=aarch64-linux-gnu- make PLAT=hikey DEBUG=1
# Convert DEBUG/RELEASE to debug/release
FASTBOOT_BUILD_OPTION=$(echo ${BUILD_OPTION} | tr '[A-Z]' '[a-z]')
cd ${EDK2_DIR}
# Build UEFI & ARM Trust Firmware
${UEFI_TOOLS_DIR}/uefi-build.sh -b ${BUILD_OPTION} -a ../arm-trusted-firmware hikey
# Generate l-loader.bin
cd ${BUILD_PATH}/l-loader
ln -sf ${EDK2_OUTPUT_DIR}/FV/bl1.bin
ln -sf ${EDK2_OUTPUT_DIR}/FV/fip.bin
ln -sf ${BUILD_PATH}/atf-fastboot/build/hikey/${FASTBOOT_BUILD_OPTION}/bl1.bin fastboot.bin
python gen_loader.py -o l-loader.bin --img_bl1=bl1.bin --img_ns_bl1u=BL33_AP_UEFI.fd
arm-linux-gnueabihf-gcc -c -o start.o start.S
arm-linux-gnueabihf-ld -Bstatic -Tl-loader.lds -Ttext 0xf9800800 start.o -o loader
arm-linux-gnueabihf-objcopy -O binary loader temp
python gen_loader_hikey.py -o l-loader.bin --img_loader=temp --img_bl1=bl1.bin --img_ns_bl1u=fastboot.bin
- Generate partition table for aosp. The eMMC capacity is either 4GB or 8GB. Just change "aosp-4g" to "linux-4g" for debian.
.. code:: shell
$PTABLE=aosp-4g SECTOR_SIZE=512 bash -x generate_ptable.sh
Setup Console
-------------
- Install ser2net. Use telnet as the console since UEFI fails to display Boot Manager GUI in minicom. **If you don't need Boot Manager GUI, just ignore this section.**
.. code:: shell
$sudo apt-get install ser2net
- Configure ser2net.
.. code:: shell
$sudo vi /etc/ser2net.conf
Append one line for serial-over-USB in below.
*#ser2net.conf*
.. code:: shell
2004:telnet:0:/dev/ttyUSB0:115200 8DATABITS NONE 1STOPBIT banner
- Open the console.
.. code:: shell
$telnet localhost 2004
And you could open the console remotely, too.
Flush images in recovery mode
-----------------------------
- Make sure Pin3-Pin4 on J15 are connected for recovery mode. Then power on HiKey.
- Remove the modemmanager package. This package may cause the idt tool failure.
.. code:: shell
$sudo apt-get purge modemmanager
- Run the command to download l-loader.bin into HiKey.
.. code:: shell
$sudo python hisi-idt.py -d /dev/ttyUSB1 --img1 l-loader.bin
- Update images. All aosp or debian images could be fetched from `link <https://builds.96boards.org/>`__.
.. code:: shell
$sudo fastboot flash ptable prm_ptable.img
$sudo fastboot flash fastboot fip.bin
$sudo fastboot flash boot boot.img
$sudo fastboot flash cache cache.img
$sudo fastboot flash system system.img
$sudo fastboot flash userdata userdata.img
Boot UEFI in normal mode
------------------------
- Make sure Pin3-Pin4 on J15 are open for normal boot mode. Then power on HiKey.
- Reference `link <https://github.com/96boards-hikey/tools-images-hikey960/blob/master/build-from-source/README-ATF-UEFI-build-from-source.md>`__
.. _link: https://github.com/96boards/documentation/blob/master/ConsumerEdition/HiKey/Quickstart/README.md
docs/plat/hikey960.md deleted 100644 → 0
View file @ aa5b843f
Description
====================
HiKey960 is one of 96boards. Hisilicon Hi3660 processor is installed on HiKey960.
More information are listed in [link](http://www.96boards.org/documentation/ConsumerEdition/HiKey960/README.md).
How to build
====================
1. Code Locations
-----------------
* ARM Trusted Firmware:
[link](https://github.com/ARM-software/arm-trusted-firmware)
* edk2:
[link](https://github.com/96boards-hikey/edk2/tree/testing/hikey960_v2.5)
* OpenPlatformPkg:
[link](https://github.com/96boards-hikey/OpenPlatformPkg/tree/testing/hikey960_v1.3.4)
* l-loader:
[link](https://github.com/96boards-hikey/l-loader/tree/testing/hikey960_v1.2)
* uefi-tools:
[link](https://github.com/96boards-hikey/uefi-tools/tree/hikey960_v1)
2. Build Procedure
------------------
* Fetch all the above 5 repositories into local host.
Make all the repositories in the same ${BUILD_PATH}.
* Create the symbol link to OpenPlatformPkg in edk2.
<br>`$cd ${BUILD_PATH}/edk2`</br>
<br>`$ln -sf ../OpenPlatformPkg`</br>
* Prepare AARCH64 toolchain.
* If your hikey960 hardware is v1, update _uefi-tools/platform.config_ first. _(optional)_
<br>__Uncomment the below sentence. Otherwise, UEFI can't output messages on serial
console on hikey960 v1.__</br>
<br>`BUILDFLAGS=-DSERIAL_BASE=0xFDF05000`</br>
<br>If your hikey960 hardware is v2 or newer, nothing to do.</br>
* Build it as debug mode. Create script file for build.
<br>`BUILD_OPTION=DEBUG`</br>
<br>`export AARCH64_TOOLCHAIN=GCC48`</br>
<br>`export UEFI_TOOLS_DIR=${BUILD_PATH}/uefi-tools`<br>
<br>`export EDK2_DIR=${BUILD_PATH}/edk2`</br>
<br>`EDK2_OUTPUT_DIR=${EDK2_DIR}/Build/HiKey960/${BUILD_OPTION}_${AARCH64_TOOLCHAIN}`</br>
<br>`cd ${EDK2_DIR}`</br>
<br>`# Build UEFI & ARM Trust Firmware`</br>
<br>`${UEFI_TOOLS_DIR}/uefi-build.sh -b ${BUILD_OPTION} -a ../arm-trusted-firmware hikey960`</br>
<br>`# Generate l-loader.bin`</br>
<br>`cd ${BUILD_PATH}/l-loader`</br>
<br>`ln -sf ${EDK2_OUTPUT_DIR}/FV/bl1.bin`</br>
<br>`ln -sf ${EDK2_OUTPUT_DIR}/FV/fip.bin`</br>
<br>`ln -sf ${EDK2_OUTPUT_DIR}/FV/BL33_AP_UEFI.fd`</br>
<br>`python gen_loader.py -o l-loader.bin --img_bl1=bl1.bin --img_ns_bl1u=BL33_AP_UEFI.fd`</br>
* Generate partition table.
<br>_Make sure that you're using the sgdisk in the l-loader directory._</br>
<br>`$PTABLE=aosp-32g SECTOR_SIZE=4096 SGDISK=./sgdisk bash -x generate_ptable.sh`</br>
3. Setup Console
----------------
* Install ser2net. Use telnet as the console since UEFI will output window
that fails to display in minicom.
<br>`$sudo apt-get install ser2net`</br>
* Configure ser2net.
<br>`$sudo vi /etc/ser2net.conf`</br>
<br>Append one line for serial-over-USB in below.</br>
<br>_#ser2net.conf_</br>
<br>`2004:telnet:0:/dev/ttyUSB0:115200 8DATABITS NONE 1STOPBIT banner`</br>
* Open the console.
<br>`$telnet localhost 2004`</br>
<br>And you could open the console remotely, too.</br>
4. Boot UEFI in recovery mode
-----------------------------
* Fetch that are used in recovery mode. The code location is in below.
[link](https://github.com/96boards-hikey/tools-images-hikey960)
* Generate l-loader.bin.
<br>`$cd tools-images-hikey960`</br>
<br>`$ln -sf ${BUILD_PATH}/l-loader/l-loader.bin`</br>
* Prepare config file.
<br>_$vi config_</br>
<br>_# The content of config file_</br>
<br>`./sec_user_xloader.img 0x00020000`</br>
<br>`./sec_uce_boot.img 0x6A908000`</br>
<br>`./l-loader.bin 0x1AC00000`</br>
* Remove the modemmanager package. This package may causes hikey_idt tool failure.
<br>`$sudo apt-get purge modemmanager`</br>
* Run the command to download l-loader.bin into HiKey960.
<br>`$sudo ./hikey_idt -c config -p /dev/ttyUSB1`</br>
* UEFI running in recovery mode.
<br>When prompt '.' is displayed on console, press hotkey 'f' in keyboard. Then Android fastboot app is running.</br>
<br>The timeout of prompt '.' is 10 seconds.</br>
* Update images.
<br>`$sudo fastboot flash ptable prm_ptable.img`</br>
<br>`$sudo fastboot flash xloader sec_xloader.img`</br>
<br>`$sudo fastboot flash fastboot l-loader.bin`</br>
<br>`$sudo fastboot flash fip fip.bin`</br>
<br>`$sudo fastboot flash boot boot.img`</br>
<br>`$sudo fastboot flash cache cache.img`</br>
<br>`$sudo fastboot flash system system.img`</br>
<br>`$sudo fastboot flash userdata userdata.img`</br>
* Notice: UEFI could also boot kernel in recovery mode, but BL31 isn't loaded in
recovery mode.
5. Boot UEFI in normal mode
-----------------------------
* Make sure "Boot Mode" switch is OFF for normal boot mode. Then power on HiKey960.
* Reference [link](https://github.com/96boards-hikey/tools-images-hikey960/blob/master/build-from-source/README-ATF-UEFI-build-from-source.md)
docs/plat/hikey960.rst 0 → 100644
View file @ 7cefb56d
Description
===========
HiKey960 is one of 96boards. Hisilicon Hi3660 processor is installed on HiKey960.
More information are listed in `link`_.
How to build
============
Code Locations
--------------
- ARM Trusted Firmware:
`link <https://github.com/ARM-software/arm-trusted-firmware>`__
- edk2:
`link <https://github.com/96boards-hikey/edk2/tree/testing/hikey960_v2.5>`__
- OpenPlatformPkg:
`link <https://github.com/96boards-hikey/OpenPlatformPkg/tree/testing/hikey960_v1.3.4>`__
- l-loader:
`link <https://github.com/96boards-hikey/l-loader/tree/testing/hikey960_v1.2>`__
- uefi-tools:
`link <https://github.com/96boards-hikey/uefi-tools/tree/hikey960_v1>`__
Build Procedure
---------------
- Fetch all the above 5 repositories into local host.
Make all the repositories in the same ${BUILD\_PATH}.
- Create the symbol link to OpenPlatformPkg in edk2.
.. code:: shell
$cd ${BUILD_PATH}/edk2
$ln -sf ../OpenPlatformPkg
- Prepare AARCH64 toolchain.
- If your hikey960 hardware is v1, update *uefi-tools/platform.config* first. *(optional)*
**Uncomment the below sentence. Otherwise, UEFI can't output messages on serial
console on hikey960 v1.**
.. code:: shell
BUILDFLAGS=-DSERIAL_BASE=0xFDF05000
If your hikey960 hardware is v2 or newer, nothing to do.
- Build it as debug mode. Create script file for build.
.. code:: shell
BUILD_OPTION=DEBUG
export AARCH64_TOOLCHAIN=GCC48
export UEFI_TOOLS_DIR=${BUILD_PATH}/uefi-tools
export EDK2_DIR=${BUILD_PATH}/edk2
EDK2_OUTPUT_DIR=${EDK2_DIR}/Build/HiKey960/${BUILD_OPTION}_${AARCH64_TOOLCHAIN}
cd ${EDK2_DIR}
# Build UEFI & ARM Trust Firmware
${UEFI_TOOLS_DIR}/uefi-build.sh -b ${BUILD_OPTION} -a ../arm-trusted-firmware hikey960
# Generate l-loader.bin
cd ${BUILD_PATH}/l-loader
ln -sf ${EDK2_OUTPUT_DIR}/FV/bl1.bin
ln -sf ${EDK2_OUTPUT_DIR}/FV/fip.bin
ln -sf ${EDK2_OUTPUT_DIR}/FV/BL33_AP_UEFI.fd
python gen_loader.py -o l-loader.bin --img_bl1=bl1.bin --img_ns_bl1u=BL33_AP_UEFI.fd
- Generate partition table.
*Make sure that you're using the sgdisk in the l-loader directory.*
.. code:: shell
$PTABLE=aosp-32g SECTOR_SIZE=4096 SGDISK=./sgdisk bash -x generate_ptable.sh
Setup Console
-------------
- Install ser2net. Use telnet as the console since UEFI will output window
that fails to display in minicom.
.. code:: shell
$sudo apt-get install ser2net
- Configure ser2net.
.. code:: shell
$sudo vi /etc/ser2net.conf
Append one line for serial-over-USB in *#ser2net.conf*
::
2004:telnet:0:/dev/ttyUSB0:115200 8DATABITS NONE 1STOPBIT banner
- Open the console.
.. code:: shell
$telnet localhost 2004
And you could open the console remotely, too.
Boot UEFI in recovery mode
--------------------------
- Fetch that are used in recovery mode. The code location is in below.
`link <https://github.com/96boards-hikey/tools-images-hikey960>`__
- Generate l-loader.bin.
.. code:: shell
$cd tools-images-hikey960
$ln -sf ${BUILD_PATH}/l-loader/l-loader.bin
- Prepare config file.
.. code:: shell
$vi config
# The content of config file
./sec_user_xloader.img 0x00020000
./sec_uce_boot.img 0x6A908000
./l-loader.bin 0x1AC00000
- Remove the modemmanager package. This package may causes hikey\_idt tool failure.
.. code:: shell
$sudo apt-get purge modemmanager
- Run the command to download l-loader.bin into HiKey960.
.. code:: shell
$sudo ./hikey_idt -c config -p /dev/ttyUSB1
- UEFI running in recovery mode.
When prompt '.' is displayed on console, press hotkey 'f' in keyboard. Then Android fastboot app is running.
The timeout of prompt '.' is 10 seconds.
- Update images.
.. code:: shell
$sudo fastboot flash ptable prm_ptable.img
$sudo fastboot flash xloader sec_xloader.img
$sudo fastboot flash fastboot l-loader.bin
$sudo fastboot flash fip fip.bin
$sudo fastboot flash boot boot.img
$sudo fastboot flash cache cache.img
$sudo fastboot flash system system.img
$sudo fastboot flash userdata userdata.img
- Notice: UEFI could also boot kernel in recovery mode, but BL31 isn't loaded in
recovery mode.
Boot UEFI in normal mode
------------------------
- Make sure "Boot Mode" switch is OFF for normal boot mode. Then power on HiKey960.
- Reference `link <https://github.com/96boards-hikey/tools-images-hikey960/blob/master/build-from-source/README-ATF-UEFI-build-from-source.md>`__
.. _link: http://www.96boards.org/documentation/ConsumerEdition/HiKey960/README.md
docs/plat/nvidia-tegra.md → docs/plat/nvidia-tegra.rst
View file @ 7cefb56d
Tegra SoCs - Overview
======================
=====================
* T210
-------
- .. rubric:: T210
:name: t210
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
......@@ -12,8 +12,8 @@ including legacy ARMv7 applications. The Cortex-A57 processors each have
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.
* T132
-------
- .. rubric:: T132
:name: t132
Denver is NVIDIA's own custom-designed, 64-bit, dual-core CPU which is
fully ARMv8 architecture compatible. Each of the two Denver cores
......@@ -41,13 +41,14 @@ to extensive power-gating and dynamic voltage and clock scaling based on
workloads.
Directory structure
====================
===================
* plat/nvidia/tegra/common - Common code for all Tegra SoCs
* plat/nvidia/tegra/soc/txxx - Chip specific code
- plat/nvidia/tegra/common - Common code for all Tegra SoCs
- plat/nvidia/tegra/soc/txxx - Chip specific code
Trusted OS dispatcher
=====================
Tegra supports multiple Trusted OS', Trusted Little Kernel (TLK) being one of
them. In order to include the 'tlkd' dispatcher in the image, pass 'SPD=tlkd'
on the command line while preparing a bl31 image. This allows other Trusted OS
......@@ -55,39 +56,43 @@ vendors to use the upstream code and include their dispatchers in the image
without changing any makefiles.
Preparing the BL31 image to run on Tegra SoCs
===================================================
'CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- make PLAT=tegra \
TARGET_SOC=<target-soc e.g. t210|t132> SPD=<dispatcher e.g. tlkd> bl31'
=============================================
.. code:: shell
Platforms wanting to use different TZDRAM_BASE, can add 'TZDRAM_BASE=<value>'
CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- make PLAT=tegra \
TARGET_SOC=<target-soc e.g. t210|t132> SPD=<dispatcher e.g. tlkd> bl31
Platforms wanting to use different TZDRAM\_BASE, can add ``TZDRAM_BASE=<value>``
to the build command line.
The Tegra platform code expects a pointer to the following platform specific
structure via 'x1' register from the BL2 layer which is used by the
bl31_early_platform_setup() handler to extract the TZDRAM carveout base and
bl31\_early\_platform\_setup() handler to extract the TZDRAM carveout base and
size for loading the Trusted OS and the UART port ID to be used. The Tegra
memory controller driver programs this base/size in order to restrict NS
accesses.
typedef struct plat_params_from_bl2 {
/* TZ memory size */
uint64_t tzdram_size;
/* TZ memory base */
uint64_t tzdram_base;
/* UART port ID */
int uart_id;
} plat_params_from_bl2_t;
typedef struct plat\_params\_from\_bl2 {
/\* TZ memory size */
uint64\_t tzdram\_size;
/* TZ memory base */
uint64\_t tzdram\_base;
/* UART port ID \*/
int uart\_id;
} plat\_params\_from\_bl2\_t;
Power Management
================
The PSCI implementation expects each platform to expose the 'power state'
parameter to be used during the 'SYSTEM SUSPEND' call. The state-id field
is implementation defined on Tegra SoCs and is preferably defined by
tegra_def.h.
tegra\_def.h.
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
be enabled by Tegrs SoCs during 'Cluster power up' or 'System Suspend' exit.
docs/plat/qemu.md → docs/plat/qemu.rst
View file @ 7cefb56d
......@@ -14,31 +14,35 @@ An ARM64 defonfig v4.5 Linux kernel is known to boot, FTD doesn't need to be
provided as it's generated by QEMU.
Current limitations:
* Only cold boot is supported
* No build instructions for QEMU_EFI.fd and rootfs-arm64.cpio.gz
* No instructions for how to load a BL32 (Secure Payload)
`QEMU_EFI.fd` can be dowloaded from
- Only cold boot is supported
- No build instructions for QEMU\_EFI.fd and rootfs-arm64.cpio.gz
- No instructions for how to load a BL32 (Secure Payload)
``QEMU_EFI.fd`` can be dowloaded from
http://snapshots.linaro.org/components/kernel/leg-virt-tianocore-edk2-upstream/latest/QEMU-KERNEL-AARCH64/RELEASE_GCC49/QEMU_EFI.fd
Boot binaries, except BL1, are primarily loaded via semi-hosting so all
binaries has to reside in the same directory as QEMU is started from. This
is conveniently achieved with symlinks the local names as:
* `bl2.bin` -> BL2
* `bl31.bin` -> BL31
* `bl33.bin` -> BL33 (`QEMU_EFI.fd`)
* `Image` -> linux/Image
- ``bl2.bin`` -> BL2
- ``bl31.bin`` -> BL31
- ``bl33.bin`` -> BL33 (``QEMU_EFI.fd``)
- ``Image`` -> linux/Image
To build:
```
make CROSS_COMPILE=aarch64-none-elf- PLAT=qemu
```
::
make CROSS_COMPILE=aarch64-none-elf- PLAT=qemu
To start (QEMU v2.6.0):
```
qemu-system-aarch64 -nographic -machine virt,secure=on -cpu cortex-a57 \
::
qemu-system-aarch64 -nographic -machine virt,secure=on -cpu cortex-a57 \
-kernel Image \
-append console=ttyAMA0,38400 keep_bootcon root=/dev/vda2 \
-initrd rootfs-arm64.cpio.gz -smp 2 -m 1024 -bios bl1.bin \
-d unimp -semihosting-config enable,target=native
```
docs/plat/socionext-uniphier.md deleted 100644 → 0
View file @ aa5b843f
ARM Trusted Firmware for Socionext UniPhier SoCs
================================================
Socionext UniPhier ARMv8-A SoCs use ARM Trusted Firmware as the secure world
firmware, supporting BL1, BL2, and BL31.
UniPhier SoC family implements its internal boot ROM, so BL1 is used as pseudo
ROM (i.e. runs in RAM). The internal boot ROM loads 64KB [1] image from a
non-volatile storage to the on-chip SRAM. Unfortunately, BL1 does not fit in
the 64KB limit if [Trusted Board Boot] (TBB) is enabled. To solve this problem,
Socionext provides a first stage loader called [UniPhier BL]. This loader runs
in the on-chip SRAM, initializes the DRAM, expands BL1 there, and hands the
control over to it. Therefore, all images of ARM Trusted Firmware run in DRAM.
The UniPhier platform works with/without TBB. See below for the build process
of each case. The image authentication for the UniPhier platform fully
complies with the Trusted Board Boot Requirements (TBBR) specification.
The UniPhier BL does not implement the authentication functionality, that is,
it can not verify the BL1 image by itself. Instead, the UniPhier BL assures
the BL1 validity in a different way; BL1 is GZIP-compressed and appended to
the UniPhier BL. The concatenation of the UniPhier BL and the compressed BL1
fits in the 64KB limit. The concatenated image is loaded by the boot ROM
(and verified if the chip fuses are blown).
[1]: Some SoCs can load 80KB, but the software implementation must be aligned
to the lowest common denominator.
[Trusted Board Boot]: ../trusted-board-boot.md
[UniPhier BL]: https://github.com/uniphier/uniphier-bl
Boot Flow
---------
1. The Boot ROM
This is hard-wired ROM, so never corrupted. It loads the UniPhier BL (with
compressed-BL1 appended) into the on-chip SRAM. If the SoC fuses are blown,
the image is verified by the SoC's own method.
2. UniPhier BL
This runs in the on-chip SRAM. After the minimum SoC initialization and DRAM
setup, it decompresses the appended BL1 image into the DRAM, then jumps to
the BL1 entry.
3. BL1
This runs in the DRAM. It extracts BL2 from FIP (Firmware Image Package).
If TBB is enabled, the BL2 is authenticated by the standard mechanism of ARM
Trusted Firmware.
4. BL2, BL31, and more
They all run in the DRAM, and are authenticated by the standard mechanism if
TBB is enabled. See [Firmware Design] for details.
[Firmware Design]: ../firmware-design.md
Basic Build
-----------
BL1 must be compressed for the reason above. The UniPhier's platform makefile
provides a build target `bl1_gzip` for this.
For a non-secure boot loader (aka BL33), U-Boot is well supported for UniPhier
SoCs. The U-Boot image (`u-boot.bin`) must be built in advance. For the build
procedure of U-Boot, refer to the document in the [U-Boot] project.
[U-Boot]: https://www.denx.de/wiki/U-Boot
To build minimum functionality for UniPhier (without TBB):
```
make CROSS_COMPILE=<gcc-prefix> PLAT=uniphier BL33=<path-to-BL33> bl1_gzip fip
```
Output images:
- `bl1.bin.gzip`
- `fip.bin`
Optional features
-----------------
- Trusted Board Boot
[mbed TLS] is needed as the cryptographic and image parser modules.
Refer to the [User Guide] for the appropriate version of mbed TLS.
To enable TBB, add the following options to the build command:
```
TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 MBEDTLS_DIR=<path-to-mbedtls>
```
[mbed TLS]: https://tls.mbed.org/
[User Guide]: ../user-guide.md
- System Control Processor (SCP)
If desired, FIP can include an SCP BL2 image. If BL2 finds an SCP BL2 image
in FIP, BL2 loads it into DRAM and kicks the SCP. Most of UniPhier boards
still work without SCP, but SCP provides better power management support.
To include SCP_BL2, add the following option to the build command:
```
SCP_BL2=<path-to-SCP>
```
- BL32 (Secure Payload)
To enable BL32, add the following option to the build command:
```
SPD=<spd> BL32=<path-to-BL32>
```
If you use TSP for BL32, `BL32=<path-to-BL32>` is not required. Just add the
following:
```
SPD=tspd
```
docs/plat/socionext-uniphier.rst 0 → 100644
View file @ 7cefb56d
ARM Trusted Firmware for Socionext UniPhier SoCs
================================================
Socionext UniPhier ARMv8-A SoCs use ARM Trusted Firmware as the secure world
firmware, supporting BL1, BL2, and BL31.
UniPhier SoC family implements its internal boot ROM, so BL1 is used as pseudo
ROM (i.e. runs in RAM). The internal boot ROM loads 64KB `1`_ image from a
non-volatile storage to the on-chip SRAM. Unfortunately, BL1 does not fit in
the 64KB limit if `Trusted Board Boot`_ (TBB) is enabled. To solve this problem,
Socionext provides a first stage loader called `UniPhier BL`_. This loader runs
in the on-chip SRAM, initializes the DRAM, expands BL1 there, and hands the
control over to it. Therefore, all images of ARM Trusted Firmware run in DRAM.
The UniPhier platform works with/without TBB. See below for the build process
of each case. The image authentication for the UniPhier platform fully
complies with the Trusted Board Boot Requirements (TBBR) specification.
The UniPhier BL does not implement the authentication functionality, that is,
it can not verify the BL1 image by itself. Instead, the UniPhier BL assures
the BL1 validity in a different way; BL1 is GZIP-compressed and appended to
the UniPhier BL. The concatenation of the UniPhier BL and the compressed BL1
fits in the 64KB limit. The concatenated image is loaded by the boot ROM
(and verified if the chip fuses are blown).
::
to the lowest common denominator.
Boot Flow
---------
#. The Boot ROM
This is hard-wired ROM, so never corrupted. It loads the UniPhier BL (with
compressed-BL1 appended) into the on-chip SRAM. If the SoC fuses are blown,
the image is verified by the SoC's own method.
#. UniPhier BL
This runs in the on-chip SRAM. After the minimum SoC initialization and DRAM
setup, it decompresses the appended BL1 image into the DRAM, then jumps to
the BL1 entry.
#. BL1
This runs in the DRAM. It extracts BL2 from FIP (Firmware Image Package).
If TBB is enabled, the BL2 is authenticated by the standard mechanism of ARM
Trusted Firmware.
#. BL2, BL31, and more
They all run in the DRAM, and are authenticated by the standard mechanism if
TBB is enabled. See `Firmware Design`_ for details.
Basic Build
-----------
BL1 must be compressed for the reason above. The UniPhier's platform makefile
provides a build target ``bl1_gzip`` for this.
For a non-secure boot loader (aka BL33), U-Boot is well supported for UniPhier
SoCs. The U-Boot image (``u-boot.bin``) must be built in advance. For the build
procedure of U-Boot, refer to the document in the `U-Boot`_ project.
To build minimum functionality for UniPhier (without TBB):
::
make CROSS_COMPILE=<gcc-prefix> PLAT=uniphier BL33=<path-to-BL33> bl1_gzip fip
Output images:
- ``bl1.bin.gzip``
- ``fip.bin``
Optional features
-----------------
- Trusted Board Boot
`mbed TLS`_ is needed as the cryptographic and image parser modules.
Refer to the `User Guide`_ for the appropriate version of mbed TLS.
To enable TBB, add the following options to the build command:
::
TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 MBEDTLS_DIR=<path-to-mbedtls>
- System Control Processor (SCP)
If desired, FIP can include an SCP BL2 image. If BL2 finds an SCP BL2 image
in FIP, BL2 loads it into DRAM and kicks the SCP. Most of UniPhier boards
still work without SCP, but SCP provides better power management support.
To include SCP\_BL2, add the following option to the build command:
::
SCP_BL2=<path-to-SCP>
- BL32 (Secure Payload)
To enable BL32, add the following option to the build command:
::
SPD=<spd> BL32=<path-to-BL32>
If you use TSP for BL32, ``BL32=<path-to-BL32>`` is not required. Just add the
following:
::
SPD=tspd
.. _1: Some%20SoCs%20can%20load%2080KB,%20but%20the%20software%20implementation%20must%20be%20aligned
.. _Trusted Board Boot: ../trusted-board-boot.rst
.. _UniPhier BL: https://github.com/uniphier/uniphier-bl
.. _Firmware Design: ../firmware-design.rst
.. _U-Boot: https://www.denx.de/wiki/U-Boot
.. _mbed TLS: https://tls.mbed.org/
.. _User Guide: ../user-guide.rst
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment