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 ...@@ -3,6 +3,7 @@ Contributor Acknowledgements
Companies Companies
--------- ---------
Linaro Limited Linaro Limited
NVIDIA Corporation 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 ARM SiP Service
=============== ===============
This document enumerates and describes the ARM SiP (Silicon Provider) services. This document enumerates and describes the ARM SiP (Silicon Provider) services.
SiP services are non-standard, platform-specific services offered by the silicon SiP services are non-standard, platform-specific services offered by the silicon
implementer or platform provider. They are accessed via. `SMC` ("SMC calls") implementer or platform provider. They are accessed via. ``SMC`` ("SMC calls")
instruction executed from Exception Levels below EL3. SMC calls for SiP instruction executed from Exception Levels below EL3. SMC calls for SiP
services: services:
* Follow [SMC Calling Convention][SMCCC]; - Follow `SMC Calling Convention`_;
* Use SMC function IDs that fall in the SiP range, which are `0xc2000000` - - Use SMC function IDs that fall in the SiP range, which are ``0xc2000000`` -
`0xc200ffff` for 64-bit calls, and `0x82000000` - `0x8200ffff` for 32-bit ``0xc200ffff`` for 64-bit calls, and ``0x82000000`` - ``0x8200ffff`` for 32-bit
calls. calls.
The ARM SiP implementation offers the following services: The ARM SiP implementation offers the following services:
* Performance Measurement Framework (PMF) - Performance Measurement Framework (PMF)
* Execution State Switching service - Execution State Switching service
Source definitions for ARM SiP service are located in the `arm_sip_svc.h` header Source definitions for ARM SiP service are located in the ``arm_sip_svc.h`` header
file. file.
Performance Measurement Framework (PMF) Performance Measurement Framework (PMF)
--------------------------------------- ---------------------------------------
The [Performance Measurement Framework](./firmware-design.md#13--performance-measurement-framework) The `Performance Measurement Framework`_
allows callers to retrieve timestamps captured at various paths in ARM Trusted allows callers to retrieve timestamps captured at various paths in 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 Execution State Switching service
--------------------------------- ---------------------------------
...@@ -37,9 +36,12 @@ Exception Level (either EL2, or NS EL1 if EL2 isn't implemented) to request to ...@@ -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 switch its execution state (a.k.a. Register Width), either from AArch64 to
AArch32, or from AArch32 to AArch64, for the calling CPU. This service is only AArch32, or from AArch32 to AArch64, for the calling CPU. This service is only
available when ARM Trusted Firmware is built for AArch64 (i.e. when build option available when 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: Arguments:
uint32_t Function ID uint32_t Function ID
...@@ -51,19 +53,19 @@ available when ARM Trusted Firmware is built for AArch64 (i.e. when build option ...@@ -51,19 +53,19 @@ available when ARM Trusted Firmware is built for AArch64 (i.e. when build option
Return: Return:
uint32_t 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. 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 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 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 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. 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 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 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 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 ...@@ -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. 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 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 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: The service may return the following error codes:
- `STATE_SW_E_PARAM`: If any of the parameters were deemed invalid for - ``STATE_SW_E_PARAM``: If any of the parameters were deemed invalid for
a specific request. a specific request.
- `STATE_SW_E_DENIED`: If the call is not successful, or when ARM Trusted - ``STATE_SW_E_DENIED``: If the call is not successful, or when ARM Trusted
Firmware is built for AArch32. Firmware is built for AArch32.
If the call is successful, the caller wouldn't observe the SMC returning. If the call is successful, the caller wouldn't observe the SMC returning.
Instead, execution starts at the supplied entry point, with the CPU registers 0 Instead, execution starts at the supplied entry point, with the CPU registers 0
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. respectively.
- - - - - - - - - - - - - - - - - - - - - - - - - - --------------
*Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.*
[Firmware Design]: ./firmware-design.md .. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
[SMCCC]: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html "SMC Calling Convention PDD (ARM DEN 0028A)" .. _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 Abstracting a Chain of Trust
============================ ============================
Contents :
1. [Introduction](#1--introduction) .. section-numbering::
2. [Framework design](#2--framework-design) :suffix: .
3. [Specifying a Chain of Trust](#3--specifying-a-chain-of-trust)
4. [Implementation example](#4--implementation-example)
.. contents::
1. Introduction
----------------
The aim of this document is to describe the authentication framework implemented The aim of this document is to describe the authentication framework implemented
in the Trusted Firmware. This framework fulfills the following requirements: 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 terms of certificate hierarchy and the mechanisms used to verify a
particular image/certificate. 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 - The mechanism used to encode and transport information, e.g. DER encoded
X.509v3 certificates to ferry Subject Public Keys, hashes and non-volatile 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: ...@@ -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 The framework has been designed following a modular approach illustrated in the
next diagram: next diagram:
``` ::
+---------------+---------------+------------+ +---------------+---------------+------------+
| Trusted | Trusted | Trusted | | Trusted | Trusted | Trusted |
| Firmware | Firmware | Firmware | | Firmware | Firmware | Firmware |
...@@ -67,26 +63,26 @@ next diagram: ...@@ -67,26 +63,26 @@ next diagram:
+-----------------+ +-----------------+
DIAGRAM 1. DIAGRAM 1.
```
This document describes the inner details of the authentication framework and This document describes the inner details of the authentication framework and
the abstraction mechanisms available to specify a Chain of Trust. the abstraction mechanisms available to specify a Chain of Trust.
Framework design
2. Framework design ----------------
--------------------
This section describes some aspects of the framework design and the rationale This section describes some aspects of the framework design and the rationale
behind them. These aspects are key to verify a Chain of Trust. 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 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 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 illustrates how this maps to a CoT for the BL31 image described in the
TBBR-Client specification. TBBR-Client specification.
``` ::
+------------------+ +-------------------+ +------------------+ +-------------------+
| ROTPK/ROTPK Hash |------>| Trusted Key | | ROTPK/ROTPK Hash |------>| Trusted Key |
+------------------+ | Certificate | +------------------+ | Certificate |
...@@ -124,39 +120,40 @@ TBBR-Client specification. ...@@ -124,39 +120,40 @@ TBBR-Client specification.
+-------------------+ +-------------------+
DIAGRAM 2. DIAGRAM 2.
```
The root of trust is usually a public key (ROTPK) that has been burnt in the The root of trust is usually a public key (ROTPK) that has been burnt in the
platform and cannot be modified. platform and cannot be modified.
### 2.2 Image types Image types
~~~~~~~~~~~
Images in a CoT are categorised as authentication and data images. An Images in a CoT are categorised as authentication and data images. An
authentication image contains information to authenticate a data image or authentication image contains information to authenticate a data image or
another authentication image. A data image is usually a boot loader binary, but another authentication image. A data image is usually a boot loader binary, but
it could be any other data that requires authentication. 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 For every image in a Chain of Trust, the following high level operations are
performed to verify it: 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. be used to authenticate the next image in the CoT.
In Diagram 1, each component is responsible for one or more of these operations. In Diagram 1, each component is responsible for one or more of these operations.
The responsibilities are briefly described below. The responsibilities are briefly described below.
TF Generic code and IO framework (GEN/IO)
#### 2.2.1 TF Generic code and IO framework (GEN/IO) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
These components are responsible for initiating the authentication process for a These components are responsible for initiating the authentication process for a
particular image in BL1 or BL2. For each BL image that requires authentication, particular image in BL1 or BL2. For each BL image that requires authentication,
...@@ -165,57 +162,57 @@ image until either an authenticated image or the ROT is reached. Then the ...@@ -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 Generic code calls the IO framewotk to load the image and calls the
Authentication module to authenticate it, following the CoT from ROT to Image. Authentication module to authenticate it, following the CoT from ROT to Image.
TF Platform Port (PP)
#### 2.2.2 TF Platform Port (PP) ^^^^^^^^^^^^^^^^^^^^^
The platform is responsible for: 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 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 also specifies the authentication methods and the parsing method used for
each image. 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. 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 extract authentication parameters contained in an image, e.g. if the
parameters are stored as X509v3 extensions, the corresponding OID must be parameters are stored as X509v3 extensions, the corresponding OID must be
provided. 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). 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 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 NV counter, then the value of the counter to compare with can only be
provided by the platform. 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). later).
Authentication Module (AM)
#### 2.2.3 Authentication Module (AM) ^^^^^^^^^^^^^^^^^^^^^^^^^^
It is responsible for: 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 other things, the authentication and image parsing methods must be specified
by the PP in the CoT. 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. 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 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 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 responsibility has not been described in this document but should be
trivial to implement). 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 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 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 time BL31 (the data image) is loaded, all information to authenticate it
...@@ -224,43 +221,45 @@ It is responsible for: ...@@ -224,43 +221,45 @@ It is responsible for:
never exceed the size of a data image. It should be possible to verify this never exceed the size of a data image. It should be possible to verify this
at build time using asserts. at build time using asserts.
Cryptographic Module (CM)
#### 2.2.4 Cryptographic Module (CM) ^^^^^^^^^^^^^^^^^^^^^^^^^
The CM is responsible for providing an API to: The CM is responsible for providing an API to:
1. Verify a digital signature. #. Verify a digital signature.
2. Verify a hash. #. Verify a hash.
The CM does not include any cryptography related code, but it relies on an 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) external library to perform the cryptographic operations. A Crypto-Library (CL)
linking the CM and the external library must be implemented. The following linking the CM and the external library must be implemented. The following
functions must be provided by the CL: functions must be provided by the CL:
``` .. code:: c
void (*init)(void);
int (*verify_signature)(void *data_ptr, unsigned int data_len, void (*init)(void);
int (*verify_signature)(void *data_ptr, unsigned int data_len,
void *sig_ptr, unsigned int sig_len, void *sig_ptr, unsigned int sig_len,
void *sig_alg, unsigned int sig_alg_len, void *sig_alg, unsigned int sig_alg_len,
void *pk_ptr, unsigned int pk_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); void *digest_info_ptr, unsigned int digest_info_len);
```
These functions are registered in the CM using the macro: 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. debugging purposes.
#### 2.2.5 Image Parser Module (IPM) Image Parser Module (IPM)
^^^^^^^^^^^^^^^^^^^^^^^^^
The IPM is responsible for: The IPM is responsible for:
1. Checking the integrity of each image loaded by the IO framework. #. Checking the integrity of each image loaded by the IO framework.
2. Extracting parameters used for authenticating an image based upon a #. Extracting parameters used for authenticating an image based upon a
description provided by the platform in the CoT descriptor. description provided by the platform in the CoT descriptor.
Images may have different formats (for example, authentication images could be Images may have different formats (for example, authentication images could be
...@@ -273,13 +272,13 @@ check the image integrity and extract the authentication parameters. ...@@ -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 See Section "Describing the image parsing methods" for more details about the
mechanism the IPM provides to define and register IPLs. mechanism the IPM provides to define and register IPLs.
Authentication methods
### 2.3 Authentication methods ~~~~~~~~~~~~~~~~~~~~~~
The AM supports the following authentication methods: The AM supports the following authentication methods:
1. Hash #. Hash
2. Digital signature #. Digital signature
The platform may specify these methods in the CoT in case it decides to define The platform may specify these methods in the CoT in case it decides to define
a custom CoT instead of reusing a predefined one. 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 ...@@ -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 the same CoT. The number and type of parameters are method specific. These
parameters should be obtained from the parent image using the IPM. parameters should be obtained from the parent image using the IPM.
1. Hash #. Hash
Parameters: Parameters:
1. A pointer to data to hash #. A pointer to data to hash
2. Length of the data #. Length of the data
4. A pointer to the hash #. A pointer to the hash
5. Length of the hash #. Length of the hash
The hash will be represented by the DER encoding of the following ASN.1 The hash will be represented by the DER encoding of the following ASN.1
type: type:
``` ::
DigestInfo ::= SEQUENCE { DigestInfo ::= SEQUENCE {
digestAlgorithm DigestAlgorithmIdentifier, digestAlgorithm DigestAlgorithmIdentifier,
digest Digest digest Digest
} }
```
This ASN.1 structure makes it possible to remove any assumption about the 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 type of hash algorithm used as this information accompanies the hash. This
should allow the Cryptography Library (CL) to support multiple hash should allow the Cryptography Library (CL) to support multiple hash
algorithm implementations. algorithm implementations.
2. Digital Signature #. Digital Signature
Parameters: Parameters:
1. A pointer to data to sign #. A pointer to data to sign
2. Length of the data #. Length of the data
3. Public Key Algorithm #. Public Key Algorithm
4. Public Key value #. Public Key value
5. Digital Signature Algorithm #. Digital Signature Algorithm
6. Digital Signature value #. Digital Signature value
The Public Key parameters will be represented by the DER encoding of the The Public Key parameters will be represented by the DER encoding of the
following ASN.1 type: following ASN.1 type:
``` ::
SubjectPublicKeyInfo ::= SEQUENCE { SubjectPublicKeyInfo ::= SEQUENCE {
algorithm AlgorithmIdentifier{PUBLIC-KEY,{PublicKeyAlgorithms}}, algorithm AlgorithmIdentifier{PUBLIC-KEY,{PublicKeyAlgorithms}},
subjectPublicKey BIT STRING } subjectPublicKey BIT STRING }
```
The Digital Signature Algorithm will be represented by the DER encoding of The Digital Signature Algorithm will be represented by the DER encoding of
the following ASN.1 types. the following ASN.1 types.
``` ::
AlgorithmIdentifier {ALGORITHM:IOSet } ::= SEQUENCE { AlgorithmIdentifier {ALGORITHM:IOSet } ::= SEQUENCE {
algorithm ALGORITHM.&id({IOSet}), algorithm ALGORITHM.&id({IOSet}),
parameters ALGORITHM.&Type({IOSet}{@algorithm}) OPTIONAL parameters ALGORITHM.&Type({IOSet}{@algorithm}) OPTIONAL
} }
```
The digital signature will be represented by: The digital signature will be represented by:
```
::
signature ::= BIT STRING signature ::= BIT STRING
```
The authentication framework will use the image descriptor to extract all the The authentication framework will use the image descriptor to extract all the
information related to authentication. information related to authentication.
Specifying a Chain of Trust
3. Specifying a Chain of Trust ---------------------------
-------------------------------
A CoT can be described as a set of image descriptors linked together in a 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 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. ...@@ -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 Unless otherwise specified, the data structures described in the following
sections are populated by the PP statically. sections are populated by the PP statically.
Describing the image parsing methods
### 3.1 Describing the image parsing methods ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The parsing method refers to the format of a particular image. For example, an 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 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 ...@@ -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 single parsing method. There has to be one IPL for every method used by the
platform. 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 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. 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 PKI certificates (authentication images). It is expected that open source
libraries will be available which can be used to parse an image represented 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 by this method. Such libraries can be used to write the corresponding IPL
e.g. the X.509 parsing library code in mbed TLS. 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 proprietary standards to represent authentication or data images. For
example, The signature of a data image could be appended to the data image 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 raw binary. A header could be prepended to the combined blob to specify the
...@@ -393,158 +392,158 @@ platform. ...@@ -393,158 +392,158 @@ platform.
The following enum can be used to define these three methods. The following enum can be used to define these three methods.
``` .. code:: c
typedef enum img_type_enum {
typedef enum img_type_enum {
IMG_RAW, /* Binary image */ IMG_RAW, /* Binary image */
IMG_PLAT, /* Platform specific format */ IMG_PLAT, /* Platform specific format */
IMG_CERT, /* X509v3 certificate */ IMG_CERT, /* X509v3 certificate */
IMG_MAX_TYPES, IMG_MAX_TYPES,
} img_type_t; } img_type_t;
```
An IPL must provide functions with the following prototypes: An IPL must provide functions with the following prototypes:
``` .. code:: c
void init(void);
int check_integrity(void *img, unsigned int img_len); void init(void);
int get_auth_param(const auth_param_type_desc_t *type_desc, 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 *img, unsigned int img_len,
void **param, unsigned int *param_len); void **param, unsigned int *param_len);
```
An IPL for each type must be registered using the following macro: 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. - ``_type``: one of the types described above.
* `_name`: a string containing the IPL name for debugging purposes. - ``_name``: a string containing the IPL name for debugging purposes.
* `_init`: initialization function pointer. - ``_init``: initialization function pointer.
* `_check_int`: check image integrity function pointer. - ``_check_int``: check image integrity function pointer.
* `_get_param`: extract authentication parameter funcion 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 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 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 been tampered with. For example, RFC-2459 describes a validation sequence for an
X.509 certificate. X.509 certificate.
The `get_auth_param()` function is passed a parameter descriptor containing The ``get_auth_param()`` function is passed a parameter descriptor containing
information about the parameter (`type_desc` and `cookie`) to identify and information about the parameter (``type_desc`` and ``cookie``) to identify and
extract the data corresponding to that parameter from an image. This data will 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. 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 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. will be used by the IPM to find the right parser descriptor for the image.
Describing the authentication method(s)
### 3.2 Describing the authentication method(s) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As part of the CoT, each image has to specify one or more authentication methods 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 which will be used to verify it. As described in the Section "Authentication
methods", there are three methods supported by the AM. methods", there are three methods supported by the AM.
``` .. code:: c
typedef enum {
typedef enum {
AUTH_METHOD_NONE, AUTH_METHOD_NONE,
AUTH_METHOD_HASH, AUTH_METHOD_HASH,
AUTH_METHOD_SIG, AUTH_METHOD_SIG,
AUTH_METHOD_NUM 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 The AM defines the type of each parameter used by an authentication method. It
uses this information to: 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. 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. 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 child image e.g. to verify the certificate image, the public key has to be
obtained from the parent image. obtained from the parent image.
``` .. code:: c
typedef enum {
typedef enum {
AUTH_PARAM_NONE, AUTH_PARAM_NONE,
AUTH_PARAM_RAW_DATA, /* Raw image data */ AUTH_PARAM_RAW_DATA, /* Raw image data */
AUTH_PARAM_SIG, /* The image signature */ AUTH_PARAM_SIG, /* The image signature */
AUTH_PARAM_SIG_ALG, /* The image signature algorithm */ AUTH_PARAM_SIG_ALG, /* The image signature algorithm */
AUTH_PARAM_HASH, /* A hash (including the algorithm) */ AUTH_PARAM_HASH, /* A hash (including the algorithm) */
AUTH_PARAM_PUB_KEY, /* A public key */ 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 The AM defines the following structure to identify an authentication parameter
required to verify an image. required to verify an image.
``` .. code:: c
typedef struct auth_param_type_desc_s {
typedef struct auth_param_type_desc_s {
auth_param_type_t type; auth_param_type_t type;
void *cookie; 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 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 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 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 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 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. the ``cookie`` field means that it is not used.
For each method, the AM defines a structure with the parameters required to For each method, the AM defines a structure with the parameters required to
verify the image. verify the image.
``` .. code:: c
/*
/*
* Parameters for authentication by hash matching * 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 *data; /* Data to hash */
auth_param_type_desc_t *hash; /* Hash to match with */ 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 * 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 *pk; /* Public key */
auth_param_type_desc_t *sig; /* Signature to check */ auth_param_type_desc_t *sig; /* Signature to check */
auth_param_type_desc_t *alg; /* Signature algorithm */ auth_param_type_desc_t *alg; /* Signature algorithm */
auth_param_type_desc_t *tbs; /* Data signed */ 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 The AM defines the following structure to describe an authentication method for
verifying an image verifying an image
``` .. code:: c
/*
/*
* Authentication method descriptor * Authentication method descriptor
*/ */
typedef struct auth_method_desc_s { typedef struct auth_method_desc_s {
auth_method_type_t type; auth_method_type_t type;
union { union {
auth_method_param_hash_t hash; auth_method_param_hash_t hash;
auth_method_param_sig_t sig; auth_method_param_sig_t sig;
} param; } param;
} auth_method_desc_t; } auth_method_desc_t;
```
Using the method type specified in the `type` field, the AM finds out what field Using the method type specified in the ``type`` field, the AM finds out what field
needs to access within the `param` union. 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 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 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 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. ...@@ -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 The AM defines the following structure to store the data corresponding to an
authentication parameter. authentication parameter.
``` .. code:: c
typedef struct auth_param_data_desc_s {
typedef struct auth_param_data_desc_s {
void *auth_param_ptr; void *auth_param_ptr;
unsigned int auth_param_len; 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. 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 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 responsible for populating the ``auth_param_ptr`` and ``auth_param_len`` fields
while executing the `img_get_auth_param()` function. while executing the ``img_get_auth_param()`` function.
The AM defines the following structure to enable an image to describe the 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 parameters that should be extracted from it and used to verify the next image
(child) in a CoT. (child) in a CoT.
``` .. code:: c
typedef struct auth_param_desc_s {
typedef struct auth_param_desc_s {
auth_param_type_desc_t type_desc; auth_param_type_desc_t type_desc;
auth_param_data_desc_t data; 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 An image in a CoT is a consolidation of the following aspects of a CoT described
above. 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 to locate the image in a FIP and load it in the memory reserved for the data
image in the CoT. 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. 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 parameters are specified only by authentication images and can be extracted
from the current image once it has been verified. from the current image once it has been verified.
The following data structure describes an image in a CoT. 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; unsigned int img_id;
const struct auth_img_desc_s *parent; const struct auth_img_desc_s *parent;
img_type_t img_type; img_type_t img_type;
auth_method_desc_t img_auth_methods[AUTH_METHOD_NUM]; auth_method_desc_t img_auth_methods[AUTH_METHOD_NUM];
auth_param_desc_t authenticated_data[COT_MAX_VERIFIED_PARAMS]; auth_param_desc_t authenticated_data[COT_MAX_VERIFIED_PARAMS];
} auth_img_desc_t; } 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.
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 This section is a detailed guide explaining a trusted boot implementation using
the authentication framework. This example corresponds to the Applicative the authentication framework. This example corresponds to the Applicative
Functional Mode (AFM) as specified in the TBBR-Client document. It is Functional Mode (AFM) as specified in the TBBR-Client document. It is
recommended to read this guide along with the source code. 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 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 (passing a pointer or any other type of indirection will cause the registration
process to fail). process to fail).
...@@ -632,21 +634,21 @@ The number of images participating in the boot process depends on the CoT. There ...@@ -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 is, however, a minimum set of images that are mandatory in the Trusted Firmware
and thus all CoTs must present: and thus all CoTs must present:
* `BL2` - ``BL2``
* `SCP_BL2` (platform specific) - ``SCP_BL2`` (platform specific)
* `BL31` - ``BL31``
* `BL32` (optional) - ``BL32`` (optional)
* `BL33` - ``BL33``
The TBBR specifies the additional certificates that must accompany these images 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 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 identifiers for all the images and certificates that will be loaded during the
boot process. If a platform is using the TBBR as a reference for trusted boot, boot process. If a platform is using the TBBR as a reference for trusted boot,
these identifiers can be obtained from `include/common/tbbr/tbbr_img_def.h`. these identifiers can be obtained from ``include/common/tbbr/tbbr_img_def.h``.
ARM platforms include this file in `include/plat/arm/common/arm_def.h`. Other ARM platforms include this file in ``include/plat/arm/common/arm_def.h``. Other
platforms may also include this file or provide their own identifiers. platforms may also include this file or provide their own identifiers.
**Important**: the authentication module uses these identifiers to index the **Important**: the authentication module uses these identifiers to index the
...@@ -654,22 +656,24 @@ CoT array, so the descriptors location in the array must match the identifiers. ...@@ -654,22 +656,24 @@ CoT array, so the descriptors location in the array must match the identifiers.
Each image descriptor must specify: Each image descriptor must specify:
* `img_id`: the corresponding image unique identifier defined by the platform. - ``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_type``: the image parser module uses the image type to call the proper
parsing library to check the image integrity and extract the required parsing library to check the image integrity and extract the required
authentication parameters. Three types of images are currently supported: 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. 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 type for custom images not directly supported by the authentication
framework. framework.
* `IMG_CERT`: image is an x509v3 certificate. - ``IMG_CERT``: image is an x509v3 certificate.
* `parent`: pointer to the parent image descriptor. The parent will contain
- ``parent``: pointer to the parent image descriptor. The parent will contain
the information required to authenticate the current image. If the parent the information required to authenticate the current image. If the parent
is NULL, the authentication parameters will be obtained from the platform 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 (i.e. the BL2 and Trusted Key certificates are signed with the ROT private
key, whose public part is stored in the platform). 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 be checked to consider an image authenticated. Each method consists of a
type and a list of parameter descriptors. A parameter descriptor consists of 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 a type and a cookie which will point to specific information required to
...@@ -677,26 +681,31 @@ Each image descriptor must specify: ...@@ -677,26 +681,31 @@ Each image descriptor must specify:
x509v3 extension, the cookie will point to the extension OID). Depending on x509v3 extension, the cookie will point to the extension OID). Depending on
the method type, a different number of parameters must be specified. the method type, a different number of parameters must be specified.
Supported methods are: 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 from the parent image. The following parameter descriptors must be
specified: specified:
* `data`: data to be hashed (obtained from current image)
* `hash`: reference hash (obtained from parent image) - ``data``: data to be hashed (obtained from current image)
* `AUTH_METHOD_SIG`: the image (usually a certificate) must be signed with - ``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 private key whose public part is extracted from the parent image (or
the platform if the parent is NULL). The following parameter descriptors the platform if the parent is NULL). The following parameter descriptors
must be specified: must be specified:
* `pk`: the public key (obtained from parent image)
* `sig`: the digital signature (obtained from current image) - ``pk``: the public key (obtained from parent image)
* `alg`: the signature algorithm used (obtained from current image) - ``sig``: the digital signature (obtained from current image)
* `data`: the data to be signed (obtained from current image) - ``alg``: the signature algorithm used (obtained from current image)
* `authenticated_data`: this array indicates what authentication parameters - ``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 must be extracted from an image once it has been authenticated. Each
parameter consists of a parameter descriptor and the buffer address/size parameter consists of a parameter descriptor and the buffer address/size
to store the parameter. The CoT is responsible for allocating the required to store the parameter. The CoT is responsible for allocating the required
memory to store the parameters. 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 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 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 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. ...@@ -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 Next in that file, the parameter descriptors are defined. These descriptors will
be used to extract the parameter data from the corresponding image. 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: Four image descriptors form the BL31 Chain of Trust:
``` .. code:: asm
[TRUSTED_KEY_CERT_ID] = {
[TRUSTED_KEY_CERT_ID] = {
.img_id = TRUSTED_KEY_CERT_ID, .img_id = TRUSTED_KEY_CERT_ID,
.img_type = IMG_CERT, .img_type = IMG_CERT,
.parent = NULL, .parent = NULL,
...@@ -741,8 +752,8 @@ Four image descriptors form the BL31 Chain of Trust: ...@@ -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_id = SOC_FW_KEY_CERT_ID,
.img_type = IMG_CERT, .img_type = IMG_CERT,
.parent = &cot_desc[TRUSTED_KEY_CERT_ID], .parent = &cot_desc[TRUSTED_KEY_CERT_ID],
...@@ -766,8 +777,8 @@ Four image descriptors form the BL31 Chain of Trust: ...@@ -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_id = SOC_FW_CONTENT_CERT_ID,
.img_type = IMG_CERT, .img_type = IMG_CERT,
.parent = &cot_desc[SOC_FW_KEY_CERT_ID], .parent = &cot_desc[SOC_FW_KEY_CERT_ID],
...@@ -791,8 +802,8 @@ Four image descriptors form the BL31 Chain of Trust: ...@@ -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_id = BL31_IMAGE_ID,
.img_type = IMG_RAW, .img_type = IMG_RAW,
.parent = &cot_desc[SOC_FW_CONTENT_CERT_ID], .parent = &cot_desc[SOC_FW_CONTENT_CERT_ID],
...@@ -805,63 +816,64 @@ Four image descriptors form the BL31 Chain of Trust: ...@@ -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 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 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 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 The Trusted Key certificate is authenticated by checking its digital signature
using the ROTPK. Four parameters are required to check a signature: the public 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, key, the algorithm, the signature and the data that has been signed. Therefore,
four parameter descriptors must be specified with the authentication method: 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 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 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 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 the parent image is NULL, the public key is obtained from the platform
(this key will be the ROTPK). (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. 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. 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. to extract the data to be signed from the certificate.
Once the signature has been checked and the certificate authenticated, the 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 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 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 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 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 The **BL31 Key certificate** is authenticated by checking its digital signature
using the Trusted World public key obtained previously from the Trusted Key using the Trusted World public key obtained previously from the Trusted Key
certificate. In the image descriptor, we specify a single authentication method 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 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 extension specified by ``bl31_content_pk``. This key will be copied to the
`plat_content_pk` buffer. ``plat_content_pk`` buffer.
The **BL31 certificate** is authenticated by checking its digital signature The **BL31 certificate** is authenticated by checking its digital signature
using the BL31 public key obtained previously from the BL31 Key certificate. 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 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. buffer.
The **BL31 image** is authenticated by calculating its hash and matching it The **BL31 image** is authenticated by calculating its hash and matching it
with the hash obtained from the BL31 certificate. The image descriptor contains 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 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 reference hash, ``bl31_hash``, and the data to be hashed. In this case, it is
the whole image, so we specify `raw_data`. 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 The image parser module relies on libraries to check the image integrity and
extract the authentication parameters. The number and type of parser libraries 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 ...@@ -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. only an x509v3 library is required for the TBBR CoT.
ARM platforms will use an x509v3 library based on mbed TLS. This library may be ARM platforms will use an x509v3 library based on mbed TLS. This library may be
found in `drivers/auth/mbedtls/mbedtls_x509_parser.c`. It exports three found in ``drivers/auth/mbedtls/mbedtls_x509_parser.c``. It exports three
functions: functions:
``` .. code:: c
void init(void);
int check_integrity(void *img, unsigned int img_len); void init(void);
int get_auth_param(const auth_param_type_desc_t *type_desc, 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 *img, unsigned int img_len,
void **param, unsigned int *param_len); void **param, unsigned int *param_len);
```
The library is registered in the framework using the macro The library is registered in the framework using the macro
`REGISTER_IMG_PARSER_LIB()`. Each time the image parser module needs to access ``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 an image of type ``IMG_CERT``, it will call the corresponding function exported
in this file. in this file.
The build system must be updated to include the corresponding library and The build system must be updated to include the corresponding library and
mbed TLS sources. ARM platforms use the `arm_common.mk` file to pull the mbed TLS sources. ARM platforms use the ``arm_common.mk`` file to pull the
sources. sources.
### 4.3 The cryptographic library The cryptographic library
~~~~~~~~~~~~~~~~~~~~~~~~~
The cryptographic module relies on a library to perform the required operations, The cryptographic module relies on a library to perform the required operations,
i.e. verify a hash or a digital signature. ARM platforms will use a library i.e. verify a hash or a digital signature. ARM platforms will use a library
based on mbed TLS, which can be found in based on mbed TLS, which can be found in
`drivers/auth/mbedtls/mbedtls_crypto.c`. This library is registered in the ``drivers/auth/mbedtls/mbedtls_crypto.c``. This library is registered in the
authentication framework using the macro `REGISTER_CRYPTO_LIB()` and exports authentication framework using the macro ``REGISTER_CRYPTO_LIB()`` and exports
three functions: three functions:
``` .. code:: c
void init(void);
int verify_signature(void *data_ptr, unsigned int data_len, void init(void);
int verify_signature(void *data_ptr, unsigned int data_len,
void *sig_ptr, unsigned int sig_len, void *sig_ptr, unsigned int sig_len,
void *sig_alg, unsigned int sig_alg_len, void *sig_alg, unsigned int sig_alg_len,
void *pk_ptr, unsigned int pk_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); void *digest_info_ptr, unsigned int digest_info_len);
```
The key algorithm (rsa, ecdsa) must be specified in the build system using the 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. 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 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%). 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 .. _Trusted Board Boot: ./trusted-board-boot.rst
[Platform Porting Guide]: ./porting-guide.md .. _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 ARM Trusted Firmware Design
=========================== ===========================
Contents :
.. section-numbering::
1. [Introduction](#1--introduction) :suffix: .
2. [Cold boot](#2--cold-boot)
3. [EL3 runtime services framework](#3--el3-runtime-services-framework) .. contents::
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
----------------
The ARM Trusted Firmware implements a subset of the Trusted Board Boot 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 platforms. The TBB sequence starts when the platform is powered on and runs up
to the stage where it hands-off control to firmware running in the normal to the stage where it hands-off control to firmware running in the normal
world in DRAM. This is the cold boot path. world in DRAM. This is the cold boot path.
The ARM Trusted Firmware also implements the Power State Coordination Interface 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 PDD [2]_ as a runtime service. PSCI is the interface from normal world software
software to firmware implementing power management use-cases (for example, to firmware implementing power management use-cases (for example, secondary CPU
secondary CPU boot, hotplug and idle). Normal world software can access ARM boot, hotplug and idle). Normal world software can access ARM Trusted Firmware
Trusted Firmware runtime services via the ARM SMC (Secure Monitor Call) runtime services via the ARM SMC (Secure Monitor Call) instruction. The SMC
instruction. The SMC instruction must be used as mandated by the [SMC Calling instruction must be used as mandated by the SMC Calling Convention [3]_.
Convention PDD][SMCCC] [3].
The ARM Trusted Firmware implements a framework for configuring and managing The ARM Trusted Firmware implements a framework for configuring and managing
interrupts generated in either security state. The details of the interrupt interrupts generated in either security state. The details of the interrupt
management framework and its design can be found in [ARM Trusted management framework and its design can be found in ARM Trusted Firmware
Firmware Interrupt Management Design guide][INTRG] [4]. Interrupt Management Design guide [4]_.
The ARM Trusted Firmware can be built to support either AArch64 or AArch32 The ARM Trusted Firmware can be built to support either AArch64 or AArch32
execution state. execution state.
2. Cold boot Cold boot
------------- ---------
The cold boot path starts when the platform is physically turned on. If 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 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 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 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 all CPUs. The secondary CPUs are kept in a safe platform-specific state until
the primary CPU has performed enough initialization to boot them. the primary CPU has performed enough initialization to boot them.
Refer to the [Reset Design] for more information on the effect of the Refer to the `Reset Design`_ for more information on the effect of the
`COLD_BOOT_SINGLE_CPU` platform build option. ``COLD_BOOT_SINGLE_CPU`` platform build option.
The cold boot path in this implementation of the ARM Trusted Firmware, The cold boot path in this implementation of the ARM Trusted Firmware,
depends on the execution state. depends on the execution state.
For AArch64, it is divided into five steps (in order of execution): For AArch64, it is divided into five steps (in order of execution):
* Boot Loader stage 1 (BL1) _AP Trusted ROM_ - Boot Loader stage 1 (BL1) *AP Trusted ROM*
* Boot Loader stage 2 (BL2) _Trusted Boot Firmware_ - Boot Loader stage 2 (BL2) *Trusted Boot Firmware*
* Boot Loader stage 3-1 (BL31) _EL3 Runtime Software_ - Boot Loader stage 3-1 (BL31) *EL3 Runtime Software*
* Boot Loader stage 3-2 (BL32) _Secure-EL1 Payload_ (optional) - Boot Loader stage 3-2 (BL32) *Secure-EL1 Payload* (optional)
* Boot Loader stage 3-3 (BL33) _Non-trusted Firmware_ - Boot Loader stage 3-3 (BL33) *Non-trusted Firmware*
For AArch32, it is divided into four steps (in order of execution): For AArch32, it is divided into four steps (in order of execution):
* Boot Loader stage 1 (BL1) _AP Trusted ROM_ - Boot Loader stage 1 (BL1) *AP Trusted ROM*
* Boot Loader stage 2 (BL2) _Trusted Boot Firmware_ - Boot Loader stage 2 (BL2) *Trusted Boot Firmware*
* Boot Loader stage 3-2 (BL32) _EL3 Runtime Software_ - Boot Loader stage 3-2 (BL32) *EL3 Runtime Software*
* Boot Loader stage 3-3 (BL33) _Non-trusted Firmware_ - Boot Loader stage 3-3 (BL33) *Non-trusted Firmware*
ARM development platforms (Fixed Virtual Platforms (FVPs) and Juno) implement a ARM development platforms (Fixed Virtual Platforms (FVPs) and Juno) implement a
combination of the following types of memory regions. Each bootloader stage uses combination of the following types of memory regions. Each bootloader stage uses
one or more of these memory regions. one or more of these memory regions.
* 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. 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 ROM. The FVPs also implement the trusted DRAM which is statically
configured. Additionally, the Base FVPs and Juno development platform configured. Additionally, the Base FVPs and Juno development platform
configure the TrustZone Controller (TZC) to create a region in the DRAM configure the TrustZone Controller (TZC) to create a region in the DRAM
which is accessible only from the secure state. which is accessible only from the secure state.
The sections below provide the following details: The sections below provide the following details:
* initialization and execution of the first three stages during cold boot - initialization and execution of the first three stages during cold boot
* specification of the EL3 Runtime Software (BL31 for AArch64 and BL32 for - specification of the EL3 Runtime Software (BL31 for AArch64 and BL32 for
AArch32) entrypoint requirements for use by alternative Trusted Boot AArch32) entrypoint requirements for use by alternative Trusted Boot
Firmware in place of the provided BL1 and BL2 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 This stage begins execution from the platform's reset vector at EL3. The reset
address is platform dependent but it is usually located in a Trusted ROM area. address is platform dependent but it is usually located in a Trusted ROM area.
The BL1 data section is copied to trusted SRAM at runtime. The BL1 data section is copied to trusted SRAM at runtime.
On the ARM development platforms, BL1 code starts execution from the reset On the ARM development platforms, BL1 code starts execution from the reset
vector defined by the constant `BL1_RO_BASE`. The BL1 data section is copied vector defined by the constant ``BL1_RO_BASE``. The BL1 data section is copied
to the top of trusted SRAM as defined by the constant `BL1_RW_BASE`. to the top of trusted SRAM as defined by the constant ``BL1_RW_BASE``.
The functionality implemented by this stage is as follows. 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 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 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 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 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 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 the `Porting Guide`_) while the primary CPU executes the remaining cold boot path
as described in the following sections. as described in the following sections.
This step only applies when `PROGRAMMABLE_RESET_ADDRESS=0`. Refer to the This step only applies when ``PROGRAMMABLE_RESET_ADDRESS=0``. Refer to the
[Reset Design] for more information on the effect of the `Reset Design`_ for more information on the effect of the
`PROGRAMMABLE_RESET_ADDRESS` platform build option. ``PROGRAMMABLE_RESET_ADDRESS`` platform build option.
#### Architectural initialization Architectural initialization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
BL1 performs minimal architectural initialization as follows. BL1 performs minimal architectural initialization as follows.
* Exception vectors - Exception vectors
BL1 sets up simple exception vectors for both synchronous and asynchronous BL1 sets up simple exception vectors for both synchronous and asynchronous
exceptions. The default behavior upon receiving an exception is to populate exceptions. The default behavior upon receiving an exception is to populate
a status code in the general purpose register `X0/R0` and call the a status code in the general purpose register ``X0/R0`` and call the
`plat_report_exception()` function (see the [Porting Guide]). The status ``plat_report_exception()`` function (see the `Porting Guide`_). The status
code is one of: code is one of:
For AArch64: For AArch64:
::
0x0 : Synchronous exception from Current EL with SP_EL0 0x0 : Synchronous exception from Current EL with SP_EL0
0x1 : IRQ 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 0x2 : FIQ exception from Current EL with SP_EL0
...@@ -158,6 +143,8 @@ BL1 performs minimal architectural initialization as follows. ...@@ -158,6 +143,8 @@ BL1 performs minimal architectural initialization as follows.
For AArch32: For AArch32:
::
0x10 : User mode 0x10 : User mode
0x11 : FIQ mode 0x11 : FIQ mode
0x12 : IRQ mode 0x12 : IRQ mode
...@@ -168,10 +155,12 @@ BL1 performs minimal architectural initialization as follows. ...@@ -168,10 +155,12 @@ BL1 performs minimal architectural initialization as follows.
0x1b : Undefined mode 0x1b : Undefined mode
0x1f : System mode 0x1f : System mode
The `plat_report_exception()` implementation on the ARM FVP port programs The ``plat_report_exception()`` implementation on the ARM FVP port programs
the Versatile Express System LED register in the following format to the Versatile Express System LED register in the following format to
indicate the occurence of an unexpected exception: indicate the occurence of an unexpected exception:
::
SYS_LED[0] - Security state (Secure=0/Non-Secure=1) SYS_LED[0] - Security state (Secure=0/Non-Secure=1)
SYS_LED[2:1] - Exception Level (EL3=0x3, EL2=0x2, EL1=0x1, EL0=0x0) SYS_LED[2:1] - Exception Level (EL3=0x3, EL2=0x2, EL1=0x1, EL0=0x0)
For AArch32 it is always 0x0 For AArch32 it is always 0x0
...@@ -184,115 +173,125 @@ BL1 performs minimal architectural initialization as follows. ...@@ -184,115 +173,125 @@ BL1 performs minimal architectural initialization as follows.
BL1 does not expect to receive any exceptions other than the SMC exception. 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 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 limited set of SMC types (determined by their function IDs in the general
purpose register `X0/R0`): purpose register ``X0/R0``):
- `BL1_SMC_RUN_IMAGE`: This SMC is raised by BL2 to make BL1 pass control
- ``BL1_SMC_RUN_IMAGE``: This SMC is raised by BL2 to make BL1 pass control
to EL3 Runtime Software. 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 Design Guide are supported for AArch64 only. These SMCs are currently
not supported when BL1 is built for AArch32. not supported when BL1 is built for AArch32.
Any other SMC leads to an assertion failure. 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 specific reset handler function (see the section: "CPU specific operations
framework"). framework").
* Control register setup (for AArch64) - Control register setup (for AArch64)
- `SCTLR_EL3`. Instruction cache is enabled by setting the `SCTLR_EL3.I`
- ``SCTLR_EL3``. Instruction cache is enabled by setting the ``SCTLR_EL3.I``
bit. Alignment and stack alignment checking is enabled by setting the bit. Alignment and stack alignment checking is enabled by setting the
`SCTLR_EL3.A` and `SCTLR_EL3.SA` bits. Exception endianness is set to ``SCTLR_EL3.A`` and ``SCTLR_EL3.SA`` bits. Exception endianness is set to
little-endian by clearing the `SCTLR_EL3.EE` bit. little-endian by clearing the ``SCTLR_EL3.EE`` bit.
- `SCR_EL3`. The register width of the next lower exception level is set - ``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 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 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 also set to disable instruction fetches from Non-secure memory when in
secure state. secure state.
- `CPTR_EL3`. Accesses to the `CPACR_EL1` register from EL1 or EL2, or the - ``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 ``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 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. configured not to trap to EL3 by clearing the ``CPTR_EL3.TTA`` bit.
Instructions that access the registers associated with Floating Point Instructions that access the registers associated with Floating Point
and Advanced SIMD execution are configured to not trap to EL3 by 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. mask bit.
- `MDCR_EL3`. The trap controls, `MDCR_EL3.TDOSA`, `MDCR_EL3.TDA` and - ``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.TPM``, are set so that accesses to the registers they control
do not trap to EL3. AArch64 Secure self-hosted debug is disabled by 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. disable AArch32 Secure self-hosted privileged debug from S-EL1.
* Control register setup (for AArch32) - 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. - ``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 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. Non-secure memory when in secure state.
- `CPACR`. Allow execution of Advanced SIMD instructions at PL0 and PL1, - ``CPACR``. Allow execution of Advanced SIMD instructions at PL0 and PL1,
by clearing the `CPACR.ASEDIS` bit. Access to the trace functionality by clearing the ``CPACR.ASEDIS`` bit. Access to the trace functionality
is configured not to trap to undefined mode by clearing the 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. 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. 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. 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. self-hosted privileged debug.
#### Platform initialization Platform initialization
^^^^^^^^^^^^^^^^^^^^^^^
On ARM platforms, BL1 performs the following platform initializations: On ARM platforms, BL1 performs the following platform initializations:
* Enable the Trusted Watchdog. - Enable the Trusted Watchdog.
* Initialize the console. - Initialize the console.
* Configure the Interconnect to enable hardware coherency. - Configure the Interconnect to enable hardware coherency.
* Enable the MMU and map the memory it needs to access. - Enable the MMU and map the memory it needs to access.
* Configure any required platform storage to load the next bootloader image - Configure any required platform storage to load the next bootloader image
(BL2). (BL2).
#### Firmware Update detection and execution Firmware Update detection and execution
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
After performing platform setup, BL1 common code calls 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 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 ``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 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 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()`. 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 The image descriptor contains an ``entry_point_info_t`` structure, which BL1
uses to initialize the execution state of the next image. 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: 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: execution of the BL1 stage:
::
"Booting Trusted Firmware" "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 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 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 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 there is not enough free trusted SRAM the following error message is
printed: printed:
::
"Failed to load BL2 firmware." "Failed to load BL2 firmware."
BL1 calculates the amount of Trusted SRAM that can be used by the BL2 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: ...@@ -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 in the platform header. Further description of the memory layout can be
found later in this document. 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. 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 available for use. This information is populated at a platform-specific
memory address. memory address.
BL2
### BL2 ~~~
BL1 loads and passes control to BL2 at Secure-EL1 (for AArch64) or at Secure 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 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). base address (more information can be found later in this document).
The functionality implemented by BL2 is as follows. The functionality implemented by BL2 is as follows.
#### Architectural initialization Architectural initialization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
For AArch64, BL2 performs the minimal architectural initialization required For AArch64, BL2 performs the minimal architectural initialization required
for subsequent stages of the ARM Trusted Firmware and normal world software. for subsequent stages of the ARM Trusted Firmware and normal world software.
EL1 and EL0 are given access to Floating Point and Advanced SIMD registers 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 For AArch32, the minimal architectural initialization required for subsequent
stages of the ARM Trusted Firmware and normal world software is taken care of stages of the ARM Trusted Firmware and normal world software is taken care of
in BL1 as both BL1 and BL2 execute at PL1. in BL1 as both BL1 and BL2 execute at PL1.
#### Platform initialization Platform initialization
^^^^^^^^^^^^^^^^^^^^^^^
On ARM platforms, BL2 performs the following platform initializations: On ARM platforms, BL2 performs the following platform initializations:
* Initialize the console. - Initialize the console.
* Configure any required platform storage to allow loading further bootloader - Configure any required platform storage to allow loading further bootloader
images. images.
* Enable the MMU and map the memory it needs to access. - Enable the MMU and map the memory it needs to access.
* Perform platform security setup to allow access to controlled components. - Perform platform security setup to allow access to controlled components.
* Reserve some memory for passing information to the next bootloader image - Reserve some memory for passing information to the next bootloader image
EL3 Runtime Software and populate it. 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. 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 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 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 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 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. 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, Some systems have a separate System Control Processor (SCP) for power, clock,
reset and system control. BL2 loads the optional SCP_BL2 image from platform reset and system control. BL2 loads the optional SCP\_BL2 image from platform
storage into a platform-specific region of secure memory. The subsequent storage into a platform-specific region of secure memory. The subsequent
handling of SCP_BL2 is platform specific. For example, on the Juno ARM handling of SCP\_BL2 is platform specific. For example, on the Juno ARM
development platform port the image is transferred into SCP's internal memory development platform port the image is transferred into SCP's internal memory
using the Boot Over MHU (BOM) protocol after being loaded in the trusted SRAM using the Boot Over MHU (BOM) protocol after being loaded in the trusted SRAM
memory. The SCP executes SCP_BL2 and signals to the Application Processor (AP) memory. The SCP executes SCP\_BL2 and signals to the Application Processor (AP)
for BL2 execution to continue. 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- 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 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 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 SRAM used and available for use by EL3 Runtime Software. This information is
populated at a platform-specific memory address. 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- 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 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 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 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 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 Secure-EL1 Payload Dispatcher (see later) within BL31, which is responsible for
managing interaction with BL32. This information is passed to BL31. 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 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. 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 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 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 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] image. The ``SPSR`` is determined as specified in Section 5.13 of the
[PSCI]. This information is passed to the EL3 Runtime Software. `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: 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 BL31 entrypoint. The exception is handled by the SMC exception handler
installed by BL1. installed by BL1.
2. BL1 turns off the MMU and flushes the caches. It clears the #. 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 ``SCTLR_EL3.M/I/C`` bits, flushes the data cache to the point of coherency
and invalidates the TLBs. 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 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 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 loaded at a platform-specific base address (more information can be found later
in this document). The functionality implemented by BL31 is as follows. 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 Currently, BL31 performs a similar architectural initialization to BL1 as
far as system register settings are concerned. Since BL1 code resides in ROM, 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 ...@@ -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 exception vectors implement more elaborate support for handling SMCs since this
is the only mechanism to access the runtime services implemented by BL31 (PSCI 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 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. 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. counter, which is provided by the platform.
#### Platform initialization Platform initialization
^^^^^^^^^^^^^^^^^^^^^^^
BL31 performs detailed platform initialization, which enables normal world BL31 performs detailed platform initialization, which enables normal world
software to function correctly. software to function correctly.
On ARM platforms, this consists of the following: On ARM platforms, this consists of the following:
* Initialize the console. - Initialize the console.
* Configure the Interconnect to enable hardware coherency. - Configure the Interconnect to enable hardware coherency.
* Enable the MMU and map the memory it needs to access. - Enable the MMU and map the memory it needs to access.
* Initialize the generic interrupt controller. - Initialize the generic interrupt controller.
* Initialize the power controller device. - Initialize the power controller device.
* Detect the system topology. - Detect the system topology.
#### Runtime services initialization Runtime services initialization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
BL31 is responsible for initializing the runtime services. One of them is PSCI. 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 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 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 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 ``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 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 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 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, 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. ...@@ -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 Details about the status of the PSCI implementation are provided in the
"Power State Coordination Interface" section below. "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 If a BL32 image is present then there must be a matching Secure-EL1 Payload
Dispatcher (SPD) service (see later for details). During initialization Dispatcher (SPD) service (see later for details). During initialization
...@@ -483,7 +494,8 @@ is not necessary for AArch32 SPs. ...@@ -483,7 +494,8 @@ is not necessary for AArch32 SPs.
Details on BL32 initialization and the SPD's role are described in the Details on BL32 initialization and the SPD's role are described in the
"Secure-EL1 Payloads and Dispatchers" section below. "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- 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 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 ...@@ -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) information provided by BL2 to jump to the Non-trusted firmware image (BL33)
at the highest available Exception Level (EL2 if available, otherwise EL1). 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 Some platforms have existing implementations of Trusted Boot Firmware that
would like to use ARM Trusted Firmware BL31 for the EL3 Runtime Software. To would like to use 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 ...@@ -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/ way, and this enables these firmware components to be independently enhanced/
updated to develop and exploit new functionality. 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. This function must only be called by the primary CPU.
On entry to this function the calling primary CPU must be executing in AArch64 On entry to this function the calling primary CPU must be executing in AArch64
EL3, little-endian data access, and all interrupt sources masked: EL3, little-endian data access, and all interrupt sources masked:
::
PSTATE.EL = 3 PSTATE.EL = 3
PSTATE.RW = 1 PSTATE.RW = 1
PSTATE.DAIF = 0xf PSTATE.DAIF = 0xf
...@@ -517,24 +533,27 @@ EL3, little-endian data access, and all interrupt sources masked: ...@@ -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 X0 and X1 can be used to pass information from the Trusted Boot Firmware to the
platform code in BL31: platform code in BL31:
::
X0 : Reserved for common Trusted Firmware information X0 : Reserved for common Trusted Firmware information
X1 : Platform specific information X1 : Platform specific information
BL31 zero-init sections (e.g. `.bss`) should not contain valid data on entry, BL31 zero-init sections (e.g. ``.bss``) should not contain valid data on entry,
these will be zero filled prior to invoking platform setup code. 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 The parameters are platform specific and passed from ``bl31_entrypoint()`` to
`bl31_early_platform_setup()`. The value of these parameters is never directly ``bl31_early_platform_setup()``. The value of these parameters is never directly
used by the common BL31 code. used by the common BL31 code.
The convention is that `X0` conveys information regarding the BL31, BL32 and The convention is that ``X0`` conveys information regarding the BL31, BL32 and
BL33 images from the Trusted Boot firmware and `X1` can be used for other BL33 images from the Trusted Boot firmware and ``X1`` can be used for other
platform specific purpose. This convention allows platforms which use ARM platform specific purpose. This convention allows platforms which use ARM
Trusted Firmware's BL1 and BL2 images to transfer additional platform specific Trusted Firmware's BL1 and BL2 images to transfer additional platform specific
information from Secure Boot without conflicting with future evolution of the 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 BL31 common and SPD initialization code depends on image and entrypoint
information about BL33 and BL32, which is provided via BL31 platform APIs. information about BL33 and BL32, which is provided via BL31 platform APIs.
...@@ -546,28 +565,32 @@ Cold boot Initialization parameters. This data may need to be cleaned out of ...@@ -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 the CPU caches if it is provided by an earlier boot stage and then accessed by
BL31 platform code before the caches are enabled. BL31 platform code before the caches are enabled.
ARM Trusted Firmware's BL2 implementation passes a `bl31_params` structure in ARM Trusted Firmware's BL2 implementation passes a ``bl31_params`` structure in
`X0` and the ARM development platforms interpret this in the BL31 platform ``X0`` and the ARM development platforms interpret this in the BL31 platform
code. code.
##### MMU, Data caches & Coherency MMU, Data caches & Coherency
''''''''''''''''''''''''''''
BL31 does not depend on the enabled state of the MMU, data caches or 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 interconnect coherency on entry to ``bl31_entrypoint()``. If these are disabled
on entry, these should be enabled during `bl31_plat_arch_setup()`. 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 These structures are designed to support compatibility and independent
evolution of the structures and the firmware images. For example, a version of 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 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 additional register information to BL31, or a ELF image loader that can convey
more details about the firmware images. more details about the firmware images.
To support these scenarios the structures are versioned and sized, which enables To support these scenarios the structures are versioned and sized, which enables
BL31 to detect which information is present and respond appropriately. The 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 { typedef struct param_header {
uint8_t type; /* type of the structure */ uint8_t type; /* type of the structure */
...@@ -576,12 +599,13 @@ BL31 to detect which information is present and respond appropriately. The ...@@ -576,12 +599,13 @@ BL31 to detect which information is present and respond appropriately. The
uint32_t attr; /* attributes: unused bits SBZ */ uint32_t attr; /* attributes: unused bits SBZ */
} param_header_t; } param_header_t;
The structures using this format are `entry_point_info`, `image_info` and The structures using this format are ``entry_point_info``, ``image_info`` and
`bl31_params`. The code that allocates and populates these structures must set ``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 header fields appropriately, and the ``SET_PARAM_HEAD()`` a macro is defined
to simplify this action. to simplify this action.
#### Required CPU state for BL31 Warm boot initialization Required CPU state for BL31 Warm boot initialization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When requesting a CPU power-on, or suspending a running CPU, ARM Trusted When requesting a CPU power-on, or suspending a running CPU, ARM Trusted
Firmware provides the platform power management code with a Warm boot 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 ...@@ -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 CPU must be in AArch64 EL3, little-endian data access and all interrupt sources
masked: masked:
::
PSTATE.EL = 3 PSTATE.EL = 3
PSTATE.RW = 1 PSTATE.RW = 1
PSTATE.DAIF = 0xf PSTATE.DAIF = 0xf
...@@ -599,7 +625,8 @@ The PSCI implementation will initialize the processor state and ensure that the ...@@ -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 platform power management code is then invoked as required to initialize all
necessary system, cluster and CPU resources. 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 To enable this firmware architecture it is important to provide a fully
documented and stable interface between the Trusted Boot Firmware and the 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 ...@@ -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 compatible way, and this enables these firmware components to be independently
enhanced/updated to develop and exploit new functionality. 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. This function must only be called by the primary CPU.
On entry to this function the calling primary CPU must be executing in AArch32 On entry to this function the calling primary CPU must be executing in AArch32
EL3, little-endian data access, and all interrupt sources masked: EL3, little-endian data access, and all interrupt sources masked:
::
PSTATE.AIF = 0x7 PSTATE.AIF = 0x7
SCTLR.EE = 0 SCTLR.EE = 0
R0 and R1 are used to pass information from the Trusted Boot Firmware to the R0 and R1 are used to pass information from the Trusted Boot Firmware to the
platform code in AArch32 EL3 Runtime Software: platform code in AArch32 EL3 Runtime Software:
::
R0 : Reserved for common Trusted Firmware information R0 : Reserved for common Trusted Firmware information
R1 : Platform specific 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 The parameters are platform specific and the convention is that ``R0`` conveys
information regarding the BL3x images from the Trusted Boot firmware and `R1` information regarding the BL3x images from the Trusted Boot firmware and ``R1``
can be used for other platform specific purpose. This convention allows can be used for other platform specific purpose. This convention allows
platforms which use ARM Trusted Firmware's BL1 and BL2 images to transfer platforms which use ARM Trusted Firmware's BL1 and BL2 images to transfer
additional platform specific information from Secure Boot without conflicting 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. structure.
The AArch32 EL3 Runtime Software is responsible for entry into BL33. This The AArch32 EL3 Runtime Software is responsible for entry into BL33. This
...@@ -644,48 +677,52 @@ out of the CPU caches if it is provided by an earlier boot stage and then ...@@ -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. accessed by AArch32 EL3 Runtime Software before the caches are enabled.
When using AArch32 EL3 Runtime Software, the ARM development platforms pass a When using AArch32 EL3 Runtime Software, the ARM development platforms pass a
`bl_params` structure in `R0` from BL2 to be interpreted by AArch32 EL3 Runtime ``bl_params`` structure in ``R0`` from BL2 to be interpreted by AArch32 EL3 Runtime
Software platform code. Software platform code.
##### MMU, Data caches & Coherency MMU, Data caches & Coherency
''''''''''''''''''''''''''''
AArch32 EL3 Runtime Software must not depend on the enabled state of the MMU, 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 data caches or interconnect coherency in its entrypoint. They must be explicitly
enabled if required. 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 The AArch32 EL3 Runtime Software cold boot interface uses ``bl_params`` instead
of `bl31_params`. The `bl_params` structure is based on the convention of ``bl31_params``. The ``bl_params`` structure is based on the convention
described in AArch64 BL31 cold boot interface section. 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 When requesting a CPU power-on, or suspending a running CPU, AArch32 EL3
Runtime Software must ensure execution of a warm boot initialization entrypoint. Runtime Software must ensure execution of a warm boot initialization entrypoint.
If ARM Trusted Firmware BL1 is used and the PROGRAMMABLE_RESET_ADDRESS build If 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 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, 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 In this case, the warm boot entrypoint must be in AArch32 EL3, little-endian
data access and all interrupt sources masked: data access and all interrupt sources masked:
::
PSTATE.AIF = 0x7 PSTATE.AIF = 0x7
SCTLR.EE = 0 SCTLR.EE = 0
The warm boot entrypoint may be implemented by using the ARM Trusted Firmware The warm boot entrypoint may be implemented by using the ARM Trusted Firmware
`psci_warmboot_entrypoint()` function. In that case, the platform must fulfil ``psci_warmboot_entrypoint()`` function. In that case, the platform must fulfil
the pre-requisites mentioned in the [PSCI Library integration guide] the pre-requisites mentioned in the `PSCI Library integration guide`_.
[PSCI Lib guide].
3. EL3 runtime services framework EL3 runtime services framework
---------------------------------- ------------------------------
Software executing in the non-secure state and in the secure state at exception 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 levels lower than EL3 will request runtime services using the Secure Monitor
Call (SMC) instruction. These requests will follow the convention described in 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 identifiers to each SMC request and describes how arguments are passed and
returned. returned.
...@@ -696,7 +733,7 @@ registration, initialization and use of runtime services in EL3 Runtime ...@@ -696,7 +733,7 @@ registration, initialization and use of runtime services in EL3 Runtime
Software (BL31). Software (BL31).
The design of the runtime services depends heavily on the concepts and 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 Entity Numbers (OEN), Fast and Yielding calls, and the SMC32 and SMC64 calling
conventions. Please refer to that document for more detailed explanation of conventions. Please refer to that document for more detailed explanation of
these terms. these terms.
...@@ -704,23 +741,23 @@ these terms. ...@@ -704,23 +741,23 @@ these terms.
The following runtime services are expected to be implemented first. They have The following runtime services are expected to be implemented first. They have
not all been instantiated in the current implementation. 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 This service is for management of the entire system. The Power State
Coordination Interface ([PSCI]) is the first set of standard service calls Coordination Interface (`PSCI`_) is the first set of standard service calls
defined by ARM (see PSCI section later). defined by ARM (see PSCI section later).
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 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). 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 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. Application Call OEN ranges.
The interface between the EL3 Runtime Software and the Secure-EL1 Payload is The interface between the EL3 Runtime Software and the Secure-EL1 Payload is
not defined by the [SMCCC] or any other standard. As a result, each not defined by the `SMCCC`_ or any other standard. As a result, each
Secure-EL1 Payload requires a specific Secure Monitor that runs as a runtime Secure-EL1 Payload requires a specific Secure Monitor that runs as a runtime
service - within ARM Trusted Firmware this service is referred to as the service - within ARM Trusted Firmware this service is referred to as the
Secure-EL1 Payload Dispatcher (SPD). Secure-EL1 Payload Dispatcher (SPD).
...@@ -729,7 +766,7 @@ not all been instantiated in the current implementation. ...@@ -729,7 +766,7 @@ not all been instantiated in the current implementation.
associated Dispatcher (TSPD). Details of SPD design and TSP/TSPD operation associated Dispatcher (TSPD). Details of SPD design and TSP/TSPD operation
are described in the "Secure-EL1 Payloads and Dispatchers" section below. 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 This service will provide an interface to CPU implementation specific
services for a given platform e.g. access to processor errata workarounds. services for a given platform e.g. access to processor errata workarounds.
...@@ -737,16 +774,15 @@ not all been instantiated in the current implementation. ...@@ -737,16 +774,15 @@ not all been instantiated in the current implementation.
Additional services for ARM Architecture, SiP and OEM calls can be implemented. Additional services for ARM Architecture, SiP and OEM calls can be implemented.
Each implemented service handles a range of SMC function identifiers as Each implemented service handles a range of SMC function identifiers as
described in the [SMCCC]. described in the `SMCCC`_.
### 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 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 initialization and call handler functions. This macro instantiates a ``const struct rt_svc_desc`` for the service with these details (see ``runtime_svc.h``).
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
This structure is allocated in a special ELF section `rt_svc_descs`, enabling
the framework to find all service descriptors included into BL31. 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 The specific service for a SMC Function is selected based on the OEN and call
...@@ -765,10 +801,10 @@ service handler is invoked. ...@@ -765,10 +801,10 @@ service handler is invoked.
Details of the parameters, requirements and behavior of the initialization and Details of the parameters, requirements and behavior of the initialization and
call handling functions are provided in the following sections. 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 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 initialization. This happens prior to initializing a Trusted OS and running
Normal world boot firmware that might in turn use these services. 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 ...@@ -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 not check descriptors for the following error conditions, and may behave in an
unpredictable manner under such scenarios: unpredictable manner under such scenarios:
1. Overlapping OEN ranges #. Overlapping OEN ranges
2. Multiple descriptors for the same range of OENs and `call_type` #. Multiple descriptors for the same range of OENs and ``call_type``
3. Incorrect range of owning entity numbers for a given `call_type` #. Incorrect range of owning entity numbers for a given ``call_type``
Once validated, the service `init()` callback is invoked. This function carries Once validated, the service ``init()`` callback is invoked. This function carries
out any essential EL3 initialization before servicing requests. The `init()` out any essential EL3 initialization before servicing requests. The ``init()``
function is only invoked on the primary CPU during cold boot. If the service 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, 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 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. 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 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 ...@@ -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 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 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 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 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()` 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 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 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 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 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 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. in R0/X0.
Bit[31] (fast/yielding call) and bits[29:24] (owning entity number) of the SMC 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 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 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. 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 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 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 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 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. restoring the stack and CPU state and returning from the original SMC.
Power State Coordination Interface
4. Power State Coordination Interface ----------------------------------
--------------------------------------
TODO: Provide design walkthrough of PSCI implementation. TODO: Provide design walkthrough of PSCI implementation.
The PSCI v1.0 specification categorizes APIs as optional and mandatory. All the 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 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. 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 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 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 platform port as well. The Juno and FVP (all variants) platforms export all the
required support. required support.
| PSCI v1.0 API |Supported| Comments | +-----------------------------+-------------+-------------------------------+
|:----------------------|:--------|:------------------------------------------| | PSCI v1.0 API | Supported | Comments |
|`PSCI_VERSION` | Yes | The version returned is 1.0 | +=============================+=============+===============================+
|`CPU_SUSPEND` | Yes* | | | ``PSCI_VERSION`` | Yes | The version returned is 1.0 |
|`CPU_OFF` | Yes* | | +-----------------------------+-------------+-------------------------------+
|`CPU_ON` | Yes* | | | ``CPU_SUSPEND`` | Yes\* | |
|`AFFINITY_INFO` | Yes | | +-----------------------------+-------------+-------------------------------+
|`MIGRATE` | Yes** | | | ``CPU_OFF`` | Yes\* | |
|`MIGRATE_INFO_TYPE` | Yes** | | +-----------------------------+-------------+-------------------------------+
|`MIGRATE_INFO_CPU` | Yes** | | | ``CPU_ON`` | Yes\* | |
|`SYSTEM_OFF` | Yes* | | +-----------------------------+-------------+-------------------------------+
|`SYSTEM_RESET` | Yes* | | | ``AFFINITY_INFO`` | Yes | |
|`PSCI_FEATURES` | Yes | | +-----------------------------+-------------+-------------------------------+
|`CPU_FREEZE` | No | | | ``MIGRATE`` | Yes\*\* | |
|`CPU_DEFAULT_SUSPEND` | No | | +-----------------------------+-------------+-------------------------------+
|`NODE_HW_STATE` | Yes* | | | ``MIGRATE_INFO_TYPE`` | Yes\*\* | |
|`SYSTEM_SUSPEND` | Yes* | | +-----------------------------+-------------+-------------------------------+
|`PSCI_SET_SUSPEND_MODE`| No | | | ``MIGRATE_INFO_CPU`` | Yes\*\* | |
|`PSCI_STAT_RESIDENCY` | Yes* | | +-----------------------------+-------------+-------------------------------+
|`PSCI_STAT_COUNT` | Yes* | | | ``SYSTEM_OFF`` | Yes\* | |
+-----------------------------+-------------+-------------------------------+
*Note : These PSCI APIs require platform power management hooks to be | ``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. registered with the generic PSCI code to be supported.
**Note : These PSCI APIs require appropriate Secure Payload Dispatcher \*\*Note : These PSCI APIs require appropriate Secure Payload Dispatcher
hooks to be registered with the generic PSCI code to be supported. hooks to be registered with the generic PSCI code to be supported.
The PSCI implementation in ARM Trusted Firmware is a library which can be The PSCI implementation in ARM Trusted Firmware is a library which can be
integrated with AArch64 or AArch32 EL3 Runtime Software for ARMv8-A systems. integrated with AArch64 or AArch32 EL3 Runtime Software for ARMv8-A systems.
A guide to integrating PSCI library with AArch32 EL3 Runtime Software 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, On a production system that includes a Trusted OS running in Secure-EL1/EL0,
the Trusted OS is coupled with a companion runtime service in the BL31 the Trusted OS is coupled with a companion runtime service in the BL31
...@@ -902,43 +955,46 @@ boot flow in ARM Trusted Firmware. The firmware will attempt to locate, load ...@@ -902,43 +955,46 @@ boot flow in ARM Trusted Firmware. The firmware will attempt to locate, load
and execute a BL32 image. and execute a BL32 image.
ARM Trusted Firmware uses a more general term for the BL32 software that runs 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 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 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 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 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 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 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 The TSP runs in Secure-EL1. It is designed to demonstrate synchronous
communication with the normal-world software running in EL1/EL2. Communication communication with the normal-world software running in EL1/EL2. Communication
is initiated by the normal-world software 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 informs the TSPD about the requested power management operation. This allows
the TSP to prepare for or respond to the power state change the TSP to prepare for or respond to the power state change
The TSPD service is responsible for. 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 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 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 the BL32 image. It needs access to the information passed by BL2 to BL31 to do
so. This is provided by: so. This is provided by:
.. code:: c
entry_point_info_t *bl31_plat_get_next_image_ep_info(uint32_t); 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 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. 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 ...@@ -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 initialization of the SPD service. The BL32 initialization function has this
prototype: prototype:
.. code:: c
int32_t init(void); 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 Trusted Firmware supports two approaches for the SPD to pass control to BL32
before returning through EL3 and running the non-trusted firmware (BL33): before returning through EL3 and running the non-trusted firmware (BL33):
1. In the BL32 setup function, use `bl31_set_next_image_type()` to #. In the BL32 setup function, use ``bl31_set_next_image_type()`` to
request that the exit from `bl31_main()` is to the BL32 entrypoint in request that the exit from ``bl31_main()`` is to the BL32 entrypoint in
Secure-EL1. BL31 will exit to BL32 using the asynchronous method by 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 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 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 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 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 ``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 the normal world firmware BL33. On return from the handler the framework
will exit to EL2 and run BL33. will exit to EL2 and run BL33.
2. The BL32 setup function registers an initialization function using #. The BL32 setup function registers an initialization function using
`bl31_register_bl32_init()` which provides a SPD-defined mechanism to ``bl31_register_bl32_init()`` which provides a SPD-defined mechanism to
invoke a 'world-switch synchronous call' to Secure-EL1 to run the BL32 invoke a 'world-switch synchronous call' to Secure-EL1 to run the BL32
entrypoint. entrypoint.
NOTE: The Test SPD service included with the Trusted Firmware provides one NOTE: The Test SPD service included with the Trusted Firmware provides one
...@@ -980,12 +1038,11 @@ before returning through EL3 and running the non-trusted firmware (BL33): ...@@ -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 On completion BL32 returns control to BL31 via a SMC, and on receipt the
SPD service handler invokes the synchronous call return mechanism to return SPD service handler invokes the synchronous call return mechanism to return
to the BL32 initialization function. On return from this function, 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. continue the boot process in the normal world.
#. .. rubric:: Crash Reporting in BL31
6. Crash Reporting in BL31 :name: crash-reporting-in-bl31
----------------------------
BL31 implements a scheme for reporting the processor state when an unhandled BL31 implements a scheme for reporting the processor state when an unhandled
exception is encountered. The reporting mechanism attempts to preserve all the 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. ...@@ -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 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 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. implementation for crash reporting.
The sample crash output is shown below. The sample crash output is shown below.
::
x0 :0x000000004F00007C x0 :0x000000004F00007C
x1 :0x0000000007FFFFFF x1 :0x0000000007FFFFFF
x2 :0x0000000004014D50 x2 :0x0000000004014D50
...@@ -1078,18 +1137,18 @@ The sample crash output is shown below. ...@@ -1078,18 +1137,18 @@ The sample crash output is shown below.
fpexc32_el2 :0x0000000004000700 fpexc32_el2 :0x0000000004000700
sp_el0 :0x0000000004010780 sp_el0 :0x0000000004010780
7. Guidelines for Reset Handlers Guidelines for Reset Handlers
--------------------------------- -----------------------------
Trusted Firmware implements a framework that allows CPU and platform ports to 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 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 both the BL1 and BL31 images. It in turn calls the platform and CPU specific
reset handling functions. reset handling functions.
Details for implementing a CPU specific reset handler can be found in Details for implementing a CPU specific reset handler can be found in
Section 8. Details for implementing a platform specific reset handler can be Section 8. Details for implementing a platform specific reset handler can be
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 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 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 ...@@ -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, already been performed and act as appropriate. Possible courses of actions are,
e.g. skip the action the second time, or undo/redo it. 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, Certain aspects of the ARMv8 architecture are implementation defined,
that is, certain behaviours are not architecturally defined, but must be defined that is, certain behaviours are not architecturally defined, but must be defined
...@@ -1108,28 +1167,28 @@ Firmware implements a framework which categorises the common implementation ...@@ -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 defined behaviours and allows a processor to export its implementation of that
behaviour. The categories are: 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. 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 are turned on, like implementation of errata workarounds, entry into
the intra-cluster coherency domain etc. 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). 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 in the event of a crash, for example Cortex-A53 has registers which
can expose the data cache contents. 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. of all errata workarounds on that processor.
Please note that only 2. is mandated by the TRM. 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 ...@@ -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 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 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 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 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`, ``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 ``reset_func()``, ``cpu_pwr_down_ops`` (array of power down functions) and
`cpu_reg_dump()`. ``cpu_reg_dump()``.
The CPU specific files in `lib/cpus` export a `cpu_ops` data structure with 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` 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 exports the ``cpu_ops`` for Cortex-A53 CPU. According to the platform
configuration, these CPU specific files must be included in the build by configuration, these CPU specific files must be included in the build by
the platform makefile. The generic CPU specific operations framework code exists 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: 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 MMU turned off, both instruction and data caches turned off and not part
of any coherency domain. 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 the platform to perform any system initialization required and any system
errata workarounds that needs to be applied. The `get_cpu_ops_ptr()` reads 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` 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 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 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 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. 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. This function must preserve the values of general purpose registers x20 to x29.
Refer to Section "Guidelines for Reset Handlers" for general guidelines Refer to Section "Guidelines for Reset Handlers" for general guidelines
regarding placement of code in a reset handler. 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` 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 entry is stored in per-CPU data by ``init_cpu_ops()`` so that it can be quickly
retrieved during power down sequences. retrieved during power down sequences.
Various CPU drivers register handlers to perform power down at certain power 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 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 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 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_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_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 requested power level is higher than what a CPU driver supports, the handler
registered for highest level is invoked. 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 ...@@ -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 perform platform specific operations during a power down sequence, for example
turning off CCI coherency during a cluster power down. 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 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 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`` using ``get_cpu_ops_ptr()`` function. The ``cpu_reg_dump()`` in
`cpu_ops` is invoked, which then returns the CPU specific register values to ``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 be reported and a pointer to the ASCII list of register names in a format
expected by the crash reporting framework. expected by the crash reporting framework.
### CPU errata status reporting CPU errata status reporting
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Errata workarounds for CPUs supported in ARM Trusted Firmware are applied during Errata workarounds for CPUs supported in ARM Trusted Firmware are applied during
both cold and warm boots, shortly after reset. Individual Errata workarounds are 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 ...@@ -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 implications; therefore some are enabled by default, others not. Platform ports
shall override build options to enable or disable errata as appropriate. The CPU 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 drivers take care of applying errata workarounds that are enabled and applicable
to a given CPU. Refer to the section titled _CPU Errata Workarounds_ in [CPUBM] to a given CPU. Refer to the section titled *CPU Errata Workarounds* in `CPUBM`_
for more information. for more information.
Functions in CPU drivers that apply errata workaround must follow the Functions in CPU drivers that apply errata workaround must follow the
...@@ -1218,28 +1281,28 @@ conventions listed below. ...@@ -1218,28 +1281,28 @@ conventions listed below.
The errata workaround must be authored as two separate functions: 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 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 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 errata. If the function determines that the errata applies to this CPU, it
must return `ERRATA_APPLIES`; otherwise, it must return must return ``ERRATA_APPLIES``; otherwise, it must return
`ERRATA_NOT_APPLIES`. The utility functions `cpu_get_rev_var` and ``ERRATA_NOT_APPLIES``. The utility functions ``cpu_get_rev_var`` and
`cpu_rev_var_ls` functions may come in handy for this purpose. ``cpu_rev_var_ls`` functions may come in handy for this purpose.
For an errata identified as `E`, the check function must be named For an errata identified as ``E``, the check function must be named
`check_errata_E`. ``check_errata_E``.
This function will be invoked at different times, both from assembly and from 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. 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. check function described above, and applies errata workaround if required.
CPU drivers that apply errata workaround can optionally implement an assembly CPU drivers that apply errata workaround can optionally implement an assembly
function that report the status of errata workarounds pertaining to that CPU. 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 macro, the errata reporting function, if it exists, must be named
`cpux_errata_report`. This function will always be called with MMU enabled; it ``cpux_errata_report``. This function will always be called with MMU enabled; it
must follow AAPCS and may use stack. must follow AAPCS and may use stack.
In a debug build of ARM Trusted Firmware, on a CPU that comes out of reset, both In a debug build of 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 ...@@ -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. 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 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 - The name of the CPU: this must be the same identifier that CPU driver
registered itself with, using `declare_cpu_ops`; 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. errata's check function described above.
The errata status reporting function will be called once per CPU type/errata The errata status reporting function will be called once per CPU type/errata
...@@ -1267,20 +1330,20 @@ status as well. ...@@ -1267,20 +1330,20 @@ status as well.
Reporting the status of errata workaround is for informational purpose only; it Reporting the status of errata workaround is for informational purpose only; it
has no functional significance. has no functional significance.
9. Memory layout of BL images Memory layout of BL images
----------------------------- --------------------------
Each bootloader image can be divided in 2 parts: Each bootloader image can be divided in 2 parts:
* the static contents of the image. These are data actually stored in the - 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` binary on the disk. In the ELF terminology, they are called ``PROGBITS``
sections; 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 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 metadata indicating where these data will be stored at run-time and the
corresponding sections need to be allocated and initialized at run-time. 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, All PROGBITS sections are grouped together at the beginning of the image,
followed by all NOBITS sections. This is true for all Trusted Firmware images followed by all NOBITS sections. This is true for all Trusted Firmware images
...@@ -1290,7 +1353,8 @@ PROGBITS sections then the resulting binary file would contain zero bytes in ...@@ -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 place of this NOBITS section, making the image unnecessarily bigger. Smaller
images allow faster loading from the FIP to the main memory. 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 Each bootloader stage image layout is described by its own linker script. The
linker scripts export some symbols into the program symbol table. Their values linker scripts export some symbols into the program symbol table. Their values
...@@ -1299,38 +1363,36 @@ symbols to figure out the image memory layout. ...@@ -1299,38 +1363,36 @@ symbols to figure out the image memory layout.
Linker symbols follow the following naming convention in the trusted firmware. Linker symbols follow the following naming convention in 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 End address of a given section named ``<SECTION>``. If there is an alignment
constraint on the section's end address then `__<SECTION>_END__` corresponds 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 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. 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. rounding up due to some alignment constraint.
* `__<SECTION>_SIZE__` - ``__<SECTION>_SIZE__``
Size (in bytes) of a given section named `<SECTION>`. If there is an Size (in bytes) of a given section named ``<SECTION>``. If there is an
alignment constraint on the section's end address then `__<SECTION>_SIZE__` 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 corresponds to the size of the section's actual contents, rounded up to the
right boundary. In other words, `__<SECTION>_SIZE__ = __<SECTION>_END__ - right boundary. In other words, ``__<SECTION>_SIZE__ = __<SECTION>_END__ - _<SECTION>_START__``. Refer to the value of ``__<SECTION>_UNALIGNED_SIZE__``
_<SECTION>_START__`. Refer to the value of `__<SECTION>_UNALIGNED_SIZE__`
to know the actual size of the section's contents. 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, rounding up due to some alignment constraint. In other words,
`__<SECTION>_UNALIGNED_SIZE__ = __<SECTION>_UNALIGNED_END__ - ``__<SECTION>_UNALIGNED_SIZE__ = __<SECTION>_UNALIGNED_END__ - __<SECTION>_START__``.
__<SECTION>_START__`.
Some of the linker symbols are mandatory as the trusted firmware code relies on 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 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 ...@@ -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 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. 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: All BL images share the following requirements:
* The BSS section must be zero-initialised before executing any C code. - 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 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 MMU setup code needs to know the extents of the coherent and read-only
memory regions to set the right memory attributes. When 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. read-only memory region is divided between code and data.
The following linker symbols are defined for this purpose: The following linker symbols are defined for this purpose:
* `__BSS_START__` - ``__BSS_START__``
* `__BSS_SIZE__` - ``__BSS_SIZE__``
* `__COHERENT_RAM_START__` Must be aligned on a page-size boundary. - ``__COHERENT_RAM_START__`` Must be aligned on a page-size boundary.
* `__COHERENT_RAM_END__` Must be aligned on a page-size boundary. - ``__COHERENT_RAM_END__`` Must be aligned on a page-size boundary.
* `__COHERENT_RAM_UNALIGNED_SIZE__` - ``__COHERENT_RAM_UNALIGNED_SIZE__``
* `__RO_START__` - ``__RO_START__``
* `__RO_END__` - ``__RO_END__``
* `__TEXT_START__` - ``__TEXT_START__``
* `__TEXT_END__` - ``__TEXT_END__``
* `__RODATA_START__` - ``__RODATA_START__``
* `__RODATA_END__` - ``__RODATA_END__``
#### BL1's linker symbols BL1's linker symbols
^^^^^^^^^^^^^^^^^^^^
BL1 being the ROM image, it has additional requirements. BL1 resides in ROM and 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 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. relocated from ROM to RAM before executing any C code.
The following additional linker symbols are defined for BL1: The following additional linker symbols are defined for BL1:
* `__BL1_ROM_END__` End address of BL1's ROM contents, covering its code - ``__BL1_ROM_END__`` End address of BL1's ROM contents, covering its code
and `.data` section in ROM. and ``.data`` section in ROM.
* `__DATA_ROM_START__` Start address of the `.data` section in ROM. Must be - ``__DATA_ROM_START__`` Start address of the ``.data`` section in ROM. Must be
aligned on a 16-byte boundary. 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. copied over. Must be aligned on a 16-byte boundary.
* `__DATA_SIZE__` Size of the `.data` section (in ROM or RAM). - ``__DATA_SIZE__`` Size of the ``.data`` section (in ROM or RAM).
* `__BL1_RAM_START__` Start address of BL1 read-write data. - ``__BL1_RAM_START__`` Start address of BL1 read-write data.
* `__BL1_RAM_END__` End 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. 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 This means that all bootloader images need to be linked against their ultimate
...@@ -1398,44 +1462,46 @@ layout. ...@@ -1398,44 +1462,46 @@ layout.
The memory layout is completely specific to the platform and so there is no The memory layout is completely specific to the platform and so there is no
general recipe for choosing the right base addresses for each bootloader image. general recipe for choosing the right base addresses for each bootloader image.
However, there are tools to aid in understanding the memory layout. These are 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 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. Among other useful information, they provide the end address of
each image. each image.
* `bl1.map` link map file provides `__BL1_RAM_END__` address. - ``bl1.map`` link map file provides ``__BL1_RAM_END__`` address.
* `bl2.map` link map file provides `__BL2_END__` address. - ``bl2.map`` link map file provides ``__BL2_END__`` address.
* `bl31.map` link map file provides `__BL31_END__` address. - ``bl31.map`` link map file provides ``__BL31_END__`` address.
* `bl32.map` link map file provides `__BL32_END__` address. - ``bl32.map`` link map file provides ``__BL32_END__`` address.
For each bootloader image, the platform code must provide its start 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 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 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: happens, the linker will issue a message similar to the following:
::
aarch64-none-elf-ld: BLx has exceeded its limit. aarch64-none-elf-ld: BLx has exceeded its limit.
Additionally, if the platform memory layout implies some image overlaying like Additionally, if the platform memory layout implies some image overlaying like
on FVP, BL31 and TSP need to know the limit address that their PROGBITS on FVP, BL31 and TSP need to know the limit address that their PROGBITS
sections must not overstep. The platform code must provide those. sections must not overstep. The platform code must provide those.
When LOAD_IMAGE_V2 is disabled, Trusted Firmware provides a mechanism to When LOAD\_IMAGE\_V2 is disabled, Trusted Firmware provides a mechanism to
verify at boot time that the memory to load a new image is free to prevent 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 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 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 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: by calling the corresponding platform API:
* `meminfo_t *bl1_plat_sec_mem_layout(void)` - ``meminfo_t *bl1_plat_sec_mem_layout(void)``
* `meminfo_t *bl2_plat_sec_mem_layout(void)` - ``meminfo_t *bl2_plat_sec_mem_layout(void)``
* `void bl2_plat_get_scp_bl2_meminfo(meminfo_t *scp_bl2_meminfo)` - ``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_bl32_meminfo(meminfo_t *bl32_meminfo)``
* `void bl2_plat_get_bl33_meminfo(meminfo_t *bl33_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 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. within the specified region and marked as free.
The actual number of regions and their base addresses and sizes is platform The actual number of regions and their base addresses and sizes is platform
...@@ -1461,6 +1527,8 @@ unexpected memory layout. ...@@ -1461,6 +1527,8 @@ unexpected memory layout.
The following diagram is an example of an image loaded in the bottom part of 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): the memory region. The region is initially free (nothing has been loaded yet):
::
Memory region Memory region
+----------+ +----------+
| | | |
...@@ -1474,6 +1542,8 @@ the memory region. The region is initially free (nothing has been loaded yet): ...@@ -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: And the following diagram is an example of an image loaded in the top part:
::
Memory region Memory region
+----------+ +----------+
| xxxxxxxx | <<<<<<<<<<<<< Marked as unavailable | xxxxxxxx | <<<<<<<<<<<<< Marked as unavailable
...@@ -1485,23 +1555,23 @@ And the following diagram is an example of an image loaded in the top part: ...@@ -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 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 overwriting a previously loaded image. The platform must specify the memory
available in the system for all the relevant BL images to be loaded. 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 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 base and maximum image size provided by the platforms. Platforms must take
this behaviour into account when defining the base/size for each of the images. this behaviour into account when defining the base/size for each of the images.
#### Memory layout on ARM development platforms Memory layout on ARM development platforms
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following list describes the memory layout on the ARM development platforms: The following list describes the memory layout on the ARM development platforms:
* A 4KB page of shared memory is used for communication between Trusted - A 4KB page of shared memory is used for communication between Trusted
Firmware and the platform's power controller. This is located at the base of Firmware and the platform's power controller. This is located at the base of
Trusted SRAM. The amount of Trusted SRAM available to load the bootloader Trusted SRAM. The amount of Trusted SRAM available to load the bootloader
images is reduced by the size of the shared memory. 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: ...@@ -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 this is also used for the MHU payload when passing messages to and from the
SCP. SCP.
* On FVP, BL1 is originally sitting in the Trusted ROM at address `0x0`. On - 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 Juno, BL1 resides in flash memory at address ``0x0BEC0000``. BL1 read-write
data are relocated to the top of Trusted SRAM at runtime. 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 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 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 only until execution reaches the EL3 Runtime Software entry point during a
cold boot. 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 region and transfered to the SCP before being overwritten by EL3 Runtime
Software. 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 SRAM
* Trusted DRAM (FVP only) - Trusted DRAM (FVP only)
* Secure region of DRAM (top 16MB of DRAM configured by the TrustZone - Secure region of DRAM (top 16MB of DRAM configured by the TrustZone
controller) controller)
When BL32 (for AArch64) is loaded into Trusted SRAM, its NOBITS sections 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 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. 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): 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 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 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 mark the BL1(rw) section within this region as occupied. The BL1(rw) section
is placed at the top of Trusted SRAM. 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 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 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. 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 This region is an exact copy of the region defined by
`bl2_plat_sec_mem_layout()`. Being a disconnected copy means that all the ``bl2_plat_sec_mem_layout()``. Being a disconnected copy means that all the
changes made to this region by the Trusted Firmware will not be propagated. changes made to this region by the Trusted Firmware will not be propagated.
This approach is valid because the SCP BL2 image is loaded temporarily 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 while it is being transferred to the SCP, so this memory is reused
afterwards. afterwards.
* `void bl2_plat_get_bl32_meminfo(meminfo_t *bl32_meminfo)` - ``void bl2_plat_get_bl32_meminfo(meminfo_t *bl32_meminfo)``
This region depends on the location of the BL32 image. Currently, ARM This region depends on the location of the BL32 image. Currently, ARM
platforms support three different locations (detailed below): Trusted SRAM, platforms support three different locations (detailed below): Trusted SRAM,
Trusted DRAM and the TZC-Secured DRAM. Trusted DRAM and the TZC-Secured DRAM.
* `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 This region corresponds to the Non-Secure DDR-DRAM, excluding the
TZC-Secured area. TZC-Secured area.
...@@ -1585,6 +1655,8 @@ layout of the other images in Trusted SRAM. ...@@ -1585,6 +1655,8 @@ layout of the other images in Trusted SRAM.
**FVP with TSP in Trusted SRAM (default option):** **FVP with TSP in Trusted SRAM (default option):**
(These diagrams only cover the AArch64 case) (These diagrams only cover the AArch64 case)
::
Trusted SRAM Trusted SRAM
0x04040000 +----------+ loaded by BL2 ------------------ 0x04040000 +----------+ loaded by BL2 ------------------
| BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS | | BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS |
...@@ -1603,9 +1675,10 @@ layout of the other images in Trusted SRAM. ...@@ -1603,9 +1675,10 @@ layout of the other images in Trusted SRAM.
| BL1 (ro) | | BL1 (ro) |
0x00000000 +----------+ 0x00000000 +----------+
**FVP with TSP in Trusted DRAM:** **FVP with TSP in Trusted DRAM:**
::
Trusted DRAM Trusted DRAM
0x08000000 +----------+ 0x08000000 +----------+
| BL32 | | BL32 |
...@@ -1631,6 +1704,8 @@ layout of the other images in Trusted SRAM. ...@@ -1631,6 +1704,8 @@ layout of the other images in Trusted SRAM.
**FVP with TSP in TZC-Secured DRAM:** **FVP with TSP in TZC-Secured DRAM:**
::
DRAM DRAM
0xffffffff +----------+ 0xffffffff +----------+
| BL32 | (secure) | BL32 | (secure)
...@@ -1658,9 +1733,10 @@ layout of the other images in Trusted SRAM. ...@@ -1658,9 +1733,10 @@ layout of the other images in Trusted SRAM.
| BL1 (ro) | | BL1 (ro) |
0x00000000 +----------+ 0x00000000 +----------+
**Juno with BL32 in Trusted SRAM (default option):** **Juno with BL32 in Trusted SRAM (default option):**
::
Flash0 Flash0
0x0C000000 +----------+ 0x0C000000 +----------+
: : : :
...@@ -1683,9 +1759,10 @@ layout of the other images in Trusted SRAM. ...@@ -1683,9 +1759,10 @@ layout of the other images in Trusted SRAM.
| MHU | | MHU |
0x04000000 +----------+ 0x04000000 +----------+
**Juno with BL32 in TZC-secured DRAM:** **Juno with BL32 in TZC-secured DRAM:**
::
DRAM DRAM
0xFFE00000 +----------+ 0xFFE00000 +----------+
| BL32 | (secure) | BL32 | (secure)
...@@ -1717,9 +1794,8 @@ layout of the other images in Trusted SRAM. ...@@ -1717,9 +1794,8 @@ layout of the other images in Trusted SRAM.
| MHU | | MHU |
0x04000000 +----------+ 0x04000000 +----------+
Firmware Image Package (FIP)
10. Firmware Image Package (FIP) ----------------------------
---------------------------------
Using a Firmware Image Package (FIP) allows for packing bootloader images (and Using a Firmware Image Package (FIP) allows for packing bootloader images (and
potentially other payloads) into a single archive that can be loaded by the ARM potentially other payloads) into a single archive that can be loaded by the ARM
...@@ -1728,7 +1804,8 @@ from a FIP has been added to the storage layer and allows a package to be read ...@@ -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 from supported platform storage. A tool to create Firmware Image Packages is
also provided and described below. 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 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 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 ...@@ -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 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. provided in the ToC entry the corresponding payload data can be retrieved.
::
------------------ ------------------
| ToC Header | | ToC Header |
|----------------| |----------------|
...@@ -1755,11 +1834,13 @@ provided in the ToC entry the corresponding payload data can be retrieved. ...@@ -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 The ToC header and entry formats are described in the header file
`include/tools_share/firmware_image_package.h`. This file is used by both the ``include/tools_share/firmware_image_package.h``. This file is used by both the
tool and the ARM Trusted firmware. tool and the ARM Trusted firmware.
The ToC header has the following fields: The ToC header has the following fields:
::
`name`: The name of the ToC. This is currently used to validate the header. `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 `serial_number`: A non-zero number provided by the creation tool
`flags`: Flags associated with this data. `flags`: Flags associated with this data.
...@@ -1769,6 +1850,8 @@ The ToC header has the following fields: ...@@ -1769,6 +1850,8 @@ The ToC header has the following fields:
A ToC entry has the following fields: A ToC entry has the following fields:
::
`uuid`: All files are referred to by a pre-defined Universally Unique `uuid`: All files are referred to by a pre-defined Universally Unique
IDentifier [UUID] . The UUIDs are defined in IDentifier [UUID] . The UUIDs are defined in
`include/tools_share/firmware_image_package.h`. The platform translates `include/tools_share/firmware_image_package.h`. The platform translates
...@@ -1779,36 +1862,37 @@ A ToC entry has the following fields: ...@@ -1779,36 +1862,37 @@ A ToC entry has the following fields:
`size`: The size of the corresponding payload data in bytes. `size`: The size of the corresponding payload data in bytes.
`flags`: Flags associated with this entry. Non are yet defined. `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 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 that can be loaded by the ARM Trusted Firmware from platform storage. The tool
currently only supports packing bootloader images. Additional image definitions currently only supports packing bootloader images. Additional image definitions
can be added to the tool as required. 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 The Firmware Image Package (FIP) driver can load images from a binary package on
non-volatile platform storage. For the ARM development platforms, this is non-volatile platform storage. For the ARM development platforms, this is
currently NOR FLASH. currently NOR FLASH.
Bootloader images are loaded according to the platform policy as specified by Bootloader images are loaded according to the platform policy as specified by
the function `plat_get_image_source()`. For the ARM development platforms, this the function ``plat_get_image_source()``. For the ARM development platforms, this
means the platform will attempt to load images from a Firmware Image Package means the platform will attempt to load images from a Firmware Image Package
located at the start of NOR FLASH0. located at the start of NOR FLASH0.
The ARM development platforms' policy is to only allow loading of a known set of The ARM development platforms' policy is to only allow loading of a known set of
images. The platform policy can be modified to allow additional images. images. The platform policy can be modified to allow additional images.
Use of coherent memory in Trusted Firmware
11. Use of coherent memory in Trusted Firmware ------------------------------------------
-----------------------------------------------
There might be loss of coherency when physical memory with mismatched There might be loss of coherency when physical memory with mismatched
shareability, cacheability and memory attributes is accessed by multiple CPUs shareability, cacheability and memory attributes is accessed by multiple CPUs
(refer to section B2.9 of [ARM ARM] for more details). This possibility occurs (refer to section B2.9 of `ARM ARM`_ for more details). This possibility occurs
in Trusted Firmware during power up/down sequences when coherency, MMU and in Trusted Firmware during power up/down sequences when coherency, MMU and
caches are turned on/off incrementally. caches are turned on/off incrementally.
...@@ -1819,7 +1903,7 @@ memory region. ...@@ -1819,7 +1903,7 @@ memory region.
By default, all data structures which are susceptible to accesses with By default, all data structures which are susceptible to accesses with
mismatched attributes from various CPUs are allocated in a coherent memory mismatched attributes from various CPUs are allocated in a coherent memory
region (refer to section 2.1 of [Porting Guide]). The coherent memory region region (refer to section 2.1 of `Porting Guide`_). The coherent memory region
accesses are Outer Shareable, non-cacheable and they can be accessed accesses are Outer Shareable, non-cacheable and they can be accessed
with the Device nGnRE attributes when the MMU is turned on. Hence, at the with the Device nGnRE attributes when the MMU is turned on. Hence, at the
expense of at least an extra page of memory, Trusted Firmware is able to work expense of at least an extra page of memory, Trusted Firmware is able to work
...@@ -1831,25 +1915,29 @@ approach requires the data structures to be designed so that it is possible to ...@@ -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 work around the issue of mismatched memory attributes by performing software
cache maintenance on them. cache maintenance on them.
### Disabling the use of coherent memory in Trusted Firmware Disabling the use of coherent memory in Trusted Firmware
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It might be desirable to avoid the cost of allocating coherent memory on It might be desirable to avoid the cost of allocating coherent memory on
platforms which are memory constrained. Trusted Firmware enables inclusion of platforms which are memory constrained. 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 This flag is enabled by default. It can be disabled to choose the second
approach described above. approach described above.
The below sections analyze the data structures allocated in the coherent memory The below sections analyze the data structures allocated in the coherent memory
region and the changes required to allocate them in normal 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 tree information for state management of power domains. By default, this data
structure is allocated in the coherent memory region in the Trusted Firmware structure is allocated in the coherent memory region in the Trusted Firmware
because it can be accessed by multple CPUs, either with caches enabled or because it can be accessed by multple CPUs, either with caches enabled or
disabled. disabled.
.. code:: c
typedef struct non_cpu_pwr_domain_node { typedef struct non_cpu_pwr_domain_node {
/* /*
* Index of the first CPU power domain node level 0 which has this node * Index of the first CPU power domain node level 0 which has this node
...@@ -1879,22 +1967,25 @@ disabled. ...@@ -1879,22 +1967,25 @@ disabled.
} non_cpu_pd_node_t; } non_cpu_pd_node_t;
In order to move this data structure to normal memory, the use of each of its 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` 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 ``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 them from coherent memory involves only doing a clean and invalidate of the
cache lines after these fields are written. cache lines after these fields are written.
The field `local_state` can be concurrently accessed by multiple CPUs in 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 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 mutual exlusion to this field and a clean and invalidate is needed after it
is written. is written.
### Bakery lock data Bakery lock data
~~~~~~~~~~~~~~~~
The bakery lock data structure `bakery_lock_t` is allocated in coherent memory 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 and is accessed by multiple CPUs with mismatched attributes. ``bakery_lock_t`` is
defined as follows: defined as follows:
.. code:: c
typedef struct bakery_lock { typedef struct bakery_lock {
/* /*
* The lock_data is a bit-field of 2 members: * 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 ...@@ -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. 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 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 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 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 lock implementation, they do not have access to any other locking primitive to
...@@ -1919,23 +2010,25 @@ the following example. ...@@ -1919,23 +2010,25 @@ the following example.
CPU0 updates its per-CPU field with data cache enabled. This write updates a 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 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 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 its field in any other cache line in the system. This operation will invalidate
the update made by CPU0 as well. 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 has been redesigned. The changes utilise the characteristic of Lamport's Bakery
algorithm mentioned earlier. The bakery_lock structure only allocates the memory 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 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 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 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 and multiplying it with (PLATFORM\_CORE\_COUNT - 1). This enables software to
perform software cache maintenance on the lock data structure without running perform software cache maintenance on the lock data structure without running
into coherency issues associated with mismatched attributes. into coherency issues associated with mismatched attributes.
The bakery lock data structure `bakery_info_t` is defined for use when The bakery lock data structure ``bakery_info_t`` is defined for use when
`USE_COHERENT_MEM` is disabled as follows: ``USE_COHERENT_MEM`` is disabled as follows:
.. code:: c
typedef struct bakery_info { typedef struct bakery_info {
/* /*
...@@ -1947,11 +2040,13 @@ The bakery lock data structure `bakery_info_t` is defined for use when ...@@ -1947,11 +2040,13 @@ The bakery lock data structure `bakery_info_t` is defined for use when
volatile uint16_t lock_data; volatile uint16_t lock_data;
} bakery_info_t; } bakery_info_t;
The `bakery_info_t` represents a single per-CPU field of one lock and 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 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 system represents the complete bakery lock. The view in memory for a system
with n bakery locks are: with n bakery locks are:
::
bakery_lock section start bakery_lock section start
|----------------| |----------------|
| `bakery_info_t`| <-- Lock_0 per-CPU field | `bakery_info_t`| <-- Lock_0 per-CPU field
...@@ -1988,15 +2083,15 @@ with n bakery locks are: ...@@ -1988,15 +2083,15 @@ with n bakery locks are:
------------------ ------------------
Consider a system of 2 CPUs with 'N' bakery locks as shown above. For an 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 operation on Lock\_N, the corresponding ``bakery_info_t`` in both CPU0 and CPU1
`bakery_lock` section need to be fetched and appropriate cache operations need ``bakery_lock`` section need to be fetched and appropriate cache operations need
to be performed for each access. to be performed for each access.
On ARM Platforms, bakery locks are used in psci (`psci_locks`) and power controller On ARM Platforms, bakery locks are used in psci (``psci_locks``) and power controller
driver (`arm_lock`). driver (``arm_lock``).
Non Functional Impact of removing coherent memory
### Non Functional Impact of removing coherent memory ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Removal of the coherent memory region leads to the additional software overhead Removal of the coherent memory region leads to the additional software overhead
of performing cache maintenance for the affected data structures. However, since 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 ...@@ -2004,8 +2099,9 @@ the memory where the data structures are allocated is cacheable, the overhead is
mostly mitigated by an increase in performance. mostly mitigated by an increase in performance.
There is however a performance impact for bakery locks, due to: 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. for each CPU are distributed across different cache lines.
The implementation has been optimized to minimize this additional overhead. 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 ...@@ -2015,15 +2111,14 @@ in Device memory the same is 2 micro seconds. The measurements were done on the
Juno ARM development platform. Juno ARM development platform.
As mentioned earlier, almost a page of memory can be saved by disabling As mentioned earlier, almost a page of memory can be saved by disabling
`USE_COHERENT_MEM`. Each platform needs to consider these trade-offs to decide ``USE_COHERENT_MEM``. Each platform needs to consider these trade-offs to decide
whether coherent memory should be used. If a platform disables 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 ``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 optionally define macro ``PLAT_PERCPU_BAKERY_LOCK_SIZE`` (see the
Guide]). Refer to the reference platform code for examples. `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 In the ARMv8 VMSA, translation table entries include fields that define the
properties of the target memory region, such as its access permissions. The properties of the target memory region, such as its access permissions. The
...@@ -2033,6 +2128,8 @@ memory regions then it needs to map them using different memory pages. ...@@ -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: The default memory layout for each BL image is as follows:
::
| ... | | ... |
+-------------------+ +-------------------+
| Read-write data | | Read-write data |
...@@ -2063,7 +2160,7 @@ means that the read-only data stored on the same memory page as the code are ...@@ -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 executable as well. This could potentially be exploited as part of a security
attack. 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 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, 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 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 ...@@ -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 limit the memory cost, this flag also changes the memory layout such that the
code and exception vectors are now contiguous, like so: code and exception vectors are now contiguous, like so:
::
| ... | | ... |
+-------------------+ +-------------------+
| Read-write data | | Read-write data |
...@@ -2099,9 +2198,8 @@ should consider the trade-off between memory footprint and security. ...@@ -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 This build flag is disabled by default, minimising memory footprint. On ARM
platforms, it is enabled. platforms, it is enabled.
Performance Measurement Framework
13. Performance Measurement Framework ---------------------------------
--------------------------------------
The Performance Measurement Framework (PMF) facilitates collection of The Performance Measurement Framework (PMF) facilitates collection of
timestamps by registered services and provides interfaces to retrieve timestamps by registered services and provides interfaces to retrieve
...@@ -2109,79 +2207,89 @@ them from within the ARM Trusted Firmware. A platform can choose to ...@@ -2109,79 +2207,89 @@ them from within the ARM Trusted Firmware. A platform can choose to
expose appropriate SMCs to retrieve these collected timestamps. expose appropriate SMCs to retrieve these collected timestamps.
By default, the global physical counter is used for the timestamp By default, the global physical counter is used for the timestamp
value and is read via `CNTPCT_EL0`. The framework allows to retrieve value and is read via ``CNTPCT_EL0``. The framework allows to retrieve
timestamps captured by other CPUs. timestamps captured by other CPUs.
### Timestamp identifier format Timestamp identifier format
~~~~~~~~~~~~~~~~~~~~~~~~~~~
A PMF timestamp is uniquely identified across the system via the 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 0-7: The local timestamp identifier.
Bits 8-9: Reserved. Bits 8-9: Reserved.
Bits 10-15: The service identifier. Bits 10-15: The service identifier.
Bits 16-31: Reserved. 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 service name and a service identifier. Both the service name and
identifier are unique within the system as a whole. 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. 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, 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 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_STORE_ENABLE: The timestamp is stored in memory for later retrieval.
PMF_DUMP_ENABLE: The timestamp is dumped on the serial console. 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. timestamps in a PMF specific linker section at build time.
Additionally, it defines necessary functions to capture and Additionally, it defines necessary functions to capture and
retrieve a particular timestamp for the given service at runtime. retrieve a particular timestamp for the given service at runtime.
The macro `PMF_REGISTER_SERVICE()` only enables capturing PMF The macro ``PMF_REGISTER_SERVICE()`` only enables capturing PMF
timestamps from within ARM Trusted Firmware. In order to retrieve timestamps from within ARM Trusted Firmware. In order to retrieve
timestamps from outside of ARM Trusted Firmware, the timestamps from outside of ARM Trusted Firmware, the
`PMF_REGISTER_SERVICE_SMC()` macro must be used instead. This macro ``PMF_REGISTER_SERVICE_SMC()`` macro must be used instead. This macro
accepts the same set of arguments as the `PMF_REGISTER_SERVICE()` accepts the same set of arguments as the ``PMF_REGISTER_SERVICE()``
macro but additionally supports retrieving timestamps using SMCs. macro but additionally supports retrieving timestamps using SMCs.
### Capturing a timestamp Capturing a timestamp
~~~~~~~~~~~~~~~~~~~~~
PMF timestamps are stored in a per-service timestamp region. On a PMF timestamps are stored in a per-service timestamp region. On a
system with multiple CPUs, each timestamp is captured and stored system with multiple CPUs, each timestamp is captured and stored
in a per-CPU cache line aligned memory region. 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 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. 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 instructs PMF to do cache maintenance following the capture. Cache
maintenance is required if any of the service's timestamps are captured maintenance is required if any of the service's timestamps are captured
with data cache disabled. with data cache disabled.
To capture a timestamp in assembly code, the caller should use 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 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. and store it at the determined address for later retrieval.
### Retrieving a timestamp Retrieving a timestamp
~~~~~~~~~~~~~~~~~~~~~~
From within ARM Trusted Firmware, timestamps for individual CPUs can From within ARM Trusted Firmware, timestamps for individual CPUs can
be retrieved using either `PMF_GET_TIMESTAMP_BY_MPIDR()` or be retrieved using either ``PMF_GET_TIMESTAMP_BY_MPIDR()`` or
`PMF_GET_TIMESTAMP_BY_INDEX()` macros. These macros accept the CPU's MPIDR ``PMF_GET_TIMESTAMP_BY_INDEX()`` macros. These macros accept the CPU's MPIDR
value, or its ordinal position, respectively. value, or its ordinal position, respectively.
From outside ARM Trusted Firmware, timestamps for individual CPUs can be 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() Interface : pmf_smc_handler()
Argument : unsigned int smc_fid, u_register_t x1, Argument : unsigned int smc_fid, u_register_t x1,
...@@ -2203,77 +2311,80 @@ retrieved by calling into `pmf_smc_handler()`. ...@@ -2203,77 +2311,80 @@ retrieved by calling into `pmf_smc_handler()`.
cache invalidate before reading the timestamp. This ensures cache invalidate before reading the timestamp. This ensures
an updated copy is returned. 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. 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. 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. 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``.
#. .. rubric:: ARMv8 Architecture Extensions
14. ARMv8 Architecture Extensions :name: armv8-architecture-extensions
----------------------------------
ARM Trusted Firmware makes use of ARMv8 Architecture Extensions where ARM Trusted Firmware makes use of ARMv8 Architecture Extensions where
applicable. This section lists the usage of Architecture Extensions, and build applicable. This section lists the usage of Architecture Extensions, and build
flags controlling them. flags controlling them.
In general, and unless individually mentioned, the build options In general, and unless individually mentioned, the build options
`ARM_ARCH_MAJOR` and `ARM_ARCH_MINOR` selects the Architecture Extension to ``ARM_ARCH_MAJOR`` and ``ARM_ARCH_MINOR`` selects the Architecture Extension to
target when building ARM Trusted Firmware. Subsequent ARM Architecture target when building ARM Trusted Firmware. Subsequent ARM Architecture
Extensions are backward compatible with previous versions. 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 valid numeric value. These build options only control whether or not
Architecture Extension-specific code is included in the build. Otherwise, ARM Architecture Extension-specific code is included in the build. Otherwise, ARM
Trusted Firmware targets the base ARMv8.0 architecture; i.e. as if 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. default values.
See also the _Summary of build options_ in [User Guide]. See also the *Summary of build options* in `User Guide`_.
For details on the Architecture Extension and available features, please refer For details on the Architecture Extension and available features, please refer
to the respective Architecture Extension Supplement. to the respective Architecture Extension Supplement.
### ARMv8.1 ARMv8.1
~~~~~~~
This Architecture Extension is targeted when `ARM_ARCH_MAJOR` >= 8, or when This Architecture Extension is targeted when ``ARM_ARCH_MAJOR`` >= 8, or when
`ARM_ARCH_MAJOR` == 8 and `ARM_ARCH_MINOR` >= 1. ``ARM_ARCH_MAJOR`` == 8 and ``ARM_ARCH_MINOR`` >= 1.
* The Compare and Swap instruction is used to implement spinlocks. Otherwise, - The Compare and Swap instruction is used to implement spinlocks. Otherwise,
the load-/store-exclusive instruction pair is used. the load-/store-exclusive instruction pair is used.
15. Code Structure Code Structure
------------------- --------------
Trusted Firmware code is logically divided between the three boot loader Trusted Firmware code is logically divided between the three boot loader
stages mentioned in the previous sections. The code is also divided into the stages mentioned in the previous sections. The code is also divided into the
following categories (present as directories in the source code): 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. the platform.
* **Common code.** This is platform and architecture agnostic code. - **Common code.** This is platform and architecture agnostic code.
* **Library code.** This code comprises of functionality commonly used by all - **Library code.** This code comprises of functionality commonly used by all
other code. The PSCI implementation and other EL3 runtime frameworks reside other code. The PSCI implementation and other EL3 runtime frameworks reside
as Library components. as Library components.
* **Stage specific.** Code specific to a boot stage. - **Stage specific.** Code specific to a boot stage.
* **Drivers.** - **Drivers.**
* **Services.** EL3 runtime services (eg: SPD). Specific SPD services - **Services.** EL3 runtime services (eg: SPD). Specific SPD services
reside in the `services/spd` directory (e.g. `services/spd/tspd`). 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 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: categories. Based upon the above, the code layout looks like this:
::
Directory Used by BL1? Used by BL2? Used by BL31? Directory Used by BL1? Used by BL2? Used by BL31?
bl1 Yes No No bl1 Yes No No
bl2 No Yes No bl2 No Yes No
...@@ -2284,43 +2395,46 @@ categories. Based upon the above, the code layout looks like this: ...@@ -2284,43 +2395,46 @@ categories. Based upon the above, the code layout looks like this:
lib Yes Yes Yes lib Yes Yes Yes
services No No Yes services No No Yes
The build system provides a non configurable build option IMAGE_BLx for each The build system provides a non configurable build option IMAGE\_BLx for each
boot loader stage (where x = BL stage). e.g. for BL1 , IMAGE_BL1 will be boot loader stage (where x = BL stage). e.g. for BL1 , IMAGE\_BL1 will be
defined by the build system. This enables the Trusted Firmware to compile defined by the build system. This enables the Trusted Firmware to compile
certain code only for specific boot loader stages certain code only for specific boot loader stages
All assembler files have the `.S` extension. The linker source files for each All assembler files have the ``.S`` extension. The linker source files for each
boot stage have the extension `.ld.S`. These are processed by GCC to create the boot stage have the extension ``.ld.S``. These are processed by GCC to create the
linker scripts which have the extension `.ld`. linker scripts which have the extension ``.ld``.
FDTs provide a description of the hardware platform and are used by the Linux FDTs provide a description of the hardware platform and are used by the Linux
kernel at boot time. These can be found in the `fdts` directory. kernel at boot time. These can be found in the ``fdts`` directory.
References
----------
16. References .. [#] Trusted Board Boot Requirements CLIENT PDD (ARM DEN 0006B-5). Available
---------------
1. Trusted Board Boot Requirements CLIENT PDD (ARM DEN 0006B-5). Available
under NDA through your ARM account representative. under NDA through your ARM account representative.
.. [#] `Power State Coordination Interface PDD`_
2. [Power State Coordination Interface PDD (ARM DEN 0022B.b)][PSCI]. .. [#] `SMC Calling Convention PDD`_
.. [#] `ARM Trusted Firmware Interrupt Management Design guide`_.
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.*
- - - - - - - - - - - - - - - - - - - - - - - - - -
.. _Reset Design: ./reset-design.rst
_Copyright (c) 2013-2016, ARM Limited and Contributors. All rights reserved._ .. _Porting Guide: ./porting-guide.rst
.. _Firmware Update: ./firmware-update.rst
[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 PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
[PSCI]: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf "Power State Coordination Interface PDD (ARM DEN 0022C)" .. _SMC calling convention PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
[SMCCC]: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html "SMC Calling Convention PDD (ARM DEN 0028A)" .. _PSCI Library integration guide: ./psci-lib-integration-guide.rst
[UUID]: https://tools.ietf.org/rfc/rfc4122.txt "A Universally Unique IDentifier (UUID) URN Namespace" .. _SMCCC: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
[User Guide]: ./user-guide.md .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
[Porting Guide]: ./porting-guide.md .. _Power State Coordination Interface PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
[Reset Design]: ./reset-design.md .. _here: ./psci-lib-integration-guide.rst
[INTRG]: ./interrupt-framework-design.md .. _cpu-specific-build-macros.rst: ./cpu-specific-build-macros.rst
[CPUBM]: ./cpu-specific-build-macros.md .. _CPUBM: ./cpu-specific-build-macros.rst
[Firmware Update]: ./firmware-update.md .. _ARM ARM: http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0487a.e/index.html
[PSCI Lib guide]: ./psci-lib-integration-guide.md .. _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 ARM Trusted Firmware - Firmware Update Design Guide
=================================================== ===================================================
Contents :
1. [Introduction](#1--introduction) .. section-numbering::
2. [FWU Overview](#2--fwu-overview) :suffix: .
3. [Image Identification](#3--image-identification)
4. [FWU State Machine](#4--fwu-state-machine)
5. [BL1 SMC Interface](#5--bl1-smc-interface)
- - - - - - - - - - - - - - - - - - .. contents::
1. Introduction --------------
----------------
Introduction
------------
This document describes the design of the Firmware Update (FWU) feature, which This document describes the design of the Firmware Update (FWU) feature, which
enables authenticated firmware to update firmware images from external enables authenticated firmware to update firmware images from external
...@@ -24,19 +22,19 @@ be complemented by other, higher level firmware update software. ...@@ -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) FWU implements a specific part of the Trusted Board Boot Requirements (TBBR)
specification, ARM DEN0006C-1. It should be used in conjunction with the specification, ARM DEN0006C-1. It should be used in conjunction with the
[Trusted Board Boot] design document, which describes the image authentication `Trusted Board Boot`_ design document, which describes the image authentication
parts of the Trusted Firmware (TF) TBBR implementation. parts of the Trusted Firmware (TF) TBBR implementation.
### Scope Scope
~~~~~
This document describes the secure world FWU design. It is beyond its scope to 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 describe how normal world FWU images should operate. To implement normal world
FWU images, please refer to the "Non-Trusted Firmware Updater" requirements in FWU images, please refer to the "Non-Trusted Firmware Updater" requirements in
the TBBR. the TBBR.
FWU Overview
2. FWU Overview ------------
----------------
The FWU boot flow is primarily mediated by BL1. Since BL1 executes in ROM, and 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 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. ...@@ -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 Platform code may choose which parts are implemented in which images but the
general expectation is: general expectation is:
* BL1 handles: - BL1 handles:
* Detection and initiation of the FWU boot flow.
* Copying images from non-secure to secure memory - Detection and initiation of the FWU boot flow.
* FWU image authentication - Copying images from non-secure to secure memory
* Context switching between the normal and secure world during the FWU - FWU image authentication
- Context switching between the normal and secure world during the FWU
process. process.
* Other secure world FWU images handle platform initialization required by
- Other secure world FWU images handle platform initialization required by
the FWU process. 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. interfaces to non-secure memory.
The primary requirements of the FWU feature are: 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. 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 it needs, and to enable platform specific FWU functionality. See the
[Porting Guide] for details of this interface. `Porting Guide`_ for details of this interface.
TF uses abbreviated image terminology for FWU images like for other TF images. TF 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. The following diagram shows the FWU boot flow for ARM development platforms.
ARM CSS platforms like Juno have a System Control Processor (SCP), and these ARM CSS platforms like Juno have a System Control Processor (SCP), and these
use all defined FWU images. Other platforms may use a subset of these. use all defined FWU images. Other platforms may use a subset of these.
![Flow Diagram](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 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 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 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] Chain of Trust (Refer to the `Authentication Framework Design`_
for more information). for more information).
The image descriptor includes the following 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 is permitted to request execution of a secure world FWU image (after
authentication). Secure world certificates and non-AP images are examples authentication). Secure world certificates and non-AP images are examples
of non-executable images. 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. authenticated/executed in secure or non-secure memory.
* Image base address and size. - Image base address and size.
* Image entry point configuration (an `entry_point_info_t`). - Image entry point configuration (an ``entry_point_info_t``).
* FWU image state. - FWU image state.
BL1 uses the FWU image descriptors to: BL1 uses the FWU image descriptors to:
* Validate the arguments of FWU SMCs - Validate the arguments of FWU SMCs
* Manage the state of the FWU process - Manage the state of the FWU process
* Initialize the execution state of the next FWU image. - Initialize the execution state of the next FWU image.
FWU State Machine
4. FWU State Machine -----------------
---------------------
BL1 maintains state for each FWU image during FWU execution. FWU images at lower 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 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 ...@@ -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 transitions are shown in the diagram below. Note that secure images have a more
complex state machine than non-secure images. 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: 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 Authentication failure also leads to this state. A secure
image may yield to this state if it has completed execution. 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. 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. 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. 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. 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. requested BL1 to resume normal world execution.
BL1 SMC Interface
-----------------
5. BL1 SMC Interface BL1\_SMC\_CALL\_COUNT
--------------------- ~~~~~~~~~~~~~~~~~~~~~
### BL1_SMC_CALL_COUNT ::
Arguments: Arguments:
uint32_t function ID : 0x0 uint32_t function ID : 0x0
...@@ -148,7 +148,10 @@ The following is a brief description of the supported states: ...@@ -148,7 +148,10 @@ The following is a brief description of the supported states:
This SMC returns the number of SMCs supported by BL1. This SMC returns the number of SMCs supported by BL1.
### BL1_SMC_UID BL1\_SMC\_UID
~~~~~~~~~~~~~
::
Arguments: Arguments:
uint32_t function ID : 0x1 uint32_t function ID : 0x1
...@@ -156,10 +159,13 @@ This SMC returns the number of SMCs supported by BL1. ...@@ -156,10 +159,13 @@ This SMC returns the number of SMCs supported by BL1.
Return: Return:
UUID : 32 bits in each of w0-w3 (or r0-r3 for AArch32 callers) 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 service.
### BL1_SMC_VERSION BL1\_SMC\_VERSION
~~~~~~~~~~~~~~~~~
::
Argument: Argument:
uint32_t function ID : 0x3 uint32_t function ID : 0x3
...@@ -170,7 +176,10 @@ BL1 SMC service. ...@@ -170,7 +176,10 @@ BL1 SMC service.
This SMC returns the current version of the BL1 SMC service. This SMC returns the current version of the BL1 SMC service.
### BL1_SMC_RUN_IMAGE BL1\_SMC\_RUN\_IMAGE
~~~~~~~~~~~~~~~~~~~~
::
Arguments: Arguments:
uint32_t function ID : 0x4 uint32_t function ID : 0x4
...@@ -184,11 +193,13 @@ This SMC returns the current version of the BL1 SMC service. ...@@ -184,11 +193,13 @@ This SMC returns the current version of the BL1 SMC service.
if (ep_info not EL3) synchronous exception if (ep_info not EL3) synchronous exception
This SMC passes execution control to an EL3 image described by the provided This SMC passes execution control to an EL3 image described by the provided
`entry_point_info_t` structure. In the normal TF boot flow, BL2 invokes this SMC ``entry_point_info_t`` structure. In the normal TF boot flow, BL2 invokes this SMC
for BL1 to pass execution control to BL31. for BL1 to pass execution control to BL31.
FWU\_SMC\_IMAGE\_COPY
~~~~~~~~~~~~~~~~~~~~~
### FWU_SMC_IMAGE_COPY ::
Arguments: Arguments:
uint32_t function ID : 0x10 uint32_t function ID : 0x10
...@@ -214,16 +225,16 @@ for BL1 to pass execution control to BL31. ...@@ -214,16 +225,16 @@ for BL1 to pass execution control to BL31.
if (image_size > free secure memory) return -ENOMEM if (image_size > free secure memory) return -ENOMEM
if (image overlaps another image) return -EPERM 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 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 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. 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. 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 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" 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 state. If there is still more to copy, the FWU state machine stays in or
...@@ -234,8 +245,10 @@ contiguous memory. ...@@ -234,8 +245,10 @@ contiguous memory.
Once the SMC is handled, BL1 returns from exception to the normal world caller. Once the SMC is handled, BL1 returns from exception to the normal world caller.
FWU\_SMC\_IMAGE\_AUTH
~~~~~~~~~~~~~~~~~~~~~
### FWU_SMC_IMAGE_AUTH ::
Arguments: Arguments:
uint32_t function ID : 0x11 uint32_t function ID : 0x11
...@@ -262,9 +275,9 @@ Once the SMC is handled, BL1 returns from exception to the normal world caller. ...@@ -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 is in secure memory) return -ENOMEM
if (image_addr/image_size not mappped into BL1) 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 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 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 ``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 state, BL1 authenticates the image from the secure memory that BL1 previously
copied the image into. copied the image into.
...@@ -272,8 +285,10 @@ BL1 returns from exception to the caller. If authentication succeeds then BL1 ...@@ -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 sets the image state to AUTHENTICATED. If authentication fails then BL1 returns
the -EAUTH error and sets the image state back to RESET. the -EAUTH error and sets the image state back to RESET.
FWU\_SMC\_IMAGE\_EXECUTE
~~~~~~~~~~~~~~~~~~~~~~~~
### FWU_SMC_IMAGE_EXECUTE ::
Arguments: Arguments:
uint32_t function ID : 0x12 uint32_t function ID : 0x12
...@@ -291,15 +306,17 @@ the -EAUTH error and sets the image state back to RESET. ...@@ -291,15 +306,17 @@ the -EAUTH error and sets the image state back to RESET.
if (image_id state is not AUTHENTICATED) return -EPERM if (image_id state is not AUTHENTICATED) return -EPERM
This SMC initiates execution of a previously authenticated image specified by 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 implementation only supports normal world callers initiating execution of a
secure world image. secure world image.
BL1 saves the normal world caller's context, sets the secure image state to BL1 saves the normal world caller's context, sets the secure image state to
EXECUTED, and returns from exception to the secure image. EXECUTED, and returns from exception to the secure image.
FWU\_SMC\_IMAGE\_RESUME
~~~~~~~~~~~~~~~~~~~~~~~
### FWU_SMC_IMAGE_RESUME ::
Arguments: Arguments:
uint32_t function ID : 0x13 uint32_t function ID : 0x13
...@@ -320,11 +337,13 @@ to EXECUTED. For secure world callers, BL1 sets the previously executing secure ...@@ -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 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 context, restores the resuming world's context and returns from exception into
the resuming world. If the call is successful then the caller provided 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. returned to the caller.
FWU\_SMC\_SEC\_IMAGE\_DONE
~~~~~~~~~~~~~~~~~~~~~~~~~~
### FWU_SMC_SEC_IMAGE_DONE ::
Arguments: Arguments:
uint32_t function ID : 0x14 uint32_t function ID : 0x14
...@@ -342,8 +361,10 @@ BL1 sets the previously executing secure image state to the RESET state, ...@@ -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 restores the normal world context and returns from exception into the normal
world. world.
FWU\_SMC\_UPDATE\_DONE
~~~~~~~~~~~~~~~~~~~~~~
### FWU_SMC_UPDATE_DONE ::
Arguments: Arguments:
uint32_t function ID : 0x15 uint32_t function ID : 0x15
...@@ -353,11 +374,13 @@ world. ...@@ -353,11 +374,13 @@ world.
N/A N/A
This SMC completes the firmware update process. BL1 calls the platform specific This SMC completes the firmware update process. BL1 calls the platform specific
function `bl1_plat_fwu_done`, passing the optional argument `client_cookie` as function ``bl1_plat_fwu_done``, passing the optional argument ``client_cookie`` as
a `void *`. The SMC does not return. a ``void *``. The SMC does not return.
FWU\_SMC\_IMAGE\_RESET
~~~~~~~~~~~~~~~~~~~~~~
### FWU_SMC_IMAGE_RESET ::
Arguments: Arguments:
uint32_t function ID : 0x16 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. ...@@ -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. 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 .. |Flow Diagram| image:: diagrams/fwu_flow.png?raw=true
[Auth Framework]: ./auth-framework.md .. |FWU state machine| image:: diagrams/fwu_states.png?raw=true
[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"
docs/interrupt-framework-design.md → docs/interrupt-framework-design.rst
View file @ 7cefb56d
ARM Trusted Firmware Interrupt Management Design guide ARM Trusted Firmware Interrupt Management Design guide
====================================================== ======================================================
Contents :
.. section-numbering::
1. [Introduction](#1-introduction) :suffix: .
* [Concepts](#11-concepts)
- [Interrupt Types](#111-interrupt-types) .. contents::
- [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.
This framework is responsible for managing interrupts routed to EL3. It also This framework is responsible for managing interrupts routed to EL3. It also
allows EL3 software to configure the interrupt routing behavior. Its main allows EL3 software to configure the interrupt routing behavior. Its main
objective is to implement the following two requirements. 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 software (Secure interrupts) to EL3, when execution is in non-secure state
(normal world). The framework should then take care of handing control of (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 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. ...@@ -60,7 +20,7 @@ objective is to implement the following two requirements.
respect to their delivery and handling without the possibility of respect to their delivery and handling without the possibility of
intervention from non-secure software. 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 non-secure software (Non-secure interrupts) to the last executed exception
level in the normal world when the execution is in secure world at 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 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. ...@@ -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 ensures that non-secure software is able to execute in tandem with the
secure software without overriding it. 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 framework categorises an interrupt to be one of the following depending upon
the exception level(s) it is handled in. 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 Secure-EL1 depending upon the security state of the current execution
context. It is always handled in Secure-EL1. 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 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 current execution context. It is always handled in either Non-secure EL1
or EL2. 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 depending upon the security state of the current execution context. It is
always handled in EL3. always handled in EL3.
The following constants define the various interrupt types in the framework The following constants define the various interrupt types in the framework
implementation. implementation.
::
#define INTR_TYPE_S_EL1 0 #define INTR_TYPE_S_EL1 0
#define INTR_TYPE_EL3 1 #define INTR_TYPE_EL3 1
#define INTR_TYPE_NS 2 #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 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 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` 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 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 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 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. 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 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 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 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 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. 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 The default routing model for an interrupt type is to route it to the FEL in
either security state. 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 The framework considers certain routing models for each type of interrupt to be
incorrect as they conflict with the requirements mentioned in Section 1. The incorrect as they conflict with the requirements mentioned in Section 1. The
following sub-sections describe all the possible routing models and specify following sub-sections describe all the possible routing models and specify
...@@ -125,97 +92,99 @@ for GIC version 3.0 (ARM GICv3) and only the Secure-EL1 and Non-secure interrupt ...@@ -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 types are supported for GIC version 2.0 (ARM GICv2) (See 1.2). The terminology
used in the following sub-sections is explained below. used in the following sub-sections is explained below.
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. targeted to EL3.
Secure-EL1 interrupts
^^^^^^^^^^^^^^^^^^^^^
##### 1.1.3.1 Secure-EL1 interrupts #. **CSS=0, TEL3=0**. Interrupt is routed to the FEL when execution is in
1. __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 secure state. This is a valid routing model as secure software is in
control of handling secure interrupts. 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 state. This is a valid routing model as secure software in EL3 can
handover the interrupt to Secure-EL1 for handling. 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 non-secure state. This is an invalid routing model as a secure interrupt
is not visible to the secure software which violates the motivation behind is not visible to the secure software which violates the motivation behind
the ARM Security Extensions. the ARM Security Extensions.
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 non-secure state. This is a valid routing model as secure software in EL3
can handover the interrupt to Secure-EL1 for handling. can handover the interrupt to Secure-EL1 for handling.
Non-secure interrupts
^^^^^^^^^^^^^^^^^^^^^
##### 1.1.3.2 Non-secure interrupts #. **CSS=0, TEL3=0**. Interrupt is routed to the FEL when execution is in
1. __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 secure state. This allows the secure software to trap non-secure
interrupts, perform its book-keeping and hand the interrupt to the interrupts, perform its book-keeping and hand the interrupt to the
non-secure software through EL3. This is a valid routing model as secure 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 software is in control of how its execution is preempted by non-secure
interrupts. 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 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 the state of software in Secure-EL1/Secure-EL0 before handing the
interrupt to non-secure software. This model requires additional interrupt to non-secure software. This model requires additional
coordination between Secure-EL1 and EL3 software to ensure that the coordination between Secure-EL1 and EL3 software to ensure that the
former's state is correctly saved by the latter. 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 non-secure state. This is an valid routing model as a non-secure interrupt
is handled by non-secure software. 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 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 reason to route the interrupt to EL3 software and then hand it back to
non-secure software for handling. non-secure software for handling.
EL3 interrupts
^^^^^^^^^^^^^^
##### 1.1.3.3 EL3 interrupts #. **CSS=0, TEL3=0**. Interrupt is routed to the FEL when execution is in
1. __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 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 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. 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 Secure-EL1/Secure-EL0. This is a valid routing model as secure software
in EL3 can handle the interrupt. 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 non-secure state. This is an invalid routing model as a secure interrupt
is not visible to the secure software which violates the motivation behind is not visible to the secure software which violates the motivation behind
the ARM Security Extensions. the ARM Security Extensions.
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 non-secure state. This is a valid routing model as secure software in EL3
can handle the interrupt. 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 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 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 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 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 uses this information to determine whether the IRQ or the FIQ bit should be
programmed in `SCR_EL3` while applying the routing model for a type of programmed in ``SCR_EL3`` while applying the routing model for a type of
interrupt. The platform provides this information through the interrupt. The platform provides this information through the
`plat_interrupt_type_to_line()` API (described in the [Porting ``plat_interrupt_type_to_line()`` API (described in the
Guide]). For example, on the FVP port when the platform uses an ARM GICv2 `Porting Guide`_). For example, on the FVP port when the platform uses an ARM GICv2
interrupt controller, Secure-EL1 interrupts are signaled through the FIQ signal interrupt controller, Secure-EL1 interrupts are signaled through the FIQ signal
while Non-secure interrupts are signaled through the IRQ signal. This applies while Non-secure interrupts are signaled through the IRQ signal. This applies
when execution is in either security state. when execution is in either security state.
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 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 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 that security state. This means that all the other interrupt types using the
same interrupt signal will be forced to the same routing model. This should be same interrupt signal will be forced to the same routing model. This should be
...@@ -224,34 +193,35 @@ borne in mind when choosing the routing model for an interrupt type. ...@@ -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/ For example, in ARM GICv3, when the execution context is Secure-EL1/
Secure-EL0, both the EL3 and the non secure interrupt types map to the FIQ Secure-EL0, both the EL3 and the non secure interrupt types map to the FIQ
signal. So if either one of the interrupt type sets the routing model so signal. So if either one of the interrupt type sets the routing model so
that __TEL3=1__ when __CSS=0__, the FIQ bit in `SCR_EL3` will be programmed to that **TEL3=1** when **CSS=0**, the FIQ bit in ``SCR_EL3`` will be programmed to
route the FIQ signal to EL3 when executing in Secure-EL1/Secure-EL0, thereby route the FIQ signal to EL3 when executing in Secure-EL1/Secure-EL0, thereby
effectively routing the other interrupt type also to EL3. 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. 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 and Secure-EL1 interrupt), only interrupt controller architectures
like ARM GICv3 has architectural support for EL3 interrupts in the form of like ARM GICv3 has architectural support for EL3 interrupts in the form of
Group 0 interrupts. In ARM GICv2, all secure interrupts are assumed to be Group 0 interrupts. In ARM GICv2, all secure interrupts are assumed to be
handled in Secure-EL1. They can be delivered to Secure-EL1 via EL3 but they handled in Secure-EL1. They can be delivered to Secure-EL1 via EL3 but they
cannot be handled in EL3. cannot be handled in EL3.
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. 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. 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. handler when the interrupt is generated.
Both aspects of interrupt management involve various components in the secure 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 ...@@ -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 in the section 2.1. The framework stores information associated with each type
of interrupt in the following data structure. of interrupt in the following data structure.
``` .. code:: c
typedef struct intr_type_desc {
typedef struct intr_type_desc {
interrupt_type_handler_t handler; interrupt_type_handler_t handler;
uint32_t flags; uint32_t flags;
uint32_t scr_el3[2]; 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 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. 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 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 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 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. parameter.
The `scr_el3[2]` field also stores the routing model but as a mapping of the 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 model in the ``flags`` field to the corresponding bit in the ``SCR_EL3`` for each
security state. security state.
The framework also depends upon the platform port to configure the interrupt 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 ...@@ -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 associated interrupt numbers. It should configure the interrupt controller to
enable the secure interrupts, ensure that their priority is always higher than 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 the non-secure interrupts and target them to the primary CPU. It should also
export the interface described in the [Porting Guide] to enable export the interface described in the `Porting Guide`_ to enable
handling of interrupts. handling of interrupts.
In the remainder of this document, for the sake of simplicity a ARM GICv2 system In the remainder of this document, for the sake of simplicity a ARM GICv2 system
...@@ -294,16 +264,17 @@ is considered and it is assumed that the FIQ signal is used to generate Secure-E ...@@ -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 interrupts and the IRQ signal is used to generate non-secure interrupts in either
security state. EL3 interrupts are not considered. security state. EL3 interrupts are not considered.
Software components
-------------------
### 2.1 Software components
Roles and responsibilities for interrupt management are sub-divided between the Roles and responsibilities for interrupt management are sub-divided between the
following components of software running in EL3 and Secure-EL1. Each component is following components of software running in EL3 and Secure-EL1. Each component is
briefly described below. briefly described below.
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. 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 Secure Payload (SP) software which runs in Secure-EL1/Secure-EL0 and is
responsible for switching execution between secure and non-secure states. responsible for switching execution between secure and non-secure states.
A switch is triggered by a Secure Monitor Call and it uses the APIs A switch is triggered by a Secure Monitor Call and it uses the APIs
...@@ -316,7 +287,7 @@ briefly described below. ...@@ -316,7 +287,7 @@ briefly described below.
An SPD service plugs into the EL3 runtime firmware and could be common to An SPD service plugs into the EL3 runtime firmware and could be common to
some ports of the ARM Trusted Firmware. some ports of 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 to a Secure OS which runs in Secure-EL1/Secure-EL0. It interfaces with the
SPD service to manage communication with non-secure software. ARM Trusted SPD service to manage communication with non-secure software. ARM Trusted
Firmware implements an example secure payload called Test Secure Payload Firmware implements an example secure payload called Test Secure Payload
...@@ -325,43 +296,47 @@ briefly described below. ...@@ -325,43 +296,47 @@ briefly described below.
A Secure payload implementation could be common to some ports of the ARM A Secure payload implementation could be common to some ports of the ARM
Trusted Firmware just like the SPD service. 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) This section describes in detail the role of each software component (see 2.1)
during the registration of a handler for an interrupt type. 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. 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, typedef uint64_t (*interrupt_type_handler_t)(uint32_t id,
uint32_t flags, uint32_t flags,
void *handle, void *handle,
void *cookie); 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 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 #. 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 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 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 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 interrupt was generated and routed as per the routing model specified
during registration. 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 The ``handle`` parameter points to the ``cpu_context`` structure of the current CPU
for the security state specified in the `flags` parameter. for the security state specified in the ``flags`` parameter.
Once the handler routine completes, execution will return to either the secure Once the handler routine completes, execution will return to either the secure
or non-secure state. The handler routine must return a pointer to 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 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. via the context management library APIs.
A portable interrupt handler implementation must set the target context both in 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 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 ...@@ -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 interrupts. This API also requires the caller to specify the routing model for
the type of interrupt. the type of interrupt.
.. code:: c
int32_t register_interrupt_type_handler(uint32_t type, int32_t register_interrupt_type_handler(uint32_t type,
interrupt_type_handler handler, interrupt_type_handler handler,
uint64_t flags); uint64_t flags);
The ``type`` parameter can be one of the three interrupt types listed above i.e.
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
`INTR_TYPE_S_EL1`, `INTR_TYPE_NS` & `INTR_TYPE_EL3`. The `flags` parameter
is as described in Section 2. is as described in Section 2.
The function will return `0` upon a successful registration. It will return The function will return ``0`` upon a successful registration. It will return
`-EALREADY` in case a handler for the interrupt type has already been ``-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 registered. If the ``type`` is unrecognised or the ``flags`` or the ``handler`` are
invalid it will return `-EINVAL`. 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 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 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 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 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 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 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. ``SCR_EL3`` register prior to returning from the EL3 exception level.
.. code:: c
uint32_t cm_get_scr_el3(uint32_t security_state); uint32_t cm_get_scr_el3(uint32_t security_state);
void cm_write_scr_el3_bit(uint32_t security_state, void cm_write_scr_el3_bit(uint32_t security_state,
uint32_t bit_pos, uint32_t bit_pos,
uint32_t value); uint32_t value);
`cm_get_scr_el3()` returns the value of the `SCR_EL3` register for the specified ``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 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 the bit specified by ``bit_pos``. ``register_interrupt_type_handler()`` invokes
`set_routing_model()` API which programs the `SCR_EL3` according to the routing ``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. 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 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 runtime firmware is responsible for programming the routing model. The SPD is
responsible for ensuring that the routing model has been adhered to upon responsible for ensuring that the routing model has been adhered to upon
receiving an interrupt. receiving an interrupt.
Secure payload dispatcher
~~~~~~~~~~~~~~~~~~~~~~~~~
#### 2.2.2 Secure payload dispatcher
A SPD service is responsible for determining and maintaining the interrupt A SPD service is responsible for determining and maintaining the interrupt
routing model supported by itself and the Secure Payload. It is also responsible routing model supported by itself and the Secure Payload. It is also responsible
for ferrying interrupts between secure and non-secure software depending upon 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 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 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 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 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 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 The SPD should determine the mechanism to pass control to the Secure Payload
after receiving an interrupt from the EL3 runtime firmware. This information 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 could either be provided to the SPD service at build time or by the SP at
runtime. 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 The TSPD only handles Secure-EL1 interrupts and is provided with the following
routing model at build time. 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 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 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. 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 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 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. 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 initialisation. The TSP provides the address of the vector table
`tsp_vectors` in the SP which also includes the handler for Secure-EL1 ``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 interrupts in the ``sel1_intr_entry`` field. The TSPD passes control to the TSP at
this address when it receives a Secure-EL1 interrupt. this address when it receives a Secure-EL1 interrupt.
The handover agreement between the TSP and the TSPD requires that the TSPD The handover agreement between the TSP and the TSPD requires that the TSPD
masks all interrupts (`PSTATE.DAIF` bits) when it calls masks all interrupts (``PSTATE.DAIF`` bits) when it calls
`tsp_sel1_intr_entry()`. The TSP has to preserve the callee saved general ``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 purpose, SP\_EL1/Secure-EL0, LR, VFP and system registers. It can use
`x0-x18` to enable its C runtime. ``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 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 */ /* Forward declaration */
interrupt_type_handler tspd_secure_el1_interrupt_handler; interrupt_type_handler tspd_secure_el1_interrupt_handler;
...@@ -482,10 +464,12 @@ requirements mentioned earlier. ...@@ -482,10 +464,12 @@ requirements mentioned earlier.
if (rc) if (rc)
panic(); 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 implements a handler function for non-secure interrupts. This function is
registered with the EL3 runtime firmware using the 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 */ /* Forward declaration */
interrupt_type_handler tspd_ns_interrupt_handler; interrupt_type_handler tspd_ns_interrupt_handler;
...@@ -497,25 +481,26 @@ requirements mentioned earlier. ...@@ -497,25 +481,26 @@ requirements mentioned earlier.
if (rc) if (rc)
panic(); panic();
Secure payload
~~~~~~~~~~~~~~
#### 2.2.3 Secure payload
A Secure Payload must implement an interrupt handling framework at Secure-EL1 A Secure Payload must implement an interrupt handling framework at Secure-EL1
(Secure-EL1 IHF) to support its chosen interrupt routing model. Secure payload (Secure-EL1 IHF) to support its chosen interrupt routing model. Secure payload
execution will alternate between the below cases. 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 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 handling interrupts. This mode applies to both Secure-EL1 and non-secure
interrupts. 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 targeted to the FEL, then execution will eventually migrate to the
non-secure state. Any non-secure interrupts will be handled as described 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 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 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 TEL3=1**) where the SPD service will hand them to the SP. This is defined
as the __synchronous mode__ of handling interrupts. as the **synchronous mode** of handling interrupts.
The interrupt handling framework implemented by the SP should support one or The interrupt handling framework implemented by the SP should support one or
both these interrupt handling models depending upon the chosen routing model. 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 ...@@ -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 the FIQ signal is used to generate Secure-EL1 interrupts and the IRQ signal
is used to generate non-secure interrupts in either security state. is used to generate non-secure interrupts in either security state.
Secure payload IHF design w.r.t secure-EL1 interrupts
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
##### 2.2.3.1 Secure payload IHF design w.r.t secure-EL1 interrupts #. **CSS=0, TEL3=0**. If ``PSTATE.F=0``, Secure-EL1 interrupts will be
1. __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 triggered at one of the Secure-EL1 FIQ exception vectors. The Secure-EL1
IHF should implement support for handling FIQ interrupts asynchronously. 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 synchronous interrupt handling model. The SP could implement this scenario
by exporting a separate entrypoint for Secure-EL1 interrupts to the SPD by exporting a separate entrypoint for Secure-EL1 interrupts to the SPD
service during the registration phase. The SPD service would also need to 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 in which it should arrange to return execution to the SP. The SP should
provide this information in an implementation defined way during the provide this information in an implementation defined way during the
registration phase if it is not known to the SPD service at build time. 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 non-secure state. They should be handled through the synchronous interrupt
handling model as described in 1. above. handling model as described in 1. above.
3. __CSS=0, TEL3=1__. Secure-EL1 interrupts are routed to EL3 when execution #. **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 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 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. call the handler registered by the SPD service for Secure-EL1 interrupts.
Secure-EL1 IHF should then handle all Secure-EL1 interrupt through the Secure-EL1 IHF should then handle all Secure-EL1 interrupt through the
synchronous interrupt handling model described in 1. above. 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 #. **CSS=0, TEL3=0**. If ``PSTATE.I=0``, non-secure interrupts will be
1. __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 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 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 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. ...@@ -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 service at compile time then the SP could provide it during the
registration phase. 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. resumes in the non-secure state.
2. __CSS=0, TEL3=1__. Non-secure interrupts are routed to EL3. They will not #. **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 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 have not effect. The SPD service should register a non-secure interrupt
handler which should save the SP state correctly and resume execution in 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 the non-secure state where the interrupt will be handled. The Secure-EL1
IHF does not need to take any action. 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 non-secure state (EL1/EL2) and are not visible to the SP. This routing
model does not affect the SP behavior. model does not affect the SP behavior.
...@@ -587,104 +574,113 @@ configured at the interrupt controller by the platform port of the EL3 runtime ...@@ -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 firmware. It should configure any additional Secure-EL1 interrupts which the EL3
runtime firmware is not aware of through its platform port. 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 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. 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 interrupts taken in non-secure state and routed through the TSPD service
(synchronous handling model). It passes the reference to this entrypoint via (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 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 exceptions taken at the same (Secure-EL1) exception level. This table is
referenced through the `tsp_exceptions` variable and programmed into the referenced through the ``tsp_exceptions`` variable and programmed into the
VBAR_EL1. It caters for the asynchronous handling model. VBAR\_EL1. It caters for the asynchronous handling model.
The TSP also programs the Secure Physical Timer in the ARM Generic Timer block The TSP also programs the Secure Physical Timer in the ARM Generic Timer block
to raise a periodic interrupt (every half a second) for the purpose of testing to raise a periodic interrupt (every half a second) for the purpose of testing
interrupt management across all the software components listed in 2.1 interrupt management across all the software components listed in 2.1
Interrupt handling
------------------
### 2.3 Interrupt handling
This section describes in detail the role of each software component (see This section describes in detail the role of each software component (see
Section 2.1) in handling an interrupt of a particular type. 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 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 #. IRQ and FIQ exceptions taken from the current exception level with
`SP_EL0` or `SP_EL3` are reported as irrecoverable error conditions. As ``SP_EL0`` or ``SP_EL3`` are reported as irrecoverable error conditions. As
mentioned earlier, EL3 runtime firmware always executes with the 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. lower exception level using AArch64 or AArch32 are handled.
When an interrupt is generated, the vector for each interrupt type is When an interrupt is generated, the vector for each interrupt type is
responsible for: responsible for:
1. Saving the entire general purpose register context (x0-x30) immediately #. Saving the entire general purpose register context (x0-x30) immediately
upon exception entry. The registers are saved in the per-cpu `cpu_context` upon exception entry. The registers are saved in the per-cpu ``cpu_context``
data structure referenced by the `SP_EL3`register. data structure referenced by the ``SP_EL3``\ register.
2. Saving the `ELR_EL3`, `SP_EL0` and `SPSR_EL3` system registers in the #. 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. 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 #. 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 from the per-cpu ``cpu_context`` data structure in ``SP_EL0`` and
executing the `msr spsel, #0` instruction. 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 at the FIQ vector. Non-secure interrupts will be signaled at the IRQ
vector. The platform should implement the following API to determine the vector. The platform should implement the following API to determine the
type of the pending interrupt. type of the pending interrupt.
.. code:: c
uint32_t plat_ic_get_interrupt_type(void); 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. The following API has been added for this purpose.
.. code:: c
interrupt_type_handler get_interrupt_type_handler(uint32_t interrupt_type); interrupt_type_handler get_interrupt_type_handler(uint32_t interrupt_type);
It returns the reference to the registered handler for this interrupt It returns the reference to the registered handler for this interrupt
type. The `handler` is retrieved from the `intr_type_desc_t` structure as 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 described in Section 2. ``NULL`` is returned if no handler has been
registered for this type of interrupt. This scenario is reported as an registered for this type of interrupt. This scenario is reported as an
irrecoverable error condition. irrecoverable error condition.
6. Calling the registered handler function for the interrupt type generated. #. Calling the registered handler function for the interrupt type generated.
The `id` parameter is set to `INTR_ID_UNAVAILABLE` currently. The id along 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` 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 structure for the current security state are passed to the handler function
as its arguments. 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. structure for the target security state.
7. Calling `el3_exit()` to return from EL3 into a lower exception level in #. Calling ``el3_exit()`` to return from EL3 into a lower exception level in
the security state determined by the handler routine. The `el3_exit()` the security state determined by the handler routine. The ``el3_exit()``
function is responsible for restoring the register context from the 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 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 the handler function for that type of interrupt. The SPD service is responsible
for the following: 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 generating according to the interrupt routing model specified by the SPD
service during registration. It should use the security state of the 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 the interrupt was taken from to determine this. If the interrupt is not
recognised then the handler should treat it as an irrecoverable error recognised then the handler should treat it as an irrecoverable error
condition. condition.
...@@ -696,23 +692,23 @@ for the following: ...@@ -696,23 +692,23 @@ for the following:
S-EL1 interrupt should never be routed to EL3 from secure state. The handler S-EL1 interrupt should never be routed to EL3 from secure state. The handler
could use the security state flag to check this. 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, routing model and interrupt type. For non secure and S-EL1 interrupt,
if the security state of the execution context where the interrupt was if the security state of the execution context where the interrupt was
generated is not the same as the security state required for handling generated is not the same as the security state required for handling
the interrupt, a context switch is required. The following 2 cases the interrupt, a context switch is required. The following 2 cases
require a context switch from secure to non-secure or vice-versa: 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. 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. to the last known non-secure exception level.
The SPD service must save the system register context of the current The SPD service must save the system register context of the current
security state. It must then restore the system register context of the 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 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 to ensure that the next ``cpu_context`` to be restored is of the target
security state. security state.
If the target state is secure then execution should be handed to the SP as If the target state is secure then execution should be handed to the SP as
...@@ -723,7 +719,7 @@ for the following: ...@@ -723,7 +719,7 @@ for the following:
service should be able to handle this preemption or manage secure interrupt service should be able to handle this preemption or manage secure interrupt
priorities before handing control to the SP. 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 the interrupt has been successfully validated and ready to be handled at a
lower exception level. lower exception level.
...@@ -734,47 +730,49 @@ exception level in the non-secure state. The former should save the SP context, ...@@ -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 restore the non-secure context and arrange for entry into the non-secure state
so that the interrupt can be handled. 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 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 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 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 exception level and the security state from where the Secure-EL1 interrupt was
originally taken. 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 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 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 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 originating from the non-secure state. It takes the following actions upon being
invoked. 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 that the secure interrupt originated from the non-secure state. It asserts
if this is not the case. if this is not the case.
2. It saves the system register context for the non-secure state by calling #. It 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. It sets the `ELR_EL3` system register to `tsp_sel1_intr_entry` and sets the #. 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 ``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 ``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 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 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 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 save any other secure context since the TSP is expected to preserve it
(see Section 2.2.2.1). (see Section 2.2.2.1).
4. It restores the system register context for the secure state by calling #. It restores the system register context for the secure state by calling
`cm_el1_sysregs_context_restore(SECURE);`. ``cm_el1_sysregs_context_restore(SECURE);``.
5. It ensures that the secure CPU context is used to program the next #. 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);`. 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 #. 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` 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 register for the non-secure state. This information is used by the SP for
debugging purposes. debugging purposes.
...@@ -782,113 +780,115 @@ The figure below describes how the interrupt handling is implemented by the TSPD ...@@ -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 when a Secure-EL1 interrupt is generated when execution is in the non-secure
state. 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. signal completion of interrupt handling.
The TSPD service takes the following actions in `tspd_smc_handler()` function 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: 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 #. It ensures that the call originated from the secure state otherwise
execution returns to the non-secure state with `SMC_UNK` in `x0`. 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 the secure CPU context (see step 3 above) in case the TSP had been preempted
by a non secure interrupt earlier. by a non secure interrupt earlier.
3. It restores the system register context for the non-secure state by #. It restores the system register context for the non-secure state by
calling `cm_el1_sysregs_context_restore(NON_SECURE)`. calling ``cm_el1_sysregs_context_restore(NON_SECURE)``.
4. It ensures that the non-secure CPU context is used to program the next #. 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)`. 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. 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 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 Secure-EL1 interrupt processing. Currently only non-secure interrupts can
cause preemption of TSP since there are no EL3 interrupts in the cause preemption of TSP since there are no EL3 interrupts in the
system. system.
It should be noted that while TSP is preempted, the TSPD only allows entry into 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 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). (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 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 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 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()`` as the non-secure interrupt handler. The
`tspd_ns_interrupt_handler()` on being invoked ensures that the interrupt ``tspd_ns_interrupt_handler()`` on being invoked ensures that the interrupt
originated from the secure state and disables routing of non-secure interrupts 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 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 interrupt) when TSP is reentered for handling Secure-EL1 interrupts that
triggered while execution was in the normal world. The 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. 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 routing model for non-secure interrupt in secure state is in effect
i.e. __TEL3=0, CSS=0__. During `yielding` SMC processing, the IRQ 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 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 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, 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 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. 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: invoked:
1. It saves the system register context for the secure state by calling #. It saves the system register context for the secure state by calling
`cm_el1_sysregs_context_save(SECURE)`. ``cm_el1_sysregs_context_save(SECURE)``.
2. It restores the system register context for the non-secure state by #. It restores the system register context for the non-secure state by
calling `cm_el1_sysregs_context_restore(NON_SECURE)`. calling ``cm_el1_sysregs_context_restore(NON_SECURE)``.
3. It ensures that the non-secure CPU context is used to program the next #. 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)`. 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. restoring non secure context.
The Normal World is expected to resume the TSP after the `yielding` SMC preemption 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). 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 TSPD service takes the following actions in ``tspd_smc_handler()`` function
upon receiving this SMC: 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. 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 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 #. Restores the secure context by calling
`cm_el1_sysregs_context_restore(SECURE)` ``cm_el1_sysregs_context_restore(SECURE)``
4. It ensures that the secure CPU context is used to program the next #. 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)`. 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. return value.
The figure below describes how the TSP/TSPD handle a non-secure interrupt when 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 it is generated during execution in the TSP with ``PSTATE.I`` = 0 when the
`TSP_NS_INTR_ASYNC_PREEMPT` build flag is 0. ``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 The SP should implement one or both of the synchronous and asynchronous
interrupt handling models depending upon the interrupt routing model it has interrupt handling models depending upon the interrupt routing model it has
chosen (as described in 2.2.3). chosen (as described in 2.2.3).
...@@ -897,76 +897,80 @@ In the synchronous model, it should begin handling a Secure-EL1 interrupt after ...@@ -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 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 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 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 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 state where the interrupt was originally taken from. The SP should use an SMC32
or SMC64 to ask the SPD service to do this. or SMC64 to ask the SPD service to do this.
In the asynchronous model, the Secure Payload is responsible for handling 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 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 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 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 level. This will allow the non-secure interrupt to be handled in the non-secure
state. 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 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 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 statistics by calling ``tsp_update_sync_sel1_intr_stats()``. It then calls
`tsp_common_int_handler()` which. ``tsp_common_int_handler()`` which.
1. Checks whether the interrupt is the secure physical timer interrupt. It #. Checks whether the interrupt is the secure physical timer interrupt. It
uses the platform API `plat_ic_get_pending_interrupt_id()` to get the 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 interrupt number. If it is not the secure physical timer interrupt, then
that means that a higher priority interrupt has preempted it. Invoke that means that a higher priority interrupt has preempted it. Invoke
`tsp_handle_preemption()` to handover control back to EL3 by issuing ``tsp_handle_preemption()`` to handover control back to EL3 by issuing
an SMC with `TSP_PREEMPTED` as the function identifier. an SMC with ``TSP_PREEMPTED`` as the function identifier.
2. Handles the secure timer interrupt interrupt by acknowledging it using the #. Handles the secure timer interrupt interrupt by acknowledging it using the
`plat_ic_acknowledge_interrupt()` platform API, calling ``plat_ic_acknowledge_interrupt()`` platform API, calling
`tsp_generic_timer_handler()` to reprogram the secure physical generic ``tsp_generic_timer_handler()`` to reprogram the secure physical generic
timer and calling the `plat_ic_end_of_interrupt()` platform API to signal timer and calling the ``plat_ic_end_of_interrupt()`` platform API to signal
end of interrupt processing. end of interrupt processing.
The TSP passes control back to the TSPD by issuing an SMC64 with 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. 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. function. The function has been described above.
2. Non-secure interrupts are handled by by calling the `tsp_common_int_handler()` #. Non-secure interrupts are handled by by calling the ``tsp_common_int_handler()``
function which ends up invoking `tsp_handle_preemption()` and issuing an function which ends up invoking ``tsp_handle_preemption()`` and issuing an
SMC64 with `TSP_PREEMPTED` as the function identifier. Execution resumes at SMC64 with ``TSP_PREEMPTED`` as the function identifier. Execution resumes at
the instruction that follows this SMC instruction when the TSPD hands 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). 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 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 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. 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 This can be achieved by issuing an SMC call which instructs to resume the
preempted SMC. 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. a fast SMC call.
In the Test Secure Payload implementation, `TSP_FID_RESUME` is designated 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 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 ``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, secure software sequence for issuing a ``yielding`` SMC would look like this,
assuming `P.STATE.I=0` in the non secure state : assuming ``P.STATE.I=0`` in the non secure state :
.. code:: c
int rc; int rc;
rc = smc(TSP_YIELD_SMC_FID, ...); /* Issue a Yielding SMC call */ 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 : ...@@ -976,22 +980,24 @@ assuming `P.STATE.I=0` in the non secure state :
rc = smc(TSP_FID_RESUME); /* Issue resume SMC call */ 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 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 interrupt causes an IRQ exception and the IRQ handler registered at the
exception vector handles the non-secure interrupt and returns. The return value 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 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 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. 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` 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 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 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 .. |Image 1| image:: diagrams/sec-int-handling.png?raw=true
[SMC calling convention]: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html "SMC Calling Convention PDD (ARM DEN 0028A)" .. |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 Tegra SoCs - Overview
====================== =====================
* T210 - .. rubric:: T210
------- :name: t210
T210 has Quad ARM® Cortex®-A57 cores in a switched configuration with a T210 has Quad ARM® Cortex®-A57 cores in a switched configuration with a
companion set of quad ARM Cortex-A53 cores. The Cortex-A57 and A53 cores companion set of quad ARM Cortex-A53 cores. The Cortex-A57 and A53 cores
...@@ -12,8 +12,8 @@ including legacy ARMv7 applications. The Cortex-A57 processors each have ...@@ -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 Level 2 unified cache. The Cortex-A53 processors each have 32 KB Instruction
and 32 KB Data Level 1 caches; and have a 512 KB shared Level 2 unified cache. and 32 KB Data Level 1 caches; and have a 512 KB shared Level 2 unified cache.
* T132 - .. rubric:: T132
------- :name: t132
Denver is NVIDIA's own custom-designed, 64-bit, dual-core CPU which is Denver is NVIDIA's own custom-designed, 64-bit, dual-core CPU which is
fully ARMv8 architecture compatible. Each of the two Denver cores fully ARMv8 architecture compatible. Each of the two Denver cores
...@@ -41,13 +41,14 @@ to extensive power-gating and dynamic voltage and clock scaling based on ...@@ -41,13 +41,14 @@ to extensive power-gating and dynamic voltage and clock scaling based on
workloads. workloads.
Directory structure Directory structure
==================== ===================
* plat/nvidia/tegra/common - Common code for all Tegra SoCs - plat/nvidia/tegra/common - Common code for all Tegra SoCs
* plat/nvidia/tegra/soc/txxx - Chip specific code - plat/nvidia/tegra/soc/txxx - Chip specific code
Trusted OS dispatcher Trusted OS dispatcher
===================== =====================
Tegra supports multiple Trusted OS', Trusted Little Kernel (TLK) being one of 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' 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 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 ...@@ -55,39 +56,43 @@ vendors to use the upstream code and include their dispatchers in the image
without changing any makefiles. without changing any makefiles.
Preparing the BL31 image to run on Tegra SoCs 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. to the build command line.
The Tegra platform code expects a pointer to the following platform specific 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 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 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 memory controller driver programs this base/size in order to restrict NS
accesses. accesses.
typedef struct plat_params_from_bl2 { typedef struct plat\_params\_from\_bl2 {
/* TZ memory size */ /\* TZ memory size */
uint64_t tzdram_size; uint64\_t tzdram\_size;
/* TZ memory base */ /* TZ memory base */
uint64_t tzdram_base; uint64\_t tzdram\_base;
/* UART port ID */ /* UART port ID \*/
int uart_id; int uart\_id;
} plat_params_from_bl2_t; } plat\_params\_from\_bl2\_t;
Power Management Power Management
================ ================
The PSCI implementation expects each platform to expose the 'power state' The PSCI implementation expects each platform to expose the 'power state'
parameter to be used during the 'SYSTEM SUSPEND' call. The state-id field parameter to be used during the 'SYSTEM SUSPEND' call. The state-id field
is implementation defined on Tegra SoCs and is preferably defined by is implementation defined on Tegra SoCs and is preferably defined by
tegra_def.h. tegra\_def.h.
Tegra configs Tegra configs
============= =============
* 'tegra_enable_l2_ecc_parity_prot': This flag enables the L2 ECC and Parity - 'tegra\_enable\_l2\_ecc\_parity\_prot': This flag enables the L2 ECC and Parity
Protection bit, for ARM Cortex-A57 CPUs, during CPU boot. This flag will Protection bit, for ARM Cortex-A57 CPUs, during CPU boot. This flag will
be enabled by Tegrs SoCs during 'Cluster power up' or 'System Suspend' exit. be enabled by Tegrs SoCs during 'Cluster power up' or 'System Suspend' exit.
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 ...@@ -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. provided as it's generated by QEMU.
Current limitations: 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 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 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 binaries has to reside in the same directory as QEMU is started from. This
is conveniently achieved with symlinks the local names as: is conveniently achieved with symlinks the local names as:
* `bl2.bin` -> BL2
* `bl31.bin` -> BL31 - ``bl2.bin`` -> BL2
* `bl33.bin` -> BL33 (`QEMU_EFI.fd`) - ``bl31.bin`` -> BL31
* `Image` -> linux/Image - ``bl33.bin`` -> BL33 (``QEMU_EFI.fd``)
- ``Image`` -> linux/Image
To build: To build:
```
make CROSS_COMPILE=aarch64-none-elf- PLAT=qemu ::
```
make CROSS_COMPILE=aarch64-none-elf- PLAT=qemu
To start (QEMU v2.6.0): 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 \ -kernel Image \
-append console=ttyAMA0,38400 keep_bootcon root=/dev/vda2 \ -append console=ttyAMA0,38400 keep_bootcon root=/dev/vda2 \
-initrd rootfs-arm64.cpio.gz -smp 2 -m 1024 -bios bl1.bin \ -initrd rootfs-arm64.cpio.gz -smp 2 -m 1024 -bios bl1.bin \
-d unimp -semihosting-config enable,target=native -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