Merge pull request #1012 from rockchip-linux/rk3399/l2cache
rockchip/rk3399: fixes the typo and the WARNINGS during suspend/resume
diff --git a/Makefile b/Makefile
index b9805c7..6aa4e9a 100644
--- a/Makefile
+++ b/Makefile
@@ -8,7 +8,7 @@
# Trusted Firmware Version
#
VERSION_MAJOR := 1
-VERSION_MINOR := 3
+VERSION_MINOR := 4
# Default goal is build all images
.DEFAULT_GOAL := all
diff --git a/acknowledgements.md b/acknowledgements.rst
similarity index 98%
rename from acknowledgements.md
rename to acknowledgements.rst
index 028f321..59f569e 100644
--- a/acknowledgements.md
+++ b/acknowledgements.rst
@@ -3,6 +3,7 @@
Companies
---------
+
Linaro Limited
NVIDIA Corporation
diff --git a/contributing.md b/contributing.md
deleted file mode 100644
index 65d2ca8..0000000
--- a/contributing.md
+++ /dev/null
@@ -1,123 +0,0 @@
-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
diff --git a/contributing.rst b/contributing.rst
new file mode 100644
index 0000000..cdf0620
--- /dev/null
+++ b/contributing.rst
@@ -0,0 +1,129 @@
+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
diff --git a/docs/arm-sip-service.md b/docs/arm-sip-service.md
deleted file mode 100644
index 7ebb724..0000000
--- a/docs/arm-sip-service.md
+++ /dev/null
@@ -1,91 +0,0 @@
-
-ARM SiP Service
-===============
-
-This document enumerates and describes the ARM SiP (Silicon Provider) services.
-
-SiP services are non-standard, platform-specific services offered by the silicon
-implementer or platform provider. They are accessed via. `SMC` ("SMC calls")
-instruction executed from Exception Levels below EL3. SMC calls for SiP
-services:
-
-* Follow [SMC Calling Convention][SMCCC];
-* Use SMC function IDs that fall in the SiP range, which are `0xc2000000` -
- `0xc200ffff` for 64-bit calls, and `0x82000000` - `0x8200ffff` for 32-bit
- calls.
-
-The ARM SiP implementation offers the following services:
-
-* Performance Measurement Framework (PMF)
-* Execution State Switching service
-
-Source definitions for ARM SiP service are located in the `arm_sip_svc.h` header
-file.
-
-Performance Measurement Framework (PMF)
----------------------------------------
-
-The [Performance Measurement Framework](./firmware-design.md#13--performance-measurement-framework)
-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].
-
-Execution State Switching service
----------------------------------
-
-Execution State Switching service provides a mechanism for a non-secure lower
-Exception Level (either EL2, or NS EL1 if EL2 isn't implemented) to request to
-switch its execution state (a.k.a. Register Width), either from AArch64 to
-AArch32, or from AArch32 to AArch64, for the calling CPU. This service is only
-available when ARM Trusted Firmware is built for AArch64 (i.e. when build option
-`ARCH` is set to `aarch64`).
-
-### `ARM_SIP_SVC_EXE_STATE_SWITCH`
-
- Arguments:
- uint32_t Function ID
- uint32_t PC hi
- uint32_t PC lo
- uint32_t Cookie hi
- uint32_t Cookie lo
-
- Return:
- uint32_t
-
-The function ID parameter must be `0x82000020`. It uniquely identifies the
-Execution State Switching service being requested.
-
-The parameters _PC hi_ and _PC lo_ defines upper and lower words, respectively,
-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.
-
-When execution starts at the supplied entry point after Execution State has been
-switched, the parameters _Cookie hi_ and _Cookie lo_ are passed in CPU registers
-0 and 1, respectively. When calling from AArch64, _Cookie hi_ must be 0.
-
-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.
-
-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
-have a defined reset value by the Architecture will assume that value. Other
-registers should not be expected to hold their values before the call was made.
-CPU endianness, however, is preserved from the previous execution state. Note
-that this switches the execution state of the calling CPU only. This is not a
-substitute for PSCI `SYSTEM_RESET`.
-
-The service may return the following error codes:
-
- - `STATE_SW_E_PARAM`: If any of the parameters were deemed invalid for
- a specific request.
- - `STATE_SW_E_DENIED`: If the call is not successful, or when ARM Trusted
- Firmware is built for AArch32.
-
-If the call is successful, the caller wouldn't observe the SMC returning.
-Instead, execution starts at the supplied entry point, with the CPU registers 0
-and 1 populated with the supplied _Cookie hi_ and _Cookie lo_ values,
-respectively.
-
-- - - - - - - - - - - - - - - - - - - - - - - - - -
-
-[Firmware Design]: ./firmware-design.md
-[SMCCC]: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html "SMC Calling Convention PDD (ARM DEN 0028A)"
diff --git a/docs/arm-sip-service.rst b/docs/arm-sip-service.rst
new file mode 100644
index 0000000..6d456c7
--- /dev/null
+++ b/docs/arm-sip-service.rst
@@ -0,0 +1,96 @@
+ARM SiP Service
+===============
+
+This document enumerates and describes the ARM SiP (Silicon Provider) services.
+
+SiP services are non-standard, platform-specific services offered by the silicon
+implementer or platform provider. They are accessed via. ``SMC`` ("SMC calls")
+instruction executed from Exception Levels below EL3. SMC calls for SiP
+services:
+
+- Follow `SMC Calling Convention`_;
+- Use SMC function IDs that fall in the SiP range, which are ``0xc2000000`` -
+ ``0xc200ffff`` for 64-bit calls, and ``0x82000000`` - ``0x8200ffff`` for 32-bit
+ calls.
+
+The ARM SiP implementation offers the following services:
+
+- Performance Measurement Framework (PMF)
+- Execution State Switching service
+
+Source definitions for ARM SiP service are located in the ``arm_sip_svc.h`` header
+file.
+
+Performance Measurement Framework (PMF)
+---------------------------------------
+
+The `Performance Measurement Framework`_
+allows callers to retrieve timestamps captured at various paths in ARM Trusted
+Firmware execution. It's described in detail in `Firmware Design document`_.
+
+Execution State Switching service
+---------------------------------
+
+Execution State Switching service provides a mechanism for a non-secure lower
+Exception Level (either EL2, or NS EL1 if EL2 isn't implemented) to request to
+switch its execution state (a.k.a. Register Width), either from AArch64 to
+AArch32, or from AArch32 to AArch64, for the calling CPU. This service is only
+available when ARM Trusted Firmware is built for AArch64 (i.e. when build option
+``ARCH`` is set to ``aarch64``).
+
+``ARM_SIP_SVC_EXE_STATE_SWITCH``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Arguments:
+ uint32_t Function ID
+ uint32_t PC hi
+ uint32_t PC lo
+ uint32_t Cookie hi
+ uint32_t Cookie lo
+
+ Return:
+ uint32_t
+
+The function ID parameter must be ``0x82000020``. It uniquely identifies the
+Execution State Switching service being requested.
+
+The parameters *PC hi* and *PC lo* defines upper and lower words, respectively,
+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.
+
+When execution starts at the supplied entry point after Execution State has been
+switched, the parameters *Cookie hi* and *Cookie lo* are passed in CPU registers
+0 and 1, respectively. When calling from AArch64, *Cookie hi* must be 0.
+
+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.
+
+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
+have a defined reset value by the Architecture will assume that value. Other
+registers should not be expected to hold their values before the call was made.
+CPU endianness, however, is preserved from the previous execution state. Note
+that this switches the execution state of the calling CPU only. This is not a
+substitute for PSCI ``SYSTEM_RESET``.
+
+The service may return the following error codes:
+
+- ``STATE_SW_E_PARAM``: If any of the parameters were deemed invalid for
+ a specific request.
+- ``STATE_SW_E_DENIED``: If the call is not successful, or when ARM Trusted
+ Firmware is built for AArch32.
+
+If the call is successful, the caller wouldn't observe the SMC returning.
+Instead, execution starts at the supplied entry point, with the CPU registers 0
+and 1 populated with the supplied *Cookie hi* and *Cookie lo* values,
+respectively.
+
+--------------
+
+*Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.*
+
+.. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
+.. _Performance Measurement Framework: ./firmware-design.rst#user-content-performance-measurement-framework
+.. _Firmware Design document: ./firmware-design.rst
diff --git a/docs/auth-framework.md b/docs/auth-framework.md
deleted file mode 100644
index b416acf..0000000
--- a/docs/auth-framework.md
+++ /dev/null
@@ -1,925 +0,0 @@
-Abstracting a Chain of Trust
-============================
-
-Contents :
-
-1. [Introduction](#1--introduction)
-2. [Framework design](#2--framework-design)
-3. [Specifying a Chain of Trust](#3--specifying-a-chain-of-trust)
-4. [Implementation example](#4--implementation-example)
-
-
-1. Introduction
-----------------
-
-The aim of this document is to describe the authentication framework implemented
-in the Trusted Firmware. This framework fulfills the following requirements:
-
-1. It should be possible for a platform port to specify the Chain of Trust in
- terms of certificate hierarchy and the mechanisms used to verify a
- particular image/certificate.
-
-2. The framework should distinguish between:
-
- - The mechanism used to encode and transport information, e.g. DER encoded
- X.509v3 certificates to ferry Subject Public Keys, hashes and non-volatile
- counters.
-
- - The mechanism used to verify the transported information i.e. the
- cryptographic libraries.
-
-The framework has been designed following a modular approach illustrated in the
-next diagram:
-
-```
- +---------------+---------------+------------+
- | Trusted | Trusted | Trusted |
- | Firmware | Firmware | Firmware |
- | Generic | IO Framework | Platform |
- | Code i.e. | (IO) | Port |
- | BL1/BL2 (GEN) | | (PP) |
- +---------------+---------------+------------+
- ^ ^ ^
- | | |
- v v v
- +-----------+ +-----------+ +-----------+
- | | | | | Image |
- | Crypto | | Auth | | Parser |
- | Module |<->| Module |<->| Module |
- | (CM) | | (AM) | | (IPM) |
- | | | | | |
- +-----------+ +-----------+ +-----------+
- ^ ^
- | |
- v v
- +----------------+ +-----------------+
- | Cryptographic | | Image Parser |
- | Libraries (CL) | | Libraries (IPL) |
- +----------------+ +-----------------+
- | |
- | |
- | |
- v v
- +-----------------+
- | Misc. Libs e.g. |
- | ASN.1 decoder |
- | |
- +-----------------+
-
- DIAGRAM 1.
-```
-
-This document describes the inner details of the authentication framework and
-the abstraction mechanisms available to specify a Chain of Trust.
-
-
-2. Framework design
---------------------
-
-This section describes some aspects of the framework design and the rationale
-behind them. These aspects are key to verify a Chain of Trust.
-
-### 2.1 Chain of Trust
-
-A CoT is basically a sequence of authentication images which usually starts with
-a root of trust and culminates in a single data image. The following diagram
-illustrates how this maps to a CoT for the BL31 image described in the
-TBBR-Client specification.
-
-```
- +------------------+ +-------------------+
- | ROTPK/ROTPK Hash |------>| Trusted Key |
- +------------------+ | Certificate |
- | (Auth Image) |
- /+-------------------+
- / |
- / |
- / |
- / |
- L v
- +------------------+ +-------------------+
- | Trusted World |------>| BL31 Key |
- | Public Key | | Certificate |
- +------------------+ | (Auth Image) |
- +-------------------+
- / |
- / |
- / |
- / |
- / v
- +------------------+ L +-------------------+
- | BL31 Content |------>| BL31 Content |
- | Certificate PK | | Certificate |
- +------------------+ | (Auth Image) |
- +-------------------+
- / |
- / |
- / |
- / |
- / v
- +------------------+ L +-------------------+
- | BL31 Hash |------>| BL31 Image |
- | | | (Data Image) |
- +------------------+ | |
- +-------------------+
-
- DIAGRAM 2.
-```
-
-The root of trust is usually a public key (ROTPK) that has been burnt in the
-platform and cannot be modified.
-
-### 2.2 Image types
-
-Images in a CoT are categorised as authentication and data images. An
-authentication image contains information to authenticate a data image or
-another authentication image. A data image is usually a boot loader binary, but
-it could be any other data that requires authentication.
-
-### 2.3 Component responsibilities
-
-For every image in a Chain of Trust, the following high level operations are
-performed to verify it:
-
-1. Allocate memory for the image either statically or at runtime.
-
-2. Identify the image and load it in the allocated memory.
-
-3. Check the integrity of the image as per its type.
-
-4. Authenticate the image as per the cryptographic algorithms used.
-
-5. If the image is an authentication image, extract the information that will
- be used to authenticate the next image in the CoT.
-
-In Diagram 1, each component is responsible for one or more of these operations.
-The responsibilities are briefly described below.
-
-
-#### 2.2.1 TF Generic code and IO framework (GEN/IO)
-
-These components are responsible for initiating the authentication process for a
-particular image in BL1 or BL2. For each BL image that requires authentication,
-the Generic code asks recursively the Authentication module what is the parent
-image until either an authenticated image or the ROT is reached. Then the
-Generic code calls the IO framewotk to load the image and calls the
-Authentication module to authenticate it, following the CoT from ROT to Image.
-
-
-#### 2.2.2 TF Platform Port (PP)
-
-The platform is responsible for:
-
-1. Specifying the CoT for each image that needs to be authenticated. Details of
- how a CoT can be specified by the platform are explained later. The platform
- also specifies the authentication methods and the parsing method used for
- each image.
-
-2. Statically allocating memory for each parameter in each image which is
- used for verifying the CoT, e.g. memory for public keys, hashes etc.
-
-3. Providing the ROTPK or a hash of it.
-
-4. Providing additional information to the IPM to enable it to identify and
- extract authentication parameters contained in an image, e.g. if the
- parameters are stored as X509v3 extensions, the corresponding OID must be
- provided.
-
-5. Fulfill any other memory requirements of the IPM and the CM (not currently
- described in this document).
-
-6. Export functions to verify an image which uses an authentication method that
- cannot be interpreted by the CM, e.g. if an image has to be verified using a
- NV counter, then the value of the counter to compare with can only be
- provided by the platform.
-
-7. Export a custom IPM if a proprietary image format is being used (described
- later).
-
-
-#### 2.2.3 Authentication Module (AM)
-
-It is responsible for:
-
-1. Providing the necessary abstraction mechanisms to describe a CoT. Amongst
- other things, the authentication and image parsing methods must be specified
- by the PP in the CoT.
-
-2. Verifying the CoT passed by GEN by utilising functionality exported by the
- PP, IPM and CM.
-
-3. Tracking which images have been verified. In case an image is a part of
- multiple CoTs then it should be verified only once e.g. the Trusted World
- Key Certificate in the TBBR-Client spec. contains information to verify
- SCP_BL2, BL31, BL32 each of which have a separate CoT. (This
- responsibility has not been described in this document but should be
- trivial to implement).
-
-4. Reusing memory meant for a data image to verify authentication images e.g.
- in the CoT described in Diagram 2, each certificate can be loaded and
- verified in the memory reserved by the platform for the BL31 image. By the
- time BL31 (the data image) is loaded, all information to authenticate it
- will have been extracted from the parent image i.e. BL31 content
- certificate. It is assumed that the size of an authentication image will
- never exceed the size of a data image. It should be possible to verify this
- at build time using asserts.
-
-
-#### 2.2.4 Cryptographic Module (CM)
-
-The CM is responsible for providing an API to:
-
-1. Verify a digital signature.
-2. Verify a hash.
-
-The CM does not include any cryptography related code, but it relies on an
-external library to perform the cryptographic operations. A Crypto-Library (CL)
-linking the CM and the external library must be implemented. The following
-functions must be provided by the CL:
-
-```
-void (*init)(void);
-int (*verify_signature)(void *data_ptr, unsigned int data_len,
- void *sig_ptr, unsigned int sig_len,
- void *sig_alg, unsigned int sig_alg_len,
- void *pk_ptr, unsigned int pk_len);
-int (*verify_hash)(void *data_ptr, unsigned int data_len,
- void *digest_info_ptr, unsigned int digest_info_len);
-```
-
-These functions are registered in the CM using the macro:
-```
-REGISTER_CRYPTO_LIB(_name, _init, _verify_signature, _verify_hash);
-```
-
-`_name` must be a string containing the name of the CL. This name is used for
-debugging purposes.
-
-#### 2.2.5 Image Parser Module (IPM)
-
-The IPM is responsible for:
-
-1. Checking the integrity of each image loaded by the IO framework.
-2. Extracting parameters used for authenticating an image based upon a
- description provided by the platform in the CoT descriptor.
-
-Images may have different formats (for example, authentication images could be
-x509v3 certificates, signed ELF files or any other platform specific format).
-The IPM allows to register an Image Parser Library (IPL) for every image format
-used in the CoT. This library must implement the specific methods to parse the
-image. The IPM obtains the image format from the CoT and calls the right IPL to
-check the image integrity and extract the authentication parameters.
-
-See Section "Describing the image parsing methods" for more details about the
-mechanism the IPM provides to define and register IPLs.
-
-
-### 2.3 Authentication methods
-
-The AM supports the following authentication methods:
-
-1. Hash
-2. Digital signature
-
-The platform may specify these methods in the CoT in case it decides to define
-a custom CoT instead of reusing a predefined one.
-
-If a data image uses multiple methods, then all the methods must be a part of
-the same CoT. The number and type of parameters are method specific. These
-parameters should be obtained from the parent image using the IPM.
-
-1. Hash
-
- Parameters:
-
- 1. A pointer to data to hash
- 2. Length of the data
- 4. A pointer to the hash
- 5. Length of the hash
-
- The hash will be represented by the DER encoding of the following ASN.1
- type:
-
- ```
- DigestInfo ::= SEQUENCE {
- digestAlgorithm DigestAlgorithmIdentifier,
- digest Digest
- }
- ```
-
- This ASN.1 structure makes it possible to remove any assumption about the
- type of hash algorithm used as this information accompanies the hash. This
- should allow the Cryptography Library (CL) to support multiple hash
- algorithm implementations.
-
-2. Digital Signature
-
- Parameters:
-
- 1. A pointer to data to sign
- 2. Length of the data
- 3. Public Key Algorithm
- 4. Public Key value
- 5. Digital Signature Algorithm
- 6. Digital Signature value
-
- The Public Key parameters will be represented by the DER encoding of the
- following ASN.1 type:
-
- ```
- SubjectPublicKeyInfo ::= SEQUENCE {
- algorithm AlgorithmIdentifier{PUBLIC-KEY,{PublicKeyAlgorithms}},
- subjectPublicKey BIT STRING }
- ```
-
- The Digital Signature Algorithm will be represented by the DER encoding of
- the following ASN.1 types.
-
- ```
- AlgorithmIdentifier {ALGORITHM:IOSet } ::= SEQUENCE {
- algorithm ALGORITHM.&id({IOSet}),
- parameters ALGORITHM.&Type({IOSet}{@algorithm}) OPTIONAL
- }
- ```
-
- The digital signature will be represented by:
- ```
- signature ::= BIT STRING
- ```
-
-The authentication framework will use the image descriptor to extract all the
-information related to authentication.
-
-
-3. Specifying a Chain of Trust
--------------------------------
-
-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
-verified. Each image has a set of properties which allow the AM to verify it.
-These properties are described below.
-
-The PP is responsible for defining a single or multiple CoTs for a data image.
-Unless otherwise specified, the data structures described in the following
-sections are populated by the PP statically.
-
-
-### 3.1 Describing the image parsing methods
-
-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
-format. A data image that represents a boot loader stage could be in raw binary
-or ELF format. The IPM supports three parsing methods. An image has to use one
-of the three methods described below. An IPL is responsible for interpreting a
-single parsing method. There has to be one IPL for every method used by the
-platform.
-
-1. Raw format: This format is effectively a nop as an image using this method
- is treated as being in raw binary format e.g. boot loader images used by ARM
- TF. This method should only be used by data images.
-
-2. X509V3 method: This method uses industry standards like X.509 to represent
- PKI certificates (authentication images). It is expected that open source
- libraries will be available which can be used to parse an image represented
- by this method. Such libraries can be used to write the corresponding IPL
- e.g. the X.509 parsing library code in mbed TLS.
-
-3. Platform defined method: This method caters for platform specific
- proprietary standards to represent authentication or data images. For
- example, The signature of a data image could be appended to the data image
- raw binary. A header could be prepended to the combined blob to specify the
- extents of each component. The platform will have to implement the
- corresponding IPL to interpret such a format.
-
-The following enum can be used to define these three methods.
-
-```
-typedef enum img_type_enum {
- IMG_RAW, /* Binary image */
- IMG_PLAT, /* Platform specific format */
- IMG_CERT, /* X509v3 certificate */
- IMG_MAX_TYPES,
-} img_type_t;
-```
-
-An IPL must provide functions with the following prototypes:
-
-```
-void init(void);
-int check_integrity(void *img, unsigned int img_len);
-int get_auth_param(const auth_param_type_desc_t *type_desc,
- void *img, unsigned int img_len,
- void **param, unsigned int *param_len);
-```
-
-An IPL for each type must be registered using the following macro:
-
-```
-REGISTER_IMG_PARSER_LIB(_type, _name, _init, _check_int, _get_param)
-```
-
-* `_type`: one of the types described above.
-* `_name`: a string containing the IPL name for debugging purposes.
-* `_init`: initialization function pointer.
-* `_check_int`: check image integrity function pointer.
-* `_get_param`: extract authentication parameter funcion pointer.
-
-The `init()` function will be used to initialize the IPL.
-
-The `check_integrity()` function is passed a pointer to the memory where the
-image has been loaded by the IO framework and the image length. It should ensure
-that the image is in the format corresponding to the parsing method and has not
-been tampered with. For example, RFC-2459 describes a validation sequence for an
-X.509 certificate.
-
-The `get_auth_param()` function is passed a parameter descriptor containing
-information about the parameter (`type_desc` and `cookie`) to identify and
-extract the data corresponding to that parameter from an image. This data will
-be used to verify either the current or the next image in the CoT sequence.
-
-Each image in the CoT will specify the parsing method it uses. This information
-will be used by the IPM to find the right parser descriptor for the image.
-
-
-### 3.2 Describing the authentication method(s)
-
-As part of the CoT, each image has to specify one or more authentication methods
-which will be used to verify it. As described in the Section "Authentication
-methods", there are three methods supported by the AM.
-
-```
-typedef enum {
- AUTH_METHOD_NONE,
- AUTH_METHOD_HASH,
- AUTH_METHOD_SIG,
- AUTH_METHOD_NUM
-} auth_method_type_t;
-```
-
-The AM defines the type of each parameter used by an authentication method. It
-uses this information to:
-
-1. Specify to the `get_auth_param()` function exported by the IPM, which
- parameter should be extracted from an image.
-
-2. Correctly marshall the parameters while calling the verification function
- exported by the CM and PP.
-
-3. Extract authentication parameters from a parent image in order to verify a
- child image e.g. to verify the certificate image, the public key has to be
- obtained from the parent image.
-
-```
-typedef enum {
- AUTH_PARAM_NONE,
- AUTH_PARAM_RAW_DATA, /* Raw image data */
- AUTH_PARAM_SIG, /* The image signature */
- AUTH_PARAM_SIG_ALG, /* The image signature algorithm */
- AUTH_PARAM_HASH, /* A hash (including the algorithm) */
- AUTH_PARAM_PUB_KEY, /* A public key */
-} auth_param_type_t;
-```
-
-The AM defines the following structure to identify an authentication parameter
-required to verify an image.
-
-```
-typedef struct auth_param_type_desc_s {
- auth_param_type_t type;
- void *cookie;
-} auth_param_type_desc_t;
-```
-
-`cookie` is used by the platform to specify additional information to the IPM
-which enables it to uniquely identify the parameter that should be extracted
-from an image. For example, the hash of a BL3x image in its corresponding
-content certificate is stored in an X509v3 custom extension field. An extension
-field can only be identified using an OID. In this case, the `cookie` could
-contain the pointer to the OID defined by the platform for the hash extension
-field while the `type` field could be set to `AUTH_PARAM_HASH`. A value of 0 for
-the `cookie` field means that it is not used.
-
-For each method, the AM defines a structure with the parameters required to
-verify the image.
-
-```
-/*
- * Parameters for authentication by hash matching
- */
-typedef struct auth_method_param_hash_s {
- auth_param_type_desc_t *data; /* Data to hash */
- auth_param_type_desc_t *hash; /* Hash to match with */
-} auth_method_param_hash_t;
-
-/*
- * Parameters for authentication by signature
- */
-typedef struct auth_method_param_sig_s {
- auth_param_type_desc_t *pk; /* Public key */
- auth_param_type_desc_t *sig; /* Signature to check */
- auth_param_type_desc_t *alg; /* Signature algorithm */
- auth_param_type_desc_t *tbs; /* Data signed */
-} auth_method_param_sig_t;
-
-```
-
-The AM defines the following structure to describe an authentication method for
-verifying an image
-
-```
-/*
- * Authentication method descriptor
- */
-typedef struct auth_method_desc_s {
- auth_method_type_t type;
- union {
- auth_method_param_hash_t hash;
- auth_method_param_sig_t sig;
- } param;
-} auth_method_desc_t;
-```
-
-Using the method type specified in the `type` field, the AM finds out what field
-needs to access within the `param` union.
-
-### 3.3 Storing Authentication parameters
-
-A parameter described by `auth_param_type_desc_t` to verify an image could be
-obtained from either the image itself or its parent image. The memory allocated
-for loading the parent image will be reused for loading the child image. Hence
-parameters which are obtained from the parent for verifying a child image need
-to have memory allocated for them separately where they can be stored. This
-memory must be statically allocated by the platform port.
-
-The AM defines the following structure to store the data corresponding to an
-authentication parameter.
-
-```
-typedef struct auth_param_data_desc_s {
- void *auth_param_ptr;
- unsigned int auth_param_len;
-} auth_param_data_desc_t;
-```
-
-The `auth_param_ptr` field is initialized by the platform. The `auth_param_len`
-field is used to specify the length of the data in the memory.
-
-For parameters that can be obtained from the child image itself, the IPM is
-responsible for populating the `auth_param_ptr` and `auth_param_len` fields
-while executing the `img_get_auth_param()` function.
-
-The AM defines the following structure to enable an image to describe the
-parameters that should be extracted from it and used to verify the next image
-(child) in a CoT.
-
-```
-typedef struct auth_param_desc_s {
- auth_param_type_desc_t type_desc;
- auth_param_data_desc_t data;
-} auth_param_desc_t;
-```
-
-### 3.4 Describing an image in a CoT
-
-An image in a CoT is a consolidation of the following aspects of a CoT described
-above.
-
-1. A unique identifier specified by the platform which allows the IO framework
- to locate the image in a FIP and load it in the memory reserved for the data
- image in the CoT.
-
-2. A parsing method which is used by the AM to find the appropriate IPM.
-
-3. Authentication methods and their parameters as described in the previous
- section. These are used to verify the current image.
-
-4. Parameters which are used to verify the next image in the current CoT. These
- parameters are specified only by authentication images and can be extracted
- from the current image once it has been verified.
-
-The following data structure describes an image in a CoT.
-```
-typedef struct auth_img_desc_s {
- unsigned int img_id;
- const struct auth_img_desc_s *parent;
- img_type_t img_type;
- auth_method_desc_t img_auth_methods[AUTH_METHOD_NUM];
- auth_param_desc_t authenticated_data[COT_MAX_VERIFIED_PARAMS];
-} auth_img_desc_t;
-```
-A CoT is defined as an array of `auth_image_desc_t` structures linked together
-by the `parent` field. Those nodes with no parent must be authenticated using
-the ROTPK stored in the platform.
-
-
-4. Implementation example
---------------------------
-
-This section is a detailed guide explaining a trusted boot implementation using
-the authentication framework. This example corresponds to the Applicative
-Functional Mode (AFM) as specified in the TBBR-Client document. It is
-recommended to read this guide along with the source code.
-
-### 4.1 The TBBR CoT
-
-The CoT can be found in `drivers/auth/tbbr/tbbr_cot.c`. This CoT consists of an
-array of image descriptors and it is registered in the framework using the macro
-`REGISTER_COT(cot_desc)`, where 'cot_desc' must be the name of the array
-(passing a pointer or any other type of indirection will cause the registration
-process to fail).
-
-The number of images participating in the boot process depends on the CoT. There
-is, however, a minimum set of images that are mandatory in the Trusted Firmware
-and thus all CoTs must present:
-
-* `BL2`
-* `SCP_BL2` (platform specific)
-* `BL31`
-* `BL32` (optional)
-* `BL33`
-
-The TBBR specifies the additional certificates that must accompany these images
-for a proper authentication. Details about the TBBR CoT may be found in the
-[Trusted Board Boot] document.
-
-Following the [Platform Porting Guide], a platform must provide unique
-identifiers for all the images and certificates that will be loaded during the
-boot process. If a platform is using the TBBR as a reference for trusted boot,
-these identifiers can be obtained from `include/common/tbbr/tbbr_img_def.h`.
-ARM platforms include this file in `include/plat/arm/common/arm_def.h`. Other
-platforms may also include this file or provide their own identifiers.
-
-**Important**: the authentication module uses these identifiers to index the
-CoT array, so the descriptors location in the array must match the identifiers.
-
-Each image descriptor must specify:
-
-* `img_id`: the corresponding image unique identifier defined by the platform.
-* `img_type`: the image parser module uses the image type to call the proper
- parsing library to check the image integrity and extract the required
- authentication parameters. Three types of images are currently supported:
- * `IMG_RAW`: image is a raw binary. No parsing functions are available,
- other than reading the whole image.
- * `IMG_PLAT`: image format is platform specific. The platform may use this
- type for custom images not directly supported by the authentication
- framework.
- * `IMG_CERT`: image is an x509v3 certificate.
-* `parent`: pointer to the parent image descriptor. The parent will contain
- the information required to authenticate the current image. If the parent
- is NULL, the authentication parameters will be obtained from the platform
- (i.e. the BL2 and Trusted Key certificates are signed with the ROT private
- key, whose public part is stored in the platform).
-* `img_auth_methods`: this array defines the authentication methods that must
- be checked to consider an image authenticated. Each method consists of a
- type and a list of parameter descriptors. A parameter descriptor consists of
- a type and a cookie which will point to specific information required to
- extract that parameter from the image (i.e. if the parameter is stored in an
- x509v3 extension, the cookie will point to the extension OID). Depending on
- the method type, a different number of parameters must be specified.
- Supported methods are:
- * `AUTH_METHOD_HASH`: the hash of the image must match the hash extracted
- from the parent image. The following parameter descriptors must be
- specified:
- * `data`: data to be hashed (obtained from current image)
- * `hash`: reference hash (obtained from parent image)
- * `AUTH_METHOD_SIG`: the image (usually a certificate) must be signed with
- the private key whose public part is extracted from the parent image (or
- the platform if the parent is NULL). The following parameter descriptors
- must be specified:
- * `pk`: the public key (obtained from parent image)
- * `sig`: the digital signature (obtained from current image)
- * `alg`: the signature algorithm used (obtained from current image)
- * `data`: the data to be signed (obtained from current image)
-* `authenticated_data`: this array indicates what authentication parameters
- must be extracted from an image once it has been authenticated. Each
- parameter consists of a parameter descriptor and the buffer address/size
- to store the parameter. The CoT is responsible for allocating the required
- memory to store the parameters.
-
-In the `tbbr_cot.c` file, a set of buffers are allocated to store the parameters
-extracted from the certificates. In the case of the TBBR CoT, these parameters
-are hashes and public keys. In DER format, an RSA-2048 public key requires 294
-bytes, and a hash requires 51 bytes. Depending on the CoT and the authentication
-process, some of the buffers may be reused at different stages during the boot.
-
-Next in that file, the parameter descriptors are defined. These descriptors will
-be used to extract the parameter data from the corresponding image.
-
-#### 4.1.1 Example: the BL31 Chain of Trust
-
-Four image descriptors form the BL31 Chain of Trust:
-
-```
-[TRUSTED_KEY_CERT_ID] = {
- .img_id = TRUSTED_KEY_CERT_ID,
- .img_type = IMG_CERT,
- .parent = NULL,
- .img_auth_methods = {
- [0] = {
- .type = AUTH_METHOD_SIG,
- .param.sig = {
- .pk = &subject_pk,
- .sig = &sig,
- .alg = &sig_alg,
- .data = &raw_data,
- }
- }
- },
- .authenticated_data = {
- [0] = {
- .type_desc = &trusted_world_pk,
- .data = {
- .ptr = (void *)trusted_world_pk_buf,
- .len = (unsigned int)PK_DER_LEN
- }
- },
- [1] = {
- .type_desc = &non_trusted_world_pk,
- .data = {
- .ptr = (void *)non_trusted_world_pk_buf,
- .len = (unsigned int)PK_DER_LEN
- }
- }
- }
-},
-[SOC_FW_KEY_CERT_ID] = {
- .img_id = SOC_FW_KEY_CERT_ID,
- .img_type = IMG_CERT,
- .parent = &cot_desc[TRUSTED_KEY_CERT_ID],
- .img_auth_methods = {
- [0] = {
- .type = AUTH_METHOD_SIG,
- .param.sig = {
- .pk = &trusted_world_pk,
- .sig = &sig,
- .alg = &sig_alg,
- .data = &raw_data,
- }
- }
- },
- .authenticated_data = {
- [0] = {
- .type_desc = &soc_fw_content_pk,
- .data = {
- .ptr = (void *)content_pk_buf,
- .len = (unsigned int)PK_DER_LEN
- }
- }
- }
-},
-[SOC_FW_CONTENT_CERT_ID] = {
- .img_id = SOC_FW_CONTENT_CERT_ID,
- .img_type = IMG_CERT,
- .parent = &cot_desc[SOC_FW_KEY_CERT_ID],
- .img_auth_methods = {
- [0] = {
- .type = AUTH_METHOD_SIG,
- .param.sig = {
- .pk = &soc_fw_content_pk,
- .sig = &sig,
- .alg = &sig_alg,
- .data = &raw_data,
- }
- }
- },
- .authenticated_data = {
- [0] = {
- .type_desc = &soc_fw_hash,
- .data = {
- .ptr = (void *)soc_fw_hash_buf,
- .len = (unsigned int)HASH_DER_LEN
- }
- }
- }
-},
-[BL31_IMAGE_ID] = {
- .img_id = BL31_IMAGE_ID,
- .img_type = IMG_RAW,
- .parent = &cot_desc[SOC_FW_CONTENT_CERT_ID],
- .img_auth_methods = {
- [0] = {
- .type = AUTH_METHOD_HASH,
- .param.hash = {
- .data = &raw_data,
- .hash = &soc_fw_hash,
- }
- }
- }
-}
-```
-The **Trusted Key certificate** is signed with the ROT private key and contains
-the Trusted World public key and the Non-Trusted World public key as x509v3
-extensions. This must be specified in the image descriptor using the
-`img_auth_methods` and `authenticated_data` arrays, respectively.
-
-The Trusted Key certificate is authenticated by checking its digital signature
-using the ROTPK. Four parameters are required to check a signature: the public
-key, the algorithm, the signature and the data that has been signed. Therefore,
-four parameter descriptors must be specified with the authentication method:
-
-* `subject_pk`: parameter descriptor of type `AUTH_PARAM_PUB_KEY`. This type
- is used to extract a public key from the parent image. If the cookie is an
- OID, the key is extracted from the corresponding x509v3 extension. If the
- cookie is NULL, the subject public key is retrieved. In this case, because
- the parent image is NULL, the public key is obtained from the platform
- (this key will be the ROTPK).
-* `sig`: parameter descriptor of type `AUTH_PARAM_SIG`. It is used to extract
- the signature from the certificate.
-* `sig_alg`: parameter descriptor of type `AUTH_PARAM_SIG`. It is used to
- extract the signature algorithm from the certificate.
-* `raw_data`: parameter descriptor of type `AUTH_PARAM_RAW_DATA`. It is used
- to extract the data to be signed from the certificate.
-
-Once the signature has been checked and the certificate authenticated, the
-Trusted World public key needs to be extracted from the certificate. A new entry
-is created in the `authenticated_data` array for that purpose. In that entry,
-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
-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
-parameter in the signature authentication method. The key is stored in the
-`plat_tz_world_pk_buf` buffer.
-
-The **BL31 Key certificate** is authenticated by checking its digital signature
-using the Trusted World public key obtained previously from the Trusted Key
-certificate. In the image descriptor, we specify a single authentication method
-by signature whose public key is the `tz_world_pk`. Once this certificate has
-been authenticated, we have to extract the BL31 public key, stored in the
-extension specified by `bl31_content_pk`. This key will be copied to the
-`plat_content_pk` buffer.
-
-The **BL31 certificate** is authenticated by checking its digital signature
-using the BL31 public key obtained previously from the BL31 Key certificate.
-We specify the authentication method using `bl31_content_pk` as public key.
-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`
-buffer.
-
-The **BL31 image** is authenticated by calculating its hash and matching it
-with the hash obtained from the BL31 certificate. The image descriptor contains
-a single authentication method by hash. The parameters to the hash method are
-the reference hash, `bl31_hash`, and the data to be hashed. In this case, it is
-the whole image, so we specify `raw_data`.
-
-### 4.2 The image parser library
-
-The image parser module relies on libraries to check the image integrity and
-extract the authentication parameters. The number and type of parser libraries
-depend on the images used in the CoT. Raw images do not need a library, so
-only an x509v3 library is required for the TBBR CoT.
-
-ARM platforms will use an x509v3 library based on mbed TLS. This library may be
-found in `drivers/auth/mbedtls/mbedtls_x509_parser.c`. It exports three
-functions:
-
-```
-void init(void);
-int check_integrity(void *img, unsigned int img_len);
-int get_auth_param(const auth_param_type_desc_t *type_desc,
- void *img, unsigned int img_len,
- void **param, unsigned int *param_len);
-```
-
-The library is registered in the framework using the macro
-`REGISTER_IMG_PARSER_LIB()`. Each time the image parser module needs to access
-an image of type `IMG_CERT`, it will call the corresponding function exported
-in this file.
-
-The build system must be updated to include the corresponding library and
-mbed TLS sources. ARM platforms use the `arm_common.mk` file to pull the
-sources.
-
-### 4.3 The cryptographic library
-
-The cryptographic module relies on a library to perform the required operations,
-i.e. verify a hash or a digital signature. ARM platforms will use a library
-based on mbed TLS, which can be found in
-`drivers/auth/mbedtls/mbedtls_crypto.c`. This library is registered in the
-authentication framework using the macro `REGISTER_CRYPTO_LIB()` and exports
-three functions:
-
-```
-void init(void);
-int verify_signature(void *data_ptr, unsigned int data_len,
- void *sig_ptr, unsigned int sig_len,
- void *sig_alg, unsigned int sig_alg_len,
- void *pk_ptr, unsigned int pk_len);
-int verify_hash(void *data_ptr, unsigned int data_len,
- void *digest_info_ptr, unsigned int digest_info_len);
-```
-
-The key algorithm (rsa, ecdsa) must be specified in the build system using the
-`TF_MBEDTLS_KEY_ALG` variable, so the Makefile can include the corresponding
-sources in the build.
-
-Note: If code size is a concern, the build option `MBEDTLS_SHA256_SMALLER` can
-be defined in the platform Makefile. It will make mbed TLS use an implementation
-of SHA-256 with smaller memory footprint (~1.5 KB less) but slower (~30%).
-
-- - - - - - - - - - - - - - - - - - - - - - - - - -
-
-_Copyright (c) 2015, ARM Limited and Contributors. All rights reserved._
-
-
-[Trusted Board Boot]: ./trusted-board-boot.md
-[Platform Porting Guide]: ./porting-guide.md
diff --git a/docs/auth-framework.rst b/docs/auth-framework.rst
new file mode 100644
index 0000000..765d9f8
--- /dev/null
+++ b/docs/auth-framework.rst
@@ -0,0 +1,937 @@
+Abstracting a Chain of Trust
+============================
+
+
+.. section-numbering::
+ :suffix: .
+
+.. contents::
+
+The aim of this document is to describe the authentication framework implemented
+in the Trusted Firmware. This framework fulfills the following requirements:
+
+#. It should be possible for a platform port to specify the Chain of Trust in
+ terms of certificate hierarchy and the mechanisms used to verify a
+ particular image/certificate.
+
+#. The framework should distinguish between:
+
+ - The mechanism used to encode and transport information, e.g. DER encoded
+ X.509v3 certificates to ferry Subject Public Keys, hashes and non-volatile
+ counters.
+
+ - The mechanism used to verify the transported information i.e. the
+ cryptographic libraries.
+
+The framework has been designed following a modular approach illustrated in the
+next diagram:
+
+::
+
+ +---------------+---------------+------------+
+ | Trusted | Trusted | Trusted |
+ | Firmware | Firmware | Firmware |
+ | Generic | IO Framework | Platform |
+ | Code i.e. | (IO) | Port |
+ | BL1/BL2 (GEN) | | (PP) |
+ +---------------+---------------+------------+
+ ^ ^ ^
+ | | |
+ v v v
+ +-----------+ +-----------+ +-----------+
+ | | | | | Image |
+ | Crypto | | Auth | | Parser |
+ | Module |<->| Module |<->| Module |
+ | (CM) | | (AM) | | (IPM) |
+ | | | | | |
+ +-----------+ +-----------+ +-----------+
+ ^ ^
+ | |
+ v v
+ +----------------+ +-----------------+
+ | Cryptographic | | Image Parser |
+ | Libraries (CL) | | Libraries (IPL) |
+ +----------------+ +-----------------+
+ | |
+ | |
+ | |
+ v v
+ +-----------------+
+ | Misc. Libs e.g. |
+ | ASN.1 decoder |
+ | |
+ +-----------------+
+
+ DIAGRAM 1.
+
+This document describes the inner details of the authentication framework and
+the abstraction mechanisms available to specify a Chain of Trust.
+
+Framework design
+----------------
+
+This section describes some aspects of the framework design and the rationale
+behind them. These aspects are key to verify a Chain of Trust.
+
+Chain of Trust
+~~~~~~~~~~~~~~
+
+A CoT is basically a sequence of authentication images which usually starts with
+a root of trust and culminates in a single data image. The following diagram
+illustrates how this maps to a CoT for the BL31 image described in the
+TBBR-Client specification.
+
+::
+
+ +------------------+ +-------------------+
+ | ROTPK/ROTPK Hash |------>| Trusted Key |
+ +------------------+ | Certificate |
+ | (Auth Image) |
+ /+-------------------+
+ / |
+ / |
+ / |
+ / |
+ L v
+ +------------------+ +-------------------+
+ | Trusted World |------>| BL31 Key |
+ | Public Key | | Certificate |
+ +------------------+ | (Auth Image) |
+ +-------------------+
+ / |
+ / |
+ / |
+ / |
+ / v
+ +------------------+ L +-------------------+
+ | BL31 Content |------>| BL31 Content |
+ | Certificate PK | | Certificate |
+ +------------------+ | (Auth Image) |
+ +-------------------+
+ / |
+ / |
+ / |
+ / |
+ / v
+ +------------------+ L +-------------------+
+ | BL31 Hash |------>| BL31 Image |
+ | | | (Data Image) |
+ +------------------+ | |
+ +-------------------+
+
+ DIAGRAM 2.
+
+The root of trust is usually a public key (ROTPK) that has been burnt in the
+platform and cannot be modified.
+
+Image types
+~~~~~~~~~~~
+
+Images in a CoT are categorised as authentication and data images. An
+authentication image contains information to authenticate a data image or
+another authentication image. A data image is usually a boot loader binary, but
+it could be any other data that requires authentication.
+
+Component responsibilities
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For every image in a Chain of Trust, the following high level operations are
+performed to verify it:
+
+#. Allocate memory for the image either statically or at runtime.
+
+#. Identify the image and load it in the allocated memory.
+
+#. Check the integrity of the image as per its type.
+
+#. Authenticate the image as per the cryptographic algorithms used.
+
+#. If the image is an authentication image, extract the information that will
+ be used to authenticate the next image in the CoT.
+
+In Diagram 1, each component is responsible for one or more of these operations.
+The responsibilities are briefly described below.
+
+TF Generic code and IO framework (GEN/IO)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These components are responsible for initiating the authentication process for a
+particular image in BL1 or BL2. For each BL image that requires authentication,
+the Generic code asks recursively the Authentication module what is the parent
+image until either an authenticated image or the ROT is reached. Then the
+Generic code calls the IO framewotk to load the image and calls the
+Authentication module to authenticate it, following the CoT from ROT to Image.
+
+TF Platform Port (PP)
+^^^^^^^^^^^^^^^^^^^^^
+
+The platform is responsible for:
+
+#. Specifying the CoT for each image that needs to be authenticated. Details of
+ how a CoT can be specified by the platform are explained later. The platform
+ also specifies the authentication methods and the parsing method used for
+ each image.
+
+#. Statically allocating memory for each parameter in each image which is
+ used for verifying the CoT, e.g. memory for public keys, hashes etc.
+
+#. Providing the ROTPK or a hash of it.
+
+#. Providing additional information to the IPM to enable it to identify and
+ extract authentication parameters contained in an image, e.g. if the
+ parameters are stored as X509v3 extensions, the corresponding OID must be
+ provided.
+
+#. Fulfill any other memory requirements of the IPM and the CM (not currently
+ described in this document).
+
+#. Export functions to verify an image which uses an authentication method that
+ cannot be interpreted by the CM, e.g. if an image has to be verified using a
+ NV counter, then the value of the counter to compare with can only be
+ provided by the platform.
+
+#. Export a custom IPM if a proprietary image format is being used (described
+ later).
+
+Authentication Module (AM)
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is responsible for:
+
+#. Providing the necessary abstraction mechanisms to describe a CoT. Amongst
+ other things, the authentication and image parsing methods must be specified
+ by the PP in the CoT.
+
+#. Verifying the CoT passed by GEN by utilising functionality exported by the
+ PP, IPM and CM.
+
+#. Tracking which images have been verified. In case an image is a part of
+ multiple CoTs then it should be verified only once e.g. the Trusted World
+ Key Certificate in the TBBR-Client spec. contains information to verify
+ SCP\_BL2, BL31, BL32 each of which have a separate CoT. (This
+ responsibility has not been described in this document but should be
+ trivial to implement).
+
+#. Reusing memory meant for a data image to verify authentication images e.g.
+ in the CoT described in Diagram 2, each certificate can be loaded and
+ verified in the memory reserved by the platform for the BL31 image. By the
+ time BL31 (the data image) is loaded, all information to authenticate it
+ will have been extracted from the parent image i.e. BL31 content
+ certificate. It is assumed that the size of an authentication image will
+ never exceed the size of a data image. It should be possible to verify this
+ at build time using asserts.
+
+Cryptographic Module (CM)
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The CM is responsible for providing an API to:
+
+#. Verify a digital signature.
+#. Verify a hash.
+
+The CM does not include any cryptography related code, but it relies on an
+external library to perform the cryptographic operations. A Crypto-Library (CL)
+linking the CM and the external library must be implemented. The following
+functions must be provided by the CL:
+
+.. code:: c
+
+ void (*init)(void);
+ int (*verify_signature)(void *data_ptr, unsigned int data_len,
+ void *sig_ptr, unsigned int sig_len,
+ void *sig_alg, unsigned int sig_alg_len,
+ void *pk_ptr, unsigned int pk_len);
+ int (*verify_hash)(void *data_ptr, unsigned int data_len,
+ void *digest_info_ptr, unsigned int digest_info_len);
+
+These functions are registered in the CM using the macro:
+
+.. 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.
+
+Image Parser Module (IPM)
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The IPM is responsible for:
+
+#. Checking the integrity of each image loaded by the IO framework.
+#. Extracting parameters used for authenticating an image based upon a
+ description provided by the platform in the CoT descriptor.
+
+Images may have different formats (for example, authentication images could be
+x509v3 certificates, signed ELF files or any other platform specific format).
+The IPM allows to register an Image Parser Library (IPL) for every image format
+used in the CoT. This library must implement the specific methods to parse the
+image. The IPM obtains the image format from the CoT and calls the right IPL to
+check the image integrity and extract the authentication parameters.
+
+See Section "Describing the image parsing methods" for more details about the
+mechanism the IPM provides to define and register IPLs.
+
+Authentication methods
+~~~~~~~~~~~~~~~~~~~~~~
+
+The AM supports the following authentication methods:
+
+#. Hash
+#. Digital signature
+
+The platform may specify these methods in the CoT in case it decides to define
+a custom CoT instead of reusing a predefined one.
+
+If a data image uses multiple methods, then all the methods must be a part of
+the same CoT. The number and type of parameters are method specific. These
+parameters should be obtained from the parent image using the IPM.
+
+#. Hash
+
+ Parameters:
+
+ #. A pointer to data to hash
+ #. Length of the data
+ #. A pointer to the hash
+ #. Length of the hash
+
+ The hash will be represented by the DER encoding of the following ASN.1
+ type:
+
+ ::
+
+ DigestInfo ::= SEQUENCE {
+ digestAlgorithm DigestAlgorithmIdentifier,
+ digest Digest
+ }
+
+ This ASN.1 structure makes it possible to remove any assumption about the
+ type of hash algorithm used as this information accompanies the hash. This
+ should allow the Cryptography Library (CL) to support multiple hash
+ algorithm implementations.
+
+#. Digital Signature
+
+ Parameters:
+
+ #. A pointer to data to sign
+ #. Length of the data
+ #. Public Key Algorithm
+ #. Public Key value
+ #. Digital Signature Algorithm
+ #. Digital Signature value
+
+ The Public Key parameters will be represented by the DER encoding of the
+ following ASN.1 type:
+
+ ::
+
+ SubjectPublicKeyInfo ::= SEQUENCE {
+ algorithm AlgorithmIdentifier{PUBLIC-KEY,{PublicKeyAlgorithms}},
+ subjectPublicKey BIT STRING }
+
+ The Digital Signature Algorithm will be represented by the DER encoding of
+ the following ASN.1 types.
+
+ ::
+
+ AlgorithmIdentifier {ALGORITHM:IOSet } ::= SEQUENCE {
+ algorithm ALGORITHM.&id({IOSet}),
+ parameters ALGORITHM.&Type({IOSet}{@algorithm}) OPTIONAL
+ }
+
+ The digital signature will be represented by:
+
+ ::
+
+ signature ::= BIT STRING
+
+The authentication framework will use the image descriptor to extract all the
+information related to authentication.
+
+Specifying a Chain of Trust
+---------------------------
+
+A CoT can be described as a set of image descriptors linked together in a
+particular order. The order dictates the sequence in which they must be
+verified. Each image has a set of properties which allow the AM to verify it.
+These properties are described below.
+
+The PP is responsible for defining a single or multiple CoTs for a data image.
+Unless otherwise specified, the data structures described in the following
+sections are populated by the PP statically.
+
+Describing the image parsing methods
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The parsing method refers to the format of a particular image. For example, an
+authentication image that represents a certificate could be in the X.509v3
+format. A data image that represents a boot loader stage could be in raw binary
+or ELF format. The IPM supports three parsing methods. An image has to use one
+of the three methods described below. An IPL is responsible for interpreting a
+single parsing method. There has to be one IPL for every method used by the
+platform.
+
+#. Raw format: This format is effectively a nop as an image using this method
+ is treated as being in raw binary format e.g. boot loader images used by ARM
+ TF. This method should only be used by data images.
+
+#. X509V3 method: This method uses industry standards like X.509 to represent
+ PKI certificates (authentication images). It is expected that open source
+ libraries will be available which can be used to parse an image represented
+ by this method. Such libraries can be used to write the corresponding IPL
+ e.g. the X.509 parsing library code in mbed TLS.
+
+#. Platform defined method: This method caters for platform specific
+ proprietary standards to represent authentication or data images. For
+ example, The signature of a data image could be appended to the data image
+ raw binary. A header could be prepended to the combined blob to specify the
+ extents of each component. The platform will have to implement the
+ corresponding IPL to interpret such a format.
+
+The following enum can be used to define these three methods.
+
+.. code:: c
+
+ typedef enum img_type_enum {
+ IMG_RAW, /* Binary image */
+ IMG_PLAT, /* Platform specific format */
+ IMG_CERT, /* X509v3 certificate */
+ IMG_MAX_TYPES,
+ } img_type_t;
+
+An IPL must provide functions with the following prototypes:
+
+.. code:: c
+
+ void init(void);
+ int check_integrity(void *img, unsigned int img_len);
+ int get_auth_param(const auth_param_type_desc_t *type_desc,
+ void *img, unsigned int img_len,
+ void **param, unsigned int *param_len);
+
+An IPL for each type must be registered using the following macro:
+
+::
+
+ REGISTER_IMG_PARSER_LIB(_type, _name, _init, _check_int, _get_param)
+
+- ``_type``: one of the types described above.
+- ``_name``: a string containing the IPL name for debugging purposes.
+- ``_init``: initialization function pointer.
+- ``_check_int``: check image integrity function pointer.
+- ``_get_param``: extract authentication parameter funcion pointer.
+
+The ``init()`` function will be used to initialize the IPL.
+
+The ``check_integrity()`` function is passed a pointer to the memory where the
+image has been loaded by the IO framework and the image length. It should ensure
+that the image is in the format corresponding to the parsing method and has not
+been tampered with. For example, RFC-2459 describes a validation sequence for an
+X.509 certificate.
+
+The ``get_auth_param()`` function is passed a parameter descriptor containing
+information about the parameter (``type_desc`` and ``cookie``) to identify and
+extract the data corresponding to that parameter from an image. This data will
+be used to verify either the current or the next image in the CoT sequence.
+
+Each image in the CoT will specify the parsing method it uses. This information
+will be used by the IPM to find the right parser descriptor for the image.
+
+Describing the authentication method(s)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As part of the CoT, each image has to specify one or more authentication methods
+which will be used to verify it. As described in the Section "Authentication
+methods", there are three methods supported by the AM.
+
+.. code:: c
+
+ typedef enum {
+ AUTH_METHOD_NONE,
+ AUTH_METHOD_HASH,
+ AUTH_METHOD_SIG,
+ AUTH_METHOD_NUM
+ } auth_method_type_t;
+
+The AM defines the type of each parameter used by an authentication method. It
+uses this information to:
+
+#. Specify to the ``get_auth_param()`` function exported by the IPM, which
+ parameter should be extracted from an image.
+
+#. Correctly marshall the parameters while calling the verification function
+ exported by the CM and PP.
+
+#. Extract authentication parameters from a parent image in order to verify a
+ child image e.g. to verify the certificate image, the public key has to be
+ obtained from the parent image.
+
+.. code:: c
+
+ typedef enum {
+ AUTH_PARAM_NONE,
+ AUTH_PARAM_RAW_DATA, /* Raw image data */
+ AUTH_PARAM_SIG, /* The image signature */
+ AUTH_PARAM_SIG_ALG, /* The image signature algorithm */
+ AUTH_PARAM_HASH, /* A hash (including the algorithm) */
+ AUTH_PARAM_PUB_KEY, /* A public key */
+ } auth_param_type_t;
+
+The AM defines the following structure to identify an authentication parameter
+required to verify an image.
+
+.. code:: c
+
+ typedef struct auth_param_type_desc_s {
+ auth_param_type_t type;
+ void *cookie;
+ } auth_param_type_desc_t;
+
+``cookie`` is used by the platform to specify additional information to the IPM
+which enables it to uniquely identify the parameter that should be extracted
+from an image. For example, the hash of a BL3x image in its corresponding
+content certificate is stored in an X509v3 custom extension field. An extension
+field can only be identified using an OID. In this case, the ``cookie`` could
+contain the pointer to the OID defined by the platform for the hash extension
+field while the ``type`` field could be set to ``AUTH_PARAM_HASH``. A value of 0 for
+the ``cookie`` field means that it is not used.
+
+For each method, the AM defines a structure with the parameters required to
+verify the image.
+
+.. code:: c
+
+ /*
+ * Parameters for authentication by hash matching
+ */
+ typedef struct auth_method_param_hash_s {
+ auth_param_type_desc_t *data; /* Data to hash */
+ auth_param_type_desc_t *hash; /* Hash to match with */
+ } auth_method_param_hash_t;
+
+ /*
+ * Parameters for authentication by signature
+ */
+ typedef struct auth_method_param_sig_s {
+ auth_param_type_desc_t *pk; /* Public key */
+ auth_param_type_desc_t *sig; /* Signature to check */
+ auth_param_type_desc_t *alg; /* Signature algorithm */
+ auth_param_type_desc_t *tbs; /* Data signed */
+ } auth_method_param_sig_t;
+
+The AM defines the following structure to describe an authentication method for
+verifying an image
+
+.. code:: c
+
+ /*
+ * Authentication method descriptor
+ */
+ typedef struct auth_method_desc_s {
+ auth_method_type_t type;
+ union {
+ auth_method_param_hash_t hash;
+ auth_method_param_sig_t sig;
+ } param;
+ } auth_method_desc_t;
+
+Using the method type specified in the ``type`` field, the AM finds out what field
+needs to access within the ``param`` union.
+
+Storing Authentication parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A parameter described by ``auth_param_type_desc_t`` to verify an image could be
+obtained from either the image itself or its parent image. The memory allocated
+for loading the parent image will be reused for loading the child image. Hence
+parameters which are obtained from the parent for verifying a child image need
+to have memory allocated for them separately where they can be stored. This
+memory must be statically allocated by the platform port.
+
+The AM defines the following structure to store the data corresponding to an
+authentication parameter.
+
+.. code:: c
+
+ typedef struct auth_param_data_desc_s {
+ void *auth_param_ptr;
+ unsigned int auth_param_len;
+ } auth_param_data_desc_t;
+
+The ``auth_param_ptr`` field is initialized by the platform. The ``auth_param_len``
+field is used to specify the length of the data in the memory.
+
+For parameters that can be obtained from the child image itself, the IPM is
+responsible for populating the ``auth_param_ptr`` and ``auth_param_len`` fields
+while executing the ``img_get_auth_param()`` function.
+
+The AM defines the following structure to enable an image to describe the
+parameters that should be extracted from it and used to verify the next image
+(child) in a CoT.
+
+.. code:: c
+
+ typedef struct auth_param_desc_s {
+ auth_param_type_desc_t type_desc;
+ auth_param_data_desc_t data;
+ } auth_param_desc_t;
+
+Describing an image in a CoT
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+An image in a CoT is a consolidation of the following aspects of a CoT described
+above.
+
+#. A unique identifier specified by the platform which allows the IO framework
+ to locate the image in a FIP and load it in the memory reserved for the data
+ image in the CoT.
+
+#. A parsing method which is used by the AM to find the appropriate IPM.
+
+#. Authentication methods and their parameters as described in the previous
+ section. These are used to verify the current image.
+
+#. Parameters which are used to verify the next image in the current CoT. These
+ parameters are specified only by authentication images and can be extracted
+ from the current image once it has been verified.
+
+The following data structure describes an image in a CoT.
+
+.. code:: c
+
+ typedef struct auth_img_desc_s {
+ unsigned int img_id;
+ const struct auth_img_desc_s *parent;
+ img_type_t img_type;
+ auth_method_desc_t img_auth_methods[AUTH_METHOD_NUM];
+ auth_param_desc_t authenticated_data[COT_MAX_VERIFIED_PARAMS];
+ } auth_img_desc_t;
+
+A CoT is defined as an array of ``auth_image_desc_t`` structures linked together
+by the ``parent`` field. Those nodes with no parent must be authenticated using
+the ROTPK stored in the platform.
+
+Implementation example
+----------------------
+
+This section is a detailed guide explaining a trusted boot implementation using
+the authentication framework. This example corresponds to the Applicative
+Functional Mode (AFM) as specified in the TBBR-Client document. It is
+recommended to read this guide along with the source code.
+
+The TBBR CoT
+~~~~~~~~~~~~
+
+The CoT can be found in ``drivers/auth/tbbr/tbbr_cot.c``. This CoT consists of an
+array of image descriptors and it is registered in the framework using the macro
+``REGISTER_COT(cot_desc)``, where 'cot\_desc' must be the name of the array
+(passing a pointer or any other type of indirection will cause the registration
+process to fail).
+
+The number of images participating in the boot process depends on the CoT. There
+is, however, a minimum set of images that are mandatory in the Trusted Firmware
+and thus all CoTs must present:
+
+- ``BL2``
+- ``SCP_BL2`` (platform specific)
+- ``BL31``
+- ``BL32`` (optional)
+- ``BL33``
+
+The TBBR specifies the additional certificates that must accompany these images
+for a proper authentication. Details about the TBBR CoT may be found in the
+`Trusted Board Boot`_ document.
+
+Following the `Platform Porting Guide`_, a platform must provide unique
+identifiers for all the images and certificates that will be loaded during the
+boot process. If a platform is using the TBBR as a reference for trusted boot,
+these identifiers can be obtained from ``include/common/tbbr/tbbr_img_def.h``.
+ARM platforms include this file in ``include/plat/arm/common/arm_def.h``. Other
+platforms may also include this file or provide their own identifiers.
+
+**Important**: the authentication module uses these identifiers to index the
+CoT array, so the descriptors location in the array must match the identifiers.
+
+Each image descriptor must specify:
+
+- ``img_id``: the corresponding image unique identifier defined by the platform.
+- ``img_type``: the image parser module uses the image type to call the proper
+ parsing library to check the image integrity and extract the required
+ authentication parameters. Three types of images are currently supported:
+
+ - ``IMG_RAW``: image is a raw binary. No parsing functions are available,
+ other than reading the whole image.
+ - ``IMG_PLAT``: image format is platform specific. The platform may use this
+ type for custom images not directly supported by the authentication
+ framework.
+ - ``IMG_CERT``: image is an x509v3 certificate.
+
+- ``parent``: pointer to the parent image descriptor. The parent will contain
+ the information required to authenticate the current image. If the parent
+ is NULL, the authentication parameters will be obtained from the platform
+ (i.e. the BL2 and Trusted Key certificates are signed with the ROT private
+ key, whose public part is stored in the platform).
+- ``img_auth_methods``: this array defines the authentication methods that must
+ be checked to consider an image authenticated. Each method consists of a
+ type and a list of parameter descriptors. A parameter descriptor consists of
+ a type and a cookie which will point to specific information required to
+ extract that parameter from the image (i.e. if the parameter is stored in an
+ x509v3 extension, the cookie will point to the extension OID). Depending on
+ the method type, a different number of parameters must be specified.
+ Supported methods are:
+
+ - ``AUTH_METHOD_HASH``: the hash of the image must match the hash extracted
+ from the parent image. The following parameter descriptors must be
+ specified:
+
+ - ``data``: data to be hashed (obtained from current image)
+ - ``hash``: reference hash (obtained from parent image)
+
+ - ``AUTH_METHOD_SIG``: the image (usually a certificate) must be signed with
+ the private key whose public part is extracted from the parent image (or
+ the platform if the parent is NULL). The following parameter descriptors
+ must be specified:
+
+ - ``pk``: the public key (obtained from parent image)
+ - ``sig``: the digital signature (obtained from current image)
+ - ``alg``: the signature algorithm used (obtained from current image)
+ - ``data``: the data to be signed (obtained from current image)
+
+- ``authenticated_data``: this array indicates what authentication parameters
+ must be extracted from an image once it has been authenticated. Each
+ parameter consists of a parameter descriptor and the buffer address/size
+ to store the parameter. The CoT is responsible for allocating the required
+ memory to store the parameters.
+
+In the ``tbbr_cot.c`` file, a set of buffers are allocated to store the parameters
+extracted from the certificates. In the case of the TBBR CoT, these parameters
+are hashes and public keys. In DER format, an RSA-2048 public key requires 294
+bytes, and a hash requires 51 bytes. Depending on the CoT and the authentication
+process, some of the buffers may be reused at different stages during the boot.
+
+Next in that file, the parameter descriptors are defined. These descriptors will
+be used to extract the parameter data from the corresponding image.
+
+Example: the BL31 Chain of Trust
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Four image descriptors form the BL31 Chain of Trust:
+
+.. code:: asm
+
+ [TRUSTED_KEY_CERT_ID] = {
+ .img_id = TRUSTED_KEY_CERT_ID,
+ .img_type = IMG_CERT,
+ .parent = NULL,
+ .img_auth_methods = {
+ [0] = {
+ .type = AUTH_METHOD_SIG,
+ .param.sig = {
+ .pk = &subject_pk,
+ .sig = &sig,
+ .alg = &sig_alg,
+ .data = &raw_data,
+ }
+ }
+ },
+ .authenticated_data = {
+ [0] = {
+ .type_desc = &trusted_world_pk,
+ .data = {
+ .ptr = (void *)trusted_world_pk_buf,
+ .len = (unsigned int)PK_DER_LEN
+ }
+ },
+ [1] = {
+ .type_desc = &non_trusted_world_pk,
+ .data = {
+ .ptr = (void *)non_trusted_world_pk_buf,
+ .len = (unsigned int)PK_DER_LEN
+ }
+ }
+ }
+ },
+ [SOC_FW_KEY_CERT_ID] = {
+ .img_id = SOC_FW_KEY_CERT_ID,
+ .img_type = IMG_CERT,
+ .parent = &cot_desc[TRUSTED_KEY_CERT_ID],
+ .img_auth_methods = {
+ [0] = {
+ .type = AUTH_METHOD_SIG,
+ .param.sig = {
+ .pk = &trusted_world_pk,
+ .sig = &sig,
+ .alg = &sig_alg,
+ .data = &raw_data,
+ }
+ }
+ },
+ .authenticated_data = {
+ [0] = {
+ .type_desc = &soc_fw_content_pk,
+ .data = {
+ .ptr = (void *)content_pk_buf,
+ .len = (unsigned int)PK_DER_LEN
+ }
+ }
+ }
+ },
+ [SOC_FW_CONTENT_CERT_ID] = {
+ .img_id = SOC_FW_CONTENT_CERT_ID,
+ .img_type = IMG_CERT,
+ .parent = &cot_desc[SOC_FW_KEY_CERT_ID],
+ .img_auth_methods = {
+ [0] = {
+ .type = AUTH_METHOD_SIG,
+ .param.sig = {
+ .pk = &soc_fw_content_pk,
+ .sig = &sig,
+ .alg = &sig_alg,
+ .data = &raw_data,
+ }
+ }
+ },
+ .authenticated_data = {
+ [0] = {
+ .type_desc = &soc_fw_hash,
+ .data = {
+ .ptr = (void *)soc_fw_hash_buf,
+ .len = (unsigned int)HASH_DER_LEN
+ }
+ }
+ }
+ },
+ [BL31_IMAGE_ID] = {
+ .img_id = BL31_IMAGE_ID,
+ .img_type = IMG_RAW,
+ .parent = &cot_desc[SOC_FW_CONTENT_CERT_ID],
+ .img_auth_methods = {
+ [0] = {
+ .type = AUTH_METHOD_HASH,
+ .param.hash = {
+ .data = &raw_data,
+ .hash = &soc_fw_hash,
+ }
+ }
+ }
+ }
+
+The **Trusted Key certificate** is signed with the ROT private key and contains
+the Trusted World public key and the Non-Trusted World public key as x509v3
+extensions. This must be specified in the image descriptor using the
+``img_auth_methods`` and ``authenticated_data`` arrays, respectively.
+
+The Trusted Key certificate is authenticated by checking its digital signature
+using the ROTPK. Four parameters are required to check a signature: the public
+key, the algorithm, the signature and the data that has been signed. Therefore,
+four parameter descriptors must be specified with the authentication method:
+
+- ``subject_pk``: parameter descriptor of type ``AUTH_PARAM_PUB_KEY``. This type
+ is used to extract a public key from the parent image. If the cookie is an
+ OID, the key is extracted from the corresponding x509v3 extension. If the
+ cookie is NULL, the subject public key is retrieved. In this case, because
+ the parent image is NULL, the public key is obtained from the platform
+ (this key will be the ROTPK).
+- ``sig``: parameter descriptor of type ``AUTH_PARAM_SIG``. It is used to extract
+ the signature from the certificate.
+- ``sig_alg``: parameter descriptor of type ``AUTH_PARAM_SIG``. It is used to
+ extract the signature algorithm from the certificate.
+- ``raw_data``: parameter descriptor of type ``AUTH_PARAM_RAW_DATA``. It is used
+ to extract the data to be signed from the certificate.
+
+Once the signature has been checked and the certificate authenticated, the
+Trusted World public key needs to be extracted from the certificate. A new entry
+is created in the ``authenticated_data`` array for that purpose. In that entry,
+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
+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
+parameter in the signature authentication method. The key is stored in the
+``plat_tz_world_pk_buf`` buffer.
+
+The **BL31 Key certificate** is authenticated by checking its digital signature
+using the Trusted World public key obtained previously from the Trusted Key
+certificate. In the image descriptor, we specify a single authentication method
+by signature whose public key is the ``tz_world_pk``. Once this certificate has
+been authenticated, we have to extract the BL31 public key, stored in the
+extension specified by ``bl31_content_pk``. This key will be copied to the
+``plat_content_pk`` buffer.
+
+The **BL31 certificate** is authenticated by checking its digital signature
+using the BL31 public key obtained previously from the BL31 Key certificate.
+We specify the authentication method using ``bl31_content_pk`` as public key.
+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``
+buffer.
+
+The **BL31 image** is authenticated by calculating its hash and matching it
+with the hash obtained from the BL31 certificate. The image descriptor contains
+a single authentication method by hash. The parameters to the hash method are
+the reference hash, ``bl31_hash``, and the data to be hashed. In this case, it is
+the whole image, so we specify ``raw_data``.
+
+The image parser library
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The image parser module relies on libraries to check the image integrity and
+extract the authentication parameters. The number and type of parser libraries
+depend on the images used in the CoT. Raw images do not need a library, so
+only an x509v3 library is required for the TBBR CoT.
+
+ARM platforms will use an x509v3 library based on mbed TLS. This library may be
+found in ``drivers/auth/mbedtls/mbedtls_x509_parser.c``. It exports three
+functions:
+
+.. code:: c
+
+ void init(void);
+ int check_integrity(void *img, unsigned int img_len);
+ int get_auth_param(const auth_param_type_desc_t *type_desc,
+ void *img, unsigned int img_len,
+ void **param, unsigned int *param_len);
+
+The library is registered in the framework using the macro
+``REGISTER_IMG_PARSER_LIB()``. Each time the image parser module needs to access
+an image of type ``IMG_CERT``, it will call the corresponding function exported
+in this file.
+
+The build system must be updated to include the corresponding library and
+mbed TLS sources. ARM platforms use the ``arm_common.mk`` file to pull the
+sources.
+
+The cryptographic library
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The cryptographic module relies on a library to perform the required operations,
+i.e. verify a hash or a digital signature. ARM platforms will use a library
+based on mbed TLS, which can be found in
+``drivers/auth/mbedtls/mbedtls_crypto.c``. This library is registered in the
+authentication framework using the macro ``REGISTER_CRYPTO_LIB()`` and exports
+three functions:
+
+.. code:: c
+
+ void init(void);
+ int verify_signature(void *data_ptr, unsigned int data_len,
+ void *sig_ptr, unsigned int sig_len,
+ void *sig_alg, unsigned int sig_alg_len,
+ void *pk_ptr, unsigned int pk_len);
+ int verify_hash(void *data_ptr, unsigned int data_len,
+ void *digest_info_ptr, unsigned int digest_info_len);
+
+The key algorithm (rsa, ecdsa) must be specified in the build system using the
+``TF_MBEDTLS_KEY_ALG`` variable, so the Makefile can include the corresponding
+sources in the build.
+
+Note: If code size is a concern, the build option ``MBEDTLS_SHA256_SMALLER`` can
+be defined in the platform Makefile. It will make mbed TLS use an implementation
+of SHA-256 with smaller memory footprint (~1.5 KB less) but slower (~30%).
+
+--------------
+
+*Copyright (c) 2015, ARM Limited and Contributors. All rights reserved.*
+
+.. _Trusted Board Boot: ./trusted-board-boot.rst
+.. _Platform Porting Guide: ./porting-guide.rst
diff --git a/docs/change-log.md b/docs/change-log.md
deleted file mode 100644
index 4eb1254..0000000
--- a/docs/change-log.md
+++ /dev/null
@@ -1,1103 +0,0 @@
-
-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
diff --git a/docs/change-log.rst b/docs/change-log.rst
new file mode 100644
index 0000000..708ec05
--- /dev/null
+++ b/docs/change-log.rst
@@ -0,0 +1,1382 @@
+
+.. section-numbering::
+ :suffix: .
+
+.. contents::
+
+ARM Trusted Firmware - version 1.4
+==================================
+
+New features
+------------
+
+- Enabled support for platforms with hardware assisted coherency.
+
+ A new build option HW_ASSISTED_COHERENCY allows platforms to take advantage
+ of the following optimisations:
+
+ - Skip performing cache maintenance during power-up and power-down.
+
+ - Use spin-locks instead of bakery locks.
+
+ - Enable data caches early on warm-booted CPUs.
+
+- Added support for Cortex-A75 and Cortex-A55 processors.
+
+ Both Cortex-A75 and Cortex-A55 processors use the ARM DynamIQ Shared Unit
+ (DSU). The power-down and power-up sequences are therefore mostly managed in
+ hardware, reducing complexity of the software operations.
+
+- Introduced ARM GIC-600 driver.
+
+ ARM GIC-600 IP complies with ARM GICv3 architecture. For FVP platforms, the
+ GIC-600 driver is chosen when FVP_USE_GIC_DRIVER is set to FVP_GIC600.
+
+- Updated GICv3 support:
+
+ - Introduced power management APIs for GICv3 Redistributor. These APIs
+ allow platforms to power down the Redistributor during CPU power on/off.
+ Requires the GICv3 implementations to have power management operations.
+
+ Implemented the power management APIs for FVP.
+
+ - GIC driver data is flushed by the primary CPU so that secondary CPU do
+ not read stale GIC data.
+
+- Added support for ARM System Control and Management Interface v1.0 (SCMI).
+
+ The SCMI driver implements the power domain management and system power
+ management protocol of the SCMI specification (ARM DEN 0056ASCMI) for
+ communicating with any compliant power controller.
+
+ Support is added for the Juno platform. The driver can be found in the
+ plat/arm/css/drivers folder.
+
+- Added support to enable pre-integration of TBB with the ARM TrustZone
+ CryptoCell product, to take advantage of its hardware Root of Trust and
+ crypto acceleration services.
+
+- Enabled Statistical Profiling Extensions for lower ELs.
+
+ The firmware support is limited to the use of SPE in the Non-secure state
+ and accesses to the SPE specific registers from S-EL1 will trap to EL3.
+
+ The SPE are architecturally specified for AArch64 only.
+
+- Code hygiene changes aligned with MISRA guidelines:
+
+ - Fixed signed / unsigned comparison warnings in the translation table
+ library.
+
+ - Added U(_x) macro and together with the existing ULL(_x) macro fixed
+ some of the signed-ness defects flagged by the MISRA scanner.
+
+- Enhancements to Firmware Update feature:
+
+ - The FWU logic now checks for overlapping images to prevent execution of
+ unauthenticated arbitary code.
+
+ - Introduced new FWU_SMC_IMAGE_RESET SMC that changes the image loading
+ state machine to go from COPYING, COPIED or AUTHENTICATED states to
+ RESET state. Previously, this was only possible when the authentication
+ of an image failed or when the execution of the image finished.
+
+ - Fixed integer overflow which addressed TFV-1: Malformed Firmware Update
+ SMC can result in copy of unexpectedly large data into secure memory.
+
+- Introduced support for ARM Compiler 6 and LLVM (clang).
+
+ ARM TF can now also be built with the ARM Compiler 6 or the clang compilers.
+ The assembler and linker must be provided by the GNU toolchain.
+
+ Tested with ARM CC 6.7 and clang 3.9.x and 4.0.x.
+
+- Memory footprint improvements:
+
+ - Introduced `tf_snprintf`, a reduced version of `snprintf` which has
+ support for a limited set of formats.
+
+ The mbedtls driver is updated to optionally use `tf_snprintf` instead of
+ `snprintf`.
+
+ - The `assert()` is updated to no longer print the function name, and
+ additional logging options are supported via an optional platform define
+ `PLAT_LOG_LEVEL_ASSERT`, which controls how verbose the assert output is.
+
+- Enhancements to Trusted Firmware support when running in AArch32 execution
+ state:
+
+ - Support booting SP_MIN and BL33 in AArch32 execution mode on Juno. Due to
+ hardware limitations, BL1 and BL2 boot in AArch64 state and there is
+ additional trampoline code to warm reset into SP_MIN in AArch32 execution
+ state.
+
+ - Added support for ARM Cortex-A53/57/72 MPCore processors including the
+ errata workarounds that are already implemented for AArch64 execution
+ state.
+
+ - For FVP platforms, added AArch32 Trusted Board Boot support, including the
+ Firmware Update feature.
+
+- Introduced ARM SiP service for use by ARM standard platforms.
+
+ - Added new ARM SiP Service SMCs to enable the Non-secure world to read PMF
+ timestamps.
+
+ Added PMF instrumentation points in ARM TF in order to quantify the
+ overall time spent in the PSCI software implementation.
+
+ - Added new ARM SiP service SMC to switch execution state.
+
+ This allows the lower exception level to change its execution state from
+ AArch64 to AArch32, or vice verse, via a request to EL3.
+
+- Migrated to use SPDX[0] license identifiers to make software license
+ auditing simpler.
+
+ *NOTE:* Files that have been imported by FreeBSD have not been modified.
+
+ [0]: https://spdx.org/
+
+- Enhancements to the translation table library:
+
+ - Added version 2 of translation table library that allows different
+ translation tables to be modified by using different 'contexts'. Version 1
+ of the transalation table library only allows the current EL's translation
+ tables to be modified.
+
+ Version 2 of the translation table also added support for dynamic
+ regions; regions that can be added and removed dynamically whilst the
+ MMU is enabled. Static regions can only be added or removed before the
+ MMU is enabled.
+
+ The dynamic mapping functionality is enabled or disabled when compiling
+ by setting the build option PLAT_XLAT_TABLES_DYNAMIC to 1 or 0. This can
+ be done per-image.
+
+ - Added support for translation regimes with two virtual address spaces
+ such as the one shared by EL1 and EL0.
+
+ The library does not support initializing translation tables for EL0
+ software.
+
+ - Added support to mark the translation tables as non-cacheable using an
+ additional build option `XLAT_TABLE_NC`.
+
+- Added support for GCC stack protection. A new build option
+ ENABLE_STACK_PROTECTOR was introduced that enables compilation of all BL
+ images with one of the GCC -fstack-protector-* options.
+
+ A new platform function plat_get_stack_protector_canary() was introduced
+ that returns a value used to initialize the canary for stack corruption
+ detection. For increased effectiveness of protection platforms must provide
+ an implementation that returns a random value.
+
+- Enhanced support for ARM platforms:
+
+ - Added support for multi-threading CPUs, indicated by `MT` field in MPDIR.
+ A new build flag `ARM_PLAT_MT` is added, and when enabled, the functions
+ accessing MPIDR assume that the `MT` bit is set for the platform and
+ access the bit fields accordingly.
+
+ Also, a new API `plat_arm_get_cpu_pe_count` is added when `ARM_PLAT_MT` is
+ enabled, returning the Processing Element count within the physical CPU
+ corresponding to `mpidr`.
+
+ - The ARM platforms migrated to use version 2 of the translation tables.
+
+ - Introduced a new ARM platform layer API `plat_arm_psci_override_pm_ops`
+ which allows ARM platforms to modify `plat_arm_psci_pm_ops` and therefore
+ dynamically define PSCI capability.
+
+ - The ARM platforms migrated to use IMAGE_LOAD_V2 by default.
+
+- Enhanced reporting of errata workaround status with the following policy:
+
+ - If an errata workaround is enabled:
+
+ - If it applies (i.e. the CPU is affected by the errata), an INFO message
+ is printed, confirming that the errata workaround has been applied.
+
+ - If it does not apply, a VERBOSE message is printed, confirming that the
+ errata workaround has been skipped.
+
+ - If an errata workaround is not enabled, but would have applied had it
+ been, a WARN message is printed, alerting that errata workaround is
+ missing.
+
+- Added build options ARM_ARCH_MAJOR and ARM_ARM_MINOR to choose the
+ architecture version to target ARM TF.
+
+- Updated the spin lock implementation to use the more efficient CAS (Compare
+ And Swap) instruction when available. This instruction was introduced in
+ ARMv8.1-A.
+
+- Applied errata workaround for ARM Cortex-A53: 855873.
+
+- Applied errata workaround for ARM-Cortex-A57: 813419.
+
+- Enabled all A53 and A57 errata workarounds for Juno, both in AArch64 and
+ AArch32 execution states.
+
+- Added support for Socionext UniPhier SoC platform.
+
+- Added support for Hikey960 and Hikey platforms.
+
+- Added support for Rockchip RK3328 platform.
+
+- Added support for NVidia Tegra T186 platform.
+
+- Added support for Designware emmc driver.
+
+- Imported libfdt v1.4.2 that addresses buffer overflow in fdt_offset_ptr().
+
+- Enhanced the CPU operations framework to allow power handlers to be
+ registered on per-level basis. This enables support for future CPUs that
+ have multiple threads which might need powering down individually.
+
+- Updated register initialisation to prevent unexpected behaviour:
+
+ - Debug registers MDCR-EL3/SDCR and MDCR_EL2/HDCR are initialised to avoid
+ unexpected traps into the higher exception levels and disable secure
+ self-hosted debug. Additionally, secure privileged external debug on
+ Juno is disabled by programming the appropriate Juno SoC registers.
+
+ - EL2 and EL3 configurable controls are initialised to avoid unexpected
+ traps in the higher exception levels.
+
+ - Essential control registers are fully initialised on EL3 start-up, when
+ initialising the non-secure and secure context structures and when
+ preparing to leave EL3 for a lower EL. This gives better alignement with
+ the ARM ARM which states that software must initialise RES0 and RES1
+ fields with 0 / 1.
+
+- Enhanced PSCI support:
+
+ - Introduced new platform interfaces that decouple PSCI stat residency
+ calculation from PMF, enabling platforms to use alternative methods of
+ capturing timestamps.
+
+ - PSCI stat accounting performed for retention/standby states when
+ requested at multiple power levels.
+
+- Simplified fiptool to have a single linked list of image descriptors.
+
+- For the TSP, resolved corruption of pre-empted secure context by aborting any
+ pre-empted SMC during PSCI power management requests.
+
+Issues resolved since last release
+==================================
+
+- ARM TF can be built with the latest mbed TLS version (v2.4.2). The earlier
+ version 2.3.0 cannot be used due to build warnings that the ARM TF build
+ system interprets as errors.
+
+- TBBR, including the Firmware Update feature is now supported on FVP
+ platforms when running Trusted Firmware in AArch32 state.
+
+- The version of the AEMv8 Base FVP used in this release has resolved the issue
+ of the model executing a reset instead of terminating in response to a
+ shutdown request using the PSCI SYSTEM_OFF API.
+
+Known Issues
+============
+
+- Building TF with compiler optimisations disabled (-O0) fails.
+
+- Trusted Board Boot currently does not work on Juno when running Trusted
+ Firmware in AArch32 execution state due to error when loading the sp_min to
+ memory becasue of lack of free space available. See `tf-issue#501`_ for more
+ details.
+
+- The errata workaround for A53 errata 843419 is only available from binutils
+ 2.26 and is not present in GCC4.9. If this errata is applicable to the
+ platform, please use GCC compiler version of at least 5.0. See `PR#1002`_ for
+ more details.
+
+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
+.. _tf-issue#501: https://github.com/ARM-software/tf-issues/issues/501
+.. _PR#1002: https://github.com/ARM-software/arm-trusted-firmware/pull/1002#issuecomment-312650193
diff --git a/docs/cpu-specific-build-macros.md b/docs/cpu-specific-build-macros.md
deleted file mode 100644
index eb23bcd..0000000
--- a/docs/cpu-specific-build-macros.md
+++ /dev/null
@@ -1,132 +0,0 @@
-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
diff --git a/docs/cpu-specific-build-macros.rst b/docs/cpu-specific-build-macros.rst
new file mode 100644
index 0000000..ce564a2
--- /dev/null
+++ b/docs/cpu-specific-build-macros.rst
@@ -0,0 +1,127 @@
+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
diff --git a/docs/firmware-design.md b/docs/firmware-design.md
deleted file mode 100644
index 9ae9717..0000000
--- a/docs/firmware-design.md
+++ /dev/null
@@ -1,2326 +0,0 @@
-ARM Trusted Firmware Design
-===========================
-
-Contents :
-
-1. [Introduction](#1--introduction)
-2. [Cold boot](#2--cold-boot)
-3. [EL3 runtime services framework](#3--el3-runtime-services-framework)
-4. [Power State Coordination Interface](#4--power-state-coordination-interface)
-5. [Secure-EL1 Payloads and Dispatchers](#5--secure-el1-payloads-and-dispatchers)
-6. [Crash Reporting in BL31](#6--crash-reporting-in-bl31)
-7. [Guidelines for Reset Handlers](#7--guidelines-for-reset-handlers)
-8. [CPU specific operations framework](#8--cpu-specific-operations-framework)
-9. [Memory layout of BL images](#9-memory-layout-of-bl-images)
-10. [Firmware Image Package (FIP)](#10--firmware-image-package-fip)
-11. [Use of coherent memory in Trusted Firmware](#11--use-of-coherent-memory-in-trusted-firmware)
-12. [Isolating code and read-only data on separate memory pages](#12--isolating-code-and-read-only-data-on-separate-memory-pages)
-13. [Performance Measurement Framework](#13--performance-measurement-framework)
-14. [ARMv8 Architecture Extensions](#14--armv8-architecture-extensions)
-15. [Code Structure](#15--code-structure)
-16. [References](#16--references)
-
-
-1. Introduction
-----------------
-
-The ARM Trusted Firmware implements a subset of the Trusted Board Boot
-Requirements (TBBR) Platform Design Document (PDD) [1] for ARM reference
-platforms. The TBB sequence starts when the platform is powered on and runs up
-to the stage where it hands-off control to firmware running in the normal
-world in DRAM. This is the cold boot path.
-
-The ARM Trusted Firmware also implements the Power State Coordination Interface
-([PSCI]) PDD [2] as a runtime service. PSCI is the interface from normal world
-software to firmware implementing power management use-cases (for example,
-secondary CPU boot, hotplug and idle). Normal world software can access ARM
-Trusted Firmware runtime services via the ARM SMC (Secure Monitor Call)
-instruction. The SMC instruction must be used as mandated by the [SMC Calling
-Convention PDD][SMCCC] [3].
-
-The ARM Trusted Firmware implements a framework for configuring and managing
-interrupts generated in either security state. The details of the interrupt
-management framework and its design can be found in [ARM Trusted
-Firmware Interrupt Management Design guide][INTRG] [4].
-
-The ARM Trusted Firmware can be built to support either AArch64 or AArch32
-execution state.
-
-2. Cold boot
--------------
-
-The cold boot path starts when the platform is physically turned on. If
-`COLD_BOOT_SINGLE_CPU=0`, one of the CPUs released from reset is chosen as the
-primary CPU, and the remaining CPUs are considered secondary CPUs. The primary
-CPU is chosen through platform-specific means. The cold boot path is mainly
-executed by the primary CPU, other than essential CPU initialization executed by
-all CPUs. The secondary CPUs are kept in a safe platform-specific state until
-the primary CPU has performed enough initialization to boot them.
-
-Refer to the [Reset Design] for more information on the effect of the
-`COLD_BOOT_SINGLE_CPU` platform build option.
-
-The cold boot path in this implementation of the ARM Trusted Firmware,
-depends on the execution state.
-For AArch64, it is divided into five steps (in order of execution):
-
-* Boot Loader stage 1 (BL1) _AP Trusted ROM_
-* Boot Loader stage 2 (BL2) _Trusted Boot Firmware_
-* Boot Loader stage 3-1 (BL31) _EL3 Runtime Software_
-* Boot Loader stage 3-2 (BL32) _Secure-EL1 Payload_ (optional)
-* Boot Loader stage 3-3 (BL33) _Non-trusted Firmware_
-
-For AArch32, it is divided into four steps (in order of execution):
-
-* Boot Loader stage 1 (BL1) _AP Trusted ROM_
-* Boot Loader stage 2 (BL2) _Trusted Boot Firmware_
-* Boot Loader stage 3-2 (BL32) _EL3 Runtime Software_
-* Boot Loader stage 3-3 (BL33) _Non-trusted Firmware_
-
-ARM development platforms (Fixed Virtual Platforms (FVPs) and Juno) implement a
-combination of the following types of memory regions. Each bootloader stage uses
-one or more of these memory regions.
-
-* Regions accessible from both non-secure and secure states. For example,
- non-trusted SRAM, ROM and DRAM.
-* Regions accessible from only the secure state. For example, trusted SRAM and
- ROM. The FVPs also implement the trusted DRAM which is statically
- configured. Additionally, the Base FVPs and Juno development platform
- configure the TrustZone Controller (TZC) to create a region in the DRAM
- which is accessible only from the secure state.
-
-
-The sections below provide the following details:
-
-* initialization and execution of the first three stages during cold boot
-* specification of the EL3 Runtime Software (BL31 for AArch64 and BL32 for
- AArch32) entrypoint requirements for use by alternative Trusted Boot
- Firmware in place of the provided BL1 and BL2
-
-
-### BL1
-
-This stage begins execution from the platform's reset vector at EL3. The reset
-address is platform dependent but it is usually located in a Trusted ROM area.
-The BL1 data section is copied to trusted SRAM at runtime.
-
-On the ARM development platforms, BL1 code starts execution from the reset
-vector defined by the constant `BL1_RO_BASE`. The BL1 data section is copied
-to the top of trusted SRAM as defined by the constant `BL1_RW_BASE`.
-
-The functionality implemented by this stage is as follows.
-
-#### Determination of boot path
-
-Whenever a CPU is released from reset, BL1 needs to distinguish between a warm
-boot and a cold boot. This is done using platform-specific mechanisms (see the
-`plat_get_my_entrypoint()` function in the [Porting Guide]). In the case of a
-warm boot, a CPU is expected to continue execution from a separate
-entrypoint. In the case of a cold boot, the secondary CPUs are placed in a safe
-platform-specific state (see the `plat_secondary_cold_boot_setup()` function in
-the [Porting Guide]) while the primary CPU executes the remaining cold boot path
-as described in the following sections.
-
-This step only applies when `PROGRAMMABLE_RESET_ADDRESS=0`. Refer to the
-[Reset Design] for more information on the effect of the
-`PROGRAMMABLE_RESET_ADDRESS` platform build option.
-
-#### Architectural initialization
-
-BL1 performs minimal architectural initialization as follows.
-
-* Exception vectors
-
- BL1 sets up simple exception vectors for both synchronous and asynchronous
- exceptions. The default behavior upon receiving an exception is to populate
- a status code in the general purpose register `X0/R0` and call the
- `plat_report_exception()` function (see the [Porting Guide]). The status
- code is one of:
-
- For AArch64:
-
- 0x0 : Synchronous exception from Current EL with SP_EL0
- 0x1 : IRQ exception from Current EL with SP_EL0
- 0x2 : FIQ exception from Current EL with SP_EL0
- 0x3 : System Error exception from Current EL with SP_EL0
- 0x4 : Synchronous exception from Current EL with SP_ELx
- 0x5 : IRQ exception from Current EL with SP_ELx
- 0x6 : FIQ exception from Current EL with SP_ELx
- 0x7 : System Error exception from Current EL with SP_ELx
- 0x8 : Synchronous exception from Lower EL using aarch64
- 0x9 : IRQ exception from Lower EL using aarch64
- 0xa : FIQ exception from Lower EL using aarch64
- 0xb : System Error exception from Lower EL using aarch64
- 0xc : Synchronous exception from Lower EL using aarch32
- 0xd : IRQ exception from Lower EL using aarch32
- 0xe : FIQ exception from Lower EL using aarch32
- 0xf : System Error exception from Lower EL using aarch32
-
- For AArch32:
-
- 0x10 : User mode
- 0x11 : FIQ mode
- 0x12 : IRQ mode
- 0x13 : SVC mode
- 0x16 : Monitor mode
- 0x17 : Abort mode
- 0x1a : Hypervisor mode
- 0x1b : Undefined mode
- 0x1f : System mode
-
- The `plat_report_exception()` implementation on the ARM FVP port programs
- the Versatile Express System LED register in the following format to
- indicate the occurence of an unexpected exception:
-
- SYS_LED[0] - Security state (Secure=0/Non-Secure=1)
- SYS_LED[2:1] - Exception Level (EL3=0x3, EL2=0x2, EL1=0x1, EL0=0x0)
- For AArch32 it is always 0x0
- SYS_LED[7:3] - Exception Class (Sync/Async & origin). This is the value
- of the status code
-
- A write to the LED register reflects in the System LEDs (S6LED0..7) in the
- CLCD window of the FVP.
-
- BL1 does not expect to receive any exceptions other than the SMC exception.
- For the latter, BL1 installs a simple stub. The stub expects to receive a
- limited set of SMC types (determined by their function IDs in the general
- purpose register `X0/R0`):
- - `BL1_SMC_RUN_IMAGE`: This SMC is raised by BL2 to make BL1 pass control
- to EL3 Runtime Software.
- - All SMCs listed in section "BL1 SMC Interface" in the [Firmware Update]
- Design Guide are supported for AArch64 only. These SMCs are currently
- not supported when BL1 is built for AArch32.
-
- Any other SMC leads to an assertion failure.
-
-* CPU initialization
-
- BL1 calls the `reset_handler()` function which in turn calls the CPU
- specific reset handler function (see the section: "CPU specific operations
- framework").
-
-* Control register setup (for AArch64)
- - `SCTLR_EL3`. Instruction cache is enabled by setting the `SCTLR_EL3.I`
- bit. Alignment and stack alignment checking is enabled by setting the
- `SCTLR_EL3.A` and `SCTLR_EL3.SA` bits. Exception endianness is set to
- little-endian by clearing the `SCTLR_EL3.EE` bit.
-
- - `SCR_EL3`. The register width of the next lower exception level is set
- to AArch64 by setting the `SCR.RW` bit. The `SCR.EA` bit is set to trap
- both External Aborts and SError Interrupts in EL3. The `SCR.SIF` bit is
- also set to disable instruction fetches from Non-secure memory when in
- secure state.
-
- - `CPTR_EL3`. Accesses to the `CPACR_EL1` register from EL1 or EL2, or the
- `CPTR_EL2` register from EL2 are configured to not trap to EL3 by
- clearing the `CPTR_EL3.TCPAC` bit. Access to the trace functionality is
- configured not to trap to EL3 by clearing the `CPTR_EL3.TTA` bit.
- Instructions that access the registers associated with Floating Point
- and Advanced SIMD execution are configured to not trap to EL3 by
- clearing the `CPTR_EL3.TFP` bit.
-
- - `DAIF`. The SError interrupt is enabled by clearing the SError interrupt
- mask bit.
-
- - `MDCR_EL3`. The trap controls, `MDCR_EL3.TDOSA`, `MDCR_EL3.TDA` and
- `MDCR_EL3.TPM`, are set so that accesses to the registers they control
- 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
- disable AArch32 Secure self-hosted privileged debug from S-EL1.
-
-* Control register setup (for AArch32)
- - `SCTLR`. Instruction cache is enabled by setting the `SCTLR.I` bit.
- Alignment checking is enabled by setting the `SCTLR.A` bit.
- Exception endianness is set to little-endian by clearing the
- `SCTLR.EE` bit.
-
- - `SCR`. The `SCR.SIF` bit is set to disable instruction fetches from
- Non-secure memory when in secure state.
-
- - `CPACR`. Allow execution of Advanced SIMD instructions at PL0 and PL1,
- by clearing the `CPACR.ASEDIS` bit. Access to the trace functionality
- is configured not to trap to undefined mode by clearing the
- `CPACR.TRCDIS` bit.
-
- - `NSACR`. Enable non-secure access to Advanced SIMD functionality and
- system register access to implemented trace registers.
-
- - `FPEXC`. Enable access to the Advanced SIMD and floating-point
- functionality from all Exception levels.
-
- - `CPSR.A`. The Asynchronous data abort interrupt is enabled by clearing
- the Asynchronous data abort interrupt mask bit.
-
- - `SDCR`. The `SDCR.SPD` field is set to disable AArch32 Secure
- self-hosted privileged debug.
-
-#### Platform initialization
-
-On ARM platforms, BL1 performs the following platform initializations:
-
-* Enable the Trusted Watchdog.
-* Initialize the console.
-* Configure the Interconnect to enable hardware coherency.
-* Enable the MMU and map the memory it needs to access.
-* Configure any required platform storage to load the next bootloader image
- (BL2).
-
-#### Firmware Update detection and execution
-
-After performing platform setup, BL1 common code calls
-`bl1_plat_get_next_image_id()` to determine if [Firmware Update] is required or
-to proceed with the normal boot process. If the platform code returns
-`BL2_IMAGE_ID` then the normal boot sequence is executed as described in the
-next section, else BL1 assumes that [Firmware Update] is required and execution
-passes to the first image in the [Firmware Update] process. In either case, BL1
-retrieves a descriptor of the next image by calling `bl1_plat_get_image_desc()`.
-The image descriptor contains an `entry_point_info_t` structure, which BL1
-uses to initialize the execution state of the next image.
-
-#### BL2 image load and execution
-
-In the normal boot flow, BL1 execution continues as follows:
-
-1. BL1 prints the following string from the primary CPU to indicate successful
- execution of the BL1 stage:
-
- "Booting Trusted Firmware"
-
-2. BL1 determines the amount of free trusted SRAM memory available by
- calculating the extent of its own data section, which also resides in
- trusted SRAM. BL1 loads a BL2 raw binary image from platform storage, at a
- platform-specific base address. If the BL2 image file is not present or if
- there is not enough free trusted SRAM the following error message is
- printed:
-
- "Failed to load BL2 firmware."
-
- BL1 calculates the amount of Trusted SRAM that can be used by the BL2
- image. The exact load location of the image is provided as a base address
- in the platform header. Further description of the memory layout can be
- found later in this document.
-
-3. BL1 passes control to the BL2 image at Secure EL1 (for AArch64) or at
- Secure SVC mode (for AArch32), starting from its load address.
-
-4. BL1 also passes information about the amount of trusted SRAM used and
- available for use. This information is populated at a platform-specific
- memory address.
-
-
-### BL2
-
-BL1 loads and passes control to BL2 at Secure-EL1 (for AArch64) or at Secure
-SVC mode (for AArch32) . BL2 is linked against and loaded at a platform-specific
-base address (more information can be found later in this document).
-The functionality implemented by BL2 is as follows.
-
-#### Architectural initialization
-
-For AArch64, BL2 performs the minimal architectural initialization required
-for subsequent stages of the ARM Trusted Firmware and normal world software.
-EL1 and EL0 are given access to Floating Point and Advanced SIMD registers
-by clearing the `CPACR.FPEN` bits.
-
-For AArch32, the minimal architectural initialization required for subsequent
-stages of the ARM Trusted Firmware and normal world software is taken care of
-in BL1 as both BL1 and BL2 execute at PL1.
-
-#### Platform initialization
-
-On ARM platforms, BL2 performs the following platform initializations:
-
-* Initialize the console.
-* Configure any required platform storage to allow loading further bootloader
- images.
-* Enable the MMU and map the memory it needs to access.
-* Perform platform security setup to allow access to controlled components.
-* Reserve some memory for passing information to the next bootloader image
- EL3 Runtime Software and populate it.
-* Define the extents of memory available for loading each subsequent
- bootloader image.
-
-#### Image loading in BL2
-
-Image loading scheme in BL2 depends on `LOAD_IMAGE_V2` build option. If the
-flag is disabled, the BLxx images are loaded, by calling the respective
-load_blxx() function from BL2 generic code. If the flag is enabled, the BL2
-generic code loads the images based on the list of loadable images provided
-by the platform. BL2 passes the list of executable images provided by the
-platform to the next handover BL image. By default, this flag is disabled for
-AArch64 and the AArch32 build is supported only if this flag is enabled.
-
-#### SCP_BL2 (System Control Processor Firmware) image load
-
-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
-storage into a platform-specific region of secure memory. The subsequent
-handling of SCP_BL2 is platform specific. For example, on the Juno ARM
-development platform port the image is transferred into SCP's internal memory
-using the Boot Over MHU (BOM) protocol after being loaded in the trusted SRAM
-memory. The SCP executes SCP_BL2 and signals to the Application Processor (AP)
-for BL2 execution to continue.
-
-#### EL3 Runtime Software image load
-
-BL2 loads the EL3 Runtime Software image from platform storage into a platform-
-specific address in trusted SRAM. If there is not enough memory to load the
-image or image is missing it leads to an assertion failure. If `LOAD_IMAGE_V2`
-is disabled and if image loads successfully, BL2 updates the amount of trusted
-SRAM used and available for use by EL3 Runtime Software. This information is
-populated at a platform-specific memory address.
-
-#### AArch64 BL32 (Secure-EL1 Payload) image load
-
-BL2 loads the optional BL32 image from platform storage into a platform-
-specific region of secure memory. The image executes in the secure world. BL2
-relies on BL31 to pass control to the BL32 image, if present. Hence, BL2
-populates a platform-specific area of memory with the entrypoint/load-address
-of the BL32 image. The value of the Saved Processor Status Register (`SPSR`)
-for entry into BL32 is not determined by BL2, it is initialized by the
-Secure-EL1 Payload Dispatcher (see later) within BL31, which is responsible for
-managing interaction with BL32. This information is passed to BL31.
-
-#### BL33 (Non-trusted Firmware) image load
-
-BL2 loads the BL33 image (e.g. UEFI or other test or boot software) from
-platform storage into non-secure memory as defined by the platform.
-
-BL2 relies on EL3 Runtime Software to pass control to BL33 once secure state
-initialization is complete. Hence, BL2 populates a platform-specific area of
-memory with the entrypoint and Saved Program Status Register (`SPSR`) of the
-normal world software image. The entrypoint is the load address of the BL33
-image. The `SPSR` is determined as specified in Section 5.13 of the [PSCI PDD]
-[PSCI]. This information is passed to the EL3 Runtime Software.
-
-#### AArch64 BL31 (EL3 Runtime Software) execution
-
-BL2 execution continues as follows:
-
-1. BL2 passes control back to BL1 by raising an SMC, providing BL1 with the
- BL31 entrypoint. The exception is handled by the SMC exception handler
- installed by BL1.
-
-2. BL1 turns off the MMU and flushes the caches. It clears the
- `SCTLR_EL3.M/I/C` bits, flushes the data cache to the point of coherency
- and invalidates the TLBs.
-
-3. BL1 passes control to BL31 at the specified entrypoint at EL3.
-
-
-### AArch64 BL31
-
-The image for this stage is loaded by BL2 and BL1 passes control to BL31 at
-EL3. BL31 executes solely in trusted SRAM. BL31 is linked against and
-loaded at a platform-specific base address (more information can be found later
-in this document). The functionality implemented by BL31 is as follows.
-
-#### Architectural initialization
-
-Currently, BL31 performs a similar architectural initialization to BL1 as
-far as system register settings are concerned. Since BL1 code resides in ROM,
-architectural initialization in BL31 allows override of any previous
-initialization done by BL1.
-
-BL31 initializes the per-CPU data framework, which provides a cache of
-frequently accessed per-CPU data optimised for fast, concurrent manipulation
-on different CPUs. This buffer includes pointers to per-CPU contexts, crash
-buffer, CPU reset and power down operations, PSCI data, platform data and so on.
-
-It then replaces the exception vectors populated by BL1 with its own. BL31
-exception vectors implement more elaborate support for handling SMCs since this
-is the only mechanism to access the runtime services implemented by BL31 (PSCI
-for example). BL31 checks each SMC for validity as specified by the
-[SMC calling convention PDD][SMCCC] before passing control to the required SMC
-handler routine.
-
-BL31 programs the `CNTFRQ_EL0` register with the clock frequency of the system
-counter, which is provided by the platform.
-
-#### Platform initialization
-
-BL31 performs detailed platform initialization, which enables normal world
-software to function correctly.
-
-On ARM platforms, this consists of the following:
-
-* Initialize the console.
-* Configure the Interconnect to enable hardware coherency.
-* Enable the MMU and map the memory it needs to access.
-* Initialize the generic interrupt controller.
-* Initialize the power controller device.
-* Detect the system topology.
-
-#### Runtime services initialization
-
-BL31 is responsible for initializing the runtime services. One of them is PSCI.
-
-As part of the PSCI initializations, BL31 detects the system topology. It also
-initializes the data structures that implement the state machine used to track
-the state of power domain nodes. The state can be one of `OFF`, `RUN` or
-`RETENTION`. All secondary CPUs are initially in the `OFF` state. The cluster
-that the primary CPU belongs to is `ON`; any other cluster is `OFF`. It also
-initializes the locks that protect them. BL31 accesses the state of a CPU or
-cluster immediately after reset and before the data cache is enabled in the
-warm boot path. It is not currently possible to use 'exclusive' based spinlocks,
-therefore BL31 uses locks based on Lamport's Bakery algorithm instead.
-
-The runtime service framework and its initialization is described in more
-detail in the "EL3 runtime services framework" section below.
-
-Details about the status of the PSCI implementation are provided in the
-"Power State Coordination Interface" section below.
-
-#### AArch64 BL32 (Secure-EL1 Payload) image initialization
-
-If a BL32 image is present then there must be a matching Secure-EL1 Payload
-Dispatcher (SPD) service (see later for details). During initialization
-that service must register a function to carry out initialization of BL32
-once the runtime services are fully initialized. BL31 invokes such a
-registered function to initialize BL32 before running BL33. This initialization
-is not necessary for AArch32 SPs.
-
-Details on BL32 initialization and the SPD's role are described in the
-"Secure-EL1 Payloads and Dispatchers" section below.
-
-#### BL33 (Non-trusted Firmware) execution
-
-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
-the non-secure execution state. EL3 Runtime Software uses the entrypoint
-information provided by BL2 to jump to the Non-trusted firmware image (BL33)
-at the highest available Exception Level (EL2 if available, otherwise EL1).
-
-### Using alternative Trusted Boot Firmware in place of BL1 & BL2 (AArch64 only)
-
-Some platforms have existing implementations of Trusted Boot Firmware that
-would like to use ARM Trusted Firmware BL31 for the EL3 Runtime Software. To
-enable this firmware architecture it is important to provide a fully documented
-and stable interface between the Trusted Boot Firmware and BL31.
-
-Future changes to the BL31 interface will be done in a backwards compatible
-way, and this enables these firmware components to be independently enhanced/
-updated to develop and exploit new functionality.
-
-#### Required CPU state when calling `bl31_entrypoint()` during cold boot
-
-This function must only be called by the primary CPU.
-
-On entry to this function the calling primary CPU must be executing in AArch64
-EL3, little-endian data access, and all interrupt sources masked:
-
- PSTATE.EL = 3
- PSTATE.RW = 1
- PSTATE.DAIF = 0xf
- SCTLR_EL3.EE = 0
-
-X0 and X1 can be used to pass information from the Trusted Boot Firmware to the
-platform code in BL31:
-
- X0 : Reserved for common Trusted Firmware information
- X1 : Platform specific information
-
-BL31 zero-init sections (e.g. `.bss`) should not contain valid data on entry,
-these will be zero filled prior to invoking platform setup code.
-
-##### Use of the X0 and X1 parameters
-
-The parameters are platform specific and passed from `bl31_entrypoint()` to
-`bl31_early_platform_setup()`. The value of these parameters is never directly
-used by the common BL31 code.
-
-The convention is that `X0` conveys information regarding the BL31, BL32 and
-BL33 images from the Trusted Boot firmware and `X1` can be used for other
-platform specific purpose. This convention allows platforms which use ARM
-Trusted Firmware's BL1 and BL2 images to transfer additional platform specific
-information from Secure Boot without conflicting with future evolution of the
-Trusted Firmware using `X0` to pass a `bl31_params` structure.
-
-BL31 common and SPD initialization code depends on image and entrypoint
-information about BL33 and BL32, which is provided via BL31 platform APIs.
-This information is required until the start of execution of BL33. This
-information can be provided in a platform defined manner, e.g. compiled into
-the platform code in BL31, or provided in a platform defined memory location
-by the Trusted Boot firmware, or passed from the Trusted Boot Firmware via the
-Cold boot Initialization parameters. This data may need to be cleaned out of
-the CPU caches if it is provided by an earlier boot stage and then accessed by
-BL31 platform code before the caches are enabled.
-
-ARM Trusted Firmware's BL2 implementation passes a `bl31_params` structure in
-`X0` and the ARM development platforms interpret this in the BL31 platform
-code.
-
-##### MMU, Data caches & Coherency
-
-BL31 does not depend on the enabled state of the MMU, data caches or
-interconnect coherency on entry to `bl31_entrypoint()`. If these are disabled
-on entry, these should be enabled during `bl31_plat_arch_setup()`.
-
-##### Data structures used in the BL31 cold boot interface
-
-These structures are designed to support compatibility and independent
-evolution of the structures and the firmware images. For example, a version of
-BL31 that can interpret the BL3x image information from different versions of
-BL2, a platform that uses an extended entry_point_info structure to convey
-additional register information to BL31, or a ELF image loader that can convey
-more details about the firmware images.
-
-To support these scenarios the structures are versioned and sized, which enables
-BL31 to detect which information is present and respond appropriately. The
-`param_header` is defined to capture this information:
-
- typedef struct param_header {
- uint8_t type; /* type of the structure */
- uint8_t version; /* version of this structure */
- uint16_t size; /* size of this structure in bytes */
- uint32_t attr; /* attributes: unused bits SBZ */
- } param_header_t;
-
-The structures using this format are `entry_point_info`, `image_info` and
-`bl31_params`. The code that allocates and populates these structures must set
-the header fields appropriately, and the `SET_PARAM_HEAD()` a macro is defined
-to simplify this action.
-
-#### Required CPU state for BL31 Warm boot initialization
-
-When requesting a CPU power-on, or suspending a running CPU, ARM Trusted
-Firmware provides the platform power management code with a Warm boot
-initialization entry-point, to be invoked by the CPU immediately after the
-reset handler. On entry to the Warm boot initialization function the calling
-CPU must be in AArch64 EL3, little-endian data access and all interrupt sources
-masked:
-
- PSTATE.EL = 3
- PSTATE.RW = 1
- PSTATE.DAIF = 0xf
- SCTLR_EL3.EE = 0
-
-The PSCI implementation will initialize the processor state and ensure that the
-platform power management code is then invoked as required to initialize all
-necessary system, cluster and CPU resources.
-
-### AArch32 EL3 Runtime Software entrypoint interface
-
-To enable this firmware architecture it is important to provide a fully
-documented and stable interface between the Trusted Boot Firmware and the
-AArch32 EL3 Runtime Software.
-
-Future changes to the entrypoint interface will be done in a backwards
-compatible way, and this enables these firmware components to be independently
-enhanced/updated to develop and exploit new functionality.
-
-#### Required CPU state when entering during cold boot
-
-This function must only be called by the primary CPU.
-
-On entry to this function the calling primary CPU must be executing in AArch32
-EL3, little-endian data access, and all interrupt sources masked:
-
- PSTATE.AIF = 0x7
- SCTLR.EE = 0
-
-R0 and R1 are used to pass information from the Trusted Boot Firmware to the
-platform code in AArch32 EL3 Runtime Software:
-
- R0 : Reserved for common Trusted Firmware information
- R1 : Platform specific information
-
-##### Use of the R0 and R1 parameters
-
-The parameters are platform specific and the convention is that `R0` conveys
-information regarding the BL3x images from the Trusted Boot firmware and `R1`
-can be used for other platform specific purpose. This convention allows
-platforms which use ARM Trusted Firmware's BL1 and BL2 images to transfer
-additional platform specific information from Secure Boot without conflicting
-with future evolution of the Trusted Firmware using `R0` to pass a `bl_params`
-structure.
-
-The AArch32 EL3 Runtime Software is responsible for entry into BL33. This
-information can be obtained in a platform defined manner, e.g. compiled into
-the AArch32 EL3 Runtime Software, or provided in a platform defined memory
-location by the Trusted Boot firmware, or passed from the Trusted Boot Firmware
-via the Cold boot Initialization parameters. This data may need to be cleaned
-out of the CPU caches if it is provided by an earlier boot stage and then
-accessed by AArch32 EL3 Runtime Software before the caches are enabled.
-
-When using AArch32 EL3 Runtime Software, the ARM development platforms pass a
-`bl_params` structure in `R0` from BL2 to be interpreted by AArch32 EL3 Runtime
-Software platform code.
-
-##### MMU, Data caches & Coherency
-
-AArch32 EL3 Runtime Software must not depend on the enabled state of the MMU,
-data caches or interconnect coherency in its entrypoint. They must be explicitly
-enabled if required.
-
-##### Data structures used in cold boot interface
-
-The AArch32 EL3 Runtime Software cold boot interface uses `bl_params` instead
-of `bl31_params`. The `bl_params` structure is based on the convention
-described in AArch64 BL31 cold boot interface section.
-
-#### Required CPU state for warm boot initialization
-
-When requesting a CPU power-on, or suspending a running CPU, AArch32 EL3
-Runtime Software must ensure execution of a warm boot initialization entrypoint.
-If ARM Trusted Firmware BL1 is used and the PROGRAMMABLE_RESET_ADDRESS build
-flag is false, then AArch32 EL3 Runtime Software must ensure that BL1 branches
-to the warm boot entrypoint by arranging for the BL1 platform function,
-plat_get_my_entrypoint(), to return a non-zero value.
-
-In this case, the warm boot entrypoint must be in AArch32 EL3, little-endian
-data access and all interrupt sources masked:
-
- PSTATE.AIF = 0x7
- SCTLR.EE = 0
-
-The warm boot entrypoint may be implemented by using the ARM Trusted Firmware
-`psci_warmboot_entrypoint()` function. In that case, the platform must fulfil
-the pre-requisites mentioned in the [PSCI Library integration guide]
-[PSCI Lib guide].
-
-3. EL3 runtime services framework
-----------------------------------
-
-Software executing in the non-secure state and in the secure state at exception
-levels lower than EL3 will request runtime services using the Secure Monitor
-Call (SMC) instruction. These requests will follow the convention described in
-the SMC Calling Convention PDD ([SMCCC]). The [SMCCC] assigns function
-identifiers to each SMC request and describes how arguments are passed and
-returned.
-
-The EL3 runtime services framework enables the development of services by
-different providers that can be easily integrated into final product firmware.
-The following sections describe the framework which facilitates the
-registration, initialization and use of runtime services in EL3 Runtime
-Software (BL31).
-
-The design of the runtime services depends heavily on the concepts and
-definitions described in the [SMCCC], in particular SMC Function IDs, Owning
-Entity Numbers (OEN), Fast and Yielding calls, and the SMC32 and SMC64 calling
-conventions. Please refer to that document for more detailed explanation of
-these terms.
-
-The following runtime services are expected to be implemented first. They have
-not all been instantiated in the current implementation.
-
-1. Standard service calls
-
- This service is for management of the entire system. The Power State
- Coordination Interface ([PSCI]) is the first set of standard service calls
- defined by ARM (see PSCI section later).
-
-2. Secure-EL1 Payload Dispatcher service
-
- If a system runs a Trusted OS or other Secure-EL1 Payload (SP) then
- it also requires a _Secure Monitor_ at EL3 to switch the EL1 processor
- context between the normal world (EL1/EL2) and trusted world (Secure-EL1).
- The Secure Monitor will make these world switches in response to SMCs. The
- [SMCCC] provides for such SMCs with the Trusted OS Call and Trusted
- Application Call OEN ranges.
-
- The interface between the EL3 Runtime Software and the Secure-EL1 Payload is
- not defined by the [SMCCC] or any other standard. As a result, each
- Secure-EL1 Payload requires a specific Secure Monitor that runs as a runtime
- service - within ARM Trusted Firmware this service is referred to as the
- Secure-EL1 Payload Dispatcher (SPD).
-
- ARM Trusted Firmware provides a Test Secure-EL1 Payload (TSP) and its
- associated Dispatcher (TSPD). Details of SPD design and TSP/TSPD operation
- are described in the "Secure-EL1 Payloads and Dispatchers" section below.
-
-3. CPU implementation service
-
- This service will provide an interface to CPU implementation specific
- services for a given platform e.g. access to processor errata workarounds.
- This service is currently unimplemented.
-
-Additional services for ARM Architecture, SiP and OEM calls can be implemented.
-Each implemented service handles a range of SMC function identifiers as
-described in the [SMCCC].
-
-
-### Registration
-
-A runtime service is registered using the `DECLARE_RT_SVC()` macro, specifying
-the name of the service, the range of OENs covered, the type of service and
-initialization and call handler functions. This macro instantiates a `const
-struct rt_svc_desc` for the service with these details (see `runtime_svc.h`).
-This structure is allocated in a special ELF section `rt_svc_descs`, enabling
-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
-type of the Function ID, and the framework uses that information in the service
-descriptor to identify the handler for the SMC Call.
-
-The service descriptors do not include information to identify the precise set
-of SMC function identifiers supported by this service implementation, the
-security state from which such calls are valid nor the capability to support
-64-bit and/or 32-bit callers (using SMC32 or SMC64). Responding appropriately
-to these aspects of a SMC call is the responsibility of the service
-implementation, the framework is focused on integration of services from
-different providers and minimizing the time taken by the framework before the
-service handler is invoked.
-
-Details of the parameters, requirements and behavior of the initialization and
-call handling functions are provided in the following sections.
-
-
-### Initialization
-
-`runtime_svc_init()` in `runtime_svc.c` initializes the runtime services
-framework running on the primary CPU during cold boot as part of the BL31
-initialization. This happens prior to initializing a Trusted OS and running
-Normal world boot firmware that might in turn use these services.
-Initialization involves validating each of the declared runtime service
-descriptors, calling the service initialization function and populating the
-index used for runtime lookup of the service.
-
-The BL31 linker script collects all of the declared service descriptors into a
-single array and defines symbols that allow the framework to locate and traverse
-the array, and determine its size.
-
-The framework does basic validation of each descriptor to halt firmware
-initialization if service declaration errors are detected. The framework does
-not check descriptors for the following error conditions, and may behave in an
-unpredictable manner under such scenarios:
-
-1. Overlapping OEN ranges
-2. Multiple descriptors for the same range of OENs and `call_type`
-3. Incorrect range of owning entity numbers for a given `call_type`
-
-Once validated, the service `init()` callback is invoked. This function carries
-out any essential EL3 initialization before servicing requests. The `init()`
-function is only invoked on the primary CPU during cold boot. If the service
-uses per-CPU data this must either be initialized for all CPUs during this call,
-or be done lazily when a CPU first issues an SMC call to that service. If
-`init()` returns anything other than `0`, this is treated as an initialization
-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
-128 distinct services, but in practice a single descriptor can cover a range of
-OENs, e.g. SMCs to call a Trusted OS function. To optimize the lookup of a
-service handler, the framework uses an array of 128 indices that map every
-distinct OEN/call-type combination either to one of the declared services or to
-indicate the service is not handled. This `rt_svc_descs_indices[]` array is
-populated for all of the OENs covered by a service after the service `init()`
-function has reported success. So a service that fails to initialize will never
-have it's `handle()` function invoked.
-
-The following figure shows how the `rt_svc_descs_indices[]` index maps the SMC
-Function ID call type and OEN onto a specific service handler in the
-`rt_svc_descs[]` array.
-
-
-
-
-### Handling an SMC
-
-When the EL3 runtime services framework receives a Secure Monitor Call, the SMC
-Function ID is passed in W0 from the lower exception level (as per the
-[SMCCC]). If the calling register width is AArch32, it is invalid to invoke an
-SMC Function which indicates the SMC64 calling convention: such calls are
-ignored and return the Unknown SMC Function Identifier result code `0xFFFFFFFF`
-in R0/X0.
-
-Bit[31] (fast/yielding call) and bits[29:24] (owning entity number) of the SMC
-Function ID are combined to index into the `rt_svc_descs_indices[]` array. The
-resulting value might indicate a service that has no handler, in this case the
-framework will also report an Unknown SMC Function ID. Otherwise, the value is
-used as a further index into the `rt_svc_descs[]` array to locate the required
-service and handler.
-
-The service's `handle()` callback is provided with five of the SMC parameters
-directly, the others are saved into memory for retrieval (if needed) by the
-handler. The handler is also provided with an opaque `handle` for use with the
-supporting library for parameter retrieval, setting return values and context
-manipulation; and with `flags` indicating the security state of the caller. The
-framework finally sets up the execution stack for the handler, and invokes the
-services `handle()` function.
-
-On return from the handler the result registers are populated in X0-X3 before
-restoring the stack and CPU state and returning from the original SMC.
-
-
-4. Power State Coordination Interface
---------------------------------------
-
-TODO: Provide design walkthrough of PSCI implementation.
-
-The PSCI v1.0 specification categorizes APIs as optional and mandatory. All the
-mandatory APIs in PSCI v1.0 and all the APIs in PSCI v0.2 draft specification
-[Power State Coordination Interface PDD] [PSCI] are implemented. The table lists
-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
-requires the platform to export a part of the implementation. Hence the level
-of support of the mandatory APIs depends upon the support exported by the
-platform port as well. The Juno and FVP (all variants) platforms export all the
-required support.
-
-| PSCI v1.0 API |Supported| Comments |
-|:----------------------|:--------|:------------------------------------------|
-|`PSCI_VERSION` | Yes | The version returned is 1.0 |
-|`CPU_SUSPEND` | Yes* | |
-|`CPU_OFF` | Yes* | |
-|`CPU_ON` | Yes* | |
-|`AFFINITY_INFO` | Yes | |
-|`MIGRATE` | Yes** | |
-|`MIGRATE_INFO_TYPE` | Yes** | |
-|`MIGRATE_INFO_CPU` | Yes** | |
-|`SYSTEM_OFF` | Yes* | |
-|`SYSTEM_RESET` | Yes* | |
-|`PSCI_FEATURES` | Yes | |
-|`CPU_FREEZE` | No | |
-|`CPU_DEFAULT_SUSPEND` | No | |
-|`NODE_HW_STATE` | Yes* | |
-|`SYSTEM_SUSPEND` | Yes* | |
-|`PSCI_SET_SUSPEND_MODE`| No | |
-|`PSCI_STAT_RESIDENCY` | Yes* | |
-|`PSCI_STAT_COUNT` | Yes* | |
-
-*Note : These PSCI APIs require platform power management hooks to be
-registered with the generic PSCI code to be supported.
-
-**Note : These PSCI APIs require appropriate Secure Payload Dispatcher
-hooks to be registered with the generic PSCI code to be supported.
-
-The PSCI implementation in ARM Trusted Firmware is a library which can be
-integrated with AArch64 or AArch32 EL3 Runtime Software for ARMv8-A systems.
-A guide to integrating PSCI library with AArch32 EL3 Runtime Software
-can be found [here][PSCI Lib guide].
-
-
-5. Secure-EL1 Payloads and Dispatchers
----------------------------------------
-
-On a production system that includes a Trusted OS running in Secure-EL1/EL0,
-the Trusted OS is coupled with a companion runtime service in the BL31
-firmware. This service is responsible for the initialisation of the Trusted
-OS and all communications with it. The Trusted OS is the BL32 stage of the
-boot flow in ARM Trusted Firmware. The firmware will attempt to locate, load
-and execute a BL32 image.
-
-ARM Trusted Firmware uses a more general term for the BL32 software that runs
-at Secure-EL1 - the _Secure-EL1 Payload_ - as it is not always a Trusted OS.
-
-The ARM Trusted Firmware provides a Test Secure-EL1 Payload (TSP) and a Test
-Secure-EL1 Payload Dispatcher (TSPD) service as an example of how a Trusted OS
-is supported on a production system using the Runtime Services Framework. On
-such a system, the Test BL32 image and service are replaced by the Trusted OS
-and its dispatcher service. The ARM Trusted Firmware build system expects that
-the dispatcher will define the build flag `NEED_BL32` to enable it to include
-the BL32 in the build either as a binary or to compile from source depending
-on whether the `BL32` build option is specified or not.
-
-The TSP runs in Secure-EL1. It is designed to demonstrate synchronous
-communication with the normal-world software running in EL1/EL2. Communication
-is initiated by the normal-world software
-
-* either directly through a Fast SMC (as defined in the [SMCCC])
-
-* or indirectly through a [PSCI] SMC. The [PSCI] implementation in turn
- informs the TSPD about the requested power management operation. This allows
- the TSP to prepare for or respond to the power state change
-
-The TSPD service is responsible for.
-
-* Initializing the TSP
-
-* Routing requests and responses between the secure and the non-secure
- states during the two types of communications just described
-
-### Initializing a BL32 Image
-
-The Secure-EL1 Payload Dispatcher (SPD) service is responsible for initializing
-the BL32 image. It needs access to the information passed by BL2 to BL31 to do
-so. This is provided by:
-
- 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
-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.
-
-In the absence of a BL32 image, BL31 passes control to the normal world
-bootloader image (BL33). When the BL32 image is present, it is typical
-that the SPD wants control to be passed to BL32 first and then later to BL33.
-
-To do this the SPD has to register a BL32 initialization function during
-initialization of the SPD service. The BL32 initialization function has this
-prototype:
-
- int32_t init(void);
-
-and is registered using the `bl31_register_bl32_init()` function.
-
-Trusted Firmware supports two approaches for the SPD to pass control to BL32
-before returning through EL3 and running the non-trusted firmware (BL33):
-
-1. In the BL32 setup function, use `bl31_set_next_image_type()` to
- request that the exit from `bl31_main()` is to the BL32 entrypoint in
- Secure-EL1. BL31 will exit to BL32 using the asynchronous method by
- calling `bl31_prepare_next_image_entry()` and `el3_exit()`.
-
- When the BL32 has completed initialization at Secure-EL1, it returns to
- BL31 by issuing an SMC, using a Function ID allocated to the SPD. On
- receipt of this SMC, the SPD service handler should switch the CPU context
- from trusted to normal world and use the `bl31_set_next_image_type()` and
- `bl31_prepare_next_image_entry()` functions to set up the initial return to
- the normal world firmware BL33. On return from the handler the framework
- will exit to EL2 and run BL33.
-
-2. The BL32 setup function registers an initialization function using
- `bl31_register_bl32_init()` which provides a SPD-defined mechanism to
- invoke a 'world-switch synchronous call' to Secure-EL1 to run the BL32
- entrypoint.
- NOTE: The Test SPD service included with the Trusted Firmware provides one
- implementation of such a mechanism.
-
- On completion BL32 returns control to BL31 via a SMC, and on receipt the
- SPD service handler invokes the synchronous call return mechanism to return
- to the BL32 initialization function. On return from this function,
- `bl31_main()` will set up the return to the normal world firmware BL33 and
- continue the boot process in the normal world.
-
-
-6. Crash Reporting in BL31
-----------------------------
-
-BL31 implements a scheme for reporting the processor state when an unhandled
-exception is encountered. The reporting mechanism attempts to preserve all the
-register contents and report it via a dedicated UART (PL011 console). BL31
-reports the general purpose, EL3, Secure EL1 and some EL2 state registers.
-
-A dedicated per-CPU crash stack is maintained by BL31 and this is retrieved via
-the per-CPU pointer cache. The implementation attempts to minimise the memory
-required for this feature. The file `crash_reporting.S` contains the
-implementation for crash reporting.
-
-The sample crash output is shown below.
-
- x0 :0x000000004F00007C
- x1 :0x0000000007FFFFFF
- x2 :0x0000000004014D50
- x3 :0x0000000000000000
- x4 :0x0000000088007998
- x5 :0x00000000001343AC
- x6 :0x0000000000000016
- x7 :0x00000000000B8A38
- x8 :0x00000000001343AC
- x9 :0x00000000000101A8
- x10 :0x0000000000000002
- x11 :0x000000000000011C
- x12 :0x00000000FEFDC644
- x13 :0x00000000FED93FFC
- x14 :0x0000000000247950
- x15 :0x00000000000007A2
- x16 :0x00000000000007A4
- x17 :0x0000000000247950
- x18 :0x0000000000000000
- x19 :0x00000000FFFFFFFF
- x20 :0x0000000004014D50
- x21 :0x000000000400A38C
- x22 :0x0000000000247950
- x23 :0x0000000000000010
- x24 :0x0000000000000024
- x25 :0x00000000FEFDC868
- x26 :0x00000000FEFDC86A
- x27 :0x00000000019EDEDC
- x28 :0x000000000A7CFDAA
- x29 :0x0000000004010780
- x30 :0x000000000400F004
- scr_el3 :0x0000000000000D3D
- sctlr_el3 :0x0000000000C8181F
- cptr_el3 :0x0000000000000000
- tcr_el3 :0x0000000080803520
- daif :0x00000000000003C0
- mair_el3 :0x00000000000004FF
- spsr_el3 :0x00000000800003CC
- elr_el3 :0x000000000400C0CC
- ttbr0_el3 :0x00000000040172A0
- esr_el3 :0x0000000096000210
- sp_el3 :0x0000000004014D50
- far_el3 :0x000000004F00007C
- spsr_el1 :0x0000000000000000
- elr_el1 :0x0000000000000000
- spsr_abt :0x0000000000000000
- spsr_und :0x0000000000000000
- spsr_irq :0x0000000000000000
- spsr_fiq :0x0000000000000000
- sctlr_el1 :0x0000000030C81807
- actlr_el1 :0x0000000000000000
- cpacr_el1 :0x0000000000300000
- csselr_el1 :0x0000000000000002
- sp_el1 :0x0000000004028800
- esr_el1 :0x0000000000000000
- ttbr0_el1 :0x000000000402C200
- ttbr1_el1 :0x0000000000000000
- mair_el1 :0x00000000000004FF
- amair_el1 :0x0000000000000000
- tcr_el1 :0x0000000000003520
- tpidr_el1 :0x0000000000000000
- tpidr_el0 :0x0000000000000000
- tpidrro_el0 :0x0000000000000000
- dacr32_el2 :0x0000000000000000
- ifsr32_el2 :0x0000000000000000
- par_el1 :0x0000000000000000
- far_el1 :0x0000000000000000
- afsr0_el1 :0x0000000000000000
- afsr1_el1 :0x0000000000000000
- contextidr_el1 :0x0000000000000000
- vbar_el1 :0x0000000004027000
- cntp_ctl_el0 :0x0000000000000000
- cntp_cval_el0 :0x0000000000000000
- cntv_ctl_el0 :0x0000000000000000
- cntv_cval_el0 :0x0000000000000000
- cntkctl_el1 :0x0000000000000000
- fpexc32_el2 :0x0000000004000700
- sp_el0 :0x0000000004010780
-
-7. Guidelines for Reset Handlers
----------------------------------
-
-Trusted Firmware implements a framework that allows CPU and platform ports to
-perform actions very early after a CPU is released from reset in both the cold
-and warm boot paths. This is done by calling the `reset_handler()` function in
-both the BL1 and BL31 images. It in turn calls the platform and CPU specific
-reset handling functions.
-
-Details for implementing a CPU specific reset handler can be found in
-Section 8. Details for implementing a platform specific reset handler can be
-found in the [Porting Guide] (see the `plat_reset_handler()` function).
-
-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
-invocations of the reset handling code, this should be detected at runtime.
-In other words, the reset handler should be able to detect whether an action has
-already been performed and act as appropriate. Possible courses of actions are,
-e.g. skip the action the second time, or undo/redo it.
-
-8. CPU specific operations framework
--------------------------------------
-
-Certain aspects of the ARMv8 architecture are implementation defined,
-that is, certain behaviours are not architecturally defined, but must be defined
-and documented by individual processor implementations. The ARM Trusted
-Firmware implements a framework which categorises the common implementation
-defined behaviours and allows a processor to export its implementation of that
-behaviour. The categories are:
-
-1. Processor specific reset sequence.
-
-2. Processor specific power down sequences.
-
-3. Processor specific register dumping as a part of crash reporting.
-
-4. Errata status reporting.
-
-Each of the above categories fulfils a different requirement.
-
-1. allows any processor specific initialization before the caches and MMU
- are turned on, like implementation of errata workarounds, entry into
- the intra-cluster coherency domain etc.
-
-2. allows each processor to implement the power down sequence mandated in
- its Technical Reference Manual (TRM).
-
-3. allows a processor to provide additional information to the developer
- in the event of a crash, for example Cortex-A53 has registers which
- can expose the data cache contents.
-
-4. allows a processor to define a function that inspects and reports the status
- of all errata workarounds on that processor.
-
-Please note that only 2. is mandated by the TRM.
-
-The CPU specific operations framework scales to accommodate a large number of
-different CPUs during power down and reset handling. The platform can specify
-any CPU optimization it wants to enable for each CPU. It can also specify
-the CPU errata workarounds to be applied for each CPU type during reset
-handling by defining CPU errata compile time macros. Details on these macros
-can be found in the [cpu-specific-build-macros.md][CPUBM] file.
-
-The CPU specific operations framework depends on the `cpu_ops` structure which
-needs to be exported for each type of CPU in the platform. It is defined in
-`include/lib/cpus/aarch64/cpu_macros.S` and has the following fields : `midr`,
-`reset_func()`, `cpu_pwr_down_ops` (array of power down functions) and
-`cpu_reg_dump()`.
-
-The CPU specific files in `lib/cpus` export a `cpu_ops` data structure with
-suitable handlers for that CPU. For example, `lib/cpus/aarch64/cortex_a53.S`
-exports the `cpu_ops` for Cortex-A53 CPU. According to the platform
-configuration, these CPU specific files must be included in the build by
-the platform makefile. The generic CPU specific operations framework code exists
-in `lib/cpus/aarch64/cpu_helpers.S`.
-
-### CPU specific Reset Handling
-
-After a reset, the state of the CPU when it calls generic reset handler is:
-MMU turned off, both instruction and data caches turned off and not part
-of any coherency domain.
-
-The BL entrypoint code first invokes the `plat_reset_handler()` to allow
-the platform to perform any system initialization required and any system
-errata workarounds that needs to be applied. The `get_cpu_ops_ptr()` reads
-the current CPU midr, finds the matching `cpu_ops` entry in the `cpu_ops`
-array and returns it. Note that only the part number and implementer fields
-in midr are used to find the matching `cpu_ops` entry. The `reset_func()` in
-the returned `cpu_ops` is then invoked which executes the required reset
-handling for that CPU and also any errata workarounds enabled by the platform.
-This function must preserve the values of general purpose registers x20 to x29.
-
-Refer to Section "Guidelines for Reset Handlers" for general guidelines
-regarding placement of code in a reset handler.
-
-### CPU specific power down sequence
-
-During the BL31 initialization sequence, the pointer to the matching `cpu_ops`
-entry is stored in per-CPU data by `init_cpu_ops()` so that it can be quickly
-retrieved during power down sequences.
-
-Various CPU drivers register handlers to perform power down at certain power
-levels for that specific CPU. The PSCI service, upon receiving a power down
-request, determines the highest power level at which to execute power down
-sequence for a particular CPU. It uses the `prepare_cpu_pwr_dwn()` function to
-pick the right power down handler for the requested level. The function
-retrieves `cpu_ops` pointer member of per-CPU data, and from that, further
-retrieves `cpu_pwr_down_ops` array, and indexes into the required level. If the
-requested power level is higher than what a CPU driver supports, the handler
-registered for highest level is invoked.
-
-At runtime the platform hooks for power down are invoked by the PSCI service to
-perform platform specific operations during a power down sequence, for example
-turning off CCI coherency during a cluster power down.
-
-### CPU specific register reporting during crash
-
-If the crash reporting is enabled in BL31, when a crash occurs, the crash
-reporting framework calls `do_cpu_reg_dump` which retrieves the matching
-`cpu_ops` using `get_cpu_ops_ptr()` function. The `cpu_reg_dump()` in
-`cpu_ops` is invoked, which then returns the CPU specific register values to
-be reported and a pointer to the ASCII list of register names in a format
-expected by the crash reporting framework.
-
-### CPU errata status reporting
-
-Errata workarounds for CPUs supported in ARM Trusted Firmware are applied during
-both cold and warm boots, shortly after reset. Individual Errata workarounds are
-enabled as build options. Some errata workarounds have potential run-time
-implications; therefore some are enabled by default, others not. Platform ports
-shall override build options to enable or disable errata as appropriate. The CPU
-drivers take care of applying errata workarounds that are enabled and applicable
-to a given CPU. Refer to the section titled _CPU Errata Workarounds_ in [CPUBM]
-for more information.
-
-Functions in CPU drivers that apply errata workaround must follow the
-conventions listed below.
-
-The errata workaround must be authored as two separate functions:
-
-* One that checks for errata. This function must determine whether that errata
- applies to the current CPU. Typically this involves matching the current
- CPUs revision and variant against a value that's known to be affected by the
- errata. If the function determines that the errata applies to this CPU, it
- must return `ERRATA_APPLIES`; otherwise, it must return
- `ERRATA_NOT_APPLIES`. The utility functions `cpu_get_rev_var` and
- `cpu_rev_var_ls` functions may come in handy for this purpose.
-
- For an errata identified as `E`, the check function must be named
- `check_errata_E`.
-
- This function will be invoked at different times, both from assembly and from
- C run time. Therefore it must follow AAPCS, and must not use stack.
-
-* Another one that applies the errata workaround. This function would call the
- check function described above, and applies errata workaround if required.
-
-CPU drivers that apply errata workaround can optionally implement an assembly
-function that report the status of errata workarounds pertaining to that CPU.
-For a driver that registers the CPU, for example, `cpux` via. `declare_cpu_ops`
-macro, the errata reporting function, if it exists, must be named
-`cpux_errata_report`. This function will always be called with MMU enabled; it
-must follow AAPCS and may use stack.
-
-In a debug build of ARM Trusted Firmware, on a CPU that comes out of reset, both
-BL1 and the run time firmware (BL31 in AArch64, and BL32 in AArch32) will invoke
-errata status reporting function, if one exists, for that type of CPU.
-
-To report the status of each errata workaround, the function shall use the
-assembler macro `report_errata`, passing it:
-
-* The build option that enables the errata;
-
-* The name of the CPU: this must be the same identifier that CPU driver
- registered itself with, using `declare_cpu_ops`;
-
-* And the errata identifier: the identifier must match what's used in the
- errata's check function described above.
-
-The errata status reporting function will be called once per CPU type/errata
-combination during the software's active life time.
-
-It's expected that whenever an errata workaround is submitted to ARM Trusted
-Firmware, the errata reporting function is appropriately extended to report its
-status as well.
-
-Reporting the status of errata workaround is for informational purpose only; it
-has no functional significance.
-
-9. Memory layout of BL images
------------------------------
-
-Each bootloader image can be divided in 2 parts:
-
- * the static contents of the image. These are data actually stored in the
- binary on the disk. In the ELF terminology, they are called `PROGBITS`
- sections;
-
- * the run-time contents of the image. These are data that don't occupy any
- space in the binary on the disk. The ELF binary just contains some
- metadata indicating where these data will be stored at run-time and the
- corresponding sections need to be allocated and initialized at run-time.
- In the ELF terminology, they are called `NOBITS` sections.
-
-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
-and it is governed by the linker scripts. This ensures that the raw binary
-images are as small as possible. If a NOBITS section was inserted in between
-PROGBITS sections then the resulting binary file would contain zero bytes in
-place of this NOBITS section, making the image unnecessarily bigger. Smaller
-images allow faster loading from the FIP to the main memory.
-
-### Linker scripts and symbols
-
-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
-correspond to particular addresses. The trusted firmware code can refer to these
-symbols to figure out the image memory layout.
-
-Linker symbols follow the following naming convention in the trusted firmware.
-
-* `__<SECTION>_START__`
-
- Start address of a given section named `<SECTION>`.
-
-* `__<SECTION>_END__`
-
- End address of a given section named `<SECTION>`. If there is an alignment
- constraint on the section's end address then `__<SECTION>_END__` corresponds
- 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
- actual end address of the section's contents.
-
-* `__<SECTION>_UNALIGNED_END__`
-
- End address of a given section named `<SECTION>` without any padding or
- rounding up due to some alignment constraint.
-
-* `__<SECTION>_SIZE__`
-
- Size (in bytes) of a given section named `<SECTION>`. If there is an
- alignment constraint on the section's end address then `__<SECTION>_SIZE__`
- corresponds to the size of the section's actual contents, rounded up to the
- right boundary. In other words, `__<SECTION>_SIZE__ = __<SECTION>_END__ -
- _<SECTION>_START__`. Refer to the value of `__<SECTION>_UNALIGNED_SIZE__`
- to know the actual size of the section's contents.
-
-* `__<SECTION>_UNALIGNED_SIZE__`
-
- Size (in bytes) of a given section named `<SECTION>` without any padding or
- rounding up due to some alignment constraint. In other words,
- `__<SECTION>_UNALIGNED_SIZE__ = __<SECTION>_UNALIGNED_END__ -
- __<SECTION>_START__`.
-
-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
-must be provided for each bootloader stage and some are specific to a given
-bootloader stage.
-
-The linker scripts define some extra, optional symbols. They are not actually
-used by any code but they help in understanding the bootloader images' memory
-layout as they are easy to spot in the link map files.
-
-#### Common linker symbols
-
-All BL images share the following requirements:
-
-* The BSS section must be zero-initialised before executing any C code.
-* The coherent memory section (if enabled) must be zero-initialised as well.
-* The MMU setup code needs to know the extents of the coherent and read-only
- memory regions to set the right memory attributes. When
- `SEPARATE_CODE_AND_RODATA=1`, it needs to know more specifically how the
- read-only memory region is divided between code and data.
-
-The following linker symbols are defined for this purpose:
-
-* `__BSS_START__`
-* `__BSS_SIZE__`
-* `__COHERENT_RAM_START__` Must be aligned on a page-size boundary.
-* `__COHERENT_RAM_END__` Must be aligned on a page-size boundary.
-* `__COHERENT_RAM_UNALIGNED_SIZE__`
-* `__RO_START__`
-* `__RO_END__`
-* `__TEXT_START__`
-* `__TEXT_END__`
-* `__RODATA_START__`
-* `__RODATA_END__`
-
-#### BL1's linker symbols
-
-BL1 being the ROM image, it has additional requirements. BL1 resides in ROM and
-it is entirely executed in place but it needs some read-write memory for its
-mutable data. Its `.data` section (i.e. its allocated read-write data) must be
-relocated from ROM to RAM before executing any C code.
-
-The following additional linker symbols are defined for BL1:
-
-* `__BL1_ROM_END__` End address of BL1's ROM contents, covering its code
- and `.data` section in ROM.
-* `__DATA_ROM_START__` Start address of the `.data` section in ROM. Must be
- aligned on a 16-byte boundary.
-* `__DATA_RAM_START__` Address in RAM where the `.data` section should be
- copied over. Must be aligned on a 16-byte boundary.
-* `__DATA_SIZE__` Size of the `.data` section (in ROM or RAM).
-* `__BL1_RAM_START__` Start address of BL1 read-write data.
-* `__BL1_RAM_END__` End address of BL1 read-write data.
-
-
-### How to choose the right base addresses for each bootloader stage image
-
-There is currently no support for dynamic image loading in the Trusted Firmware.
-This means that all bootloader images need to be linked against their ultimate
-runtime locations and the base addresses of each image must be chosen carefully
-such that images don't overlap each other in an undesired way. As the code
-grows, the base addresses might need adjustments to cope with the new memory
-layout.
-
-The memory layout is completely specific to the platform and so there is no
-general recipe for choosing the right base addresses for each bootloader image.
-However, there are tools to aid in understanding the memory layout. These are
-the link map files: `build/<platform>/<build-type>/bl<x>/bl<x>.map`, with `<x>`
-being the stage bootloader. They provide a detailed view of the memory usage of
-each image. Among other useful information, they provide the end address of
-each image.
-
-* `bl1.map` link map file provides `__BL1_RAM_END__` address.
-* `bl2.map` link map file provides `__BL2_END__` address.
-* `bl31.map` link map file provides `__BL31_END__` address.
-* `bl32.map` link map file provides `__BL32_END__` address.
-
-For each bootloader image, the platform code must provide its start address
-as well as a limit address that it must not overstep. The latter is used in the
-linker scripts to check that the image doesn't grow past that address. If that
-happens, the linker will issue a message similar to the following:
-
- aarch64-none-elf-ld: BLx has exceeded its limit.
-
-Additionally, if the platform memory layout implies some image overlaying like
-on FVP, BL31 and TSP need to know the limit address that their PROGBITS
-sections must not overstep. The platform code must provide those.
-
-When LOAD_IMAGE_V2 is disabled, Trusted Firmware provides a mechanism to
-verify at boot time that the memory to load a new image is free to prevent
-overwriting a previously loaded image. For this mechanism to work, the platform
-must specify the memory available in the system as regions, where each region
-consists of base address, total size and the free area within it (as defined
-in the `meminfo_t` structure). Trusted Firmware retrieves these memory regions
-by calling the corresponding platform API:
-
-* `meminfo_t *bl1_plat_sec_mem_layout(void)`
-* `meminfo_t *bl2_plat_sec_mem_layout(void)`
-* `void bl2_plat_get_scp_bl2_meminfo(meminfo_t *scp_bl2_meminfo)`
-* `void bl2_plat_get_bl32_meminfo(meminfo_t *bl32_meminfo)`
-* `void bl2_plat_get_bl33_meminfo(meminfo_t *bl33_meminfo)`
-
-For example, in the case of BL1 loading BL2, `bl1_plat_sec_mem_layout()` will
-return the region defined by the platform where BL1 intends to load BL2. The
-`load_image()` function will check that the memory where BL2 will be loaded is
-within the specified region and marked as free.
-
-The actual number of regions and their base addresses and sizes is platform
-specific. The platform may return the same region or define a different one for
-each API. However, the overlap verification mechanism applies only to a single
-region. Hence, it is the platform responsibility to guarantee that different
-regions do not overlap, or that if they do, the overlapping images are not
-accessed at the same time. This could be used, for example, to load temporary
-images (e.g. certificates) or firmware images prior to being transfered to its
-corresponding processor (e.g. the SCP BL2 image).
-
-To reduce fragmentation and simplify the tracking of free memory, all the free
-memory within a region is always located in one single buffer defined by its
-base address and size. Trusted Firmware implements a top/bottom load approach:
-after a new image is loaded, it checks how much memory remains free above and
-below the image. The smallest area is marked as unavailable, while the larger
-area becomes the new free memory buffer. Platforms should take this behaviour
-into account when defining the base address for each of the images. For example,
-if an image is loaded near the middle of the region, small changes in image size
-could cause a flip between a top load and a bottom load, which may result in an
-unexpected memory layout.
-
-The following diagram is an example of an image loaded in the bottom part of
-the memory region. The region is initially free (nothing has been loaded yet):
-
- Memory region
- +----------+
- | |
- | | <<<<<<<<<<<<< Free
- | |
- |----------| +------------+
- | image | <<<<<<<<<<<<< | image |
- |----------| +------------+
- | xxxxxxxx | <<<<<<<<<<<<< Marked as unavailable
- +----------+
-
-And the following diagram is an example of an image loaded in the top part:
-
- Memory region
- +----------+
- | xxxxxxxx | <<<<<<<<<<<<< Marked as unavailable
- |----------| +------------+
- | image | <<<<<<<<<<<<< | image |
- |----------| +------------+
- | |
- | | <<<<<<<<<<<<< Free
- | |
- +----------+
-
-
-When LOAD_IMAGE_V2 is enabled, Trusted Firmware does not provide any mechanism
-to verify at boot time that the memory to load a new image is free to prevent
-overwriting a previously loaded image. The platform must specify the memory
-available in the system for all the relevant BL images to be loaded.
-
-For example, in the case of BL1 loading BL2, `bl1_plat_sec_mem_layout()` will
-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
-base and maximum image size provided by the platforms. Platforms must take
-this behaviour into account when defining the base/size for each of the images.
-
-#### Memory layout on ARM development platforms
-
-The following list describes the memory layout on the ARM development platforms:
-
-* A 4KB page of shared memory is used for communication between Trusted
- Firmware and the platform's power controller. This is located at the base of
- Trusted SRAM. The amount of Trusted SRAM available to load the bootloader
- images is reduced by the size of the shared memory.
-
- The shared memory is used to store the CPUs' entrypoint mailbox. On Juno,
- this is also used for the MHU payload when passing messages to and from the
- SCP.
-
-* On FVP, BL1 is originally sitting in the Trusted ROM at address `0x0`. On
- Juno, BL1 resides in flash memory at address `0x0BEC0000`. BL1 read-write
- 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),
- is loaded at the top of the Trusted SRAM, such that its NOBITS sections will
- overwrite BL1 R/W data. This implies that BL1 global variables remain valid
- only until execution reaches the EL3 Runtime Software entry point during a
- cold boot.
-
-* BL2 is loaded below EL3 Runtime Software.
-
-* On Juno, SCP_BL2 is loaded temporarily into the EL3 Runtime Software memory
- region and transfered to the SCP before being overwritten by EL3 Runtime
- Software.
-
-* BL32 (for AArch64) can be loaded in one of the following locations:
-
- * Trusted SRAM
- * Trusted DRAM (FVP only)
- * Secure region of DRAM (top 16MB of DRAM configured by the TrustZone
- controller)
-
- When BL32 (for AArch64) is loaded into Trusted SRAM, its NOBITS sections
- are allowed to overlay BL2. This memory layout is designed to give the
- BL32 image as much memory as possible when it is loaded into Trusted SRAM.
-
-When LOAD_IMAGE_V2 is disabled the memory regions for the overlap detection
-mechanism at boot time are defined as follows (shown per API):
-
-* `meminfo_t *bl1_plat_sec_mem_layout(void)`
-
- This region corresponds to the whole Trusted SRAM except for the shared
- memory at the base. This region is initially free. At boot time, BL1 will
- mark the BL1(rw) section within this region as occupied. The BL1(rw) section
- is placed at the top of Trusted SRAM.
-
-* `meminfo_t *bl2_plat_sec_mem_layout(void)`
-
- This region corresponds to the whole Trusted SRAM as defined by
- `bl1_plat_sec_mem_layout()`, but with the BL1(rw) section marked as
- occupied. This memory region is used to check that BL2 and BL31 do not
- overlap with each other. BL2_BASE and BL1_RW_BASE are carefully chosen so
- that the memory for BL31 is top loaded above BL2.
-
-* `void bl2_plat_get_scp_bl2_meminfo(meminfo_t *scp_bl2_meminfo)`
-
- This region is an exact copy of the region defined by
- `bl2_plat_sec_mem_layout()`. Being a disconnected copy means that all the
- changes made to this region by the Trusted Firmware will not be propagated.
- This approach is valid because the SCP BL2 image is loaded temporarily
- while it is being transferred to the SCP, so this memory is reused
- afterwards.
-
-* `void bl2_plat_get_bl32_meminfo(meminfo_t *bl32_meminfo)`
-
- This region depends on the location of the BL32 image. Currently, ARM
- platforms support three different locations (detailed below): Trusted SRAM,
- Trusted DRAM and the TZC-Secured DRAM.
-
-* `void bl2_plat_get_bl33_meminfo(meminfo_t *bl33_meminfo)`
-
- This region corresponds to the Non-Secure DDR-DRAM, excluding the
- TZC-Secured area.
-
-The location of the BL32 image will result in different memory maps. This is
-illustrated for both FVP and Juno in the following diagrams, using the TSP as
-an example.
-
-Note: Loading the BL32 image in TZC secured DRAM doesn't change the memory
-layout of the other images in Trusted SRAM.
-
-**FVP with TSP in Trusted SRAM (default option):**
-(These diagrams only cover the AArch64 case)
-
- Trusted SRAM
- 0x04040000 +----------+ loaded by BL2 ------------------
- | BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS |
- |----------| <<<<<<<<<<<<< |----------------|
- | | <<<<<<<<<<<<< | BL31 PROGBITS |
- |----------| ------------------
- | BL2 | <<<<<<<<<<<<< | BL32 NOBITS |
- |----------| <<<<<<<<<<<<< |----------------|
- | | <<<<<<<<<<<<< | BL32 PROGBITS |
- 0x04001000 +----------+ ------------------
- | Shared |
- 0x04000000 +----------+
-
- Trusted ROM
- 0x04000000 +----------+
- | BL1 (ro) |
- 0x00000000 +----------+
-
-
-**FVP with TSP in Trusted DRAM:**
-
- Trusted DRAM
- 0x08000000 +----------+
- | BL32 |
- 0x06000000 +----------+
-
- Trusted SRAM
- 0x04040000 +----------+ loaded by BL2 ------------------
- | BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS |
- |----------| <<<<<<<<<<<<< |----------------|
- | | <<<<<<<<<<<<< | BL31 PROGBITS |
- |----------| ------------------
- | BL2 |
- |----------|
- | |
- 0x04001000 +----------+
- | Shared |
- 0x04000000 +----------+
-
- Trusted ROM
- 0x04000000 +----------+
- | BL1 (ro) |
- 0x00000000 +----------+
-
-**FVP with TSP in TZC-Secured DRAM:**
-
- DRAM
- 0xffffffff +----------+
- | BL32 | (secure)
- 0xff000000 +----------+
- | |
- : : (non-secure)
- | |
- 0x80000000 +----------+
-
- Trusted SRAM
- 0x04040000 +----------+ loaded by BL2 ------------------
- | BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS |
- |----------| <<<<<<<<<<<<< |----------------|
- | | <<<<<<<<<<<<< | BL31 PROGBITS |
- |----------| ------------------
- | BL2 |
- |----------|
- | |
- 0x04001000 +----------+
- | Shared |
- 0x04000000 +----------+
-
- Trusted ROM
- 0x04000000 +----------+
- | BL1 (ro) |
- 0x00000000 +----------+
-
-
-**Juno with BL32 in Trusted SRAM (default option):**
-
- Flash0
- 0x0C000000 +----------+
- : :
- 0x0BED0000 |----------|
- | BL1 (ro) |
- 0x0BEC0000 |----------|
- : :
- 0x08000000 +----------+ BL31 is loaded
- after SCP_BL2 has
- Trusted SRAM been sent to SCP
- 0x04040000 +----------+ loaded by BL2 ------------------
- | BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS |
- |----------| <<<<<<<<<<<<< |----------------|
- | SCP_BL2 | <<<<<<<<<<<<< | BL31 PROGBITS |
- |----------| ------------------
- | BL2 | <<<<<<<<<<<<< | BL32 NOBITS |
- |----------| <<<<<<<<<<<<< |----------------|
- | | <<<<<<<<<<<<< | BL32 PROGBITS |
- 0x04001000 +----------+ ------------------
- | MHU |
- 0x04000000 +----------+
-
-
-**Juno with BL32 in TZC-secured DRAM:**
-
- DRAM
- 0xFFE00000 +----------+
- | BL32 | (secure)
- 0xFF000000 |----------|
- | |
- : : (non-secure)
- | |
- 0x80000000 +----------+
-
- Flash0
- 0x0C000000 +----------+
- : :
- 0x0BED0000 |----------|
- | BL1 (ro) |
- 0x0BEC0000 |----------|
- : :
- 0x08000000 +----------+ BL31 is loaded
- after SCP_BL2 has
- Trusted SRAM been sent to SCP
- 0x04040000 +----------+ loaded by BL2 ------------------
- | BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS |
- |----------| <<<<<<<<<<<<< |----------------|
- | SCP_BL2 | <<<<<<<<<<<<< | BL31 PROGBITS |
- |----------| ------------------
- | BL2 |
- |----------|
- | |
- 0x04001000 +----------+
- | MHU |
- 0x04000000 +----------+
-
-
-10. Firmware Image Package (FIP)
----------------------------------
-
-Using a Firmware Image Package (FIP) allows for packing bootloader images (and
-potentially other payloads) into a single archive that can be loaded by the ARM
-Trusted Firmware from non-volatile platform storage. A driver to load images
-from a FIP has been added to the storage layer and allows a package to be read
-from supported platform storage. A tool to create Firmware Image Packages is
-also provided and described below.
-
-### Firmware Image Package layout
-
-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
-terminated by an end marker entry. All ToC entries describe some payload data
-that has been appended to the end of the binary package. With the information
-provided in the ToC entry the corresponding payload data can be retrieved.
-
- ------------------
- | ToC Header |
- |----------------|
- | ToC Entry 0 |
- |----------------|
- | ToC Entry 1 |
- |----------------|
- | ToC End Marker |
- |----------------|
- | |
- | Data 0 |
- | |
- |----------------|
- | |
- | Data 1 |
- | |
- ------------------
-
-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
-tool and the ARM Trusted firmware.
-
-The ToC header has the following fields:
-
- `name`: The name of the ToC. This is currently used to validate the header.
- `serial_number`: A non-zero number provided by the creation tool
- `flags`: Flags associated with this data.
- Bits 0-31: Reserved
- Bits 32-47: Platform defined
- Bits 48-63: Reserved
-
-A ToC entry has the following fields:
-
- `uuid`: All files are referred to by a pre-defined Universally Unique
- IDentifier [UUID] . The UUIDs are defined in
- `include/tools_share/firmware_image_package.h`. The platform translates
- the requested image name into the corresponding UUID when accessing the
- package.
- `offset_address`: The offset address at which the corresponding payload data
- can be found. The offset is calculated from the ToC base address.
- `size`: The size of the corresponding payload data in bytes.
- `flags`: Flags associated with this entry. Non are yet defined.
-
-### Firmware Image Package creation tool
-
-The FIP creation tool can be used to pack specified images into a binary package
-that can be loaded by the ARM Trusted Firmware from platform storage. The tool
-currently only supports packing bootloader images. Additional image definitions
-can be added to the tool as required.
-
-The tool can be found in `tools/fiptool`.
-
-### Loading from a Firmware Image Package (FIP)
-
-The Firmware Image Package (FIP) driver can load images from a binary package on
-non-volatile platform storage. For the ARM development platforms, this is
-currently NOR FLASH.
-
-Bootloader images are loaded according to the platform policy as specified by
-the function `plat_get_image_source()`. For the ARM development platforms, this
-means the platform will attempt to load images from a Firmware Image Package
-located at the start of NOR FLASH0.
-
-The ARM development platforms' policy is to only allow loading of a known set of
-images. The platform policy can be modified to allow additional images.
-
-
-11. Use of coherent memory in Trusted Firmware
------------------------------------------------
-
-There might be loss of coherency when physical memory with mismatched
-shareability, cacheability and memory attributes is accessed by multiple CPUs
-(refer to section B2.9 of [ARM ARM] for more details). This possibility occurs
-in Trusted Firmware during power up/down sequences when coherency, MMU and
-caches are turned on/off incrementally.
-
-Trusted Firmware defines coherent memory as a region of memory with Device
-nGnRE attributes in the translation tables. The translation granule size in
-Trusted Firmware is 4KB. This is the smallest possible size of the coherent
-memory region.
-
-By default, all data structures which are susceptible to accesses with
-mismatched attributes from various CPUs are allocated in a coherent memory
-region (refer to section 2.1 of [Porting Guide]). The coherent memory region
-accesses are Outer Shareable, non-cacheable and they can be accessed
-with the Device nGnRE attributes when the MMU is turned on. Hence, at the
-expense of at least an extra page of memory, Trusted Firmware is able to work
-around coherency issues due to mismatched memory attributes.
-
-The alternative to the above approach is to allocate the susceptible data
-structures in Normal WriteBack WriteAllocate Inner shareable memory. This
-approach requires the data structures to be designed so that it is possible to
-work around the issue of mismatched memory attributes by performing software
-cache maintenance on them.
-
-### Disabling the use of coherent memory in Trusted Firmware
-
-It might be desirable to avoid the cost of allocating coherent memory on
-platforms which are memory constrained. Trusted Firmware enables inclusion of
-coherent memory in firmware images through the build flag `USE_COHERENT_MEM`.
-This flag is enabled by default. It can be disabled to choose the second
-approach described above.
-
-The below sections analyze the data structures allocated in the coherent memory
-region and the changes required to allocate them in normal memory.
-
-### Coherent memory usage in PSCI implementation
-
-The `psci_non_cpu_pd_nodes` data structure stores the platform's power domain
-tree information for state management of power domains. By default, this data
-structure is allocated in the coherent memory region in the Trusted Firmware
-because it can be accessed by multple CPUs, either with caches enabled or
-disabled.
-
- typedef struct non_cpu_pwr_domain_node {
- /*
- * Index of the first CPU power domain node level 0 which has this node
- * as its parent.
- */
- unsigned int cpu_start_idx;
-
- /*
- * Number of CPU power domains which are siblings of the domain indexed
- * by 'cpu_start_idx' i.e. all the domains in the range 'cpu_start_idx
- * -> cpu_start_idx + ncpus' have this node as their parent.
- */
- unsigned int ncpus;
-
- /*
- * Index of the parent power domain node.
- * TODO: Figure out whether to whether using pointer is more efficient.
- */
- unsigned int parent_node;
-
- plat_local_state_t local_state;
-
- unsigned char level;
-
- /* For indexing the psci_lock array*/
- unsigned char lock_index;
- } non_cpu_pd_node_t;
-
-In order to move this data structure to normal memory, the use of each of its
-fields must be analyzed. Fields like `cpu_start_idx`, `ncpus`, `parent_node`
-`level` and `lock_index` are only written once during cold boot. Hence removing
-them from coherent memory involves only doing a clean and invalidate of the
-cache lines after these fields are written.
-
-The field `local_state` can be concurrently accessed by multiple CPUs in
-different cache states. A Lamport's Bakery lock `psci_locks` is used to ensure
-mutual exlusion to this field and a clean and invalidate is needed after it
-is written.
-
-### Bakery lock data
-
-The bakery lock data structure `bakery_lock_t` is allocated in coherent memory
-and is accessed by multiple CPUs with mismatched attributes. `bakery_lock_t` is
-defined as follows:
-
- typedef struct bakery_lock {
- /*
- * The lock_data is a bit-field of 2 members:
- * Bit[0] : choosing. This field is set when the CPU is
- * choosing its bakery number.
- * Bits[1 - 15] : number. This is the bakery number allocated.
- */
- volatile uint16_t lock_data[BAKERY_LOCK_MAX_CPUS];
- } bakery_lock_t;
-
-It is a characteristic of Lamport's Bakery algorithm that the volatile per-CPU
-fields can be read by all CPUs but only written to by the owning CPU.
-
-Depending upon the data cache line size, the per-CPU fields of the
-`bakery_lock_t` structure for multiple CPUs may exist on a single cache line.
-These per-CPU fields can be read and written during lock contention by multiple
-CPUs with mismatched memory attributes. Since these fields are a part of the
-lock implementation, they do not have access to any other locking primitive to
-safeguard against the resulting coherency issues. As a result, simple software
-cache maintenance is not enough to allocate them in coherent memory. Consider
-the following example.
-
-CPU0 updates its per-CPU field with data cache enabled. This write updates a
-local cache line which contains a copy of the fields for other CPUs as well. Now
-CPU1 updates its per-CPU field of the `bakery_lock_t` structure with data cache
-disabled. CPU1 then issues a DCIVAC operation to invalidate any stale copies of
-its field in any other cache line in the system. This operation will invalidate
-the update made by CPU0 as well.
-
-To use bakery locks when `USE_COHERENT_MEM` is disabled, the lock data structure
-has been redesigned. The changes utilise the characteristic of Lamport's Bakery
-algorithm mentioned earlier. The bakery_lock structure only allocates the memory
-for a single CPU. The macro `DEFINE_BAKERY_LOCK` allocates all the bakery locks
-needed for a CPU into a section `bakery_lock`. The linker allocates the memory
-for other cores by using the total size allocated for the bakery_lock section
-and multiplying it with (PLATFORM_CORE_COUNT - 1). This enables software to
-perform software cache maintenance on the lock data structure without running
-into coherency issues associated with mismatched attributes.
-
-The bakery lock data structure `bakery_info_t` is defined for use when
-`USE_COHERENT_MEM` is disabled as follows:
-
- typedef struct bakery_info {
- /*
- * The lock_data is a bit-field of 2 members:
- * Bit[0] : choosing. This field is set when the CPU is
- * choosing its bakery number.
- * Bits[1 - 15] : number. This is the bakery number allocated.
- */
- volatile uint16_t lock_data;
- } bakery_info_t;
-
-The `bakery_info_t` represents a single per-CPU field of one lock and
-the combination of corresponding `bakery_info_t` structures for all CPUs in the
-system represents the complete bakery lock. The view in memory for a system
-with n bakery locks are:
-
- bakery_lock section start
- |----------------|
- | `bakery_info_t`| <-- Lock_0 per-CPU field
- | Lock_0 | for CPU0
- |----------------|
- | `bakery_info_t`| <-- Lock_1 per-CPU field
- | Lock_1 | for CPU0
- |----------------|
- | .... |
- |----------------|
- | `bakery_info_t`| <-- Lock_N per-CPU field
- | Lock_N | for CPU0
- ------------------
- | XXXXX |
- | Padding to |
- | next Cache WB | <--- Calculate PERCPU_BAKERY_LOCK_SIZE, allocate
- | Granule | continuous memory for remaining CPUs.
- ------------------
- | `bakery_info_t`| <-- Lock_0 per-CPU field
- | Lock_0 | for CPU1
- |----------------|
- | `bakery_info_t`| <-- Lock_1 per-CPU field
- | Lock_1 | for CPU1
- |----------------|
- | .... |
- |----------------|
- | `bakery_info_t`| <-- Lock_N per-CPU field
- | Lock_N | for CPU1
- ------------------
- | XXXXX |
- | Padding to |
- | next Cache WB |
- | Granule |
- ------------------
-
-Consider a system of 2 CPUs with 'N' bakery locks as shown above. For an
-operation on Lock_N, the corresponding `bakery_info_t` in both CPU0 and CPU1
-`bakery_lock` section need to be fetched and appropriate cache operations need
-to be performed for each access.
-
-On ARM Platforms, bakery locks are used in psci (`psci_locks`) and power controller
-driver (`arm_lock`).
-
-
-### Non Functional Impact of removing coherent memory
-
-Removal of the coherent memory region leads to the additional software overhead
-of performing cache maintenance for the affected data structures. However, since
-the memory where the data structures are allocated is cacheable, the overhead is
-mostly mitigated by an increase in performance.
-
-There is however a performance impact for bakery locks, due to:
-* Additional cache maintenance operations, and
-* Multiple cache line reads for each lock operation, since the bakery locks
- for each CPU are distributed across different cache lines.
-
-The implementation has been optimized to minimize this additional overhead.
-Measurements indicate that when bakery locks are allocated in Normal memory, the
-minimum latency of acquiring a lock is on an average 3-4 micro seconds whereas
-in Device memory the same is 2 micro seconds. The measurements were done on the
-Juno ARM development platform.
-
-As mentioned earlier, almost a page of memory can be saved by disabling
-`USE_COHERENT_MEM`. Each platform needs to consider these trade-offs to decide
-whether coherent memory should be used. If a platform disables
-`USE_COHERENT_MEM` and needs to use bakery locks in the porting layer, it can
-optionally define macro `PLAT_PERCPU_BAKERY_LOCK_SIZE` (see the [Porting
-Guide]). Refer to the reference platform code for examples.
-
-
-12. Isolating code and read-only data on separate memory pages
----------------------------------------------------------------
-
-In the ARMv8 VMSA, translation table entries include fields that define the
-properties of the target memory region, such as its access permissions. The
-smallest unit of memory that can be addressed by a translation table entry is
-a memory page. Therefore, if software needs to set different permissions on two
-memory regions then it needs to map them using different memory pages.
-
-The default memory layout for each BL image is as follows:
-
- | ... |
- +-------------------+
- | Read-write data |
- +-------------------+ Page boundary
- | <Padding> |
- +-------------------+
- | Exception vectors |
- +-------------------+ 2 KB boundary
- | <Padding> |
- +-------------------+
- | Read-only data |
- +-------------------+
- | Code |
- +-------------------+ BLx_BASE
-
-Note: The 2KB alignment for the exception vectors is an architectural
-requirement.
-
-The read-write data start on a new memory page so that they can be mapped with
-read-write permissions, whereas the code and read-only data below are configured
-as read-only.
-
-However, the read-only data are not aligned on a page boundary. They are
-contiguous to the code. Therefore, the end of the code section and the beginning
-of the read-only data one might share a memory page. This forces both to be
-mapped with the same memory attributes. As the code needs to be executable, this
-means that the read-only data stored on the same memory page as the code are
-executable as well. This could potentially be exploited as part of a security
-attack.
-
-TF provides the build flag `SEPARATE_CODE_AND_RODATA` to isolate the code and
-read-only data on separate memory pages. This in turn allows independent control
-of the access permissions for the code and read-only data. In this case,
-platform code gets a finer-grained view of the image layout and can
-appropriately map the code region as executable and the read-only data as
-execute-never.
-
-This has an impact on memory footprint, as padding bytes need to be introduced
-between the code and read-only data to ensure the segragation of the two. To
-limit the memory cost, this flag also changes the memory layout such that the
-code and exception vectors are now contiguous, like so:
-
- | ... |
- +-------------------+
- | Read-write data |
- +-------------------+ Page boundary
- | <Padding> |
- +-------------------+
- | Read-only data |
- +-------------------+ Page boundary
- | <Padding> |
- +-------------------+
- | Exception vectors |
- +-------------------+ 2 KB boundary
- | <Padding> |
- +-------------------+
- | Code |
- +-------------------+ BLx_BASE
-
-With this more condensed memory layout, the separation of read-only data will
-add zero or one page to the memory footprint of each BL image. Each platform
-should consider the trade-off between memory footprint and security.
-
-This build flag is disabled by default, minimising memory footprint. On ARM
-platforms, it is enabled.
-
-
-13. Performance Measurement Framework
---------------------------------------
-
-The Performance Measurement Framework (PMF) facilitates collection of
-timestamps by registered services and provides interfaces to retrieve
-them from within the ARM Trusted Firmware. A platform can choose to
-expose appropriate SMCs to retrieve these collected timestamps.
-
-By default, the global physical counter is used for the timestamp
-value and is read via `CNTPCT_EL0`. The framework allows to retrieve
-timestamps captured by other CPUs.
-
-### Timestamp identifier format
-
-A PMF timestamp is uniquely identified across the system via the
-timestamp ID or `tid`. The `tid` is composed as follows:
-
- Bits 0-7: The local timestamp identifier.
- Bits 8-9: Reserved.
- Bits 10-15: The service identifier.
- Bits 16-31: Reserved.
-
-1. The service identifier. Each PMF service is identified by a
- service name and a service identifier. Both the service name and
- identifier are unique within the system as a whole.
-
-2. The local timestamp identifier. This identifier is unique within a given
- service.
-
-### Registering a PMF service
-
-To register a PMF service, the `PMF_REGISTER_SERVICE()` macro from `pmf.h`
-is used. The arguments required are the service name, the service ID,
-the total number of local timestamps to be captured and a set of flags.
-
-The `flags` field can be specified as a bitwise-OR of the following values:
-
- PMF_STORE_ENABLE: The timestamp is stored in memory for later retrieval.
- PMF_DUMP_ENABLE: The timestamp is dumped on the serial console.
-
-The `PMF_REGISTER_SERVICE()` reserves memory to store captured
-timestamps in a PMF specific linker section at build time.
-Additionally, it defines necessary functions to capture and
-retrieve a particular timestamp for the given service at runtime.
-
-The macro `PMF_REGISTER_SERVICE()` only enables capturing PMF
-timestamps from within ARM Trusted Firmware. In order to retrieve
-timestamps from outside of ARM Trusted Firmware, the
-`PMF_REGISTER_SERVICE_SMC()` macro must be used instead. This macro
-accepts the same set of arguments as the `PMF_REGISTER_SERVICE()`
-macro but additionally supports retrieving timestamps using SMCs.
-
-### Capturing a timestamp
-
-PMF timestamps are stored in a per-service timestamp region. On a
-system with multiple CPUs, each timestamp is captured and stored
-in a per-CPU cache line aligned memory region.
-
-Having registered the service, the `PMF_CAPTURE_TIMESTAMP()` macro can be
-used to capture a timestamp at the location where it is used. The macro
-takes the service name, a local timestamp identifier and a flag as arguments.
-
-The `flags` field argument can be zero, or `PMF_CACHE_MAINT` which
-instructs PMF to do cache maintenance following the capture. Cache
-maintenance is required if any of the service's timestamps are captured
-with data cache disabled.
-
-To capture a timestamp in assembly code, the caller should use
-`pmf_calc_timestamp_addr` macro (defined in `pmf_asm_macros.S`) to
-calculate the address of where the timestamp would be stored. The
-caller should then read `CNTPCT_EL0` register to obtain the timestamp
-and store it at the determined address for later retrieval.
-
-### Retrieving a timestamp
-
-From within ARM Trusted Firmware, timestamps for individual CPUs can
-be retrieved using either `PMF_GET_TIMESTAMP_BY_MPIDR()` or
-`PMF_GET_TIMESTAMP_BY_INDEX()` macros. These macros accept the CPU's MPIDR
-value, or its ordinal position, respectively.
-
-From outside ARM Trusted Firmware, timestamps for individual CPUs can be
-retrieved by calling into `pmf_smc_handler()`.
-
- Interface : pmf_smc_handler()
- Argument : unsigned int smc_fid, u_register_t x1,
- u_register_t x2, u_register_t x3,
- u_register_t x4, void *cookie,
- void *handle, u_register_t flags
- Return : uintptr_t
-
- smc_fid: Holds the SMC identifier which is either `PMF_SMC_GET_TIMESTAMP_32`
- when the caller of the SMC is running in AArch32 mode
- or `PMF_SMC_GET_TIMESTAMP_64` when the caller is running in AArch64 mode.
- x1: Timestamp identifier.
- x2: The `mpidr` of the CPU for which the timestamp has to be retrieved.
- This can be the `mpidr` of a different core to the one initiating
- the SMC. In that case, service specific cache maintenance may be
- required to ensure the updated copy of the timestamp is returned.
- x3: A flags value that is either 0 or `PMF_CACHE_MAINT`. If
- `PMF_CACHE_MAINT` is passed, then the PMF code will perform a
- cache invalidate before reading the timestamp. This ensures
- an updated copy is returned.
-
-The remaining arguments, `x4`, `cookie`, `handle` and `flags` are unused
-in this implementation.
-
-### PMF code structure
-
-1. `pmf_main.c` consists of core functions that implement service registration,
- initialization, storing, dumping and retrieving timestamps.
-
-2. `pmf_smc.c` contains the SMC handling for registered PMF services.
-
-3. `pmf.h` contains the public interface to Performance Measurement Framework.
-
-4. `pmf_asm_macros.S` consists of macros to facilitate capturing timestamps in
- assembly code.
-
-5. `pmf_helpers.h` is an internal header used by `pmf.h`.
-
-
-14. ARMv8 Architecture Extensions
-----------------------------------
-
-ARM Trusted Firmware makes use of ARMv8 Architecture Extensions where
-applicable. This section lists the usage of Architecture Extensions, and build
-flags controlling them.
-
-In general, and unless individually mentioned, the build options
-`ARM_ARCH_MAJOR` and `ARM_ARCH_MINOR` selects the Architecture Extension to
-target when building ARM Trusted Firmware. Subsequent ARM Architecture
-Extensions are backward compatible with previous versions.
-
-The build system only requires that `ARM_ARCH_MAJOR` and `ARM_ARCH_MINOR` have a
-valid numeric value. These build options only control whether or not
-Architecture Extension-specific code is included in the build. Otherwise, ARM
-Trusted Firmware targets the base ARMv8.0 architecture; i.e. as if
-`ARM_ARCH_MAJOR` == 8 and `ARM_ARCH_MINOR` == 0, which are also their respective
-default values.
-
-See also the _Summary of build options_ in [User Guide].
-
-For details on the Architecture Extension and available features, please refer
-to the respective Architecture Extension Supplement.
-
-### ARMv8.1
-
-This Architecture Extension is targeted when `ARM_ARCH_MAJOR` >= 8, or when
-`ARM_ARCH_MAJOR` == 8 and `ARM_ARCH_MINOR` >= 1.
-
-* The Compare and Swap instruction is used to implement spinlocks. Otherwise,
- the load-/store-exclusive instruction pair is used.
-
-15. Code Structure
--------------------
-
-Trusted Firmware code is logically divided between the three boot loader
-stages mentioned in the previous sections. The code is also divided into the
-following categories (present as directories in the source code):
-
-* **Platform specific.** Choice of architecture specific code depends upon
- the platform.
-* **Common code.** This is platform and architecture agnostic code.
-* **Library code.** This code comprises of functionality commonly used by all
- other code. The PSCI implementation and other EL3 runtime frameworks reside
- as Library components.
-* **Stage specific.** Code specific to a boot stage.
-* **Drivers.**
-* **Services.** EL3 runtime services (eg: SPD). Specific SPD services
- reside in the `services/spd` directory (e.g. `services/spd/tspd`).
-
-Each boot loader stage uses code from one or more of the above mentioned
-categories. Based upon the above, the code layout looks like this:
-
- Directory Used by BL1? Used by BL2? Used by BL31?
- bl1 Yes No No
- bl2 No Yes No
- bl31 No No Yes
- plat Yes Yes Yes
- drivers Yes No Yes
- common Yes Yes Yes
- lib Yes Yes Yes
- services No No Yes
-
-The build system provides a non configurable build option IMAGE_BLx for each
-boot loader stage (where x = BL stage). e.g. for BL1 , IMAGE_BL1 will be
-defined by the build system. This enables the Trusted Firmware to compile
-certain code only for specific boot loader stages
-
-All assembler files have the `.S` extension. The linker source files for each
-boot stage have the extension `.ld.S`. These are processed by GCC to create the
-linker scripts which have the extension `.ld`.
-
-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.
-
-
-16. References
----------------
-
-1. Trusted Board Boot Requirements CLIENT PDD (ARM DEN 0006B-5). Available
- under NDA through your ARM account representative.
-
-2. [Power State Coordination Interface PDD (ARM DEN 0022B.b)][PSCI].
-
-3. [SMC Calling Convention PDD (ARM DEN 0028A)][SMCCC].
-
-4. [ARM Trusted Firmware Interrupt Management Design guide][INTRG].
-
-- - - - - - - - - - - - - - - - - - - - - - - - - -
-
-_Copyright (c) 2013-2016, ARM Limited and Contributors. All rights reserved._
-
-[ARM ARM]: http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0487a.e/index.html "ARMv8-A Reference Manual (ARM DDI0487A.E)"
-[PSCI]: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf "Power State Coordination Interface PDD (ARM DEN 0022C)"
-[SMCCC]: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html "SMC Calling Convention PDD (ARM DEN 0028A)"
-[UUID]: https://tools.ietf.org/rfc/rfc4122.txt "A Universally Unique IDentifier (UUID) URN Namespace"
-[User Guide]: ./user-guide.md
-[Porting Guide]: ./porting-guide.md
-[Reset Design]: ./reset-design.md
-[INTRG]: ./interrupt-framework-design.md
-[CPUBM]: ./cpu-specific-build-macros.md
-[Firmware Update]: ./firmware-update.md
-[PSCI Lib guide]: ./psci-lib-integration-guide.md
diff --git a/docs/firmware-design.rst b/docs/firmware-design.rst
new file mode 100644
index 0000000..f50890b
--- /dev/null
+++ b/docs/firmware-design.rst
@@ -0,0 +1,2440 @@
+ARM Trusted Firmware Design
+===========================
+
+
+.. section-numbering::
+ :suffix: .
+
+.. contents::
+
+The ARM Trusted Firmware implements a subset of the Trusted Board Boot
+Requirements (TBBR) Platform Design Document (PDD) [1]_ for ARM reference
+platforms. The TBB sequence starts when the platform is powered on and runs up
+to the stage where it hands-off control to firmware running in the normal
+world in DRAM. This is the cold boot path.
+
+The ARM Trusted Firmware also implements the Power State Coordination Interface
+PDD [2]_ as a runtime service. PSCI is the interface from normal world software
+to firmware implementing power management use-cases (for example, secondary CPU
+boot, hotplug and idle). Normal world software can access ARM Trusted Firmware
+runtime services via the ARM SMC (Secure Monitor Call) instruction. The SMC
+instruction must be used as mandated by the SMC Calling Convention [3]_.
+
+The ARM Trusted Firmware implements a framework for configuring and managing
+interrupts generated in either security state. The details of the interrupt
+management framework and its design can be found in ARM Trusted Firmware
+Interrupt Management Design guide [4]_.
+
+The ARM Trusted Firmware can be built to support either AArch64 or AArch32
+execution state.
+
+Cold boot
+---------
+
+The cold boot path starts when the platform is physically turned on. If
+``COLD_BOOT_SINGLE_CPU=0``, one of the CPUs released from reset is chosen as the
+primary CPU, and the remaining CPUs are considered secondary CPUs. The primary
+CPU is chosen through platform-specific means. The cold boot path is mainly
+executed by the primary CPU, other than essential CPU initialization executed by
+all CPUs. The secondary CPUs are kept in a safe platform-specific state until
+the primary CPU has performed enough initialization to boot them.
+
+Refer to the `Reset Design`_ for more information on the effect of the
+``COLD_BOOT_SINGLE_CPU`` platform build option.
+
+The cold boot path in this implementation of the ARM Trusted Firmware,
+depends on the execution state.
+For AArch64, it is divided into five steps (in order of execution):
+
+- Boot Loader stage 1 (BL1) *AP Trusted ROM*
+- Boot Loader stage 2 (BL2) *Trusted Boot Firmware*
+- Boot Loader stage 3-1 (BL31) *EL3 Runtime Software*
+- Boot Loader stage 3-2 (BL32) *Secure-EL1 Payload* (optional)
+- Boot Loader stage 3-3 (BL33) *Non-trusted Firmware*
+
+For AArch32, it is divided into four steps (in order of execution):
+
+- Boot Loader stage 1 (BL1) *AP Trusted ROM*
+- Boot Loader stage 2 (BL2) *Trusted Boot Firmware*
+- Boot Loader stage 3-2 (BL32) *EL3 Runtime Software*
+- Boot Loader stage 3-3 (BL33) *Non-trusted Firmware*
+
+ARM development platforms (Fixed Virtual Platforms (FVPs) and Juno) implement a
+combination of the following types of memory regions. Each bootloader stage uses
+one or more of these memory regions.
+
+- Regions accessible from both non-secure and secure states. For example,
+ non-trusted SRAM, ROM and DRAM.
+- Regions accessible from only the secure state. For example, trusted SRAM and
+ ROM. The FVPs also implement the trusted DRAM which is statically
+ configured. Additionally, the Base FVPs and Juno development platform
+ configure the TrustZone Controller (TZC) to create a region in the DRAM
+ which is accessible only from the secure state.
+
+The sections below provide the following details:
+
+- initialization and execution of the first three stages during cold boot
+- specification of the EL3 Runtime Software (BL31 for AArch64 and BL32 for
+ AArch32) entrypoint requirements for use by alternative Trusted Boot
+ Firmware in place of the provided BL1 and BL2
+
+BL1
+~~~
+
+This stage begins execution from the platform's reset vector at EL3. The reset
+address is platform dependent but it is usually located in a Trusted ROM area.
+The BL1 data section is copied to trusted SRAM at runtime.
+
+On the ARM development platforms, BL1 code starts execution from the reset
+vector defined by the constant ``BL1_RO_BASE``. The BL1 data section is copied
+to the top of trusted SRAM as defined by the constant ``BL1_RW_BASE``.
+
+The functionality implemented by this stage is as follows.
+
+Determination of boot path
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Whenever a CPU is released from reset, BL1 needs to distinguish between a warm
+boot and a cold boot. This is done using platform-specific mechanisms (see the
+``plat_get_my_entrypoint()`` function in the `Porting Guide`_). In the case of a
+warm boot, a CPU is expected to continue execution from a separate
+entrypoint. In the case of a cold boot, the secondary CPUs are placed in a safe
+platform-specific state (see the ``plat_secondary_cold_boot_setup()`` function in
+the `Porting Guide`_) while the primary CPU executes the remaining cold boot path
+as described in the following sections.
+
+This step only applies when ``PROGRAMMABLE_RESET_ADDRESS=0``. Refer to the
+`Reset Design`_ for more information on the effect of the
+``PROGRAMMABLE_RESET_ADDRESS`` platform build option.
+
+Architectural initialization
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+BL1 performs minimal architectural initialization as follows.
+
+- Exception vectors
+
+ BL1 sets up simple exception vectors for both synchronous and asynchronous
+ exceptions. The default behavior upon receiving an exception is to populate
+ a status code in the general purpose register ``X0/R0`` and call the
+ ``plat_report_exception()`` function (see the `Porting Guide`_). The status
+ code is one of:
+
+ For AArch64:
+
+ ::
+
+ 0x0 : Synchronous exception from Current EL with SP_EL0
+ 0x1 : IRQ exception from Current EL with SP_EL0
+ 0x2 : FIQ exception from Current EL with SP_EL0
+ 0x3 : System Error exception from Current EL with SP_EL0
+ 0x4 : Synchronous exception from Current EL with SP_ELx
+ 0x5 : IRQ exception from Current EL with SP_ELx
+ 0x6 : FIQ exception from Current EL with SP_ELx
+ 0x7 : System Error exception from Current EL with SP_ELx
+ 0x8 : Synchronous exception from Lower EL using aarch64
+ 0x9 : IRQ exception from Lower EL using aarch64
+ 0xa : FIQ exception from Lower EL using aarch64
+ 0xb : System Error exception from Lower EL using aarch64
+ 0xc : Synchronous exception from Lower EL using aarch32
+ 0xd : IRQ exception from Lower EL using aarch32
+ 0xe : FIQ exception from Lower EL using aarch32
+ 0xf : System Error exception from Lower EL using aarch32
+
+ For AArch32:
+
+ ::
+
+ 0x10 : User mode
+ 0x11 : FIQ mode
+ 0x12 : IRQ mode
+ 0x13 : SVC mode
+ 0x16 : Monitor mode
+ 0x17 : Abort mode
+ 0x1a : Hypervisor mode
+ 0x1b : Undefined mode
+ 0x1f : System mode
+
+ The ``plat_report_exception()`` implementation on the ARM FVP port programs
+ the Versatile Express System LED register in the following format to
+ indicate the occurence of an unexpected exception:
+
+ ::
+
+ SYS_LED[0] - Security state (Secure=0/Non-Secure=1)
+ SYS_LED[2:1] - Exception Level (EL3=0x3, EL2=0x2, EL1=0x1, EL0=0x0)
+ For AArch32 it is always 0x0
+ SYS_LED[7:3] - Exception Class (Sync/Async & origin). This is the value
+ of the status code
+
+ A write to the LED register reflects in the System LEDs (S6LED0..7) in the
+ CLCD window of the FVP.
+
+ BL1 does not expect to receive any exceptions other than the SMC exception.
+ For the latter, BL1 installs a simple stub. The stub expects to receive a
+ limited set of SMC types (determined by their function IDs in the general
+ purpose register ``X0/R0``):
+
+ - ``BL1_SMC_RUN_IMAGE``: This SMC is raised by BL2 to make BL1 pass control
+ to EL3 Runtime Software.
+ - All SMCs listed in section "BL1 SMC Interface" in the `Firmware Update`_
+ Design Guide are supported for AArch64 only. These SMCs are currently
+ not supported when BL1 is built for AArch32.
+
+ Any other SMC leads to an assertion failure.
+
+- CPU initialization
+
+ BL1 calls the ``reset_handler()`` function which in turn calls the CPU
+ specific reset handler function (see the section: "CPU specific operations
+ framework").
+
+- Control register setup (for AArch64)
+
+ - ``SCTLR_EL3``. Instruction cache is enabled by setting the ``SCTLR_EL3.I``
+ bit. Alignment and stack alignment checking is enabled by setting the
+ ``SCTLR_EL3.A`` and ``SCTLR_EL3.SA`` bits. Exception endianness is set to
+ little-endian by clearing the ``SCTLR_EL3.EE`` bit.
+
+ - ``SCR_EL3``. The register width of the next lower exception level is set
+ to AArch64 by setting the ``SCR.RW`` bit. The ``SCR.EA`` bit is set to trap
+ both External Aborts and SError Interrupts in EL3. The ``SCR.SIF`` bit is
+ also set to disable instruction fetches from Non-secure memory when in
+ secure state.
+
+ - ``CPTR_EL3``. Accesses to the ``CPACR_EL1`` register from EL1 or EL2, or the
+ ``CPTR_EL2`` register from EL2 are configured to not trap to EL3 by
+ clearing the ``CPTR_EL3.TCPAC`` bit. Access to the trace functionality is
+ configured not to trap to EL3 by clearing the ``CPTR_EL3.TTA`` bit.
+ Instructions that access the registers associated with Floating Point
+ and Advanced SIMD execution are configured to not trap to EL3 by
+ clearing the ``CPTR_EL3.TFP`` bit.
+
+ - ``DAIF``. The SError interrupt is enabled by clearing the SError interrupt
+ mask bit.
+
+ - ``MDCR_EL3``. The trap controls, ``MDCR_EL3.TDOSA``, ``MDCR_EL3.TDA`` and
+ ``MDCR_EL3.TPM``, are set so that accesses to the registers they control
+ 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
+ disable AArch32 Secure self-hosted privileged debug from S-EL1.
+
+- Control register setup (for AArch32)
+
+ - ``SCTLR``. Instruction cache is enabled by setting the ``SCTLR.I`` bit.
+ Alignment checking is enabled by setting the ``SCTLR.A`` bit.
+ Exception endianness is set to little-endian by clearing the
+ ``SCTLR.EE`` bit.
+
+ - ``SCR``. The ``SCR.SIF`` bit is set to disable instruction fetches from
+ Non-secure memory when in secure state.
+
+ - ``CPACR``. Allow execution of Advanced SIMD instructions at PL0 and PL1,
+ by clearing the ``CPACR.ASEDIS`` bit. Access to the trace functionality
+ is configured not to trap to undefined mode by clearing the
+ ``CPACR.TRCDIS`` bit.
+
+ - ``NSACR``. Enable non-secure access to Advanced SIMD functionality and
+ system register access to implemented trace registers.
+
+ - ``FPEXC``. Enable access to the Advanced SIMD and floating-point
+ functionality from all Exception levels.
+
+ - ``CPSR.A``. The Asynchronous data abort interrupt is enabled by clearing
+ the Asynchronous data abort interrupt mask bit.
+
+ - ``SDCR``. The ``SDCR.SPD`` field is set to disable AArch32 Secure
+ self-hosted privileged debug.
+
+Platform initialization
+^^^^^^^^^^^^^^^^^^^^^^^
+
+On ARM platforms, BL1 performs the following platform initializations:
+
+- Enable the Trusted Watchdog.
+- Initialize the console.
+- Configure the Interconnect to enable hardware coherency.
+- Enable the MMU and map the memory it needs to access.
+- Configure any required platform storage to load the next bootloader image
+ (BL2).
+
+Firmware Update detection and execution
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+After performing platform setup, BL1 common code calls
+``bl1_plat_get_next_image_id()`` to determine if `Firmware Update`_ is required or
+to proceed with the normal boot process. If the platform code returns
+``BL2_IMAGE_ID`` then the normal boot sequence is executed as described in the
+next section, else BL1 assumes that `Firmware Update`_ is required and execution
+passes to the first image in the `Firmware Update`_ process. In either case, BL1
+retrieves a descriptor of the next image by calling ``bl1_plat_get_image_desc()``.
+The image descriptor contains an ``entry_point_info_t`` structure, which BL1
+uses to initialize the execution state of the next image.
+
+BL2 image load and execution
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In the normal boot flow, BL1 execution continues as follows:
+
+#. BL1 prints the following string from the primary CPU to indicate successful
+ execution of the BL1 stage:
+
+ ::
+
+ "Booting Trusted Firmware"
+
+#. BL1 determines the amount of free trusted SRAM memory available by
+ calculating the extent of its own data section, which also resides in
+ trusted SRAM. BL1 loads a BL2 raw binary image from platform storage, at a
+ platform-specific base address. If the BL2 image file is not present or if
+ there is not enough free trusted SRAM the following error message is
+ printed:
+
+ ::
+
+ "Failed to load BL2 firmware."
+
+ BL1 calculates the amount of Trusted SRAM that can be used by the BL2
+ image. The exact load location of the image is provided as a base address
+ in the platform header. Further description of the memory layout can be
+ found later in this document.
+
+#. BL1 passes control to the BL2 image at Secure EL1 (for AArch64) or at
+ Secure SVC mode (for AArch32), starting from its load address.
+
+#. BL1 also passes information about the amount of trusted SRAM used and
+ available for use. This information is populated at a platform-specific
+ memory address.
+
+BL2
+~~~
+
+BL1 loads and passes control to BL2 at Secure-EL1 (for AArch64) or at Secure
+SVC mode (for AArch32) . BL2 is linked against and loaded at a platform-specific
+base address (more information can be found later in this document).
+The functionality implemented by BL2 is as follows.
+
+Architectural initialization
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For AArch64, BL2 performs the minimal architectural initialization required
+for subsequent stages of the ARM Trusted Firmware and normal world software.
+EL1 and EL0 are given access to Floating Point and Advanced SIMD registers
+by clearing the ``CPACR.FPEN`` bits.
+
+For AArch32, the minimal architectural initialization required for subsequent
+stages of the ARM Trusted Firmware and normal world software is taken care of
+in BL1 as both BL1 and BL2 execute at PL1.
+
+Platform initialization
+^^^^^^^^^^^^^^^^^^^^^^^
+
+On ARM platforms, BL2 performs the following platform initializations:
+
+- Initialize the console.
+- Configure any required platform storage to allow loading further bootloader
+ images.
+- Enable the MMU and map the memory it needs to access.
+- Perform platform security setup to allow access to controlled components.
+- Reserve some memory for passing information to the next bootloader image
+ EL3 Runtime Software and populate it.
+- Define the extents of memory available for loading each subsequent
+ bootloader image.
+
+Image loading in BL2
+^^^^^^^^^^^^^^^^^^^^
+
+Image loading scheme in BL2 depends on ``LOAD_IMAGE_V2`` build option. If the
+flag is disabled, the BLxx images are loaded, by calling the respective
+load\_blxx() function from BL2 generic code. If the flag is enabled, the BL2
+generic code loads the images based on the list of loadable images provided
+by the platform. BL2 passes the list of executable images provided by the
+platform to the next handover BL image. By default, this flag is disabled for
+AArch64 and the AArch32 build is supported only if this flag is enabled.
+
+SCP\_BL2 (System Control Processor Firmware) image load
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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
+storage into a platform-specific region of secure memory. The subsequent
+handling of SCP\_BL2 is platform specific. For example, on the Juno ARM
+development platform port the image is transferred into SCP's internal memory
+using the Boot Over MHU (BOM) protocol after being loaded in the trusted SRAM
+memory. The SCP executes SCP\_BL2 and signals to the Application Processor (AP)
+for BL2 execution to continue.
+
+EL3 Runtime Software image load
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+BL2 loads the EL3 Runtime Software image from platform storage into a platform-
+specific address in trusted SRAM. If there is not enough memory to load the
+image or image is missing it leads to an assertion failure. If ``LOAD_IMAGE_V2``
+is disabled and if image loads successfully, BL2 updates the amount of trusted
+SRAM used and available for use by EL3 Runtime Software. This information is
+populated at a platform-specific memory address.
+
+AArch64 BL32 (Secure-EL1 Payload) image load
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+BL2 loads the optional BL32 image from platform storage into a platform-
+specific region of secure memory. The image executes in the secure world. BL2
+relies on BL31 to pass control to the BL32 image, if present. Hence, BL2
+populates a platform-specific area of memory with the entrypoint/load-address
+of the BL32 image. The value of the Saved Processor Status Register (``SPSR``)
+for entry into BL32 is not determined by BL2, it is initialized by the
+Secure-EL1 Payload Dispatcher (see later) within BL31, which is responsible for
+managing interaction with BL32. This information is passed to BL31.
+
+BL33 (Non-trusted Firmware) image load
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+BL2 loads the BL33 image (e.g. UEFI or other test or boot software) from
+platform storage into non-secure memory as defined by the platform.
+
+BL2 relies on EL3 Runtime Software to pass control to BL33 once secure state
+initialization is complete. Hence, BL2 populates a platform-specific area of
+memory with the entrypoint and Saved Program Status Register (``SPSR``) of the
+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`_. This information is passed to the EL3 Runtime Software.
+
+AArch64 BL31 (EL3 Runtime Software) execution
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+BL2 execution continues as follows:
+
+#. BL2 passes control back to BL1 by raising an SMC, providing BL1 with the
+ BL31 entrypoint. The exception is handled by the SMC exception handler
+ installed by BL1.
+
+#. BL1 turns off the MMU and flushes the caches. It clears the
+ ``SCTLR_EL3.M/I/C`` bits, flushes the data cache to the point of coherency
+ and invalidates the TLBs.
+
+#. BL1 passes control to BL31 at the specified entrypoint at EL3.
+
+AArch64 BL31
+~~~~~~~~~~~~
+
+The image for this stage is loaded by BL2 and BL1 passes control to BL31 at
+EL3. BL31 executes solely in trusted SRAM. BL31 is linked against and
+loaded at a platform-specific base address (more information can be found later
+in this document). The functionality implemented by BL31 is as follows.
+
+Architectural initialization
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Currently, BL31 performs a similar architectural initialization to BL1 as
+far as system register settings are concerned. Since BL1 code resides in ROM,
+architectural initialization in BL31 allows override of any previous
+initialization done by BL1.
+
+BL31 initializes the per-CPU data framework, which provides a cache of
+frequently accessed per-CPU data optimised for fast, concurrent manipulation
+on different CPUs. This buffer includes pointers to per-CPU contexts, crash
+buffer, CPU reset and power down operations, PSCI data, platform data and so on.
+
+It then replaces the exception vectors populated by BL1 with its own. BL31
+exception vectors implement more elaborate support for handling SMCs since this
+is the only mechanism to access the runtime services implemented by BL31 (PSCI
+for example). BL31 checks each SMC for validity as specified by the
+`SMC calling convention PDD`_ before passing control to the required SMC
+handler routine.
+
+BL31 programs the ``CNTFRQ_EL0`` register with the clock frequency of the system
+counter, which is provided by the platform.
+
+Platform initialization
+^^^^^^^^^^^^^^^^^^^^^^^
+
+BL31 performs detailed platform initialization, which enables normal world
+software to function correctly.
+
+On ARM platforms, this consists of the following:
+
+- Initialize the console.
+- Configure the Interconnect to enable hardware coherency.
+- Enable the MMU and map the memory it needs to access.
+- Initialize the generic interrupt controller.
+- Initialize the power controller device.
+- Detect the system topology.
+
+Runtime services initialization
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+BL31 is responsible for initializing the runtime services. One of them is PSCI.
+
+As part of the PSCI initializations, BL31 detects the system topology. It also
+initializes the data structures that implement the state machine used to track
+the state of power domain nodes. The state can be one of ``OFF``, ``RUN`` or
+``RETENTION``. All secondary CPUs are initially in the ``OFF`` state. The cluster
+that the primary CPU belongs to is ``ON``; any other cluster is ``OFF``. It also
+initializes the locks that protect them. BL31 accesses the state of a CPU or
+cluster immediately after reset and before the data cache is enabled in the
+warm boot path. It is not currently possible to use 'exclusive' based spinlocks,
+therefore BL31 uses locks based on Lamport's Bakery algorithm instead.
+
+The runtime service framework and its initialization is described in more
+detail in the "EL3 runtime services framework" section below.
+
+Details about the status of the PSCI implementation are provided in the
+"Power State Coordination Interface" section below.
+
+AArch64 BL32 (Secure-EL1 Payload) image initialization
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If a BL32 image is present then there must be a matching Secure-EL1 Payload
+Dispatcher (SPD) service (see later for details). During initialization
+that service must register a function to carry out initialization of BL32
+once the runtime services are fully initialized. BL31 invokes such a
+registered function to initialize BL32 before running BL33. This initialization
+is not necessary for AArch32 SPs.
+
+Details on BL32 initialization and the SPD's role are described in the
+"Secure-EL1 Payloads and Dispatchers" section below.
+
+BL33 (Non-trusted Firmware) execution
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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
+the non-secure execution state. EL3 Runtime Software uses the entrypoint
+information provided by BL2 to jump to the Non-trusted firmware image (BL33)
+at the highest available Exception Level (EL2 if available, otherwise EL1).
+
+Using alternative Trusted Boot Firmware in place of BL1 & BL2 (AArch64 only)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some platforms have existing implementations of Trusted Boot Firmware that
+would like to use ARM Trusted Firmware BL31 for the EL3 Runtime Software. To
+enable this firmware architecture it is important to provide a fully documented
+and stable interface between the Trusted Boot Firmware and BL31.
+
+Future changes to the BL31 interface will be done in a backwards compatible
+way, and this enables these firmware components to be independently enhanced/
+updated to develop and exploit new functionality.
+
+Required CPU state when calling ``bl31_entrypoint()`` during cold boot
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function must only be called by the primary CPU.
+
+On entry to this function the calling primary CPU must be executing in AArch64
+EL3, little-endian data access, and all interrupt sources masked:
+
+::
+
+ PSTATE.EL = 3
+ PSTATE.RW = 1
+ PSTATE.DAIF = 0xf
+ SCTLR_EL3.EE = 0
+
+X0 and X1 can be used to pass information from the Trusted Boot Firmware to the
+platform code in BL31:
+
+::
+
+ X0 : Reserved for common Trusted Firmware information
+ X1 : Platform specific information
+
+BL31 zero-init sections (e.g. ``.bss``) should not contain valid data on entry,
+these will be zero filled prior to invoking platform setup code.
+
+Use of the X0 and X1 parameters
+'''''''''''''''''''''''''''''''
+
+The parameters are platform specific and passed from ``bl31_entrypoint()`` to
+``bl31_early_platform_setup()``. The value of these parameters is never directly
+used by the common BL31 code.
+
+The convention is that ``X0`` conveys information regarding the BL31, BL32 and
+BL33 images from the Trusted Boot firmware and ``X1`` can be used for other
+platform specific purpose. This convention allows platforms which use ARM
+Trusted Firmware's BL1 and BL2 images to transfer additional platform specific
+information from Secure Boot without conflicting with future evolution of the
+Trusted Firmware using ``X0`` to pass a ``bl31_params`` structure.
+
+BL31 common and SPD initialization code depends on image and entrypoint
+information about BL33 and BL32, which is provided via BL31 platform APIs.
+This information is required until the start of execution of BL33. This
+information can be provided in a platform defined manner, e.g. compiled into
+the platform code in BL31, or provided in a platform defined memory location
+by the Trusted Boot firmware, or passed from the Trusted Boot Firmware via the
+Cold boot Initialization parameters. This data may need to be cleaned out of
+the CPU caches if it is provided by an earlier boot stage and then accessed by
+BL31 platform code before the caches are enabled.
+
+ARM Trusted Firmware's BL2 implementation passes a ``bl31_params`` structure in
+``X0`` and the ARM development platforms interpret this in the BL31 platform
+code.
+
+MMU, Data caches & Coherency
+''''''''''''''''''''''''''''
+
+BL31 does not depend on the enabled state of the MMU, data caches or
+interconnect coherency on entry to ``bl31_entrypoint()``. If these are disabled
+on entry, these should be enabled during ``bl31_plat_arch_setup()``.
+
+Data structures used in the BL31 cold boot interface
+''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+These structures are designed to support compatibility and independent
+evolution of the structures and the firmware images. For example, a version of
+BL31 that can interpret the BL3x image information from different versions of
+BL2, a platform that uses an extended entry\_point\_info structure to convey
+additional register information to BL31, or a ELF image loader that can convey
+more details about the firmware images.
+
+To support these scenarios the structures are versioned and sized, which enables
+BL31 to detect which information is present and respond appropriately. The
+``param_header`` is defined to capture this information:
+
+.. code:: c
+
+ typedef struct param_header {
+ uint8_t type; /* type of the structure */
+ uint8_t version; /* version of this structure */
+ uint16_t size; /* size of this structure in bytes */
+ uint32_t attr; /* attributes: unused bits SBZ */
+ } param_header_t;
+
+The structures using this format are ``entry_point_info``, ``image_info`` and
+``bl31_params``. The code that allocates and populates these structures must set
+the header fields appropriately, and the ``SET_PARAM_HEAD()`` a macro is defined
+to simplify this action.
+
+Required CPU state for BL31 Warm boot initialization
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When requesting a CPU power-on, or suspending a running CPU, ARM Trusted
+Firmware provides the platform power management code with a Warm boot
+initialization entry-point, to be invoked by the CPU immediately after the
+reset handler. On entry to the Warm boot initialization function the calling
+CPU must be in AArch64 EL3, little-endian data access and all interrupt sources
+masked:
+
+::
+
+ PSTATE.EL = 3
+ PSTATE.RW = 1
+ PSTATE.DAIF = 0xf
+ SCTLR_EL3.EE = 0
+
+The PSCI implementation will initialize the processor state and ensure that the
+platform power management code is then invoked as required to initialize all
+necessary system, cluster and CPU resources.
+
+AArch32 EL3 Runtime Software entrypoint interface
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To enable this firmware architecture it is important to provide a fully
+documented and stable interface between the Trusted Boot Firmware and the
+AArch32 EL3 Runtime Software.
+
+Future changes to the entrypoint interface will be done in a backwards
+compatible way, and this enables these firmware components to be independently
+enhanced/updated to develop and exploit new functionality.
+
+Required CPU state when entering during cold boot
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function must only be called by the primary CPU.
+
+On entry to this function the calling primary CPU must be executing in AArch32
+EL3, little-endian data access, and all interrupt sources masked:
+
+::
+
+ PSTATE.AIF = 0x7
+ SCTLR.EE = 0
+
+R0 and R1 are used to pass information from the Trusted Boot Firmware to the
+platform code in AArch32 EL3 Runtime Software:
+
+::
+
+ R0 : Reserved for common Trusted Firmware information
+ R1 : Platform specific information
+
+Use of the R0 and R1 parameters
+'''''''''''''''''''''''''''''''
+
+The parameters are platform specific and the convention is that ``R0`` conveys
+information regarding the BL3x images from the Trusted Boot firmware and ``R1``
+can be used for other platform specific purpose. This convention allows
+platforms which use ARM Trusted Firmware's BL1 and BL2 images to transfer
+additional platform specific information from Secure Boot without conflicting
+with future evolution of the Trusted Firmware using ``R0`` to pass a ``bl_params``
+structure.
+
+The AArch32 EL3 Runtime Software is responsible for entry into BL33. This
+information can be obtained in a platform defined manner, e.g. compiled into
+the AArch32 EL3 Runtime Software, or provided in a platform defined memory
+location by the Trusted Boot firmware, or passed from the Trusted Boot Firmware
+via the Cold boot Initialization parameters. This data may need to be cleaned
+out of the CPU caches if it is provided by an earlier boot stage and then
+accessed by AArch32 EL3 Runtime Software before the caches are enabled.
+
+When using AArch32 EL3 Runtime Software, the ARM development platforms pass a
+``bl_params`` structure in ``R0`` from BL2 to be interpreted by AArch32 EL3 Runtime
+Software platform code.
+
+MMU, Data caches & Coherency
+''''''''''''''''''''''''''''
+
+AArch32 EL3 Runtime Software must not depend on the enabled state of the MMU,
+data caches or interconnect coherency in its entrypoint. They must be explicitly
+enabled if required.
+
+Data structures used in cold boot interface
+'''''''''''''''''''''''''''''''''''''''''''
+
+The AArch32 EL3 Runtime Software cold boot interface uses ``bl_params`` instead
+of ``bl31_params``. The ``bl_params`` structure is based on the convention
+described in AArch64 BL31 cold boot interface section.
+
+Required CPU state for warm boot initialization
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When requesting a CPU power-on, or suspending a running CPU, AArch32 EL3
+Runtime Software must ensure execution of a warm boot initialization entrypoint.
+If ARM Trusted Firmware BL1 is used and the PROGRAMMABLE\_RESET\_ADDRESS build
+flag is false, then AArch32 EL3 Runtime Software must ensure that BL1 branches
+to the warm boot entrypoint by arranging for the BL1 platform function,
+plat\_get\_my\_entrypoint(), to return a non-zero value.
+
+In this case, the warm boot entrypoint must be in AArch32 EL3, little-endian
+data access and all interrupt sources masked:
+
+::
+
+ PSTATE.AIF = 0x7
+ SCTLR.EE = 0
+
+The warm boot entrypoint may be implemented by using the ARM Trusted Firmware
+``psci_warmboot_entrypoint()`` function. In that case, the platform must fulfil
+the pre-requisites mentioned in the `PSCI Library integration guide`_.
+
+EL3 runtime services framework
+------------------------------
+
+Software executing in the non-secure state and in the secure state at exception
+levels lower than EL3 will request runtime services using the Secure Monitor
+Call (SMC) instruction. These requests will follow the convention described in
+the SMC Calling Convention PDD (`SMCCC`_). The `SMCCC`_ assigns function
+identifiers to each SMC request and describes how arguments are passed and
+returned.
+
+The EL3 runtime services framework enables the development of services by
+different providers that can be easily integrated into final product firmware.
+The following sections describe the framework which facilitates the
+registration, initialization and use of runtime services in EL3 Runtime
+Software (BL31).
+
+The design of the runtime services depends heavily on the concepts and
+definitions described in the `SMCCC`_, in particular SMC Function IDs, Owning
+Entity Numbers (OEN), Fast and Yielding calls, and the SMC32 and SMC64 calling
+conventions. Please refer to that document for more detailed explanation of
+these terms.
+
+The following runtime services are expected to be implemented first. They have
+not all been instantiated in the current implementation.
+
+#. Standard service calls
+
+ This service is for management of the entire system. The Power State
+ Coordination Interface (`PSCI`_) is the first set of standard service calls
+ defined by ARM (see PSCI section later).
+
+#. Secure-EL1 Payload Dispatcher service
+
+ If a system runs a Trusted OS or other Secure-EL1 Payload (SP) then
+ it also requires a *Secure Monitor* at EL3 to switch the EL1 processor
+ context between the normal world (EL1/EL2) and trusted world (Secure-EL1).
+ The Secure Monitor will make these world switches in response to SMCs. The
+ `SMCCC`_ provides for such SMCs with the Trusted OS Call and Trusted
+ Application Call OEN ranges.
+
+ The interface between the EL3 Runtime Software and the Secure-EL1 Payload is
+ not defined by the `SMCCC`_ or any other standard. As a result, each
+ Secure-EL1 Payload requires a specific Secure Monitor that runs as a runtime
+ service - within ARM Trusted Firmware this service is referred to as the
+ Secure-EL1 Payload Dispatcher (SPD).
+
+ ARM Trusted Firmware provides a Test Secure-EL1 Payload (TSP) and its
+ associated Dispatcher (TSPD). Details of SPD design and TSP/TSPD operation
+ are described in the "Secure-EL1 Payloads and Dispatchers" section below.
+
+#. CPU implementation service
+
+ This service will provide an interface to CPU implementation specific
+ services for a given platform e.g. access to processor errata workarounds.
+ This service is currently unimplemented.
+
+Additional services for ARM Architecture, SiP and OEM calls can be implemented.
+Each implemented service handles a range of SMC function identifiers as
+described in the `SMCCC`_.
+
+Registration
+~~~~~~~~~~~~
+
+A runtime service is registered using the ``DECLARE_RT_SVC()`` macro, specifying
+the name of the service, the range of OENs covered, the type of service and
+initialization and call handler functions. This macro instantiates a ``const struct rt_svc_desc`` for the service with these details (see ``runtime_svc.h``).
+This structure is allocated in a special ELF section ``rt_svc_descs``, enabling
+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
+type of the Function ID, and the framework uses that information in the service
+descriptor to identify the handler for the SMC Call.
+
+The service descriptors do not include information to identify the precise set
+of SMC function identifiers supported by this service implementation, the
+security state from which such calls are valid nor the capability to support
+64-bit and/or 32-bit callers (using SMC32 or SMC64). Responding appropriately
+to these aspects of a SMC call is the responsibility of the service
+implementation, the framework is focused on integration of services from
+different providers and minimizing the time taken by the framework before the
+service handler is invoked.
+
+Details of the parameters, requirements and behavior of the initialization and
+call handling functions are provided in the following sections.
+
+Initialization
+~~~~~~~~~~~~~~
+
+``runtime_svc_init()`` in ``runtime_svc.c`` initializes the runtime services
+framework running on the primary CPU during cold boot as part of the BL31
+initialization. This happens prior to initializing a Trusted OS and running
+Normal world boot firmware that might in turn use these services.
+Initialization involves validating each of the declared runtime service
+descriptors, calling the service initialization function and populating the
+index used for runtime lookup of the service.
+
+The BL31 linker script collects all of the declared service descriptors into a
+single array and defines symbols that allow the framework to locate and traverse
+the array, and determine its size.
+
+The framework does basic validation of each descriptor to halt firmware
+initialization if service declaration errors are detected. The framework does
+not check descriptors for the following error conditions, and may behave in an
+unpredictable manner under such scenarios:
+
+#. Overlapping OEN ranges
+#. Multiple descriptors for the same range of OENs and ``call_type``
+#. Incorrect range of owning entity numbers for a given ``call_type``
+
+Once validated, the service ``init()`` callback is invoked. This function carries
+out any essential EL3 initialization before servicing requests. The ``init()``
+function is only invoked on the primary CPU during cold boot. If the service
+uses per-CPU data this must either be initialized for all CPUs during this call,
+or be done lazily when a CPU first issues an SMC call to that service. If
+``init()`` returns anything other than ``0``, this is treated as an initialization
+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
+128 distinct services, but in practice a single descriptor can cover a range of
+OENs, e.g. SMCs to call a Trusted OS function. To optimize the lookup of a
+service handler, the framework uses an array of 128 indices that map every
+distinct OEN/call-type combination either to one of the declared services or to
+indicate the service is not handled. This ``rt_svc_descs_indices[]`` array is
+populated for all of the OENs covered by a service after the service ``init()``
+function has reported success. So a service that fails to initialize will never
+have it's ``handle()`` function invoked.
+
+The following figure shows how the ``rt_svc_descs_indices[]`` index maps the SMC
+Function ID call type and OEN onto a specific service handler in the
+``rt_svc_descs[]`` array.
+
+|Image 1|
+
+Handling an SMC
+~~~~~~~~~~~~~~~
+
+When the EL3 runtime services framework receives a Secure Monitor Call, the SMC
+Function ID is passed in W0 from the lower exception level (as per the
+`SMCCC`_). If the calling register width is AArch32, it is invalid to invoke an
+SMC Function which indicates the SMC64 calling convention: such calls are
+ignored and return the Unknown SMC Function Identifier result code ``0xFFFFFFFF``
+in R0/X0.
+
+Bit[31] (fast/yielding call) and bits[29:24] (owning entity number) of the SMC
+Function ID are combined to index into the ``rt_svc_descs_indices[]`` array. The
+resulting value might indicate a service that has no handler, in this case the
+framework will also report an Unknown SMC Function ID. Otherwise, the value is
+used as a further index into the ``rt_svc_descs[]`` array to locate the required
+service and handler.
+
+The service's ``handle()`` callback is provided with five of the SMC parameters
+directly, the others are saved into memory for retrieval (if needed) by the
+handler. The handler is also provided with an opaque ``handle`` for use with the
+supporting library for parameter retrieval, setting return values and context
+manipulation; and with ``flags`` indicating the security state of the caller. The
+framework finally sets up the execution stack for the handler, and invokes the
+services ``handle()`` function.
+
+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.
+
+Power State Coordination Interface
+----------------------------------
+
+TODO: Provide design walkthrough of PSCI implementation.
+
+The PSCI v1.0 specification categorizes APIs as optional and mandatory. All the
+mandatory APIs in PSCI v1.0 and all the APIs in PSCI v0.2 draft specification
+`Power State Coordination Interface PDD`_ are implemented. The table lists
+the PSCI v1.0 APIs and their support in generic code.
+
+An API implementation might have a dependency on platform code e.g. CPU\_SUSPEND
+requires the platform to export a part of the implementation. Hence the level
+of support of the mandatory APIs depends upon the support exported by the
+platform port as well. The Juno and FVP (all variants) platforms export all the
+required support.
+
++-----------------------------+-------------+-------------------------------+
+| PSCI v1.0 API | Supported | Comments |
++=============================+=============+===============================+
+| ``PSCI_VERSION`` | Yes | The version returned is 1.0 |
++-----------------------------+-------------+-------------------------------+
+| ``CPU_SUSPEND`` | Yes\* | |
++-----------------------------+-------------+-------------------------------+
+| ``CPU_OFF`` | Yes\* | |
++-----------------------------+-------------+-------------------------------+
+| ``CPU_ON`` | Yes\* | |
++-----------------------------+-------------+-------------------------------+
+| ``AFFINITY_INFO`` | Yes | |
++-----------------------------+-------------+-------------------------------+
+| ``MIGRATE`` | Yes\*\* | |
++-----------------------------+-------------+-------------------------------+
+| ``MIGRATE_INFO_TYPE`` | Yes\*\* | |
++-----------------------------+-------------+-------------------------------+
+| ``MIGRATE_INFO_CPU`` | Yes\*\* | |
++-----------------------------+-------------+-------------------------------+
+| ``SYSTEM_OFF`` | Yes\* | |
++-----------------------------+-------------+-------------------------------+
+| ``SYSTEM_RESET`` | Yes\* | |
++-----------------------------+-------------+-------------------------------+
+| ``PSCI_FEATURES`` | Yes | |
++-----------------------------+-------------+-------------------------------+
+| ``CPU_FREEZE`` | No | |
++-----------------------------+-------------+-------------------------------+
+| ``CPU_DEFAULT_SUSPEND`` | No | |
++-----------------------------+-------------+-------------------------------+
+| ``NODE_HW_STATE`` | Yes\* | |
++-----------------------------+-------------+-------------------------------+
+| ``SYSTEM_SUSPEND`` | Yes\* | |
++-----------------------------+-------------+-------------------------------+
+| ``PSCI_SET_SUSPEND_MODE`` | No | |
++-----------------------------+-------------+-------------------------------+
+| ``PSCI_STAT_RESIDENCY`` | Yes\* | |
++-----------------------------+-------------+-------------------------------+
+| ``PSCI_STAT_COUNT`` | Yes\* | |
++-----------------------------+-------------+-------------------------------+
+
+\*Note : These PSCI APIs require platform power management hooks to be
+registered with the generic PSCI code to be supported.
+
+\*\*Note : These PSCI APIs require appropriate Secure Payload Dispatcher
+hooks to be registered with the generic PSCI code to be supported.
+
+The PSCI implementation in ARM Trusted Firmware is a library which can be
+integrated with AArch64 or AArch32 EL3 Runtime Software for ARMv8-A systems.
+A guide to integrating PSCI library with AArch32 EL3 Runtime Software
+can be found `here`_.
+
+Secure-EL1 Payloads and Dispatchers
+-----------------------------------
+
+On a production system that includes a Trusted OS running in Secure-EL1/EL0,
+the Trusted OS is coupled with a companion runtime service in the BL31
+firmware. This service is responsible for the initialisation of the Trusted
+OS and all communications with it. The Trusted OS is the BL32 stage of the
+boot flow in ARM Trusted Firmware. The firmware will attempt to locate, load
+and execute a BL32 image.
+
+ARM Trusted Firmware uses a more general term for the BL32 software that runs
+at Secure-EL1 - the *Secure-EL1 Payload* - as it is not always a Trusted OS.
+
+The ARM Trusted Firmware provides a Test Secure-EL1 Payload (TSP) and a Test
+Secure-EL1 Payload Dispatcher (TSPD) service as an example of how a Trusted OS
+is supported on a production system using the Runtime Services Framework. On
+such a system, the Test BL32 image and service are replaced by the Trusted OS
+and its dispatcher service. The ARM Trusted Firmware build system expects that
+the dispatcher will define the build flag ``NEED_BL32`` to enable it to include
+the BL32 in the build either as a binary or to compile from source depending
+on whether the ``BL32`` build option is specified or not.
+
+The TSP runs in Secure-EL1. It is designed to demonstrate synchronous
+communication with the normal-world software running in EL1/EL2. Communication
+is initiated by the normal-world software
+
+- either directly through a Fast SMC (as defined in the `SMCCC`_)
+
+- or indirectly through a `PSCI`_ SMC. The `PSCI`_ implementation in turn
+ informs the TSPD about the requested power management operation. This allows
+ the TSP to prepare for or respond to the power state change
+
+The TSPD service is responsible for.
+
+- Initializing the TSP
+
+- Routing requests and responses between the secure and the non-secure
+ states during the two types of communications just described
+
+Initializing a BL32 Image
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Secure-EL1 Payload Dispatcher (SPD) service is responsible for initializing
+the BL32 image. It needs access to the information passed by BL2 to BL31 to do
+so. This is provided by:
+
+.. code:: c
+
+ entry_point_info_t *bl31_plat_get_next_image_ep_info(uint32_t);
+
+which returns a reference to the ``entry_point_info`` structure corresponding to
+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.
+
+In the absence of a BL32 image, BL31 passes control to the normal world
+bootloader image (BL33). When the BL32 image is present, it is typical
+that the SPD wants control to be passed to BL32 first and then later to BL33.
+
+To do this the SPD has to register a BL32 initialization function during
+initialization of the SPD service. The BL32 initialization function has this
+prototype:
+
+.. code:: c
+
+ int32_t init(void);
+
+and is registered using the ``bl31_register_bl32_init()`` function.
+
+Trusted Firmware supports two approaches for the SPD to pass control to BL32
+before returning through EL3 and running the non-trusted firmware (BL33):
+
+#. In the BL32 setup function, use ``bl31_set_next_image_type()`` to
+ request that the exit from ``bl31_main()`` is to the BL32 entrypoint in
+ Secure-EL1. BL31 will exit to BL32 using the asynchronous method by
+ calling ``bl31_prepare_next_image_entry()`` and ``el3_exit()``.
+
+ When the BL32 has completed initialization at Secure-EL1, it returns to
+ BL31 by issuing an SMC, using a Function ID allocated to the SPD. On
+ receipt of this SMC, the SPD service handler should switch the CPU context
+ from trusted to normal world and use the ``bl31_set_next_image_type()`` and
+ ``bl31_prepare_next_image_entry()`` functions to set up the initial return to
+ the normal world firmware BL33. On return from the handler the framework
+ will exit to EL2 and run BL33.
+
+#. The BL32 setup function registers an initialization function using
+ ``bl31_register_bl32_init()`` which provides a SPD-defined mechanism to
+ invoke a 'world-switch synchronous call' to Secure-EL1 to run the BL32
+ entrypoint.
+ NOTE: The Test SPD service included with the Trusted Firmware provides one
+ implementation of such a mechanism.
+
+ On completion BL32 returns control to BL31 via a SMC, and on receipt the
+ SPD service handler invokes the synchronous call return mechanism to return
+ to the BL32 initialization function. On return from this function,
+ ``bl31_main()`` will set up the return to the normal world firmware BL33 and
+ continue the boot process in the normal world.
+
+#. .. rubric:: Crash Reporting in BL31
+ :name: crash-reporting-in-bl31
+
+BL31 implements a scheme for reporting the processor state when an unhandled
+exception is encountered. The reporting mechanism attempts to preserve all the
+register contents and report it via a dedicated UART (PL011 console). BL31
+reports the general purpose, EL3, Secure EL1 and some EL2 state registers.
+
+A dedicated per-CPU crash stack is maintained by BL31 and this is retrieved via
+the per-CPU pointer cache. The implementation attempts to minimise the memory
+required for this feature. The file ``crash_reporting.S`` contains the
+implementation for crash reporting.
+
+The sample crash output is shown below.
+
+::
+
+ x0 :0x000000004F00007C
+ x1 :0x0000000007FFFFFF
+ x2 :0x0000000004014D50
+ x3 :0x0000000000000000
+ x4 :0x0000000088007998
+ x5 :0x00000000001343AC
+ x6 :0x0000000000000016
+ x7 :0x00000000000B8A38
+ x8 :0x00000000001343AC
+ x9 :0x00000000000101A8
+ x10 :0x0000000000000002
+ x11 :0x000000000000011C
+ x12 :0x00000000FEFDC644
+ x13 :0x00000000FED93FFC
+ x14 :0x0000000000247950
+ x15 :0x00000000000007A2
+ x16 :0x00000000000007A4
+ x17 :0x0000000000247950
+ x18 :0x0000000000000000
+ x19 :0x00000000FFFFFFFF
+ x20 :0x0000000004014D50
+ x21 :0x000000000400A38C
+ x22 :0x0000000000247950
+ x23 :0x0000000000000010
+ x24 :0x0000000000000024
+ x25 :0x00000000FEFDC868
+ x26 :0x00000000FEFDC86A
+ x27 :0x00000000019EDEDC
+ x28 :0x000000000A7CFDAA
+ x29 :0x0000000004010780
+ x30 :0x000000000400F004
+ scr_el3 :0x0000000000000D3D
+ sctlr_el3 :0x0000000000C8181F
+ cptr_el3 :0x0000000000000000
+ tcr_el3 :0x0000000080803520
+ daif :0x00000000000003C0
+ mair_el3 :0x00000000000004FF
+ spsr_el3 :0x00000000800003CC
+ elr_el3 :0x000000000400C0CC
+ ttbr0_el3 :0x00000000040172A0
+ esr_el3 :0x0000000096000210
+ sp_el3 :0x0000000004014D50
+ far_el3 :0x000000004F00007C
+ spsr_el1 :0x0000000000000000
+ elr_el1 :0x0000000000000000
+ spsr_abt :0x0000000000000000
+ spsr_und :0x0000000000000000
+ spsr_irq :0x0000000000000000
+ spsr_fiq :0x0000000000000000
+ sctlr_el1 :0x0000000030C81807
+ actlr_el1 :0x0000000000000000
+ cpacr_el1 :0x0000000000300000
+ csselr_el1 :0x0000000000000002
+ sp_el1 :0x0000000004028800
+ esr_el1 :0x0000000000000000
+ ttbr0_el1 :0x000000000402C200
+ ttbr1_el1 :0x0000000000000000
+ mair_el1 :0x00000000000004FF
+ amair_el1 :0x0000000000000000
+ tcr_el1 :0x0000000000003520
+ tpidr_el1 :0x0000000000000000
+ tpidr_el0 :0x0000000000000000
+ tpidrro_el0 :0x0000000000000000
+ dacr32_el2 :0x0000000000000000
+ ifsr32_el2 :0x0000000000000000
+ par_el1 :0x0000000000000000
+ far_el1 :0x0000000000000000
+ afsr0_el1 :0x0000000000000000
+ afsr1_el1 :0x0000000000000000
+ contextidr_el1 :0x0000000000000000
+ vbar_el1 :0x0000000004027000
+ cntp_ctl_el0 :0x0000000000000000
+ cntp_cval_el0 :0x0000000000000000
+ cntv_ctl_el0 :0x0000000000000000
+ cntv_cval_el0 :0x0000000000000000
+ cntkctl_el1 :0x0000000000000000
+ fpexc32_el2 :0x0000000004000700
+ sp_el0 :0x0000000004010780
+
+Guidelines for Reset Handlers
+-----------------------------
+
+Trusted Firmware implements a framework that allows CPU and platform ports to
+perform actions very early after a CPU is released from reset in both the cold
+and warm boot paths. This is done by calling the ``reset_handler()`` function in
+both the BL1 and BL31 images. It in turn calls the platform and CPU specific
+reset handling functions.
+
+Details for implementing a CPU specific reset handler can be found in
+Section 8. Details for implementing a platform specific reset handler can be
+found in the `Porting Guide`_ (see the ``plat_reset_handler()`` function).
+
+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
+invocations of the reset handling code, this should be detected at runtime.
+In other words, the reset handler should be able to detect whether an action has
+already been performed and act as appropriate. Possible courses of actions are,
+e.g. skip the action the second time, or undo/redo it.
+
+CPU specific operations framework
+---------------------------------
+
+Certain aspects of the ARMv8 architecture are implementation defined,
+that is, certain behaviours are not architecturally defined, but must be defined
+and documented by individual processor implementations. The ARM Trusted
+Firmware implements a framework which categorises the common implementation
+defined behaviours and allows a processor to export its implementation of that
+behaviour. The categories are:
+
+#. Processor specific reset sequence.
+
+#. Processor specific power down sequences.
+
+#. Processor specific register dumping as a part of crash reporting.
+
+#. Errata status reporting.
+
+Each of the above categories fulfils a different requirement.
+
+#. allows any processor specific initialization before the caches and MMU
+ are turned on, like implementation of errata workarounds, entry into
+ the intra-cluster coherency domain etc.
+
+#. allows each processor to implement the power down sequence mandated in
+ its Technical Reference Manual (TRM).
+
+#. allows a processor to provide additional information to the developer
+ in the event of a crash, for example Cortex-A53 has registers which
+ can expose the data cache contents.
+
+#. allows a processor to define a function that inspects and reports the status
+ of all errata workarounds on that processor.
+
+Please note that only 2. is mandated by the TRM.
+
+The CPU specific operations framework scales to accommodate a large number of
+different CPUs during power down and reset handling. The platform can specify
+any CPU optimization it wants to enable for each CPU. It can also specify
+the CPU errata workarounds to be applied for each CPU type during reset
+handling by defining CPU errata compile time macros. Details on these macros
+can be found in the `cpu-specific-build-macros.rst`_ file.
+
+The CPU specific operations framework depends on the ``cpu_ops`` structure which
+needs to be exported for each type of CPU in the platform. It is defined in
+``include/lib/cpus/aarch64/cpu_macros.S`` and has the following fields : ``midr``,
+``reset_func()``, ``cpu_pwr_down_ops`` (array of power down functions) and
+``cpu_reg_dump()``.
+
+The CPU specific files in ``lib/cpus`` export a ``cpu_ops`` data structure with
+suitable handlers for that CPU. For example, ``lib/cpus/aarch64/cortex_a53.S``
+exports the ``cpu_ops`` for Cortex-A53 CPU. According to the platform
+configuration, these CPU specific files must be included in the build by
+the platform makefile. The generic CPU specific operations framework code exists
+in ``lib/cpus/aarch64/cpu_helpers.S``.
+
+CPU specific Reset Handling
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After a reset, the state of the CPU when it calls generic reset handler is:
+MMU turned off, both instruction and data caches turned off and not part
+of any coherency domain.
+
+The BL entrypoint code first invokes the ``plat_reset_handler()`` to allow
+the platform to perform any system initialization required and any system
+errata workarounds that needs to be applied. The ``get_cpu_ops_ptr()`` reads
+the current CPU midr, finds the matching ``cpu_ops`` entry in the ``cpu_ops``
+array and returns it. Note that only the part number and implementer fields
+in midr are used to find the matching ``cpu_ops`` entry. The ``reset_func()`` in
+the returned ``cpu_ops`` is then invoked which executes the required reset
+handling for that CPU and also any errata workarounds enabled by the platform.
+This function must preserve the values of general purpose registers x20 to x29.
+
+Refer to Section "Guidelines for Reset Handlers" for general guidelines
+regarding placement of code in a reset handler.
+
+CPU specific power down sequence
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+During the BL31 initialization sequence, the pointer to the matching ``cpu_ops``
+entry is stored in per-CPU data by ``init_cpu_ops()`` so that it can be quickly
+retrieved during power down sequences.
+
+Various CPU drivers register handlers to perform power down at certain power
+levels for that specific CPU. The PSCI service, upon receiving a power down
+request, determines the highest power level at which to execute power down
+sequence for a particular CPU. It uses the ``prepare_cpu_pwr_dwn()`` function to
+pick the right power down handler for the requested level. The function
+retrieves ``cpu_ops`` pointer member of per-CPU data, and from that, further
+retrieves ``cpu_pwr_down_ops`` array, and indexes into the required level. If the
+requested power level is higher than what a CPU driver supports, the handler
+registered for highest level is invoked.
+
+At runtime the platform hooks for power down are invoked by the PSCI service to
+perform platform specific operations during a power down sequence, for example
+turning off CCI coherency during a cluster power down.
+
+CPU specific register reporting during crash
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the crash reporting is enabled in BL31, when a crash occurs, the crash
+reporting framework calls ``do_cpu_reg_dump`` which retrieves the matching
+``cpu_ops`` using ``get_cpu_ops_ptr()`` function. The ``cpu_reg_dump()`` in
+``cpu_ops`` is invoked, which then returns the CPU specific register values to
+be reported and a pointer to the ASCII list of register names in a format
+expected by the crash reporting framework.
+
+CPU errata status reporting
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Errata workarounds for CPUs supported in ARM Trusted Firmware are applied during
+both cold and warm boots, shortly after reset. Individual Errata workarounds are
+enabled as build options. Some errata workarounds have potential run-time
+implications; therefore some are enabled by default, others not. Platform ports
+shall override build options to enable or disable errata as appropriate. The CPU
+drivers take care of applying errata workarounds that are enabled and applicable
+to a given CPU. Refer to the section titled *CPU Errata Workarounds* in `CPUBM`_
+for more information.
+
+Functions in CPU drivers that apply errata workaround must follow the
+conventions listed below.
+
+The errata workaround must be authored as two separate functions:
+
+- One that checks for errata. This function must determine whether that errata
+ applies to the current CPU. Typically this involves matching the current
+ CPUs revision and variant against a value that's known to be affected by the
+ errata. If the function determines that the errata applies to this CPU, it
+ must return ``ERRATA_APPLIES``; otherwise, it must return
+ ``ERRATA_NOT_APPLIES``. The utility functions ``cpu_get_rev_var`` and
+ ``cpu_rev_var_ls`` functions may come in handy for this purpose.
+
+For an errata identified as ``E``, the check function must be named
+``check_errata_E``.
+
+This function will be invoked at different times, both from assembly and from
+C run time. Therefore it must follow AAPCS, and must not use stack.
+
+- Another one that applies the errata workaround. This function would call the
+ check function described above, and applies errata workaround if required.
+
+CPU drivers that apply errata workaround can optionally implement an assembly
+function that report the status of errata workarounds pertaining to that CPU.
+For a driver that registers the CPU, for example, ``cpux`` via. ``declare_cpu_ops``
+macro, the errata reporting function, if it exists, must be named
+``cpux_errata_report``. This function will always be called with MMU enabled; it
+must follow AAPCS and may use stack.
+
+In a debug build of ARM Trusted Firmware, on a CPU that comes out of reset, both
+BL1 and the run time firmware (BL31 in AArch64, and BL32 in AArch32) will invoke
+errata status reporting function, if one exists, for that type of CPU.
+
+To report the status of each errata workaround, the function shall use the
+assembler macro ``report_errata``, passing it:
+
+- The build option that enables the errata;
+
+- The name of the CPU: this must be the same identifier that CPU driver
+ registered itself with, using ``declare_cpu_ops``;
+
+- And the errata identifier: the identifier must match what's used in the
+ errata's check function described above.
+
+The errata status reporting function will be called once per CPU type/errata
+combination during the software's active life time.
+
+It's expected that whenever an errata workaround is submitted to ARM Trusted
+Firmware, the errata reporting function is appropriately extended to report its
+status as well.
+
+Reporting the status of errata workaround is for informational purpose only; it
+has no functional significance.
+
+Memory layout of BL images
+--------------------------
+
+Each bootloader image can be divided in 2 parts:
+
+- the static contents of the image. These are data actually stored in the
+ binary on the disk. In the ELF terminology, they are called ``PROGBITS``
+ sections;
+
+- the run-time contents of the image. These are data that don't occupy any
+ space in the binary on the disk. The ELF binary just contains some
+ metadata indicating where these data will be stored at run-time and the
+ corresponding sections need to be allocated and initialized at run-time.
+ In the ELF terminology, they are called ``NOBITS`` sections.
+
+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
+and it is governed by the linker scripts. This ensures that the raw binary
+images are as small as possible. If a NOBITS section was inserted in between
+PROGBITS sections then the resulting binary file would contain zero bytes in
+place of this NOBITS section, making the image unnecessarily bigger. Smaller
+images allow faster loading from the FIP to the main memory.
+
+Linker scripts and symbols
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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
+correspond to particular addresses. The trusted firmware code can refer to these
+symbols to figure out the image memory layout.
+
+Linker symbols follow the following naming convention in the trusted firmware.
+
+- ``__<SECTION>_START__``
+
+ Start address of a given section named ``<SECTION>``.
+
+- ``__<SECTION>_END__``
+
+ End address of a given section named ``<SECTION>``. If there is an alignment
+ constraint on the section's end address then ``__<SECTION>_END__`` corresponds
+ 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
+ actual end address of the section's contents.
+
+- ``__<SECTION>_UNALIGNED_END__``
+
+ End address of a given section named ``<SECTION>`` without any padding or
+ rounding up due to some alignment constraint.
+
+- ``__<SECTION>_SIZE__``
+
+ Size (in bytes) of a given section named ``<SECTION>``. If there is an
+ alignment constraint on the section's end address then ``__<SECTION>_SIZE__``
+ corresponds to the size of the section's actual contents, rounded up to the
+ right boundary. In other words, ``__<SECTION>_SIZE__ = __<SECTION>_END__ - _<SECTION>_START__``. Refer to the value of ``__<SECTION>_UNALIGNED_SIZE__``
+ to know the actual size of the section's contents.
+
+- ``__<SECTION>_UNALIGNED_SIZE__``
+
+ Size (in bytes) of a given section named ``<SECTION>`` without any padding or
+ rounding up due to some alignment constraint. In other words,
+ ``__<SECTION>_UNALIGNED_SIZE__ = __<SECTION>_UNALIGNED_END__ - __<SECTION>_START__``.
+
+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
+must be provided for each bootloader stage and some are specific to a given
+bootloader stage.
+
+The linker scripts define some extra, optional symbols. They are not actually
+used by any code but they help in understanding the bootloader images' memory
+layout as they are easy to spot in the link map files.
+
+Common linker symbols
+^^^^^^^^^^^^^^^^^^^^^
+
+All BL images share the following requirements:
+
+- The BSS section must be zero-initialised before executing any C code.
+- The coherent memory section (if enabled) must be zero-initialised as well.
+- The MMU setup code needs to know the extents of the coherent and read-only
+ memory regions to set the right memory attributes. When
+ ``SEPARATE_CODE_AND_RODATA=1``, it needs to know more specifically how the
+ read-only memory region is divided between code and data.
+
+The following linker symbols are defined for this purpose:
+
+- ``__BSS_START__``
+- ``__BSS_SIZE__``
+- ``__COHERENT_RAM_START__`` Must be aligned on a page-size boundary.
+- ``__COHERENT_RAM_END__`` Must be aligned on a page-size boundary.
+- ``__COHERENT_RAM_UNALIGNED_SIZE__``
+- ``__RO_START__``
+- ``__RO_END__``
+- ``__TEXT_START__``
+- ``__TEXT_END__``
+- ``__RODATA_START__``
+- ``__RODATA_END__``
+
+BL1's linker symbols
+^^^^^^^^^^^^^^^^^^^^
+
+BL1 being the ROM image, it has additional requirements. BL1 resides in ROM and
+it is entirely executed in place but it needs some read-write memory for its
+mutable data. Its ``.data`` section (i.e. its allocated read-write data) must be
+relocated from ROM to RAM before executing any C code.
+
+The following additional linker symbols are defined for BL1:
+
+- ``__BL1_ROM_END__`` End address of BL1's ROM contents, covering its code
+ and ``.data`` section in ROM.
+- ``__DATA_ROM_START__`` Start address of the ``.data`` section in ROM. Must be
+ aligned on a 16-byte boundary.
+- ``__DATA_RAM_START__`` Address in RAM where the ``.data`` section should be
+ copied over. Must be aligned on a 16-byte boundary.
+- ``__DATA_SIZE__`` Size of the ``.data`` section (in ROM or RAM).
+- ``__BL1_RAM_START__`` Start address of BL1 read-write data.
+- ``__BL1_RAM_END__`` End address of BL1 read-write data.
+
+How to choose the right base addresses for each bootloader stage image
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There is currently no support for dynamic image loading in the Trusted Firmware.
+This means that all bootloader images need to be linked against their ultimate
+runtime locations and the base addresses of each image must be chosen carefully
+such that images don't overlap each other in an undesired way. As the code
+grows, the base addresses might need adjustments to cope with the new memory
+layout.
+
+The memory layout is completely specific to the platform and so there is no
+general recipe for choosing the right base addresses for each bootloader image.
+However, there are tools to aid in understanding the memory layout. These are
+the link map files: ``build/<platform>/<build-type>/bl<x>/bl<x>.map``, with ``<x>``
+being the stage bootloader. They provide a detailed view of the memory usage of
+each image. Among other useful information, they provide the end address of
+each image.
+
+- ``bl1.map`` link map file provides ``__BL1_RAM_END__`` address.
+- ``bl2.map`` link map file provides ``__BL2_END__`` address.
+- ``bl31.map`` link map file provides ``__BL31_END__`` address.
+- ``bl32.map`` link map file provides ``__BL32_END__`` address.
+
+For each bootloader image, the platform code must provide its start address
+as well as a limit address that it must not overstep. The latter is used in the
+linker scripts to check that the image doesn't grow past that address. If that
+happens, the linker will issue a message similar to the following:
+
+::
+
+ aarch64-none-elf-ld: BLx has exceeded its limit.
+
+Additionally, if the platform memory layout implies some image overlaying like
+on FVP, BL31 and TSP need to know the limit address that their PROGBITS
+sections must not overstep. The platform code must provide those.
+
+When LOAD\_IMAGE\_V2 is disabled, Trusted Firmware provides a mechanism to
+verify at boot time that the memory to load a new image is free to prevent
+overwriting a previously loaded image. For this mechanism to work, the platform
+must specify the memory available in the system as regions, where each region
+consists of base address, total size and the free area within it (as defined
+in the ``meminfo_t`` structure). Trusted Firmware retrieves these memory regions
+by calling the corresponding platform API:
+
+- ``meminfo_t *bl1_plat_sec_mem_layout(void)``
+- ``meminfo_t *bl2_plat_sec_mem_layout(void)``
+- ``void bl2_plat_get_scp_bl2_meminfo(meminfo_t *scp_bl2_meminfo)``
+- ``void bl2_plat_get_bl32_meminfo(meminfo_t *bl32_meminfo)``
+- ``void bl2_plat_get_bl33_meminfo(meminfo_t *bl33_meminfo)``
+
+For example, in the case of BL1 loading BL2, ``bl1_plat_sec_mem_layout()`` will
+return the region defined by the platform where BL1 intends to load BL2. The
+``load_image()`` function will check that the memory where BL2 will be loaded is
+within the specified region and marked as free.
+
+The actual number of regions and their base addresses and sizes is platform
+specific. The platform may return the same region or define a different one for
+each API. However, the overlap verification mechanism applies only to a single
+region. Hence, it is the platform responsibility to guarantee that different
+regions do not overlap, or that if they do, the overlapping images are not
+accessed at the same time. This could be used, for example, to load temporary
+images (e.g. certificates) or firmware images prior to being transfered to its
+corresponding processor (e.g. the SCP BL2 image).
+
+To reduce fragmentation and simplify the tracking of free memory, all the free
+memory within a region is always located in one single buffer defined by its
+base address and size. Trusted Firmware implements a top/bottom load approach:
+after a new image is loaded, it checks how much memory remains free above and
+below the image. The smallest area is marked as unavailable, while the larger
+area becomes the new free memory buffer. Platforms should take this behaviour
+into account when defining the base address for each of the images. For example,
+if an image is loaded near the middle of the region, small changes in image size
+could cause a flip between a top load and a bottom load, which may result in an
+unexpected memory layout.
+
+The following diagram is an example of an image loaded in the bottom part of
+the memory region. The region is initially free (nothing has been loaded yet):
+
+::
+
+ Memory region
+ +----------+
+ | |
+ | | <<<<<<<<<<<<< Free
+ | |
+ |----------| +------------+
+ | image | <<<<<<<<<<<<< | image |
+ |----------| +------------+
+ | xxxxxxxx | <<<<<<<<<<<<< Marked as unavailable
+ +----------+
+
+And the following diagram is an example of an image loaded in the top part:
+
+::
+
+ Memory region
+ +----------+
+ | xxxxxxxx | <<<<<<<<<<<<< Marked as unavailable
+ |----------| +------------+
+ | image | <<<<<<<<<<<<< | image |
+ |----------| +------------+
+ | |
+ | | <<<<<<<<<<<<< Free
+ | |
+ +----------+
+
+When LOAD\_IMAGE\_V2 is enabled, Trusted Firmware does not provide any mechanism
+to verify at boot time that the memory to load a new image is free to prevent
+overwriting a previously loaded image. The platform must specify the memory
+available in the system for all the relevant BL images to be loaded.
+
+For example, in the case of BL1 loading BL2, ``bl1_plat_sec_mem_layout()`` will
+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
+base and maximum image size provided by the platforms. Platforms must take
+this behaviour into account when defining the base/size for each of the images.
+
+Memory layout on ARM development platforms
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following list describes the memory layout on the ARM development platforms:
+
+- A 4KB page of shared memory is used for communication between Trusted
+ Firmware and the platform's power controller. This is located at the base of
+ Trusted SRAM. The amount of Trusted SRAM available to load the bootloader
+ images is reduced by the size of the shared memory.
+
+ The shared memory is used to store the CPUs' entrypoint mailbox. On Juno,
+ this is also used for the MHU payload when passing messages to and from the
+ SCP.
+
+- On FVP, BL1 is originally sitting in the Trusted ROM at address ``0x0``. On
+ Juno, BL1 resides in flash memory at address ``0x0BEC0000``. BL1 read-write
+ 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),
+ is loaded at the top of the Trusted SRAM, such that its NOBITS sections will
+ overwrite BL1 R/W data. This implies that BL1 global variables remain valid
+ only until execution reaches the EL3 Runtime Software entry point during a
+ cold boot.
+
+- BL2 is loaded below EL3 Runtime Software.
+
+- On Juno, SCP\_BL2 is loaded temporarily into the EL3 Runtime Software memory
+ region and transfered to the SCP before being overwritten by EL3 Runtime
+ Software.
+
+- BL32 (for AArch64) can be loaded in one of the following locations:
+
+ - Trusted SRAM
+ - Trusted DRAM (FVP only)
+ - Secure region of DRAM (top 16MB of DRAM configured by the TrustZone
+ controller)
+
+ When BL32 (for AArch64) is loaded into Trusted SRAM, its NOBITS sections
+ are allowed to overlay BL2. This memory layout is designed to give the
+ BL32 image as much memory as possible when it is loaded into Trusted SRAM.
+
+When LOAD\_IMAGE\_V2 is disabled the memory regions for the overlap detection
+mechanism at boot time are defined as follows (shown per API):
+
+- ``meminfo_t *bl1_plat_sec_mem_layout(void)``
+
+ This region corresponds to the whole Trusted SRAM except for the shared
+ memory at the base. This region is initially free. At boot time, BL1 will
+ mark the BL1(rw) section within this region as occupied. The BL1(rw) section
+ is placed at the top of Trusted SRAM.
+
+- ``meminfo_t *bl2_plat_sec_mem_layout(void)``
+
+ This region corresponds to the whole Trusted SRAM as defined by
+ ``bl1_plat_sec_mem_layout()``, but with the BL1(rw) section marked as
+ occupied. This memory region is used to check that BL2 and BL31 do not
+ overlap with each other. BL2\_BASE and BL1\_RW\_BASE are carefully chosen so
+ that the memory for BL31 is top loaded above BL2.
+
+- ``void bl2_plat_get_scp_bl2_meminfo(meminfo_t *scp_bl2_meminfo)``
+
+ This region is an exact copy of the region defined by
+ ``bl2_plat_sec_mem_layout()``. Being a disconnected copy means that all the
+ changes made to this region by the Trusted Firmware will not be propagated.
+ This approach is valid because the SCP BL2 image is loaded temporarily
+ while it is being transferred to the SCP, so this memory is reused
+ afterwards.
+
+- ``void bl2_plat_get_bl32_meminfo(meminfo_t *bl32_meminfo)``
+
+ This region depends on the location of the BL32 image. Currently, ARM
+ platforms support three different locations (detailed below): Trusted SRAM,
+ Trusted DRAM and the TZC-Secured DRAM.
+
+- ``void bl2_plat_get_bl33_meminfo(meminfo_t *bl33_meminfo)``
+
+ This region corresponds to the Non-Secure DDR-DRAM, excluding the
+ TZC-Secured area.
+
+The location of the BL32 image will result in different memory maps. This is
+illustrated for both FVP and Juno in the following diagrams, using the TSP as
+an example.
+
+Note: Loading the BL32 image in TZC secured DRAM doesn't change the memory
+layout of the other images in Trusted SRAM.
+
+**FVP with TSP in Trusted SRAM (default option):**
+(These diagrams only cover the AArch64 case)
+
+::
+
+ Trusted SRAM
+ 0x04040000 +----------+ loaded by BL2 ------------------
+ | BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS |
+ |----------| <<<<<<<<<<<<< |----------------|
+ | | <<<<<<<<<<<<< | BL31 PROGBITS |
+ |----------| ------------------
+ | BL2 | <<<<<<<<<<<<< | BL32 NOBITS |
+ |----------| <<<<<<<<<<<<< |----------------|
+ | | <<<<<<<<<<<<< | BL32 PROGBITS |
+ 0x04001000 +----------+ ------------------
+ | Shared |
+ 0x04000000 +----------+
+
+ Trusted ROM
+ 0x04000000 +----------+
+ | BL1 (ro) |
+ 0x00000000 +----------+
+
+**FVP with TSP in Trusted DRAM:**
+
+::
+
+ Trusted DRAM
+ 0x08000000 +----------+
+ | BL32 |
+ 0x06000000 +----------+
+
+ Trusted SRAM
+ 0x04040000 +----------+ loaded by BL2 ------------------
+ | BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS |
+ |----------| <<<<<<<<<<<<< |----------------|
+ | | <<<<<<<<<<<<< | BL31 PROGBITS |
+ |----------| ------------------
+ | BL2 |
+ |----------|
+ | |
+ 0x04001000 +----------+
+ | Shared |
+ 0x04000000 +----------+
+
+ Trusted ROM
+ 0x04000000 +----------+
+ | BL1 (ro) |
+ 0x00000000 +----------+
+
+**FVP with TSP in TZC-Secured DRAM:**
+
+::
+
+ DRAM
+ 0xffffffff +----------+
+ | BL32 | (secure)
+ 0xff000000 +----------+
+ | |
+ : : (non-secure)
+ | |
+ 0x80000000 +----------+
+
+ Trusted SRAM
+ 0x04040000 +----------+ loaded by BL2 ------------------
+ | BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS |
+ |----------| <<<<<<<<<<<<< |----------------|
+ | | <<<<<<<<<<<<< | BL31 PROGBITS |
+ |----------| ------------------
+ | BL2 |
+ |----------|
+ | |
+ 0x04001000 +----------+
+ | Shared |
+ 0x04000000 +----------+
+
+ Trusted ROM
+ 0x04000000 +----------+
+ | BL1 (ro) |
+ 0x00000000 +----------+
+
+**Juno with BL32 in Trusted SRAM (default option):**
+
+::
+
+ Flash0
+ 0x0C000000 +----------+
+ : :
+ 0x0BED0000 |----------|
+ | BL1 (ro) |
+ 0x0BEC0000 |----------|
+ : :
+ 0x08000000 +----------+ BL31 is loaded
+ after SCP_BL2 has
+ Trusted SRAM been sent to SCP
+ 0x04040000 +----------+ loaded by BL2 ------------------
+ | BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS |
+ |----------| <<<<<<<<<<<<< |----------------|
+ | SCP_BL2 | <<<<<<<<<<<<< | BL31 PROGBITS |
+ |----------| ------------------
+ | BL2 | <<<<<<<<<<<<< | BL32 NOBITS |
+ |----------| <<<<<<<<<<<<< |----------------|
+ | | <<<<<<<<<<<<< | BL32 PROGBITS |
+ 0x04001000 +----------+ ------------------
+ | MHU |
+ 0x04000000 +----------+
+
+**Juno with BL32 in TZC-secured DRAM:**
+
+::
+
+ DRAM
+ 0xFFE00000 +----------+
+ | BL32 | (secure)
+ 0xFF000000 |----------|
+ | |
+ : : (non-secure)
+ | |
+ 0x80000000 +----------+
+
+ Flash0
+ 0x0C000000 +----------+
+ : :
+ 0x0BED0000 |----------|
+ | BL1 (ro) |
+ 0x0BEC0000 |----------|
+ : :
+ 0x08000000 +----------+ BL31 is loaded
+ after SCP_BL2 has
+ Trusted SRAM been sent to SCP
+ 0x04040000 +----------+ loaded by BL2 ------------------
+ | BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS |
+ |----------| <<<<<<<<<<<<< |----------------|
+ | SCP_BL2 | <<<<<<<<<<<<< | BL31 PROGBITS |
+ |----------| ------------------
+ | BL2 |
+ |----------|
+ | |
+ 0x04001000 +----------+
+ | MHU |
+ 0x04000000 +----------+
+
+Firmware Image Package (FIP)
+----------------------------
+
+Using a Firmware Image Package (FIP) allows for packing bootloader images (and
+potentially other payloads) into a single archive that can be loaded by the ARM
+Trusted Firmware from non-volatile platform storage. A driver to load images
+from a FIP has been added to the storage layer and allows a package to be read
+from supported platform storage. A tool to create Firmware Image Packages is
+also provided and described below.
+
+Firmware Image Package layout
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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
+terminated by an end marker entry. All ToC entries describe some payload data
+that has been appended to the end of the binary package. With the information
+provided in the ToC entry the corresponding payload data can be retrieved.
+
+::
+
+ ------------------
+ | ToC Header |
+ |----------------|
+ | ToC Entry 0 |
+ |----------------|
+ | ToC Entry 1 |
+ |----------------|
+ | ToC End Marker |
+ |----------------|
+ | |
+ | Data 0 |
+ | |
+ |----------------|
+ | |
+ | Data 1 |
+ | |
+ ------------------
+
+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
+tool and the ARM Trusted firmware.
+
+The ToC header has the following fields:
+
+::
+
+ `name`: The name of the ToC. This is currently used to validate the header.
+ `serial_number`: A non-zero number provided by the creation tool
+ `flags`: Flags associated with this data.
+ Bits 0-31: Reserved
+ Bits 32-47: Platform defined
+ Bits 48-63: Reserved
+
+A ToC entry has the following fields:
+
+::
+
+ `uuid`: All files are referred to by a pre-defined Universally Unique
+ IDentifier [UUID] . The UUIDs are defined in
+ `include/tools_share/firmware_image_package.h`. The platform translates
+ the requested image name into the corresponding UUID when accessing the
+ package.
+ `offset_address`: The offset address at which the corresponding payload data
+ can be found. The offset is calculated from the ToC base address.
+ `size`: The size of the corresponding payload data in bytes.
+ `flags`: Flags associated with this entry. Non are yet defined.
+
+Firmware Image Package creation tool
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The FIP creation tool can be used to pack specified images into a binary package
+that can be loaded by the ARM Trusted Firmware from platform storage. The tool
+currently only supports packing bootloader images. Additional image definitions
+can be added to the tool as required.
+
+The tool can be found in ``tools/fiptool``.
+
+Loading from a Firmware Image Package (FIP)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Firmware Image Package (FIP) driver can load images from a binary package on
+non-volatile platform storage. For the ARM development platforms, this is
+currently NOR FLASH.
+
+Bootloader images are loaded according to the platform policy as specified by
+the function ``plat_get_image_source()``. For the ARM development platforms, this
+means the platform will attempt to load images from a Firmware Image Package
+located at the start of NOR FLASH0.
+
+The ARM development platforms' policy is to only allow loading of a known set of
+images. The platform policy can be modified to allow additional images.
+
+Use of coherent memory in Trusted Firmware
+------------------------------------------
+
+There might be loss of coherency when physical memory with mismatched
+shareability, cacheability and memory attributes is accessed by multiple CPUs
+(refer to section B2.9 of `ARM ARM`_ for more details). This possibility occurs
+in Trusted Firmware during power up/down sequences when coherency, MMU and
+caches are turned on/off incrementally.
+
+Trusted Firmware defines coherent memory as a region of memory with Device
+nGnRE attributes in the translation tables. The translation granule size in
+Trusted Firmware is 4KB. This is the smallest possible size of the coherent
+memory region.
+
+By default, all data structures which are susceptible to accesses with
+mismatched attributes from various CPUs are allocated in a coherent memory
+region (refer to section 2.1 of `Porting Guide`_). The coherent memory region
+accesses are Outer Shareable, non-cacheable and they can be accessed
+with the Device nGnRE attributes when the MMU is turned on. Hence, at the
+expense of at least an extra page of memory, Trusted Firmware is able to work
+around coherency issues due to mismatched memory attributes.
+
+The alternative to the above approach is to allocate the susceptible data
+structures in Normal WriteBack WriteAllocate Inner shareable memory. This
+approach requires the data structures to be designed so that it is possible to
+work around the issue of mismatched memory attributes by performing software
+cache maintenance on them.
+
+Disabling the use of coherent memory in Trusted Firmware
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It might be desirable to avoid the cost of allocating coherent memory on
+platforms which are memory constrained. Trusted Firmware enables inclusion of
+coherent memory in firmware images through the build flag ``USE_COHERENT_MEM``.
+This flag is enabled by default. It can be disabled to choose the second
+approach described above.
+
+The below sections analyze the data structures allocated in the coherent memory
+region and the changes required to allocate them in normal memory.
+
+Coherent memory usage in PSCI implementation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``psci_non_cpu_pd_nodes`` data structure stores the platform's power domain
+tree information for state management of power domains. By default, this data
+structure is allocated in the coherent memory region in the Trusted Firmware
+because it can be accessed by multple CPUs, either with caches enabled or
+disabled.
+
+.. code:: c
+
+ typedef struct non_cpu_pwr_domain_node {
+ /*
+ * Index of the first CPU power domain node level 0 which has this node
+ * as its parent.
+ */
+ unsigned int cpu_start_idx;
+
+ /*
+ * Number of CPU power domains which are siblings of the domain indexed
+ * by 'cpu_start_idx' i.e. all the domains in the range 'cpu_start_idx
+ * -> cpu_start_idx + ncpus' have this node as their parent.
+ */
+ unsigned int ncpus;
+
+ /*
+ * Index of the parent power domain node.
+ * TODO: Figure out whether to whether using pointer is more efficient.
+ */
+ unsigned int parent_node;
+
+ plat_local_state_t local_state;
+
+ unsigned char level;
+
+ /* For indexing the psci_lock array*/
+ unsigned char lock_index;
+ } non_cpu_pd_node_t;
+
+In order to move this data structure to normal memory, the use of each of its
+fields must be analyzed. Fields like ``cpu_start_idx``, ``ncpus``, ``parent_node``
+``level`` and ``lock_index`` are only written once during cold boot. Hence removing
+them from coherent memory involves only doing a clean and invalidate of the
+cache lines after these fields are written.
+
+The field ``local_state`` can be concurrently accessed by multiple CPUs in
+different cache states. A Lamport's Bakery lock ``psci_locks`` is used to ensure
+mutual exlusion to this field and a clean and invalidate is needed after it
+is written.
+
+Bakery lock data
+~~~~~~~~~~~~~~~~
+
+The bakery lock data structure ``bakery_lock_t`` is allocated in coherent memory
+and is accessed by multiple CPUs with mismatched attributes. ``bakery_lock_t`` is
+defined as follows:
+
+.. code:: c
+
+ typedef struct bakery_lock {
+ /*
+ * The lock_data is a bit-field of 2 members:
+ * Bit[0] : choosing. This field is set when the CPU is
+ * choosing its bakery number.
+ * Bits[1 - 15] : number. This is the bakery number allocated.
+ */
+ volatile uint16_t lock_data[BAKERY_LOCK_MAX_CPUS];
+ } bakery_lock_t;
+
+It is a characteristic of Lamport's Bakery algorithm that the volatile per-CPU
+fields can be read by all CPUs but only written to by the owning CPU.
+
+Depending upon the data cache line size, the per-CPU fields of the
+``bakery_lock_t`` structure for multiple CPUs may exist on a single cache line.
+These per-CPU fields can be read and written during lock contention by multiple
+CPUs with mismatched memory attributes. Since these fields are a part of the
+lock implementation, they do not have access to any other locking primitive to
+safeguard against the resulting coherency issues. As a result, simple software
+cache maintenance is not enough to allocate them in coherent memory. Consider
+the following example.
+
+CPU0 updates its per-CPU field with data cache enabled. This write updates a
+local cache line which contains a copy of the fields for other CPUs as well. Now
+CPU1 updates its per-CPU field of the ``bakery_lock_t`` structure with data cache
+disabled. CPU1 then issues a DCIVAC operation to invalidate any stale copies of
+its field in any other cache line in the system. This operation will invalidate
+the update made by CPU0 as well.
+
+To use bakery locks when ``USE_COHERENT_MEM`` is disabled, the lock data structure
+has been redesigned. The changes utilise the characteristic of Lamport's Bakery
+algorithm mentioned earlier. The bakery\_lock structure only allocates the memory
+for a single CPU. The macro ``DEFINE_BAKERY_LOCK`` allocates all the bakery locks
+needed for a CPU into a section ``bakery_lock``. The linker allocates the memory
+for other cores by using the total size allocated for the bakery\_lock section
+and multiplying it with (PLATFORM\_CORE\_COUNT - 1). This enables software to
+perform software cache maintenance on the lock data structure without running
+into coherency issues associated with mismatched attributes.
+
+The bakery lock data structure ``bakery_info_t`` is defined for use when
+``USE_COHERENT_MEM`` is disabled as follows:
+
+.. code:: c
+
+ typedef struct bakery_info {
+ /*
+ * The lock_data is a bit-field of 2 members:
+ * Bit[0] : choosing. This field is set when the CPU is
+ * choosing its bakery number.
+ * Bits[1 - 15] : number. This is the bakery number allocated.
+ */
+ volatile uint16_t lock_data;
+ } bakery_info_t;
+
+The ``bakery_info_t`` represents a single per-CPU field of one lock and
+the combination of corresponding ``bakery_info_t`` structures for all CPUs in the
+system represents the complete bakery lock. The view in memory for a system
+with n bakery locks are:
+
+::
+
+ bakery_lock section start
+ |----------------|
+ | `bakery_info_t`| <-- Lock_0 per-CPU field
+ | Lock_0 | for CPU0
+ |----------------|
+ | `bakery_info_t`| <-- Lock_1 per-CPU field
+ | Lock_1 | for CPU0
+ |----------------|
+ | .... |
+ |----------------|
+ | `bakery_info_t`| <-- Lock_N per-CPU field
+ | Lock_N | for CPU0
+ ------------------
+ | XXXXX |
+ | Padding to |
+ | next Cache WB | <--- Calculate PERCPU_BAKERY_LOCK_SIZE, allocate
+ | Granule | continuous memory for remaining CPUs.
+ ------------------
+ | `bakery_info_t`| <-- Lock_0 per-CPU field
+ | Lock_0 | for CPU1
+ |----------------|
+ | `bakery_info_t`| <-- Lock_1 per-CPU field
+ | Lock_1 | for CPU1
+ |----------------|
+ | .... |
+ |----------------|
+ | `bakery_info_t`| <-- Lock_N per-CPU field
+ | Lock_N | for CPU1
+ ------------------
+ | XXXXX |
+ | Padding to |
+ | next Cache WB |
+ | Granule |
+ ------------------
+
+Consider a system of 2 CPUs with 'N' bakery locks as shown above. For an
+operation on Lock\_N, the corresponding ``bakery_info_t`` in both CPU0 and CPU1
+``bakery_lock`` section need to be fetched and appropriate cache operations need
+to be performed for each access.
+
+On ARM Platforms, bakery locks are used in psci (``psci_locks``) and power controller
+driver (``arm_lock``).
+
+Non Functional Impact of removing coherent memory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Removal of the coherent memory region leads to the additional software overhead
+of performing cache maintenance for the affected data structures. However, since
+the memory where the data structures are allocated is cacheable, the overhead is
+mostly mitigated by an increase in performance.
+
+There is however a performance impact for bakery locks, due to:
+
+- Additional cache maintenance operations, and
+- Multiple cache line reads for each lock operation, since the bakery locks
+ for each CPU are distributed across different cache lines.
+
+The implementation has been optimized to minimize this additional overhead.
+Measurements indicate that when bakery locks are allocated in Normal memory, the
+minimum latency of acquiring a lock is on an average 3-4 micro seconds whereas
+in Device memory the same is 2 micro seconds. The measurements were done on the
+Juno ARM development platform.
+
+As mentioned earlier, almost a page of memory can be saved by disabling
+``USE_COHERENT_MEM``. Each platform needs to consider these trade-offs to decide
+whether coherent memory should be used. If a platform disables
+``USE_COHERENT_MEM`` and needs to use bakery locks in the porting layer, it can
+optionally define macro ``PLAT_PERCPU_BAKERY_LOCK_SIZE`` (see the
+`Porting Guide`_). Refer to the reference platform code for examples.
+
+Isolating code and read-only data on separate memory pages
+----------------------------------------------------------
+
+In the ARMv8 VMSA, translation table entries include fields that define the
+properties of the target memory region, such as its access permissions. The
+smallest unit of memory that can be addressed by a translation table entry is
+a memory page. Therefore, if software needs to set different permissions on two
+memory regions then it needs to map them using different memory pages.
+
+The default memory layout for each BL image is as follows:
+
+::
+
+ | ... |
+ +-------------------+
+ | Read-write data |
+ +-------------------+ Page boundary
+ | <Padding> |
+ +-------------------+
+ | Exception vectors |
+ +-------------------+ 2 KB boundary
+ | <Padding> |
+ +-------------------+
+ | Read-only data |
+ +-------------------+
+ | Code |
+ +-------------------+ BLx_BASE
+
+Note: The 2KB alignment for the exception vectors is an architectural
+requirement.
+
+The read-write data start on a new memory page so that they can be mapped with
+read-write permissions, whereas the code and read-only data below are configured
+as read-only.
+
+However, the read-only data are not aligned on a page boundary. They are
+contiguous to the code. Therefore, the end of the code section and the beginning
+of the read-only data one might share a memory page. This forces both to be
+mapped with the same memory attributes. As the code needs to be executable, this
+means that the read-only data stored on the same memory page as the code are
+executable as well. This could potentially be exploited as part of a security
+attack.
+
+TF provides the build flag ``SEPARATE_CODE_AND_RODATA`` to isolate the code and
+read-only data on separate memory pages. This in turn allows independent control
+of the access permissions for the code and read-only data. In this case,
+platform code gets a finer-grained view of the image layout and can
+appropriately map the code region as executable and the read-only data as
+execute-never.
+
+This has an impact on memory footprint, as padding bytes need to be introduced
+between the code and read-only data to ensure the segragation of the two. To
+limit the memory cost, this flag also changes the memory layout such that the
+code and exception vectors are now contiguous, like so:
+
+::
+
+ | ... |
+ +-------------------+
+ | Read-write data |
+ +-------------------+ Page boundary
+ | <Padding> |
+ +-------------------+
+ | Read-only data |
+ +-------------------+ Page boundary
+ | <Padding> |
+ +-------------------+
+ | Exception vectors |
+ +-------------------+ 2 KB boundary
+ | <Padding> |
+ +-------------------+
+ | Code |
+ +-------------------+ BLx_BASE
+
+With this more condensed memory layout, the separation of read-only data will
+add zero or one page to the memory footprint of each BL image. Each platform
+should consider the trade-off between memory footprint and security.
+
+This build flag is disabled by default, minimising memory footprint. On ARM
+platforms, it is enabled.
+
+Performance Measurement Framework
+---------------------------------
+
+The Performance Measurement Framework (PMF) facilitates collection of
+timestamps by registered services and provides interfaces to retrieve
+them from within the ARM Trusted Firmware. A platform can choose to
+expose appropriate SMCs to retrieve these collected timestamps.
+
+By default, the global physical counter is used for the timestamp
+value and is read via ``CNTPCT_EL0``. The framework allows to retrieve
+timestamps captured by other CPUs.
+
+Timestamp identifier format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A PMF timestamp is uniquely identified across the system via the
+timestamp ID or ``tid``. The ``tid`` is composed as follows:
+
+::
+
+ Bits 0-7: The local timestamp identifier.
+ Bits 8-9: Reserved.
+ Bits 10-15: The service identifier.
+ Bits 16-31: Reserved.
+
+#. The service identifier. Each PMF service is identified by a
+ service name and a service identifier. Both the service name and
+ identifier are unique within the system as a whole.
+
+#. The local timestamp identifier. This identifier is unique within a given
+ service.
+
+Registering a PMF service
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To register a PMF service, the ``PMF_REGISTER_SERVICE()`` macro from ``pmf.h``
+is used. The arguments required are the service name, the service ID,
+the total number of local timestamps to be captured and a set of flags.
+
+The ``flags`` field can be specified as a bitwise-OR of the following values:
+
+::
+
+ PMF_STORE_ENABLE: The timestamp is stored in memory for later retrieval.
+ PMF_DUMP_ENABLE: The timestamp is dumped on the serial console.
+
+The ``PMF_REGISTER_SERVICE()`` reserves memory to store captured
+timestamps in a PMF specific linker section at build time.
+Additionally, it defines necessary functions to capture and
+retrieve a particular timestamp for the given service at runtime.
+
+The macro ``PMF_REGISTER_SERVICE()`` only enables capturing PMF
+timestamps from within ARM Trusted Firmware. In order to retrieve
+timestamps from outside of ARM Trusted Firmware, the
+``PMF_REGISTER_SERVICE_SMC()`` macro must be used instead. This macro
+accepts the same set of arguments as the ``PMF_REGISTER_SERVICE()``
+macro but additionally supports retrieving timestamps using SMCs.
+
+Capturing a timestamp
+~~~~~~~~~~~~~~~~~~~~~
+
+PMF timestamps are stored in a per-service timestamp region. On a
+system with multiple CPUs, each timestamp is captured and stored
+in a per-CPU cache line aligned memory region.
+
+Having registered the service, the ``PMF_CAPTURE_TIMESTAMP()`` macro can be
+used to capture a timestamp at the location where it is used. The macro
+takes the service name, a local timestamp identifier and a flag as arguments.
+
+The ``flags`` field argument can be zero, or ``PMF_CACHE_MAINT`` which
+instructs PMF to do cache maintenance following the capture. Cache
+maintenance is required if any of the service's timestamps are captured
+with data cache disabled.
+
+To capture a timestamp in assembly code, the caller should use
+``pmf_calc_timestamp_addr`` macro (defined in ``pmf_asm_macros.S``) to
+calculate the address of where the timestamp would be stored. The
+caller should then read ``CNTPCT_EL0`` register to obtain the timestamp
+and store it at the determined address for later retrieval.
+
+Retrieving a timestamp
+~~~~~~~~~~~~~~~~~~~~~~
+
+From within ARM Trusted Firmware, timestamps for individual CPUs can
+be retrieved using either ``PMF_GET_TIMESTAMP_BY_MPIDR()`` or
+``PMF_GET_TIMESTAMP_BY_INDEX()`` macros. These macros accept the CPU's MPIDR
+value, or its ordinal position, respectively.
+
+From outside ARM Trusted Firmware, timestamps for individual CPUs can be
+retrieved by calling into ``pmf_smc_handler()``.
+
+.. code:: c
+
+ Interface : pmf_smc_handler()
+ Argument : unsigned int smc_fid, u_register_t x1,
+ u_register_t x2, u_register_t x3,
+ u_register_t x4, void *cookie,
+ void *handle, u_register_t flags
+ Return : uintptr_t
+
+ smc_fid: Holds the SMC identifier which is either `PMF_SMC_GET_TIMESTAMP_32`
+ when the caller of the SMC is running in AArch32 mode
+ or `PMF_SMC_GET_TIMESTAMP_64` when the caller is running in AArch64 mode.
+ x1: Timestamp identifier.
+ x2: The `mpidr` of the CPU for which the timestamp has to be retrieved.
+ This can be the `mpidr` of a different core to the one initiating
+ the SMC. In that case, service specific cache maintenance may be
+ required to ensure the updated copy of the timestamp is returned.
+ x3: A flags value that is either 0 or `PMF_CACHE_MAINT`. If
+ `PMF_CACHE_MAINT` is passed, then the PMF code will perform a
+ cache invalidate before reading the timestamp. This ensures
+ an updated copy is returned.
+
+The remaining arguments, ``x4``, ``cookie``, ``handle`` and ``flags`` are unused
+in this implementation.
+
+PMF code structure
+~~~~~~~~~~~~~~~~~~
+
+#. ``pmf_main.c`` consists of core functions that implement service registration,
+ initialization, storing, dumping and retrieving timestamps.
+
+#. ``pmf_smc.c`` contains the SMC handling for registered PMF services.
+
+#. ``pmf.h`` contains the public interface to Performance Measurement Framework.
+
+#. ``pmf_asm_macros.S`` consists of macros to facilitate capturing timestamps in
+ assembly code.
+
+#. ``pmf_helpers.h`` is an internal header used by ``pmf.h``.
+
+#. .. rubric:: ARMv8 Architecture Extensions
+ :name: armv8-architecture-extensions
+
+ARM Trusted Firmware makes use of ARMv8 Architecture Extensions where
+applicable. This section lists the usage of Architecture Extensions, and build
+flags controlling them.
+
+In general, and unless individually mentioned, the build options
+``ARM_ARCH_MAJOR`` and ``ARM_ARCH_MINOR`` selects the Architecture Extension to
+target when building ARM Trusted Firmware. Subsequent ARM Architecture
+Extensions are backward compatible with previous versions.
+
+The build system only requires that ``ARM_ARCH_MAJOR`` and ``ARM_ARCH_MINOR`` have a
+valid numeric value. These build options only control whether or not
+Architecture Extension-specific code is included in the build. Otherwise, ARM
+Trusted Firmware targets the base ARMv8.0 architecture; i.e. as if
+``ARM_ARCH_MAJOR`` == 8 and ``ARM_ARCH_MINOR`` == 0, which are also their respective
+default values.
+
+See also the *Summary of build options* in `User Guide`_.
+
+For details on the Architecture Extension and available features, please refer
+to the respective Architecture Extension Supplement.
+
+ARMv8.1
+~~~~~~~
+
+This Architecture Extension is targeted when ``ARM_ARCH_MAJOR`` >= 8, or when
+``ARM_ARCH_MAJOR`` == 8 and ``ARM_ARCH_MINOR`` >= 1.
+
+- The Compare and Swap instruction is used to implement spinlocks. Otherwise,
+ the load-/store-exclusive instruction pair is used.
+
+Code Structure
+--------------
+
+Trusted Firmware code is logically divided between the three boot loader
+stages mentioned in the previous sections. The code is also divided into the
+following categories (present as directories in the source code):
+
+- **Platform specific.** Choice of architecture specific code depends upon
+ the platform.
+- **Common code.** This is platform and architecture agnostic code.
+- **Library code.** This code comprises of functionality commonly used by all
+ other code. The PSCI implementation and other EL3 runtime frameworks reside
+ as Library components.
+- **Stage specific.** Code specific to a boot stage.
+- **Drivers.**
+- **Services.** EL3 runtime services (eg: SPD). Specific SPD services
+ reside in the ``services/spd`` directory (e.g. ``services/spd/tspd``).
+
+Each boot loader stage uses code from one or more of the above mentioned
+categories. Based upon the above, the code layout looks like this:
+
+::
+
+ Directory Used by BL1? Used by BL2? Used by BL31?
+ bl1 Yes No No
+ bl2 No Yes No
+ bl31 No No Yes
+ plat Yes Yes Yes
+ drivers Yes No Yes
+ common Yes Yes Yes
+ lib Yes Yes Yes
+ services No No Yes
+
+The build system provides a non configurable build option IMAGE\_BLx for each
+boot loader stage (where x = BL stage). e.g. for BL1 , IMAGE\_BL1 will be
+defined by the build system. This enables the Trusted Firmware to compile
+certain code only for specific boot loader stages
+
+All assembler files have the ``.S`` extension. The linker source files for each
+boot stage have the extension ``.ld.S``. These are processed by GCC to create the
+linker scripts which have the extension ``.ld``.
+
+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.
+
+References
+----------
+
+.. [#] Trusted Board Boot Requirements CLIENT PDD (ARM DEN 0006B-5). Available
+ under NDA through your ARM account representative.
+.. [#] `Power State Coordination Interface PDD`_
+.. [#] `SMC Calling Convention PDD`_
+.. [#] `ARM Trusted Firmware Interrupt Management Design guide`_.
+
+--------------
+
+*Copyright (c) 2013-2016, ARM Limited and Contributors. All rights reserved.*
+
+.. _Reset Design: ./reset-design.rst
+.. _Porting Guide: ./porting-guide.rst
+.. _Firmware Update: ./firmware-update.rst
+.. _PSCI PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
+.. _SMC calling convention PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
+.. _PSCI Library integration guide: ./psci-lib-integration-guide.rst
+.. _SMCCC: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
+.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
+.. _Power State Coordination Interface PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
+.. _here: ./psci-lib-integration-guide.rst
+.. _cpu-specific-build-macros.rst: ./cpu-specific-build-macros.rst
+.. _CPUBM: ./cpu-specific-build-macros.rst
+.. _ARM ARM: http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0487a.e/index.html
+.. _User Guide: ./user-guide.rst
+.. _SMC Calling Convention PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
+.. _ARM Trusted Firmware Interrupt Management Design guide: ./interrupt-framework-design.rst
+
+.. |Image 1| image:: diagrams/rt-svc-descs-layout.png?raw=true
diff --git a/docs/firmware-update.md b/docs/firmware-update.rst
similarity index 63%
rename from docs/firmware-update.md
rename to docs/firmware-update.rst
index b04586e..829341d 100644
--- a/docs/firmware-update.md
+++ b/docs/firmware-update.rst
@@ -1,18 +1,16 @@
ARM Trusted Firmware - Firmware Update Design Guide
===================================================
-Contents :
-1. [Introduction](#1--introduction)
-2. [FWU Overview](#2--fwu-overview)
-3. [Image Identification](#3--image-identification)
-4. [FWU State Machine](#4--fwu-state-machine)
-5. [BL1 SMC Interface](#5--bl1-smc-interface)
+.. section-numbering::
+ :suffix: .
-- - - - - - - - - - - - - - - - - -
+.. contents::
-1. Introduction
-----------------
+--------------
+
+Introduction
+------------
This document describes the design of the Firmware Update (FWU) feature, which
enables authenticated firmware to update firmware images from external
@@ -24,19 +22,19 @@
FWU implements a specific part of the Trusted Board Boot Requirements (TBBR)
specification, ARM DEN0006C-1. It should be used in conjunction with the
-[Trusted Board Boot] design document, which describes the image authentication
+`Trusted Board Boot`_ design document, which describes the image authentication
parts of the Trusted Firmware (TF) TBBR implementation.
-### Scope
+Scope
+~~~~~
This document describes the secure world FWU design. It is beyond its scope to
describe how normal world FWU images should operate. To implement normal world
FWU images, please refer to the "Non-Trusted Firmware Updater" requirements in
the TBBR.
-
-2. FWU Overview
-----------------
+FWU Overview
+------------
The FWU boot flow is primarily mediated by BL1. Since BL1 executes in ROM, and
it is usually desirable to minimize the amount of ROM code, the design allows
@@ -44,65 +42,65 @@
Platform code may choose which parts are implemented in which images but the
general expectation is:
-* BL1 handles:
- * Detection and initiation of the FWU boot flow.
- * Copying images from non-secure to secure memory
- * FWU image authentication
- * Context switching between the normal and secure world during the FWU
- process.
-* Other secure world FWU images handle platform initialization required by
- the FWU process.
-* Normal world FWU images handle loading of firmware images from external
- interfaces to non-secure memory.
+- BL1 handles:
+
+ - Detection and initiation of the FWU boot flow.
+ - Copying images from non-secure to secure memory
+ - FWU image authentication
+ - Context switching between the normal and secure world during the FWU
+ process.
+
+- Other secure world FWU images handle platform initialization required by
+ the FWU process.
+- Normal world FWU images handle loading of firmware images from external
+ interfaces to non-secure memory.
The primary requirements of the FWU feature are:
-1. Export a BL1 SMC interface to interoperate with other FWU images executing
- at other Exception Levels.
-2. Export a platform interface to provide FWU common code with the information
- it needs, and to enable platform specific FWU functionality. See the
- [Porting Guide] for details of this interface.
+#. Export a BL1 SMC interface to interoperate with other FWU images executing
+ at other Exception Levels.
+#. Export a platform interface to provide FWU common code with the information
+ it needs, and to enable platform specific FWU functionality. See the
+ `Porting Guide`_ for details of this interface.
TF uses abbreviated image terminology for FWU images like for other TF images.
-An overview of this terminology can be found [here][TF Image Terminology].
+An overview of this terminology can be found `here`_.
The following diagram shows the FWU boot flow for ARM development platforms.
ARM CSS platforms like Juno have a System Control Processor (SCP), and these
use all defined FWU images. Other platforms may use a subset of these.
-
+|Flow Diagram|
-
-3. Image Identification
-------------------------
+Image Identification
+--------------------
Each FWU image and certificate is identified by a unique ID, defined by the
-platform, which BL1 uses to fetch an image descriptor (`image_desc_t`) via a
-call to `bl1_plat_get_image_desc()`. The same ID is also used to prepare the
-Chain of Trust (Refer to the [Authentication Framework Design][Auth Framework]
+platform, which BL1 uses to fetch an image descriptor (``image_desc_t``) via a
+call to ``bl1_plat_get_image_desc()``. The same ID is also used to prepare the
+Chain of Trust (Refer to the `Authentication Framework Design`_
for more information).
The image descriptor includes the following information:
-* Executable or non-executable image. This indicates whether the normal world
- is permitted to request execution of a secure world FWU image (after
- authentication). Secure world certificates and non-AP images are examples
- of non-executable images.
-* Secure or non-secure image. This indicates whether the image is
- authenticated/executed in secure or non-secure memory.
-* Image base address and size.
-* Image entry point configuration (an `entry_point_info_t`).
-* FWU image state.
+- Executable or non-executable image. This indicates whether the normal world
+ is permitted to request execution of a secure world FWU image (after
+ authentication). Secure world certificates and non-AP images are examples
+ of non-executable images.
+- Secure or non-secure image. This indicates whether the image is
+ authenticated/executed in secure or non-secure memory.
+- Image base address and size.
+- Image entry point configuration (an ``entry_point_info_t``).
+- FWU image state.
BL1 uses the FWU image descriptors to:
-* Validate the arguments of FWU SMCs
-* Manage the state of the FWU process
-* Initialize the execution state of the next FWU image.
+- Validate the arguments of FWU SMCs
+- Manage the state of the FWU process
+- Initialize the execution state of the next FWU image.
-
-4. FWU State Machine
----------------------
+FWU State Machine
+-----------------
BL1 maintains state for each FWU image during FWU execution. FWU images at lower
Exception Levels raise SMCs to invoke FWU functionality in BL1, which causes
@@ -110,35 +108,37 @@
transitions are shown in the diagram below. Note that secure images have a more
complex state machine than non-secure images.
-
+|FWU state machine|
The following is a brief description of the supported states:
-* RESET: This is the initial state of every image at the start of FWU.
- Authentication failure also leads to this state. A secure
- image may yield to this state if it has completed execution.
- It can also be reached by using `FWU_SMC_IMAGE_RESET`.
+- RESET: This is the initial state of every image at the start of FWU.
+ Authentication failure also leads to this state. A secure
+ image may yield to this state if it has completed execution.
+ It can also be reached by using ``FWU_SMC_IMAGE_RESET``.
-* COPYING: This is the state of a secure image while BL1 is copying it
- in blocks from non-secure to secure memory.
+- COPYING: This is the state of a secure image while BL1 is copying it
+ in blocks from non-secure to secure memory.
-* COPIED: This is the state of a secure image when BL1 has completed
- copying it to secure memory.
+- COPIED: This is the state of a secure image when BL1 has completed
+ copying it to secure memory.
-* AUTHENTICATED: This is the state of an image when BL1 has successfully
- authenticated it.
+- AUTHENTICATED: This is the state of an image when BL1 has successfully
+ authenticated it.
-* EXECUTED: This is the state of a secure, executable image when BL1 has
- passed execution control to it.
+- EXECUTED: This is the state of a secure, executable image when BL1 has
+ passed execution control to it.
-* INTERRUPTED: This is the state of a secure, executable image after it has
- requested BL1 to resume normal world execution.
+- INTERRUPTED: This is the state of a secure, executable image after it has
+ requested BL1 to resume normal world execution.
+BL1 SMC Interface
+-----------------
-5. BL1 SMC Interface
----------------------
+BL1\_SMC\_CALL\_COUNT
+~~~~~~~~~~~~~~~~~~~~~
-### BL1_SMC_CALL_COUNT
+::
Arguments:
uint32_t function ID : 0x0
@@ -148,7 +148,10 @@
This SMC returns the number of SMCs supported by BL1.
-### BL1_SMC_UID
+BL1\_SMC\_UID
+~~~~~~~~~~~~~
+
+::
Arguments:
uint32_t function ID : 0x1
@@ -156,10 +159,13 @@
Return:
UUID : 32 bits in each of w0-w3 (or r0-r3 for AArch32 callers)
-This SMC returns the 128-bit [Universally Unique Identifier][UUID] for the
+This SMC returns the 128-bit `Universally Unique Identifier`_ for the
BL1 SMC service.
-### BL1_SMC_VERSION
+BL1\_SMC\_VERSION
+~~~~~~~~~~~~~~~~~
+
+::
Argument:
uint32_t function ID : 0x3
@@ -170,7 +176,10 @@
This SMC returns the current version of the BL1 SMC service.
-### BL1_SMC_RUN_IMAGE
+BL1\_SMC\_RUN\_IMAGE
+~~~~~~~~~~~~~~~~~~~~
+
+::
Arguments:
uint32_t function ID : 0x4
@@ -184,11 +193,13 @@
if (ep_info not EL3) synchronous exception
This SMC passes execution control to an EL3 image described by the provided
-`entry_point_info_t` structure. In the normal TF boot flow, BL2 invokes this SMC
+``entry_point_info_t`` structure. In the normal TF boot flow, BL2 invokes this SMC
for BL1 to pass execution control to BL31.
+FWU\_SMC\_IMAGE\_COPY
+~~~~~~~~~~~~~~~~~~~~~
-### FWU_SMC_IMAGE_COPY
+::
Arguments:
uint32_t function ID : 0x10
@@ -214,16 +225,16 @@
if (image_size > free secure memory) return -ENOMEM
if (image overlaps another image) return -EPERM
-This SMC copies the secure image indicated by `image_id` from non-secure memory
+This SMC copies the secure image indicated by ``image_id`` from non-secure memory
to secure memory for later authentication. The image may be copied in a single
block or multiple blocks. In either case, the total size of the image must be
-provided in `image_size` when invoking this SMC for the first time for each
+provided in ``image_size`` when invoking this SMC for the first time for each
image; it is ignored in subsequent calls (if any) for the same image.
-The `image_addr` and `block_size` specify the source memory block to copy from.
+The ``image_addr`` and ``block_size`` specify the source memory block to copy from.
The destination address is provided by the platform code.
-If `block_size` is greater than the amount of remaining bytes to copy for this
+If ``block_size`` is greater than the amount of remaining bytes to copy for this
image then the former is truncated to the latter. The copy operation is then
considered as complete and the FWU state machine transitions to the "COPIED"
state. If there is still more to copy, the FWU state machine stays in or
@@ -234,8 +245,10 @@
Once the SMC is handled, BL1 returns from exception to the normal world caller.
+FWU\_SMC\_IMAGE\_AUTH
+~~~~~~~~~~~~~~~~~~~~~
-### FWU_SMC_IMAGE_AUTH
+::
Arguments:
uint32_t function ID : 0x11
@@ -262,9 +275,9 @@
if (image_addr/image_size is in secure memory) return -ENOMEM
if (image_addr/image_size not mappped into BL1) return -ENOMEM
-This SMC authenticates the image specified by `image_id`. If the image is in the
- RESET state, BL1 authenticates the image in place using the provided
-`image_addr` and `image_size`. If the image is a secure image in the COPIED
+This SMC authenticates the image specified by ``image_id``. If the image is in the
+RESET state, BL1 authenticates the image in place using the provided
+``image_addr`` and ``image_size``. If the image is a secure image in the COPIED
state, BL1 authenticates the image from the secure memory that BL1 previously
copied the image into.
@@ -272,8 +285,10 @@
sets the image state to AUTHENTICATED. If authentication fails then BL1 returns
the -EAUTH error and sets the image state back to RESET.
+FWU\_SMC\_IMAGE\_EXECUTE
+~~~~~~~~~~~~~~~~~~~~~~~~
-### FWU_SMC_IMAGE_EXECUTE
+::
Arguments:
uint32_t function ID : 0x12
@@ -291,15 +306,17 @@
if (image_id state is not AUTHENTICATED) return -EPERM
This SMC initiates execution of a previously authenticated image specified by
-`image_id`, in the other security world to the caller. The current
+``image_id``, in the other security world to the caller. The current
implementation only supports normal world callers initiating execution of a
secure world image.
BL1 saves the normal world caller's context, sets the secure image state to
EXECUTED, and returns from exception to the secure image.
+FWU\_SMC\_IMAGE\_RESUME
+~~~~~~~~~~~~~~~~~~~~~~~
-### FWU_SMC_IMAGE_RESUME
+::
Arguments:
uint32_t function ID : 0x13
@@ -320,11 +337,13 @@
image state to INTERRUPTED. In either case, BL1 saves the calling world's
context, restores the resuming world's context and returns from exception into
the resuming world. If the call is successful then the caller provided
-`image_param` is returned to the resumed world, otherwise an error code is
+``image_param`` is returned to the resumed world, otherwise an error code is
returned to the caller.
+FWU\_SMC\_SEC\_IMAGE\_DONE
+~~~~~~~~~~~~~~~~~~~~~~~~~~
-### FWU_SMC_SEC_IMAGE_DONE
+::
Arguments:
uint32_t function ID : 0x14
@@ -342,8 +361,10 @@
restores the normal world context and returns from exception into the normal
world.
+FWU\_SMC\_UPDATE\_DONE
+~~~~~~~~~~~~~~~~~~~~~~
-### FWU_SMC_UPDATE_DONE
+::
Arguments:
uint32_t function ID : 0x15
@@ -353,11 +374,13 @@
N/A
This SMC completes the firmware update process. BL1 calls the platform specific
-function `bl1_plat_fwu_done`, passing the optional argument `client_cookie` as
-a `void *`. The SMC does not return.
+function ``bl1_plat_fwu_done``, passing the optional argument ``client_cookie`` as
+a ``void *``. The SMC does not return.
+FWU\_SMC\_IMAGE\_RESET
+~~~~~~~~~~~~~~~~~~~~~~
-### FWU_SMC_IMAGE_RESET
+::
Arguments:
uint32_t function ID : 0x16
@@ -375,14 +398,15 @@
This is only allowed if the image is not being executed.
+--------------
-- - - - - - - - - - - - - - - - - - - - - - - - - -
+*Copyright (c) 2015-2017, ARM Limited and Contributors. All rights reserved.*
-_Copyright (c) 2015-2017, ARM Limited and Contributors. All rights reserved._
+.. _Trusted Board Boot: ./trusted-board-boot.rst
+.. _Porting Guide: ./porting-guide.rst
+.. _here: https://github.com/ARM-software/arm-trusted-firmware/wiki/ARM-Trusted-Firmware-Image-Terminology
+.. _Authentication Framework Design: ./auth-framework.rst
+.. _Universally Unique Identifier: https://tools.ietf.org/rfc/rfc4122.txt
-
-[Porting Guide]: ./porting-guide.md
-[Auth Framework]: ./auth-framework.md
-[Trusted Board Boot]: ./trusted-board-boot.md
-[TF Image Terminology]: https://github.com/ARM-software/arm-trusted-firmware/wiki/ARM-Trusted-Firmware-Image-Terminology
-[UUID]: https://tools.ietf.org/rfc/rfc4122.txt "A Universally Unique IDentifier (UUID) URN Namespace"
+.. |Flow Diagram| image:: diagrams/fwu_flow.png?raw=true
+.. |FWU state machine| image:: diagrams/fwu_states.png?raw=true
diff --git a/docs/interrupt-framework-design.md b/docs/interrupt-framework-design.md
deleted file mode 100644
index 1deab02..0000000
--- a/docs/interrupt-framework-design.md
+++ /dev/null
@@ -1,997 +0,0 @@
-ARM Trusted Firmware Interrupt Management Design guide
-======================================================
-
-Contents :
-
-1. [Introduction](#1-introduction)
- * [Concepts](#11-concepts)
- - [Interrupt Types](#111-interrupt-types)
- - [Routing Model](#112-routing-model)
- - [Valid Routing Models](#113-valid-routing-models)
- + [Secure-EL1 Interrupts](#1131-secure-el1-interrupts)
- + [Non-secure Interrupts](#1132-non-secure-interrupts)
- + [EL3 interrupts](#1133-el3-interrupts)
- - [Mapping of Interrupt Type to Signal](#114-mapping-of-interrupt-type-to-signal)
- + [Effect of mapping of several interrupt types to one signal](#1141-effect-of-mapping-of-several-interrupt-types-to-one-signal)
- - [Assumptions in Interrupt Management Framework](#12-assumptions-in-interrupt-management-framework)
-
-2. [Interrupt Management](#2-interrupt-management)
- * [Software Components](#21-software-components)
- * [Interrupt Registration](#22-interrupt-registration)
- - [EL3 Runtime Firmware](#221-el3-runtime-firmware)
- - [Secure Payload Dispatcher](#222-secure-payload-dispatcher)
- + [Test Secure Payload Dispatcher behavior](#2221-test-secure-payload-dispatcher-behavior)
- - [Secure Payload](#223-secure-payload)
- + [Secure Payload IHF design w.r.t Secure-EL1 interrupts](#2231-secure-payload-ihf-design-wrt-secure-el1-interrupts)
- + [Secure Payload IHF design w.r.t Non-secure interrupts](#2232-secure-payload-ihf-design-wrt-non-secure-interrupts)
- + [Test Secure Payload behavior](#2233-test-secure-payload-behavior)
- * [Interrupt Handling](#23-interrupt-handling)
- - [EL3 Runtime Firmware](#231-el3-runtime-firmware)
- - [Secure Payload Dispatcher](#232-secure-payload-dispatcher)
- + [Interrupt Entry](#2321-interrupt-entry)
- + [Interrupt Exit](#2322-interrupt-exit)
- + [Test secure payload dispatcher Secure-EL1 interrupt handling](#2323-test-secure-payload-dispatcher-secure-el1-interrupt-handling)
- + [Test secure payload dispatcher non-secure interrupt handling](#2324-test-secure-payload-dispatcher-non-secure-interrupt-handling)
- - [Secure Payload](#233-secure-payload)
- + [Test Secure Payload behavior](#2331-test-secure-payload-behavior)
-
-3. [Other considerations](#3-other-considerations)
- * [Implication of preempted SMC on Non-Secure Software](#31-implication-of-preempted-smc-on-non-secure-software)
-
-
-1. Introduction
-----------------
-This document describes the design of the Interrupt management framework in ARM
-Trusted Firmware. This section briefly describes the requirements from this
-framework. It also briefly explains some concepts and assumptions. They will
-help in understanding the implementation of the framework explained in
-subsequent sections.
-
-This framework is responsible for managing interrupts routed to EL3. It also
-allows EL3 software to configure the interrupt routing behavior. Its main
-objective is to implement the following two requirements.
-
-1. It should be possible to route interrupts meant to be handled by secure
- software (Secure interrupts) to EL3, when execution is in non-secure state
- (normal world). The framework should then take care of handing control of
- the interrupt to either software in EL3 or Secure-EL1 depending upon the
- software configuration and the GIC implementation. This requirement ensures
- that secure interrupts are under the control of the secure software with
- respect to their delivery and handling without the possibility of
- intervention from non-secure software.
-
-2. It should be possible to route interrupts meant to be handled by
- non-secure software (Non-secure interrupts) to the last executed exception
- level in the normal world when the execution is in secure world at
- exception levels lower than EL3. This could be done with or without the
- knowledge of software executing in Secure-EL1/Secure-EL0. The choice of
- approach should be governed by the secure software. This requirement
- ensures that non-secure software is able to execute in tandem with the
- secure software without overriding it.
-
-### 1.1 Concepts
-
-#### 1.1.1 Interrupt types
-The framework categorises an interrupt to be one of the following depending upon
-the exception level(s) it is handled in.
-
-1. Secure EL1 interrupt. This type of interrupt can be routed to EL3 or
- Secure-EL1 depending upon the security state of the current execution
- context. It is always handled in Secure-EL1.
-
-2. Non-secure interrupt. This type of interrupt can be routed to EL3,
- Secure-EL1, Non-secure EL1 or EL2 depending upon the security state of the
- current execution context. It is always handled in either Non-secure EL1
- or EL2.
-
-3. EL3 interrupt. This type of interrupt can be routed to EL3 or Secure-EL1
- depending upon the security state of the current execution context. It is
- always handled in EL3.
-
-The following constants define the various interrupt types in the framework
-implementation.
-
- #define INTR_TYPE_S_EL1 0
- #define INTR_TYPE_EL3 1
- #define INTR_TYPE_NS 2
-
-
-#### 1.1.2 Routing model
-A type of interrupt can be either generated as an FIQ or an IRQ. The target
-exception level of an interrupt type is configured through the FIQ and IRQ bits
-in the Secure Configuration Register at EL3 (`SCR_EL3.FIQ` and `SCR_EL3.IRQ`
-bits). When `SCR_EL3.FIQ`=1, FIQs are routed to EL3. Otherwise they are routed
-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
-FEL. This register is configured independently by EL3 software for each security
-state prior to entry into a lower exception level in that security state.
-
-A routing model for a type of interrupt (generated as FIQ or IRQ) is defined as
-its target exception level for each security state. It is represented by a
-single bit for each security state. A value of `0` means that the interrupt
-should be routed to the FEL. A value of `1` means that the interrupt should be
-routed to EL3. A routing model is applicable only when execution is not in EL3.
-
-The default routing model for an interrupt type is to route it to the FEL in
-either security state.
-
-
-#### 1.1.3 Valid routing models
-The framework considers certain routing models for each type of interrupt to be
-incorrect as they conflict with the requirements mentioned in Section 1. The
-following sub-sections describe all the possible routing models and specify
-which ones are valid or invalid. EL3 interrupts are currently supported only
-for GIC version 3.0 (ARM GICv3) and only the Secure-EL1 and Non-secure interrupt
-types are supported for GIC version 2.0 (ARM GICv2) (See 1.2). The terminology
-used in the following sub-sections is explained below.
-
-1. __CSS__. Current Security State. `0` when secure and `1` when non-secure
-
-2. __TEL3__. Target Exception Level 3. `0` when targeted to the FEL. `1` when
- targeted to EL3.
-
-
-##### 1.1.3.1 Secure-EL1 interrupts
-
-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
- control of handling secure interrupts.
-
-2. __CSS=0, TEL3=1__. Interrupt is routed to EL3 when execution is in secure
- state. This is a valid routing model as secure software in EL3 can
- handover the interrupt to Secure-EL1 for handling.
-
-3. __CSS=1, TEL3=0__. Interrupt is routed to the FEL when execution is in
- non-secure state. This is an invalid routing model as a secure interrupt
- is not visible to the secure software which violates the motivation behind
- the ARM Security Extensions.
-
-4. __CSS=1, TEL3=1__. Interrupt is routed to EL3 when execution is in
- non-secure state. This is a valid routing model as secure software in EL3
- can handover the interrupt to Secure-EL1 for handling.
-
-
-##### 1.1.3.2 Non-secure interrupts
-
-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
- interrupts, perform its book-keeping and hand the interrupt to the
- non-secure software through EL3. This is a valid routing model as secure
- software is in control of how its execution is preempted by non-secure
- interrupts.
-
-2. __CSS=0, TEL3=1__. Interrupt is routed to EL3 when execution is in secure
- state. This is a valid routing model as secure software in EL3 can save
- the state of software in Secure-EL1/Secure-EL0 before handing the
- interrupt to non-secure software. This model requires additional
- coordination between Secure-EL1 and EL3 software to ensure that the
- former's state is correctly saved by the latter.
-
-3. __CSS=1, TEL3=0__. Interrupt is routed to FEL when execution is in
- non-secure state. This is an valid routing model as a non-secure interrupt
- is handled by non-secure software.
-
-4. __CSS=1, TEL3=1__. Interrupt is routed to EL3 when execution is in
- non-secure state. This is an invalid routing model as there is no valid
- reason to route the interrupt to EL3 software and then hand it back to
- non-secure software for handling.
-
-
-##### 1.1.3.3 EL3 interrupts
-
-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
- in Secure-EL1/Secure-EL0 is in control of how its execution is preempted
- by EL3 interrupt and can handover the interrupt to EL3 for handling.
-
-2. __CSS=0, TEL3=1__. Interrupt is routed to EL3 when execution is in
- Secure-EL1/Secure-EL0. This is a valid routing model as secure software
- in EL3 can handle the interrupt.
-
-3. __CSS=1, TEL3=0__. Interrupt is routed to the FEL when execution is in
- non-secure state. This is an invalid routing model as a secure interrupt
- is not visible to the secure software which violates the motivation behind
- the ARM Security Extensions.
-
-4. __CSS=1, TEL3=1__. Interrupt is routed to EL3 when execution is in
- non-secure state. This is a valid routing model as secure software in EL3
- can handle the interrupt.
-
-
-#### 1.1.4 Mapping of interrupt type to signal
-The framework is meant to work with any interrupt controller implemented by a
-platform. A interrupt controller could generate a type of interrupt as either an
-FIQ or IRQ signal to the CPU depending upon the current security state. The
-mapping between the type and signal is known only to the platform. The framework
-uses this information to determine whether the IRQ or the FIQ bit should be
-programmed in `SCR_EL3` while applying the routing model for a type of
-interrupt. The platform provides this information through the
-`plat_interrupt_type_to_line()` API (described in the [Porting
-Guide]). For example, on the FVP port when the platform uses an ARM GICv2
-interrupt controller, Secure-EL1 interrupts are signaled through the FIQ signal
-while Non-secure interrupts are signaled through the IRQ signal. This applies
-when execution is in either security state.
-
-
-##### 1.1.4.1 Effect of mapping of several interrupt types to one signal
-It should be noted that if more than one interrupt type maps to a single
-interrupt signal, and if any one of the interrupt type sets __TEL3=1__ for a
-particular security state, then interrupt signal will be routed to EL3 when in
-that security state. This means that all the other interrupt types using the
-same interrupt signal will be forced to the same routing model. This should be
-borne in mind when choosing the routing model for an interrupt type.
-
-For example, in ARM GICv3, when the execution context is Secure-EL1/
-Secure-EL0, both the EL3 and the non secure interrupt types map to the FIQ
-signal. So if either one of the interrupt type sets the routing model so
-that __TEL3=1__ when __CSS=0__, the FIQ bit in `SCR_EL3` will be programmed to
-route the FIQ signal to EL3 when executing in Secure-EL1/Secure-EL0, thereby
-effectively routing the other interrupt type also to EL3.
-
-
-### 1.2 Assumptions in Interrupt Management Framework
-The framework makes the following assumptions to simplify its implementation.
-
-1. Although the framework has support for 2 types of secure interrupts (EL3
- and Secure-EL1 interrupt), only interrupt controller architectures
- like ARM GICv3 has architectural support for EL3 interrupts in the form of
- Group 0 interrupts. In ARM GICv2, all secure interrupts are assumed to be
- handled in Secure-EL1. They can be delivered to Secure-EL1 via EL3 but they
- cannot be handled in EL3.
-
-2. Interrupt exceptions (`PSTATE.I` and `F` bits) are masked during execution
- in EL3.
-
-
-2. Interrupt management
------------------------
-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
- of the routing model for a type of interrupt.
-
-2. Implementing support to hand control of an interrupt type to its registered
- handler when the interrupt is generated.
-
-Both aspects of interrupt management involve various components in the secure
-software stack spanning from EL3 to Secure-EL1. These components are described
-in the section 2.1. The framework stores information associated with each type
-of interrupt in the following data structure.
-
-```
-typedef struct intr_type_desc {
- interrupt_type_handler_t handler;
- uint32_t flags;
- uint32_t scr_el3[2];
-} intr_type_desc_t;
-```
-
-The `flags` field stores the routing model for the interrupt type in
-bits[1:0]. Bit[0] stores the routing model when execution is in the secure
-state. Bit[1] stores the routing model when execution is in the non-secure
-state. As mentioned in Section 1.2.2, a value of `0` implies that the interrupt
-should be targeted to the FEL. A value of `1` implies that it should be targeted
-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`
-parameter.
-
-The `scr_el3[2]` field also stores the routing model but as a mapping of the
-model in the `flags` field to the corresponding bit in the `SCR_EL3` for each
-security state.
-
-The framework also depends upon the platform port to configure the interrupt
-controller to distinguish between secure and non-secure interrupts. The platform
-is expected to be aware of the secure devices present in the system and their
-associated interrupt numbers. It should configure the interrupt controller to
-enable the secure interrupts, ensure that their priority is always higher than
-the non-secure interrupts and target them to the primary CPU. It should also
-export the interface described in the [Porting Guide] to enable
-handling of interrupts.
-
-In the remainder of this document, for the sake of simplicity a ARM GICv2 system
-is considered and it is assumed that the FIQ signal is used to generate Secure-EL1
-interrupts and the IRQ signal is used to generate non-secure interrupts in either
-security state. EL3 interrupts are not considered.
-
-
-### 2.1 Software components
-Roles and responsibilities for interrupt management are sub-divided between the
-following components of software running in EL3 and Secure-EL1. Each component is
-briefly described below.
-
-1. EL3 Runtime Firmware. This component is common to all ports of the ARM
- Trusted Firmware.
-
-2. Secure Payload Dispatcher (SPD) service. This service interfaces with the
- Secure Payload (SP) software which runs in Secure-EL1/Secure-EL0 and is
- responsible for switching execution between secure and non-secure states.
- A switch is triggered by a Secure Monitor Call and it uses the APIs
- exported by the Context management library to implement this functionality.
- Switching execution between the two security states is a requirement for
- interrupt management as well. This results in a significant dependency on
- the SPD service. ARM Trusted firmware implements an example Test Secure
- Payload Dispatcher (TSPD) service.
-
- An SPD service plugs into the EL3 runtime firmware and could be common to
- some ports of the ARM Trusted Firmware.
-
-3. Secure Payload (SP). On a production system, the Secure Payload corresponds
- to a Secure OS which runs in Secure-EL1/Secure-EL0. It interfaces with the
- SPD service to manage communication with non-secure software. ARM Trusted
- Firmware implements an example secure payload called Test Secure Payload
- (TSP) which runs only in Secure-EL1.
-
- A Secure payload implementation could be common to some ports of the ARM
- Trusted Firmware just like the SPD service.
-
-
-### 2.2 Interrupt registration
-This section describes in detail the role of each software component (see 2.1)
-during the registration of a handler for an interrupt type.
-
-
-#### 2.2.1 EL3 runtime firmware
-This component declares the following prototype for a handler of an interrupt type.
-
- typedef uint64_t (*interrupt_type_handler_t)(uint32_t id,
- uint32_t flags,
- void *handle,
- void *cookie);
-
-The `id` is parameter is reserved and could be used in the future for passing
-the interrupt id of the highest pending interrupt only if there is a foolproof
-way of determining the id. Currently it contains `INTR_ID_UNAVAILABLE`.
-
-The `flags` parameter contains miscellaneous information as follows.
-
-1. Security state, bit[0]. This bit indicates the security state of the lower
- exception level when the interrupt was generated. A value of `1` means
- that it was in the non-secure state. A value of `0` indicates that it was
- in the secure state. This bit can be used by the handler to ensure that
- interrupt was generated and routed as per the routing model specified
- during registration.
-
-2. Reserved, bits[31:1]. The remaining bits are reserved for future use.
-
-The `handle` parameter points to the `cpu_context` structure of the current CPU
-for the security state specified in the `flags` parameter.
-
-Once the handler routine completes, execution will return to either the secure
-or non-secure state. The handler routine must return a pointer to
-`cpu_context` structure of the current CPU for the target security state. On
-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
-via the context management library APIs.
-A portable interrupt handler implementation must set the target context both in
-the structure pointed to by the returned pointer and via the context management
-library APIs. The handler should treat all error conditions as critical errors
-and take appropriate action within its implementation e.g. use assertion
-failures.
-
-The runtime firmware provides the following API for registering a handler for a
-particular type of interrupt. A Secure Payload Dispatcher service should use
-this API to register a handler for Secure-EL1 and optionally for non-secure
-interrupts. This API also requires the caller to specify the routing model for
-the type of interrupt.
-
- int32_t register_interrupt_type_handler(uint32_t type,
- interrupt_type_handler handler,
- uint64_t flags);
-
-
-The `type` parameter can be one of the three interrupt types listed above i.e.
-`INTR_TYPE_S_EL1`, `INTR_TYPE_NS` & `INTR_TYPE_EL3`. The `flags` parameter
-is as described in Section 2.
-
-The function will return `0` upon a successful registration. It will return
-`-EALREADY` in case a handler for the interrupt type has already been
-registered. If the `type` is unrecognised or the `flags` or the `handler` are
-invalid it will return `-EINVAL`.
-
-Interrupt routing is governed by the configuration of the `SCR_EL3.FIQ/IRQ` bits
-prior to entry into a lower exception level in either security state. The
-context management library maintains a copy of the `SCR_EL3` system register for
-each security state in the `cpu_context` structure of each CPU. It exports the
-following APIs to let EL3 Runtime Firmware program and retrieve the routing
-model for each security state for the current CPU. The value of `SCR_EL3` stored
-in the `cpu_context` is used by the `el3_exit()` function to program the
-`SCR_EL3` register prior to returning from the EL3 exception level.
-
- uint32_t cm_get_scr_el3(uint32_t security_state);
- void cm_write_scr_el3_bit(uint32_t security_state,
- uint32_t bit_pos,
- uint32_t value);
-
-`cm_get_scr_el3()` returns the value of the `SCR_EL3` register for the specified
-security state of the current CPU. `cm_write_scr_el3()` writes a `0` or `1` to
-the bit specified by `bit_pos`. `register_interrupt_type_handler()` invokes
-`set_routing_model()` API which programs the `SCR_EL3` according to the routing
-model using the `cm_get_scr_el3()` and `cm_write_scr_el3_bit()` APIs.
-
-It is worth noting that in the current implementation of the framework, the EL3
-runtime firmware is responsible for programming the routing model. The SPD is
-responsible for ensuring that the routing model has been adhered to upon
-receiving an interrupt.
-
-
-#### 2.2.2 Secure payload dispatcher
-A SPD service is responsible for determining and maintaining the interrupt
-routing model supported by itself and the Secure Payload. It is also responsible
-for ferrying interrupts between secure and non-secure software depending upon
-the routing model. It could determine the routing model at build time or at
-runtime. It must use this information to register a handler for each interrupt
-type using the `register_interrupt_type_handler()` API in EL3 runtime firmware.
-
-If the routing model is not known to the SPD service at build time, then it must
-be provided by the SP as the result of its initialisation. The SPD should
-program the routing model only after SP initialisation has completed e.g. in the
-SPD initialisation function pointed to by the `bl32_init` variable.
-
-The SPD should determine the mechanism to pass control to the Secure Payload
-after receiving an interrupt from the EL3 runtime firmware. This information
-could either be provided to the SPD service at build time or by the SP at
-runtime.
-
-
-#### 2.2.2.1 Test secure payload dispatcher behavior
-The TSPD only handles Secure-EL1 interrupts and is provided with the following
-routing model at build time.
-
-* Secure-EL1 interrupts are routed to EL3 when execution is in non-secure
- 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
-
-* When the build flag `TSP_NS_INTR_ASYNC_PREEMPT` is zero, the default routing
- model is used for non-secure interrupts. They are routed to the FEL in
- either security state i.e __CSS=0, TEL3=0__ & __CSS=1, TEL3=0__ for
- Non-secure interrupts.
-
-* When the build flag `TSP_NS_INTR_ASYNC_PREEMPT` is defined to 1, then the
- non secure interrupts are routed to EL3 when execution is in secure state
- i.e __CSS=0, TEL3=1__ for non-secure interrupts. This effectively preempts
- Secure-EL1. The default routing model is used for non secure interrupts in
- non-secure state. i.e __CSS=1, TEL3=0__.
-
-It performs the following actions in the `tspd_init()` function to fulfill the
-requirements mentioned earlier.
-
-1. It passes control to the Test Secure Payload to perform its
- initialisation. The TSP provides the address of the vector table
- `tsp_vectors` in the SP which also includes the handler for Secure-EL1
- interrupts in the `sel1_intr_entry` field. The TSPD passes control to the TSP at
- this address when it receives a Secure-EL1 interrupt.
-
- The handover agreement between the TSP and the TSPD requires that the TSPD
- masks all interrupts (`PSTATE.DAIF` bits) when it calls
- `tsp_sel1_intr_entry()`. The TSP has to preserve the callee saved general
- purpose, SP_EL1/Secure-EL0, LR, VFP and system registers. It can use
- `x0-x18` to enable its C runtime.
-
-2. The TSPD implements a handler function for Secure-EL1 interrupts. This
- function is registered with the EL3 runtime firmware using the
- `register_interrupt_type_handler()` API as follows
-
- /* Forward declaration */
- interrupt_type_handler tspd_secure_el1_interrupt_handler;
- int32_t rc, flags = 0;
- set_interrupt_rm_flag(flags, NON_SECURE);
- rc = register_interrupt_type_handler(INTR_TYPE_S_EL1,
- tspd_secure_el1_interrupt_handler,
- flags);
- if (rc)
- panic();
-
-3. When the build flag `TSP_NS_INTR_ASYNC_PREEMPT` is defined to 1, the TSPD
- implements a handler function for non-secure interrupts. This function is
- registered with the EL3 runtime firmware using the
- `register_interrupt_type_handler()` API as follows
-
- /* Forward declaration */
- interrupt_type_handler tspd_ns_interrupt_handler;
- int32_t rc, flags = 0;
- set_interrupt_rm_flag(flags, SECURE);
- rc = register_interrupt_type_handler(INTR_TYPE_NS,
- tspd_ns_interrupt_handler,
- flags);
- if (rc)
- panic();
-
-
-#### 2.2.3 Secure payload
-A Secure Payload must implement an interrupt handling framework at Secure-EL1
-(Secure-EL1 IHF) to support its chosen interrupt routing model. Secure payload
-execution will alternate between the below cases.
-
-1. In the code where IRQ, FIQ or both interrupts are enabled, if an interrupt
- 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
- handling interrupts. This mode applies to both Secure-EL1 and non-secure
- interrupts.
-
-2. In the code where both interrupts are disabled, if an interrupt type is
- targeted to the FEL, then execution will eventually migrate to the
- non-secure state. Any non-secure interrupts will be handled as described
- in the routing model where __CSS=1 and TEL3=0__. Secure-EL1 interrupts
- will be routed to EL3 (as per the routing model where __CSS=1 and
- TEL3=1__) where the SPD service will hand them to the SP. This is defined
- as the __synchronous mode__ of handling interrupts.
-
-The interrupt handling framework implemented by the SP should support one or
-both these interrupt handling models depending upon the chosen routing model.
-
-The following list briefly describes how the choice of a valid routing model
-(See 1.2.3) effects the implementation of the Secure-EL1 IHF. If the choice of
-the interrupt routing model is not known to the SPD service at compile time,
-then the SP should pass this information to the SPD service at runtime during
-its initialisation phase.
-
-As mentioned earlier, a ARM GICv2 system is considered and it is assumed that
-the FIQ signal is used to generate Secure-EL1 interrupts and the IRQ signal
-is used to generate non-secure interrupts in either security state.
-
-
-##### 2.2.3.1 Secure payload IHF design w.r.t secure-EL1 interrupts
-1. __CSS=0, TEL3=0__. If `PSTATE.F=0`, Secure-EL1 interrupts will be
- triggered at one of the Secure-EL1 FIQ exception vectors. The Secure-EL1
- IHF should implement support for handling FIQ interrupts asynchronously.
-
- If `PSTATE.F=1` then Secure-EL1 interrupts will be handled as per the
- synchronous interrupt handling model. The SP could implement this scenario
- by exporting a separate entrypoint for Secure-EL1 interrupts to the SPD
- service during the registration phase. The SPD service would also need to
- know the state of the system, general purpose and the `PSTATE` registers
- in which it should arrange to return execution to the SP. The SP should
- provide this information in an implementation defined way during the
- registration phase if it is not known to the SPD service at build time.
-
-2. __CSS=1, TEL3=1__. Interrupts are routed to EL3 when execution is in
- non-secure state. They should be handled through the synchronous interrupt
- handling model as described in 1. above.
-
-3. __CSS=0, TEL3=1__. Secure-EL1 interrupts are routed to EL3 when execution
- is in secure state. They will not be visible to the SP. The `PSTATE.F` bit
- in Secure-EL1/Secure-EL0 will not mask FIQs. The EL3 runtime firmware will
- call the handler registered by the SPD service for Secure-EL1 interrupts.
- Secure-EL1 IHF should then handle all Secure-EL1 interrupt through the
- synchronous interrupt handling model described in 1. above.
-
-
-##### 2.2.3.2 Secure payload IHF design w.r.t non-secure interrupts
-1. __CSS=0, TEL3=0__. If `PSTATE.I=0`, non-secure interrupts will be
- triggered at one of the Secure-EL1 IRQ exception vectors . The Secure-EL1
- IHF should co-ordinate with the SPD service to transfer execution to the
- non-secure state where the interrupt should be handled e.g the SP could
- allocate a function identifier to issue a SMC64 or SMC32 to the SPD
- service which indicates that the SP execution has been preempted by a
- non-secure interrupt. If this function identifier is not known to the SPD
- service at compile time then the SP could provide it during the
- registration phase.
-
- If `PSTATE.I=1` then the non-secure interrupt will pend until execution
- resumes in the non-secure state.
-
-2. __CSS=0, TEL3=1__. Non-secure interrupts are routed to EL3. They will not
- be visible to the SP. The `PSTATE.I` bit in Secure-EL1/Secure-EL0 will
- have not effect. The SPD service should register a non-secure interrupt
- handler which should save the SP state correctly and resume execution in
- the non-secure state where the interrupt will be handled. The Secure-EL1
- IHF does not need to take any action.
-
-3. __CSS=1, TEL3=0__. Non-secure interrupts are handled in the FEL in
- non-secure state (EL1/EL2) and are not visible to the SP. This routing
- model does not affect the SP behavior.
-
-A Secure Payload must also ensure that all Secure-EL1 interrupts are correctly
-configured at the interrupt controller by the platform port of the EL3 runtime
-firmware. It should configure any additional Secure-EL1 interrupts which the EL3
-runtime firmware is not aware of through its platform port.
-
-
-#### 2.2.3.3 Test secure payload behavior
-The routing model for Secure-EL1 and non-secure interrupts chosen by the TSP is
-described in Section 2.2.2. It is known to the TSPD service at build time.
-
-The TSP implements an entrypoint (`tsp_sel1_intr_entry()`) for handling Secure-EL1
-interrupts taken in non-secure state and routed through the TSPD service
-(synchronous handling model). It passes the reference to this entrypoint via
-`tsp_vectors` to the TSPD service.
-
-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
-exceptions taken at the same (Secure-EL1) exception level. This table is
-referenced through the `tsp_exceptions` variable and programmed into the
-VBAR_EL1. It caters for the asynchronous handling model.
-
-The TSP also programs the Secure Physical Timer in the ARM Generic Timer block
-to raise a periodic interrupt (every half a second) for the purpose of testing
-interrupt management across all the software components listed in 2.1
-
-
-### 2.3 Interrupt handling
-This section describes in detail the role of each software component (see
-Section 2.1) in handling an interrupt of a particular type.
-
-
-#### 2.3.1 EL3 runtime firmware
-The EL3 runtime firmware populates the IRQ and FIQ exception vectors referenced
-by the `runtime_exceptions` variable as follows.
-
-1. IRQ and FIQ exceptions taken from the current exception level with
- `SP_EL0` or `SP_EL3` are reported as irrecoverable error conditions. As
- mentioned earlier, EL3 runtime firmware always executes with the
- `PSTATE.I` and `PSTATE.F` bits set.
-
-2. The following text describes how the IRQ and FIQ exceptions taken from a
- lower exception level using AArch64 or AArch32 are handled.
-
-When an interrupt is generated, the vector for each interrupt type is
-responsible for:
-
-1. Saving the entire general purpose register context (x0-x30) immediately
- upon exception entry. The registers are saved in the per-cpu `cpu_context`
- data structure referenced by the `SP_EL3`register.
-
-2. Saving the `ELR_EL3`, `SP_EL0` and `SPSR_EL3` system registers in the
- per-cpu `cpu_context` data structure referenced by the `SP_EL3` register.
-
-3. Switching to the C runtime stack by restoring the `CTX_RUNTIME_SP` value
- from the per-cpu `cpu_context` data structure in `SP_EL0` and
- executing the `msr spsel, #0` instruction.
-
-4. Determining the type of interrupt. Secure-EL1 interrupts will be signaled
- at the FIQ vector. Non-secure interrupts will be signaled at the IRQ
- vector. The platform should implement the following API to determine the
- type of the pending interrupt.
-
- uint32_t plat_ic_get_interrupt_type(void);
-
- 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.
- The following API has been added for this purpose.
-
- interrupt_type_handler get_interrupt_type_handler(uint32_t interrupt_type);
-
- It returns the reference to the registered handler for this interrupt
- type. The `handler` is retrieved from the `intr_type_desc_t` structure as
- described in Section 2. `NULL` is returned if no handler has been
- registered for this type of interrupt. This scenario is reported as an
- irrecoverable error condition.
-
-6. Calling the registered handler function for the interrupt type generated.
- The `id` parameter is set to `INTR_ID_UNAVAILABLE` currently. The id along
- with the current security state and a reference to the `cpu_context_t`
- structure for the current security state are passed to the handler function
- as its arguments.
-
- The handler function returns a reference to the per-cpu `cpu_context_t`
- structure for the target security state.
-
-7. Calling `el3_exit()` to return from EL3 into a lower exception level in
- the security state determined by the handler routine. The `el3_exit()`
- function is responsible for restoring the register context from the
- `cpu_context_t` data structure for the target security state.
-
-
-#### 2.3.2 Secure payload dispatcher
-
-##### 2.3.2.1 Interrupt entry
-The SPD service begins handling an interrupt when the EL3 runtime firmware calls
-the handler function for that type of interrupt. The SPD service is responsible
-for the following:
-
-1. Validating the interrupt. This involves ensuring that the interrupt was
- generating according to the interrupt routing model specified by the SPD
- service during registration. It should use the security state of the
- exception level (passed in the `flags` parameter of the handler) where
- the interrupt was taken from to determine this. If the interrupt is not
- recognised then the handler should treat it as an irrecoverable error
- condition.
-
- A SPD service can register a handler for Secure-EL1 and/or Non-secure
- interrupts. A non-secure interrupt should never be routed to EL3 from
- from non-secure state. Also if a routing model is chosen where Secure-EL1
- interrupts are routed to S-EL1 when execution is in Secure state, then a
- S-EL1 interrupt should never be routed to EL3 from secure state. The handler
- could use the security state flag to check this.
-
-2. Determining whether a context switch is required. This depends upon the
- routing model and interrupt type. For non secure and S-EL1 interrupt,
- if the security state of the execution context where the interrupt was
- generated is not the same as the security state required for handling
- the interrupt, a context switch is required. The following 2 cases
- require a context switch from secure to non-secure or vice-versa:
-
- 1. A Secure-EL1 interrupt taken from the non-secure state should be
- routed to the Secure Payload.
-
- 2. A non-secure interrupt taken from the secure state should be routed
- to the last known non-secure exception level.
-
- The SPD service must save the system register context of the current
- security state. It must then restore the system register context of the
- target security state. It should use the `cm_set_next_eret_context()` API
- to ensure that the next `cpu_context` to be restored is of the target
- security state.
-
- If the target state is secure then execution should be handed to the SP as
- per the synchronous interrupt handling model it implements. A Secure-EL1
- interrupt can be routed to EL3 while execution is in the SP. This implies
- that SP execution can be preempted while handling an interrupt by a
- another higher priority Secure-EL1 interrupt or a EL3 interrupt. The SPD
- service should be able to handle this preemption or manage secure interrupt
- priorities before handing control to the SP.
-
-3. Setting the return value of the handler to the per-cpu `cpu_context` if
- the interrupt has been successfully validated and ready to be handled at a
- lower exception level.
-
-The routing model allows non-secure interrupts to interrupt Secure-EL1 when in
-secure state if it has been configured to do so. The SPD service and the SP
-should implement a mechanism for routing these interrupts to the last known
-exception level in the non-secure state. The former should save the SP context,
-restore the non-secure context and arrange for entry into the non-secure state
-so that the interrupt can be handled.
-
-
-##### 2.3.2.2 Interrupt exit
-When the Secure Payload has finished handling a Secure-EL1 interrupt, it could
-return control back to the SPD service through a SMC32 or SMC64. The SPD service
-should handle this secure monitor call so that execution resumes in the
-exception level and the security state from where the Secure-EL1 interrupt was
-originally taken.
-
-
-##### 2.3.2.3 Test secure payload dispatcher Secure-EL1 interrupt handling
-The example TSPD service registers a handler for Secure-EL1 interrupts taken
-from the non-secure state. During execution in S-EL1, the TSPD expects that the
-Secure-EL1 interrupts are handled in S-EL1 by TSP. Its handler
-`tspd_secure_el1_interrupt_handler()` expects only to be invoked for Secure-EL1
-originating from the non-secure state. It takes the following actions upon being
-invoked.
-
-1. It uses the security state provided in the `flags` parameter to ensure
- that the secure interrupt originated from the non-secure state. It asserts
- if this is not the case.
-
-2. It saves the system register context for the non-secure state by calling
- `cm_el1_sysregs_context_save(NON_SECURE);`.
-
-3. It sets the `ELR_EL3` system register to `tsp_sel1_intr_entry` and sets the
- `SPSR_EL3.DAIF` bits in the secure CPU context. It sets `x0` to
- `TSP_HANDLE_SEL1_INTR_AND_RETURN`. If the TSP was preempted earlier by a non
- secure interrupt during `yielding` SMC processing, save the registers that
- will be trashed, which is the `ELR_EL3` and `SPSR_EL3`, in order to be able
- to re-enter TSP for Secure-EL1 interrupt processing. It does not need to
- save any other secure context since the TSP is expected to preserve it
- (see Section 2.2.2.1).
-
-4. It restores the system register context for the secure state by calling
- `cm_el1_sysregs_context_restore(SECURE);`.
-
-5. It ensures that the secure CPU context is used to program the next
- exception return from EL3 by calling `cm_set_next_eret_context(SECURE);`.
-
-6. It returns the per-cpu `cpu_context` to indicate that the interrupt can
- now be handled by the SP. `x1` is written with the value of `elr_el3`
- register for the non-secure state. This information is used by the SP for
- debugging purposes.
-
-The figure below describes how the interrupt handling is implemented by the TSPD
-when a Secure-EL1 interrupt is generated when execution is in the non-secure
-state.
-
-
-
-The TSP issues an SMC with `TSP_HANDLED_S_EL1_INTR` as the function identifier to
-signal completion of interrupt handling.
-
-The TSPD service takes the following actions in `tspd_smc_handler()` function
-upon receiving an SMC with `TSP_HANDLED_S_EL1_INTR` as the function identifier:
-
-1. It ensures that the call originated from the secure state otherwise
- execution returns to the non-secure state with `SMC_UNK` in `x0`.
-
-2. It restores the saved `ELR_EL3` and `SPSR_EL3` system registers back to
- the secure CPU context (see step 3 above) in case the TSP had been preempted
- by a non secure interrupt earlier.
-
-3. It restores the system register context for the non-secure state by
- calling `cm_el1_sysregs_context_restore(NON_SECURE)`.
-
-4. It ensures that the non-secure CPU context is used to program the next
- exception return from EL3 by calling `cm_set_next_eret_context(NON_SECURE)`.
-
-5. `tspd_smc_handler()` returns a reference to the non-secure `cpu_context`
- as the return value.
-
-
-##### 2.3.2.4 Test secure payload dispatcher non-secure interrupt handling
-The TSP in Secure-EL1 can be preempted by a non-secure interrupt during
-`yielding` SMC processing or by a higher priority EL3 interrupt during
-Secure-EL1 interrupt processing. Currently only non-secure interrupts can
-cause preemption of TSP since there are no EL3 interrupts in the
-system.
-
-It should be noted that while TSP is preempted, the TSPD only allows entry into
-the TSP either for Secure-EL1 interrupt handling or for resuming the preempted
-`yielding` SMC in response to the `TSP_FID_RESUME` SMC from the normal world.
-(See Section 3).
-
-The non-secure interrupt triggered in Secure-EL1 during `yielding` SMC processing
-can be routed to either EL3 or Secure-EL1 and is controlled by build option
-`TSP_NS_INTR_ASYNC_PREEMPT` (see Section 2.2.2.1). If the build option is set,
-the TSPD will set the routing model for the non-secure interrupt to be routed to
-EL3 from secure state i.e. __TEL3=1, CSS=0__ and registers
-`tspd_ns_interrupt_handler()` as the non-secure interrupt handler. The
-`tspd_ns_interrupt_handler()` on being invoked ensures that the interrupt
-originated from the secure state and disables routing of non-secure interrupts
-from secure state to EL3. This is to prevent further preemption (by a non-secure
-interrupt) when TSP is reentered for handling Secure-EL1 interrupts that
-triggered while execution was in the normal world. The
-`tspd_ns_interrupt_handler()` then invokes `tspd_handle_sp_preemption()` for
-further handling.
-
-If the `TSP_NS_INTR_ASYNC_PREEMPT` build option is zero (default), the default
-routing model for non-secure interrupt in secure state is in effect
-i.e. __TEL3=0, CSS=0__. During `yielding` SMC processing, the IRQ
-exceptions are unmasked i.e. `PSTATE.I=0`, and a non-secure interrupt will
-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
-identifier to signal preemption of TSP. The TSPD SMC handler,
-`tspd_smc_handler()`, ensures that the SMC call originated from the
-secure state otherwise execution returns to the non-secure state with
-`SMC_UNK` in `x0`. It then invokes `tspd_handle_sp_preemption()` for
-further handling.
-
-The `tspd_handle_sp_preemption()` takes the following actions upon being
-invoked:
-
-1. It saves the system register context for the secure state by calling
- `cm_el1_sysregs_context_save(SECURE)`.
-
-2. It restores the system register context for the non-secure state by
- calling `cm_el1_sysregs_context_restore(NON_SECURE)`.
-
-3. It ensures that the non-secure CPU context is used to program the next
- exception return from EL3 by calling `cm_set_next_eret_context(NON_SECURE)`.
-
-4. `SMC_PREEMPTED` is set in x0 and return to non secure state after
- restoring non secure context.
-
-The Normal World is expected to resume the TSP after the `yielding` SMC preemption
-by issuing an SMC with `TSP_FID_RESUME` as the function identifier (see section 3).
-The TSPD service takes the following actions in `tspd_smc_handler()` function
-upon receiving this SMC:
-
-1. It ensures that the call originated from the non secure state. An
- assertion is raised otherwise.
-
-2. Checks whether the TSP needs a resume i.e check if it was preempted. It
- then saves the system register context for the non-secure state by calling
- `cm_el1_sysregs_context_save(NON_SECURE)`.
-
-3. Restores the secure context by calling
- `cm_el1_sysregs_context_restore(SECURE)`
-
-4. It ensures that the secure CPU context is used to program the next
- exception return from EL3 by calling `cm_set_next_eret_context(SECURE)`.
-
-5. `tspd_smc_handler()` returns a reference to the secure `cpu_context` as the
- return value.
-
-The figure below describes how the TSP/TSPD handle a non-secure interrupt when
-it is generated during execution in the TSP with `PSTATE.I` = 0 when the
-`TSP_NS_INTR_ASYNC_PREEMPT` build flag is 0.
-
-
-
-
-#### 2.3.3 Secure payload
-The SP should implement one or both of the synchronous and asynchronous
-interrupt handling models depending upon the interrupt routing model it has
-chosen (as described in 2.2.3).
-
-In the synchronous model, it should begin handling a Secure-EL1 interrupt after
-receiving control from the SPD service at an entrypoint agreed upon during build
-time or during the registration phase. Before handling the interrupt, the SP
-should save any Secure-EL1 system register context which is needed for resuming
-normal execution in the SP later e.g. `SPSR_EL1, `ELR_EL1`. After handling the
-interrupt, the SP could return control back to the exception level and security
-state where the interrupt was originally taken from. The SP should use an SMC32
-or SMC64 to ask the SPD service to do this.
-
-In the asynchronous model, the Secure Payload is responsible for handling
-non-secure and Secure-EL1 interrupts at the IRQ and FIQ vectors in its exception
-vector table when `PSTATE.I` and `PSTATE.F` bits are 0. As described earlier,
-when a non-secure interrupt is generated, the SP should coordinate with the SPD
-service to pass control back to the non-secure state in the last known exception
-level. This will allow the non-secure interrupt to be handled in the non-secure
-state.
-
-
-##### 2.3.3.1 Test secure payload behavior
-The TSPD hands control of a Secure-EL1 interrupt to the TSP at the
-`tsp_sel1_intr_entry()`. The TSP handles the interrupt while ensuring that the
-handover agreement described in Section 2.2.2.1 is maintained. It updates some
-statistics by calling `tsp_update_sync_sel1_intr_stats()`. It then calls
-`tsp_common_int_handler()` which.
-
-1. Checks whether the interrupt is the secure physical timer interrupt. It
- uses the platform API `plat_ic_get_pending_interrupt_id()` to get the
- interrupt number. If it is not the secure physical timer interrupt, then
- that means that a higher priority interrupt has preempted it. Invoke
- `tsp_handle_preemption()` to handover control back to EL3 by issuing
- an SMC with `TSP_PREEMPTED` as the function identifier.
-
-2. Handles the secure timer interrupt interrupt by acknowledging it using the
- `plat_ic_acknowledge_interrupt()` platform API, calling
- `tsp_generic_timer_handler()` to reprogram the secure physical generic
- timer and calling the `plat_ic_end_of_interrupt()` platform API to signal
- end of interrupt processing.
-
-The TSP passes control back to the TSPD by issuing an SMC64 with
-`TSP_HANDLED_S_EL1_INTR` as the function identifier.
-
-The TSP handles interrupts under the asynchronous model as follows.
-
-1. Secure-EL1 interrupts are handled by calling the `tsp_common_int_handler()`
- function. The function has been described above.
-
-2. Non-secure interrupts are handled by by calling the `tsp_common_int_handler()`
- function which ends up invoking `tsp_handle_preemption()` and issuing an
- SMC64 with `TSP_PREEMPTED` as the function identifier. Execution resumes at
- 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
- function identifier from the non-secure state (see section 2.3.2.4).
-
-
-3. Other considerations
------------------------
-
-### 3.1 Implication of preempted SMC on Non-Secure Software
-A `yielding` SMC call to Secure payload can be preempted by a non-secure
-interrupt and the execution can return to the non-secure world for handling
-the interrupt (For details on `yielding` SMC refer [SMC calling convention]).
-In this case, the SMC call has not completed its execution and the execution
-must return back to the secure payload to resume the preempted SMC call.
-This can be achieved by issuing an SMC call which instructs to resume the
-preempted SMC.
-
-A `fast` SMC cannot be preempted and hence this case will not happen for
-a fast SMC call.
-
-In the Test Secure Payload implementation, `TSP_FID_RESUME` is designated
-as the resume SMC FID. It is important to note that `TSP_FID_RESUME` is a
-`yielding` SMC which means it too can be be preempted. The typical non
-secure software sequence for issuing a `yielding` SMC would look like this,
-assuming `P.STATE.I=0` in the non secure state :
-
- int rc;
- rc = smc(TSP_YIELD_SMC_FID, ...); /* Issue a Yielding SMC call */
- /* The pending non-secure interrupt is handled by the interrupt handler
- and returns back here. */
- while (rc == SMC_PREEMPTED) { /* Check if the SMC call is preempted */
- rc = smc(TSP_FID_RESUME); /* Issue resume SMC call */
- }
-
-The `TSP_YIELD_SMC_FID` is any `yielding` SMC function identifier and the smc()
-function invokes a SMC call with the required arguments. The pending non-secure
-interrupt causes an IRQ exception and the IRQ handler registered at the
-exception vector handles the non-secure interrupt and returns. The return value
-from the SMC call is tested for `SMC_PREEMPTED` to check whether it is
-preempted. If it is, then the resume SMC call `TSP_FID_RESUME` is issued. The
-return value of the SMC call is tested again to check if it is preempted.
-This is done in a loop till the SMC call succeeds or fails. If a `yielding`
-SMC is preempted, until it is resumed using `TSP_FID_RESUME` SMC and
-completed, the current TSPD prevents any other SMC call from re-entering
-TSP by returning `SMC_UNK` error.
-
-
-- - - - - - - - - - - - - - - - - - - - - - - - - -
-
-_Copyright (c) 2014-2015, ARM Limited and Contributors. All rights reserved._
-
-[Porting Guide]: ./porting-guide.md
-[SMC calling convention]: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html "SMC Calling Convention PDD (ARM DEN 0028A)"
diff --git a/docs/interrupt-framework-design.rst b/docs/interrupt-framework-design.rst
new file mode 100644
index 0000000..940bc24
--- /dev/null
+++ b/docs/interrupt-framework-design.rst
@@ -0,0 +1,1003 @@
+ARM Trusted Firmware Interrupt Management Design guide
+======================================================
+
+
+.. section-numbering::
+ :suffix: .
+
+.. contents::
+
+This framework is responsible for managing interrupts routed to EL3. It also
+allows EL3 software to configure the interrupt routing behavior. Its main
+objective is to implement the following two requirements.
+
+#. It should be possible to route interrupts meant to be handled by secure
+ software (Secure interrupts) to EL3, when execution is in non-secure state
+ (normal world). The framework should then take care of handing control of
+ the interrupt to either software in EL3 or Secure-EL1 depending upon the
+ software configuration and the GIC implementation. This requirement ensures
+ that secure interrupts are under the control of the secure software with
+ respect to their delivery and handling without the possibility of
+ intervention from non-secure software.
+
+#. It should be possible to route interrupts meant to be handled by
+ non-secure software (Non-secure interrupts) to the last executed exception
+ level in the normal world when the execution is in secure world at
+ exception levels lower than EL3. This could be done with or without the
+ knowledge of software executing in Secure-EL1/Secure-EL0. The choice of
+ approach should be governed by the secure software. This requirement
+ ensures that non-secure software is able to execute in tandem with the
+ secure software without overriding it.
+
+Concepts
+--------
+
+Interrupt types
+~~~~~~~~~~~~~~~
+
+The framework categorises an interrupt to be one of the following depending upon
+the exception level(s) it is handled in.
+
+#. Secure EL1 interrupt. This type of interrupt can be routed to EL3 or
+ Secure-EL1 depending upon the security state of the current execution
+ context. It is always handled in Secure-EL1.
+
+#. Non-secure interrupt. This type of interrupt can be routed to EL3,
+ Secure-EL1, Non-secure EL1 or EL2 depending upon the security state of the
+ current execution context. It is always handled in either Non-secure EL1
+ or EL2.
+
+#. EL3 interrupt. This type of interrupt can be routed to EL3 or Secure-EL1
+ depending upon the security state of the current execution context. It is
+ always handled in EL3.
+
+The following constants define the various interrupt types in the framework
+implementation.
+
+::
+
+ #define INTR_TYPE_S_EL1 0
+ #define INTR_TYPE_EL3 1
+ #define INTR_TYPE_NS 2
+
+Routing model
+~~~~~~~~~~~~~
+
+A type of interrupt can be either generated as an FIQ or an IRQ. The target
+exception level of an interrupt type is configured through the FIQ and IRQ bits
+in the Secure Configuration Register at EL3 (``SCR_EL3.FIQ`` and ``SCR_EL3.IRQ``
+bits). When ``SCR_EL3.FIQ``\ =1, FIQs are routed to EL3. Otherwise they are routed
+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
+FEL. This register is configured independently by EL3 software for each security
+state prior to entry into a lower exception level in that security state.
+
+A routing model for a type of interrupt (generated as FIQ or IRQ) is defined as
+its target exception level for each security state. It is represented by a
+single bit for each security state. A value of ``0`` means that the interrupt
+should be routed to the FEL. A value of ``1`` means that the interrupt should be
+routed to EL3. A routing model is applicable only when execution is not in EL3.
+
+The default routing model for an interrupt type is to route it to the FEL in
+either security state.
+
+Valid routing models
+~~~~~~~~~~~~~~~~~~~~
+
+The framework considers certain routing models for each type of interrupt to be
+incorrect as they conflict with the requirements mentioned in Section 1. The
+following sub-sections describe all the possible routing models and specify
+which ones are valid or invalid. EL3 interrupts are currently supported only
+for GIC version 3.0 (ARM GICv3) and only the Secure-EL1 and Non-secure interrupt
+types are supported for GIC version 2.0 (ARM GICv2) (See 1.2). The terminology
+used in the following sub-sections is explained below.
+
+#. **CSS**. Current Security State. ``0`` when secure and ``1`` when non-secure
+
+#. **TEL3**. Target Exception Level 3. ``0`` when targeted to the FEL. ``1`` when
+ targeted to EL3.
+
+Secure-EL1 interrupts
+^^^^^^^^^^^^^^^^^^^^^
+
+#. **CSS=0, TEL3=0**. Interrupt is routed to the FEL when execution is in
+ secure state. This is a valid routing model as secure software is in
+ control of handling secure interrupts.
+
+#. **CSS=0, TEL3=1**. Interrupt is routed to EL3 when execution is in secure
+ state. This is a valid routing model as secure software in EL3 can
+ handover the interrupt to Secure-EL1 for handling.
+
+#. **CSS=1, TEL3=0**. Interrupt is routed to the FEL when execution is in
+ non-secure state. This is an invalid routing model as a secure interrupt
+ is not visible to the secure software which violates the motivation behind
+ the ARM Security Extensions.
+
+#. **CSS=1, TEL3=1**. Interrupt is routed to EL3 when execution is in
+ non-secure state. This is a valid routing model as secure software in EL3
+ can handover the interrupt to Secure-EL1 for handling.
+
+Non-secure interrupts
+^^^^^^^^^^^^^^^^^^^^^
+
+#. **CSS=0, TEL3=0**. Interrupt is routed to the FEL when execution is in
+ secure state. This allows the secure software to trap non-secure
+ interrupts, perform its book-keeping and hand the interrupt to the
+ non-secure software through EL3. This is a valid routing model as secure
+ software is in control of how its execution is preempted by non-secure
+ interrupts.
+
+#. **CSS=0, TEL3=1**. Interrupt is routed to EL3 when execution is in secure
+ state. This is a valid routing model as secure software in EL3 can save
+ the state of software in Secure-EL1/Secure-EL0 before handing the
+ interrupt to non-secure software. This model requires additional
+ coordination between Secure-EL1 and EL3 software to ensure that the
+ former's state is correctly saved by the latter.
+
+#. **CSS=1, TEL3=0**. Interrupt is routed to FEL when execution is in
+ non-secure state. This is an valid routing model as a non-secure interrupt
+ is handled by non-secure software.
+
+#. **CSS=1, TEL3=1**. Interrupt is routed to EL3 when execution is in
+ non-secure state. This is an invalid routing model as there is no valid
+ reason to route the interrupt to EL3 software and then hand it back to
+ non-secure software for handling.
+
+EL3 interrupts
+^^^^^^^^^^^^^^
+
+#. **CSS=0, TEL3=0**. Interrupt is routed to the FEL when execution is in
+ Secure-EL1/Secure-EL0. This is a valid routing model as secure software
+ in Secure-EL1/Secure-EL0 is in control of how its execution is preempted
+ by EL3 interrupt and can handover the interrupt to EL3 for handling.
+
+#. **CSS=0, TEL3=1**. Interrupt is routed to EL3 when execution is in
+ Secure-EL1/Secure-EL0. This is a valid routing model as secure software
+ in EL3 can handle the interrupt.
+
+#. **CSS=1, TEL3=0**. Interrupt is routed to the FEL when execution is in
+ non-secure state. This is an invalid routing model as a secure interrupt
+ is not visible to the secure software which violates the motivation behind
+ the ARM Security Extensions.
+
+#. **CSS=1, TEL3=1**. Interrupt is routed to EL3 when execution is in
+ non-secure state. This is a valid routing model as secure software in EL3
+ can handle the interrupt.
+
+Mapping of interrupt type to signal
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The framework is meant to work with any interrupt controller implemented by a
+platform. A interrupt controller could generate a type of interrupt as either an
+FIQ or IRQ signal to the CPU depending upon the current security state. The
+mapping between the type and signal is known only to the platform. The framework
+uses this information to determine whether the IRQ or the FIQ bit should be
+programmed in ``SCR_EL3`` while applying the routing model for a type of
+interrupt. The platform provides this information through the
+``plat_interrupt_type_to_line()`` API (described in the
+`Porting Guide`_). For example, on the FVP port when the platform uses an ARM GICv2
+interrupt controller, Secure-EL1 interrupts are signaled through the FIQ signal
+while Non-secure interrupts are signaled through the IRQ signal. This applies
+when execution is in either security state.
+
+Effect of mapping of several interrupt types to one signal
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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
+particular security state, then interrupt signal will be routed to EL3 when in
+that security state. This means that all the other interrupt types using the
+same interrupt signal will be forced to the same routing model. This should be
+borne in mind when choosing the routing model for an interrupt type.
+
+For example, in ARM GICv3, when the execution context is Secure-EL1/
+Secure-EL0, both the EL3 and the non secure interrupt types map to the FIQ
+signal. So if either one of the interrupt type sets the routing model so
+that **TEL3=1** when **CSS=0**, the FIQ bit in ``SCR_EL3`` will be programmed to
+route the FIQ signal to EL3 when executing in Secure-EL1/Secure-EL0, thereby
+effectively routing the other interrupt type also to EL3.
+
+Assumptions in Interrupt Management Framework
+---------------------------------------------
+
+The framework makes the following assumptions to simplify its implementation.
+
+#. Although the framework has support for 2 types of secure interrupts (EL3
+ and Secure-EL1 interrupt), only interrupt controller architectures
+ like ARM GICv3 has architectural support for EL3 interrupts in the form of
+ Group 0 interrupts. In ARM GICv2, all secure interrupts are assumed to be
+ handled in Secure-EL1. They can be delivered to Secure-EL1 via EL3 but they
+ cannot be handled in EL3.
+
+#. Interrupt exceptions (``PSTATE.I`` and ``F`` bits) are masked during execution
+ in EL3.
+
+#. .. rubric:: Interrupt management
+ :name: interrupt-management
+
+ The following sections describe how interrupts are managed by the interrupt
+ handling framework. This entails:
+
+#. Providing an interface to allow registration of a handler and specification
+ of the routing model for a type of interrupt.
+
+#. Implementing support to hand control of an interrupt type to its registered
+ handler when the interrupt is generated.
+
+Both aspects of interrupt management involve various components in the secure
+software stack spanning from EL3 to Secure-EL1. These components are described
+in the section 2.1. The framework stores information associated with each type
+of interrupt in the following data structure.
+
+.. code:: c
+
+ typedef struct intr_type_desc {
+ interrupt_type_handler_t handler;
+ uint32_t flags;
+ uint32_t scr_el3[2];
+ } intr_type_desc_t;
+
+The ``flags`` field stores the routing model for the interrupt type in
+bits[1:0]. Bit[0] stores the routing model when execution is in the secure
+state. Bit[1] stores the routing model when execution is in the non-secure
+state. As mentioned in Section 1.2.2, a value of ``0`` implies that the interrupt
+should be targeted to the FEL. A value of ``1`` implies that it should be targeted
+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``
+parameter.
+
+The ``scr_el3[2]`` field also stores the routing model but as a mapping of the
+model in the ``flags`` field to the corresponding bit in the ``SCR_EL3`` for each
+security state.
+
+The framework also depends upon the platform port to configure the interrupt
+controller to distinguish between secure and non-secure interrupts. The platform
+is expected to be aware of the secure devices present in the system and their
+associated interrupt numbers. It should configure the interrupt controller to
+enable the secure interrupts, ensure that their priority is always higher than
+the non-secure interrupts and target them to the primary CPU. It should also
+export the interface described in the `Porting Guide`_ to enable
+handling of interrupts.
+
+In the remainder of this document, for the sake of simplicity a ARM GICv2 system
+is considered and it is assumed that the FIQ signal is used to generate Secure-EL1
+interrupts and the IRQ signal is used to generate non-secure interrupts in either
+security state. EL3 interrupts are not considered.
+
+Software components
+-------------------
+
+Roles and responsibilities for interrupt management are sub-divided between the
+following components of software running in EL3 and Secure-EL1. Each component is
+briefly described below.
+
+#. EL3 Runtime Firmware. This component is common to all ports of the ARM
+ Trusted Firmware.
+
+#. Secure Payload Dispatcher (SPD) service. This service interfaces with the
+ Secure Payload (SP) software which runs in Secure-EL1/Secure-EL0 and is
+ responsible for switching execution between secure and non-secure states.
+ A switch is triggered by a Secure Monitor Call and it uses the APIs
+ exported by the Context management library to implement this functionality.
+ Switching execution between the two security states is a requirement for
+ interrupt management as well. This results in a significant dependency on
+ the SPD service. ARM Trusted firmware implements an example Test Secure
+ Payload Dispatcher (TSPD) service.
+
+ An SPD service plugs into the EL3 runtime firmware and could be common to
+ some ports of the ARM Trusted Firmware.
+
+#. Secure Payload (SP). On a production system, the Secure Payload corresponds
+ to a Secure OS which runs in Secure-EL1/Secure-EL0. It interfaces with the
+ SPD service to manage communication with non-secure software. ARM Trusted
+ Firmware implements an example secure payload called Test Secure Payload
+ (TSP) which runs only in Secure-EL1.
+
+ A Secure payload implementation could be common to some ports of the ARM
+ Trusted Firmware just like the SPD service.
+
+Interrupt registration
+----------------------
+
+This section describes in detail the role of each software component (see 2.1)
+during the registration of a handler for an interrupt type.
+
+EL3 runtime firmware
+~~~~~~~~~~~~~~~~~~~~
+
+This component declares the following prototype for a handler of an interrupt type.
+
+.. code:: c
+
+ typedef uint64_t (*interrupt_type_handler_t)(uint32_t id,
+ uint32_t flags,
+ void *handle,
+ void *cookie);
+
+The ``id`` is parameter is reserved and could be used in the future for passing
+the interrupt id of the highest pending interrupt only if there is a foolproof
+way of determining the id. Currently it contains ``INTR_ID_UNAVAILABLE``.
+
+The ``flags`` parameter contains miscellaneous information as follows.
+
+#. Security state, bit[0]. This bit indicates the security state of the lower
+ exception level when the interrupt was generated. A value of ``1`` means
+ that it was in the non-secure state. A value of ``0`` indicates that it was
+ in the secure state. This bit can be used by the handler to ensure that
+ interrupt was generated and routed as per the routing model specified
+ during registration.
+
+#. Reserved, bits[31:1]. The remaining bits are reserved for future use.
+
+The ``handle`` parameter points to the ``cpu_context`` structure of the current CPU
+for the security state specified in the ``flags`` parameter.
+
+Once the handler routine completes, execution will return to either the secure
+or non-secure state. The handler routine must return a pointer to
+``cpu_context`` structure of the current CPU for the target security state. On
+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
+via the context management library APIs.
+A portable interrupt handler implementation must set the target context both in
+the structure pointed to by the returned pointer and via the context management
+library APIs. The handler should treat all error conditions as critical errors
+and take appropriate action within its implementation e.g. use assertion
+failures.
+
+The runtime firmware provides the following API for registering a handler for a
+particular type of interrupt. A Secure Payload Dispatcher service should use
+this API to register a handler for Secure-EL1 and optionally for non-secure
+interrupts. This API also requires the caller to specify the routing model for
+the type of interrupt.
+
+.. code:: c
+
+ int32_t register_interrupt_type_handler(uint32_t type,
+ interrupt_type_handler handler,
+ uint64_t flags);
+
+The ``type`` parameter can be one of the three interrupt types listed above i.e.
+``INTR_TYPE_S_EL1``, ``INTR_TYPE_NS`` & ``INTR_TYPE_EL3``. The ``flags`` parameter
+is as described in Section 2.
+
+The function will return ``0`` upon a successful registration. It will return
+``-EALREADY`` in case a handler for the interrupt type has already been
+registered. If the ``type`` is unrecognised or the ``flags`` or the ``handler`` are
+invalid it will return ``-EINVAL``.
+
+Interrupt routing is governed by the configuration of the ``SCR_EL3.FIQ/IRQ`` bits
+prior to entry into a lower exception level in either security state. The
+context management library maintains a copy of the ``SCR_EL3`` system register for
+each security state in the ``cpu_context`` structure of each CPU. It exports the
+following APIs to let EL3 Runtime Firmware program and retrieve the routing
+model for each security state for the current CPU. The value of ``SCR_EL3`` stored
+in the ``cpu_context`` is used by the ``el3_exit()`` function to program the
+``SCR_EL3`` register prior to returning from the EL3 exception level.
+
+.. code:: c
+
+ uint32_t cm_get_scr_el3(uint32_t security_state);
+ void cm_write_scr_el3_bit(uint32_t security_state,
+ uint32_t bit_pos,
+ uint32_t value);
+
+``cm_get_scr_el3()`` returns the value of the ``SCR_EL3`` register for the specified
+security state of the current CPU. ``cm_write_scr_el3()`` writes a ``0`` or ``1`` to
+the bit specified by ``bit_pos``. ``register_interrupt_type_handler()`` invokes
+``set_routing_model()`` API which programs the ``SCR_EL3`` according to the routing
+model using the ``cm_get_scr_el3()`` and ``cm_write_scr_el3_bit()`` APIs.
+
+It is worth noting that in the current implementation of the framework, the EL3
+runtime firmware is responsible for programming the routing model. The SPD is
+responsible for ensuring that the routing model has been adhered to upon
+receiving an interrupt.
+
+Secure payload dispatcher
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A SPD service is responsible for determining and maintaining the interrupt
+routing model supported by itself and the Secure Payload. It is also responsible
+for ferrying interrupts between secure and non-secure software depending upon
+the routing model. It could determine the routing model at build time or at
+runtime. It must use this information to register a handler for each interrupt
+type using the ``register_interrupt_type_handler()`` API in EL3 runtime firmware.
+
+If the routing model is not known to the SPD service at build time, then it must
+be provided by the SP as the result of its initialisation. The SPD should
+program the routing model only after SP initialisation has completed e.g. in the
+SPD initialisation function pointed to by the ``bl32_init`` variable.
+
+The SPD should determine the mechanism to pass control to the Secure Payload
+after receiving an interrupt from the EL3 runtime firmware. This information
+could either be provided to the SPD service at build time or by the SP at
+runtime.
+
+Test secure payload dispatcher behavior
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The TSPD only handles Secure-EL1 interrupts and is provided with the following
+routing model at build time.
+
+- Secure-EL1 interrupts are routed to EL3 when execution is in non-secure
+ 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
+
+- When the build flag ``TSP_NS_INTR_ASYNC_PREEMPT`` is zero, the default routing
+ model is used for non-secure interrupts. They are routed to the FEL in
+ either security state i.e **CSS=0, TEL3=0** & **CSS=1, TEL3=0** for
+ Non-secure interrupts.
+
+- When the build flag ``TSP_NS_INTR_ASYNC_PREEMPT`` is defined to 1, then the
+ non secure interrupts are routed to EL3 when execution is in secure state
+ i.e **CSS=0, TEL3=1** for non-secure interrupts. This effectively preempts
+ Secure-EL1. The default routing model is used for non secure interrupts in
+ non-secure state. i.e **CSS=1, TEL3=0**.
+
+It performs the following actions in the ``tspd_init()`` function to fulfill the
+requirements mentioned earlier.
+
+#. It passes control to the Test Secure Payload to perform its
+ initialisation. The TSP provides the address of the vector table
+ ``tsp_vectors`` in the SP which also includes the handler for Secure-EL1
+ interrupts in the ``sel1_intr_entry`` field. The TSPD passes control to the TSP at
+ this address when it receives a Secure-EL1 interrupt.
+
+ The handover agreement between the TSP and the TSPD requires that the TSPD
+ masks all interrupts (``PSTATE.DAIF`` bits) when it calls
+ ``tsp_sel1_intr_entry()``. The TSP has to preserve the callee saved general
+ purpose, SP\_EL1/Secure-EL0, LR, VFP and system registers. It can use
+ ``x0-x18`` to enable its C runtime.
+
+#. The TSPD implements a handler function for Secure-EL1 interrupts. This
+ function is registered with the EL3 runtime firmware using the
+ ``register_interrupt_type_handler()`` API as follows
+
+ .. code:: c
+
+ /* Forward declaration */
+ interrupt_type_handler tspd_secure_el1_interrupt_handler;
+ int32_t rc, flags = 0;
+ set_interrupt_rm_flag(flags, NON_SECURE);
+ rc = register_interrupt_type_handler(INTR_TYPE_S_EL1,
+ tspd_secure_el1_interrupt_handler,
+ flags);
+ if (rc)
+ panic();
+
+#. When the build flag ``TSP_NS_INTR_ASYNC_PREEMPT`` is defined to 1, the TSPD
+ implements a handler function for non-secure interrupts. This function is
+ registered with the EL3 runtime firmware using the
+ ``register_interrupt_type_handler()`` API as follows
+
+ .. code:: c
+
+ /* Forward declaration */
+ interrupt_type_handler tspd_ns_interrupt_handler;
+ int32_t rc, flags = 0;
+ set_interrupt_rm_flag(flags, SECURE);
+ rc = register_interrupt_type_handler(INTR_TYPE_NS,
+ tspd_ns_interrupt_handler,
+ flags);
+ if (rc)
+ panic();
+
+Secure payload
+~~~~~~~~~~~~~~
+
+A Secure Payload must implement an interrupt handling framework at Secure-EL1
+(Secure-EL1 IHF) to support its chosen interrupt routing model. Secure payload
+execution will alternate between the below cases.
+
+#. In the code where IRQ, FIQ or both interrupts are enabled, if an interrupt
+ type is targeted to the FEL, then it will be routed to the Secure-EL1
+ exception vector table. This is defined as the **asynchronous mode** of
+ handling interrupts. This mode applies to both Secure-EL1 and non-secure
+ interrupts.
+
+#. In the code where both interrupts are disabled, if an interrupt type is
+ targeted to the FEL, then execution will eventually migrate to the
+ non-secure state. Any non-secure interrupts will be handled as described
+ in the routing model where **CSS=1 and TEL3=0**. Secure-EL1 interrupts
+ will be routed to EL3 (as per the routing model where **CSS=1 and
+ TEL3=1**) where the SPD service will hand them to the SP. This is defined
+ as the **synchronous mode** of handling interrupts.
+
+The interrupt handling framework implemented by the SP should support one or
+both these interrupt handling models depending upon the chosen routing model.
+
+The following list briefly describes how the choice of a valid routing model
+(See 1.2.3) effects the implementation of the Secure-EL1 IHF. If the choice of
+the interrupt routing model is not known to the SPD service at compile time,
+then the SP should pass this information to the SPD service at runtime during
+its initialisation phase.
+
+As mentioned earlier, a ARM GICv2 system is considered and it is assumed that
+the FIQ signal is used to generate Secure-EL1 interrupts and the IRQ signal
+is used to generate non-secure interrupts in either security state.
+
+Secure payload IHF design w.r.t secure-EL1 interrupts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. **CSS=0, TEL3=0**. If ``PSTATE.F=0``, Secure-EL1 interrupts will be
+ triggered at one of the Secure-EL1 FIQ exception vectors. The Secure-EL1
+ IHF should implement support for handling FIQ interrupts asynchronously.
+
+ If ``PSTATE.F=1`` then Secure-EL1 interrupts will be handled as per the
+ synchronous interrupt handling model. The SP could implement this scenario
+ by exporting a separate entrypoint for Secure-EL1 interrupts to the SPD
+ service during the registration phase. The SPD service would also need to
+ know the state of the system, general purpose and the ``PSTATE`` registers
+ in which it should arrange to return execution to the SP. The SP should
+ provide this information in an implementation defined way during the
+ registration phase if it is not known to the SPD service at build time.
+
+#. **CSS=1, TEL3=1**. Interrupts are routed to EL3 when execution is in
+ non-secure state. They should be handled through the synchronous interrupt
+ handling model as described in 1. above.
+
+#. **CSS=0, TEL3=1**. Secure-EL1 interrupts are routed to EL3 when execution
+ is in secure state. They will not be visible to the SP. The ``PSTATE.F`` bit
+ in Secure-EL1/Secure-EL0 will not mask FIQs. The EL3 runtime firmware will
+ call the handler registered by the SPD service for Secure-EL1 interrupts.
+ Secure-EL1 IHF should then handle all Secure-EL1 interrupt through the
+ synchronous interrupt handling model described in 1. above.
+
+Secure payload IHF design w.r.t non-secure interrupts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. **CSS=0, TEL3=0**. If ``PSTATE.I=0``, non-secure interrupts will be
+ triggered at one of the Secure-EL1 IRQ exception vectors . The Secure-EL1
+ IHF should co-ordinate with the SPD service to transfer execution to the
+ non-secure state where the interrupt should be handled e.g the SP could
+ allocate a function identifier to issue a SMC64 or SMC32 to the SPD
+ service which indicates that the SP execution has been preempted by a
+ non-secure interrupt. If this function identifier is not known to the SPD
+ service at compile time then the SP could provide it during the
+ registration phase.
+
+ If ``PSTATE.I=1`` then the non-secure interrupt will pend until execution
+ resumes in the non-secure state.
+
+#. **CSS=0, TEL3=1**. Non-secure interrupts are routed to EL3. They will not
+ be visible to the SP. The ``PSTATE.I`` bit in Secure-EL1/Secure-EL0 will
+ have not effect. The SPD service should register a non-secure interrupt
+ handler which should save the SP state correctly and resume execution in
+ the non-secure state where the interrupt will be handled. The Secure-EL1
+ IHF does not need to take any action.
+
+#. **CSS=1, TEL3=0**. Non-secure interrupts are handled in the FEL in
+ non-secure state (EL1/EL2) and are not visible to the SP. This routing
+ model does not affect the SP behavior.
+
+A Secure Payload must also ensure that all Secure-EL1 interrupts are correctly
+configured at the interrupt controller by the platform port of the EL3 runtime
+firmware. It should configure any additional Secure-EL1 interrupts which the EL3
+runtime firmware is not aware of through its platform port.
+
+Test secure payload behavior
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The routing model for Secure-EL1 and non-secure interrupts chosen by the TSP is
+described in Section 2.2.2. It is known to the TSPD service at build time.
+
+The TSP implements an entrypoint (``tsp_sel1_intr_entry()``) for handling Secure-EL1
+interrupts taken in non-secure state and routed through the TSPD service
+(synchronous handling model). It passes the reference to this entrypoint via
+``tsp_vectors`` to the TSPD service.
+
+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
+exceptions taken at the same (Secure-EL1) exception level. This table is
+referenced through the ``tsp_exceptions`` variable and programmed into the
+VBAR\_EL1. It caters for the asynchronous handling model.
+
+The TSP also programs the Secure Physical Timer in the ARM Generic Timer block
+to raise a periodic interrupt (every half a second) for the purpose of testing
+interrupt management across all the software components listed in 2.1
+
+Interrupt handling
+------------------
+
+This section describes in detail the role of each software component (see
+Section 2.1) in handling an interrupt of a particular type.
+
+EL3 runtime firmware
+~~~~~~~~~~~~~~~~~~~~
+
+The EL3 runtime firmware populates the IRQ and FIQ exception vectors referenced
+by the ``runtime_exceptions`` variable as follows.
+
+#. IRQ and FIQ exceptions taken from the current exception level with
+ ``SP_EL0`` or ``SP_EL3`` are reported as irrecoverable error conditions. As
+ mentioned earlier, EL3 runtime firmware always executes with the
+ ``PSTATE.I`` and ``PSTATE.F`` bits set.
+
+#. The following text describes how the IRQ and FIQ exceptions taken from a
+ lower exception level using AArch64 or AArch32 are handled.
+
+When an interrupt is generated, the vector for each interrupt type is
+responsible for:
+
+#. Saving the entire general purpose register context (x0-x30) immediately
+ upon exception entry. The registers are saved in the per-cpu ``cpu_context``
+ data structure referenced by the ``SP_EL3``\ register.
+
+#. Saving the ``ELR_EL3``, ``SP_EL0`` and ``SPSR_EL3`` system registers in the
+ per-cpu ``cpu_context`` data structure referenced by the ``SP_EL3`` register.
+
+#. Switching to the C runtime stack by restoring the ``CTX_RUNTIME_SP`` value
+ from the per-cpu ``cpu_context`` data structure in ``SP_EL0`` and
+ executing the ``msr spsel, #0`` instruction.
+
+#. Determining the type of interrupt. Secure-EL1 interrupts will be signaled
+ at the FIQ vector. Non-secure interrupts will be signaled at the IRQ
+ vector. The platform should implement the following API to determine the
+ type of the pending interrupt.
+
+ .. code:: c
+
+ uint32_t plat_ic_get_interrupt_type(void);
+
+ It should return either ``INTR_TYPE_S_EL1`` or ``INTR_TYPE_NS``.
+
+#. Determining the handler for the type of interrupt that has been generated.
+ The following API has been added for this purpose.
+
+ .. code:: c
+
+ interrupt_type_handler get_interrupt_type_handler(uint32_t interrupt_type);
+
+ It returns the reference to the registered handler for this interrupt
+ type. The ``handler`` is retrieved from the ``intr_type_desc_t`` structure as
+ described in Section 2. ``NULL`` is returned if no handler has been
+ registered for this type of interrupt. This scenario is reported as an
+ irrecoverable error condition.
+
+#. Calling the registered handler function for the interrupt type generated.
+ The ``id`` parameter is set to ``INTR_ID_UNAVAILABLE`` currently. The id along
+ with the current security state and a reference to the ``cpu_context_t``
+ structure for the current security state are passed to the handler function
+ as its arguments.
+
+ The handler function returns a reference to the per-cpu ``cpu_context_t``
+ structure for the target security state.
+
+#. Calling ``el3_exit()`` to return from EL3 into a lower exception level in
+ the security state determined by the handler routine. The ``el3_exit()``
+ function is responsible for restoring the register context from the
+ ``cpu_context_t`` data structure for the target security state.
+
+Secure payload dispatcher
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Interrupt entry
+^^^^^^^^^^^^^^^
+
+The SPD service begins handling an interrupt when the EL3 runtime firmware calls
+the handler function for that type of interrupt. The SPD service is responsible
+for the following:
+
+#. Validating the interrupt. This involves ensuring that the interrupt was
+ generating according to the interrupt routing model specified by the SPD
+ service during registration. It should use the security state of the
+ exception level (passed in the ``flags`` parameter of the handler) where
+ the interrupt was taken from to determine this. If the interrupt is not
+ recognised then the handler should treat it as an irrecoverable error
+ condition.
+
+ A SPD service can register a handler for Secure-EL1 and/or Non-secure
+ interrupts. A non-secure interrupt should never be routed to EL3 from
+ from non-secure state. Also if a routing model is chosen where Secure-EL1
+ interrupts are routed to S-EL1 when execution is in Secure state, then a
+ S-EL1 interrupt should never be routed to EL3 from secure state. The handler
+ could use the security state flag to check this.
+
+#. Determining whether a context switch is required. This depends upon the
+ routing model and interrupt type. For non secure and S-EL1 interrupt,
+ if the security state of the execution context where the interrupt was
+ generated is not the same as the security state required for handling
+ the interrupt, a context switch is required. The following 2 cases
+ require a context switch from secure to non-secure or vice-versa:
+
+ #. A Secure-EL1 interrupt taken from the non-secure state should be
+ routed to the Secure Payload.
+
+ #. A non-secure interrupt taken from the secure state should be routed
+ to the last known non-secure exception level.
+
+ The SPD service must save the system register context of the current
+ security state. It must then restore the system register context of the
+ target security state. It should use the ``cm_set_next_eret_context()`` API
+ to ensure that the next ``cpu_context`` to be restored is of the target
+ security state.
+
+ If the target state is secure then execution should be handed to the SP as
+ per the synchronous interrupt handling model it implements. A Secure-EL1
+ interrupt can be routed to EL3 while execution is in the SP. This implies
+ that SP execution can be preempted while handling an interrupt by a
+ another higher priority Secure-EL1 interrupt or a EL3 interrupt. The SPD
+ service should be able to handle this preemption or manage secure interrupt
+ priorities before handing control to the SP.
+
+#. Setting the return value of the handler to the per-cpu ``cpu_context`` if
+ the interrupt has been successfully validated and ready to be handled at a
+ lower exception level.
+
+The routing model allows non-secure interrupts to interrupt Secure-EL1 when in
+secure state if it has been configured to do so. The SPD service and the SP
+should implement a mechanism for routing these interrupts to the last known
+exception level in the non-secure state. The former should save the SP context,
+restore the non-secure context and arrange for entry into the non-secure state
+so that the interrupt can be handled.
+
+Interrupt exit
+^^^^^^^^^^^^^^
+
+When the Secure Payload has finished handling a Secure-EL1 interrupt, it could
+return control back to the SPD service through a SMC32 or SMC64. The SPD service
+should handle this secure monitor call so that execution resumes in the
+exception level and the security state from where the Secure-EL1 interrupt was
+originally taken.
+
+Test secure payload dispatcher Secure-EL1 interrupt handling
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The example TSPD service registers a handler for Secure-EL1 interrupts taken
+from the non-secure state. During execution in S-EL1, the TSPD expects that the
+Secure-EL1 interrupts are handled in S-EL1 by TSP. Its handler
+``tspd_secure_el1_interrupt_handler()`` expects only to be invoked for Secure-EL1
+originating from the non-secure state. It takes the following actions upon being
+invoked.
+
+#. It uses the security state provided in the ``flags`` parameter to ensure
+ that the secure interrupt originated from the non-secure state. It asserts
+ if this is not the case.
+
+#. It saves the system register context for the non-secure state by calling
+ ``cm_el1_sysregs_context_save(NON_SECURE);``.
+
+#. It sets the ``ELR_EL3`` system register to ``tsp_sel1_intr_entry`` and sets the
+ ``SPSR_EL3.DAIF`` bits in the secure CPU context. It sets ``x0`` to
+ ``TSP_HANDLE_SEL1_INTR_AND_RETURN``. If the TSP was preempted earlier by a non
+ secure interrupt during ``yielding`` SMC processing, save the registers that
+ will be trashed, which is the ``ELR_EL3`` and ``SPSR_EL3``, in order to be able
+ to re-enter TSP for Secure-EL1 interrupt processing. It does not need to
+ save any other secure context since the TSP is expected to preserve it
+ (see Section 2.2.2.1).
+
+#. It restores the system register context for the secure state by calling
+ ``cm_el1_sysregs_context_restore(SECURE);``.
+
+#. It ensures that the secure CPU context is used to program the next
+ exception return from EL3 by calling ``cm_set_next_eret_context(SECURE);``.
+
+#. It returns the per-cpu ``cpu_context`` to indicate that the interrupt can
+ now be handled by the SP. ``x1`` is written with the value of ``elr_el3``
+ register for the non-secure state. This information is used by the SP for
+ debugging purposes.
+
+The figure below describes how the interrupt handling is implemented by the TSPD
+when a Secure-EL1 interrupt is generated when execution is in the non-secure
+state.
+
+|Image 1|
+
+The TSP issues an SMC with ``TSP_HANDLED_S_EL1_INTR`` as the function identifier to
+signal completion of interrupt handling.
+
+The TSPD service takes the following actions in ``tspd_smc_handler()`` function
+upon receiving an SMC with ``TSP_HANDLED_S_EL1_INTR`` as the function identifier:
+
+#. It ensures that the call originated from the secure state otherwise
+ execution returns to the non-secure state with ``SMC_UNK`` in ``x0``.
+
+#. It restores the saved ``ELR_EL3`` and ``SPSR_EL3`` system registers back to
+ the secure CPU context (see step 3 above) in case the TSP had been preempted
+ by a non secure interrupt earlier.
+
+#. It restores the system register context for the non-secure state by
+ calling ``cm_el1_sysregs_context_restore(NON_SECURE)``.
+
+#. It ensures that the non-secure CPU context is used to program the next
+ exception return from EL3 by calling ``cm_set_next_eret_context(NON_SECURE)``.
+
+#. ``tspd_smc_handler()`` returns a reference to the non-secure ``cpu_context``
+ as the return value.
+
+Test secure payload dispatcher non-secure interrupt handling
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The TSP in Secure-EL1 can be preempted by a non-secure interrupt during
+``yielding`` SMC processing or by a higher priority EL3 interrupt during
+Secure-EL1 interrupt processing. Currently only non-secure interrupts can
+cause preemption of TSP since there are no EL3 interrupts in the
+system.
+
+It should be noted that while TSP is preempted, the TSPD only allows entry into
+the TSP either for Secure-EL1 interrupt handling or for resuming the preempted
+``yielding`` SMC in response to the ``TSP_FID_RESUME`` SMC from the normal world.
+(See Section 3).
+
+The non-secure interrupt triggered in Secure-EL1 during ``yielding`` SMC processing
+can be routed to either EL3 or Secure-EL1 and is controlled by build option
+``TSP_NS_INTR_ASYNC_PREEMPT`` (see Section 2.2.2.1). If the build option is set,
+the TSPD will set the routing model for the non-secure interrupt to be routed to
+EL3 from secure state i.e. **TEL3=1, CSS=0** and registers
+``tspd_ns_interrupt_handler()`` as the non-secure interrupt handler. The
+``tspd_ns_interrupt_handler()`` on being invoked ensures that the interrupt
+originated from the secure state and disables routing of non-secure interrupts
+from secure state to EL3. This is to prevent further preemption (by a non-secure
+interrupt) when TSP is reentered for handling Secure-EL1 interrupts that
+triggered while execution was in the normal world. The
+``tspd_ns_interrupt_handler()`` then invokes ``tspd_handle_sp_preemption()`` for
+further handling.
+
+If the ``TSP_NS_INTR_ASYNC_PREEMPT`` build option is zero (default), the default
+routing model for non-secure interrupt in secure state is in effect
+i.e. **TEL3=0, CSS=0**. During ``yielding`` SMC processing, the IRQ
+exceptions are unmasked i.e. ``PSTATE.I=0``, and a non-secure interrupt will
+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
+identifier to signal preemption of TSP. The TSPD SMC handler,
+``tspd_smc_handler()``, ensures that the SMC call originated from the
+secure state otherwise execution returns to the non-secure state with
+``SMC_UNK`` in ``x0``. It then invokes ``tspd_handle_sp_preemption()`` for
+further handling.
+
+The ``tspd_handle_sp_preemption()`` takes the following actions upon being
+invoked:
+
+#. It saves the system register context for the secure state by calling
+ ``cm_el1_sysregs_context_save(SECURE)``.
+
+#. It restores the system register context for the non-secure state by
+ calling ``cm_el1_sysregs_context_restore(NON_SECURE)``.
+
+#. It ensures that the non-secure CPU context is used to program the next
+ exception return from EL3 by calling ``cm_set_next_eret_context(NON_SECURE)``.
+
+#. ``SMC_PREEMPTED`` is set in x0 and return to non secure state after
+ restoring non secure context.
+
+The Normal World is expected to resume the TSP after the ``yielding`` SMC preemption
+by issuing an SMC with ``TSP_FID_RESUME`` as the function identifier (see section 3).
+The TSPD service takes the following actions in ``tspd_smc_handler()`` function
+upon receiving this SMC:
+
+#. It ensures that the call originated from the non secure state. An
+ assertion is raised otherwise.
+
+#. Checks whether the TSP needs a resume i.e check if it was preempted. It
+ then saves the system register context for the non-secure state by calling
+ ``cm_el1_sysregs_context_save(NON_SECURE)``.
+
+#. Restores the secure context by calling
+ ``cm_el1_sysregs_context_restore(SECURE)``
+
+#. It ensures that the secure CPU context is used to program the next
+ exception return from EL3 by calling ``cm_set_next_eret_context(SECURE)``.
+
+#. ``tspd_smc_handler()`` returns a reference to the secure ``cpu_context`` as the
+ return value.
+
+The figure below describes how the TSP/TSPD handle a non-secure interrupt when
+it is generated during execution in the TSP with ``PSTATE.I`` = 0 when the
+``TSP_NS_INTR_ASYNC_PREEMPT`` build flag is 0.
+
+|Image 2|
+
+Secure payload
+~~~~~~~~~~~~~~
+
+The SP should implement one or both of the synchronous and asynchronous
+interrupt handling models depending upon the interrupt routing model it has
+chosen (as described in 2.2.3).
+
+In the synchronous model, it should begin handling a Secure-EL1 interrupt after
+receiving control from the SPD service at an entrypoint agreed upon during build
+time or during the registration phase. Before handling the interrupt, the SP
+should save any Secure-EL1 system register context which is needed for resuming
+normal execution in the SP later e.g. ``SPSR_EL1,``\ ELR\_EL1\`. After handling the
+interrupt, the SP could return control back to the exception level and security
+state where the interrupt was originally taken from. The SP should use an SMC32
+or SMC64 to ask the SPD service to do this.
+
+In the asynchronous model, the Secure Payload is responsible for handling
+non-secure and Secure-EL1 interrupts at the IRQ and FIQ vectors in its exception
+vector table when ``PSTATE.I`` and ``PSTATE.F`` bits are 0. As described earlier,
+when a non-secure interrupt is generated, the SP should coordinate with the SPD
+service to pass control back to the non-secure state in the last known exception
+level. This will allow the non-secure interrupt to be handled in the non-secure
+state.
+
+Test secure payload behavior
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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
+handover agreement described in Section 2.2.2.1 is maintained. It updates some
+statistics by calling ``tsp_update_sync_sel1_intr_stats()``. It then calls
+``tsp_common_int_handler()`` which.
+
+#. Checks whether the interrupt is the secure physical timer interrupt. It
+ uses the platform API ``plat_ic_get_pending_interrupt_id()`` to get the
+ interrupt number. If it is not the secure physical timer interrupt, then
+ that means that a higher priority interrupt has preempted it. Invoke
+ ``tsp_handle_preemption()`` to handover control back to EL3 by issuing
+ an SMC with ``TSP_PREEMPTED`` as the function identifier.
+
+#. Handles the secure timer interrupt interrupt by acknowledging it using the
+ ``plat_ic_acknowledge_interrupt()`` platform API, calling
+ ``tsp_generic_timer_handler()`` to reprogram the secure physical generic
+ timer and calling the ``plat_ic_end_of_interrupt()`` platform API to signal
+ end of interrupt processing.
+
+The TSP passes control back to the TSPD by issuing an SMC64 with
+``TSP_HANDLED_S_EL1_INTR`` as the function identifier.
+
+The TSP handles interrupts under the asynchronous model as follows.
+
+#. Secure-EL1 interrupts are handled by calling the ``tsp_common_int_handler()``
+ function. The function has been described above.
+
+#. Non-secure interrupts are handled by by calling the ``tsp_common_int_handler()``
+ function which ends up invoking ``tsp_handle_preemption()`` and issuing an
+ SMC64 with ``TSP_PREEMPTED`` as the function identifier. Execution resumes at
+ the instruction that follows this SMC instruction when the TSPD hands
+ control to the TSP in response to an SMC with ``TSP_FID_RESUME`` as the
+ function identifier from the non-secure state (see section 2.3.2.4).
+
+#. .. rubric:: Other considerations
+ :name: other-considerations
+
+Implication of preempted SMC on Non-Secure Software
+---------------------------------------------------
+
+A ``yielding`` SMC call to Secure payload can be preempted by a non-secure
+interrupt and the execution can return to the non-secure world for handling
+the interrupt (For details on ``yielding`` SMC refer `SMC calling convention`_).
+In this case, the SMC call has not completed its execution and the execution
+must return back to the secure payload to resume the preempted SMC call.
+This can be achieved by issuing an SMC call which instructs to resume the
+preempted SMC.
+
+A ``fast`` SMC cannot be preempted and hence this case will not happen for
+a fast SMC call.
+
+In the Test Secure Payload implementation, ``TSP_FID_RESUME`` is designated
+as the resume SMC FID. It is important to note that ``TSP_FID_RESUME`` is a
+``yielding`` SMC which means it too can be be preempted. The typical non
+secure software sequence for issuing a ``yielding`` SMC would look like this,
+assuming ``P.STATE.I=0`` in the non secure state :
+
+.. code:: c
+
+ int rc;
+ rc = smc(TSP_YIELD_SMC_FID, ...); /* Issue a Yielding SMC call */
+ /* The pending non-secure interrupt is handled by the interrupt handler
+ and returns back here. */
+ while (rc == SMC_PREEMPTED) { /* Check if the SMC call is preempted */
+ rc = smc(TSP_FID_RESUME); /* Issue resume SMC call */
+ }
+
+The ``TSP_YIELD_SMC_FID`` is any ``yielding`` SMC function identifier and the smc()
+function invokes a SMC call with the required arguments. The pending non-secure
+interrupt causes an IRQ exception and the IRQ handler registered at the
+exception vector handles the non-secure interrupt and returns. The return value
+from the SMC call is tested for ``SMC_PREEMPTED`` to check whether it is
+preempted. If it is, then the resume SMC call ``TSP_FID_RESUME`` is issued. The
+return value of the SMC call is tested again to check if it is preempted.
+This is done in a loop till the SMC call succeeds or fails. If a ``yielding``
+SMC is preempted, until it is resumed using ``TSP_FID_RESUME`` SMC and
+completed, the current TSPD prevents any other SMC call from re-entering
+TSP by returning ``SMC_UNK`` error.
+
+--------------
+
+*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
+
+.. |Image 1| image:: diagrams/sec-int-handling.png?raw=true
+.. |Image 2| image:: diagrams/non-sec-int-handling.png?raw=true
diff --git a/docs/plat/hikey.md b/docs/plat/hikey.md
deleted file mode 100644
index a5e592b..0000000
--- a/docs/plat/hikey.md
+++ /dev/null
@@ -1,123 +0,0 @@
-
-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)
diff --git a/docs/plat/hikey.rst b/docs/plat/hikey.rst
new file mode 100644
index 0000000..027e14c
--- /dev/null
+++ b/docs/plat/hikey.rst
@@ -0,0 +1,156 @@
+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
diff --git a/docs/plat/hikey960.md b/docs/plat/hikey960.md
deleted file mode 100644
index 786a54b..0000000
--- a/docs/plat/hikey960.md
+++ /dev/null
@@ -1,134 +0,0 @@
-
-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)
diff --git a/docs/plat/hikey960.rst b/docs/plat/hikey960.rst
new file mode 100644
index 0000000..c28ef3a
--- /dev/null
+++ b/docs/plat/hikey960.rst
@@ -0,0 +1,172 @@
+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
diff --git a/docs/plat/nvidia-tegra.md b/docs/plat/nvidia-tegra.rst
similarity index 75%
rename from docs/plat/nvidia-tegra.md
rename to docs/plat/nvidia-tegra.rst
index b45fec6..7aac7e5 100644
--- a/docs/plat/nvidia-tegra.md
+++ b/docs/plat/nvidia-tegra.rst
@@ -1,8 +1,8 @@
Tegra SoCs - Overview
-======================
+=====================
-* T210
--------
+- .. rubric:: T210
+ :name: t210
T210 has Quad ARM® Cortex®-A57 cores in a switched configuration with a
companion set of quad ARM Cortex-A53 cores. The Cortex-A57 and A53 cores
@@ -12,11 +12,11 @@
Level 2 unified cache. The Cortex-A53 processors each have 32 KB Instruction
and 32 KB Data Level 1 caches; and have a 512 KB shared Level 2 unified cache.
-* T132
--------
+- .. rubric:: T132
+ :name: t132
Denver is NVIDIA's own custom-designed, 64-bit, dual-core CPU which is
-fully ARMv8 architecture compatible. Each of the two Denver cores
+fully ARMv8 architecture compatible. Each of the two Denver cores
implements a 7-way superscalar microarchitecture (up to 7 concurrent
micro-ops can be executed per clock), and includes a 128KB 4-way L1
instruction cache, a 64KB 4-way L1 data cache, and a 2MB 16-way L2
@@ -41,13 +41,14 @@
workloads.
Directory structure
-====================
+===================
-* plat/nvidia/tegra/common - Common code for all Tegra SoCs
-* plat/nvidia/tegra/soc/txxx - Chip specific code
+- plat/nvidia/tegra/common - Common code for all Tegra SoCs
+- plat/nvidia/tegra/soc/txxx - Chip specific code
Trusted OS dispatcher
=====================
+
Tegra supports multiple Trusted OS', Trusted Little Kernel (TLK) being one of
them. In order to include the 'tlkd' dispatcher in the image, pass 'SPD=tlkd'
on the command line while preparing a bl31 image. This allows other Trusted OS
@@ -55,39 +56,43 @@
without changing any makefiles.
Preparing the BL31 image to run on Tegra SoCs
-===================================================
-'CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- make PLAT=tegra \
-TARGET_SOC=<target-soc e.g. t210|t132> SPD=<dispatcher e.g. tlkd> bl31'
+=============================================
-Platforms wanting to use different TZDRAM_BASE, can add 'TZDRAM_BASE=<value>'
+.. code:: shell
+
+ CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- make PLAT=tegra \
+ TARGET_SOC=<target-soc e.g. t210|t132> SPD=<dispatcher e.g. tlkd> bl31
+
+Platforms wanting to use different TZDRAM\_BASE, can add ``TZDRAM_BASE=<value>``
to the build command line.
The Tegra platform code expects a pointer to the following platform specific
structure via 'x1' register from the BL2 layer which is used by the
-bl31_early_platform_setup() handler to extract the TZDRAM carveout base and
+bl31\_early\_platform\_setup() handler to extract the TZDRAM carveout base and
size for loading the Trusted OS and the UART port ID to be used. The Tegra
memory controller driver programs this base/size in order to restrict NS
accesses.
-typedef struct plat_params_from_bl2 {
- /* TZ memory size */
- uint64_t tzdram_size;
- /* TZ memory base */
- uint64_t tzdram_base;
- /* UART port ID */
- int uart_id;
-} plat_params_from_bl2_t;
+typedef struct plat\_params\_from\_bl2 {
+/\* TZ memory size */
+uint64\_t tzdram\_size;
+/* TZ memory base */
+uint64\_t tzdram\_base;
+/* UART port ID \*/
+int uart\_id;
+} plat\_params\_from\_bl2\_t;
Power Management
================
+
The PSCI implementation expects each platform to expose the 'power state'
parameter to be used during the 'SYSTEM SUSPEND' call. The state-id field
is implementation defined on Tegra SoCs and is preferably defined by
-tegra_def.h.
+tegra\_def.h.
Tegra configs
=============
-* 'tegra_enable_l2_ecc_parity_prot': This flag enables the L2 ECC and Parity
+- 'tegra\_enable\_l2\_ecc\_parity\_prot': This flag enables the L2 ECC and Parity
Protection bit, for ARM Cortex-A57 CPUs, during CPU boot. This flag will
be enabled by Tegrs SoCs during 'Cluster power up' or 'System Suspend' exit.
diff --git a/docs/plat/qemu.md b/docs/plat/qemu.md
deleted file mode 100644
index 5e6bcbc..0000000
--- a/docs/plat/qemu.md
+++ /dev/null
@@ -1,44 +0,0 @@
-ARM Trusted Firmware for QEMU virt ARMv8-A
-==========================================
-
-ARM Trusted Firmware implements the EL3 firmware layer for QEMU virt
-ARMv8-A. BL1 is used as the BootROM, supplied with the -bios argument.
-When QEMU starts all CPUs are released simultaneously, BL1 selects a
-primary CPU to handle the boot and the secondaries are placed in a polling
-loop to be released by normal world via PSCI.
-
-BL2 edits the Flattened Device Tree, FDT, generated by QEMU at run-time to
-add a node describing PSCI and also enable methods for the CPUs.
-
-An ARM64 defonfig v4.5 Linux kernel is known to boot, FTD doesn't need to be
-provided as it's generated by QEMU.
-
-Current limitations:
-* Only cold boot is supported
-* No build instructions for QEMU_EFI.fd and rootfs-arm64.cpio.gz
-* No instructions for how to load a BL32 (Secure Payload)
-
-`QEMU_EFI.fd` can be dowloaded from
-http://snapshots.linaro.org/components/kernel/leg-virt-tianocore-edk2-upstream/latest/QEMU-KERNEL-AARCH64/RELEASE_GCC49/QEMU_EFI.fd
-
-Boot binaries, except BL1, are primarily loaded via semi-hosting so all
-binaries has to reside in the same directory as QEMU is started from. This
-is conveniently achieved with symlinks the local names as:
-* `bl2.bin` -> BL2
-* `bl31.bin` -> BL31
-* `bl33.bin` -> BL33 (`QEMU_EFI.fd`)
-* `Image` -> linux/Image
-
-To build:
-```
-make CROSS_COMPILE=aarch64-none-elf- PLAT=qemu
-```
-
-To start (QEMU v2.6.0):
-```
-qemu-system-aarch64 -nographic -machine virt,secure=on -cpu cortex-a57 \
- -kernel Image \
- -append console=ttyAMA0,38400 keep_bootcon root=/dev/vda2 \
- -initrd rootfs-arm64.cpio.gz -smp 2 -m 1024 -bios bl1.bin \
- -d unimp -semihosting-config enable,target=native
-```
diff --git a/docs/plat/qemu.rst b/docs/plat/qemu.rst
new file mode 100644
index 0000000..4e2cd7c
--- /dev/null
+++ b/docs/plat/qemu.rst
@@ -0,0 +1,48 @@
+ARM Trusted Firmware for QEMU virt ARMv8-A
+==========================================
+
+ARM Trusted Firmware implements the EL3 firmware layer for QEMU virt
+ARMv8-A. BL1 is used as the BootROM, supplied with the -bios argument.
+When QEMU starts all CPUs are released simultaneously, BL1 selects a
+primary CPU to handle the boot and the secondaries are placed in a polling
+loop to be released by normal world via PSCI.
+
+BL2 edits the Flattened Device Tree, FDT, generated by QEMU at run-time to
+add a node describing PSCI and also enable methods for the CPUs.
+
+An ARM64 defonfig v4.5 Linux kernel is known to boot, FTD doesn't need to be
+provided as it's generated by QEMU.
+
+Current limitations:
+
+- Only cold boot is supported
+- No build instructions for QEMU\_EFI.fd and rootfs-arm64.cpio.gz
+- No instructions for how to load a BL32 (Secure Payload)
+
+``QEMU_EFI.fd`` can be dowloaded from
+http://snapshots.linaro.org/components/kernel/leg-virt-tianocore-edk2-upstream/latest/QEMU-KERNEL-AARCH64/RELEASE_GCC49/QEMU_EFI.fd
+
+Boot binaries, except BL1, are primarily loaded via semi-hosting so all
+binaries has to reside in the same directory as QEMU is started from. This
+is conveniently achieved with symlinks the local names as:
+
+- ``bl2.bin`` -> BL2
+- ``bl31.bin`` -> BL31
+- ``bl33.bin`` -> BL33 (``QEMU_EFI.fd``)
+- ``Image`` -> linux/Image
+
+To build:
+
+::
+
+ make CROSS_COMPILE=aarch64-none-elf- PLAT=qemu
+
+To start (QEMU v2.6.0):
+
+::
+
+ qemu-system-aarch64 -nographic -machine virt,secure=on -cpu cortex-a57 \
+ -kernel Image \
+ -append console=ttyAMA0,38400 keep_bootcon root=/dev/vda2 \
+ -initrd rootfs-arm64.cpio.gz -smp 2 -m 1024 -bios bl1.bin \
+ -d unimp -semihosting-config enable,target=native
diff --git a/docs/plat/socionext-uniphier.md b/docs/plat/socionext-uniphier.md
deleted file mode 100644
index 91d72ec..0000000
--- a/docs/plat/socionext-uniphier.md
+++ /dev/null
@@ -1,130 +0,0 @@
-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
-```
diff --git a/docs/plat/socionext-uniphier.rst b/docs/plat/socionext-uniphier.rst
new file mode 100644
index 0000000..fb6ebe5
--- /dev/null
+++ b/docs/plat/socionext-uniphier.rst
@@ -0,0 +1,124 @@
+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
diff --git a/docs/plat/xilinx-zynqmp.md b/docs/plat/xilinx-zynqmp.md
deleted file mode 100644
index d2dc8b7..0000000
--- a/docs/plat/xilinx-zynqmp.md
+++ /dev/null
@@ -1,56 +0,0 @@
-ARM Trusted Firmware for Xilinx Zynq UltraScale+ MPSoC
-================================
-
-ARM Trusted Firmware implements the EL3 firmware layer for Xilinx Zynq
-UltraScale + MPSoC.
-The platform only uses the runtime part of ATF as ZynqMP already has a
-BootROM (BL1) and FSBL (BL2).
-
-BL31 is ATF.
-BL32 is an optional Secure Payload.
-BL33 is the non-secure world software (U-Boot, Linux etc).
-
-To build:
-```bash
-make ERROR_DEPRECATED=1 CROSS_COMPILE=aarch64-none-elf- PLAT=zynqmp bl31
-```
-
-To build bl32 TSP you have to rebuild bl31 too:
-```bash
-make ERROR_DEPRECATED=1 CROSS_COMPILE=aarch64-none-elf- PLAT=zynqmp SPD=tspd bl31 bl32
-```
-
-# ZynqMP platform specific build options
-* `ZYNQMP_ATF_MEM_BASE`: Specifies the base address of the bl31 binary.
-* `ZYNQMP_ATF_MEM_SIZE`: Specifies the size of the memory region of the bl31 binary.
-* `ZYNQMP_BL32_MEM_BASE`: Specifies the base address of the bl32 binary.
-* `ZYNQMP_BL32_MEM_SIZE`: Specifies the size of the memory region of the bl32 binary.
-
-* `ZYNQMP_CONSOLE`: Select the console driver. Options:
- - `cadence`, `cadence0`: Cadence UART 0
- - `cadence1` : Cadence UART 1
-
-# FSBL->ATF Parameter Passing
-The FSBL populates a data structure with image information for the ATF. The ATF
-uses that data to hand off to the loaded images. The address of the handoff data
-structure is passed in the ```PMU_GLOBAL.GLOBAL_GEN_STORAGE6``` register. The
-register is free to be used by other software once the ATF is bringing up
-further firmware images.
-
-# Power Domain Tree
-The following power domain tree represents the power domain model used by the
-ATF for ZynqMP:
-```
- +-+
- |0|
- +-+
- +-------+---+---+-------+
- | | | |
- | | | |
- v v v v
- +-+ +-+ +-+ +-+
- |0| |1| |2| |3|
- +-+ +-+ +-+ +-+
-```
-The 4 leaf power domains represent the individual A53 cores, while resources
-common to the cluster are grouped in the power domain on the top.
diff --git a/docs/plat/xilinx-zynqmp.rst b/docs/plat/xilinx-zynqmp.rst
new file mode 100644
index 0000000..b9c7825
--- /dev/null
+++ b/docs/plat/xilinx-zynqmp.rst
@@ -0,0 +1,67 @@
+ARM Trusted Firmware for Xilinx Zynq UltraScale+ MPSoC
+======================================================
+
+ARM Trusted Firmware implements the EL3 firmware layer for Xilinx Zynq
+UltraScale + MPSoC.
+The platform only uses the runtime part of ATF as ZynqMP already has a
+BootROM (BL1) and FSBL (BL2).
+
+BL31 is ATF.
+BL32 is an optional Secure Payload.
+BL33 is the non-secure world software (U-Boot, Linux etc).
+
+To build:
+
+.. code:: bash
+
+ make ERROR_DEPRECATED=1 CROSS_COMPILE=aarch64-none-elf- PLAT=zynqmp bl31
+
+To build bl32 TSP you have to rebuild bl31 too:
+
+.. code:: bash
+
+ make ERROR_DEPRECATED=1 CROSS_COMPILE=aarch64-none-elf- PLAT=zynqmp SPD=tspd bl31 bl32
+
+ZynqMP platform specific build options
+======================================
+
+- ``ZYNQMP_ATF_MEM_BASE``: Specifies the base address of the bl31 binary.
+- ``ZYNQMP_ATF_MEM_SIZE``: Specifies the size of the memory region of the bl31 binary.
+- ``ZYNQMP_BL32_MEM_BASE``: Specifies the base address of the bl32 binary.
+- ``ZYNQMP_BL32_MEM_SIZE``: Specifies the size of the memory region of the bl32 binary.
+
+- ``ZYNQMP_CONSOLE``: Select the console driver. Options:
+
+ - ``cadence``, ``cadence0``: Cadence UART 0
+ - ``cadence1`` : Cadence UART 1
+
+FSBL->ATF Parameter Passing
+===========================
+
+The FSBL populates a data structure with image information for the ATF. The ATF
+uses that data to hand off to the loaded images. The address of the handoff data
+structure is passed in the ``PMU_GLOBAL.GLOBAL_GEN_STORAGE6`` register. The
+register is free to be used by other software once the ATF is bringing up
+further firmware images.
+
+Power Domain Tree
+=================
+
+The following power domain tree represents the power domain model used by the
+ATF for ZynqMP:
+
+::
+
+ +-+
+ |0|
+ +-+
+ +-------+---+---+-------+
+ | | | |
+ | | | |
+ v v v v
+ +-+ +-+ +-+ +-+
+ |0| |1| |2| |3|
+ +-+ +-+ +-+ +-+
+
+The 4 leaf power domains represent the individual A53 cores, while resources
+common to the cluster are grouped in the power domain on the top.
diff --git a/docs/platform-migration-guide.md b/docs/platform-migration-guide.md
deleted file mode 100644
index 27cd067..0000000
--- a/docs/platform-migration-guide.md
+++ /dev/null
@@ -1,575 +0,0 @@
-Guide to migrate to new Platform porting interface
-==================================================
-
-Contents
---------
-
-1. [Introduction](#1--introduction)
-2. [Platform API modification due to PSCI framework changes](#2--platform-api-modification-due-to-psci-framework-changes)
- * [Power domain topology framework platform API modifications](#21-power-domain-topology-framework-platform-api-modifications)
- * [Composite power state framework platform API modifications](#22-composite-power-state-framework-platform-api-modifications)
- * [Miscellaneous modifications](#23-miscellaneous-modifications)
-3. [Compatibility layer](#3--compatibility-layer)
-4. [Deprecated Platform API](#4--deprecated-platform-api)
-
-- - - - - - - - - - - - - - - - - -
-
-
-1. Introduction
-----------------
-
-The PSCI implementation in Trusted Firmware has undergone a redesign because of
-three requirements that the PSCI 1.0 specification introduced :
-
-* Removing the framework assumption about the structure of the MPIDR, and
- its relation to the power topology enables support for deeper and more
- complex hierarchies.
-
-* Reworking the power state coordination implementation in the framework
- to support the more detailed PSCI 1.0 requirements and reduce platform
- port complexity
-
-* Enable the use of the extended power_state parameter and the larger StateID
- field
-
-The PSCI 1.0 implementation introduces new frameworks to fulfill the above
-requirements. These framework changes mean that the platform porting API must
-also be modified. This document is a guide to assist migration of the existing
-platform ports to the new platform API.
-
-This document describes the new platform API and compares it with the
-deprecated API. It also describes the compatibility layer that enables the
-existing platform ports to work with the PSCI 1.0 implementation. The
-deprecated platform API is documented for reference.
-
-
-2. Platform API modification due to PSCI framework changes
------------------------------------------------------------
-
-This section describes changes to the platform APIs.
-
-
-2.1 Power domain topology framework platform API modifications
---------------------------------------------------------------
-
-This removes the assumption in the PSCI implementation that MPIDR
-based affinity instances map directly to power domains. A power domain, as
-described in section 4.2 of [PSCI], could contain a core or a logical group
-of cores (a cluster) which share some state on which power management
-operations can be performed. The existing affinity instance based APIs
-`plat_get_aff_count()` and `plat_get_aff_state()` are deprecated. The new
-platform interfaces that are introduced for this framework are:
-
-* `plat_core_pos_by_mpidr()`
-* `plat_my_core_pos()`
-* `plat_get_power_domain_tree_desc()`
-
-`plat_my_core_pos()` and `plat_core_pos_by_mpidr()` are mandatory
-and are meant to replace the existing `platform_get_core_pos()` API.
-The description of these APIs can be found in the [Porting Guide][my_core_pos].
-These are used by the power domain topology framework such that:
-
-1. The generic PSCI code does not generate MPIDRs or use them to query the
- platform about the number of power domains at a particular power level. The
- `plat_get_power_domain_tree_desc()` provides a description of the power
- domain tree on the SoC through a pointer to the byte array containing the
- power domain topology tree description data structure.
-
-2. The linear indices returned by `plat_core_pos_by_mpidr()` and
- `plat_my_core_pos()` are used to retrieve core power domain nodes from
- the power domain tree. These core indices are unique for a core and it is a
- number between `0` and `PLATFORM_CORE_COUNT - 1`. The platform can choose
- to implement a static mapping between `MPIDR` and core index or implement
- a dynamic mapping, choosing to skip the unavailable/unused cores to compact
- the core indices.
-
-In addition, the platforms must define the macros `PLAT_NUM_PWR_DOMAINS` and
-`PLAT_MAX_PWR_LVL` which replace the macros `PLAT_NUM_AFFS` and
-`PLATFORM_MAX_AFFLVL` respectively. On platforms where the affinity instances
-correspond to power domains, the values of new macros remain the same as the
-old ones.
-
-More details on the power domain topology description and its platform
-interface can be found in [psci pd tree].
-
-
-2.2 Composite power state framework platform API modifications
---------------------------------------------------------------
-
-The state-ID field in the power-state parameter of a CPU_SUSPEND call can be
-used to describe the composite power states specific to a platform. The existing
-PSCI state coordination had the limitation that it operates on a run/off
-granularity of power states and it did not interpret the state-ID field. This
-was acceptable as the specification requirement in PSCI 0.2 and the framework's
-approach to coordination only required maintaining a reference
-count of the number of cores that have requested the cluster to remain powered.
-
-In the PSCI 1.0 specification, this approach is non optimal. If composite
-power states are used, the PSCI implementation cannot make global
-decisions about state coordination required because it does not understand the
-platform specific states.
-
-The PSCI 1.0 implementation now defines a generic representation of the
-power-state parameter :
-
- typedef struct psci_power_state {
- plat_local_state_t pwr_domain_state[PLAT_MAX_PWR_LVL + 1];
- } psci_power_state_t;
-
-
-`pwr_domain_state` is an array where each index corresponds to a power level.
-Each entry in the array contains the local power state the power domain at
-that power level could enter. The meaning of the local power state value is
-platform defined, and can vary between levels in a single platform. The PSCI
-implementation constraints the values only so that it can classify the state
-as RUN, RETENTION or OFF as required by the specification:
-
-1. Zero means RUN
-
-2. All OFF state values at all levels must be higher than all
- RETENTION state values at all levels
-
-The platform is required to define the macros `PLAT_MAX_RET_STATE` and
-`PLAT_MAX_OFF_STATE` to the framework. The requirement for these macros can
-be found in the [Porting Guide].
-
-The PSCI 1.0 implementation adds support to involve the platform in state
-coordination. This enables the platform to decide the final target state.
-During a request to place a power domain in a low power state, the platform
-is passed an array of requested `plat_local_state_t` for that power domain by
-each core within it through the `plat_get_target_pwr_state()` API. This API
-coordinates amongst these requested states to determine a target
-`plat_local_state_t` for that power domain. A default weak implementation of
-this API is provided in the platform layer which returns the minimum of the
-requested local states back to the PSCI state coordination. More details
-of `plat_get_target_pwr_state()` API can be found in the
-[Porting Guide][get_target_pwr_state].
-
-The PSCI Generic implementation expects platform ports to populate the handlers
-for the `plat_psci_ops` structure which is declared as :
-
- typedef struct plat_psci_ops {
- void (*cpu_standby)(plat_local_state_t cpu_state);
- int (*pwr_domain_on)(u_register_t mpidr);
- void (*pwr_domain_off)(const psci_power_state_t *target_state);
- void (*pwr_domain_suspend)(const psci_power_state_t *target_state);
- void (*pwr_domain_on_finish)(const psci_power_state_t *target_state);
- void (*pwr_domain_suspend_finish)(
- const psci_power_state_t *target_state);
- void (*system_off)(void) __dead2;
- void (*system_reset)(void) __dead2;
- int (*validate_power_state)(unsigned int power_state,
- psci_power_state_t *req_state);
- int (*validate_ns_entrypoint)(unsigned long ns_entrypoint);
- void (*get_sys_suspend_power_state)(
- psci_power_state_t *req_state);
- } plat_psci_ops_t;
-
-The description of these handlers can be found in the [Porting Guide][psci_ops].
-The previous `plat_pm_ops` structure is deprecated. Compared with the previous
-handlers, the major differences are:
-
-* Difference in parameters
-
-The PSCI 1.0 implementation depends on the `validate_power_state` handler to
-convert the power-state parameter (possibly encoding a composite power state)
-passed in a PSCI `CPU_SUSPEND` to the `psci_power_state` format. This handler
-is now mandatory for PSCI `CPU_SUSPEND` support.
-
-The `plat_psci_ops` handlers, `pwr_domain_off` and `pwr_domain_suspend`, are
-passed the target local state for each affected power domain. The platform
-must execute operations specific to these target states. Similarly,
-`pwr_domain_on_finish` and `pwr_domain_suspend_finish` are passed the local
-states of the affected power domains before wakeup. The platform
-must execute actions to restore these power domains from these specific
-local states.
-
-* Difference in invocation
-
-Whereas the power management handlers in `plat_pm_ops` used to be invoked
-for each affinity level till the target affinity level, the new handlers
-are only invoked once. The `target_state` encodes the target low power
-state or the low power state woken up from for each affected power domain.
-
-* Difference in semantics
-
-Although the previous `suspend` handlers could be used for power down as well
-as retention at different affinity levels, the new handlers make this support
-explicit. The `pwr_domain_suspend` can be used to specify powerdown and
-retention at various power domain levels subject to the conditions mentioned
-in section 4.2.1 of [PSCI]
-
-Unlike the previous `standby` handler, the `cpu_standby()` handler is only used
-as a fast path for placing a core power domain into a standby or retention
-state.
-
-The below diagram shows the sequence of a PSCI SUSPEND call and the interaction
-with the platform layer depicting the exchange of data between PSCI Generic
-layer and the platform layer.
-
-
-
-Refer [plat/arm/board/fvp/fvp_pm.c] for the implementation details of
-these handlers for the FVP. The commit 38dce70f51fb83b27958ba3e2ad15f5635cb1061
-demonstrates the migration of ARM reference platforms to the new platform API.
-
-
-2.3 Miscellaneous modifications
--------------------------------
-
-In addition to the framework changes, unification of warm reset entry points on
-wakeup from low power modes has led to a change in the platform API. In the
-earlier implementation, the warm reset entry used to be programmed into the
-mailboxes by the 'ON' and 'SUSPEND' power management hooks. In the PSCI 1.0
-implementation, this information is not required, because it can figure that
-out by querying affinity info state whether to execute the 'suspend_finisher`
-or 'on_finisher'.
-
-As a result, the warm reset entry point must be programmed only once. The
-`plat_setup_psci_ops()` API takes the secure entry point as an
-additional parameter to enable the platforms to configure their mailbox. The
-plat_psci_ops handlers `pwr_domain_on` and `pwr_domain_suspend` no longer take
-the warm reset entry point as a parameter.
-
-Also, some platform APIs which took `MPIDR` as an argument were only ever
-invoked to perform actions specific to the caller core which makes the argument
-redundant. Therefore the platform APIs `plat_get_my_entrypoint()`,
-`plat_is_my_cpu_primary()`, `plat_set_my_stack()` and
-`plat_get_my_stack()` are defined which are meant to be invoked only for
-operations on the current caller core instead of `platform_get_entrypoint()`,
-`platform_is_primary_cpu()`, `platform_set_stack()` and `platform_get_stack()`.
-
-
-3. Compatibility layer
-----------------------
-
-To ease the migration of the platform ports to the new porting interface,
-a compatibility layer is introduced that essentially implements a glue layer
-between the old platform API and the new API. The build flag
-`ENABLE_PLAT_COMPAT` (enabled by default), specifies whether to enable this
-layer or not. A platform port which has migrated to the new API can disable
-this flag within the platform specific makefile.
-
-The compatibility layer works on the assumption that the onus of
-state coordination, in case multiple low power states are supported,
-is with the platform. The generic PSCI implementation only takes into
-account whether the suspend request is power down or not. This corresponds
-with the behavior of the PSCI implementation before the introduction of
-new frameworks. Also, it assumes that the affinity levels of the platform
-correspond directly to the power domain levels.
-
-The compatibility layer dynamically constructs the new topology
-description array by querying the platform using `plat_get_aff_count()`
-and `plat_get_aff_state()` APIs. The linear index returned by
-`platform_get_core_pos()` is used as the core index for the cores. The
-higher level (non-core) power domain nodes must know the cores contained
-within its domain. It does so by storing the core index of first core
-within it and number of core indexes following it. This means that core
-indices returned by `platform_get_core_pos()` for cores within a particular
-power domain must be consecutive. We expect that this is the case for most
-platform ports including ARM reference platforms.
-
-The old PSCI helpers like `psci_get_suspend_powerstate()`,
-`psci_get_suspend_stateid()`, `psci_get_suspend_stateid_by_mpidr()`,
-`psci_get_max_phys_off_afflvl()` and `psci_get_suspend_afflvl()` are also
-implemented for the compatibility layer. This allows the existing
-platform ports to work with the new PSCI frameworks without significant
-rework.
-
-
-4. Deprecated Platform API
----------------------------
-
-This section documents the deprecated platform porting API.
-
-## Common mandatory modifications
-
-The mandatory macros to be defined by the platform port in `platform_def.h`
-
-* **#define : PLATFORM_NUM_AFFS**
-
- Defines the total number of nodes in the affinity hierarchy at all affinity
- levels used by the platform.
-
-* **#define : PLATFORM_MAX_AFFLVL**
-
- Defines the maximum affinity level that the power management operations
- should apply to. ARMv8-A has support for four affinity levels. It is likely
- that hardware will implement fewer affinity levels. This macro allows the
- PSCI implementation to consider only those affinity levels in the system
- that the platform implements. For example, the Base AEM FVP implements two
- clusters with a configurable number of cores. It reports the maximum
- affinity level as 1, resulting in PSCI power control up to the cluster
- level.
-
-The following functions must be implemented by the platform port to enable
-the reset vector code to perform the required tasks.
-
-### Function : platform_get_entrypoint() [mandatory]
-
- Argument : unsigned long
- Return : unsigned long
-
-This function is called with the `SCTLR.M` and `SCTLR.C` bits disabled. The core
-is identified by its `MPIDR`, which is passed as the argument. The function is
-responsible for distinguishing between a warm and cold reset using platform-
-specific means. If it is a warm reset, it returns the entrypoint into the
-BL31 image that the core must jump to. If it is a cold reset, this function
-must return zero.
-
-This function is also responsible for implementing a platform-specific mechanism
-to handle the condition where the core has been warm reset but there is no
-entrypoint to jump to.
-
-This function does not follow the Procedure Call Standard used by the
-Application Binary Interface for the ARM 64-bit architecture. The caller should
-not assume that callee saved registers are preserved across a call to this
-function.
-
-### Function : platform_is_primary_cpu() [mandatory]
-
- Argument : unsigned long
- Return : unsigned int
-
-This function identifies a core by its `MPIDR`, which is passed as the argument,
-to determine whether this core is the primary core or a secondary core. A return
-value of zero indicates that the core is not the primary core, while a non-zero
-return value indicates that the core is the primary core.
-
-## Common optional modifications
-
-### Function : platform_get_core_pos()
-
- Argument : unsigned long
- Return : int
-
-A platform may need to convert the `MPIDR` of a core to an absolute number, which
-can be used as a core-specific linear index into blocks of memory (for example
-while allocating per-core stacks). This routine contains a simple mechanism
-to perform this conversion, using the assumption that each cluster contains a
-maximum of four cores:
-
- linear index = cpu_id + (cluster_id * 4)
-
- cpu_id = 8-bit value in MPIDR at affinity level 0
- cluster_id = 8-bit value in MPIDR at affinity level 1
-
-
-### Function : platform_set_stack()
-
- Argument : unsigned long
- Return : void
-
-This function sets the current stack pointer to the normal memory stack that
-has been allocated for the core specified by MPIDR. For BL images that only
-require a stack for the primary core the parameter is ignored. The size of
-the stack allocated to each core is specified by the platform defined constant
-`PLATFORM_STACK_SIZE`.
-
-Common implementations of this function for the UP and MP BL images are
-provided in [plat/common/aarch64/platform_up_stack.S] and
-[plat/common/aarch64/platform_mp_stack.S]
-
-
-### Function : platform_get_stack()
-
- Argument : unsigned long
- Return : unsigned long
-
-This function returns the base address of the normal memory stack that
-has been allocated for the core specificed by MPIDR. For BL images that only
-require a stack for the primary core the parameter is ignored. The size of
-the stack allocated to each core is specified by the platform defined constant
-`PLATFORM_STACK_SIZE`.
-
-Common implementations of this function for the UP and MP BL images are
-provided in [plat/common/aarch64/platform_up_stack.S] and
-[plat/common/aarch64/platform_mp_stack.S]
-
-
-## Modifications for Power State Coordination Interface (in BL31)
-
-The following functions must be implemented to initialize PSCI functionality in
-the ARM Trusted Firmware.
-
-
-### Function : plat_get_aff_count() [mandatory]
-
- Argument : unsigned int, unsigned long
- Return : unsigned int
-
-This function may execute with the MMU and data caches enabled if the platform
-port does the necessary initializations in `bl31_plat_arch_setup()`. It is only
-called by the primary core.
-
-This function is called by the PSCI initialization code to detect the system
-topology. Its purpose is to return the number of affinity instances implemented
-at a given `affinity level` (specified by the first argument) and a given
-`MPIDR` (specified by the second argument). For example, on a dual-cluster
-system where first cluster implements two cores and the second cluster
-implements four cores, a call to this function with an `MPIDR` corresponding
-to the first cluster (`0x0`) and affinity level 0, would return 2. A call
-to this function with an `MPIDR` corresponding to the second cluster (`0x100`)
-and affinity level 0, would return 4.
-
-
-### Function : plat_get_aff_state() [mandatory]
-
- Argument : unsigned int, unsigned long
- Return : unsigned int
-
-This function may execute with the MMU and data caches enabled if the platform
-port does the necessary initializations in `bl31_plat_arch_setup()`. It is only
-called by the primary core.
-
-This function is called by the PSCI initialization code. Its purpose is to
-return the state of an affinity instance. The affinity instance is determined by
-the affinity ID at a given `affinity level` (specified by the first argument)
-and an `MPIDR` (specified by the second argument). The state can be one of
-`PSCI_AFF_PRESENT` or `PSCI_AFF_ABSENT`. The latter state is used to cater for
-system topologies where certain affinity instances are unimplemented. For
-example, consider a platform that implements a single cluster with four cores and
-another core implemented directly on the interconnect with the cluster. The
-`MPIDR`s of the cluster would range from `0x0-0x3`. The `MPIDR` of the single
-core is 0x100 to indicate that it does not belong to cluster 0. Cluster 1
-is missing but needs to be accounted for to reach this single core in the
-topology tree. Therefore it is marked as `PSCI_AFF_ABSENT`.
-
-
-### Function : platform_setup_pm() [mandatory]
-
- Argument : const plat_pm_ops **
- Return : int
-
-This function may execute with the MMU and data caches enabled if the platform
-port does the necessary initializations in `bl31_plat_arch_setup()`. It is only
-called by the primary core.
-
-This function is called by PSCI initialization code. Its purpose is to export
-handler routines for platform-specific power management actions by populating
-the passed pointer with a pointer to the private `plat_pm_ops` structure of
-BL31.
-
-A description of each member of this structure is given below. A platform port
-is expected to implement these handlers if the corresponding PSCI operation
-is to be supported and these handlers are expected to succeed if the return
-type is `void`.
-
-#### plat_pm_ops.affinst_standby()
-
-Perform the platform-specific setup to enter the standby state indicated by the
-passed argument. The generic code expects the handler to succeed.
-
-#### plat_pm_ops.affinst_on()
-
-Perform the platform specific setup to power on an affinity instance, specified
-by the `MPIDR` (first argument) and `affinity level` (third argument). The
-`state` (fourth argument) contains the current state of that affinity instance
-(ON or OFF). This is useful to determine whether any action must be taken. For
-example, while powering on a core, the cluster that contains this core might
-already be in the ON state. The platform decides what actions must be taken to
-transition from the current state to the target state (indicated by the power
-management operation). The generic code expects the platform to return
-E_SUCCESS on success or E_INTERN_FAIL for any failure.
-
-#### plat_pm_ops.affinst_off()
-
-Perform the platform specific setup to power off an affinity instance of the
-calling core. It is called by the PSCI `CPU_OFF` API implementation.
-
-The `affinity level` (first argument) and `state` (second argument) have
-a similar meaning as described in the `affinst_on()` operation. They
-identify the affinity instance on which the call is made and its
-current state. This gives the platform port an indication of the
-state transition it must make to perform the requested action. For example, if
-the calling core is the last powered on core in the cluster, after powering down
-affinity level 0 (the core), the platform port should power down affinity
-level 1 (the cluster) as well. The generic code expects the handler to succeed.
-
-#### plat_pm_ops.affinst_suspend()
-
-Perform the platform specific setup to power off an affinity instance of the
-calling core. It is called by the PSCI `CPU_SUSPEND` API and `SYSTEM_SUSPEND`
-API implementation
-
-The `affinity level` (second argument) and `state` (third argument) have a
-similar meaning as described in the `affinst_on()` operation. They are used to
-identify the affinity instance on which the call is made and its current state.
-This gives the platform port an indication of the state transition it must
-make to perform the requested action. For example, if the calling core is the
-last powered on core in the cluster, after powering down affinity level 0
-(the core), the platform port should power down affinity level 1 (the cluster)
-as well.
-
-The difference between turning an affinity instance off and suspending it
-is that in the former case, the affinity instance is expected to re-initialize
-its state when it is next powered on (see `affinst_on_finish()`). In the latter
-case, the affinity instance is expected to save enough state so that it can
-resume execution by restoring this state when it is powered on (see
-`affinst_suspend_finish()`).The generic code expects the handler to succeed.
-
-#### plat_pm_ops.affinst_on_finish()
-
-This function is called by the PSCI implementation after the calling core is
-powered on and released from reset in response to an earlier PSCI `CPU_ON` call.
-It performs the platform-specific setup required to initialize enough state for
-this core to enter the Normal world and also provide secure runtime firmware
-services.
-
-The `affinity level` (first argument) and `state` (second argument) have a
-similar meaning as described in the previous operations. The generic code
-expects the handler to succeed.
-
-#### plat_pm_ops.affinst_suspend_finish()
-
-This function is called by the PSCI implementation after the calling core is
-powered on and released from reset in response to an asynchronous wakeup
-event, for example a timer interrupt that was programmed by the core during the
-`CPU_SUSPEND` call or `SYSTEM_SUSPEND` call. It performs the platform-specific
-setup required to restore the saved state for this core to resume execution
-in the Normal world and also provide secure runtime firmware services.
-
-The `affinity level` (first argument) and `state` (second argument) have a
-similar meaning as described in the previous operations. The generic code
-expects the platform to succeed.
-
-#### plat_pm_ops.validate_power_state()
-
-This function is called by the PSCI implementation during the `CPU_SUSPEND`
-call to validate the `power_state` parameter of the PSCI API. If the
-`power_state` is known to be invalid, the platform must return
-PSCI_E_INVALID_PARAMS as an error, which is propagated back to the Normal
-world PSCI client.
-
-#### plat_pm_ops.validate_ns_entrypoint()
-
-This function is called by the PSCI implementation during the `CPU_SUSPEND`,
-`SYSTEM_SUSPEND` and `CPU_ON` calls to validate the Non-secure `entry_point`
-parameter passed by the Normal world. If the `entry_point` is known to be
-invalid, the platform must return PSCI_E_INVALID_PARAMS as an error, which is
-propagated back to the Normal world PSCI client.
-
-#### plat_pm_ops.get_sys_suspend_power_state()
-
-This function is called by the PSCI implementation during the `SYSTEM_SUSPEND`
-call to return the `power_state` parameter. This allows the platform to encode
-the appropriate State-ID field within the `power_state` parameter which can be
-utilized in `affinst_suspend()` to suspend to system affinity level. The
-`power_state` parameter should be in the same format as specified by the
-PSCI specification for the CPU_SUSPEND API.
-
-- - - - - - - - - - - - - - - - - - - - - - - - - -
-
-_Copyright (c) 2015, ARM Limited and Contributors. All rights reserved._
-
-
-[Porting Guide]: porting-guide.md
-[Power Domain Topology Design]: psci-pd-tree.md
-[PSCI]: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
-[psci pd tree]: psci-pd-tree.md
-[my_core_pos]: porting-guide.md#function--plat_my_core_pos
-[get_target_pwr_state]: porting-guide.md#function--plat_get_target_pwr_state-optional
-[psci_ops]: porting-guide.md#function--plat_setup_psci_ops-mandatory
-[plat/arm/board/fvp/fvp_pm.c]: ../plat/arm/board/fvp/fvp_pm.c
-[plat/common/aarch64/platform_mp_stack.S]: ../plat/common/aarch64/platform_mp_stack.S
-[plat/common/aarch64/platform_up_stack.S]: ../plat/common/aarch64/platform_up_stack.S
diff --git a/docs/platform-migration-guide.rst b/docs/platform-migration-guide.rst
new file mode 100644
index 0000000..5e8eeba
--- /dev/null
+++ b/docs/platform-migration-guide.rst
@@ -0,0 +1,596 @@
+Guide to migrate to new Platform porting interface
+==================================================
+
+
+.. section-numbering::
+ :suffix: .
+
+.. contents::
+
+--------------
+
+Introduction
+------------
+
+The PSCI implementation in Trusted Firmware has undergone a redesign because of
+three requirements that the PSCI 1.0 specification introduced :
+
+- Removing the framework assumption about the structure of the MPIDR, and
+ its relation to the power topology enables support for deeper and more
+ complex hierarchies.
+
+- Reworking the power state coordination implementation in the framework
+ to support the more detailed PSCI 1.0 requirements and reduce platform
+ port complexity
+
+- Enable the use of the extended power\_state parameter and the larger StateID
+ field
+
+The PSCI 1.0 implementation introduces new frameworks to fulfill the above
+requirements. These framework changes mean that the platform porting API must
+also be modified. This document is a guide to assist migration of the existing
+platform ports to the new platform API.
+
+This document describes the new platform API and compares it with the
+deprecated API. It also describes the compatibility layer that enables the
+existing platform ports to work with the PSCI 1.0 implementation. The
+deprecated platform API is documented for reference.
+
+Platform API modification due to PSCI framework changes
+-------------------------------------------------------
+
+This section describes changes to the platform APIs.
+
+Power domain topology framework platform API modifications
+----------------------------------------------------------
+
+This removes the assumption in the PSCI implementation that MPIDR
+based affinity instances map directly to power domains. A power domain, as
+described in section 4.2 of `PSCI`_, could contain a core or a logical group
+of cores (a cluster) which share some state on which power management
+operations can be performed. The existing affinity instance based APIs
+``plat_get_aff_count()`` and ``plat_get_aff_state()`` are deprecated. The new
+platform interfaces that are introduced for this framework are:
+
+- ``plat_core_pos_by_mpidr()``
+- ``plat_my_core_pos()``
+- ``plat_get_power_domain_tree_desc()``
+
+``plat_my_core_pos()`` and ``plat_core_pos_by_mpidr()`` are mandatory
+and are meant to replace the existing ``platform_get_core_pos()`` API.
+The description of these APIs can be found in the `Porting Guide`_.
+These are used by the power domain topology framework such that:
+
+#. The generic PSCI code does not generate MPIDRs or use them to query the
+ platform about the number of power domains at a particular power level. The
+ ``plat_get_power_domain_tree_desc()`` provides a description of the power
+ domain tree on the SoC through a pointer to the byte array containing the
+ power domain topology tree description data structure.
+
+#. The linear indices returned by ``plat_core_pos_by_mpidr()`` and
+ ``plat_my_core_pos()`` are used to retrieve core power domain nodes from
+ the power domain tree. These core indices are unique for a core and it is a
+ number between ``0`` and ``PLATFORM_CORE_COUNT - 1``. The platform can choose
+ to implement a static mapping between ``MPIDR`` and core index or implement
+ a dynamic mapping, choosing to skip the unavailable/unused cores to compact
+ the core indices.
+
+In addition, the platforms must define the macros ``PLAT_NUM_PWR_DOMAINS`` and
+``PLAT_MAX_PWR_LVL`` which replace the macros ``PLAT_NUM_AFFS`` and
+``PLATFORM_MAX_AFFLVL`` respectively. On platforms where the affinity instances
+correspond to power domains, the values of new macros remain the same as the
+old ones.
+
+More details on the power domain topology description and its platform
+interface can be found in `psci pd tree`_.
+
+Composite power state framework platform API modifications
+----------------------------------------------------------
+
+The state-ID field in the power-state parameter of a CPU\_SUSPEND call can be
+used to describe the composite power states specific to a platform. The existing
+PSCI state coordination had the limitation that it operates on a run/off
+granularity of power states and it did not interpret the state-ID field. This
+was acceptable as the specification requirement in PSCI 0.2 and the framework's
+approach to coordination only required maintaining a reference
+count of the number of cores that have requested the cluster to remain powered.
+
+In the PSCI 1.0 specification, this approach is non optimal. If composite
+power states are used, the PSCI implementation cannot make global
+decisions about state coordination required because it does not understand the
+platform specific states.
+
+The PSCI 1.0 implementation now defines a generic representation of the
+power-state parameter :
+
+.. code:: c
+
+ typedef struct psci_power_state {
+ plat_local_state_t pwr_domain_state[PLAT_MAX_PWR_LVL + 1];
+ } psci_power_state_t;
+
+``pwr_domain_state`` is an array where each index corresponds to a power level.
+Each entry in the array contains the local power state the power domain at
+that power level could enter. The meaning of the local power state value is
+platform defined, and can vary between levels in a single platform. The PSCI
+implementation constraints the values only so that it can classify the state
+as RUN, RETENTION or OFF as required by the specification:
+
+#. Zero means RUN
+
+#. All OFF state values at all levels must be higher than all
+ RETENTION state values at all levels
+
+The platform is required to define the macros ``PLAT_MAX_RET_STATE`` and
+``PLAT_MAX_OFF_STATE`` to the framework. The requirement for these macros can
+be found in the `Porting Guide <porting-guide.rst>`__.
+
+The PSCI 1.0 implementation adds support to involve the platform in state
+coordination. This enables the platform to decide the final target state.
+During a request to place a power domain in a low power state, the platform
+is passed an array of requested ``plat_local_state_t`` for that power domain by
+each core within it through the ``plat_get_target_pwr_state()`` API. This API
+coordinates amongst these requested states to determine a target
+``plat_local_state_t`` for that power domain. A default weak implementation of
+this API is provided in the platform layer which returns the minimum of the
+requested local states back to the PSCI state coordination. More details
+of ``plat_get_target_pwr_state()`` API can be found in the
+`Porting Guide <porting-guide.rst#user-content-function--plat_get_target_pwr_state-optional>`__.
+
+The PSCI Generic implementation expects platform ports to populate the handlers
+for the ``plat_psci_ops`` structure which is declared as :
+
+.. code:: c
+
+ typedef struct plat_psci_ops {
+ void (*cpu_standby)(plat_local_state_t cpu_state);
+ int (*pwr_domain_on)(u_register_t mpidr);
+ void (*pwr_domain_off)(const psci_power_state_t *target_state);
+ void (*pwr_domain_suspend)(const psci_power_state_t *target_state);
+ void (*pwr_domain_on_finish)(const psci_power_state_t *target_state);
+ void (*pwr_domain_suspend_finish)(
+ const psci_power_state_t *target_state);
+ void (*system_off)(void) __dead2;
+ void (*system_reset)(void) __dead2;
+ int (*validate_power_state)(unsigned int power_state,
+ psci_power_state_t *req_state);
+ int (*validate_ns_entrypoint)(unsigned long ns_entrypoint);
+ void (*get_sys_suspend_power_state)(
+ psci_power_state_t *req_state);
+ } plat_psci_ops_t;
+
+The description of these handlers can be found in the `Porting Guide <porting-guide.rst#user-content-function--plat_setup_psci_ops-mandatory>`__.
+The previous ``plat_pm_ops`` structure is deprecated. Compared with the previous
+handlers, the major differences are:
+
+- Difference in parameters
+
+The PSCI 1.0 implementation depends on the ``validate_power_state`` handler to
+convert the power-state parameter (possibly encoding a composite power state)
+passed in a PSCI ``CPU_SUSPEND`` to the ``psci_power_state`` format. This handler
+is now mandatory for PSCI ``CPU_SUSPEND`` support.
+
+The ``plat_psci_ops`` handlers, ``pwr_domain_off`` and ``pwr_domain_suspend``, are
+passed the target local state for each affected power domain. The platform
+must execute operations specific to these target states. Similarly,
+``pwr_domain_on_finish`` and ``pwr_domain_suspend_finish`` are passed the local
+states of the affected power domains before wakeup. The platform
+must execute actions to restore these power domains from these specific
+local states.
+
+- Difference in invocation
+
+Whereas the power management handlers in ``plat_pm_ops`` used to be invoked
+for each affinity level till the target affinity level, the new handlers
+are only invoked once. The ``target_state`` encodes the target low power
+state or the low power state woken up from for each affected power domain.
+
+- Difference in semantics
+
+Although the previous ``suspend`` handlers could be used for power down as well
+as retention at different affinity levels, the new handlers make this support
+explicit. The ``pwr_domain_suspend`` can be used to specify powerdown and
+retention at various power domain levels subject to the conditions mentioned
+in section 4.2.1 of `PSCI`_
+
+Unlike the previous ``standby`` handler, the ``cpu_standby()`` handler is only used
+as a fast path for placing a core power domain into a standby or retention
+state.
+
+The below diagram shows the sequence of a PSCI SUSPEND call and the interaction
+with the platform layer depicting the exchange of data between PSCI Generic
+layer and the platform layer.
+
+|Image 1|
+
+Refer `plat/arm/board/fvp/fvp\_pm.c`_ for the implementation details of
+these handlers for the FVP. The commit `38dce70f51fb83b27958ba3e2ad15f5635cb1061`_
+demonstrates the migration of ARM reference platforms to the new platform API.
+
+Miscellaneous modifications
+---------------------------
+
+In addition to the framework changes, unification of warm reset entry points on
+wakeup from low power modes has led to a change in the platform API. In the
+earlier implementation, the warm reset entry used to be programmed into the
+mailboxes by the 'ON' and 'SUSPEND' power management hooks. In the PSCI 1.0
+implementation, this information is not required, because it can figure that
+out by querying affinity info state whether to execute the 'suspend\_finisher\`
+or 'on\_finisher'.
+
+As a result, the warm reset entry point must be programmed only once. The
+``plat_setup_psci_ops()`` API takes the secure entry point as an
+additional parameter to enable the platforms to configure their mailbox. The
+plat\_psci\_ops handlers ``pwr_domain_on`` and ``pwr_domain_suspend`` no longer take
+the warm reset entry point as a parameter.
+
+Also, some platform APIs which took ``MPIDR`` as an argument were only ever
+invoked to perform actions specific to the caller core which makes the argument
+redundant. Therefore the platform APIs ``plat_get_my_entrypoint()``,
+``plat_is_my_cpu_primary()``, ``plat_set_my_stack()`` and
+``plat_get_my_stack()`` are defined which are meant to be invoked only for
+operations on the current caller core instead of ``platform_get_entrypoint()``,
+``platform_is_primary_cpu()``, ``platform_set_stack()`` and ``platform_get_stack()``.
+
+Compatibility layer
+-------------------
+
+To ease the migration of the platform ports to the new porting interface,
+a compatibility layer is introduced that essentially implements a glue layer
+between the old platform API and the new API. The build flag
+``ENABLE_PLAT_COMPAT`` (enabled by default), specifies whether to enable this
+layer or not. A platform port which has migrated to the new API can disable
+this flag within the platform specific makefile.
+
+The compatibility layer works on the assumption that the onus of
+state coordination, in case multiple low power states are supported,
+is with the platform. The generic PSCI implementation only takes into
+account whether the suspend request is power down or not. This corresponds
+with the behavior of the PSCI implementation before the introduction of
+new frameworks. Also, it assumes that the affinity levels of the platform
+correspond directly to the power domain levels.
+
+The compatibility layer dynamically constructs the new topology
+description array by querying the platform using ``plat_get_aff_count()``
+and ``plat_get_aff_state()`` APIs. The linear index returned by
+``platform_get_core_pos()`` is used as the core index for the cores. The
+higher level (non-core) power domain nodes must know the cores contained
+within its domain. It does so by storing the core index of first core
+within it and number of core indexes following it. This means that core
+indices returned by ``platform_get_core_pos()`` for cores within a particular
+power domain must be consecutive. We expect that this is the case for most
+platform ports including ARM reference platforms.
+
+The old PSCI helpers like ``psci_get_suspend_powerstate()``,
+``psci_get_suspend_stateid()``, ``psci_get_suspend_stateid_by_mpidr()``,
+``psci_get_max_phys_off_afflvl()`` and ``psci_get_suspend_afflvl()`` are also
+implemented for the compatibility layer. This allows the existing
+platform ports to work with the new PSCI frameworks without significant
+rework.
+
+Deprecated Platform API
+-----------------------
+
+This section documents the deprecated platform porting API.
+
+Common mandatory modifications
+------------------------------
+
+The mandatory macros to be defined by the platform port in ``platform_def.h``
+
+- **#define : PLATFORM\_NUM\_AFFS**
+
+ Defines the total number of nodes in the affinity hierarchy at all affinity
+ levels used by the platform.
+
+- **#define : PLATFORM\_MAX\_AFFLVL**
+
+ Defines the maximum affinity level that the power management operations
+ should apply to. ARMv8-A has support for four affinity levels. It is likely
+ that hardware will implement fewer affinity levels. This macro allows the
+ PSCI implementation to consider only those affinity levels in the system
+ that the platform implements. For example, the Base AEM FVP implements two
+ clusters with a configurable number of cores. It reports the maximum
+ affinity level as 1, resulting in PSCI power control up to the cluster
+ level.
+
+The following functions must be implemented by the platform port to enable
+the reset vector code to perform the required tasks.
+
+Function : platform\_get\_entrypoint() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : unsigned long
+ Return : unsigned long
+
+This function is called with the ``SCTLR.M`` and ``SCTLR.C`` bits disabled. The core
+is identified by its ``MPIDR``, which is passed as the argument. The function is
+responsible for distinguishing between a warm and cold reset using platform-
+specific means. If it is a warm reset, it returns the entrypoint into the
+BL31 image that the core must jump to. If it is a cold reset, this function
+must return zero.
+
+This function is also responsible for implementing a platform-specific mechanism
+to handle the condition where the core has been warm reset but there is no
+entrypoint to jump to.
+
+This function does not follow the Procedure Call Standard used by the
+Application Binary Interface for the ARM 64-bit architecture. The caller should
+not assume that callee saved registers are preserved across a call to this
+function.
+
+Function : platform\_is\_primary\_cpu() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : unsigned long
+ Return : unsigned int
+
+This function identifies a core by its ``MPIDR``, which is passed as the argument,
+to determine whether this core is the primary core or a secondary core. A return
+value of zero indicates that the core is not the primary core, while a non-zero
+return value indicates that the core is the primary core.
+
+Common optional modifications
+-----------------------------
+
+Function : platform\_get\_core\_pos()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : unsigned long
+ Return : int
+
+A platform may need to convert the ``MPIDR`` of a core to an absolute number, which
+can be used as a core-specific linear index into blocks of memory (for example
+while allocating per-core stacks). This routine contains a simple mechanism
+to perform this conversion, using the assumption that each cluster contains a
+maximum of four cores:
+
+::
+
+ linear index = cpu_id + (cluster_id * 4)
+
+ cpu_id = 8-bit value in MPIDR at affinity level 0
+ cluster_id = 8-bit value in MPIDR at affinity level 1
+
+Function : platform\_set\_stack()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : unsigned long
+ Return : void
+
+This function sets the current stack pointer to the normal memory stack that
+has been allocated for the core specified by MPIDR. For BL images that only
+require a stack for the primary core the parameter is ignored. The size of
+the stack allocated to each core is specified by the platform defined constant
+``PLATFORM_STACK_SIZE``.
+
+Common implementations of this function for the UP and MP BL images are
+provided in `plat/common/aarch64/platform\_up\_stack.S`_ and
+`plat/common/aarch64/platform\_mp\_stack.S`_
+
+Function : platform\_get\_stack()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : unsigned long
+ Return : unsigned long
+
+This function returns the base address of the normal memory stack that
+has been allocated for the core specificed by MPIDR. For BL images that only
+require a stack for the primary core the parameter is ignored. The size of
+the stack allocated to each core is specified by the platform defined constant
+``PLATFORM_STACK_SIZE``.
+
+Common implementations of this function for the UP and MP BL images are
+provided in `plat/common/aarch64/platform\_up\_stack.S`_ and
+`plat/common/aarch64/platform\_mp\_stack.S`_
+
+Modifications for Power State Coordination Interface (in BL31)
+--------------------------------------------------------------
+
+The following functions must be implemented to initialize PSCI functionality in
+the ARM Trusted Firmware.
+
+Function : plat\_get\_aff\_count() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : unsigned int, unsigned long
+ Return : unsigned int
+
+This function may execute with the MMU and data caches enabled if the platform
+port does the necessary initializations in ``bl31_plat_arch_setup()``. It is only
+called by the primary core.
+
+This function is called by the PSCI initialization code to detect the system
+topology. Its purpose is to return the number of affinity instances implemented
+at a given ``affinity level`` (specified by the first argument) and a given
+``MPIDR`` (specified by the second argument). For example, on a dual-cluster
+system where first cluster implements two cores and the second cluster
+implements four cores, a call to this function with an ``MPIDR`` corresponding
+to the first cluster (``0x0``) and affinity level 0, would return 2. A call
+to this function with an ``MPIDR`` corresponding to the second cluster (``0x100``)
+and affinity level 0, would return 4.
+
+Function : plat\_get\_aff\_state() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : unsigned int, unsigned long
+ Return : unsigned int
+
+This function may execute with the MMU and data caches enabled if the platform
+port does the necessary initializations in ``bl31_plat_arch_setup()``. It is only
+called by the primary core.
+
+This function is called by the PSCI initialization code. Its purpose is to
+return the state of an affinity instance. The affinity instance is determined by
+the affinity ID at a given ``affinity level`` (specified by the first argument)
+and an ``MPIDR`` (specified by the second argument). The state can be one of
+``PSCI_AFF_PRESENT`` or ``PSCI_AFF_ABSENT``. The latter state is used to cater for
+system topologies where certain affinity instances are unimplemented. For
+example, consider a platform that implements a single cluster with four cores and
+another core implemented directly on the interconnect with the cluster. The
+``MPIDR``\ s of the cluster would range from ``0x0-0x3``. The ``MPIDR`` of the single
+core is 0x100 to indicate that it does not belong to cluster 0. Cluster 1
+is missing but needs to be accounted for to reach this single core in the
+topology tree. Therefore it is marked as ``PSCI_AFF_ABSENT``.
+
+Function : platform\_setup\_pm() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : const plat_pm_ops **
+ Return : int
+
+This function may execute with the MMU and data caches enabled if the platform
+port does the necessary initializations in ``bl31_plat_arch_setup()``. It is only
+called by the primary core.
+
+This function is called by PSCI initialization code. Its purpose is to export
+handler routines for platform-specific power management actions by populating
+the passed pointer with a pointer to the private ``plat_pm_ops`` structure of
+BL31.
+
+A description of each member of this structure is given below. A platform port
+is expected to implement these handlers if the corresponding PSCI operation
+is to be supported and these handlers are expected to succeed if the return
+type is ``void``.
+
+plat\_pm\_ops.affinst\_standby()
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Perform the platform-specific setup to enter the standby state indicated by the
+passed argument. The generic code expects the handler to succeed.
+
+plat\_pm\_ops.affinst\_on()
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Perform the platform specific setup to power on an affinity instance, specified
+by the ``MPIDR`` (first argument) and ``affinity level`` (third argument). The
+``state`` (fourth argument) contains the current state of that affinity instance
+(ON or OFF). This is useful to determine whether any action must be taken. For
+example, while powering on a core, the cluster that contains this core might
+already be in the ON state. The platform decides what actions must be taken to
+transition from the current state to the target state (indicated by the power
+management operation). The generic code expects the platform to return
+E\_SUCCESS on success or E\_INTERN\_FAIL for any failure.
+
+plat\_pm\_ops.affinst\_off()
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Perform the platform specific setup to power off an affinity instance of the
+calling core. It is called by the PSCI ``CPU_OFF`` API implementation.
+
+The ``affinity level`` (first argument) and ``state`` (second argument) have
+a similar meaning as described in the ``affinst_on()`` operation. They
+identify the affinity instance on which the call is made and its
+current state. This gives the platform port an indication of the
+state transition it must make to perform the requested action. For example, if
+the calling core is the last powered on core in the cluster, after powering down
+affinity level 0 (the core), the platform port should power down affinity
+level 1 (the cluster) as well. The generic code expects the handler to succeed.
+
+plat\_pm\_ops.affinst\_suspend()
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Perform the platform specific setup to power off an affinity instance of the
+calling core. It is called by the PSCI ``CPU_SUSPEND`` API and ``SYSTEM_SUSPEND``
+API implementation
+
+The ``affinity level`` (second argument) and ``state`` (third argument) have a
+similar meaning as described in the ``affinst_on()`` operation. They are used to
+identify the affinity instance on which the call is made and its current state.
+This gives the platform port an indication of the state transition it must
+make to perform the requested action. For example, if the calling core is the
+last powered on core in the cluster, after powering down affinity level 0
+(the core), the platform port should power down affinity level 1 (the cluster)
+as well.
+
+The difference between turning an affinity instance off and suspending it
+is that in the former case, the affinity instance is expected to re-initialize
+its state when it is next powered on (see ``affinst_on_finish()``). In the latter
+case, the affinity instance is expected to save enough state so that it can
+resume execution by restoring this state when it is powered on (see
+``affinst_suspend_finish()``).The generic code expects the handler to succeed.
+
+plat\_pm\_ops.affinst\_on\_finish()
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function is called by the PSCI implementation after the calling core is
+powered on and released from reset in response to an earlier PSCI ``CPU_ON`` call.
+It performs the platform-specific setup required to initialize enough state for
+this core to enter the Normal world and also provide secure runtime firmware
+services.
+
+The ``affinity level`` (first argument) and ``state`` (second argument) have a
+similar meaning as described in the previous operations. The generic code
+expects the handler to succeed.
+
+plat\_pm\_ops.affinst\_suspend\_finish()
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function is called by the PSCI implementation after the calling core is
+powered on and released from reset in response to an asynchronous wakeup
+event, for example a timer interrupt that was programmed by the core during the
+``CPU_SUSPEND`` call or ``SYSTEM_SUSPEND`` call. It performs the platform-specific
+setup required to restore the saved state for this core to resume execution
+in the Normal world and also provide secure runtime firmware services.
+
+The ``affinity level`` (first argument) and ``state`` (second argument) have a
+similar meaning as described in the previous operations. The generic code
+expects the platform to succeed.
+
+plat\_pm\_ops.validate\_power\_state()
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function is called by the PSCI implementation during the ``CPU_SUSPEND``
+call to validate the ``power_state`` parameter of the PSCI API. If the
+``power_state`` is known to be invalid, the platform must return
+PSCI\_E\_INVALID\_PARAMS as an error, which is propagated back to the Normal
+world PSCI client.
+
+plat\_pm\_ops.validate\_ns\_entrypoint()
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function is called by the PSCI implementation during the ``CPU_SUSPEND``,
+``SYSTEM_SUSPEND`` and ``CPU_ON`` calls to validate the Non-secure ``entry_point``
+parameter passed by the Normal world. If the ``entry_point`` is known to be
+invalid, the platform must return PSCI\_E\_INVALID\_PARAMS as an error, which is
+propagated back to the Normal world PSCI client.
+
+plat\_pm\_ops.get\_sys\_suspend\_power\_state()
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function is called by the PSCI implementation during the ``SYSTEM_SUSPEND``
+call to return the ``power_state`` parameter. This allows the platform to encode
+the appropriate State-ID field within the ``power_state`` parameter which can be
+utilized in ``affinst_suspend()`` to suspend to system affinity level. The
+``power_state`` parameter should be in the same format as specified by the
+PSCI specification for the CPU\_SUSPEND API.
+
+--------------
+
+*Copyright (c) 2015, ARM Limited and Contributors. All rights reserved.*
+
+.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
+.. _Porting Guide: porting-guide.rst#user-content-function--plat_my_core_pos
+.. _psci pd tree: psci-pd-tree.rst
+.. _plat/arm/board/fvp/fvp\_pm.c: ../plat/arm/board/fvp/fvp_pm.c
+.. _38dce70f51fb83b27958ba3e2ad15f5635cb1061: https://github.com/ARM-software/arm-trusted-firmware/commit/38dce70f51fb83b27958ba3e2ad15f5635cb1061
+.. _plat/common/aarch64/platform\_up\_stack.S: ../plat/common/aarch64/platform_up_stack.S
+.. _plat/common/aarch64/platform\_mp\_stack.S: ../plat/common/aarch64/platform_mp_stack.S
+
+.. |Image 1| image:: diagrams/psci-suspend-sequence.png?raw=true
diff --git a/docs/porting-guide.md b/docs/porting-guide.md
deleted file mode 100644
index 047e225..0000000
--- a/docs/porting-guide.md
+++ /dev/null
@@ -1,2413 +0,0 @@
-ARM Trusted Firmware Porting Guide
-==================================
-
-Contents
---------
-
-1. [Introduction](#1--introduction)
-2. [Common Modifications](#2--common-modifications)
- * [Common mandatory modifications](#21-common-mandatory-modifications)
- * [Handling reset](#22-handling-reset)
- * [Common mandatory function modifications](#23-common-mandatory-function-modifications)
- * [Common optional modifications](#24-common-optional-modifications)
-3. [Boot Loader stage specific modifications](#3--modifications-specific-to-a-boot-loader-stage)
- * [Boot Loader stage 1 (BL1)](#31-boot-loader-stage-1-bl1)
- * [Boot Loader stage 2 (BL2)](#32-boot-loader-stage-2-bl2)
- * [FWU Boot Loader stage 2 (BL2U)](#33-fwu-boot-loader-stage-2-bl2u)
- * [Boot Loader stage 3-1 (BL31)](#34-boot-loader-stage-3-1-bl31)
- * [PSCI implementation (in BL31)](#35-power-state-coordination-interface-in-bl31)
- * [Interrupt Management framework (in BL31)](#36--interrupt-management-framework-in-bl31)
- * [Crash Reporting mechanism (in BL31)](#37--crash-reporting-mechanism-in-bl31)
-4. [Build flags](#4--build-flags)
-5. [C Library](#5--c-library)
-6. [Storage abstraction layer](#6--storage-abstraction-layer)
-
-- - - - - - - - - - - - - - - - - -
-
-1. Introduction
-----------------
-
-Please note that this document has been updated for the new platform API
-as required by the PSCI v1.0 implementation. Please refer to the
-[Migration Guide] for the previous platform API.
-
-Porting the ARM Trusted Firmware to a new platform involves making some
-mandatory and optional modifications for both the cold and warm boot paths.
-Modifications consist of:
-
-* Implementing a platform-specific function or variable,
-* Setting up the execution context in a certain way, or
-* Defining certain constants (for example #defines).
-
-The platform-specific functions and variables are declared in
-[include/plat/common/platform.h]. The firmware provides a default implementation
-of variables and functions to fulfill the optional requirements. These
-implementations are all weakly defined; they are provided to ease the porting
-effort. Each platform port can override them with its own implementation if the
-default implementation is inadequate.
-
-Platform ports that want to be aligned with standard ARM platforms (for example
-FVP and Juno) may also use [include/plat/arm/common/plat_arm.h] and the
-corresponding source files in `plat/arm/common/`. These provide standard
-implementations for some of the required platform porting functions. However,
-using these functions requires the platform port to implement additional
-ARM standard platform porting functions. These additional functions are not
-documented here.
-
-Some modifications are common to all Boot Loader (BL) stages. Section 2
-discusses these in detail. The subsequent sections discuss the remaining
-modifications for each BL stage in detail.
-
-This document should be read in conjunction with the ARM Trusted Firmware
-[User Guide].
-
-
-2. Common modifications
-------------------------
-
-This section covers the modifications that should be made by the platform for
-each BL stage to correctly port the firmware stack. They are categorized as
-either mandatory or optional.
-
-
-2.1 Common mandatory modifications
-----------------------------------
-
-A platform port must enable the Memory Management Unit (MMU) as well as the
-instruction and data caches for each BL stage. Setting up the translation
-tables is the responsibility of the platform port because memory maps differ
-across platforms. A memory translation library (see `lib/xlat_tables/`) is
-provided to help in this setup. Note that although this library supports
-non-identity mappings, this is intended only for re-mapping peripheral physical
-addresses and allows platforms with high I/O addresses to reduce their virtual
-address space. All other addresses corresponding to code and data must currently
-use an identity mapping.
-
-In ARM standard platforms, each BL stage configures the MMU in the
-platform-specific architecture setup function, `blX_plat_arch_setup()`, and uses
-an identity mapping for all addresses.
-
-If the build option `USE_COHERENT_MEM` is enabled, each platform can allocate a
-block of identity mapped secure memory with Device-nGnRE attributes aligned to
-page boundary (4K) for each BL stage. All sections which allocate coherent
-memory are grouped under `coherent_ram`. For ex: Bakery locks are placed in a
-section identified by name `bakery_lock` inside `coherent_ram` so that its
-possible for the firmware to place variables in it using the following C code
-directive:
-
- __section("bakery_lock")
-
-Or alternatively the following assembler code directive:
-
- .section bakery_lock
-
-The `coherent_ram` section is a sum of all sections like `bakery_lock` which are
-used to allocate any data structures that are accessed both when a CPU is
-executing with its MMU and caches enabled, and when it's running with its MMU
-and caches disabled. Examples are given below.
-
-The following variables, functions and constants must be defined by the platform
-for the firmware to work correctly.
-
-
-### File : platform_def.h [mandatory]
-
-Each platform must ensure that a header file of this name is in the system
-include path with the following constants defined. This may require updating the
-list of `PLAT_INCLUDES` in the `platform.mk` file. In the ARM development
-platforms, this file is found in `plat/arm/board/<plat_name>/include/`.
-
-Platform ports may optionally use the file [include/plat/common/common_def.h],
-which provides typical values for some of the constants below. These values are
-likely to be suitable for all platform ports.
-
-Platform ports that want to be aligned with standard ARM platforms (for example
-FVP and Juno) may also use [include/plat/arm/common/arm_def.h], which provides
-standard values for some of the constants below. However, this requires the
-platform port to define additional platform porting constants in
-`platform_def.h`. These additional constants are not documented here.
-
-* **#define : PLATFORM_LINKER_FORMAT**
-
- Defines the linker format used by the platform, for example
- `elf64-littleaarch64`.
-
-* **#define : PLATFORM_LINKER_ARCH**
-
- Defines the processor architecture for the linker by the platform, for
- example `aarch64`.
-
-* **#define : PLATFORM_STACK_SIZE**
-
- Defines the normal stack memory available to each CPU. This constant is used
- by [plat/common/aarch64/platform_mp_stack.S] and
- [plat/common/aarch64/platform_up_stack.S].
-
-* **define : CACHE_WRITEBACK_GRANULE**
-
- Defines the size in bits of the largest cache line across all the cache
- levels in the platform.
-
-* **#define : FIRMWARE_WELCOME_STR**
-
- Defines the character string printed by BL1 upon entry into the `bl1_main()`
- function.
-
-* **#define : PLATFORM_CORE_COUNT**
-
- Defines the total number of CPUs implemented by the platform across all
- clusters in the system.
-
-* **#define : PLAT_NUM_PWR_DOMAINS**
-
- Defines the total number of nodes in the power domain topology
- tree at all the power domain levels used by the platform.
- This macro is used by the PSCI implementation to allocate
- data structures to represent power domain topology.
-
-* **#define : PLAT_MAX_PWR_LVL**
-
- Defines the maximum power domain level that the power management operations
- should apply to. More often, but not always, the power domain level
- corresponds to affinity level. This macro allows the PSCI implementation
- to know the highest power domain level that it should consider for power
- management operations in the system that the platform implements. For
- example, the Base AEM FVP implements two clusters with a configurable
- number of CPUs and it reports the maximum power domain level as 1.
-
-* **#define : PLAT_MAX_OFF_STATE**
-
- Defines the local power state corresponding to the deepest power down
- possible at every power domain level in the platform. The local power
- states for each level may be sparsely allocated between 0 and this value
- with 0 being reserved for the RUN state. The PSCI implementation uses this
- value to initialize the local power states of the power domain nodes and
- to specify the requested power state for a PSCI_CPU_OFF call.
-
-* **#define : PLAT_MAX_RET_STATE**
-
- Defines the local power state corresponding to the deepest retention state
- possible at every power domain level in the platform. This macro should be
- a value less than PLAT_MAX_OFF_STATE and greater than 0. It is used by the
- PSCI implementation to distinguish between retention and power down local
- power states within PSCI_CPU_SUSPEND call.
-
-* **#define : PLAT_MAX_PWR_LVL_STATES**
-
- Defines the maximum number of local power states per power domain level
- that the platform supports. The default value of this macro is 2 since
- most platforms just support a maximum of two local power states at each
- power domain level (power-down and retention). If the platform needs to
- account for more local power states, then it must redefine this macro.
-
- Currently, this macro is used by the Generic PSCI implementation to size
- the array used for PSCI_STAT_COUNT/RESIDENCY accounting.
-
-* **#define : BL1_RO_BASE**
-
- Defines the base address in secure ROM where BL1 originally lives. Must be
- aligned on a page-size boundary.
-
-* **#define : BL1_RO_LIMIT**
-
- Defines the maximum address in secure ROM that BL1's actual content (i.e.
- excluding any data section allocated at runtime) can occupy.
-
-* **#define : BL1_RW_BASE**
-
- Defines the base address in secure RAM where BL1's read-write data will live
- at runtime. Must be aligned on a page-size boundary.
-
-* **#define : BL1_RW_LIMIT**
-
- Defines the maximum address in secure RAM that BL1's read-write data can
- occupy at runtime.
-
-* **#define : BL2_BASE**
-
- Defines the base address in secure RAM where BL1 loads the BL2 binary image.
- Must be aligned on a page-size boundary.
-
-* **#define : BL2_LIMIT**
-
- Defines the maximum address in secure RAM that the BL2 image can occupy.
-
-* **#define : BL31_BASE**
-
- Defines the base address in secure RAM where BL2 loads the BL31 binary
- image. Must be aligned on a page-size boundary.
-
-* **#define : BL31_LIMIT**
-
- Defines the maximum address in secure RAM that the BL31 image can occupy.
-
-For every image, the platform must define individual identifiers that will be
-used by BL1 or BL2 to load the corresponding image into memory from non-volatile
-storage. For the sake of performance, integer numbers will be used as
-identifiers. The platform will use those identifiers to return the relevant
-information about the image to be loaded (file handler, load address,
-authentication information, etc.). The following image identifiers are
-mandatory:
-
-* **#define : BL2_IMAGE_ID**
-
- BL2 image identifier, used by BL1 to load BL2.
-
-* **#define : BL31_IMAGE_ID**
-
- BL31 image identifier, used by BL2 to load BL31.
-
-* **#define : BL33_IMAGE_ID**
-
- BL33 image identifier, used by BL2 to load BL33.
-
-If Trusted Board Boot is enabled, the following certificate identifiers must
-also be defined:
-
-* **#define : TRUSTED_BOOT_FW_CERT_ID**
-
- BL2 content certificate identifier, used by BL1 to load the BL2 content
- certificate.
-
-* **#define : TRUSTED_KEY_CERT_ID**
-
- Trusted key certificate identifier, used by BL2 to load the trusted key
- certificate.
-
-* **#define : SOC_FW_KEY_CERT_ID**
-
- BL31 key certificate identifier, used by BL2 to load the BL31 key
- certificate.
-
-* **#define : SOC_FW_CONTENT_CERT_ID**
-
- BL31 content certificate identifier, used by BL2 to load the BL31 content
- certificate.
-
-* **#define : NON_TRUSTED_FW_KEY_CERT_ID**
-
- BL33 key certificate identifier, used by BL2 to load the BL33 key
- certificate.
-
-* **#define : NON_TRUSTED_FW_CONTENT_CERT_ID**
-
- BL33 content certificate identifier, used by BL2 to load the BL33 content
- certificate.
-
-* **#define : FWU_CERT_ID**
-
- Firmware Update (FWU) certificate identifier, used by NS_BL1U to load the
- FWU content certificate.
-
-* **#define : PLAT_CRYPTOCELL_BASE**
-
- This defines the base address of ARM® TrustZone® CryptoCell and must be
- defined if CryptoCell crypto driver is used for Trusted Board Boot. For
- capable ARM platforms, this driver is used if `ARM_CRYPTOCELL_INTEG` is
- set.
-
-If the AP Firmware Updater Configuration image, BL2U is used, the following
-must also be defined:
-
-* **#define : BL2U_BASE**
-
- Defines the base address in secure memory where BL1 copies the BL2U binary
- image. Must be aligned on a page-size boundary.
-
-* **#define : BL2U_LIMIT**
-
- Defines the maximum address in secure memory that the BL2U image can occupy.
-
-* **#define : BL2U_IMAGE_ID**
-
- BL2U image identifier, used by BL1 to fetch an image descriptor
- corresponding to BL2U.
-
-If the SCP Firmware Update Configuration Image, SCP_BL2U is used, the following
-must also be defined:
-
-* **#define : SCP_BL2U_IMAGE_ID**
-
- SCP_BL2U image identifier, used by BL1 to fetch an image descriptor
- corresponding to SCP_BL2U.
- NOTE: TF does not provide source code for this image.
-
-If the Non-Secure Firmware Updater ROM, NS_BL1U is used, the following must
-also be defined:
-
-* **#define : NS_BL1U_BASE**
-
- Defines the base address in non-secure ROM where NS_BL1U executes.
- Must be aligned on a page-size boundary.
- NOTE: TF does not provide source code for this image.
-
-* **#define : NS_BL1U_IMAGE_ID**
-
- NS_BL1U image identifier, used by BL1 to fetch an image descriptor
- corresponding to NS_BL1U.
-
-If the Non-Secure Firmware Updater, NS_BL2U is used, the following must also
-be defined:
-
-* **#define : NS_BL2U_BASE**
-
- Defines the base address in non-secure memory where NS_BL2U executes.
- Must be aligned on a page-size boundary.
- NOTE: TF does not provide source code for this image.
-
-* **#define : NS_BL2U_IMAGE_ID**
-
- NS_BL2U image identifier, used by BL1 to fetch an image descriptor
- corresponding to NS_BL2U.
-
-For the the Firmware update capability of TRUSTED BOARD BOOT, the following
-macros may also be defined:
-
-* **#define : PLAT_FWU_MAX_SIMULTANEOUS_IMAGES**
-
- Total number of images that can be loaded simultaneously. If the platform
- doesn't specify any value, it defaults to 10.
-
-If a SCP_BL2 image is supported by the platform, the following constants must
-also be defined:
-
-* **#define : SCP_BL2_IMAGE_ID**
-
- SCP_BL2 image identifier, used by BL2 to load SCP_BL2 into secure memory
- from platform storage before being transfered to the SCP.
-
-* **#define : SCP_FW_KEY_CERT_ID**
-
- SCP_BL2 key certificate identifier, used by BL2 to load the SCP_BL2 key
- certificate (mandatory when Trusted Board Boot is enabled).
-
-* **#define : SCP_FW_CONTENT_CERT_ID**
-
- SCP_BL2 content certificate identifier, used by BL2 to load the SCP_BL2
- content certificate (mandatory when Trusted Board Boot is enabled).
-
-If a BL32 image is supported by the platform, the following constants must
-also be defined:
-
-* **#define : BL32_IMAGE_ID**
-
- BL32 image identifier, used by BL2 to load BL32.
-
-* **#define : TRUSTED_OS_FW_KEY_CERT_ID**
-
- BL32 key certificate identifier, used by BL2 to load the BL32 key
- certificate (mandatory when Trusted Board Boot is enabled).
-
-* **#define : TRUSTED_OS_FW_CONTENT_CERT_ID**
-
- BL32 content certificate identifier, used by BL2 to load the BL32 content
- certificate (mandatory when Trusted Board Boot is enabled).
-
-* **#define : BL32_BASE**
-
- Defines the base address in secure memory where BL2 loads the BL32 binary
- image. Must be aligned on a page-size boundary.
-
-* **#define : BL32_LIMIT**
-
- Defines the maximum address that the BL32 image can occupy.
-
-If the Test Secure-EL1 Payload (TSP) instantiation of BL32 is supported by the
-platform, the following constants must also be defined:
-
-* **#define : TSP_SEC_MEM_BASE**
-
- Defines the base address of the secure memory used by the TSP image on the
- platform. This must be at the same address or below `BL32_BASE`.
-
-* **#define : TSP_SEC_MEM_SIZE**
-
- Defines the size of the secure memory used by the BL32 image on the
- platform. `TSP_SEC_MEM_BASE` and `TSP_SEC_MEM_SIZE` must fully accomodate
- the memory required by the BL32 image, defined by `BL32_BASE` and
- `BL32_LIMIT`.
-
-* **#define : TSP_IRQ_SEC_PHY_TIMER**
-
- Defines the ID of the secure physical generic timer interrupt used by the
- TSP's interrupt handling code.
-
-If the platform port uses the translation table library code, the following
-constants must also be defined:
-
-* **#define : PLAT_XLAT_TABLES_DYNAMIC**
-
- Optional flag that can be set per-image to enable the dynamic allocation of
- regions even when the MMU is enabled. If not defined, only static
- functionality will be available, if defined and set to 1 it will also
- include the dynamic functionality.
-
-* **#define : MAX_XLAT_TABLES**
-
- Defines the maximum number of translation tables that are allocated by the
- translation table library code. To minimize the amount of runtime memory
- used, choose the smallest value needed to map the required virtual addresses
- for each BL stage. If `PLAT_XLAT_TABLES_DYNAMIC` flag is enabled for a BL
- image, `MAX_XLAT_TABLES` must be defined to accommodate the dynamic regions
- as well.
-
-* **#define : MAX_MMAP_REGIONS**
-
- Defines the maximum number of regions that are allocated by the translation
- table library code. A region consists of physical base address, virtual base
- address, size and attributes (Device/Memory, RO/RW, Secure/Non-Secure), as
- defined in the `mmap_region_t` structure. The platform defines the regions
- that should be mapped. Then, the translation table library will create the
- corresponding tables and descriptors at runtime. To minimize the amount of
- runtime memory used, choose the smallest value needed to register the
- required regions for each BL stage. If `PLAT_XLAT_TABLES_DYNAMIC` flag is
- enabled for a BL image, `MAX_MMAP_REGIONS` must be defined to accommodate
- the dynamic regions as well.
-
-* **#define : ADDR_SPACE_SIZE**
-
- Defines the total size of the address space in bytes. For example, for a 32
- bit address space, this value should be `(1ull << 32)`. This definition is
- now deprecated, platforms should use `PLAT_PHY_ADDR_SPACE_SIZE` and
- `PLAT_VIRT_ADDR_SPACE_SIZE` instead.
-
-* **#define : PLAT_VIRT_ADDR_SPACE_SIZE**
-
- Defines the total size of the virtual address space in bytes. For example,
- for a 32 bit virtual address space, this value should be `(1ull << 32)`.
-
-* **#define : PLAT_PHY_ADDR_SPACE_SIZE**
-
- Defines the total size of the physical address space in bytes. For example,
- for a 32 bit physical address space, this value should be `(1ull << 32)`.
-
-If the platform port uses the IO storage framework, the following constants
-must also be defined:
-
-* **#define : MAX_IO_DEVICES**
-
- Defines the maximum number of registered IO devices. Attempting to register
- more devices than this value using `io_register_device()` will fail with
- -ENOMEM.
-
-* **#define : MAX_IO_HANDLES**
-
- Defines the maximum number of open IO handles. Attempting to open more IO
- entities than this value using `io_open()` will fail with -ENOMEM.
-
-* **#define : MAX_IO_BLOCK_DEVICES**
-
- Defines the maximum number of registered IO block devices. Attempting to
- register more devices this value using `io_dev_open()` will fail
- with -ENOMEM. MAX_IO_BLOCK_DEVICES should be less than MAX_IO_DEVICES.
- With this macro, multiple block devices could be supported at the same
- time.
-
-If the platform needs to allocate data within the per-cpu data framework in
-BL31, it should define the following macro. Currently this is only required if
-the platform decides not to use the coherent memory section by undefining the
-`USE_COHERENT_MEM` build flag. In this case, the framework allocates the
-required memory within the the per-cpu data to minimize wastage.
-
-* **#define : PLAT_PCPU_DATA_SIZE**
-
- Defines the memory (in bytes) to be reserved within the per-cpu data
- structure for use by the platform layer.
-
-The following constants are optional. They should be defined when the platform
-memory layout implies some image overlaying like in ARM standard platforms.
-
-* **#define : BL31_PROGBITS_LIMIT**
-
- Defines the maximum address in secure RAM that the BL31's progbits sections
- can occupy.
-
-* **#define : TSP_PROGBITS_LIMIT**
-
- Defines the maximum address that the TSP's progbits sections can occupy.
-
-If the platform port uses the PL061 GPIO driver, the following constant may
-optionally be defined:
-
-* **PLAT_PL061_MAX_GPIOS**
- Maximum number of GPIOs required by the platform. This allows control how
- much memory is allocated for PL061 GPIO controllers. The default value is
- 32.
- [For example, define the build flag in platform.mk]:
- PLAT_PL061_MAX_GPIOS := 160
- $(eval $(call add_define,PLAT_PL061_MAX_GPIOS))
-
-If the platform port uses the partition driver, the following constant may
-optionally be defined:
-
-* **PLAT_PARTITION_MAX_ENTRIES**
- Maximum number of partition entries required by the platform. This allows
- control how much memory is allocated for partition entries. The default
- value is 128.
- [For example, define the build flag in platform.mk]:
- PLAT_PARTITION_MAX_ENTRIES := 12
- $(eval $(call add_define,PLAT_PARTITION_MAX_ENTRIES))
-
-The following constant is optional. It should be defined to override the default
-behaviour of the `assert()` function (for example, to save memory).
-
-* **PLAT_LOG_LEVEL_ASSERT**
- If `PLAT_LOG_LEVEL_ASSERT` is higher or equal than `LOG_LEVEL_VERBOSE`,
- `assert()` prints the name of the file, the line number and the asserted
- expression. Else if it is higher than `LOG_LEVEL_INFO`, it prints the file
- name and the line number. Else if it is lower than `LOG_LEVEL_INFO`, it
- doesn't print anything to the console. If `PLAT_LOG_LEVEL_ASSERT` isn't
- defined, it defaults to `LOG_LEVEL`.
-
-
-### File : plat_macros.S [mandatory]
-
-Each platform must ensure a file of this name is in the system include path with
-the following macro defined. In the ARM development platforms, this file is
-found in `plat/arm/board/<plat_name>/include/plat_macros.S`.
-
-* **Macro : plat_crash_print_regs**
-
- This macro allows the crash reporting routine to print relevant platform
- registers in case of an unhandled exception in BL31. This aids in debugging
- and this macro can be defined to be empty in case register reporting is not
- desired.
-
- For instance, GIC or interconnect registers may be helpful for
- troubleshooting.
-
-
-2.2 Handling Reset
-------------------
-
-BL1 by default implements the reset vector where execution starts from a cold
-or warm boot. BL31 can be optionally set as a reset vector using the
-`RESET_TO_BL31` make variable.
-
-For each CPU, the reset vector code is responsible for the following tasks:
-
-1. Distinguishing between a cold boot and a warm boot.
-
-2. In the case of a cold boot and the CPU being a secondary CPU, ensuring that
- the CPU is placed in a platform-specific state until the primary CPU
- performs the necessary steps to remove it from this state.
-
-3. In the case of a warm boot, ensuring that the CPU jumps to a platform-
- specific address in the BL31 image in the same processor mode as it was
- when released from reset.
-
-The following functions need to be implemented by the platform port to enable
-reset vector code to perform the above tasks.
-
-
-### Function : plat_get_my_entrypoint() [mandatory when PROGRAMMABLE_RESET_ADDRESS == 0]
-
- Argument : void
- Return : uintptr_t
-
-This function is called with the MMU and caches disabled
-(`SCTLR_EL3.M` = 0 and `SCTLR_EL3.C` = 0). The function is responsible for
-distinguishing between a warm and cold reset for the current CPU using
-platform-specific means. If it's a warm reset, then it returns the warm
-reset entrypoint point provided to `plat_setup_psci_ops()` during
-BL31 initialization. If it's a cold reset then this function must return zero.
-
-This function does not follow the Procedure Call Standard used by the
-Application Binary Interface for the ARM 64-bit architecture. The caller should
-not assume that callee saved registers are preserved across a call to this
-function.
-
-This function fulfills requirement 1 and 3 listed above.
-
-Note that for platforms that support programming the reset address, it is
-expected that a CPU will start executing code directly at the right address,
-both on a cold and warm reset. In this case, there is no need to identify the
-type of reset nor to query the warm reset entrypoint. Therefore, implementing
-this function is not required on such platforms.
-
-
-### Function : plat_secondary_cold_boot_setup() [mandatory when COLD_BOOT_SINGLE_CPU == 0]
-
- Argument : void
-
-This function is called with the MMU and data caches disabled. It is responsible
-for placing the executing secondary CPU in a platform-specific state until the
-primary CPU performs the necessary actions to bring it out of that state and
-allow entry into the OS. This function must not return.
-
-In the ARM FVP port, when using the normal boot flow, each secondary CPU powers
-itself off. The primary CPU is responsible for powering up the secondary CPUs
-when normal world software requires them. When booting an EL3 payload instead,
-they stay powered on and are put in a holding pen until their mailbox gets
-populated.
-
-This function fulfills requirement 2 above.
-
-Note that for platforms that can't release secondary CPUs out of reset, only the
-primary CPU will execute the cold boot code. Therefore, implementing this
-function is not required on such platforms.
-
-
-### Function : plat_is_my_cpu_primary() [mandatory when COLD_BOOT_SINGLE_CPU == 0]
-
- Argument : void
- Return : unsigned int
-
-This function identifies whether the current CPU is the primary CPU or a
-secondary CPU. A return value of zero indicates that the CPU is not the
-primary CPU, while a non-zero return value indicates that the CPU is the
-primary CPU.
-
-Note that for platforms that can't release secondary CPUs out of reset, only the
-primary CPU will execute the cold boot code. Therefore, there is no need to
-distinguish between primary and secondary CPUs and implementing this function is
-not required.
-
-
-### Function : platform_mem_init() [mandatory]
-
- Argument : void
- Return : void
-
-This function is called before any access to data is made by the firmware, in
-order to carry out any essential memory initialization.
-
-
-### Function: plat_get_rotpk_info()
-
- Argument : void *, void **, unsigned int *, unsigned int *
- Return : int
-
-This function is mandatory when Trusted Board Boot is enabled. It returns a
-pointer to the ROTPK stored in the platform (or a hash of it) and its length.
-The ROTPK must be encoded in DER format according to the following ASN.1
-structure:
-
- AlgorithmIdentifier ::= SEQUENCE {
- algorithm OBJECT IDENTIFIER,
- parameters ANY DEFINED BY algorithm OPTIONAL
- }
-
- SubjectPublicKeyInfo ::= SEQUENCE {
- algorithm AlgorithmIdentifier,
- subjectPublicKey BIT STRING
- }
-
-In case the function returns a hash of the key:
-
- DigestInfo ::= SEQUENCE {
- digestAlgorithm AlgorithmIdentifier,
- digest OCTET STRING
- }
-
-The function returns 0 on success. Any other value is treated as error by the
-Trusted Board Boot. The function also reports extra information related
-to the ROTPK in the flags parameter:
-
- ROTPK_IS_HASH : Indicates that the ROTPK returned by the platform is a
- hash.
- ROTPK_NOT_DEPLOYED : This allows the platform to skip certificate ROTPK
- verification while the platform ROTPK is not deployed.
- When this flag is set, the function does not need to
- return a platform ROTPK, and the authentication
- framework uses the ROTPK in the certificate without
- verifying it against the platform value. This flag
- must not be used in a deployed production environment.
-
-### Function: plat_get_nv_ctr()
-
- Argument : void *, unsigned int *
- Return : int
-
-This function is mandatory when Trusted Board Boot is enabled. It returns the
-non-volatile counter value stored in the platform in the second argument. The
-cookie in the first argument may be used to select the counter in case the
-platform provides more than one (for example, on platforms that use the default
-TBBR CoT, the cookie will correspond to the OID values defined in
-TRUSTED_FW_NVCOUNTER_OID or NON_TRUSTED_FW_NVCOUNTER_OID).
-
-The function returns 0 on success. Any other value means the counter value could
-not be retrieved from the platform.
-
-
-### Function: plat_set_nv_ctr()
-
- Argument : void *, unsigned int
- Return : int
-
-This function is mandatory when Trusted Board Boot is enabled. It sets a new
-counter value in the platform. The cookie in the first argument may be used to
-select the counter (as explained in plat_get_nv_ctr()). The second argument is
-the updated counter value to be written to the NV counter.
-
-The function returns 0 on success. Any other value means the counter value could
-not be updated.
-
-
-### Function: plat_set_nv_ctr2()
-
- Argument : void *, const auth_img_desc_t *, unsigned int
- Return : int
-
-This function is optional when Trusted Board Boot is enabled. If this
-interface is defined, then `plat_set_nv_ctr()` need not be defined. The
-first argument passed is a cookie and is typically used to
-differentiate between a Non Trusted NV Counter and a Trusted NV
-Counter. The second argument is a pointer to an authentication image
-descriptor and may be used to decide if the counter is allowed to be
-updated or not. The third argument is the updated counter value to
-be written to the NV counter.
-
-The function returns 0 on success. Any other value means the counter value
-either could not be updated or the authentication image descriptor indicates
-that it is not allowed to be updated.
-
-
-2.3 Common mandatory function modifications
----------------------------------
-
-The following functions are mandatory functions which need to be implemented
-by the platform port.
-
-### Function : plat_my_core_pos()
-
- Argument : void
- Return : unsigned int
-
-This funtion returns the index of the calling CPU which is used as a
-CPU-specific linear index into blocks of memory (for example while allocating
-per-CPU stacks). This function will be invoked very early in the
-initialization sequence which mandates that this function should be
-implemented in assembly and should not rely on the avalability of a C
-runtime environment. This function can clobber x0 - x8 and must preserve
-x9 - x29.
-
-This function plays a crucial role in the power domain topology framework in
-PSCI and details of this can be found in [Power Domain Topology Design].
-
-### Function : plat_core_pos_by_mpidr()
-
- Argument : u_register_t
- Return : int
-
-This function validates the `MPIDR` of a CPU and converts it to an index,
-which can be used as a CPU-specific linear index into blocks of memory. In
-case the `MPIDR` is invalid, this function returns -1. This function will only
-be invoked by BL31 after the power domain topology is initialized and can
-utilize the C runtime environment. For further details about how ARM Trusted
-Firmware represents the power domain topology and how this relates to the
-linear CPU index, please refer [Power Domain Topology Design].
-
-
-2.4 Common optional modifications
----------------------------------
-
-The following are helper functions implemented by the firmware that perform
-common platform-specific tasks. A platform may choose to override these
-definitions.
-
-### Function : plat_set_my_stack()
-
- Argument : void
- Return : void
-
-This function sets the current stack pointer to the normal memory stack that
-has been allocated for the current CPU. For BL images that only require a
-stack for the primary CPU, the UP version of the function is used. The size
-of the stack allocated to each CPU is specified by the platform defined
-constant `PLATFORM_STACK_SIZE`.
-
-Common implementations of this function for the UP and MP BL images are
-provided in [plat/common/aarch64/platform_up_stack.S] and
-[plat/common/aarch64/platform_mp_stack.S]
-
-
-### Function : plat_get_my_stack()
-
- Argument : void
- Return : uintptr_t
-
-This function returns the base address of the normal memory stack that
-has been allocated for the current CPU. For BL images that only require a
-stack for the primary CPU, the UP version of the function is used. The size
-of the stack allocated to each CPU is specified by the platform defined
-constant `PLATFORM_STACK_SIZE`.
-
-Common implementations of this function for the UP and MP BL images are
-provided in [plat/common/aarch64/platform_up_stack.S] and
-[plat/common/aarch64/platform_mp_stack.S]
-
-
-### Function : plat_report_exception()
-
- Argument : unsigned int
- Return : void
-
-A platform may need to report various information about its status when an
-exception is taken, for example the current exception level, the CPU security
-state (secure/non-secure), the exception type, and so on. This function is
-called in the following circumstances:
-
-* In BL1, whenever an exception is taken.
-* In BL2, whenever an exception is taken.
-
-The default implementation doesn't do anything, to avoid making assumptions
-about the way the platform displays its status information.
-
-For AArch64, this function receives the exception type as its argument.
-Possible values for exceptions types are listed in the
-[include/common/bl_common.h] header file. Note that these constants are not
-related to any architectural exception code; they are just an ARM Trusted
-Firmware convention.
-
-For AArch32, this function receives the exception mode as its argument.
-Possible values for exception modes are listed in the
-[include/lib/aarch32/arch.h] header file.
-
-### Function : plat_reset_handler()
-
- Argument : void
- Return : void
-
-A platform may need to do additional initialization after reset. This function
-allows the platform to do the platform specific intializations. Platform
-specific errata workarounds could also be implemented here. The api should
-preserve the values of callee saved registers x19 to x29.
-
-The default implementation doesn't do anything. If a platform needs to override
-the default implementation, refer to the [Firmware Design] for general
-guidelines.
-
-### Function : plat_disable_acp()
-
- Argument : void
- Return : void
-
-This api allows a platform to disable the Accelerator Coherency Port (if
-present) during a cluster power down sequence. The default weak implementation
-doesn't do anything. Since this api is called during the power down sequence,
-it has restrictions for stack usage and it can use the registers x0 - x17 as
-scratch registers. It should preserve the value in x18 register as it is used
-by the caller to store the return address.
-
-### Function : plat_error_handler()
-
- Argument : int
- Return : void
-
-This API is called when the generic code encounters an error situation from
-which it cannot continue. It allows the platform to perform error reporting or
-recovery actions (for example, reset the system). This function must not return.
-
-The parameter indicates the type of error using standard codes from `errno.h`.
-Possible errors reported by the generic code are:
-
-* `-EAUTH`: a certificate or image could not be authenticated (when Trusted
- Board Boot is enabled)
-* `-ENOENT`: the requested image or certificate could not be found or an IO
- error was detected
-* `-ENOMEM`: resources exhausted. Trusted Firmware does not use dynamic
- memory, so this error is usually an indication of an incorrect array size
-
-The default implementation simply spins.
-
-### Function : plat_panic_handler()
-
- Argument : void
- Return : void
-
-This API is called when the generic code encounters an unexpected error
-situation from which it cannot recover. This function must not return,
-and must be implemented in assembly because it may be called before the C
-environment is initialized.
-
-Note: The address from where it was called is stored in x30 (Link Register).
-The default implementation simply spins.
-
-
-### Function : plat_get_bl_image_load_info()
-
- Argument : void
- Return : bl_load_info_t *
-
-This function returns pointer to the list of images that the platform has
-populated to load. This function is currently invoked in BL2 to load the
-BL3xx images, when LOAD_IMAGE_V2 is enabled.
-
-### Function : plat_get_next_bl_params()
-
- Argument : void
- Return : bl_params_t *
-
-This function returns a pointer to the shared memory that the platform has
-kept aside to pass trusted firmware related information that next BL image
-needs. This function is currently invoked in BL2 to pass this information to
-the next BL image, when LOAD_IMAGE_V2 is enabled.
-
-### Function : plat_get_stack_protector_canary()
- Argument : void
- Return : u_register_t
-
-This function returns a random value that is used to initialize the canary used
-when the stack protector is enabled with ENABLE_STACK_PROTECTOR. A predictable
-value will weaken the protection as the attacker could easily write the right
-value as part of the attack most of the time. Therefore, it should return a
-true random number.
-
-Note: For the protection to be effective, the global data need to be placed at
-a lower address than the stack bases. Failure to do so would allow an attacker
-to overwrite the canary as part of the stack buffer overflow attack.
-
-### Function : plat_flush_next_bl_params()
-
- Argument : void
- Return : void
-
-This function flushes to main memory all the image params that are passed to
-next image. This function is currently invoked in BL2 to flush this information
-to the next BL image, when LOAD_IMAGE_V2 is enabled.
-
-3. Modifications specific to a Boot Loader stage
--------------------------------------------------
-
-3.1 Boot Loader Stage 1 (BL1)
------------------------------
-
-BL1 implements the reset vector where execution starts from after a cold or
-warm boot. For each CPU, BL1 is responsible for the following tasks:
-
-1. Handling the reset as described in section 2.2
-
-2. In the case of a cold boot and the CPU being the primary CPU, ensuring that
- only this CPU executes the remaining BL1 code, including loading and passing
- control to the BL2 stage.
-
-3. Identifying and starting the Firmware Update process (if required).
-
-4. Loading the BL2 image from non-volatile storage into secure memory at the
- address specified by the platform defined constant `BL2_BASE`.
-
-5. Populating a `meminfo` structure with the following information in memory,
- accessible by BL2 immediately upon entry.
-
- meminfo.total_base = Base address of secure RAM visible to BL2
- meminfo.total_size = Size of secure RAM visible to BL2
- meminfo.free_base = Base address of secure RAM available for
- allocation to BL2
- meminfo.free_size = Size of secure RAM available for allocation to BL2
-
- BL1 places this `meminfo` structure at the beginning of the free memory
- available for its use. Since BL1 cannot allocate memory dynamically at the
- moment, its free memory will be available for BL2's use as-is. However, this
- means that BL2 must read the `meminfo` structure before it starts using its
- free memory (this is discussed in Section 3.2).
-
- In future releases of the ARM Trusted Firmware it will be possible for
- the platform to decide where it wants to place the `meminfo` structure for
- BL2.
-
- BL1 implements the `bl1_init_bl2_mem_layout()` function to populate the
- BL2 `meminfo` structure. The platform may override this implementation, for
- example if the platform wants to restrict the amount of memory visible to
- BL2. Details of how to do this are given below.
-
-The following functions need to be implemented by the platform port to enable
-BL1 to perform the above tasks.
-
-
-### Function : bl1_early_platform_setup() [mandatory]
-
- Argument : void
- Return : void
-
-This function executes with the MMU and data caches disabled. It is only called
-by the primary CPU.
-
-On ARM standard platforms, this function:
-
-* Enables a secure instance of SP805 to act as the Trusted Watchdog.
-
-* Initializes a UART (PL011 console), which enables access to the `printf`
- family of functions in BL1.
-
-* Enables issuing of snoop and DVM (Distributed Virtual Memory) requests to
- the CCI slave interface corresponding to the cluster that includes the
- primary CPU.
-
-### Function : bl1_plat_arch_setup() [mandatory]
-
- Argument : void
- Return : void
-
-This function performs any platform-specific and architectural setup that the
-platform requires. Platform-specific setup might include configuration of
-memory controllers and the interconnect.
-
-In ARM standard platforms, this function enables the MMU.
-
-This function helps fulfill requirement 2 above.
-
-
-### Function : bl1_platform_setup() [mandatory]
-
- Argument : void
- Return : void
-
-This function executes with the MMU and data caches enabled. It is responsible
-for performing any remaining platform-specific setup that can occur after the
-MMU and data cache have been enabled.
-
-In ARM standard platforms, this function initializes the storage abstraction
-layer used to load the next bootloader image.
-
-This function helps fulfill requirement 4 above.
-
-
-### Function : bl1_plat_sec_mem_layout() [mandatory]
-
- Argument : void
- Return : meminfo *
-
-This function should only be called on the cold boot path. It executes with the
-MMU and data caches enabled. The pointer returned by this function must point to
-a `meminfo` structure containing the extents and availability of secure RAM for
-the BL1 stage.
-
- meminfo.total_base = Base address of secure RAM visible to BL1
- meminfo.total_size = Size of secure RAM visible to BL1
- meminfo.free_base = Base address of secure RAM available for allocation
- to BL1
- meminfo.free_size = Size of secure RAM available for allocation to BL1
-
-This information is used by BL1 to load the BL2 image in secure RAM. BL1 also
-populates a similar structure to tell BL2 the extents of memory available for
-its own use.
-
-This function helps fulfill requirements 4 and 5 above.
-
-
-### Function : bl1_init_bl2_mem_layout() [optional]
-
- Argument : meminfo *, meminfo *
- Return : void
-
-BL1 needs to tell the next stage the amount of secure RAM available
-for it to use. This information is populated in a `meminfo`
-structure.
-
-Depending upon where BL2 has been loaded in secure RAM (determined by
-`BL2_BASE`), BL1 calculates the amount of free memory available for BL2 to use.
-BL1 also ensures that its data sections resident in secure RAM are not visible
-to BL2. An illustration of how this is done in ARM standard platforms is given
-in the **Memory layout on ARM development platforms** section in the
-[Firmware Design].
-
-
-### Function : bl1_plat_prepare_exit() [optional]
-
- Argument : entry_point_info_t *
- Return : void
-
-This function is called prior to exiting BL1 in response to the
-`BL1_SMC_RUN_IMAGE` SMC request raised by BL2. It should be used to perform
-platform specific clean up or bookkeeping operations before transferring
-control to the next image. It receives the address of the `entry_point_info_t`
-structure passed from BL2. This function runs with MMU disabled.
-
-### Function : bl1_plat_set_ep_info() [optional]
-
- Argument : unsigned int image_id, entry_point_info_t *ep_info
- Return : void
-
-This function allows platforms to override `ep_info` for the given `image_id`.
-
-The default implementation just returns.
-
-### Function : bl1_plat_get_next_image_id() [optional]
-
- Argument : void
- Return : unsigned int
-
-This and the following function must be overridden to enable the FWU feature.
-
-BL1 calls this function after platform setup to identify the next image to be
-loaded and executed. If the platform returns `BL2_IMAGE_ID` then BL1 proceeds
-with the normal boot sequence, which loads and executes BL2. If the platform
-returns a different image id, BL1 assumes that Firmware Update is required.
-
-The default implementation always returns `BL2_IMAGE_ID`. The ARM development
-platforms override this function to detect if firmware update is required, and
-if so, return the first image in the firmware update process.
-
-### Function : bl1_plat_get_image_desc() [optional]
-
- Argument : unsigned int image_id
- Return : image_desc_t *
-
-BL1 calls this function to get the image descriptor information `image_desc_t`
-for the provided `image_id` from the platform.
-
-The default implementation always returns a common BL2 image descriptor. ARM
-standard platforms return an image descriptor corresponding to BL2 or one of
-the firmware update images defined in the Trusted Board Boot Requirements
-specification.
-
-### Function : bl1_plat_fwu_done() [optional]
-
- Argument : unsigned int image_id, uintptr_t image_src,
- unsigned int image_size
- Return : void
-
-BL1 calls this function when the FWU process is complete. It must not return.
-The platform may override this function to take platform specific action, for
-example to initiate the normal boot flow.
-
-The default implementation spins forever.
-
-### Function : bl1_plat_mem_check() [mandatory]
-
- Argument : uintptr_t mem_base, unsigned int mem_size,
- unsigned int flags
- Return : int
-
-BL1 calls this function while handling FWU related SMCs, more specifically when
-copying or authenticating an image. Its responsibility is to ensure that the
-region of memory identified by `mem_base` and `mem_size` is mapped in BL1, and
-that this memory corresponds to either a secure or non-secure memory region as
-indicated by the security state of the `flags` argument.
-
-This function can safely assume that the value resulting from the addition of
-`mem_base` and `mem_size` fits into a `uintptr_t` type variable and does not
-overflow.
-
-This function must return 0 on success, a non-null error code otherwise.
-
-The default implementation of this function asserts therefore platforms must
-override it when using the FWU feature.
-
-
-3.2 Boot Loader Stage 2 (BL2)
------------------------------
-
-The BL2 stage is executed only by the primary CPU, which is determined in BL1
-using the `platform_is_primary_cpu()` function. BL1 passed control to BL2 at
-`BL2_BASE`. BL2 executes in Secure EL1 and is responsible for:
-
-1. (Optional) Loading the SCP_BL2 binary image (if present) from platform
- provided non-volatile storage. To load the SCP_BL2 image, BL2 makes use of
- the `meminfo` returned by the `bl2_plat_get_scp_bl2_meminfo()` function.
- The platform also defines the address in memory where SCP_BL2 is loaded
- through the optional constant `SCP_BL2_BASE`. BL2 uses this information
- to determine if there is enough memory to load the SCP_BL2 image.
- Subsequent handling of the SCP_BL2 image is platform-specific and is
- implemented in the `bl2_plat_handle_scp_bl2()` function.
- If `SCP_BL2_BASE` is not defined then this step is not performed.
-
-2. Loading the BL31 binary image into secure RAM from non-volatile storage. To
- load the BL31 image, BL2 makes use of the `meminfo` structure passed to it
- by BL1. This structure allows BL2 to calculate how much secure RAM is
- available for its use. The platform also defines the address in secure RAM
- where BL31 is loaded through the constant `BL31_BASE`. BL2 uses this
- information to determine if there is enough memory to load the BL31 image.
-
-3. (Optional) Loading the BL32 binary image (if present) from platform
- provided non-volatile storage. To load the BL32 image, BL2 makes use of
- the `meminfo` returned by the `bl2_plat_get_bl32_meminfo()` function.
- The platform also defines the address in memory where BL32 is loaded
- through the optional constant `BL32_BASE`. BL2 uses this information
- to determine if there is enough memory to load the BL32 image.
- If `BL32_BASE` is not defined then this and the next step is not performed.
-
-4. (Optional) Arranging to pass control to the BL32 image (if present) that
- has been pre-loaded at `BL32_BASE`. BL2 populates an `entry_point_info`
- structure in memory provided by the platform with information about how
- BL31 should pass control to the BL32 image.
-
-5. (Optional) Loading the normal world BL33 binary image (if not loaded by
- other means) into non-secure DRAM from platform storage and arranging for
- BL31 to pass control to this image. This address is determined using the
- `plat_get_ns_image_entrypoint()` function described below.
-
-6. BL2 populates an `entry_point_info` structure in memory provided by the
- platform with information about how BL31 should pass control to the
- other BL images.
-
-The following functions must be implemented by the platform port to enable BL2
-to perform the above tasks.
-
-
-### Function : bl2_early_platform_setup() [mandatory]
-
- Argument : meminfo *
- Return : void
-
-This function executes with the MMU and data caches disabled. It is only called
-by the primary CPU. The arguments to this function is the address of the
-`meminfo` structure populated by BL1.
-
-The platform may copy the contents of the `meminfo` structure into a private
-variable as the original memory may be subsequently overwritten by BL2. The
-copied structure is made available to all BL2 code through the
-`bl2_plat_sec_mem_layout()` function.
-
-On ARM standard platforms, this function also:
-
-* Initializes a UART (PL011 console), which enables access to the `printf`
- family of functions in BL2.
-
-* Initializes the storage abstraction layer used to load further bootloader
- images. It is necessary to do this early on platforms with a SCP_BL2 image,
- since the later `bl2_platform_setup` must be done after SCP_BL2 is loaded.
-
-
-### Function : bl2_plat_arch_setup() [mandatory]
-
- Argument : void
- Return : void
-
-This function executes with the MMU and data caches disabled. It is only called
-by the primary CPU.
-
-The purpose of this function is to perform any architectural initialization
-that varies across platforms.
-
-On ARM standard platforms, this function enables the MMU.
-
-### Function : bl2_platform_setup() [mandatory]
-
- Argument : void
- Return : void
-
-This function may execute with the MMU and data caches enabled if the platform
-port does the necessary initialization in `bl2_plat_arch_setup()`. It is only
-called by the primary CPU.
-
-The purpose of this function is to perform any platform initialization
-specific to BL2.
-
-In ARM standard platforms, this function performs security setup, including
-configuration of the TrustZone controller to allow non-secure masters access
-to most of DRAM. Part of DRAM is reserved for secure world use.
-
-
-### Function : bl2_plat_sec_mem_layout() [mandatory]
-
- Argument : void
- Return : meminfo *
-
-This function should only be called on the cold boot path. It may execute with
-the MMU and data caches enabled if the platform port does the necessary
-initialization in `bl2_plat_arch_setup()`. It is only called by the primary CPU.
-
-The purpose of this function is to return a pointer to a `meminfo` structure
-populated with the extents of secure RAM available for BL2 to use. See
-`bl2_early_platform_setup()` above.
-
-
-Following function is required only when LOAD_IMAGE_V2 is enabled.
-
-### Function : bl2_plat_handle_post_image_load() [mandatory]
-
- Argument : unsigned int
- Return : int
-
-This function can be used by the platforms to update/use image information
-for given `image_id`. This function is currently invoked in BL2 to handle
-BL image specific information based on the `image_id` passed, when
-LOAD_IMAGE_V2 is enabled.
-
-Following functions are required only when LOAD_IMAGE_V2 is disabled.
-
-### Function : bl2_plat_get_scp_bl2_meminfo() [mandatory]
-
- Argument : meminfo *
- Return : void
-
-This function is used to get the memory limits where BL2 can load the
-SCP_BL2 image. The meminfo provided by this is used by load_image() to
-validate whether the SCP_BL2 image can be loaded within the given
-memory from the given base.
-
-
-### Function : bl2_plat_handle_scp_bl2() [mandatory]
-
- Argument : image_info *
- Return : int
-
-This function is called after loading SCP_BL2 image and it is used to perform
-any platform-specific actions required to handle the SCP firmware. Typically it
-transfers the image into SCP memory using a platform-specific protocol and waits
-until SCP executes it and signals to the Application Processor (AP) for BL2
-execution to continue.
-
-This function returns 0 on success, a negative error code otherwise.
-
-
-### Function : bl2_plat_get_bl31_params() [mandatory]
-
- Argument : void
- Return : bl31_params *
-
-BL2 platform code needs to return a pointer to a `bl31_params` structure it
-will use for passing information to BL31. The `bl31_params` structure carries
-the following information.
- - Header describing the version information for interpreting the bl31_param
- structure
- - Information about executing the BL33 image in the `bl33_ep_info` field
- - Information about executing the BL32 image in the `bl32_ep_info` field
- - Information about the type and extents of BL31 image in the
- `bl31_image_info` field
- - Information about the type and extents of BL32 image in the
- `bl32_image_info` field
- - Information about the type and extents of BL33 image in the
- `bl33_image_info` field
-
-The memory pointed by this structure and its sub-structures should be
-accessible from BL31 initialisation code. BL31 might choose to copy the
-necessary content, or maintain the structures until BL33 is initialised.
-
-
-### Funtion : bl2_plat_get_bl31_ep_info() [mandatory]
-
- Argument : void
- Return : entry_point_info *
-
-BL2 platform code returns a pointer which is used to populate the entry point
-information for BL31 entry point. The location pointed by it should be
-accessible from BL1 while processing the synchronous exception to run to BL31.
-
-In ARM standard platforms this is allocated inside a bl2_to_bl31_params_mem
-structure in BL2 memory.
-
-
-### Function : bl2_plat_set_bl31_ep_info() [mandatory]
-
- Argument : image_info *, entry_point_info *
- Return : void
-
-In the normal boot flow, this function is called after loading BL31 image and
-it can be used to overwrite the entry point set by loader and also set the
-security state and SPSR which represents the entry point system state for BL31.
-
-When booting an EL3 payload instead, this function is called after populating
-its entry point address and can be used for the same purpose for the payload
-image. It receives a null pointer as its first argument in this case.
-
-### Function : bl2_plat_set_bl32_ep_info() [mandatory]
-
- Argument : image_info *, entry_point_info *
- Return : void
-
-This function is called after loading BL32 image and it can be used to
-overwrite the entry point set by loader and also set the security state
-and SPSR which represents the entry point system state for BL32.
-
-
-### Function : bl2_plat_set_bl33_ep_info() [mandatory]
-
- Argument : image_info *, entry_point_info *
- Return : void
-
-This function is called after loading BL33 image and it can be used to
-overwrite the entry point set by loader and also set the security state
-and SPSR which represents the entry point system state for BL33.
-
-In the preloaded BL33 alternative boot flow, this function is called after
-populating its entry point address. It is passed a null pointer as its first
-argument in this case.
-
-
-### Function : bl2_plat_get_bl32_meminfo() [mandatory]
-
- Argument : meminfo *
- Return : void
-
-This function is used to get the memory limits where BL2 can load the
-BL32 image. The meminfo provided by this is used by load_image() to
-validate whether the BL32 image can be loaded with in the given
-memory from the given base.
-
-### Function : bl2_plat_get_bl33_meminfo() [mandatory]
-
- Argument : meminfo *
- Return : void
-
-This function is used to get the memory limits where BL2 can load the
-BL33 image. The meminfo provided by this is used by load_image() to
-validate whether the BL33 image can be loaded with in the given
-memory from the given base.
-
-This function isn't needed if either `PRELOADED_BL33_BASE` or `EL3_PAYLOAD_BASE`
-build options are used.
-
-### Function : bl2_plat_flush_bl31_params() [mandatory]
-
- Argument : void
- Return : void
-
-Once BL2 has populated all the structures that needs to be read by BL1
-and BL31 including the bl31_params structures and its sub-structures,
-the bl31_ep_info structure and any platform specific data. It flushes
-all these data to the main memory so that it is available when we jump to
-later Bootloader stages with MMU off
-
-### Function : plat_get_ns_image_entrypoint() [mandatory]
-
- Argument : void
- Return : uintptr_t
-
-As previously described, BL2 is responsible for arranging for control to be
-passed to a normal world BL image through BL31. This function returns the
-entrypoint of that image, which BL31 uses to jump to it.
-
-BL2 is responsible for loading the normal world BL33 image (e.g. UEFI).
-
-This function isn't needed if either `PRELOADED_BL33_BASE` or `EL3_PAYLOAD_BASE`
-build options are used.
-
-
-3.3 FWU Boot Loader Stage 2 (BL2U)
-----------------------------------
-
-The AP Firmware Updater Configuration, BL2U, is an optional part of the FWU
-process and is executed only by the primary CPU. BL1 passes control to BL2U at
-`BL2U_BASE`. BL2U executes in Secure-EL1 and is responsible for:
-
-1. (Optional) Transfering the optional SCP_BL2U binary image from AP secure
- memory to SCP RAM. BL2U uses the SCP_BL2U `image_info` passed by BL1.
- `SCP_BL2U_BASE` defines the address in AP secure memory where SCP_BL2U
- should be copied from. Subsequent handling of the SCP_BL2U image is
- implemented by the platform specific `bl2u_plat_handle_scp_bl2u()` function.
- If `SCP_BL2U_BASE` is not defined then this step is not performed.
-
-2. Any platform specific setup required to perform the FWU process. For
- example, ARM standard platforms initialize the TZC controller so that the
- normal world can access DDR memory.
-
-The following functions must be implemented by the platform port to enable
-BL2U to perform the tasks mentioned above.
-
-### Function : bl2u_early_platform_setup() [mandatory]
-
- Argument : meminfo *mem_info, void *plat_info
- Return : void
-
-This function executes with the MMU and data caches disabled. It is only
-called by the primary CPU. The arguments to this function is the address
-of the `meminfo` structure and platform specific info provided by BL1.
-
-The platform may copy the contents of the `mem_info` and `plat_info` into
-private storage as the original memory may be subsequently overwritten by BL2U.
-
-On ARM CSS platforms `plat_info` is interpreted as an `image_info_t` structure,
-to extract SCP_BL2U image information, which is then copied into a private
-variable.
-
-### Function : bl2u_plat_arch_setup() [mandatory]
-
- Argument : void
- Return : void
-
-This function executes with the MMU and data caches disabled. It is only
-called by the primary CPU.
-
-The purpose of this function is to perform any architectural initialization
-that varies across platforms, for example enabling the MMU (since the memory
-map differs across platforms).
-
-### Function : bl2u_platform_setup() [mandatory]
-
- Argument : void
- Return : void
-
-This function may execute with the MMU and data caches enabled if the platform
-port does the necessary initialization in `bl2u_plat_arch_setup()`. It is only
-called by the primary CPU.
-
-The purpose of this function is to perform any platform initialization
-specific to BL2U.
-
-In ARM standard platforms, this function performs security setup, including
-configuration of the TrustZone controller to allow non-secure masters access
-to most of DRAM. Part of DRAM is reserved for secure world use.
-
-### Function : bl2u_plat_handle_scp_bl2u() [optional]
-
- Argument : void
- Return : int
-
-This function is used to perform any platform-specific actions required to
-handle the SCP firmware. Typically it transfers the image into SCP memory using
-a platform-specific protocol and waits until SCP executes it and signals to the
-Application Processor (AP) for BL2U execution to continue.
-
-This function returns 0 on success, a negative error code otherwise.
-This function is included if SCP_BL2U_BASE is defined.
-
-
-3.4 Boot Loader Stage 3-1 (BL31)
----------------------------------
-
-During cold boot, the BL31 stage is executed only by the primary CPU. This is
-determined in BL1 using the `platform_is_primary_cpu()` function. BL1 passes
-control to BL31 at `BL31_BASE`. During warm boot, BL31 is executed by all
-CPUs. BL31 executes at EL3 and is responsible for:
-
-1. Re-initializing all architectural and platform state. Although BL1 performs
- some of this initialization, BL31 remains resident in EL3 and must ensure
- that EL3 architectural and platform state is completely initialized. It
- should make no assumptions about the system state when it receives control.
-
-2. Passing control to a normal world BL image, pre-loaded at a platform-
- specific address by BL2. BL31 uses the `entry_point_info` structure that BL2
- populated in memory to do this.
-
-3. Providing runtime firmware services. Currently, BL31 only implements a
- subset of the Power State Coordination Interface (PSCI) API as a runtime
- service. See Section 3.3 below for details of porting the PSCI
- implementation.
-
-4. Optionally passing control to the BL32 image, pre-loaded at a platform-
- specific address by BL2. BL31 exports a set of apis that allow runtime
- services to specify the security state in which the next image should be
- executed and run the corresponding image. BL31 uses the `entry_point_info`
- structure populated by BL2 to do this.
-
-If BL31 is a reset vector, It also needs to handle the reset as specified in
-section 2.2 before the tasks described above.
-
-The following functions must be implemented by the platform port to enable BL31
-to perform the above tasks.
-
-
-### Function : bl31_early_platform_setup() [mandatory]
-
- Argument : bl31_params *, void *
- Return : void
-
-This function executes with the MMU and data caches disabled. It is only called
-by the primary CPU. The arguments to this function are:
-
-* The address of the `bl31_params` structure populated by BL2.
-* An opaque pointer that the platform may use as needed.
-
-The platform can copy the contents of the `bl31_params` structure and its
-sub-structures into private variables if the original memory may be
-subsequently overwritten by BL31 and similarly the `void *` pointing
-to the platform data also needs to be saved.
-
-In ARM standard platforms, BL2 passes a pointer to a `bl31_params` structure
-in BL2 memory. BL31 copies the information in this pointer to internal data
-structures. It also performs the following:
-
-* Initialize a UART (PL011 console), which enables access to the `printf`
- family of functions in BL31.
-
-* Enable issuing of snoop and DVM (Distributed Virtual Memory) requests to the
- CCI slave interface corresponding to the cluster that includes the primary
- CPU.
-
-
-### Function : bl31_plat_arch_setup() [mandatory]
-
- Argument : void
- Return : void
-
-This function executes with the MMU and data caches disabled. It is only called
-by the primary CPU.
-
-The purpose of this function is to perform any architectural initialization
-that varies across platforms.
-
-On ARM standard platforms, this function enables the MMU.
-
-
-### Function : bl31_platform_setup() [mandatory]
-
- Argument : void
- Return : void
-
-This function may execute with the MMU and data caches enabled if the platform
-port does the necessary initialization in `bl31_plat_arch_setup()`. It is only
-called by the primary CPU.
-
-The purpose of this function is to complete platform initialization so that both
-BL31 runtime services and normal world software can function correctly.
-
-On ARM standard platforms, this function does the following:
-
-* Initialize the generic interrupt controller.
-
- Depending on the GIC driver selected by the platform, the appropriate GICv2
- or GICv3 initialization will be done, which mainly consists of:
-
- - Enable secure interrupts in the GIC CPU interface.
- - Disable the legacy interrupt bypass mechanism.
- - Configure the priority mask register to allow interrupts of all priorities
- to be signaled to the CPU interface.
- - Mark SGIs 8-15 and the other secure interrupts on the platform as secure.
- - Target all secure SPIs to CPU0.
- - Enable these secure interrupts in the GIC distributor.
- - Configure all other interrupts as non-secure.
- - Enable signaling of secure interrupts in the GIC distributor.
-
-* Enable system-level implementation of the generic timer counter through the
- memory mapped interface.
-
-* Grant access to the system counter timer module
-
-* Initialize the power controller device.
-
- In particular, initialise the locks that prevent concurrent accesses to the
- power controller device.
-
-
-### Function : bl31_plat_runtime_setup() [optional]
-
- Argument : void
- Return : void
-
-The purpose of this function is allow the platform to perform any BL31 runtime
-setup just prior to BL31 exit during cold boot. The default weak
-implementation of this function will invoke `console_uninit()` which will
-suppress any BL31 runtime logs.
-
-In ARM Standard platforms, this function will initialize the BL31 runtime
-console which will cause all further BL31 logs to be output to the
-runtime console.
-
-
-### Function : bl31_get_next_image_info() [mandatory]
-
- Argument : unsigned int
- Return : entry_point_info *
-
-This function may execute with the MMU and data caches enabled if the platform
-port does the necessary initializations in `bl31_plat_arch_setup()`.
-
-This function is called by `bl31_main()` to retrieve information provided by
-BL2 for the next image in the security state specified by the argument. BL31
-uses this information to pass control to that image in the specified security
-state. This function must return a pointer to the `entry_point_info` structure
-(that was copied during `bl31_early_platform_setup()`) if the image exists. It
-should return NULL otherwise.
-
-### Function : plat_get_syscnt_freq2() [mandatory]
-
- Argument : void
- Return : unsigned int
-
-This function is used by the architecture setup code to retrieve the counter
-frequency for the CPU's generic timer. This value will be programmed into the
-`CNTFRQ_EL0` register. In ARM standard platforms, it returns the base frequency
-of the system counter, which is retrieved from the first entry in the frequency
-modes table.
-
-
-### #define : PLAT_PERCPU_BAKERY_LOCK_SIZE [optional]
-
- When `USE_COHERENT_MEM = 0`, this constant defines the total memory (in
- bytes) aligned to the cache line boundary that should be allocated per-cpu to
- accommodate all the bakery locks.
-
- If this constant is not defined when `USE_COHERENT_MEM = 0`, the linker
- calculates the size of the `bakery_lock` input section, aligns it to the
- nearest `CACHE_WRITEBACK_GRANULE`, multiplies it with `PLATFORM_CORE_COUNT`
- and stores the result in a linker symbol. This constant prevents a platform
- from relying on the linker and provide a more efficient mechanism for
- accessing per-cpu bakery lock information.
-
- If this constant is defined and its value is not equal to the value
- calculated by the linker then a link time assertion is raised. A compile time
- assertion is raised if the value of the constant is not aligned to the cache
- line boundary.
-
-3.5 Power State Coordination Interface (in BL31)
-------------------------------------------------
-
-The ARM Trusted Firmware's implementation of the PSCI API is based around the
-concept of a _power domain_. A _power domain_ is a CPU or a logical group of
-CPUs which share some state on which power management operations can be
-performed as specified by [PSCI]. Each CPU in the system is assigned a cpu
-index which is a unique number between `0` and `PLATFORM_CORE_COUNT - 1`.
-The _power domains_ are arranged in a hierarchical tree structure and
-each _power domain_ can be identified in a system by the cpu index of any CPU
-that is part of that domain and a _power domain level_. A processing element
-(for example, a CPU) is at level 0. If the _power domain_ node above a CPU is
-a logical grouping of CPUs that share some state, then level 1 is that group
-of CPUs (for example, a cluster), and level 2 is a group of clusters
-(for example, the system). More details on the power domain topology and its
-organization can be found in [Power Domain Topology Design].
-
-BL31's platform initialization code exports a pointer to the platform-specific
-power management operations required for the PSCI implementation to function
-correctly. This information is populated in the `plat_psci_ops` structure. The
-PSCI implementation calls members of the `plat_psci_ops` structure for performing
-power management operations on the power domains. For example, the target
-CPU is specified by its `MPIDR` in a PSCI `CPU_ON` call. The `pwr_domain_on()`
-handler (if present) is called for the CPU power domain.
-
-The `power-state` parameter of a PSCI `CPU_SUSPEND` call can be used to
-describe composite power states specific to a platform. The PSCI implementation
-defines a generic representation of the power-state parameter viz which is an
-array of local power states where each index corresponds to a power domain
-level. Each entry contains the local power state the power domain at that power
-level could enter. It depends on the `validate_power_state()` handler to
-convert the power-state parameter (possibly encoding a composite power state)
-passed in a PSCI `CPU_SUSPEND` call to this representation.
-
-The following functions form part of platform port of PSCI functionality.
-
-
-### Function : plat_psci_stat_accounting_start() [optional]
-
- Argument : const psci_power_state_t *
- Return : void
-
-This is an optional hook that platforms can implement for residency statistics
-accounting before entering a low power state. The `pwr_domain_state` field of
-`state_info` (first argument) can be inspected if stat accounting is done
-differently at CPU level versus higher levels. As an example, if the element at
-index 0 (CPU power level) in the `pwr_domain_state` array indicates a power down
-state, special hardware logic may be programmed in order to keep track of the
-residency statistics. For higher levels (array indices > 0), the residency
-statistics could be tracked in software using PMF. If `ENABLE_PMF` is set, the
-default implementation will use PMF to capture timestamps.
-
-### Function : plat_psci_stat_accounting_stop() [optional]
-
- Argument : const psci_power_state_t *
- Return : void
-
-This is an optional hook that platforms can implement for residency statistics
-accounting after exiting from a low power state. The `pwr_domain_state` field
-of `state_info` (first argument) can be inspected if stat accounting is done
-differently at CPU level versus higher levels. As an example, if the element at
-index 0 (CPU power level) in the `pwr_domain_state` array indicates a power down
-state, special hardware logic may be programmed in order to keep track of the
-residency statistics. For higher levels (array indices > 0), the residency
-statistics could be tracked in software using PMF. If `ENABLE_PMF` is set, the
-default implementation will use PMF to capture timestamps.
-
-### Function : plat_psci_stat_get_residency() [optional]
-
- Argument : unsigned int, const psci_power_state_t *, int
- Return : u_register_t
-
-This is an optional interface that is is invoked after resuming from a low power
-state and provides the time spent resident in that low power state by the power
-domain at a particular power domain level. When a CPU wakes up from suspend,
-all its parent power domain levels are also woken up. The generic PSCI code
-invokes this function for each parent power domain that is resumed and it
-identified by the `lvl` (first argument) parameter. The `state_info` (second
-argument) describes the low power state that the power domain has resumed from.
-The current CPU is the first CPU in the power domain to resume from the low
-power state and the `last_cpu_idx` (third parameter) is the index of the last
-CPU in the power domain to suspend and may be needed to calculate the residency
-for that power domain.
-
-### Function : plat_get_target_pwr_state() [optional]
-
- Argument : unsigned int, const plat_local_state_t *, unsigned int
- Return : plat_local_state_t
-
-The PSCI generic code uses this function to let the platform participate in
-state coordination during a power management operation. The function is passed
-a pointer to an array of platform specific local power state `states` (second
-argument) which contains the requested power state for each CPU at a particular
-power domain level `lvl` (first argument) within the power domain. The function
-is expected to traverse this array of upto `ncpus` (third argument) and return
-a coordinated target power state by the comparing all the requested power
-states. The target power state should not be deeper than any of the requested
-power states.
-
-A weak definition of this API is provided by default wherein it assumes
-that the platform assigns a local state value in order of increasing depth
-of the power state i.e. for two power states X & Y, if X < Y
-then X represents a shallower power state than Y. As a result, the
-coordinated target local power state for a power domain will be the minimum
-of the requested local power state values.
-
-
-### Function : plat_get_power_domain_tree_desc() [mandatory]
-
- Argument : void
- Return : const unsigned char *
-
-This function returns a pointer to the byte array containing the power domain
-topology tree description. The format and method to construct this array are
-described in [Power Domain Topology Design]. The BL31 PSCI initilization code
-requires this array to be described by the platform, either statically or
-dynamically, to initialize the power domain topology tree. In case the array
-is populated dynamically, then plat_core_pos_by_mpidr() and
-plat_my_core_pos() should also be implemented suitably so that the topology
-tree description matches the CPU indices returned by these APIs. These APIs
-together form the platform interface for the PSCI topology framework.
-
-
-## Function : plat_setup_psci_ops() [mandatory]
-
- Argument : uintptr_t, const plat_psci_ops **
- Return : int
-
-This function may execute with the MMU and data caches enabled if the platform
-port does the necessary initializations in `bl31_plat_arch_setup()`. It is only
-called by the primary CPU.
-
-This function is called by PSCI initialization code. Its purpose is to let
-the platform layer know about the warm boot entrypoint through the
-`sec_entrypoint` (first argument) and to export handler routines for
-platform-specific psci power management actions by populating the passed
-pointer with a pointer to BL31's private `plat_psci_ops` structure.
-
-A description of each member of this structure is given below. Please refer to
-the ARM FVP specific implementation of these handlers in
-[plat/arm/board/fvp/fvp_pm.c] as an example. For each PSCI function that the
-platform wants to support, the associated operation or operations in this
-structure must be provided and implemented (Refer section 4 of
-[Firmware Design] for the PSCI API supported in Trusted Firmware). To disable
-a PSCI function in a platform port, the operation should be removed from this
-structure instead of providing an empty implementation.
-
-#### plat_psci_ops.cpu_standby()
-
-Perform the platform-specific actions to enter the standby state for a cpu
-indicated by the passed argument. This provides a fast path for CPU standby
-wherein overheads of PSCI state management and lock acquistion is avoided.
-For this handler to be invoked by the PSCI `CPU_SUSPEND` API implementation,
-the suspend state type specified in the `power-state` parameter should be
-STANDBY and the target power domain level specified should be the CPU. The
-handler should put the CPU into a low power retention state (usually by
-issuing a wfi instruction) and ensure that it can be woken up from that
-state by a normal interrupt. The generic code expects the handler to succeed.
-
-#### plat_psci_ops.pwr_domain_on()
-
-Perform the platform specific actions to power on a CPU, specified
-by the `MPIDR` (first argument). The generic code expects the platform to
-return PSCI_E_SUCCESS on success or PSCI_E_INTERN_FAIL for any failure.
-
-#### plat_psci_ops.pwr_domain_off()
-
-Perform the platform specific actions to prepare to power off the calling CPU
-and its higher parent power domain levels as indicated by the `target_state`
-(first argument). It is called by the PSCI `CPU_OFF` API implementation.
-
-The `target_state` encodes the platform coordinated target local power states
-for the CPU power domain and its parent power domain levels. The handler
-needs to perform power management operation corresponding to the local state
-at each power level.
-
-For this handler, the local power state for the CPU power domain will be a
-power down state where as it could be either power down, retention or run state
-for the higher power domain levels depending on the result of state
-coordination. The generic code expects the handler to succeed.
-
-#### plat_psci_ops.pwr_domain_suspend()
-
-Perform the platform specific actions to prepare to suspend the calling
-CPU and its higher parent power domain levels as indicated by the
-`target_state` (first argument). It is called by the PSCI `CPU_SUSPEND`
-API implementation.
-
-The `target_state` has a similar meaning as described in
-the `pwr_domain_off()` operation. It encodes the platform coordinated
-target local power states for the CPU power domain and its parent
-power domain levels. The handler needs to perform power management operation
-corresponding to the local state at each power level. The generic code
-expects the handler to succeed.
-
-The difference between turning a power domain off versus suspending it
-is that in the former case, the power domain is expected to re-initialize
-its state when it is next powered on (see `pwr_domain_on_finish()`). In the
-latter case, the power domain is expected to save enough state so that it can
-resume execution by restoring this state when its powered on (see
-`pwr_domain_suspend_finish()`).
-
-#### plat_psci_ops.pwr_domain_pwr_down_wfi()
-
-This is an optional function and, if implemented, is expected to perform
-platform specific actions including the `wfi` invocation which allows the
-CPU to powerdown. Since this function is invoked outside the PSCI locks,
-the actions performed in this hook must be local to the CPU or the platform
-must ensure that races between multiple CPUs cannot occur.
-
-The `target_state` has a similar meaning as described in the `pwr_domain_off()`
-operation and it encodes the platform coordinated target local power states for
-the CPU power domain and its parent power domain levels. This function must
-not return back to the caller.
-
-If this function is not implemented by the platform, PSCI generic
-implementation invokes `psci_power_down_wfi()` for power down.
-
-#### plat_psci_ops.pwr_domain_on_finish()
-
-This function is called by the PSCI implementation after the calling CPU is
-powered on and released from reset in response to an earlier PSCI `CPU_ON` call.
-It performs the platform-specific setup required to initialize enough state for
-this CPU to enter the normal world and also provide secure runtime firmware
-services.
-
-The `target_state` (first argument) is the prior state of the power domains
-immediately before the CPU was turned on. It indicates which power domains
-above the CPU might require initialization due to having previously been in
-low power states. The generic code expects the handler to succeed.
-
-#### plat_psci_ops.pwr_domain_suspend_finish()
-
-This function is called by the PSCI implementation after the calling CPU is
-powered on and released from reset in response to an asynchronous wakeup
-event, for example a timer interrupt that was programmed by the CPU during the
-`CPU_SUSPEND` call or `SYSTEM_SUSPEND` call. It performs the platform-specific
-setup required to restore the saved state for this CPU to resume execution
-in the normal world and also provide secure runtime firmware services.
-
-The `target_state` (first argument) has a similar meaning as described in
-the `pwr_domain_on_finish()` operation. The generic code expects the platform
-to succeed.
-
-#### plat_psci_ops.system_off()
-
-This function is called by PSCI implementation in response to a `SYSTEM_OFF`
-call. It performs the platform-specific system poweroff sequence after
-notifying the Secure Payload Dispatcher.
-
-#### plat_psci_ops.system_reset()
-
-This function is called by PSCI implementation in response to a `SYSTEM_RESET`
-call. It performs the platform-specific system reset sequence after
-notifying the Secure Payload Dispatcher.
-
-#### plat_psci_ops.validate_power_state()
-
-This function is called by the PSCI implementation during the `CPU_SUSPEND`
-call to validate the `power_state` parameter of the PSCI API and if valid,
-populate it in `req_state` (second argument) array as power domain level
-specific local states. If the `power_state` is invalid, the platform must
-return PSCI_E_INVALID_PARAMS as error, which is propagated back to the
-normal world PSCI client.
-
-#### plat_psci_ops.validate_ns_entrypoint()
-
-This function is called by the PSCI implementation during the `CPU_SUSPEND`,
-`SYSTEM_SUSPEND` and `CPU_ON` calls to validate the non-secure `entry_point`
-parameter passed by the normal world. If the `entry_point` is invalid,
-the platform must return PSCI_E_INVALID_ADDRESS as error, which is
-propagated back to the normal world PSCI client.
-
-#### plat_psci_ops.get_sys_suspend_power_state()
-
-This function is called by the PSCI implementation during the `SYSTEM_SUSPEND`
-call to get the `req_state` parameter from platform which encodes the power
-domain level specific local states to suspend to system affinity level. The
-`req_state` will be utilized to do the PSCI state coordination and
-`pwr_domain_suspend()` will be invoked with the coordinated target state to
-enter system suspend.
-
-#### plat_psci_ops.get_pwr_lvl_state_idx()
-
-This is an optional function and, if implemented, is invoked by the PSCI
-implementation to convert the `local_state` (first argument) at a specified
-`pwr_lvl` (second argument) to an index between 0 and
-`PLAT_MAX_PWR_LVL_STATES` - 1. This function is only needed if the platform
-supports more than two local power states at each power domain level, that is
-`PLAT_MAX_PWR_LVL_STATES` is greater than 2, and needs to account for these
-local power states.
-
-#### plat_psci_ops.translate_power_state_by_mpidr()
-
-This is an optional function and, if implemented, verifies the `power_state`
-(second argument) parameter of the PSCI API corresponding to a target power
-domain. The target power domain is identified by using both `MPIDR` (first
-argument) and the power domain level encoded in `power_state`. The power domain
-level specific local states are to be extracted from `power_state` and be
-populated in the `output_state` (third argument) array. The functionality
-is similar to the `validate_power_state` function described above and is
-envisaged to be used in case the validity of `power_state` depend on the
-targeted power domain. If the `power_state` is invalid for the targeted power
-domain, the platform must return PSCI_E_INVALID_PARAMS as error. If this
-function is not implemented, then the generic implementation relies on
-`validate_power_state` function to translate the `power_state`.
-
-This function can also be used in case the platform wants to support local
-power state encoding for `power_state` parameter of PSCI_STAT_COUNT/RESIDENCY
-APIs as described in Section 5.18 of [PSCI].
-
-#### plat_psci_ops.get_node_hw_state()
-
-This is an optional function. If implemented this function is intended to return
-the power state of a node (identified by the first parameter, the `MPIDR`) in
-the power domain topology (identified by the second parameter, `power_level`),
-as retrieved from a power controller or equivalent component on the platform.
-Upon successful completion, the implementation must map and return the final
-status among `HW_ON`, `HW_OFF` or `HW_STANDBY`. Upon encountering failures, it
-must return either `PSCI_E_INVALID_PARAMS` or `PSCI_E_NOT_SUPPORTED` as
-appropriate.
-
-Implementations are not expected to handle `power_levels` greater than
-`PLAT_MAX_PWR_LVL`.
-
-3.6 Interrupt Management framework (in BL31)
-----------------------------------------------
-BL31 implements an Interrupt Management Framework (IMF) to manage interrupts
-generated in either security state and targeted to EL1 or EL2 in the non-secure
-state or EL3/S-EL1 in the secure state. The design of this framework is
-described in the [IMF Design Guide]
-
-A platform should export the following APIs to support the IMF. The following
-text briefly describes each api and its implementation in ARM standard
-platforms. The API implementation depends upon the type of interrupt controller
-present in the platform. ARM standard platform layer supports both [ARM Generic
-Interrupt Controller version 2.0 (GICv2)][ARM GIC Architecture Specification 2.0]
-and [3.0 (GICv3)][ARM GIC Architecture Specification 3.0]. Juno builds the ARM
-Standard layer to use GICv2 and the FVP can be configured to use either GICv2 or
-GICv3 depending on the build flag `FVP_USE_GIC_DRIVER` (See FVP platform
-specific build options in [User Guide] for more details).
-
-### Function : plat_interrupt_type_to_line() [mandatory]
-
- Argument : uint32_t, uint32_t
- Return : uint32_t
-
-The ARM processor signals an interrupt exception either through the IRQ or FIQ
-interrupt line. The specific line that is signaled depends on how the interrupt
-controller (IC) reports different interrupt types from an execution context in
-either security state. The IMF uses this API to determine which interrupt line
-the platform IC uses to signal each type of interrupt supported by the framework
-from a given security state. This API must be invoked at EL3.
-
-The first parameter will be one of the `INTR_TYPE_*` values (see [IMF Design
-Guide]) indicating the target type of the interrupt, the second parameter is the
-security state of the originating execution context. The return result is the
-bit position in the `SCR_EL3` register of the respective interrupt trap: IRQ=1,
-FIQ=2.
-
-In the case of ARM standard platforms using GICv2, S-EL1 interrupts are
-configured as FIQs and Non-secure interrupts as IRQs from either security
-state.
-
-In the case of ARM standard platforms using GICv3, the interrupt line to be
-configured depends on the security state of the execution context when the
-interrupt is signalled and are as follows:
-* The S-EL1 interrupts are signaled as IRQ in S-EL0/1 context and as FIQ in
- NS-EL0/1/2 context.
-* The Non secure interrupts are signaled as FIQ in S-EL0/1 context and as IRQ
- in the NS-EL0/1/2 context.
-* The EL3 interrupts are signaled as FIQ in both S-EL0/1 and NS-EL0/1/2
- context.
-
-
-### Function : plat_ic_get_pending_interrupt_type() [mandatory]
-
- Argument : void
- Return : uint32_t
-
-This API returns the type of the highest priority pending interrupt at the
-platform IC. The IMF uses the interrupt type to retrieve the corresponding
-handler function. `INTR_TYPE_INVAL` is returned when there is no interrupt
-pending. The valid interrupt types that can be returned are `INTR_TYPE_EL3`,
-`INTR_TYPE_S_EL1` and `INTR_TYPE_NS`. This API must be invoked at EL3.
-
-In the case of ARM standard platforms using GICv2, the _Highest Priority
-Pending Interrupt Register_ (`GICC_HPPIR`) is read to determine the id of
-the pending interrupt. The type of interrupt depends upon the id value as
-follows.
-
-1. id < 1022 is reported as a S-EL1 interrupt
-2. id = 1022 is reported as a Non-secure interrupt.
-3. id = 1023 is reported as an invalid interrupt type.
-
-In the case of ARM standard platforms using GICv3, the system register
-`ICC_HPPIR0_EL1`, _Highest Priority Pending group 0 Interrupt Register_,
-is read to determine the id of the pending interrupt. The type of interrupt
-depends upon the id value as follows.
-
-1. id = `PENDING_G1S_INTID` (1020) is reported as a S-EL1 interrupt
-2. id = `PENDING_G1NS_INTID` (1021) is reported as a Non-secure interrupt.
-3. id = `GIC_SPURIOUS_INTERRUPT` (1023) is reported as an invalid interrupt type.
-4. All other interrupt id's are reported as EL3 interrupt.
-
-
-### Function : plat_ic_get_pending_interrupt_id() [mandatory]
-
- Argument : void
- Return : uint32_t
-
-This API returns the id of the highest priority pending interrupt at the
-platform IC. `INTR_ID_UNAVAILABLE` is returned when there is no interrupt
-pending.
-
-In the case of ARM standard platforms using GICv2, the _Highest Priority
-Pending Interrupt Register_ (`GICC_HPPIR`) is read to determine the id of the
-pending interrupt. The id that is returned by API depends upon the value of
-the id read from the interrupt controller as follows.
-
-1. id < 1022. id is returned as is.
-2. id = 1022. The _Aliased Highest Priority Pending Interrupt Register_
- (`GICC_AHPPIR`) is read to determine the id of the non-secure interrupt.
- This id is returned by the API.
-3. id = 1023. `INTR_ID_UNAVAILABLE` is returned.
-
-In the case of ARM standard platforms using GICv3, if the API is invoked from
-EL3, the system register `ICC_HPPIR0_EL1`, _Highest Priority Pending Interrupt
-group 0 Register_, is read to determine the id of the pending interrupt. The id
-that is returned by API depends upon the value of the id read from the
-interrupt controller as follows.
-
-1. id < `PENDING_G1S_INTID` (1020). id is returned as is.
-2. id = `PENDING_G1S_INTID` (1020) or `PENDING_G1NS_INTID` (1021). The system
- register `ICC_HPPIR1_EL1`, _Highest Priority Pending Interrupt group 1
- Register_ is read to determine the id of the group 1 interrupt. This id
- is returned by the API as long as it is a valid interrupt id
-3. If the id is any of the special interrupt identifiers,
- `INTR_ID_UNAVAILABLE` is returned.
-
-When the API invoked from S-EL1 for GICv3 systems, the id read from system
-register `ICC_HPPIR1_EL1`, _Highest Priority Pending group 1 Interrupt
-Register_, is returned if is not equal to GIC_SPURIOUS_INTERRUPT (1023) else
-`INTR_ID_UNAVAILABLE` is returned.
-
-### Function : plat_ic_acknowledge_interrupt() [mandatory]
-
- Argument : void
- Return : uint32_t
-
-This API is used by the CPU to indicate to the platform IC that processing of
-the highest pending interrupt has begun. It should return the id of the
-interrupt which is being processed.
-
-This function in ARM standard platforms using GICv2, reads the _Interrupt
-Acknowledge Register_ (`GICC_IAR`). This changes the state of the highest
-priority pending interrupt from pending to active in the interrupt controller.
-It returns the value read from the `GICC_IAR`. This value is the id of the
-interrupt whose state has been changed.
-
-In the case of ARM standard platforms using GICv3, if the API is invoked
-from EL3, the function reads the system register `ICC_IAR0_EL1`, _Interrupt
-Acknowledge Register group 0_. If the API is invoked from S-EL1, the function
-reads the system register `ICC_IAR1_EL1`, _Interrupt Acknowledge Register
-group 1_. The read changes the state of the highest pending interrupt from
-pending to active in the interrupt controller. The value read is returned
-and is the id of the interrupt whose state has been changed.
-
-The TSP uses this API to start processing of the secure physical timer
-interrupt.
-
-
-### Function : plat_ic_end_of_interrupt() [mandatory]
-
- Argument : uint32_t
- Return : void
-
-This API is used by the CPU to indicate to the platform IC that processing of
-the interrupt corresponding to the id (passed as the parameter) has
-finished. The id should be the same as the id returned by the
-`plat_ic_acknowledge_interrupt()` API.
-
-ARM standard platforms write the id to the _End of Interrupt Register_
-(`GICC_EOIR`) in case of GICv2, and to `ICC_EOIR0_EL1` or `ICC_EOIR1_EL1`
-system register in case of GICv3 depending on where the API is invoked from,
-EL3 or S-EL1. This deactivates the corresponding interrupt in the interrupt
-controller.
-
-The TSP uses this API to finish processing of the secure physical timer
-interrupt.
-
-
-### Function : plat_ic_get_interrupt_type() [mandatory]
-
- Argument : uint32_t
- Return : uint32_t
-
-This API returns the type of the interrupt id passed as the parameter.
-`INTR_TYPE_INVAL` is returned if the id is invalid. If the id is valid, a valid
-interrupt type (one of `INTR_TYPE_EL3`, `INTR_TYPE_S_EL1` and `INTR_TYPE_NS`) is
-returned depending upon how the interrupt has been configured by the platform
-IC. This API must be invoked at EL3.
-
-ARM standard platforms using GICv2 configures S-EL1 interrupts as Group0 interrupts
-and Non-secure interrupts as Group1 interrupts. It reads the group value
-corresponding to the interrupt id from the relevant _Interrupt Group Register_
-(`GICD_IGROUPRn`). It uses the group value to determine the type of interrupt.
-
-In the case of ARM standard platforms using GICv3, both the _Interrupt Group
-Register_ (`GICD_IGROUPRn`) and _Interrupt Group Modifier Register_
-(`GICD_IGRPMODRn`) is read to figure out whether the interrupt is configured
-as Group 0 secure interrupt, Group 1 secure interrupt or Group 1 NS interrupt.
-
-
-3.7 Crash Reporting mechanism (in BL31)
-----------------------------------------------
-BL31 implements a crash reporting mechanism which prints the various registers
-of the CPU to enable quick crash analysis and debugging. It requires that a
-console is designated as the crash console by the platform which will be used to
-print the register dump.
-
-The following functions must be implemented by the platform if it wants crash
-reporting mechanism in BL31. The functions are implemented in assembly so that
-they can be invoked without a C Runtime stack.
-
-### Function : plat_crash_console_init
-
- Argument : void
- Return : int
-
-This API is used by the crash reporting mechanism to initialize the crash
-console. It must only use the general purpose registers x0 to x4 to do the
-initialization and returns 1 on success.
-
-### Function : plat_crash_console_putc
-
- Argument : int
- Return : int
-
-This API is used by the crash reporting mechanism to print a character on the
-designated crash console. It must only use general purpose registers x1 and
-x2 to do its work. The parameter and the return value are in general purpose
-register x0.
-
-### Function : plat_crash_console_flush
-
- Argument : void
- Return : int
-
-This API is used by the crash reporting mechanism to force write of all buffered
-data on the designated crash console. It should only use general purpose
-registers x0 and x1 to do its work. The return value is 0 on successful
-completion; otherwise the return value is -1.
-
-
-4. Build flags
----------------
-
-* **ENABLE_PLAT_COMPAT**
- All the platforms ports conforming to this API specification should define
- the build flag `ENABLE_PLAT_COMPAT` to 0 as the compatibility layer should
- be disabled. For more details on compatibility layer, refer
- [Migration Guide].
-
-There are some build flags which can be defined by the platform to control
-inclusion or exclusion of certain BL stages from the FIP image. These flags
-need to be defined in the platform makefile which will get included by the
-build system.
-
-* **NEED_BL33**
- By default, this flag is defined `yes` by the build system and `BL33`
- build option should be supplied as a build option. The platform has the
- option of excluding the BL33 image in the `fip` image by defining this flag
- to `no`. If any of the options `EL3_PAYLOAD_BASE` or `PRELOADED_BL33_BASE`
- are used, this flag will be set to `no` automatically.
-
-5. C Library
--------------
-
-To avoid subtle toolchain behavioral dependencies, the header files provided
-by the compiler are not used. The software is built with the `-nostdinc` flag
-to ensure no headers are included from the toolchain inadvertently. Instead the
-required headers are included in the ARM Trusted Firmware source tree. The
-library only contains those C library definitions required by the local
-implementation. If more functionality is required, the needed library functions
-will need to be added to the local implementation.
-
-Versions of [FreeBSD] headers can be found in `include/lib/stdlib`. Some of
-these headers have been cut down in order to simplify the implementation. In
-order to minimize changes to the header files, the [FreeBSD] layout has been
-maintained. The generic C library definitions can be found in
-`include/lib/stdlib` with more system and machine specific declarations in
-`include/lib/stdlib/sys` and `include/lib/stdlib/machine`.
-
-The local C library implementations can be found in `lib/stdlib`. In order to
-extend the C library these files may need to be modified. It is recommended to
-use a release version of [FreeBSD] as a starting point.
-
-The C library header files in the [FreeBSD] source tree are located in the
-`include` and `sys/sys` directories. [FreeBSD] machine specific definitions
-can be found in the `sys/<machine-type>` directories. These files define things
-like 'the size of a pointer' and 'the range of an integer'. Since an AArch64
-port for [FreeBSD] does not yet exist, the machine specific definitions are
-based on existing machine types with similar properties (for example SPARC64).
-
-Where possible, C library function implementations were taken from [FreeBSD]
-as found in the `lib/libc` directory.
-
-A copy of the [FreeBSD] sources can be downloaded with `git`.
-
- git clone git://github.com/freebsd/freebsd.git -b origin/release/9.2.0
-
-
-6. Storage abstraction layer
------------------------------
-
-In order to improve platform independence and portability an storage abstraction
-layer is used to load data from non-volatile platform storage.
-
-Each platform should register devices and their drivers via the Storage layer.
-These drivers then need to be initialized by bootloader phases as
-required in their respective `blx_platform_setup()` functions. Currently
-storage access is only required by BL1 and BL2 phases. The `load_image()`
-function uses the storage layer to access non-volatile platform storage.
-
-It is mandatory to implement at least one storage driver. For the ARM
-development platforms the Firmware Image Package (FIP) driver is provided as
-the default means to load data from storage (see the "Firmware Image Package"
-section in the [User Guide]). The storage layer is described in the header file
-`include/drivers/io/io_storage.h`. The implementation of the common library
-is in `drivers/io/io_storage.c` and the driver files are located in
-`drivers/io/`.
-
-Each IO driver must provide `io_dev_*` structures, as described in
-`drivers/io/io_driver.h`. These are returned via a mandatory registration
-function that is called on platform initialization. The semi-hosting driver
-implementation in `io_semihosting.c` can be used as an example.
-
-The Storage layer provides mechanisms to initialize storage devices before
-IO operations are called. The basic operations supported by the layer
-include `open()`, `close()`, `read()`, `write()`, `size()` and `seek()`.
-Drivers do not have to implement all operations, but each platform must
-provide at least one driver for a device capable of supporting generic
-operations such as loading a bootloader image.
-
-The current implementation only allows for known images to be loaded by the
-firmware. These images are specified by using their identifiers, as defined in
-[include/plat/common/platform_def.h] (or a separate header file included from
-there). The platform layer (`plat_get_image_source()`) then returns a reference
-to a device and a driver-specific `spec` which will be understood by the driver
-to allow access to the image data.
-
-The layer is designed in such a way that is it possible to chain drivers with
-other drivers. For example, file-system drivers may be implemented on top of
-physical block devices, both represented by IO devices with corresponding
-drivers. In such a case, the file-system "binding" with the block device may
-be deferred until the file-system device is initialised.
-
-The abstraction currently depends on structures being statically allocated
-by the drivers and callers, as the system does not yet provide a means of
-dynamically allocating memory. This may also have the affect of limiting the
-amount of open resources per driver.
-
-
-- - - - - - - - - - - - - - - - - - - - - - - - - -
-
-_Copyright (c) 2013-2016, ARM Limited and Contributors. All rights reserved._
-
-
-[ARM GIC Architecture Specification 2.0]: http://infocenter.arm.com/help/topic/com.arm.doc.ihi0048b/index.html
-[ARM GIC Architecture Specification 3.0]: http://infocenter.arm.com/help/topic/com.arm.doc.ihi0069b/index.html
-[IMF Design Guide]: interrupt-framework-design.md
-[User Guide]: user-guide.md
-[FreeBSD]: http://www.freebsd.org
-[Firmware Design]: firmware-design.md
-[Power Domain Topology Design]: psci-pd-tree.md
-[PSCI]: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
-[Migration Guide]: platform-migration-guide.md
-[Firmware Update]: firmware-update.md
-
-[plat/common/aarch64/platform_mp_stack.S]: ../plat/common/aarch64/platform_mp_stack.S
-[plat/common/aarch64/platform_up_stack.S]: ../plat/common/aarch64/platform_up_stack.S
-[plat/arm/board/fvp/fvp_pm.c]: ../plat/arm/board/fvp/fvp_pm.c
-[include/common/bl_common.h]: ../include/common/bl_common.h
-[include/lib/aarch32/arch.h]: ../include/lib/aarch32/arch.h
-[include/plat/arm/common/arm_def.h]: ../include/plat/arm/common/arm_def.h
-[include/plat/common/common_def.h]: ../include/plat/common/common_def.h
-[include/plat/common/platform.h]: ../include/plat/common/platform.h
-[include/plat/arm/common/plat_arm.h]: ../include/plat/arm/common/plat_arm.h]
diff --git a/docs/porting-guide.rst b/docs/porting-guide.rst
new file mode 100644
index 0000000..66fe0f1
--- /dev/null
+++ b/docs/porting-guide.rst
@@ -0,0 +1,2599 @@
+ARM Trusted Firmware Porting Guide
+==================================
+
+
+.. section-numbering::
+ :suffix: .
+
+.. contents::
+
+--------------
+
+Introduction
+------------
+
+Please note that this document has been updated for the new platform API
+as required by the PSCI v1.0 implementation. Please refer to the
+`Migration Guide`_ for the previous platform API.
+
+Porting the ARM Trusted Firmware to a new platform involves making some
+mandatory and optional modifications for both the cold and warm boot paths.
+Modifications consist of:
+
+- Implementing a platform-specific function or variable,
+- Setting up the execution context in a certain way, or
+- Defining certain constants (for example #defines).
+
+The platform-specific functions and variables are declared in
+`include/plat/common/platform.h`_. The firmware provides a default implementation
+of variables and functions to fulfill the optional requirements. These
+implementations are all weakly defined; they are provided to ease the porting
+effort. Each platform port can override them with its own implementation if the
+default implementation is inadequate.
+
+Platform ports that want to be aligned with standard ARM platforms (for example
+FVP and Juno) may also use `include/plat/arm/common/plat\_arm.h`_ and the
+corresponding source files in ``plat/arm/common/``. These provide standard
+implementations for some of the required platform porting functions. However,
+using these functions requires the platform port to implement additional
+ARM standard platform porting functions. These additional functions are not
+documented here.
+
+Some modifications are common to all Boot Loader (BL) stages. Section 2
+discusses these in detail. The subsequent sections discuss the remaining
+modifications for each BL stage in detail.
+
+This document should be read in conjunction with the ARM Trusted Firmware
+`User Guide`_.
+
+Common modifications
+--------------------
+
+This section covers the modifications that should be made by the platform for
+each BL stage to correctly port the firmware stack. They are categorized as
+either mandatory or optional.
+
+Common mandatory modifications
+------------------------------
+
+A platform port must enable the Memory Management Unit (MMU) as well as the
+instruction and data caches for each BL stage. Setting up the translation
+tables is the responsibility of the platform port because memory maps differ
+across platforms. A memory translation library (see ``lib/xlat_tables/``) is
+provided to help in this setup. Note that although this library supports
+non-identity mappings, this is intended only for re-mapping peripheral physical
+addresses and allows platforms with high I/O addresses to reduce their virtual
+address space. All other addresses corresponding to code and data must currently
+use an identity mapping.
+
+In ARM standard platforms, each BL stage configures the MMU in the
+platform-specific architecture setup function, ``blX_plat_arch_setup()``, and uses
+an identity mapping for all addresses.
+
+If the build option ``USE_COHERENT_MEM`` is enabled, each platform can allocate a
+block of identity mapped secure memory with Device-nGnRE attributes aligned to
+page boundary (4K) for each BL stage. All sections which allocate coherent
+memory are grouped under ``coherent_ram``. For ex: Bakery locks are placed in a
+section identified by name ``bakery_lock`` inside ``coherent_ram`` so that its
+possible for the firmware to place variables in it using the following C code
+directive:
+
+::
+
+ __section("bakery_lock")
+
+Or alternatively the following assembler code directive:
+
+::
+
+ .section bakery_lock
+
+The ``coherent_ram`` section is a sum of all sections like ``bakery_lock`` which are
+used to allocate any data structures that are accessed both when a CPU is
+executing with its MMU and caches enabled, and when it's running with its MMU
+and caches disabled. Examples are given below.
+
+The following variables, functions and constants must be defined by the platform
+for the firmware to work correctly.
+
+File : platform\_def.h [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Each platform must ensure that a header file of this name is in the system
+include path with the following constants defined. This may require updating the
+list of ``PLAT_INCLUDES`` in the ``platform.mk`` file. In the ARM development
+platforms, this file is found in ``plat/arm/board/<plat_name>/include/``.
+
+Platform ports may optionally use the file `include/plat/common/common\_def.h`_,
+which provides typical values for some of the constants below. These values are
+likely to be suitable for all platform ports.
+
+Platform ports that want to be aligned with standard ARM platforms (for example
+FVP and Juno) may also use `include/plat/arm/common/arm\_def.h`_, which provides
+standard values for some of the constants below. However, this requires the
+platform port to define additional platform porting constants in
+``platform_def.h``. These additional constants are not documented here.
+
+- **#define : PLATFORM\_LINKER\_FORMAT**
+
+ Defines the linker format used by the platform, for example
+ ``elf64-littleaarch64``.
+
+- **#define : PLATFORM\_LINKER\_ARCH**
+
+ Defines the processor architecture for the linker by the platform, for
+ example ``aarch64``.
+
+- **#define : PLATFORM\_STACK\_SIZE**
+
+ Defines the normal stack memory available to each CPU. This constant is used
+ by `plat/common/aarch64/platform\_mp\_stack.S`_ and
+ `plat/common/aarch64/platform\_up\_stack.S`_.
+
+- **define : CACHE\_WRITEBACK\_GRANULE**
+
+ Defines the size in bits of the largest cache line across all the cache
+ levels in the platform.
+
+- **#define : FIRMWARE\_WELCOME\_STR**
+
+ Defines the character string printed by BL1 upon entry into the ``bl1_main()``
+ function.
+
+- **#define : PLATFORM\_CORE\_COUNT**
+
+ Defines the total number of CPUs implemented by the platform across all
+ clusters in the system.
+
+- **#define : PLAT\_NUM\_PWR\_DOMAINS**
+
+ Defines the total number of nodes in the power domain topology
+ tree at all the power domain levels used by the platform.
+ This macro is used by the PSCI implementation to allocate
+ data structures to represent power domain topology.
+
+- **#define : PLAT\_MAX\_PWR\_LVL**
+
+ Defines the maximum power domain level that the power management operations
+ should apply to. More often, but not always, the power domain level
+ corresponds to affinity level. This macro allows the PSCI implementation
+ to know the highest power domain level that it should consider for power
+ management operations in the system that the platform implements. For
+ example, the Base AEM FVP implements two clusters with a configurable
+ number of CPUs and it reports the maximum power domain level as 1.
+
+- **#define : PLAT\_MAX\_OFF\_STATE**
+
+ Defines the local power state corresponding to the deepest power down
+ possible at every power domain level in the platform. The local power
+ states for each level may be sparsely allocated between 0 and this value
+ with 0 being reserved for the RUN state. The PSCI implementation uses this
+ value to initialize the local power states of the power domain nodes and
+ to specify the requested power state for a PSCI\_CPU\_OFF call.
+
+- **#define : PLAT\_MAX\_RET\_STATE**
+
+ Defines the local power state corresponding to the deepest retention state
+ possible at every power domain level in the platform. This macro should be
+ a value less than PLAT\_MAX\_OFF\_STATE and greater than 0. It is used by the
+ PSCI implementation to distinguish between retention and power down local
+ power states within PSCI\_CPU\_SUSPEND call.
+
+- **#define : PLAT\_MAX\_PWR\_LVL\_STATES**
+
+ Defines the maximum number of local power states per power domain level
+ that the platform supports. The default value of this macro is 2 since
+ most platforms just support a maximum of two local power states at each
+ power domain level (power-down and retention). If the platform needs to
+ account for more local power states, then it must redefine this macro.
+
+ Currently, this macro is used by the Generic PSCI implementation to size
+ the array used for PSCI\_STAT\_COUNT/RESIDENCY accounting.
+
+- **#define : BL1\_RO\_BASE**
+
+ Defines the base address in secure ROM where BL1 originally lives. Must be
+ aligned on a page-size boundary.
+
+- **#define : BL1\_RO\_LIMIT**
+
+ Defines the maximum address in secure ROM that BL1's actual content (i.e.
+ excluding any data section allocated at runtime) can occupy.
+
+- **#define : BL1\_RW\_BASE**
+
+ Defines the base address in secure RAM where BL1's read-write data will live
+ at runtime. Must be aligned on a page-size boundary.
+
+- **#define : BL1\_RW\_LIMIT**
+
+ Defines the maximum address in secure RAM that BL1's read-write data can
+ occupy at runtime.
+
+- **#define : BL2\_BASE**
+
+ Defines the base address in secure RAM where BL1 loads the BL2 binary image.
+ Must be aligned on a page-size boundary.
+
+- **#define : BL2\_LIMIT**
+
+ Defines the maximum address in secure RAM that the BL2 image can occupy.
+
+- **#define : BL31\_BASE**
+
+ Defines the base address in secure RAM where BL2 loads the BL31 binary
+ image. Must be aligned on a page-size boundary.
+
+- **#define : BL31\_LIMIT**
+
+ Defines the maximum address in secure RAM that the BL31 image can occupy.
+
+For every image, the platform must define individual identifiers that will be
+used by BL1 or BL2 to load the corresponding image into memory from non-volatile
+storage. For the sake of performance, integer numbers will be used as
+identifiers. The platform will use those identifiers to return the relevant
+information about the image to be loaded (file handler, load address,
+authentication information, etc.). The following image identifiers are
+mandatory:
+
+- **#define : BL2\_IMAGE\_ID**
+
+ BL2 image identifier, used by BL1 to load BL2.
+
+- **#define : BL31\_IMAGE\_ID**
+
+ BL31 image identifier, used by BL2 to load BL31.
+
+- **#define : BL33\_IMAGE\_ID**
+
+ BL33 image identifier, used by BL2 to load BL33.
+
+If Trusted Board Boot is enabled, the following certificate identifiers must
+also be defined:
+
+- **#define : TRUSTED\_BOOT\_FW\_CERT\_ID**
+
+ BL2 content certificate identifier, used by BL1 to load the BL2 content
+ certificate.
+
+- **#define : TRUSTED\_KEY\_CERT\_ID**
+
+ Trusted key certificate identifier, used by BL2 to load the trusted key
+ certificate.
+
+- **#define : SOC\_FW\_KEY\_CERT\_ID**
+
+ BL31 key certificate identifier, used by BL2 to load the BL31 key
+ certificate.
+
+- **#define : SOC\_FW\_CONTENT\_CERT\_ID**
+
+ BL31 content certificate identifier, used by BL2 to load the BL31 content
+ certificate.
+
+- **#define : NON\_TRUSTED\_FW\_KEY\_CERT\_ID**
+
+ BL33 key certificate identifier, used by BL2 to load the BL33 key
+ certificate.
+
+- **#define : NON\_TRUSTED\_FW\_CONTENT\_CERT\_ID**
+
+ BL33 content certificate identifier, used by BL2 to load the BL33 content
+ certificate.
+
+- **#define : FWU\_CERT\_ID**
+
+ Firmware Update (FWU) certificate identifier, used by NS\_BL1U to load the
+ FWU content certificate.
+
+- **#define : PLAT\_CRYPTOCELL\_BASE**
+
+ This defines the base address of ARM® TrustZone® CryptoCell and must be
+ defined if CryptoCell crypto driver is used for Trusted Board Boot. For
+ capable ARM platforms, this driver is used if ``ARM_CRYPTOCELL_INTEG`` is
+ set.
+
+If the AP Firmware Updater Configuration image, BL2U is used, the following
+must also be defined:
+
+- **#define : BL2U\_BASE**
+
+ Defines the base address in secure memory where BL1 copies the BL2U binary
+ image. Must be aligned on a page-size boundary.
+
+- **#define : BL2U\_LIMIT**
+
+ Defines the maximum address in secure memory that the BL2U image can occupy.
+
+- **#define : BL2U\_IMAGE\_ID**
+
+ BL2U image identifier, used by BL1 to fetch an image descriptor
+ corresponding to BL2U.
+
+If the SCP Firmware Update Configuration Image, SCP\_BL2U is used, the following
+must also be defined:
+
+- **#define : SCP\_BL2U\_IMAGE\_ID**
+
+ SCP\_BL2U image identifier, used by BL1 to fetch an image descriptor
+ corresponding to SCP\_BL2U.
+ NOTE: TF does not provide source code for this image.
+
+If the Non-Secure Firmware Updater ROM, NS\_BL1U is used, the following must
+also be defined:
+
+- **#define : NS\_BL1U\_BASE**
+
+ Defines the base address in non-secure ROM where NS\_BL1U executes.
+ Must be aligned on a page-size boundary.
+ NOTE: TF does not provide source code for this image.
+
+- **#define : NS\_BL1U\_IMAGE\_ID**
+
+ NS\_BL1U image identifier, used by BL1 to fetch an image descriptor
+ corresponding to NS\_BL1U.
+
+If the Non-Secure Firmware Updater, NS\_BL2U is used, the following must also
+be defined:
+
+- **#define : NS\_BL2U\_BASE**
+
+ Defines the base address in non-secure memory where NS\_BL2U executes.
+ Must be aligned on a page-size boundary.
+ NOTE: TF does not provide source code for this image.
+
+- **#define : NS\_BL2U\_IMAGE\_ID**
+
+ NS\_BL2U image identifier, used by BL1 to fetch an image descriptor
+ corresponding to NS\_BL2U.
+
+For the the Firmware update capability of TRUSTED BOARD BOOT, the following
+macros may also be defined:
+
+- **#define : PLAT\_FWU\_MAX\_SIMULTANEOUS\_IMAGES**
+
+ Total number of images that can be loaded simultaneously. If the platform
+ doesn't specify any value, it defaults to 10.
+
+If a SCP\_BL2 image is supported by the platform, the following constants must
+also be defined:
+
+- **#define : SCP\_BL2\_IMAGE\_ID**
+
+ SCP\_BL2 image identifier, used by BL2 to load SCP\_BL2 into secure memory
+ from platform storage before being transfered to the SCP.
+
+- **#define : SCP\_FW\_KEY\_CERT\_ID**
+
+ SCP\_BL2 key certificate identifier, used by BL2 to load the SCP\_BL2 key
+ certificate (mandatory when Trusted Board Boot is enabled).
+
+- **#define : SCP\_FW\_CONTENT\_CERT\_ID**
+
+ SCP\_BL2 content certificate identifier, used by BL2 to load the SCP\_BL2
+ content certificate (mandatory when Trusted Board Boot is enabled).
+
+If a BL32 image is supported by the platform, the following constants must
+also be defined:
+
+- **#define : BL32\_IMAGE\_ID**
+
+ BL32 image identifier, used by BL2 to load BL32.
+
+- **#define : TRUSTED\_OS\_FW\_KEY\_CERT\_ID**
+
+ BL32 key certificate identifier, used by BL2 to load the BL32 key
+ certificate (mandatory when Trusted Board Boot is enabled).
+
+- **#define : TRUSTED\_OS\_FW\_CONTENT\_CERT\_ID**
+
+ BL32 content certificate identifier, used by BL2 to load the BL32 content
+ certificate (mandatory when Trusted Board Boot is enabled).
+
+- **#define : BL32\_BASE**
+
+ Defines the base address in secure memory where BL2 loads the BL32 binary
+ image. Must be aligned on a page-size boundary.
+
+- **#define : BL32\_LIMIT**
+
+ Defines the maximum address that the BL32 image can occupy.
+
+If the Test Secure-EL1 Payload (TSP) instantiation of BL32 is supported by the
+platform, the following constants must also be defined:
+
+- **#define : TSP\_SEC\_MEM\_BASE**
+
+ Defines the base address of the secure memory used by the TSP image on the
+ platform. This must be at the same address or below ``BL32_BASE``.
+
+- **#define : TSP\_SEC\_MEM\_SIZE**
+
+ Defines the size of the secure memory used by the BL32 image on the
+ platform. ``TSP_SEC_MEM_BASE`` and ``TSP_SEC_MEM_SIZE`` must fully accomodate
+ the memory required by the BL32 image, defined by ``BL32_BASE`` and
+ ``BL32_LIMIT``.
+
+- **#define : TSP\_IRQ\_SEC\_PHY\_TIMER**
+
+ Defines the ID of the secure physical generic timer interrupt used by the
+ TSP's interrupt handling code.
+
+If the platform port uses the translation table library code, the following
+constants must also be defined:
+
+- **#define : PLAT\_XLAT\_TABLES\_DYNAMIC**
+
+ Optional flag that can be set per-image to enable the dynamic allocation of
+ regions even when the MMU is enabled. If not defined, only static
+ functionality will be available, if defined and set to 1 it will also
+ include the dynamic functionality.
+
+- **#define : MAX\_XLAT\_TABLES**
+
+ Defines the maximum number of translation tables that are allocated by the
+ translation table library code. To minimize the amount of runtime memory
+ used, choose the smallest value needed to map the required virtual addresses
+ for each BL stage. If ``PLAT_XLAT_TABLES_DYNAMIC`` flag is enabled for a BL
+ image, ``MAX_XLAT_TABLES`` must be defined to accommodate the dynamic regions
+ as well.
+
+- **#define : MAX\_MMAP\_REGIONS**
+
+ Defines the maximum number of regions that are allocated by the translation
+ table library code. A region consists of physical base address, virtual base
+ address, size and attributes (Device/Memory, RO/RW, Secure/Non-Secure), as
+ defined in the ``mmap_region_t`` structure. The platform defines the regions
+ that should be mapped. Then, the translation table library will create the
+ corresponding tables and descriptors at runtime. To minimize the amount of
+ runtime memory used, choose the smallest value needed to register the
+ required regions for each BL stage. If ``PLAT_XLAT_TABLES_DYNAMIC`` flag is
+ enabled for a BL image, ``MAX_MMAP_REGIONS`` must be defined to accommodate
+ the dynamic regions as well.
+
+- **#define : ADDR\_SPACE\_SIZE**
+
+ Defines the total size of the address space in bytes. For example, for a 32
+ bit address space, this value should be ``(1ull << 32)``. This definition is
+ now deprecated, platforms should use ``PLAT_PHY_ADDR_SPACE_SIZE`` and
+ ``PLAT_VIRT_ADDR_SPACE_SIZE`` instead.
+
+- **#define : PLAT\_VIRT\_ADDR\_SPACE\_SIZE**
+
+ Defines the total size of the virtual address space in bytes. For example,
+ for a 32 bit virtual address space, this value should be ``(1ull << 32)``.
+
+- **#define : PLAT\_PHY\_ADDR\_SPACE\_SIZE**
+
+ Defines the total size of the physical address space in bytes. For example,
+ for a 32 bit physical address space, this value should be ``(1ull << 32)``.
+
+If the platform port uses the IO storage framework, the following constants
+must also be defined:
+
+- **#define : MAX\_IO\_DEVICES**
+
+ Defines the maximum number of registered IO devices. Attempting to register
+ more devices than this value using ``io_register_device()`` will fail with
+ -ENOMEM.
+
+- **#define : MAX\_IO\_HANDLES**
+
+ Defines the maximum number of open IO handles. Attempting to open more IO
+ entities than this value using ``io_open()`` will fail with -ENOMEM.
+
+- **#define : MAX\_IO\_BLOCK\_DEVICES**
+
+ Defines the maximum number of registered IO block devices. Attempting to
+ register more devices this value using ``io_dev_open()`` will fail
+ with -ENOMEM. MAX\_IO\_BLOCK\_DEVICES should be less than MAX\_IO\_DEVICES.
+ With this macro, multiple block devices could be supported at the same
+ time.
+
+If the platform needs to allocate data within the per-cpu data framework in
+BL31, it should define the following macro. Currently this is only required if
+the platform decides not to use the coherent memory section by undefining the
+``USE_COHERENT_MEM`` build flag. In this case, the framework allocates the
+required memory within the the per-cpu data to minimize wastage.
+
+- **#define : PLAT\_PCPU\_DATA\_SIZE**
+
+ Defines the memory (in bytes) to be reserved within the per-cpu data
+ structure for use by the platform layer.
+
+The following constants are optional. They should be defined when the platform
+memory layout implies some image overlaying like in ARM standard platforms.
+
+- **#define : BL31\_PROGBITS\_LIMIT**
+
+ Defines the maximum address in secure RAM that the BL31's progbits sections
+ can occupy.
+
+- **#define : TSP\_PROGBITS\_LIMIT**
+
+ Defines the maximum address that the TSP's progbits sections can occupy.
+
+If the platform port uses the PL061 GPIO driver, the following constant may
+optionally be defined:
+
+- **PLAT\_PL061\_MAX\_GPIOS**
+ Maximum number of GPIOs required by the platform. This allows control how
+ much memory is allocated for PL061 GPIO controllers. The default value is
+
+ #. $(eval $(call add\_define,PLAT\_PL061\_MAX\_GPIOS))
+
+If the platform port uses the partition driver, the following constant may
+optionally be defined:
+
+- **PLAT\_PARTITION\_MAX\_ENTRIES**
+ Maximum number of partition entries required by the platform. This allows
+ control how much memory is allocated for partition entries. The default
+ value is 128.
+ `For example, define the build flag in platform.mk`_:
+ PLAT\_PARTITION\_MAX\_ENTRIES := 12
+ $(eval $(call add\_define,PLAT\_PARTITION\_MAX\_ENTRIES))
+
+The following constant is optional. It should be defined to override the default
+behaviour of the ``assert()`` function (for example, to save memory).
+
+- **PLAT\_LOG\_LEVEL\_ASSERT**
+ If ``PLAT_LOG_LEVEL_ASSERT`` is higher or equal than ``LOG_LEVEL_VERBOSE``,
+ ``assert()`` prints the name of the file, the line number and the asserted
+ expression. Else if it is higher than ``LOG_LEVEL_INFO``, it prints the file
+ name and the line number. Else if it is lower than ``LOG_LEVEL_INFO``, it
+ doesn't print anything to the console. If ``PLAT_LOG_LEVEL_ASSERT`` isn't
+ defined, it defaults to ``LOG_LEVEL``.
+
+File : plat\_macros.S [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Each platform must ensure a file of this name is in the system include path with
+the following macro defined. In the ARM development platforms, this file is
+found in ``plat/arm/board/<plat_name>/include/plat_macros.S``.
+
+- **Macro : plat\_crash\_print\_regs**
+
+ This macro allows the crash reporting routine to print relevant platform
+ registers in case of an unhandled exception in BL31. This aids in debugging
+ and this macro can be defined to be empty in case register reporting is not
+ desired.
+
+ For instance, GIC or interconnect registers may be helpful for
+ troubleshooting.
+
+Handling Reset
+--------------
+
+BL1 by default implements the reset vector where execution starts from a cold
+or warm boot. BL31 can be optionally set as a reset vector using the
+``RESET_TO_BL31`` make variable.
+
+For each CPU, the reset vector code is responsible for the following tasks:
+
+#. Distinguishing between a cold boot and a warm boot.
+
+#. In the case of a cold boot and the CPU being a secondary CPU, ensuring that
+ the CPU is placed in a platform-specific state until the primary CPU
+ performs the necessary steps to remove it from this state.
+
+#. In the case of a warm boot, ensuring that the CPU jumps to a platform-
+ specific address in the BL31 image in the same processor mode as it was
+ when released from reset.
+
+The following functions need to be implemented by the platform port to enable
+reset vector code to perform the above tasks.
+
+Function : plat\_get\_my\_entrypoint() [mandatory when PROGRAMMABLE\_RESET\_ADDRESS == 0]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : uintptr_t
+
+This function is called with the MMU and caches disabled
+(``SCTLR_EL3.M`` = 0 and ``SCTLR_EL3.C`` = 0). The function is responsible for
+distinguishing between a warm and cold reset for the current CPU using
+platform-specific means. If it's a warm reset, then it returns the warm
+reset entrypoint point provided to ``plat_setup_psci_ops()`` during
+BL31 initialization. If it's a cold reset then this function must return zero.
+
+This function does not follow the Procedure Call Standard used by the
+Application Binary Interface for the ARM 64-bit architecture. The caller should
+not assume that callee saved registers are preserved across a call to this
+function.
+
+This function fulfills requirement 1 and 3 listed above.
+
+Note that for platforms that support programming the reset address, it is
+expected that a CPU will start executing code directly at the right address,
+both on a cold and warm reset. In this case, there is no need to identify the
+type of reset nor to query the warm reset entrypoint. Therefore, implementing
+this function is not required on such platforms.
+
+Function : plat\_secondary\_cold\_boot\_setup() [mandatory when COLD\_BOOT\_SINGLE\_CPU == 0]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+
+This function is called with the MMU and data caches disabled. It is responsible
+for placing the executing secondary CPU in a platform-specific state until the
+primary CPU performs the necessary actions to bring it out of that state and
+allow entry into the OS. This function must not return.
+
+In the ARM FVP port, when using the normal boot flow, each secondary CPU powers
+itself off. The primary CPU is responsible for powering up the secondary CPUs
+when normal world software requires them. When booting an EL3 payload instead,
+they stay powered on and are put in a holding pen until their mailbox gets
+populated.
+
+This function fulfills requirement 2 above.
+
+Note that for platforms that can't release secondary CPUs out of reset, only the
+primary CPU will execute the cold boot code. Therefore, implementing this
+function is not required on such platforms.
+
+Function : plat\_is\_my\_cpu\_primary() [mandatory when COLD\_BOOT\_SINGLE\_CPU == 0]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : unsigned int
+
+This function identifies whether the current CPU is the primary CPU or a
+secondary CPU. A return value of zero indicates that the CPU is not the
+primary CPU, while a non-zero return value indicates that the CPU is the
+primary CPU.
+
+Note that for platforms that can't release secondary CPUs out of reset, only the
+primary CPU will execute the cold boot code. Therefore, there is no need to
+distinguish between primary and secondary CPUs and implementing this function is
+not required.
+
+Function : platform\_mem\_init() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : void
+
+This function is called before any access to data is made by the firmware, in
+order to carry out any essential memory initialization.
+
+Function: plat\_get\_rotpk\_info()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void *, void **, unsigned int *, unsigned int *
+ Return : int
+
+This function is mandatory when Trusted Board Boot is enabled. It returns a
+pointer to the ROTPK stored in the platform (or a hash of it) and its length.
+The ROTPK must be encoded in DER format according to the following ASN.1
+structure:
+
+::
+
+ AlgorithmIdentifier ::= SEQUENCE {
+ algorithm OBJECT IDENTIFIER,
+ parameters ANY DEFINED BY algorithm OPTIONAL
+ }
+
+ SubjectPublicKeyInfo ::= SEQUENCE {
+ algorithm AlgorithmIdentifier,
+ subjectPublicKey BIT STRING
+ }
+
+In case the function returns a hash of the key:
+
+::
+
+ DigestInfo ::= SEQUENCE {
+ digestAlgorithm AlgorithmIdentifier,
+ digest OCTET STRING
+ }
+
+The function returns 0 on success. Any other value is treated as error by the
+Trusted Board Boot. The function also reports extra information related
+to the ROTPK in the flags parameter:
+
+::
+
+ ROTPK_IS_HASH : Indicates that the ROTPK returned by the platform is a
+ hash.
+ ROTPK_NOT_DEPLOYED : This allows the platform to skip certificate ROTPK
+ verification while the platform ROTPK is not deployed.
+ When this flag is set, the function does not need to
+ return a platform ROTPK, and the authentication
+ framework uses the ROTPK in the certificate without
+ verifying it against the platform value. This flag
+ must not be used in a deployed production environment.
+
+Function: plat\_get\_nv\_ctr()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void *, unsigned int *
+ Return : int
+
+This function is mandatory when Trusted Board Boot is enabled. It returns the
+non-volatile counter value stored in the platform in the second argument. The
+cookie in the first argument may be used to select the counter in case the
+platform provides more than one (for example, on platforms that use the default
+TBBR CoT, the cookie will correspond to the OID values defined in
+TRUSTED\_FW\_NVCOUNTER\_OID or NON\_TRUSTED\_FW\_NVCOUNTER\_OID).
+
+The function returns 0 on success. Any other value means the counter value could
+not be retrieved from the platform.
+
+Function: plat\_set\_nv\_ctr()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void *, unsigned int
+ Return : int
+
+This function is mandatory when Trusted Board Boot is enabled. It sets a new
+counter value in the platform. The cookie in the first argument may be used to
+select the counter (as explained in plat\_get\_nv\_ctr()). The second argument is
+the updated counter value to be written to the NV counter.
+
+The function returns 0 on success. Any other value means the counter value could
+not be updated.
+
+Function: plat\_set\_nv\_ctr2()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void *, const auth_img_desc_t *, unsigned int
+ Return : int
+
+This function is optional when Trusted Board Boot is enabled. If this
+interface is defined, then ``plat_set_nv_ctr()`` need not be defined. The
+first argument passed is a cookie and is typically used to
+differentiate between a Non Trusted NV Counter and a Trusted NV
+Counter. The second argument is a pointer to an authentication image
+descriptor and may be used to decide if the counter is allowed to be
+updated or not. The third argument is the updated counter value to
+be written to the NV counter.
+
+The function returns 0 on success. Any other value means the counter value
+either could not be updated or the authentication image descriptor indicates
+that it is not allowed to be updated.
+
+Common mandatory function modifications
+---------------------------------------
+
+The following functions are mandatory functions which need to be implemented
+by the platform port.
+
+Function : plat\_my\_core\_pos()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : unsigned int
+
+This funtion returns the index of the calling CPU which is used as a
+CPU-specific linear index into blocks of memory (for example while allocating
+per-CPU stacks). This function will be invoked very early in the
+initialization sequence which mandates that this function should be
+implemented in assembly and should not rely on the avalability of a C
+runtime environment. This function can clobber x0 - x8 and must preserve
+x9 - x29.
+
+This function plays a crucial role in the power domain topology framework in
+PSCI and details of this can be found in `Power Domain Topology Design`_.
+
+Function : plat\_core\_pos\_by\_mpidr()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : u_register_t
+ Return : int
+
+This function validates the ``MPIDR`` of a CPU and converts it to an index,
+which can be used as a CPU-specific linear index into blocks of memory. In
+case the ``MPIDR`` is invalid, this function returns -1. This function will only
+be invoked by BL31 after the power domain topology is initialized and can
+utilize the C runtime environment. For further details about how ARM Trusted
+Firmware represents the power domain topology and how this relates to the
+linear CPU index, please refer `Power Domain Topology Design`_.
+
+Common optional modifications
+-----------------------------
+
+The following are helper functions implemented by the firmware that perform
+common platform-specific tasks. A platform may choose to override these
+definitions.
+
+Function : plat\_set\_my\_stack()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : void
+
+This function sets the current stack pointer to the normal memory stack that
+has been allocated for the current CPU. For BL images that only require a
+stack for the primary CPU, the UP version of the function is used. The size
+of the stack allocated to each CPU is specified by the platform defined
+constant ``PLATFORM_STACK_SIZE``.
+
+Common implementations of this function for the UP and MP BL images are
+provided in `plat/common/aarch64/platform\_up\_stack.S`_ and
+`plat/common/aarch64/platform\_mp\_stack.S`_
+
+Function : plat\_get\_my\_stack()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : uintptr_t
+
+This function returns the base address of the normal memory stack that
+has been allocated for the current CPU. For BL images that only require a
+stack for the primary CPU, the UP version of the function is used. The size
+of the stack allocated to each CPU is specified by the platform defined
+constant ``PLATFORM_STACK_SIZE``.
+
+Common implementations of this function for the UP and MP BL images are
+provided in `plat/common/aarch64/platform\_up\_stack.S`_ and
+`plat/common/aarch64/platform\_mp\_stack.S`_
+
+Function : plat\_report\_exception()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : unsigned int
+ Return : void
+
+A platform may need to report various information about its status when an
+exception is taken, for example the current exception level, the CPU security
+state (secure/non-secure), the exception type, and so on. This function is
+called in the following circumstances:
+
+- In BL1, whenever an exception is taken.
+- In BL2, whenever an exception is taken.
+
+The default implementation doesn't do anything, to avoid making assumptions
+about the way the platform displays its status information.
+
+For AArch64, this function receives the exception type as its argument.
+Possible values for exceptions types are listed in the
+`include/common/bl\_common.h`_ header file. Note that these constants are not
+related to any architectural exception code; they are just an ARM Trusted
+Firmware convention.
+
+For AArch32, this function receives the exception mode as its argument.
+Possible values for exception modes are listed in the
+`include/lib/aarch32/arch.h`_ header file.
+
+Function : plat\_reset\_handler()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : void
+
+A platform may need to do additional initialization after reset. This function
+allows the platform to do the platform specific intializations. Platform
+specific errata workarounds could also be implemented here. The api should
+preserve the values of callee saved registers x19 to x29.
+
+The default implementation doesn't do anything. If a platform needs to override
+the default implementation, refer to the `Firmware Design`_ for general
+guidelines.
+
+Function : plat\_disable\_acp()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : void
+
+This api allows a platform to disable the Accelerator Coherency Port (if
+present) during a cluster power down sequence. The default weak implementation
+doesn't do anything. Since this api is called during the power down sequence,
+it has restrictions for stack usage and it can use the registers x0 - x17 as
+scratch registers. It should preserve the value in x18 register as it is used
+by the caller to store the return address.
+
+Function : plat\_error\_handler()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : int
+ Return : void
+
+This API is called when the generic code encounters an error situation from
+which it cannot continue. It allows the platform to perform error reporting or
+recovery actions (for example, reset the system). This function must not return.
+
+The parameter indicates the type of error using standard codes from ``errno.h``.
+Possible errors reported by the generic code are:
+
+- ``-EAUTH``: a certificate or image could not be authenticated (when Trusted
+ Board Boot is enabled)
+- ``-ENOENT``: the requested image or certificate could not be found or an IO
+ error was detected
+- ``-ENOMEM``: resources exhausted. Trusted Firmware does not use dynamic
+ memory, so this error is usually an indication of an incorrect array size
+
+The default implementation simply spins.
+
+Function : plat\_panic\_handler()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : void
+
+This API is called when the generic code encounters an unexpected error
+situation from which it cannot recover. This function must not return,
+and must be implemented in assembly because it may be called before the C
+environment is initialized.
+
+Note: The address from where it was called is stored in x30 (Link Register).
+The default implementation simply spins.
+
+Function : plat\_get\_bl\_image\_load\_info()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : bl_load_info_t *
+
+This function returns pointer to the list of images that the platform has
+populated to load. This function is currently invoked in BL2 to load the
+BL3xx images, when LOAD\_IMAGE\_V2 is enabled.
+
+Function : plat\_get\_next\_bl\_params()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : bl_params_t *
+
+This function returns a pointer to the shared memory that the platform has
+kept aside to pass trusted firmware related information that next BL image
+needs. This function is currently invoked in BL2 to pass this information to
+the next BL image, when LOAD\_IMAGE\_V2 is enabled.
+
+Function : plat\_get\_stack\_protector\_canary()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : u_register_t
+
+This function returns a random value that is used to initialize the canary used
+when the stack protector is enabled with ENABLE\_STACK\_PROTECTOR. A predictable
+value will weaken the protection as the attacker could easily write the right
+value as part of the attack most of the time. Therefore, it should return a
+true random number.
+
+Note: For the protection to be effective, the global data need to be placed at
+a lower address than the stack bases. Failure to do so would allow an attacker
+to overwrite the canary as part of the stack buffer overflow attack.
+
+Function : plat\_flush\_next\_bl\_params()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : void
+
+This function flushes to main memory all the image params that are passed to
+next image. This function is currently invoked in BL2 to flush this information
+to the next BL image, when LOAD\_IMAGE\_V2 is enabled.
+
+Modifications specific to a Boot Loader stage
+---------------------------------------------
+
+Boot Loader Stage 1 (BL1)
+-------------------------
+
+BL1 implements the reset vector where execution starts from after a cold or
+warm boot. For each CPU, BL1 is responsible for the following tasks:
+
+#. Handling the reset as described in section 2.2
+
+#. In the case of a cold boot and the CPU being the primary CPU, ensuring that
+ only this CPU executes the remaining BL1 code, including loading and passing
+ control to the BL2 stage.
+
+#. Identifying and starting the Firmware Update process (if required).
+
+#. Loading the BL2 image from non-volatile storage into secure memory at the
+ address specified by the platform defined constant ``BL2_BASE``.
+
+#. Populating a ``meminfo`` structure with the following information in memory,
+ accessible by BL2 immediately upon entry.
+
+ ::
+
+ meminfo.total_base = Base address of secure RAM visible to BL2
+ meminfo.total_size = Size of secure RAM visible to BL2
+ meminfo.free_base = Base address of secure RAM available for
+ allocation to BL2
+ meminfo.free_size = Size of secure RAM available for allocation to BL2
+
+ BL1 places this ``meminfo`` structure at the beginning of the free memory
+ available for its use. Since BL1 cannot allocate memory dynamically at the
+ moment, its free memory will be available for BL2's use as-is. However, this
+ means that BL2 must read the ``meminfo`` structure before it starts using its
+ free memory (this is discussed in Section 3.2).
+
+ In future releases of the ARM Trusted Firmware it will be possible for
+ the platform to decide where it wants to place the ``meminfo`` structure for
+ BL2.
+
+ BL1 implements the ``bl1_init_bl2_mem_layout()`` function to populate the
+ BL2 ``meminfo`` structure. The platform may override this implementation, for
+ example if the platform wants to restrict the amount of memory visible to
+ BL2. Details of how to do this are given below.
+
+The following functions need to be implemented by the platform port to enable
+BL1 to perform the above tasks.
+
+Function : bl1\_early\_platform\_setup() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : void
+
+This function executes with the MMU and data caches disabled. It is only called
+by the primary CPU.
+
+On ARM standard platforms, this function:
+
+- Enables a secure instance of SP805 to act as the Trusted Watchdog.
+
+- Initializes a UART (PL011 console), which enables access to the ``printf``
+ family of functions in BL1.
+
+- Enables issuing of snoop and DVM (Distributed Virtual Memory) requests to
+ the CCI slave interface corresponding to the cluster that includes the
+ primary CPU.
+
+Function : bl1\_plat\_arch\_setup() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : void
+
+This function performs any platform-specific and architectural setup that the
+platform requires. Platform-specific setup might include configuration of
+memory controllers and the interconnect.
+
+In ARM standard platforms, this function enables the MMU.
+
+This function helps fulfill requirement 2 above.
+
+Function : bl1\_platform\_setup() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : void
+
+This function executes with the MMU and data caches enabled. It is responsible
+for performing any remaining platform-specific setup that can occur after the
+MMU and data cache have been enabled.
+
+In ARM standard platforms, this function initializes the storage abstraction
+layer used to load the next bootloader image.
+
+This function helps fulfill requirement 4 above.
+
+Function : bl1\_plat\_sec\_mem\_layout() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : meminfo *
+
+This function should only be called on the cold boot path. It executes with the
+MMU and data caches enabled. The pointer returned by this function must point to
+a ``meminfo`` structure containing the extents and availability of secure RAM for
+the BL1 stage.
+
+::
+
+ meminfo.total_base = Base address of secure RAM visible to BL1
+ meminfo.total_size = Size of secure RAM visible to BL1
+ meminfo.free_base = Base address of secure RAM available for allocation
+ to BL1
+ meminfo.free_size = Size of secure RAM available for allocation to BL1
+
+This information is used by BL1 to load the BL2 image in secure RAM. BL1 also
+populates a similar structure to tell BL2 the extents of memory available for
+its own use.
+
+This function helps fulfill requirements 4 and 5 above.
+
+Function : bl1\_init\_bl2\_mem\_layout() [optional]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : meminfo *, meminfo *
+ Return : void
+
+BL1 needs to tell the next stage the amount of secure RAM available
+for it to use. This information is populated in a ``meminfo``
+structure.
+
+Depending upon where BL2 has been loaded in secure RAM (determined by
+``BL2_BASE``), BL1 calculates the amount of free memory available for BL2 to use.
+BL1 also ensures that its data sections resident in secure RAM are not visible
+to BL2. An illustration of how this is done in ARM standard platforms is given
+in the **Memory layout on ARM development platforms** section in the
+`Firmware Design`_.
+
+Function : bl1\_plat\_prepare\_exit() [optional]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : entry_point_info_t *
+ Return : void
+
+This function is called prior to exiting BL1 in response to the
+``BL1_SMC_RUN_IMAGE`` SMC request raised by BL2. It should be used to perform
+platform specific clean up or bookkeeping operations before transferring
+control to the next image. It receives the address of the ``entry_point_info_t``
+structure passed from BL2. This function runs with MMU disabled.
+
+Function : bl1\_plat\_set\_ep\_info() [optional]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : unsigned int image_id, entry_point_info_t *ep_info
+ Return : void
+
+This function allows platforms to override ``ep_info`` for the given ``image_id``.
+
+The default implementation just returns.
+
+Function : bl1\_plat\_get\_next\_image\_id() [optional]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : unsigned int
+
+This and the following function must be overridden to enable the FWU feature.
+
+BL1 calls this function after platform setup to identify the next image to be
+loaded and executed. If the platform returns ``BL2_IMAGE_ID`` then BL1 proceeds
+with the normal boot sequence, which loads and executes BL2. If the platform
+returns a different image id, BL1 assumes that Firmware Update is required.
+
+The default implementation always returns ``BL2_IMAGE_ID``. The ARM development
+platforms override this function to detect if firmware update is required, and
+if so, return the first image in the firmware update process.
+
+Function : bl1\_plat\_get\_image\_desc() [optional]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : unsigned int image_id
+ Return : image_desc_t *
+
+BL1 calls this function to get the image descriptor information ``image_desc_t``
+for the provided ``image_id`` from the platform.
+
+The default implementation always returns a common BL2 image descriptor. ARM
+standard platforms return an image descriptor corresponding to BL2 or one of
+the firmware update images defined in the Trusted Board Boot Requirements
+specification.
+
+Function : bl1\_plat\_fwu\_done() [optional]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : unsigned int image_id, uintptr_t image_src,
+ unsigned int image_size
+ Return : void
+
+BL1 calls this function when the FWU process is complete. It must not return.
+The platform may override this function to take platform specific action, for
+example to initiate the normal boot flow.
+
+The default implementation spins forever.
+
+Function : bl1\_plat\_mem\_check() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : uintptr_t mem_base, unsigned int mem_size,
+ unsigned int flags
+ Return : int
+
+BL1 calls this function while handling FWU related SMCs, more specifically when
+copying or authenticating an image. Its responsibility is to ensure that the
+region of memory identified by ``mem_base`` and ``mem_size`` is mapped in BL1, and
+that this memory corresponds to either a secure or non-secure memory region as
+indicated by the security state of the ``flags`` argument.
+
+This function can safely assume that the value resulting from the addition of
+``mem_base`` and ``mem_size`` fits into a ``uintptr_t`` type variable and does not
+overflow.
+
+This function must return 0 on success, a non-null error code otherwise.
+
+The default implementation of this function asserts therefore platforms must
+override it when using the FWU feature.
+
+Boot Loader Stage 2 (BL2)
+-------------------------
+
+The BL2 stage is executed only by the primary CPU, which is determined in BL1
+using the ``platform_is_primary_cpu()`` function. BL1 passed control to BL2 at
+``BL2_BASE``. BL2 executes in Secure EL1 and is responsible for:
+
+#. (Optional) Loading the SCP\_BL2 binary image (if present) from platform
+ provided non-volatile storage. To load the SCP\_BL2 image, BL2 makes use of
+ the ``meminfo`` returned by the ``bl2_plat_get_scp_bl2_meminfo()`` function.
+ The platform also defines the address in memory where SCP\_BL2 is loaded
+ through the optional constant ``SCP_BL2_BASE``. BL2 uses this information
+ to determine if there is enough memory to load the SCP\_BL2 image.
+ Subsequent handling of the SCP\_BL2 image is platform-specific and is
+ implemented in the ``bl2_plat_handle_scp_bl2()`` function.
+ If ``SCP_BL2_BASE`` is not defined then this step is not performed.
+
+#. Loading the BL31 binary image into secure RAM from non-volatile storage. To
+ load the BL31 image, BL2 makes use of the ``meminfo`` structure passed to it
+ by BL1. This structure allows BL2 to calculate how much secure RAM is
+ available for its use. The platform also defines the address in secure RAM
+ where BL31 is loaded through the constant ``BL31_BASE``. BL2 uses this
+ information to determine if there is enough memory to load the BL31 image.
+
+#. (Optional) Loading the BL32 binary image (if present) from platform
+ provided non-volatile storage. To load the BL32 image, BL2 makes use of
+ the ``meminfo`` returned by the ``bl2_plat_get_bl32_meminfo()`` function.
+ The platform also defines the address in memory where BL32 is loaded
+ through the optional constant ``BL32_BASE``. BL2 uses this information
+ to determine if there is enough memory to load the BL32 image.
+ If ``BL32_BASE`` is not defined then this and the next step is not performed.
+
+#. (Optional) Arranging to pass control to the BL32 image (if present) that
+ has been pre-loaded at ``BL32_BASE``. BL2 populates an ``entry_point_info``
+ structure in memory provided by the platform with information about how
+ BL31 should pass control to the BL32 image.
+
+#. (Optional) Loading the normal world BL33 binary image (if not loaded by
+ other means) into non-secure DRAM from platform storage and arranging for
+ BL31 to pass control to this image. This address is determined using the
+ ``plat_get_ns_image_entrypoint()`` function described below.
+
+#. BL2 populates an ``entry_point_info`` structure in memory provided by the
+ platform with information about how BL31 should pass control to the
+ other BL images.
+
+The following functions must be implemented by the platform port to enable BL2
+to perform the above tasks.
+
+Function : bl2\_early\_platform\_setup() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : meminfo *
+ Return : void
+
+This function executes with the MMU and data caches disabled. It is only called
+by the primary CPU. The arguments to this function is the address of the
+``meminfo`` structure populated by BL1.
+
+The platform may copy the contents of the ``meminfo`` structure into a private
+variable as the original memory may be subsequently overwritten by BL2. The
+copied structure is made available to all BL2 code through the
+``bl2_plat_sec_mem_layout()`` function.
+
+On ARM standard platforms, this function also:
+
+- Initializes a UART (PL011 console), which enables access to the ``printf``
+ family of functions in BL2.
+
+- Initializes the storage abstraction layer used to load further bootloader
+ images. It is necessary to do this early on platforms with a SCP\_BL2 image,
+ since the later ``bl2_platform_setup`` must be done after SCP\_BL2 is loaded.
+
+Function : bl2\_plat\_arch\_setup() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : void
+
+This function executes with the MMU and data caches disabled. It is only called
+by the primary CPU.
+
+The purpose of this function is to perform any architectural initialization
+that varies across platforms.
+
+On ARM standard platforms, this function enables the MMU.
+
+Function : bl2\_platform\_setup() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : void
+
+This function may execute with the MMU and data caches enabled if the platform
+port does the necessary initialization in ``bl2_plat_arch_setup()``. It is only
+called by the primary CPU.
+
+The purpose of this function is to perform any platform initialization
+specific to BL2.
+
+In ARM standard platforms, this function performs security setup, including
+configuration of the TrustZone controller to allow non-secure masters access
+to most of DRAM. Part of DRAM is reserved for secure world use.
+
+Function : bl2\_plat\_sec\_mem\_layout() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : meminfo *
+
+This function should only be called on the cold boot path. It may execute with
+the MMU and data caches enabled if the platform port does the necessary
+initialization in ``bl2_plat_arch_setup()``. It is only called by the primary CPU.
+
+The purpose of this function is to return a pointer to a ``meminfo`` structure
+populated with the extents of secure RAM available for BL2 to use. See
+``bl2_early_platform_setup()`` above.
+
+Following function is required only when LOAD\_IMAGE\_V2 is enabled.
+
+Function : bl2\_plat\_handle\_post\_image\_load() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : unsigned int
+ Return : int
+
+This function can be used by the platforms to update/use image information
+for given ``image_id``. This function is currently invoked in BL2 to handle
+BL image specific information based on the ``image_id`` passed, when
+LOAD\_IMAGE\_V2 is enabled.
+
+Following functions are required only when LOAD\_IMAGE\_V2 is disabled.
+
+Function : bl2\_plat\_get\_scp\_bl2\_meminfo() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : meminfo *
+ Return : void
+
+This function is used to get the memory limits where BL2 can load the
+SCP\_BL2 image. The meminfo provided by this is used by load\_image() to
+validate whether the SCP\_BL2 image can be loaded within the given
+memory from the given base.
+
+Function : bl2\_plat\_handle\_scp\_bl2() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : image_info *
+ Return : int
+
+This function is called after loading SCP\_BL2 image and it is used to perform
+any platform-specific actions required to handle the SCP firmware. Typically it
+transfers the image into SCP memory using a platform-specific protocol and waits
+until SCP executes it and signals to the Application Processor (AP) for BL2
+execution to continue.
+
+This function returns 0 on success, a negative error code otherwise.
+
+Function : bl2\_plat\_get\_bl31\_params() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : bl31_params *
+
+BL2 platform code needs to return a pointer to a ``bl31_params`` structure it
+will use for passing information to BL31. The ``bl31_params`` structure carries
+the following information.
+- Header describing the version information for interpreting the bl31\_param
+structure
+- Information about executing the BL33 image in the ``bl33_ep_info`` field
+- Information about executing the BL32 image in the ``bl32_ep_info`` field
+- Information about the type and extents of BL31 image in the
+``bl31_image_info`` field
+- Information about the type and extents of BL32 image in the
+``bl32_image_info`` field
+- Information about the type and extents of BL33 image in the
+``bl33_image_info`` field
+
+The memory pointed by this structure and its sub-structures should be
+accessible from BL31 initialisation code. BL31 might choose to copy the
+necessary content, or maintain the structures until BL33 is initialised.
+
+Funtion : bl2\_plat\_get\_bl31\_ep\_info() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : entry_point_info *
+
+BL2 platform code returns a pointer which is used to populate the entry point
+information for BL31 entry point. The location pointed by it should be
+accessible from BL1 while processing the synchronous exception to run to BL31.
+
+In ARM standard platforms this is allocated inside a bl2\_to\_bl31\_params\_mem
+structure in BL2 memory.
+
+Function : bl2\_plat\_set\_bl31\_ep\_info() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : image_info *, entry_point_info *
+ Return : void
+
+In the normal boot flow, this function is called after loading BL31 image and
+it can be used to overwrite the entry point set by loader and also set the
+security state and SPSR which represents the entry point system state for BL31.
+
+When booting an EL3 payload instead, this function is called after populating
+its entry point address and can be used for the same purpose for the payload
+image. It receives a null pointer as its first argument in this case.
+
+Function : bl2\_plat\_set\_bl32\_ep\_info() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : image_info *, entry_point_info *
+ Return : void
+
+This function is called after loading BL32 image and it can be used to
+overwrite the entry point set by loader and also set the security state
+and SPSR which represents the entry point system state for BL32.
+
+Function : bl2\_plat\_set\_bl33\_ep\_info() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : image_info *, entry_point_info *
+ Return : void
+
+This function is called after loading BL33 image and it can be used to
+overwrite the entry point set by loader and also set the security state
+and SPSR which represents the entry point system state for BL33.
+
+In the preloaded BL33 alternative boot flow, this function is called after
+populating its entry point address. It is passed a null pointer as its first
+argument in this case.
+
+Function : bl2\_plat\_get\_bl32\_meminfo() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : meminfo *
+ Return : void
+
+This function is used to get the memory limits where BL2 can load the
+BL32 image. The meminfo provided by this is used by load\_image() to
+validate whether the BL32 image can be loaded with in the given
+memory from the given base.
+
+Function : bl2\_plat\_get\_bl33\_meminfo() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : meminfo *
+ Return : void
+
+This function is used to get the memory limits where BL2 can load the
+BL33 image. The meminfo provided by this is used by load\_image() to
+validate whether the BL33 image can be loaded with in the given
+memory from the given base.
+
+This function isn't needed if either ``PRELOADED_BL33_BASE`` or ``EL3_PAYLOAD_BASE``
+build options are used.
+
+Function : bl2\_plat\_flush\_bl31\_params() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : void
+
+Once BL2 has populated all the structures that needs to be read by BL1
+and BL31 including the bl31\_params structures and its sub-structures,
+the bl31\_ep\_info structure and any platform specific data. It flushes
+all these data to the main memory so that it is available when we jump to
+later Bootloader stages with MMU off
+
+Function : plat\_get\_ns\_image\_entrypoint() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : uintptr_t
+
+As previously described, BL2 is responsible for arranging for control to be
+passed to a normal world BL image through BL31. This function returns the
+entrypoint of that image, which BL31 uses to jump to it.
+
+BL2 is responsible for loading the normal world BL33 image (e.g. UEFI).
+
+This function isn't needed if either ``PRELOADED_BL33_BASE`` or ``EL3_PAYLOAD_BASE``
+build options are used.
+
+FWU Boot Loader Stage 2 (BL2U)
+------------------------------
+
+The AP Firmware Updater Configuration, BL2U, is an optional part of the FWU
+process and is executed only by the primary CPU. BL1 passes control to BL2U at
+``BL2U_BASE``. BL2U executes in Secure-EL1 and is responsible for:
+
+#. (Optional) Transfering the optional SCP\_BL2U binary image from AP secure
+ memory to SCP RAM. BL2U uses the SCP\_BL2U ``image_info`` passed by BL1.
+ ``SCP_BL2U_BASE`` defines the address in AP secure memory where SCP\_BL2U
+ should be copied from. Subsequent handling of the SCP\_BL2U image is
+ implemented by the platform specific ``bl2u_plat_handle_scp_bl2u()`` function.
+ If ``SCP_BL2U_BASE`` is not defined then this step is not performed.
+
+#. Any platform specific setup required to perform the FWU process. For
+ example, ARM standard platforms initialize the TZC controller so that the
+ normal world can access DDR memory.
+
+The following functions must be implemented by the platform port to enable
+BL2U to perform the tasks mentioned above.
+
+Function : bl2u\_early\_platform\_setup() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : meminfo *mem_info, void *plat_info
+ Return : void
+
+This function executes with the MMU and data caches disabled. It is only
+called by the primary CPU. The arguments to this function is the address
+of the ``meminfo`` structure and platform specific info provided by BL1.
+
+The platform may copy the contents of the ``mem_info`` and ``plat_info`` into
+private storage as the original memory may be subsequently overwritten by BL2U.
+
+On ARM CSS platforms ``plat_info`` is interpreted as an ``image_info_t`` structure,
+to extract SCP\_BL2U image information, which is then copied into a private
+variable.
+
+Function : bl2u\_plat\_arch\_setup() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : void
+
+This function executes with the MMU and data caches disabled. It is only
+called by the primary CPU.
+
+The purpose of this function is to perform any architectural initialization
+that varies across platforms, for example enabling the MMU (since the memory
+map differs across platforms).
+
+Function : bl2u\_platform\_setup() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : void
+
+This function may execute with the MMU and data caches enabled if the platform
+port does the necessary initialization in ``bl2u_plat_arch_setup()``. It is only
+called by the primary CPU.
+
+The purpose of this function is to perform any platform initialization
+specific to BL2U.
+
+In ARM standard platforms, this function performs security setup, including
+configuration of the TrustZone controller to allow non-secure masters access
+to most of DRAM. Part of DRAM is reserved for secure world use.
+
+Function : bl2u\_plat\_handle\_scp\_bl2u() [optional]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : int
+
+This function is used to perform any platform-specific actions required to
+handle the SCP firmware. Typically it transfers the image into SCP memory using
+a platform-specific protocol and waits until SCP executes it and signals to the
+Application Processor (AP) for BL2U execution to continue.
+
+This function returns 0 on success, a negative error code otherwise.
+This function is included if SCP\_BL2U\_BASE is defined.
+
+Boot Loader Stage 3-1 (BL31)
+----------------------------
+
+During cold boot, the BL31 stage is executed only by the primary CPU. This is
+determined in BL1 using the ``platform_is_primary_cpu()`` function. BL1 passes
+control to BL31 at ``BL31_BASE``. During warm boot, BL31 is executed by all
+CPUs. BL31 executes at EL3 and is responsible for:
+
+#. Re-initializing all architectural and platform state. Although BL1 performs
+ some of this initialization, BL31 remains resident in EL3 and must ensure
+ that EL3 architectural and platform state is completely initialized. It
+ should make no assumptions about the system state when it receives control.
+
+#. Passing control to a normal world BL image, pre-loaded at a platform-
+ specific address by BL2. BL31 uses the ``entry_point_info`` structure that BL2
+ populated in memory to do this.
+
+#. Providing runtime firmware services. Currently, BL31 only implements a
+ subset of the Power State Coordination Interface (PSCI) API as a runtime
+ service. See Section 3.3 below for details of porting the PSCI
+ implementation.
+
+#. Optionally passing control to the BL32 image, pre-loaded at a platform-
+ specific address by BL2. BL31 exports a set of apis that allow runtime
+ services to specify the security state in which the next image should be
+ executed and run the corresponding image. BL31 uses the ``entry_point_info``
+ structure populated by BL2 to do this.
+
+If BL31 is a reset vector, It also needs to handle the reset as specified in
+section 2.2 before the tasks described above.
+
+The following functions must be implemented by the platform port to enable BL31
+to perform the above tasks.
+
+Function : bl31\_early\_platform\_setup() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : bl31_params *, void *
+ Return : void
+
+This function executes with the MMU and data caches disabled. It is only called
+by the primary CPU. The arguments to this function are:
+
+- The address of the ``bl31_params`` structure populated by BL2.
+- An opaque pointer that the platform may use as needed.
+
+The platform can copy the contents of the ``bl31_params`` structure and its
+sub-structures into private variables if the original memory may be
+subsequently overwritten by BL31 and similarly the ``void *`` pointing
+to the platform data also needs to be saved.
+
+In ARM standard platforms, BL2 passes a pointer to a ``bl31_params`` structure
+in BL2 memory. BL31 copies the information in this pointer to internal data
+structures. It also performs the following:
+
+- Initialize a UART (PL011 console), which enables access to the ``printf``
+ family of functions in BL31.
+
+- Enable issuing of snoop and DVM (Distributed Virtual Memory) requests to the
+ CCI slave interface corresponding to the cluster that includes the primary
+ CPU.
+
+Function : bl31\_plat\_arch\_setup() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : void
+
+This function executes with the MMU and data caches disabled. It is only called
+by the primary CPU.
+
+The purpose of this function is to perform any architectural initialization
+that varies across platforms.
+
+On ARM standard platforms, this function enables the MMU.
+
+Function : bl31\_platform\_setup() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : void
+
+This function may execute with the MMU and data caches enabled if the platform
+port does the necessary initialization in ``bl31_plat_arch_setup()``. It is only
+called by the primary CPU.
+
+The purpose of this function is to complete platform initialization so that both
+BL31 runtime services and normal world software can function correctly.
+
+On ARM standard platforms, this function does the following:
+
+- Initialize the generic interrupt controller.
+
+ Depending on the GIC driver selected by the platform, the appropriate GICv2
+ or GICv3 initialization will be done, which mainly consists of:
+
+ - Enable secure interrupts in the GIC CPU interface.
+ - Disable the legacy interrupt bypass mechanism.
+ - Configure the priority mask register to allow interrupts of all priorities
+ to be signaled to the CPU interface.
+ - Mark SGIs 8-15 and the other secure interrupts on the platform as secure.
+ - Target all secure SPIs to CPU0.
+ - Enable these secure interrupts in the GIC distributor.
+ - Configure all other interrupts as non-secure.
+ - Enable signaling of secure interrupts in the GIC distributor.
+
+- Enable system-level implementation of the generic timer counter through the
+ memory mapped interface.
+
+- Grant access to the system counter timer module
+
+- Initialize the power controller device.
+
+ In particular, initialise the locks that prevent concurrent accesses to the
+ power controller device.
+
+Function : bl31\_plat\_runtime\_setup() [optional]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : void
+
+The purpose of this function is allow the platform to perform any BL31 runtime
+setup just prior to BL31 exit during cold boot. The default weak
+implementation of this function will invoke ``console_uninit()`` which will
+suppress any BL31 runtime logs.
+
+In ARM Standard platforms, this function will initialize the BL31 runtime
+console which will cause all further BL31 logs to be output to the
+runtime console.
+
+Function : bl31\_get\_next\_image\_info() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : unsigned int
+ Return : entry_point_info *
+
+This function may execute with the MMU and data caches enabled if the platform
+port does the necessary initializations in ``bl31_plat_arch_setup()``.
+
+This function is called by ``bl31_main()`` to retrieve information provided by
+BL2 for the next image in the security state specified by the argument. BL31
+uses this information to pass control to that image in the specified security
+state. This function must return a pointer to the ``entry_point_info`` structure
+(that was copied during ``bl31_early_platform_setup()``) if the image exists. It
+should return NULL otherwise.
+
+Function : plat\_get\_syscnt\_freq2() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : unsigned int
+
+This function is used by the architecture setup code to retrieve the counter
+frequency for the CPU's generic timer. This value will be programmed into the
+``CNTFRQ_EL0`` register. In ARM standard platforms, it returns the base frequency
+of the system counter, which is retrieved from the first entry in the frequency
+modes table.
+
+#define : PLAT\_PERCPU\_BAKERY\_LOCK\_SIZE [optional]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When ``USE_COHERENT_MEM = 0``, this constant defines the total memory (in
+bytes) aligned to the cache line boundary that should be allocated per-cpu to
+accommodate all the bakery locks.
+
+If this constant is not defined when ``USE_COHERENT_MEM = 0``, the linker
+calculates the size of the ``bakery_lock`` input section, aligns it to the
+nearest ``CACHE_WRITEBACK_GRANULE``, multiplies it with ``PLATFORM_CORE_COUNT``
+and stores the result in a linker symbol. This constant prevents a platform
+from relying on the linker and provide a more efficient mechanism for
+accessing per-cpu bakery lock information.
+
+If this constant is defined and its value is not equal to the value
+calculated by the linker then a link time assertion is raised. A compile time
+assertion is raised if the value of the constant is not aligned to the cache
+line boundary.
+
+Power State Coordination Interface (in BL31)
+--------------------------------------------
+
+The ARM Trusted Firmware's implementation of the PSCI API is based around the
+concept of a *power domain*. A *power domain* is a CPU or a logical group of
+CPUs which share some state on which power management operations can be
+performed as specified by `PSCI`_. Each CPU in the system is assigned a cpu
+index which is a unique number between ``0`` and ``PLATFORM_CORE_COUNT - 1``.
+The *power domains* are arranged in a hierarchical tree structure and
+each *power domain* can be identified in a system by the cpu index of any CPU
+that is part of that domain and a *power domain level*. A processing element
+(for example, a CPU) is at level 0. If the *power domain* node above a CPU is
+a logical grouping of CPUs that share some state, then level 1 is that group
+of CPUs (for example, a cluster), and level 2 is a group of clusters
+(for example, the system). More details on the power domain topology and its
+organization can be found in `Power Domain Topology Design`_.
+
+BL31's platform initialization code exports a pointer to the platform-specific
+power management operations required for the PSCI implementation to function
+correctly. This information is populated in the ``plat_psci_ops`` structure. The
+PSCI implementation calls members of the ``plat_psci_ops`` structure for performing
+power management operations on the power domains. For example, the target
+CPU is specified by its ``MPIDR`` in a PSCI ``CPU_ON`` call. The ``pwr_domain_on()``
+handler (if present) is called for the CPU power domain.
+
+The ``power-state`` parameter of a PSCI ``CPU_SUSPEND`` call can be used to
+describe composite power states specific to a platform. The PSCI implementation
+defines a generic representation of the power-state parameter viz which is an
+array of local power states where each index corresponds to a power domain
+level. Each entry contains the local power state the power domain at that power
+level could enter. It depends on the ``validate_power_state()`` handler to
+convert the power-state parameter (possibly encoding a composite power state)
+passed in a PSCI ``CPU_SUSPEND`` call to this representation.
+
+The following functions form part of platform port of PSCI functionality.
+
+Function : plat\_psci\_stat\_accounting\_start() [optional]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : const psci_power_state_t *
+ Return : void
+
+This is an optional hook that platforms can implement for residency statistics
+accounting before entering a low power state. The ``pwr_domain_state`` field of
+``state_info`` (first argument) can be inspected if stat accounting is done
+differently at CPU level versus higher levels. As an example, if the element at
+index 0 (CPU power level) in the ``pwr_domain_state`` array indicates a power down
+state, special hardware logic may be programmed in order to keep track of the
+residency statistics. For higher levels (array indices > 0), the residency
+statistics could be tracked in software using PMF. If ``ENABLE_PMF`` is set, the
+default implementation will use PMF to capture timestamps.
+
+Function : plat\_psci\_stat\_accounting\_stop() [optional]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : const psci_power_state_t *
+ Return : void
+
+This is an optional hook that platforms can implement for residency statistics
+accounting after exiting from a low power state. The ``pwr_domain_state`` field
+of ``state_info`` (first argument) can be inspected if stat accounting is done
+differently at CPU level versus higher levels. As an example, if the element at
+index 0 (CPU power level) in the ``pwr_domain_state`` array indicates a power down
+state, special hardware logic may be programmed in order to keep track of the
+residency statistics. For higher levels (array indices > 0), the residency
+statistics could be tracked in software using PMF. If ``ENABLE_PMF`` is set, the
+default implementation will use PMF to capture timestamps.
+
+Function : plat\_psci\_stat\_get\_residency() [optional]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : unsigned int, const psci_power_state_t *, int
+ Return : u_register_t
+
+This is an optional interface that is is invoked after resuming from a low power
+state and provides the time spent resident in that low power state by the power
+domain at a particular power domain level. When a CPU wakes up from suspend,
+all its parent power domain levels are also woken up. The generic PSCI code
+invokes this function for each parent power domain that is resumed and it
+identified by the ``lvl`` (first argument) parameter. The ``state_info`` (second
+argument) describes the low power state that the power domain has resumed from.
+The current CPU is the first CPU in the power domain to resume from the low
+power state and the ``last_cpu_idx`` (third parameter) is the index of the last
+CPU in the power domain to suspend and may be needed to calculate the residency
+for that power domain.
+
+Function : plat\_get\_target\_pwr\_state() [optional]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : unsigned int, const plat_local_state_t *, unsigned int
+ Return : plat_local_state_t
+
+The PSCI generic code uses this function to let the platform participate in
+state coordination during a power management operation. The function is passed
+a pointer to an array of platform specific local power state ``states`` (second
+argument) which contains the requested power state for each CPU at a particular
+power domain level ``lvl`` (first argument) within the power domain. The function
+is expected to traverse this array of upto ``ncpus`` (third argument) and return
+a coordinated target power state by the comparing all the requested power
+states. The target power state should not be deeper than any of the requested
+power states.
+
+A weak definition of this API is provided by default wherein it assumes
+that the platform assigns a local state value in order of increasing depth
+of the power state i.e. for two power states X & Y, if X < Y
+then X represents a shallower power state than Y. As a result, the
+coordinated target local power state for a power domain will be the minimum
+of the requested local power state values.
+
+Function : plat\_get\_power\_domain\_tree\_desc() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : const unsigned char *
+
+This function returns a pointer to the byte array containing the power domain
+topology tree description. The format and method to construct this array are
+described in `Power Domain Topology Design`_. The BL31 PSCI initilization code
+requires this array to be described by the platform, either statically or
+dynamically, to initialize the power domain topology tree. In case the array
+is populated dynamically, then plat\_core\_pos\_by\_mpidr() and
+plat\_my\_core\_pos() should also be implemented suitably so that the topology
+tree description matches the CPU indices returned by these APIs. These APIs
+together form the platform interface for the PSCI topology framework.
+
+Function : plat\_setup\_psci\_ops() [mandatory]
+-----------------------------------------------
+
+::
+
+ Argument : uintptr_t, const plat_psci_ops **
+ Return : int
+
+This function may execute with the MMU and data caches enabled if the platform
+port does the necessary initializations in ``bl31_plat_arch_setup()``. It is only
+called by the primary CPU.
+
+This function is called by PSCI initialization code. Its purpose is to let
+the platform layer know about the warm boot entrypoint through the
+``sec_entrypoint`` (first argument) and to export handler routines for
+platform-specific psci power management actions by populating the passed
+pointer with a pointer to BL31's private ``plat_psci_ops`` structure.
+
+A description of each member of this structure is given below. Please refer to
+the ARM FVP specific implementation of these handlers in
+`plat/arm/board/fvp/fvp\_pm.c`_ as an example. For each PSCI function that the
+platform wants to support, the associated operation or operations in this
+structure must be provided and implemented (Refer section 4 of
+`Firmware Design`_ for the PSCI API supported in Trusted Firmware). To disable
+a PSCI function in a platform port, the operation should be removed from this
+structure instead of providing an empty implementation.
+
+plat\_psci\_ops.cpu\_standby()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Perform the platform-specific actions to enter the standby state for a cpu
+indicated by the passed argument. This provides a fast path for CPU standby
+wherein overheads of PSCI state management and lock acquistion is avoided.
+For this handler to be invoked by the PSCI ``CPU_SUSPEND`` API implementation,
+the suspend state type specified in the ``power-state`` parameter should be
+STANDBY and the target power domain level specified should be the CPU. The
+handler should put the CPU into a low power retention state (usually by
+issuing a wfi instruction) and ensure that it can be woken up from that
+state by a normal interrupt. The generic code expects the handler to succeed.
+
+plat\_psci\_ops.pwr\_domain\_on()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Perform the platform specific actions to power on a CPU, specified
+by the ``MPIDR`` (first argument). The generic code expects the platform to
+return PSCI\_E\_SUCCESS on success or PSCI\_E\_INTERN\_FAIL for any failure.
+
+plat\_psci\_ops.pwr\_domain\_off()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Perform the platform specific actions to prepare to power off the calling CPU
+and its higher parent power domain levels as indicated by the ``target_state``
+(first argument). It is called by the PSCI ``CPU_OFF`` API implementation.
+
+The ``target_state`` encodes the platform coordinated target local power states
+for the CPU power domain and its parent power domain levels. The handler
+needs to perform power management operation corresponding to the local state
+at each power level.
+
+For this handler, the local power state for the CPU power domain will be a
+power down state where as it could be either power down, retention or run state
+for the higher power domain levels depending on the result of state
+coordination. The generic code expects the handler to succeed.
+
+plat\_psci\_ops.pwr\_domain\_suspend()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Perform the platform specific actions to prepare to suspend the calling
+CPU and its higher parent power domain levels as indicated by the
+``target_state`` (first argument). It is called by the PSCI ``CPU_SUSPEND``
+API implementation.
+
+The ``target_state`` has a similar meaning as described in
+the ``pwr_domain_off()`` operation. It encodes the platform coordinated
+target local power states for the CPU power domain and its parent
+power domain levels. The handler needs to perform power management operation
+corresponding to the local state at each power level. The generic code
+expects the handler to succeed.
+
+The difference between turning a power domain off versus suspending it
+is that in the former case, the power domain is expected to re-initialize
+its state when it is next powered on (see ``pwr_domain_on_finish()``). In the
+latter case, the power domain is expected to save enough state so that it can
+resume execution by restoring this state when its powered on (see
+``pwr_domain_suspend_finish()``).
+
+plat\_psci\_ops.pwr\_domain\_pwr\_down\_wfi()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is an optional function and, if implemented, is expected to perform
+platform specific actions including the ``wfi`` invocation which allows the
+CPU to powerdown. Since this function is invoked outside the PSCI locks,
+the actions performed in this hook must be local to the CPU or the platform
+must ensure that races between multiple CPUs cannot occur.
+
+The ``target_state`` has a similar meaning as described in the ``pwr_domain_off()``
+operation and it encodes the platform coordinated target local power states for
+the CPU power domain and its parent power domain levels. This function must
+not return back to the caller.
+
+If this function is not implemented by the platform, PSCI generic
+implementation invokes ``psci_power_down_wfi()`` for power down.
+
+plat\_psci\_ops.pwr\_domain\_on\_finish()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This function is called by the PSCI implementation after the calling CPU is
+powered on and released from reset in response to an earlier PSCI ``CPU_ON`` call.
+It performs the platform-specific setup required to initialize enough state for
+this CPU to enter the normal world and also provide secure runtime firmware
+services.
+
+The ``target_state`` (first argument) is the prior state of the power domains
+immediately before the CPU was turned on. It indicates which power domains
+above the CPU might require initialization due to having previously been in
+low power states. The generic code expects the handler to succeed.
+
+plat\_psci\_ops.pwr\_domain\_suspend\_finish()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This function is called by the PSCI implementation after the calling CPU is
+powered on and released from reset in response to an asynchronous wakeup
+event, for example a timer interrupt that was programmed by the CPU during the
+``CPU_SUSPEND`` call or ``SYSTEM_SUSPEND`` call. It performs the platform-specific
+setup required to restore the saved state for this CPU to resume execution
+in the normal world and also provide secure runtime firmware services.
+
+The ``target_state`` (first argument) has a similar meaning as described in
+the ``pwr_domain_on_finish()`` operation. The generic code expects the platform
+to succeed.
+
+plat\_psci\_ops.system\_off()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This function is called by PSCI implementation in response to a ``SYSTEM_OFF``
+call. It performs the platform-specific system poweroff sequence after
+notifying the Secure Payload Dispatcher.
+
+plat\_psci\_ops.system\_reset()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This function is called by PSCI implementation in response to a ``SYSTEM_RESET``
+call. It performs the platform-specific system reset sequence after
+notifying the Secure Payload Dispatcher.
+
+plat\_psci\_ops.validate\_power\_state()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This function is called by the PSCI implementation during the ``CPU_SUSPEND``
+call to validate the ``power_state`` parameter of the PSCI API and if valid,
+populate it in ``req_state`` (second argument) array as power domain level
+specific local states. If the ``power_state`` is invalid, the platform must
+return PSCI\_E\_INVALID\_PARAMS as error, which is propagated back to the
+normal world PSCI client.
+
+plat\_psci\_ops.validate\_ns\_entrypoint()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This function is called by the PSCI implementation during the ``CPU_SUSPEND``,
+``SYSTEM_SUSPEND`` and ``CPU_ON`` calls to validate the non-secure ``entry_point``
+parameter passed by the normal world. If the ``entry_point`` is invalid,
+the platform must return PSCI\_E\_INVALID\_ADDRESS as error, which is
+propagated back to the normal world PSCI client.
+
+plat\_psci\_ops.get\_sys\_suspend\_power\_state()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This function is called by the PSCI implementation during the ``SYSTEM_SUSPEND``
+call to get the ``req_state`` parameter from platform which encodes the power
+domain level specific local states to suspend to system affinity level. The
+``req_state`` will be utilized to do the PSCI state coordination and
+``pwr_domain_suspend()`` will be invoked with the coordinated target state to
+enter system suspend.
+
+plat\_psci\_ops.get\_pwr\_lvl\_state\_idx()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is an optional function and, if implemented, is invoked by the PSCI
+implementation to convert the ``local_state`` (first argument) at a specified
+``pwr_lvl`` (second argument) to an index between 0 and
+``PLAT_MAX_PWR_LVL_STATES`` - 1. This function is only needed if the platform
+supports more than two local power states at each power domain level, that is
+``PLAT_MAX_PWR_LVL_STATES`` is greater than 2, and needs to account for these
+local power states.
+
+plat\_psci\_ops.translate\_power\_state\_by\_mpidr()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is an optional function and, if implemented, verifies the ``power_state``
+(second argument) parameter of the PSCI API corresponding to a target power
+domain. The target power domain is identified by using both ``MPIDR`` (first
+argument) and the power domain level encoded in ``power_state``. The power domain
+level specific local states are to be extracted from ``power_state`` and be
+populated in the ``output_state`` (third argument) array. The functionality
+is similar to the ``validate_power_state`` function described above and is
+envisaged to be used in case the validity of ``power_state`` depend on the
+targeted power domain. If the ``power_state`` is invalid for the targeted power
+domain, the platform must return PSCI\_E\_INVALID\_PARAMS as error. If this
+function is not implemented, then the generic implementation relies on
+``validate_power_state`` function to translate the ``power_state``.
+
+This function can also be used in case the platform wants to support local
+power state encoding for ``power_state`` parameter of PSCI\_STAT\_COUNT/RESIDENCY
+APIs as described in Section 5.18 of `PSCI`_.
+
+plat\_psci\_ops.get\_node\_hw\_state()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is an optional function. If implemented this function is intended to return
+the power state of a node (identified by the first parameter, the ``MPIDR``) in
+the power domain topology (identified by the second parameter, ``power_level``),
+as retrieved from a power controller or equivalent component on the platform.
+Upon successful completion, the implementation must map and return the final
+status among ``HW_ON``, ``HW_OFF`` or ``HW_STANDBY``. Upon encountering failures, it
+must return either ``PSCI_E_INVALID_PARAMS`` or ``PSCI_E_NOT_SUPPORTED`` as
+appropriate.
+
+Implementations are not expected to handle ``power_levels`` greater than
+``PLAT_MAX_PWR_LVL``.
+
+Interrupt Management framework (in BL31)
+----------------------------------------
+
+BL31 implements an Interrupt Management Framework (IMF) to manage interrupts
+generated in either security state and targeted to EL1 or EL2 in the non-secure
+state or EL3/S-EL1 in the secure state. The design of this framework is
+described in the `IMF Design Guide`_
+
+A platform should export the following APIs to support the IMF. The following
+text briefly describes each api and its implementation in ARM standard
+platforms. The API implementation depends upon the type of interrupt controller
+present in the platform. ARM standard platform layer supports both
+`ARM Generic Interrupt Controller version 2.0 (GICv2)`_
+and `3.0 (GICv3)`_. Juno builds the ARM
+Standard layer to use GICv2 and the FVP can be configured to use either GICv2 or
+GICv3 depending on the build flag ``FVP_USE_GIC_DRIVER`` (See FVP platform
+specific build options in `User Guide`_ for more details).
+
+Function : plat\_interrupt\_type\_to\_line() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : uint32_t, uint32_t
+ Return : uint32_t
+
+The ARM processor signals an interrupt exception either through the IRQ or FIQ
+interrupt line. The specific line that is signaled depends on how the interrupt
+controller (IC) reports different interrupt types from an execution context in
+either security state. The IMF uses this API to determine which interrupt line
+the platform IC uses to signal each type of interrupt supported by the framework
+from a given security state. This API must be invoked at EL3.
+
+The first parameter will be one of the ``INTR_TYPE_*`` values (see
+`IMF Design Guide`_) indicating the target type of the interrupt, the second parameter is the
+security state of the originating execution context. The return result is the
+bit position in the ``SCR_EL3`` register of the respective interrupt trap: IRQ=1,
+FIQ=2.
+
+In the case of ARM standard platforms using GICv2, S-EL1 interrupts are
+configured as FIQs and Non-secure interrupts as IRQs from either security
+state.
+
+In the case of ARM standard platforms using GICv3, the interrupt line to be
+configured depends on the security state of the execution context when the
+interrupt is signalled and are as follows:
+
+- The S-EL1 interrupts are signaled as IRQ in S-EL0/1 context and as FIQ in
+ NS-EL0/1/2 context.
+- The Non secure interrupts are signaled as FIQ in S-EL0/1 context and as IRQ
+ in the NS-EL0/1/2 context.
+- The EL3 interrupts are signaled as FIQ in both S-EL0/1 and NS-EL0/1/2
+ context.
+
+Function : plat\_ic\_get\_pending\_interrupt\_type() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : uint32_t
+
+This API returns the type of the highest priority pending interrupt at the
+platform IC. The IMF uses the interrupt type to retrieve the corresponding
+handler function. ``INTR_TYPE_INVAL`` is returned when there is no interrupt
+pending. The valid interrupt types that can be returned are ``INTR_TYPE_EL3``,
+``INTR_TYPE_S_EL1`` and ``INTR_TYPE_NS``. This API must be invoked at EL3.
+
+In the case of ARM standard platforms using GICv2, the *Highest Priority
+Pending Interrupt Register* (``GICC_HPPIR``) is read to determine the id of
+the pending interrupt. The type of interrupt depends upon the id value as
+follows.
+
+#. id < 1022 is reported as a S-EL1 interrupt
+#. id = 1022 is reported as a Non-secure interrupt.
+#. id = 1023 is reported as an invalid interrupt type.
+
+In the case of ARM standard platforms using GICv3, the system register
+``ICC_HPPIR0_EL1``, *Highest Priority Pending group 0 Interrupt Register*,
+is read to determine the id of the pending interrupt. The type of interrupt
+depends upon the id value as follows.
+
+#. id = ``PENDING_G1S_INTID`` (1020) is reported as a S-EL1 interrupt
+#. id = ``PENDING_G1NS_INTID`` (1021) is reported as a Non-secure interrupt.
+#. id = ``GIC_SPURIOUS_INTERRUPT`` (1023) is reported as an invalid interrupt type.
+#. All other interrupt id's are reported as EL3 interrupt.
+
+Function : plat\_ic\_get\_pending\_interrupt\_id() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : uint32_t
+
+This API returns the id of the highest priority pending interrupt at the
+platform IC. ``INTR_ID_UNAVAILABLE`` is returned when there is no interrupt
+pending.
+
+In the case of ARM standard platforms using GICv2, the *Highest Priority
+Pending Interrupt Register* (``GICC_HPPIR``) is read to determine the id of the
+pending interrupt. The id that is returned by API depends upon the value of
+the id read from the interrupt controller as follows.
+
+#. id < 1022. id is returned as is.
+#. id = 1022. The *Aliased Highest Priority Pending Interrupt Register*
+ (``GICC_AHPPIR``) is read to determine the id of the non-secure interrupt.
+ This id is returned by the API.
+#. id = 1023. ``INTR_ID_UNAVAILABLE`` is returned.
+
+In the case of ARM standard platforms using GICv3, if the API is invoked from
+EL3, the system register ``ICC_HPPIR0_EL1``, *Highest Priority Pending Interrupt
+group 0 Register*, is read to determine the id of the pending interrupt. The id
+that is returned by API depends upon the value of the id read from the
+interrupt controller as follows.
+
+#. id < ``PENDING_G1S_INTID`` (1020). id is returned as is.
+#. id = ``PENDING_G1S_INTID`` (1020) or ``PENDING_G1NS_INTID`` (1021). The system
+ register ``ICC_HPPIR1_EL1``, *Highest Priority Pending Interrupt group 1
+ Register* is read to determine the id of the group 1 interrupt. This id
+ is returned by the API as long as it is a valid interrupt id
+#. If the id is any of the special interrupt identifiers,
+ ``INTR_ID_UNAVAILABLE`` is returned.
+
+When the API invoked from S-EL1 for GICv3 systems, the id read from system
+register ``ICC_HPPIR1_EL1``, *Highest Priority Pending group 1 Interrupt
+Register*, is returned if is not equal to GIC\_SPURIOUS\_INTERRUPT (1023) else
+``INTR_ID_UNAVAILABLE`` is returned.
+
+Function : plat\_ic\_acknowledge\_interrupt() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : uint32_t
+
+This API is used by the CPU to indicate to the platform IC that processing of
+the highest pending interrupt has begun. It should return the id of the
+interrupt which is being processed.
+
+This function in ARM standard platforms using GICv2, reads the *Interrupt
+Acknowledge Register* (``GICC_IAR``). This changes the state of the highest
+priority pending interrupt from pending to active in the interrupt controller.
+It returns the value read from the ``GICC_IAR``. This value is the id of the
+interrupt whose state has been changed.
+
+In the case of ARM standard platforms using GICv3, if the API is invoked
+from EL3, the function reads the system register ``ICC_IAR0_EL1``, *Interrupt
+Acknowledge Register group 0*. If the API is invoked from S-EL1, the function
+reads the system register ``ICC_IAR1_EL1``, *Interrupt Acknowledge Register
+group 1*. The read changes the state of the highest pending interrupt from
+pending to active in the interrupt controller. The value read is returned
+and is the id of the interrupt whose state has been changed.
+
+The TSP uses this API to start processing of the secure physical timer
+interrupt.
+
+Function : plat\_ic\_end\_of\_interrupt() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : uint32_t
+ Return : void
+
+This API is used by the CPU to indicate to the platform IC that processing of
+the interrupt corresponding to the id (passed as the parameter) has
+finished. The id should be the same as the id returned by the
+``plat_ic_acknowledge_interrupt()`` API.
+
+ARM standard platforms write the id to the *End of Interrupt Register*
+(``GICC_EOIR``) in case of GICv2, and to ``ICC_EOIR0_EL1`` or ``ICC_EOIR1_EL1``
+system register in case of GICv3 depending on where the API is invoked from,
+EL3 or S-EL1. This deactivates the corresponding interrupt in the interrupt
+controller.
+
+The TSP uses this API to finish processing of the secure physical timer
+interrupt.
+
+Function : plat\_ic\_get\_interrupt\_type() [mandatory]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : uint32_t
+ Return : uint32_t
+
+This API returns the type of the interrupt id passed as the parameter.
+``INTR_TYPE_INVAL`` is returned if the id is invalid. If the id is valid, a valid
+interrupt type (one of ``INTR_TYPE_EL3``, ``INTR_TYPE_S_EL1`` and ``INTR_TYPE_NS``) is
+returned depending upon how the interrupt has been configured by the platform
+IC. This API must be invoked at EL3.
+
+ARM standard platforms using GICv2 configures S-EL1 interrupts as Group0 interrupts
+and Non-secure interrupts as Group1 interrupts. It reads the group value
+corresponding to the interrupt id from the relevant *Interrupt Group Register*
+(``GICD_IGROUPRn``). It uses the group value to determine the type of interrupt.
+
+In the case of ARM standard platforms using GICv3, both the *Interrupt Group
+Register* (``GICD_IGROUPRn``) and *Interrupt Group Modifier Register*
+(``GICD_IGRPMODRn``) is read to figure out whether the interrupt is configured
+as Group 0 secure interrupt, Group 1 secure interrupt or Group 1 NS interrupt.
+
+Crash Reporting mechanism (in BL31)
+-----------------------------------
+
+BL31 implements a crash reporting mechanism which prints the various registers
+of the CPU to enable quick crash analysis and debugging. It requires that a
+console is designated as the crash console by the platform which will be used to
+print the register dump.
+
+The following functions must be implemented by the platform if it wants crash
+reporting mechanism in BL31. The functions are implemented in assembly so that
+they can be invoked without a C Runtime stack.
+
+Function : plat\_crash\_console\_init
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : int
+
+This API is used by the crash reporting mechanism to initialize the crash
+console. It must only use the general purpose registers x0 to x4 to do the
+initialization and returns 1 on success.
+
+Function : plat\_crash\_console\_putc
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : int
+ Return : int
+
+This API is used by the crash reporting mechanism to print a character on the
+designated crash console. It must only use general purpose registers x1 and
+x2 to do its work. The parameter and the return value are in general purpose
+register x0.
+
+Function : plat\_crash\_console\_flush
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : int
+
+This API is used by the crash reporting mechanism to force write of all buffered
+data on the designated crash console. It should only use general purpose
+registers x0 and x1 to do its work. The return value is 0 on successful
+completion; otherwise the return value is -1.
+
+Build flags
+-----------
+
+- **ENABLE\_PLAT\_COMPAT**
+ All the platforms ports conforming to this API specification should define
+ the build flag ``ENABLE_PLAT_COMPAT`` to 0 as the compatibility layer should
+ be disabled. For more details on compatibility layer, refer
+ `Migration Guide`_.
+
+There are some build flags which can be defined by the platform to control
+inclusion or exclusion of certain BL stages from the FIP image. These flags
+need to be defined in the platform makefile which will get included by the
+build system.
+
+- **NEED\_BL33**
+ By default, this flag is defined ``yes`` by the build system and ``BL33``
+ build option should be supplied as a build option. The platform has the
+ option of excluding the BL33 image in the ``fip`` image by defining this flag
+ to ``no``. If any of the options ``EL3_PAYLOAD_BASE`` or ``PRELOADED_BL33_BASE``
+ are used, this flag will be set to ``no`` automatically.
+
+C Library
+---------
+
+To avoid subtle toolchain behavioral dependencies, the header files provided
+by the compiler are not used. The software is built with the ``-nostdinc`` flag
+to ensure no headers are included from the toolchain inadvertently. Instead the
+required headers are included in the ARM Trusted Firmware source tree. The
+library only contains those C library definitions required by the local
+implementation. If more functionality is required, the needed library functions
+will need to be added to the local implementation.
+
+Versions of `FreeBSD`_ headers can be found in ``include/lib/stdlib``. Some of
+these headers have been cut down in order to simplify the implementation. In
+order to minimize changes to the header files, the `FreeBSD`_ layout has been
+maintained. The generic C library definitions can be found in
+``include/lib/stdlib`` with more system and machine specific declarations in
+``include/lib/stdlib/sys`` and ``include/lib/stdlib/machine``.
+
+The local C library implementations can be found in ``lib/stdlib``. In order to
+extend the C library these files may need to be modified. It is recommended to
+use a release version of `FreeBSD`_ as a starting point.
+
+The C library header files in the `FreeBSD`_ source tree are located in the
+``include`` and ``sys/sys`` directories. `FreeBSD`_ machine specific definitions
+can be found in the ``sys/<machine-type>`` directories. These files define things
+like 'the size of a pointer' and 'the range of an integer'. Since an AArch64
+port for `FreeBSD`_ does not yet exist, the machine specific definitions are
+based on existing machine types with similar properties (for example SPARC64).
+
+Where possible, C library function implementations were taken from `FreeBSD`_
+as found in the ``lib/libc`` directory.
+
+A copy of the `FreeBSD`_ sources can be downloaded with ``git``.
+
+::
+
+ git clone git://github.com/freebsd/freebsd.git -b origin/release/9.2.0
+
+Storage abstraction layer
+-------------------------
+
+In order to improve platform independence and portability an storage abstraction
+layer is used to load data from non-volatile platform storage.
+
+Each platform should register devices and their drivers via the Storage layer.
+These drivers then need to be initialized by bootloader phases as
+required in their respective ``blx_platform_setup()`` functions. Currently
+storage access is only required by BL1 and BL2 phases. The ``load_image()``
+function uses the storage layer to access non-volatile platform storage.
+
+It is mandatory to implement at least one storage driver. For the ARM
+development platforms the Firmware Image Package (FIP) driver is provided as
+the default means to load data from storage (see the "Firmware Image Package"
+section in the `User Guide`_). The storage layer is described in the header file
+``include/drivers/io/io_storage.h``. The implementation of the common library
+is in ``drivers/io/io_storage.c`` and the driver files are located in
+``drivers/io/``.
+
+Each IO driver must provide ``io_dev_*`` structures, as described in
+``drivers/io/io_driver.h``. These are returned via a mandatory registration
+function that is called on platform initialization. The semi-hosting driver
+implementation in ``io_semihosting.c`` can be used as an example.
+
+The Storage layer provides mechanisms to initialize storage devices before
+IO operations are called. The basic operations supported by the layer
+include ``open()``, ``close()``, ``read()``, ``write()``, ``size()`` and ``seek()``.
+Drivers do not have to implement all operations, but each platform must
+provide at least one driver for a device capable of supporting generic
+operations such as loading a bootloader image.
+
+The current implementation only allows for known images to be loaded by the
+firmware. These images are specified by using their identifiers, as defined in
+[include/plat/common/platform\_def.h] (or a separate header file included from
+there). The platform layer (``plat_get_image_source()``) then returns a reference
+to a device and a driver-specific ``spec`` which will be understood by the driver
+to allow access to the image data.
+
+The layer is designed in such a way that is it possible to chain drivers with
+other drivers. For example, file-system drivers may be implemented on top of
+physical block devices, both represented by IO devices with corresponding
+drivers. In such a case, the file-system "binding" with the block device may
+be deferred until the file-system device is initialised.
+
+The abstraction currently depends on structures being statically allocated
+by the drivers and callers, as the system does not yet provide a means of
+dynamically allocating memory. This may also have the affect of limiting the
+amount of open resources per driver.
+
+--------------
+
+*Copyright (c) 2013-2016, ARM Limited and Contributors. All rights reserved.*
+
+.. _Migration Guide: platform-migration-guide.rst
+.. _include/plat/common/platform.h: ../include/plat/common/platform.h
+.. _include/plat/arm/common/plat\_arm.h: ../include/plat/arm/common/plat_arm.h%5D
+.. _User Guide: user-guide.rst
+.. _include/plat/common/common\_def.h: ../include/plat/common/common_def.h
+.. _include/plat/arm/common/arm\_def.h: ../include/plat/arm/common/arm_def.h
+.. _plat/common/aarch64/platform\_mp\_stack.S: ../plat/common/aarch64/platform_mp_stack.S
+.. _plat/common/aarch64/platform\_up\_stack.S: ../plat/common/aarch64/platform_up_stack.S
+.. _For example, define the build flag in platform.mk: PLAT_PL061_MAX_GPIOS%20:=%20160
+.. _Power Domain Topology Design: psci-pd-tree.rst
+.. _include/common/bl\_common.h: ../include/common/bl_common.h
+.. _include/lib/aarch32/arch.h: ../include/lib/aarch32/arch.h
+.. _Firmware Design: firmware-design.rst
+.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
+.. _plat/arm/board/fvp/fvp\_pm.c: ../plat/arm/board/fvp/fvp_pm.c
+.. _IMF Design Guide: interrupt-framework-design.rst
+.. _ARM Generic Interrupt Controller version 2.0 (GICv2): http://infocenter.arm.com/help/topic/com.arm.doc.ihi0048b/index.html
+.. _3.0 (GICv3): http://infocenter.arm.com/help/topic/com.arm.doc.ihi0069b/index.html
+.. _FreeBSD: http://www.freebsd.org
diff --git a/docs/psci-lib-integration-guide.md b/docs/psci-lib-integration-guide.md
deleted file mode 100644
index d81b328..0000000
--- a/docs/psci-lib-integration-guide.md
+++ /dev/null
@@ -1,537 +0,0 @@
-PSCI Library Integration guide for ARMv8-A AArch32 systems
-==========================================================
-
-Contents
---------
-
-1. [Introduction](#1-introduction)
-2. [Generic call sequence for PSCI Library interface (AArch32)](#2-generic-call-sequence-for-psci-library-interface-aarch32)
-3. [PSCI CPU context management](#3-psci-cpu-context-management)
-4. [PSCI Library Interface](#4-psci-library-interface)
-5. [EL3 Runtime Software dependencies](#5-el3-runtime-software-dependencies)
-
-
-1. Introduction
----------------
-
-This document describes the PSCI library interface with a focus on how to
-integrate with a suitable Trusted OS for an ARMv8-A AArch32 system. The PSCI
-Library implements the PSCI Standard as described in [PSCI spec] and is meant
-to be integrated with EL3 Runtime Software which invokes the PSCI Library
-interface appropriately. **EL3 Runtime Software** refers to software executing
-at the highest secure privileged mode, which is EL3 in AArch64 or Secure SVC/
-Monitor mode in AArch32, and provides runtime services to the non-secure world.
-The runtime service request is made via SMC (Secure Monitor Call) and the call
-must adhere to [SMCCC]. In AArch32, EL3 Runtime Software may additionally
-include Trusted OS functionality. A minimal AArch32 Secure Payload, SP-MIN, is
-provided in ARM Trusted Firmware to illustrate the usage and integration of the
-PSCI library. The description of PSCI library interface and its integration
-with EL3 Runtime Software in this document is targeted towards AArch32 systems.
-
-2. Generic call sequence for PSCI Library interface (AArch32)
--------------------------------------------------------------
-
-The generic call sequence of PSCI Library interfaces
-[(see section 4)](#4-psci-library-interface) during cold boot in AArch32
-system is described below:
-
-1. After cold reset, the EL3 Runtime Software performs its cold boot
- initialization including the PSCI library pre-requisites mentioned in
- [section 4](#4-psci-library-interface), and also the necessary platform
- setup.
-
-2. Call `psci_setup()` in Monitor mode.
-
-3. Optionally call `psci_register_spd_pm_hook()` to register callbacks to
- do bookkeeping for the EL3 Runtime Software during power management.
-
-4. Call `psci_prepare_next_non_secure_ctx()` to initialize the non-secure CPU
- context.
-
-5. Get the non-secure `cpu_context_t` for the current CPU by calling
- `cm_get_context()` , then programming the registers in the non-secure
- context and exiting to non-secure world. If the EL3 Runtime Software needs
- additional configuration to be set for non-secure context, like routing
- FIQs to the secure world, the values of the registers can be modified prior
- to programming. See [section 3](#3-psci-cpu-context-management) for more
- details on CPU context management.
-
-The generic call sequence of PSCI library interfaces during warm boot in
-AArch32 systems is described below:
-
-1. After warm reset, the EL3 Runtime Software performs the necessary warm
- boot initialization including the PSCI library pre-requisites mentioned in
- [section 4](#4-psci-library-interface) (Note that the Data cache
- **must not** be enabled).
-
-2. Call `psci_warmboot_entrypoint()` in Monitor mode. This interface
- initializes/restores the non-secure CPU context as well.
-
-3. Do step 5 of the cold boot call sequence described above.
-
-The generic call sequence of PSCI library interfaces on receipt of a PSCI SMC
-on an AArch32 system is described below:
-
-1. On receipt of an SMC, save the register context as per [SMCCC].
-
-2. If the SMC function identifier corresponds to a SMC32 PSCI API, construct
- the appropriate arguments and call the `psci_smc_handler()` interface.
- The invocation may or may not return back to the caller depending on
- whether the PSCI API resulted in power down of the CPU.
-
-3. If `psci_smc_handler()` returns, populate the return value in R0 (AArch32)/
- X0 (AArch64) and restore other registers as per [SMCCC].
-
-
-3. PSCI CPU context management
-------------------------------
-
-PSCI library is in charge of initializing/restoring the non-secure CPU system
-registers according to [PSCI specification][PSCI spec] during cold/warm boot.
-This is referred to as `PSCI CPU Context Management`. Registers that need to
-be preserved across CPU power down/power up cycles are maintained in
-`cpu_context_t` data structure. The initialization of other non-secure CPU
-system registers which do not require coordination with the EL3 Runtime
-Software is done directly by the PSCI library (see `cm_prepare_el3_exit()`).
-
-The EL3 Runtime Software is responsible for managing register context
-during switch between Normal and Secure worlds. The register context to be
-saved and restored depends on the mechanism used to trigger the world switch.
-For example, if the world switch was triggered by an SMC call, then the
-registers need to be saved and restored according to [SMCCC]. In AArch64,
-due to the tight integration with BL31, both BL31 and PSCI library
-use the same `cpu_context_t` data structure for PSCI CPU context management
-and register context management during world switch. This cannot be assumed
-for AArch32 EL3 Runtime Software since most AArch32 Trusted OSes already implement
-a mechanism for register context management during world switch. Hence, when
-the PSCI library is integrated with a AArch32 EL3 Runtime Software, the
-`cpu_context_t` is stripped down for just PSCI CPU context management.
-
-During cold/warm boot, after invoking appropriate PSCI library interfaces, it
-is expected that the EL3 Runtime Software will query the `cpu_context_t` and
-write appropriate values to the corresponding system registers. This mechanism
-resolves 2 additional problems for AArch32 EL3 Runtime Software:
-
-1. Values for certain system registers like SCR and SCTLR cannot be
- unilaterally determined by PSCI library and need inputs from the EL3
- Runtime Software. Using `cpu_context_t` as an intermediary data store
- allows EL3 Runtime Software to modify the register values appropriately
- before programming them.
-
-2. The PSCI library provides appropriate LR and SPSR values (entrypoint
- information) for exit into non-secure world. Using `cpu_context_t` as an
- intermediary data store allows the EL3 Runtime Software to store these
- values safely until it is ready for exit to non-secure world.
-
-Currently the `cpu_context_t` data structure for AArch32 stores the following
-registers: R0 - R3, LR (R14), SCR, SPSR, SCTLR.
-
-The EL3 Runtime Software must implement accessors to get/set pointers
-to CPU context `cpu_context_t` data and these are described in
-[section 5.2](#52-cpu-context-management-api).
-
-
-4. PSCI Library Interface
--------------------------
-
-The PSCI library implements the [PSCI Specification][PSCI spec]. The interfaces
-to this library are declared in `psci.h` and are as listed below:
-
-```
- u_register_t psci_smc_handler(uint32_t smc_fid, u_register_t x1,
- u_register_t x2, u_register_t x3,
- u_register_t x4, void *cookie,
- void *handle, u_register_t flags);
- int psci_setup(const psci_lib_args_t *lib_args);
- void psci_warmboot_entrypoint(void);
- void psci_register_spd_pm_hook(const spd_pm_ops_t *pm);
- void psci_prepare_next_non_secure_ctx(entry_point_info_t *next_image_info);
-```
-
-The CPU context data 'cpu_context_t' is programmed to the registers differently
-when PSCI is integrated with an AArch32 EL3 Runtime Software compared to
-when the PSCI is integrated with an AArch64 EL3 Runtime Software (BL31). For
-example, in the case of AArch64, there is no need to retrieve `cpu_context_t`
-data and program the registers as it will done implicitly as part of
-`el3_exit`. The description below of the PSCI interfaces is targeted at
-integration with an AArch32 EL3 Runtime Software.
-
-The PSCI library is responsible for initializing/restoring the non-secure world
-to an appropriate state after boot and may choose to directly program the
-non-secure system registers. The PSCI generic code takes care not to directly
-modify any of the system registers affecting the secure world and instead
-returns the values to be programmed to these registers via `cpu_context_t`.
-The EL3 Runtime Software is responsible for programming those registers and
-can use the proposed values provided in the `cpu_context_t`, modifying the
-values if required.
-
-PSCI library needs the flexibility to access both secure and non-secure
-copies of banked registers. Hence it needs to be invoked in Monitor mode
-for AArch32 and in EL3 for AArch64. The NS bit in SCR (in AArch32) or SCR_EL3
-(in AArch64) must be set to 0. Additional requirements for the PSCI library
-interfaces are:
-
- * Instruction cache must be enabled
- * Both IRQ and FIQ must be masked for the current CPU
- * The page tables must be setup and the MMU enabled
- * The C runtime environment must be setup and stack initialized
- * The Data cache must be enabled prior to invoking any of the PSCI library
- interfaces except for `psci_warmboot_entrypoint()`. For
- `psci_warmboot_entrypoint()`, if the build option `HW_ASSISTED_COHERENCY`
- is enabled however, data caches are expected to be enabled.
-
-Further requirements for each interface can be found in the interface
-description.
-
-### 4.1 Interface : psci_setup()
-
- Argument : const psci_lib_args_t *lib_args
- Return : void
-
-This function is to be called by the primary CPU during cold boot before
-any other interface to the PSCI library. It takes `lib_args`, a const pointer
-to `psci_lib_args_t`, as the argument. The `psci_lib_args_t` is a versioned
-structure and is declared in `psci.h` header as follows:
-
-```
- typedef struct psci_lib_args {
- /* The version information of PSCI Library Interface */
- param_header_t h;
- /* The warm boot entrypoint function */
- mailbox_entrypoint_t mailbox_ep;
- } psci_lib_args_t;
-```
-
-The first field `h`, of `param_header_t` type, provides the version
-information. The second field `mailbox_ep` is the warm boot entrypoint address
-and is used to configure the platform mailbox. Helper macros are provided in
-psci.h to construct the `lib_args` argument statically or during runtime. Prior
-to calling the `psci_setup()` interface, the platform setup for cold boot
-must have completed. Major actions performed by this interface are:
-
- * Initializes architecture.
- * Initializes PSCI power domain and state coordination data structures.
- * Calls `plat_setup_psci_ops()` with warm boot entrypoint `mailbox_ep` as
- argument.
- * Calls `cm_set_context_by_index()` (see
- [section 5.2](#52-cpu-context-management-api)) for all the CPUs in the
- platform
-
-### 4.2 Interface : psci_prepare_next_non_secure_ctx()
-
- Argument : entry_point_info_t *next_image_info
- Return : void
-
-After `psci_setup()` and prior to exit to the non-secure world, this function
-must be called by the EL3 Runtime Software to initialize the non-secure world
-context. The non-secure world entrypoint information `next_image_info` (first
-argument) will be used to determine the non-secure context. After this function
-returns, the EL3 Runtime Software must retrieve the `cpu_context_t` (using
-cm_get_context()) for the current CPU and program the registers prior to exit
-to the non-secure world.
-
-### 4.3 Interface : psci_register_spd_pm_hook()
-
- Argument : const spd_pm_ops_t *
- Return : void
-
-As explained in [section 5.4](#54-secure-payload-power-management-callback),
-the EL3 Runtime Software may want to perform some bookkeeping during power
-management operations. This function is used to register the `spd_pm_ops_t`
-(first argument) callbacks with the PSCI library which will be called
-ppropriately during power management. Calling this function is optional and
-need to be called by the primary CPU during the cold boot sequence after
-`psci_setup()` has completed.
-
-### 4.4 Interface : psci_smc_handler()
-
- Argument : uint32_t smc_fid, u_register_t x1,
- u_register_t x2, u_register_t x3,
- u_register_t x4, void *cookie,
- void *handle, u_register_t flags
- Return : u_register_t
-
-This function is the top level handler for SMCs which fall within the
-PSCI service range specified in [SMCCC]. The function ID `smc_fid` (first
-argument) determines the PSCI API to be called. The `x1` to `x4` (2nd to 5th
-arguments), are the values of the registers r1 - r4 (in AArch32) or x1 - x4
-(in AArch64) when the SMC is received. These are the arguments to PSCI API as
-described in [PSCI spec]. The 'flags' (8th argument) is a bit field parameter
-and is detailed in 'smcc.h' header. It includes whether the call is from the
-secure or non-secure world. The `cookie` (6th argument) and the `handle`
-(7th argument) are not used and are reserved for future use.
-
-The return value from this interface is the return value from the underlying
-PSCI API corresponding to `smc_fid`. This function may not return back to the
-caller if PSCI API causes power down of the CPU. In this case, when the CPU
-wakes up, it will start execution from the warm reset address.
-
-### 4.5 Interface : psci_warmboot_entrypoint()
-
- Argument : void
- Return : void
-
-This function performs the warm boot initialization/restoration as mandated by
-[PSCI spec]. For AArch32, on wakeup from power down the CPU resets to secure SVC
-mode and the EL3 Runtime Software must perform the prerequisite initializations
-mentioned at top of this section. This function must be called with Data cache
-disabled (unless build option `HW_ASSISTED_COHERENCY` is enabled) but with MMU
-initialized and enabled. The major actions performed by this function are:
-
- * Invalidates the stack and enables the data cache.
- * Initializes architecture and PSCI state coordination.
- * Restores/Initializes the peripheral drivers to the required state via
- appropriate `plat_psci_ops_t` hooks
- * Restores the EL3 Runtime Software context via appropriate `spd_pm_ops_t`
- callbacks.
- * Restores/Initializes the non-secure context and populates the
- `cpu_context_t` for the current CPU.
-
-Upon the return of this function, the EL3 Runtime Software must retrieve the
-non-secure `cpu_context_t` using `cm_get_context()` and program the registers
-prior to exit to the non-secure world.
-
-
-5. EL3 Runtime Software dependencies
----------------------------------------
-
-The PSCI Library includes supporting frameworks like context management,
-cpu operations (cpu_ops) and per-cpu data framework. Other helper library
-functions like bakery locks and spin locks are also included in the library.
-The dependencies which must be fulfilled by the EL3 Runtime Software
-for integration with PSCI library are described below.
-
-### 5.1 General dependencies
-
-The PSCI library being a Multiprocessor (MP) implementation, EL3 Runtime
-Software must provide an SMC handling framework capable of MP adhering to
-[SMCCC] specification.
-
-The EL3 Runtime Software must also export cache maintenance primitives
-and some helper utilities for assert, print and memory operations as listed
-below. The ARM Trusted Firmware source tree provides implementations for all
-these functions but the EL3 Runtime Software may use its own implementation.
-
-**Functions : assert(), memcpy(), memset**
-
-These must be implemented as described in ISO C Standard.
-
-**Function : flush_dcache_range()**
-
- Argument : uintptr_t addr, size_t size
- Return : void
-
-This function cleans and invalidates (flushes) the data cache for memory
-at address `addr` (first argument) address and of size `size` (second argument).
-
-**Function : inv_dcache_range()**
-
- Argument : uintptr_t addr, size_t size
- Return : void
-
-This function invalidates (flushes) the data cache for memory at address
-`addr` (first argument) address and of size `size` (second argument).
-
-**Function : do_panic()**
-
- Argument : void
- Return : void
-
-This function will be called by the PSCI library on encountering a critical
-failure that cannot be recovered from. This function **must not** return.
-
-**Function : tf_printf()**
-
-This is printf-compatible function, but unlike printf, it does not return any
-value. The ARM Trusted Firmware source tree provides an implementation which
-is optimized for stack usage and supports only a subset of format specifiers.
-The details of the format specifiers supported can be found in the
-`tf_printf.c` file in ARM Trusted Firmware source tree.
-
-### 5.2 CPU Context management API
-
-The CPU context management data memory is statically allocated by PSCI library
-in BSS section. The PSCI library requires the EL3 Runtime Software to implement
-APIs to store and retrieve pointers to this CPU context data. SP-MIN
-demonstrates how these APIs can be implemented but the EL3 Runtime Software can
-choose a more optimal implementation (like dedicating the secure TPIDRPRW
-system register (in AArch32) for storing these pointers).
-
-**Function : cm_set_context_by_index()**
-
- Argument : unsigned int cpu_idx, void *context, unsigned int security_state
- Return : void
-
-This function is called during cold boot when the `psci_setup()` PSCI library
-interface is called.
-
-This function must store the pointer to the CPU context data, `context` (2nd
-argument), for the specified `security_state` (3rd argument) and CPU identified
-by `cpu_idx` (first argument). The `security_state` will always be non-secure
-when called by PSCI library and this argument is retained for compatibility
-with BL31. The `cpu_idx` will correspond to the index returned by the
-`plat_core_pos_by_mpidr()` for `mpidr` of the CPU.
-
-The actual method of storing the `context` pointers is implementation specific.
-For example, SP-MIN stores the pointers in the array `sp_min_cpu_ctx_ptr`
-declared in `sp_min_main.c`.
-
-**Function : cm_get_context()**
-
- Argument : uint32_t security_state
- Return : void *
-
-This function must return the pointer to the `cpu_context_t` structure for
-the specified `security_state` (first argument) for the current CPU. The caller
-must ensure that `cm_set_context_by_index` is called first and the appropriate
-context pointers are stored prior to invoking this API. The `security_state`
-will always be non-secure when called by PSCI library and this argument
-is retained for compatibility with BL31.
-
-**Function : cm_get_context_by_index()**
-
- Argument : unsigned int cpu_idx, unsigned int security_state
- Return : void *
-
-This function must return the pointer to the `cpu_context_t` structure for
-the specified `security_state` (second argument) for the CPU identified by
-`cpu_idx` (first argument). The caller must ensure that
-`cm_set_context_by_index` is called first and the appropriate context
-pointers are stored prior to invoking this API. The `security_state` will
-always be non-secure when called by PSCI library and this argument is
-retained for compatibility with BL31. The `cpu_idx` will correspond to the
-index returned by the `plat_core_pos_by_mpidr()` for `mpidr` of the CPU.
-
-### 5.3 Platform API
-
-The platform layer abstracts the platform-specific details from the generic
-PSCI library. The following platform APIs/macros must be defined by the EL3
-Runtime Software for integration with the PSCI library.
-
-The mandatory platform APIs are:
-
- * plat_my_core_pos
- * plat_core_pos_by_mpidr
- * plat_get_syscnt_freq2
- * plat_get_power_domain_tree_desc
- * plat_setup_psci_ops
- * plat_reset_handler
- * plat_panic_handler
- * plat_get_my_stack
-
-The mandatory platform macros are:
-
- * PLATFORM_CORE_COUNT
- * PLAT_MAX_PWR_LVL
- * PLAT_NUM_PWR_DOMAINS
- * CACHE_WRITEBACK_GRANULE
- * PLAT_MAX_OFF_STATE
- * PLAT_MAX_RET_STATE
- * PLAT_MAX_PWR_LVL_STATES (optional)
- * PLAT_PCPU_DATA_SIZE (optional)
-
-The details of these APIs/macros can be found in [Porting Guide].
-
-All platform specific operations for power management are done via
-`plat_psci_ops_t` callbacks registered by the platform when
-`plat_setup_psci_ops()` API is called. The description of each of
-the callbacks in `plat_psci_ops_t` can be found in PSCI section of the
-[Porting Guide]. If any these callbacks are not registered, then the
-PSCI API associated with that callback will not be supported by PSCI
-library.
-
-### 5.4 Secure payload power management callback
-
-During PSCI power management operations, the EL3 Runtime Software may
-need to perform some bookkeeping, and PSCI library provides
-`spd_pm_ops_t` callbacks for this purpose. These hooks must be
-populated and registered by using `psci_register_spd_pm_hook()` PSCI
-library interface.
-
-Typical bookkeeping during PSCI power management calls include save/restore
-of the EL3 Runtime Software context. Also if the EL3 Runtime Software makes
-use of secure interrupts, then these interrupts must also be managed
-appropriately during CPU power down/power up. Any secure interrupt targeted
-to the current CPU must be disabled or re-targeted to other running CPU prior
-to power down of the current CPU. During power up, these interrupt can be
-enabled/re-targeted back to the current CPU.
-
-```
- typedef struct spd_pm_ops {
- void (*svc_on)(u_register_t target_cpu);
- int32_t (*svc_off)(u_register_t __unused);
- void (*svc_suspend)(u_register_t max_off_pwrlvl);
- void (*svc_on_finish)(u_register_t __unused);
- void (*svc_suspend_finish)(u_register_t max_off_pwrlvl);
- int32_t (*svc_migrate)(u_register_t from_cpu, u_register_t to_cpu);
- int32_t (*svc_migrate_info)(u_register_t *resident_cpu);
- void (*svc_system_off)(void);
- void (*svc_system_reset)(void);
- } spd_pm_ops_t;
-```
-A brief description of each callback is given below:
-
-* svc_on, svc_off, svc_on_finish
-
- The `svc_on`, `svc_off` callbacks are called during PSCI_CPU_ON,
- PSCI_CPU_OFF APIs respectively. The `svc_on_finish` is called when the
- target CPU of PSCI_CPU_ON API powers up and executes the
- `psci_warmboot_entrypoint()` PSCI library interface.
-
-* svc_suspend, svc_suspend_finish
-
- The `svc_suspend` callback is called during power down bu either
- PSCI_SUSPEND or PSCI_SYSTEM_SUSPEND APIs. The `svc_suspend_finish` is
- called when the CPU wakes up from suspend and executes the
- `psci_warmboot_entrypoint()` PSCI library interface. The `max_off_pwrlvl`
- (first parameter) denotes the highest power domain level being powered down
- to or woken up from suspend.
-
-* svc_system_off, svc_system_reset
-
- These callbacks are called during PSCI_SYSTEM_OFF and PSCI_SYSTEM_RESET
- PSCI APIs respectively.
-
-* svc_migrate_info
-
- This callback is called in response to PSCI_MIGRATE_INFO_TYPE or
- PSCI_MIGRATE_INFO_UP_CPU APIs. The return value of this callback must
- correspond to the return value of PSCI_MIGRATE_INFO_TYPE API as described
- in [PSCI spec]. If the secure payload is a Uniprocessor (UP)
- implementation, then it must update the mpidr of the CPU it is resident in
- via `resident_cpu` (first argument). The updates to `resident_cpu` is
- ignored if the secure payload is a multiprocessor (MP) implementation.
-
-* svc_migrate
-
- This callback is only relevant if the secure payload in EL3 Runtime
- Software is a Uniprocessor (UP) implementation and supports migration from
- the current CPU `from_cpu` (first argument) to another CPU `to_cpu`
- (second argument). This callback is called in response to PSCI_MIGRATE
- API. This callback is never called if the secure payload is a
- Multiprocessor (MP) implementation.
-
-### 5.5 CPU operations
-
-The CPU operations (cpu_ops) framework implement power down sequence specific
-to the CPU and the details of which can be found in the `CPU specific
-operations framework` section of [Firmware Design]. The ARM Trusted Firmware
-tree implements the `cpu_ops` for various supported CPUs and the EL3 Runtime
-Software needs to include the required `cpu_ops` in its build. The start and
-end of the `cpu_ops` descriptors must be exported by the EL3 Runtime Software
-via the `__CPU_OPS_START__` and `__CPU_OPS_END__` linker symbols.
-
-The `cpu_ops` descriptors also include reset sequences and may include errata
-workarounds for the CPU. The EL3 Runtime Software can choose to call this
-during cold/warm reset if it does not implement its own reset sequence/errata
-workarounds.
-
-
-- - - - - - - - - - - - - - - - - - - - - - - - - -
-
-_Copyright (c) 2016, ARM Limited and Contributors. All rights reserved._
-
-[PSCI spec]: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf "Power State Coordination Interface PDD (ARM DEN 0022C)"
-[SMCCC]: https://silver.arm.com/download/ARM_and_AMBA_Architecture/AR570-DA-80002-r0p0-00rel0/ARM_DEN0028A_SMC_Calling_Convention.pdf "SMC Calling Convention"
-[Porting Guide]: porting-guide.md
-[Firmware Design]: ./firmware-design.md
diff --git a/docs/psci-lib-integration-guide.rst b/docs/psci-lib-integration-guide.rst
new file mode 100644
index 0000000..5e788d1
--- /dev/null
+++ b/docs/psci-lib-integration-guide.rst
@@ -0,0 +1,560 @@
+PSCI Library Integration guide for ARMv8-A AArch32 systems
+==========================================================
+
+
+.. section-numbering::
+ :suffix: .
+
+.. contents::
+
+This document describes the PSCI library interface with a focus on how to
+integrate with a suitable Trusted OS for an ARMv8-A AArch32 system. The PSCI
+Library implements the PSCI Standard as described in `PSCI spec`_ and is meant
+to be integrated with EL3 Runtime Software which invokes the PSCI Library
+interface appropriately. **EL3 Runtime Software** refers to software executing
+at the highest secure privileged mode, which is EL3 in AArch64 or Secure SVC/
+Monitor mode in AArch32, and provides runtime services to the non-secure world.
+The runtime service request is made via SMC (Secure Monitor Call) and the call
+must adhere to `SMCCC`_. In AArch32, EL3 Runtime Software may additionally
+include Trusted OS functionality. A minimal AArch32 Secure Payload, SP-MIN, is
+provided in ARM Trusted Firmware to illustrate the usage and integration of the
+PSCI library. The description of PSCI library interface and its integration
+with EL3 Runtime Software in this document is targeted towards AArch32 systems.
+
+Generic call sequence for PSCI Library interface (AArch32)
+----------------------------------------------------------
+
+The generic call sequence of PSCI Library interfaces (see
+`PSCI Library Interface`_) during cold boot in AArch32
+system is described below:
+
+#. After cold reset, the EL3 Runtime Software performs its cold boot
+ initialization including the PSCI library pre-requisites mentioned in
+ `PSCI Library Interface`_, and also the necessary platform
+ setup.
+
+#. Call ``psci_setup()`` in Monitor mode.
+
+#. Optionally call ``psci_register_spd_pm_hook()`` to register callbacks to
+ do bookkeeping for the EL3 Runtime Software during power management.
+
+#. Call ``psci_prepare_next_non_secure_ctx()`` to initialize the non-secure CPU
+ context.
+
+#. Get the non-secure ``cpu_context_t`` for the current CPU by calling
+ ``cm_get_context()`` , then programming the registers in the non-secure
+ context and exiting to non-secure world. If the EL3 Runtime Software needs
+ additional configuration to be set for non-secure context, like routing
+ FIQs to the secure world, the values of the registers can be modified prior
+ to programming. See `PSCI CPU context management`_ for more
+ details on CPU context management.
+
+The generic call sequence of PSCI library interfaces during warm boot in
+AArch32 systems is described below:
+
+#. After warm reset, the EL3 Runtime Software performs the necessary warm
+ boot initialization including the PSCI library pre-requisites mentioned in
+ `PSCI Library Interface`_ (Note that the Data cache
+ **must not** be enabled).
+
+#. Call ``psci_warmboot_entrypoint()`` in Monitor mode. This interface
+ initializes/restores the non-secure CPU context as well.
+
+#. Do step 5 of the cold boot call sequence described above.
+
+The generic call sequence of PSCI library interfaces on receipt of a PSCI SMC
+on an AArch32 system is described below:
+
+#. On receipt of an SMC, save the register context as per `SMCCC`_.
+
+#. If the SMC function identifier corresponds to a SMC32 PSCI API, construct
+ the appropriate arguments and call the ``psci_smc_handler()`` interface.
+ The invocation may or may not return back to the caller depending on
+ whether the PSCI API resulted in power down of the CPU.
+
+#. If ``psci_smc_handler()`` returns, populate the return value in R0 (AArch32)/
+ X0 (AArch64) and restore other registers as per `SMCCC`_.
+
+PSCI CPU context management
+---------------------------
+
+PSCI library is in charge of initializing/restoring the non-secure CPU system
+registers according to `PSCI specification`_ during cold/warm boot.
+This is referred to as ``PSCI CPU Context Management``. Registers that need to
+be preserved across CPU power down/power up cycles are maintained in
+``cpu_context_t`` data structure. The initialization of other non-secure CPU
+system registers which do not require coordination with the EL3 Runtime
+Software is done directly by the PSCI library (see ``cm_prepare_el3_exit()``).
+
+The EL3 Runtime Software is responsible for managing register context
+during switch between Normal and Secure worlds. The register context to be
+saved and restored depends on the mechanism used to trigger the world switch.
+For example, if the world switch was triggered by an SMC call, then the
+registers need to be saved and restored according to `SMCCC`_. In AArch64,
+due to the tight integration with BL31, both BL31 and PSCI library
+use the same ``cpu_context_t`` data structure for PSCI CPU context management
+and register context management during world switch. This cannot be assumed
+for AArch32 EL3 Runtime Software since most AArch32 Trusted OSes already implement
+a mechanism for register context management during world switch. Hence, when
+the PSCI library is integrated with a AArch32 EL3 Runtime Software, the
+``cpu_context_t`` is stripped down for just PSCI CPU context management.
+
+During cold/warm boot, after invoking appropriate PSCI library interfaces, it
+is expected that the EL3 Runtime Software will query the ``cpu_context_t`` and
+write appropriate values to the corresponding system registers. This mechanism
+resolves 2 additional problems for AArch32 EL3 Runtime Software:
+
+#. Values for certain system registers like SCR and SCTLR cannot be
+ unilaterally determined by PSCI library and need inputs from the EL3
+ Runtime Software. Using ``cpu_context_t`` as an intermediary data store
+ allows EL3 Runtime Software to modify the register values appropriately
+ before programming them.
+
+#. The PSCI library provides appropriate LR and SPSR values (entrypoint
+ information) for exit into non-secure world. Using ``cpu_context_t`` as an
+ intermediary data store allows the EL3 Runtime Software to store these
+ values safely until it is ready for exit to non-secure world.
+
+Currently the ``cpu_context_t`` data structure for AArch32 stores the following
+registers: R0 - R3, LR (R14), SCR, SPSR, SCTLR.
+
+The EL3 Runtime Software must implement accessors to get/set pointers
+to CPU context ``cpu_context_t`` data and these are described in
+`CPU Context management API`_.
+
+PSCI Library Interface
+----------------------
+
+The PSCI library implements the `PSCI Specification`_. The interfaces
+to this library are declared in ``psci.h`` and are as listed below:
+
+.. code:: c
+
+ u_register_t psci_smc_handler(uint32_t smc_fid, u_register_t x1,
+ u_register_t x2, u_register_t x3,
+ u_register_t x4, void *cookie,
+ void *handle, u_register_t flags);
+ int psci_setup(const psci_lib_args_t *lib_args);
+ void psci_warmboot_entrypoint(void);
+ void psci_register_spd_pm_hook(const spd_pm_ops_t *pm);
+ void psci_prepare_next_non_secure_ctx(entry_point_info_t *next_image_info);
+
+The CPU context data 'cpu\_context\_t' is programmed to the registers differently
+when PSCI is integrated with an AArch32 EL3 Runtime Software compared to
+when the PSCI is integrated with an AArch64 EL3 Runtime Software (BL31). For
+example, in the case of AArch64, there is no need to retrieve ``cpu_context_t``
+data and program the registers as it will done implicitly as part of
+``el3_exit``. The description below of the PSCI interfaces is targeted at
+integration with an AArch32 EL3 Runtime Software.
+
+The PSCI library is responsible for initializing/restoring the non-secure world
+to an appropriate state after boot and may choose to directly program the
+non-secure system registers. The PSCI generic code takes care not to directly
+modify any of the system registers affecting the secure world and instead
+returns the values to be programmed to these registers via ``cpu_context_t``.
+The EL3 Runtime Software is responsible for programming those registers and
+can use the proposed values provided in the ``cpu_context_t``, modifying the
+values if required.
+
+PSCI library needs the flexibility to access both secure and non-secure
+copies of banked registers. Hence it needs to be invoked in Monitor mode
+for AArch32 and in EL3 for AArch64. The NS bit in SCR (in AArch32) or SCR\_EL3
+(in AArch64) must be set to 0. Additional requirements for the PSCI library
+interfaces are:
+
+- Instruction cache must be enabled
+- Both IRQ and FIQ must be masked for the current CPU
+- The page tables must be setup and the MMU enabled
+- The C runtime environment must be setup and stack initialized
+- The Data cache must be enabled prior to invoking any of the PSCI library
+ interfaces except for ``psci_warmboot_entrypoint()``. For
+ ``psci_warmboot_entrypoint()``, if the build option ``HW_ASSISTED_COHERENCY``
+ is enabled however, data caches are expected to be enabled.
+
+Further requirements for each interface can be found in the interface
+description.
+
+Interface : psci\_setup()
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : const psci_lib_args_t *lib_args
+ Return : void
+
+This function is to be called by the primary CPU during cold boot before
+any other interface to the PSCI library. It takes ``lib_args``, a const pointer
+to ``psci_lib_args_t``, as the argument. The ``psci_lib_args_t`` is a versioned
+structure and is declared in ``psci.h`` header as follows:
+
+.. code:: c
+
+ typedef struct psci_lib_args {
+ /* The version information of PSCI Library Interface */
+ param_header_t h;
+ /* The warm boot entrypoint function */
+ mailbox_entrypoint_t mailbox_ep;
+ } psci_lib_args_t;
+
+The first field ``h``, of ``param_header_t`` type, provides the version
+information. The second field ``mailbox_ep`` is the warm boot entrypoint address
+and is used to configure the platform mailbox. Helper macros are provided in
+psci.h to construct the ``lib_args`` argument statically or during runtime. Prior
+to calling the ``psci_setup()`` interface, the platform setup for cold boot
+must have completed. Major actions performed by this interface are:
+
+- Initializes architecture.
+- Initializes PSCI power domain and state coordination data structures.
+- Calls ``plat_setup_psci_ops()`` with warm boot entrypoint ``mailbox_ep`` as
+ argument.
+- Calls ``cm_set_context_by_index()`` (see
+ `CPU Context management API`_) for all the CPUs in the
+ platform
+
+Interface : psci\_prepare\_next\_non\_secure\_ctx()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : entry_point_info_t *next_image_info
+ Return : void
+
+After ``psci_setup()`` and prior to exit to the non-secure world, this function
+must be called by the EL3 Runtime Software to initialize the non-secure world
+context. The non-secure world entrypoint information ``next_image_info`` (first
+argument) will be used to determine the non-secure context. After this function
+returns, the EL3 Runtime Software must retrieve the ``cpu_context_t`` (using
+cm\_get\_context()) for the current CPU and program the registers prior to exit
+to the non-secure world.
+
+Interface : psci\_register\_spd\_pm\_hook()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : const spd_pm_ops_t *
+ Return : void
+
+As explained in `Secure payload power management callback`_,
+the EL3 Runtime Software may want to perform some bookkeeping during power
+management operations. This function is used to register the ``spd_pm_ops_t``
+(first argument) callbacks with the PSCI library which will be called
+ppropriately during power management. Calling this function is optional and
+need to be called by the primary CPU during the cold boot sequence after
+``psci_setup()`` has completed.
+
+Interface : psci\_smc\_handler()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : uint32_t smc_fid, u_register_t x1,
+ u_register_t x2, u_register_t x3,
+ u_register_t x4, void *cookie,
+ void *handle, u_register_t flags
+ Return : u_register_t
+
+This function is the top level handler for SMCs which fall within the
+PSCI service range specified in `SMCCC`_. The function ID ``smc_fid`` (first
+argument) determines the PSCI API to be called. The ``x1`` to ``x4`` (2nd to 5th
+arguments), are the values of the registers r1 - r4 (in AArch32) or x1 - x4
+(in AArch64) when the SMC is received. These are the arguments to PSCI API as
+described in `PSCI spec`_. The 'flags' (8th argument) is a bit field parameter
+and is detailed in 'smcc.h' header. It includes whether the call is from the
+secure or non-secure world. The ``cookie`` (6th argument) and the ``handle``
+(7th argument) are not used and are reserved for future use.
+
+The return value from this interface is the return value from the underlying
+PSCI API corresponding to ``smc_fid``. This function may not return back to the
+caller if PSCI API causes power down of the CPU. In this case, when the CPU
+wakes up, it will start execution from the warm reset address.
+
+Interface : psci\_warmboot\_entrypoint()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : void
+
+This function performs the warm boot initialization/restoration as mandated by
+`PSCI spec`_. For AArch32, on wakeup from power down the CPU resets to secure SVC
+mode and the EL3 Runtime Software must perform the prerequisite initializations
+mentioned at top of this section. This function must be called with Data cache
+disabled (unless build option ``HW_ASSISTED_COHERENCY`` is enabled) but with MMU
+initialized and enabled. The major actions performed by this function are:
+
+- Invalidates the stack and enables the data cache.
+- Initializes architecture and PSCI state coordination.
+- Restores/Initializes the peripheral drivers to the required state via
+ appropriate ``plat_psci_ops_t`` hooks
+- Restores the EL3 Runtime Software context via appropriate ``spd_pm_ops_t``
+ callbacks.
+- Restores/Initializes the non-secure context and populates the
+ ``cpu_context_t`` for the current CPU.
+
+Upon the return of this function, the EL3 Runtime Software must retrieve the
+non-secure ``cpu_context_t`` using ``cm_get_context()`` and program the registers
+prior to exit to the non-secure world.
+
+EL3 Runtime Software dependencies
+---------------------------------
+
+The PSCI Library includes supporting frameworks like context management,
+cpu operations (cpu\_ops) and per-cpu data framework. Other helper library
+functions like bakery locks and spin locks are also included in the library.
+The dependencies which must be fulfilled by the EL3 Runtime Software
+for integration with PSCI library are described below.
+
+General dependencies
+~~~~~~~~~~~~~~~~~~~~
+
+The PSCI library being a Multiprocessor (MP) implementation, EL3 Runtime
+Software must provide an SMC handling framework capable of MP adhering to
+`SMCCC`_ specification.
+
+The EL3 Runtime Software must also export cache maintenance primitives
+and some helper utilities for assert, print and memory operations as listed
+below. The ARM Trusted Firmware source tree provides implementations for all
+these functions but the EL3 Runtime Software may use its own implementation.
+
+**Functions : assert(), memcpy(), memset**
+
+These must be implemented as described in ISO C Standard.
+
+**Function : flush\_dcache\_range()**
+
+::
+
+ Argument : uintptr_t addr, size_t size
+ Return : void
+
+This function cleans and invalidates (flushes) the data cache for memory
+at address ``addr`` (first argument) address and of size ``size`` (second argument).
+
+**Function : inv\_dcache\_range()**
+
+::
+
+ Argument : uintptr_t addr, size_t size
+ Return : void
+
+This function invalidates (flushes) the data cache for memory at address
+``addr`` (first argument) address and of size ``size`` (second argument).
+
+**Function : do\_panic()**
+
+::
+
+ Argument : void
+ Return : void
+
+This function will be called by the PSCI library on encountering a critical
+failure that cannot be recovered from. This function **must not** return.
+
+**Function : tf\_printf()**
+
+This is printf-compatible function, but unlike printf, it does not return any
+value. The ARM Trusted Firmware source tree provides an implementation which
+is optimized for stack usage and supports only a subset of format specifiers.
+The details of the format specifiers supported can be found in the
+``tf_printf.c`` file in ARM Trusted Firmware source tree.
+
+CPU Context management API
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The CPU context management data memory is statically allocated by PSCI library
+in BSS section. The PSCI library requires the EL3 Runtime Software to implement
+APIs to store and retrieve pointers to this CPU context data. SP-MIN
+demonstrates how these APIs can be implemented but the EL3 Runtime Software can
+choose a more optimal implementation (like dedicating the secure TPIDRPRW
+system register (in AArch32) for storing these pointers).
+
+**Function : cm\_set\_context\_by\_index()**
+
+::
+
+ Argument : unsigned int cpu_idx, void *context, unsigned int security_state
+ Return : void
+
+This function is called during cold boot when the ``psci_setup()`` PSCI library
+interface is called.
+
+This function must store the pointer to the CPU context data, ``context`` (2nd
+argument), for the specified ``security_state`` (3rd argument) and CPU identified
+by ``cpu_idx`` (first argument). The ``security_state`` will always be non-secure
+when called by PSCI library and this argument is retained for compatibility
+with BL31. The ``cpu_idx`` will correspond to the index returned by the
+``plat_core_pos_by_mpidr()`` for ``mpidr`` of the CPU.
+
+The actual method of storing the ``context`` pointers is implementation specific.
+For example, SP-MIN stores the pointers in the array ``sp_min_cpu_ctx_ptr``
+declared in ``sp_min_main.c``.
+
+**Function : cm\_get\_context()**
+
+::
+
+ Argument : uint32_t security_state
+ Return : void *
+
+This function must return the pointer to the ``cpu_context_t`` structure for
+the specified ``security_state`` (first argument) for the current CPU. The caller
+must ensure that ``cm_set_context_by_index`` is called first and the appropriate
+context pointers are stored prior to invoking this API. The ``security_state``
+will always be non-secure when called by PSCI library and this argument
+is retained for compatibility with BL31.
+
+**Function : cm\_get\_context\_by\_index()**
+
+::
+
+ Argument : unsigned int cpu_idx, unsigned int security_state
+ Return : void *
+
+This function must return the pointer to the ``cpu_context_t`` structure for
+the specified ``security_state`` (second argument) for the CPU identified by
+``cpu_idx`` (first argument). The caller must ensure that
+``cm_set_context_by_index`` is called first and the appropriate context
+pointers are stored prior to invoking this API. The ``security_state`` will
+always be non-secure when called by PSCI library and this argument is
+retained for compatibility with BL31. The ``cpu_idx`` will correspond to the
+index returned by the ``plat_core_pos_by_mpidr()`` for ``mpidr`` of the CPU.
+
+Platform API
+~~~~~~~~~~~~
+
+The platform layer abstracts the platform-specific details from the generic
+PSCI library. The following platform APIs/macros must be defined by the EL3
+Runtime Software for integration with the PSCI library.
+
+The mandatory platform APIs are:
+
+- plat\_my\_core\_pos
+- plat\_core\_pos\_by\_mpidr
+- plat\_get\_syscnt\_freq2
+- plat\_get\_power\_domain\_tree\_desc
+- plat\_setup\_psci\_ops
+- plat\_reset\_handler
+- plat\_panic\_handler
+- plat\_get\_my\_stack
+
+The mandatory platform macros are:
+
+- PLATFORM\_CORE\_COUNT
+- PLAT\_MAX\_PWR\_LVL
+- PLAT\_NUM\_PWR\_DOMAINS
+- CACHE\_WRITEBACK\_GRANULE
+- PLAT\_MAX\_OFF\_STATE
+- PLAT\_MAX\_RET\_STATE
+- PLAT\_MAX\_PWR\_LVL\_STATES (optional)
+- PLAT\_PCPU\_DATA\_SIZE (optional)
+
+The details of these APIs/macros can be found in `Porting Guide`_.
+
+All platform specific operations for power management are done via
+``plat_psci_ops_t`` callbacks registered by the platform when
+``plat_setup_psci_ops()`` API is called. The description of each of
+the callbacks in ``plat_psci_ops_t`` can be found in PSCI section of the
+`Porting Guide`_. If any these callbacks are not registered, then the
+PSCI API associated with that callback will not be supported by PSCI
+library.
+
+Secure payload power management callback
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+During PSCI power management operations, the EL3 Runtime Software may
+need to perform some bookkeeping, and PSCI library provides
+``spd_pm_ops_t`` callbacks for this purpose. These hooks must be
+populated and registered by using ``psci_register_spd_pm_hook()`` PSCI
+library interface.
+
+Typical bookkeeping during PSCI power management calls include save/restore
+of the EL3 Runtime Software context. Also if the EL3 Runtime Software makes
+use of secure interrupts, then these interrupts must also be managed
+appropriately during CPU power down/power up. Any secure interrupt targeted
+to the current CPU must be disabled or re-targeted to other running CPU prior
+to power down of the current CPU. During power up, these interrupt can be
+enabled/re-targeted back to the current CPU.
+
+.. code:: c
+
+ typedef struct spd_pm_ops {
+ void (*svc_on)(u_register_t target_cpu);
+ int32_t (*svc_off)(u_register_t __unused);
+ void (*svc_suspend)(u_register_t max_off_pwrlvl);
+ void (*svc_on_finish)(u_register_t __unused);
+ void (*svc_suspend_finish)(u_register_t max_off_pwrlvl);
+ int32_t (*svc_migrate)(u_register_t from_cpu, u_register_t to_cpu);
+ int32_t (*svc_migrate_info)(u_register_t *resident_cpu);
+ void (*svc_system_off)(void);
+ void (*svc_system_reset)(void);
+ } spd_pm_ops_t;
+
+A brief description of each callback is given below:
+
+- svc\_on, svc\_off, svc\_on\_finish
+
+ The ``svc_on``, ``svc_off`` callbacks are called during PSCI\_CPU\_ON,
+ PSCI\_CPU\_OFF APIs respectively. The ``svc_on_finish`` is called when the
+ target CPU of PSCI\_CPU\_ON API powers up and executes the
+ ``psci_warmboot_entrypoint()`` PSCI library interface.
+
+- svc\_suspend, svc\_suspend\_finish
+
+ The ``svc_suspend`` callback is called during power down bu either
+ PSCI\_SUSPEND or PSCI\_SYSTEM\_SUSPEND APIs. The ``svc_suspend_finish`` is
+ called when the CPU wakes up from suspend and executes the
+ ``psci_warmboot_entrypoint()`` PSCI library interface. The ``max_off_pwrlvl``
+ (first parameter) denotes the highest power domain level being powered down
+ to or woken up from suspend.
+
+- svc\_system\_off, svc\_system\_reset
+
+ These callbacks are called during PSCI\_SYSTEM\_OFF and PSCI\_SYSTEM\_RESET
+ PSCI APIs respectively.
+
+- svc\_migrate\_info
+
+ This callback is called in response to PSCI\_MIGRATE\_INFO\_TYPE or
+ PSCI\_MIGRATE\_INFO\_UP\_CPU APIs. The return value of this callback must
+ correspond to the return value of PSCI\_MIGRATE\_INFO\_TYPE API as described
+ in `PSCI spec`_. If the secure payload is a Uniprocessor (UP)
+ implementation, then it must update the mpidr of the CPU it is resident in
+ via ``resident_cpu`` (first argument). The updates to ``resident_cpu`` is
+ ignored if the secure payload is a multiprocessor (MP) implementation.
+
+- svc\_migrate
+
+ This callback is only relevant if the secure payload in EL3 Runtime
+ Software is a Uniprocessor (UP) implementation and supports migration from
+ the current CPU ``from_cpu`` (first argument) to another CPU ``to_cpu``
+ (second argument). This callback is called in response to PSCI\_MIGRATE
+ API. This callback is never called if the secure payload is a
+ Multiprocessor (MP) implementation.
+
+CPU operations
+~~~~~~~~~~~~~~
+
+The CPU operations (cpu\_ops) framework implement power down sequence specific
+to the CPU and the details of which can be found in the ``CPU specific operations framework`` section of `Firmware Design`_. The ARM Trusted Firmware
+tree implements the ``cpu_ops`` for various supported CPUs and the EL3 Runtime
+Software needs to include the required ``cpu_ops`` in its build. The start and
+end of the ``cpu_ops`` descriptors must be exported by the EL3 Runtime Software
+via the ``__CPU_OPS_START__`` and ``__CPU_OPS_END__`` linker symbols.
+
+The ``cpu_ops`` descriptors also include reset sequences and may include errata
+workarounds for the CPU. The EL3 Runtime Software can choose to call this
+during cold/warm reset if it does not implement its own reset sequence/errata
+workarounds.
+
+--------------
+
+*Copyright (c) 2016, ARM Limited and Contributors. All rights reserved.*
+
+.. _PSCI spec: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
+.. _SMCCC: https://silver.arm.com/download/ARM_and_AMBA_Architecture/AR570-DA-80002-r0p0-00rel0/ARM_DEN0028A_SMC_Calling_Convention.pdf
+.. _PSCI specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
+.. _PSCI Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
+.. _Porting Guide: porting-guide.rst
+.. _Firmware Design: ./firmware-design.rst
diff --git a/docs/psci-pd-tree.md b/docs/psci-pd-tree.md
deleted file mode 100644
index c253905..0000000
--- a/docs/psci-pd-tree.md
+++ /dev/null
@@ -1,295 +0,0 @@
-------------
-Requirements
-------------
-
-1. A platform must export the `plat_get_aff_count()` and
- `plat_get_aff_state()` APIs to enable the generic PSCI code to
- populate a tree that describes the hierarchy of power domains in the
- system. This approach is inflexible because a change to the topology
- requires a change in the code.
-
- It would be much simpler for the platform to describe its power domain tree
- in a data structure.
-
-2. The generic PSCI code generates MPIDRs in order to populate the power domain
- tree. It also uses an MPIDR to find a node in the tree. The assumption that
- a platform will use exactly the same MPIDRs as generated by the generic PSCI
- code is not scalable. The use of an MPIDR also restricts the number of
- levels in the power domain tree to four.
-
- Therefore, there is a need to decouple allocation of MPIDRs from the
- mechanism used to populate the power domain topology tree.
-
-3. The current arrangement of the power domain tree requires a binary search
- over the sibling nodes at a particular level to find a specified power
- domain node. During a power management operation, the tree is traversed from
- a 'start' to an 'end' power level. The binary search is required to find the
- node at each level. The natural way to perform this traversal is to
- start from a leaf node and follow the parent node pointer to reach the end
- level.
-
- Therefore, there is a need to define data structures that implement the tree in
- a way which facilitates such a traversal.
-
-4. The attributes of a core power domain differ from the attributes of power
- domains at higher levels. For example, only a core power domain can be identified
- using an MPIDR. There is no requirement to perform state coordination while
- performing a power management operation on the core power domain.
-
- Therefore, there is a need to implement the tree in a way which facilitates this
- distinction between a leaf and non-leaf node and any associated
- optimizations.
-
-
-------
-Design
-------
-
-### Describing a power domain tree
-
-To fulfill requirement 1., the existing platform APIs
-`plat_get_aff_count()` and `plat_get_aff_state()` have been
-removed. A platform must define an array of unsigned chars such that:
-
-1. The first entry in the array specifies the number of power domains at the
- highest power level implemented in the platform. This caters for platforms
- where the power domain tree does not have a single root node, for example,
- the FVP has two cluster power domains at the highest level (1).
-
-2. Each subsequent entry corresponds to a power domain and contains the number
- of power domains that are its direct children.
-
-3. The size of the array minus the first entry will be equal to the number of
- non-leaf power domains.
-
-4. The value in each entry in the array is used to find the number of entries
- to consider at the next level. The sum of the values (number of children) of
- all the entries at a level specifies the number of entries in the array for
- the next level.
-
-The following example power domain topology tree will be used to describe the
-above text further. The leaf and non-leaf nodes in this tree have been numbered
-separately.
-
-```
- +-+
- |0|
- +-+
- / \
- / \
- / \
- / \
- / \
- / \
- / \
- / \
- / \
- / \
- +-+ +-+
- |1| |2|
- +-+ +-+
- / \ / \
- / \ / \
- / \ / \
- / \ / \
- +-+ +-+ +-+ +-+
- |3| |4| |5| |6|
- +-+ +-+ +-+ +-+
- +---+-----+ +----+----| +----+----+ +----+-----+-----+
- | | | | | | | | | | | | |
- | | | | | | | | | | | | |
- v v v v v v v v v v v v v
- +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +--+ +--+ +--+
- |0| |1| |2| |3| |4| |5| |6| |7| |8| |9| |10| |11| |12|
- +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +--+ +--+ +--+
-```
-
-
-This tree is defined by the platform as the array described above as follows:
-
-```
- #define PLAT_NUM_POWER_DOMAINS 20
- #define PLATFORM_CORE_COUNT 13
- #define PSCI_NUM_NON_CPU_PWR_DOMAINS \
- (PLAT_NUM_POWER_DOMAINS - PLATFORM_CORE_COUNT)
-
- unsigned char plat_power_domain_tree_desc[] = { 1, 2, 2, 2, 3, 3, 3, 4};
-```
-
-### Removing assumptions about MPIDRs used in a platform
-
-To fulfill requirement 2., it is assumed that the platform assigns a
-unique number (core index) between `0` and `PLAT_CORE_COUNT - 1` to each core
-power domain. MPIDRs could be allocated in any manner and will not be used to
-populate the tree.
-
-`plat_core_pos_by_mpidr(mpidr)` will return the core index for the core
-corresponding to the MPIDR. It will return an error (-1) if an MPIDR is passed
-which is not allocated or corresponds to an absent core. The semantics of this
-platform API have changed since it is required to validate the passed MPIDR. It
-has been made a mandatory API as a result.
-
-Another mandatory API, `plat_my_core_pos()` has been added to return the core
-index for the calling core. This API provides a more lightweight mechanism to get
-the index since there is no need to validate the MPIDR of the calling core.
-
-The platform should assign the core indices (as illustrated in the diagram above)
-such that, if the core nodes are numbered from left to right, then the index
-for a core domain will be the same as the index returned by
- `plat_core_pos_by_mpidr()` or `plat_my_core_pos()` for that core. This
-relationship allows the core nodes to be allocated in a separate array
-(requirement 4.) during `psci_setup()` in such an order that the index of the
-core in the array is the same as the return value from these APIs.
-
-#### Dealing with holes in MPIDR allocation
-
-For platforms where the number of allocated MPIDRs is equal to the number of
-core power domains, for example, Juno and FVPs, the logic to convert an MPIDR to
-a core index should remain unchanged. Both Juno and FVP use a simple collision
-proof hash function to do this.
-
-It is possible that on some platforms, the allocation of MPIDRs is not
-contiguous or certain cores have been disabled. This essentially means that the
-MPIDRs have been sparsely allocated, that is, the size of the range of MPIDRs
-used by the platform is not equal to the number of core power domains.
-
-The platform could adopt one of the following approaches to deal with this
-scenario:
-
-1. Implement more complex logic to convert a valid MPIDR to a core index while
- maintaining the relationship described earlier. This means that the power
- domain tree descriptor will not describe any core power domains which are
- disabled or absent. Entries will not be allocated in the tree for these
- domains.
-
-2. Treat unallocated MPIDRs and disabled cores as absent but still describe them
- in the power domain descriptor, that is, the number of core nodes described
- is equal to the size of the range of MPIDRs allocated. This approach will
- lead to memory wastage since entries will be allocated in the tree but will
- allow use of a simpler logic to convert an MPIDR to a core index.
-
-
-### Traversing through and distinguishing between core and non-core power domains
-
-To fulfill requirement 3 and 4, separate data structures have been defined
-to represent leaf and non-leaf power domain nodes in the tree.
-
-```
-/*******************************************************************************
- * The following two data structures implement the power domain tree. The tree
- * is used to track the state of all the nodes i.e. power domain instances
- * described by the platform. The tree consists of nodes that describe CPU power
- * domains i.e. leaf nodes and all other power domains which are parents of a
- * CPU power domain i.e. non-leaf nodes.
- ******************************************************************************/
-typedef struct non_cpu_pwr_domain_node {
- /*
- * Index of the first CPU power domain node level 0 which has this node
- * as its parent.
- */
- unsigned int cpu_start_idx;
-
- /*
- * Number of CPU power domains which are siblings of the domain indexed
- * by 'cpu_start_idx' i.e. all the domains in the range 'cpu_start_idx
- * -> cpu_start_idx + ncpus' have this node as their parent.
- */
- unsigned int ncpus;
-
- /* Index of the parent power domain node */
- unsigned int parent_node;
-
- -----
-} non_cpu_pd_node_t;
-
-typedef struct cpu_pwr_domain_node {
- u_register_t mpidr;
-
- /* Index of the parent power domain node */
- unsigned int parent_node;
-
- -----
-} cpu_pd_node_t;
-```
-
-The power domain tree is implemented as a combination of the following data
-structures.
-
-```
-non_cpu_pd_node_t psci_non_cpu_pd_nodes[PSCI_NUM_NON_CPU_PWR_DOMAINS];
-cpu_pd_node_t psci_cpu_pd_nodes[PLATFORM_CORE_COUNT];
-```
-
-### Populating the power domain tree
-
-The `populate_power_domain_tree()` function in `psci_setup.c` implements the
-algorithm to parse the power domain descriptor exported by the platform to
-populate the two arrays. It is essentially a breadth-first-search. The nodes for
-each level starting from the root are laid out one after another in the
-`psci_non_cpu_pd_nodes` and `psci_cpu_pd_nodes` arrays as follows:
-
-```
-psci_non_cpu_pd_nodes -> [[Level 3 nodes][Level 2 nodes][Level 1 nodes]]
-psci_cpu_pd_nodes -> [Level 0 nodes]
-```
-
-For the example power domain tree illustrated above, the `psci_cpu_pd_nodes`
-will be populated as follows. The value in each entry is the index of the parent
-node. Other fields have been ignored for simplicity.
-
-```
- +-------------+ ^
- CPU0 | 3 | |
- +-------------+ |
- CPU1 | 3 | |
- +-------------+ |
- CPU2 | 3 | |
- +-------------+ |
- CPU3 | 4 | |
- +-------------+ |
- CPU4 | 4 | |
- +-------------+ |
- CPU5 | 4 | | PLATFORM_CORE_COUNT
- +-------------+ |
- CPU6 | 5 | |
- +-------------+ |
- CPU7 | 5 | |
- +-------------+ |
- CPU8 | 5 | |
- +-------------+ |
- CPU9 | 6 | |
- +-------------+ |
- CPU10 | 6 | |
- +-------------+ |
- CPU11 | 6 | |
- +-------------+ |
- CPU12 | 6 | v
- +-------------+
-```
-
-The `psci_non_cpu_pd_nodes` array will be populated as follows. The value in
-each entry is the index of the parent node.
-
-```
- +-------------+ ^
- PD0 | -1 | |
- +-------------+ |
- PD1 | 0 | |
- +-------------+ |
- PD2 | 0 | |
- +-------------+ |
- PD3 | 1 | | PLAT_NUM_POWER_DOMAINS -
- +-------------+ | PLATFORM_CORE_COUNT
- PD4 | 1 | |
- +-------------+ |
- PD5 | 2 | |
- +-------------+ |
- PD6 | 2 | |
- +-------------+ v
-```
-
-Each core can find its node in the `psci_cpu_pd_nodes` array using the
-`plat_my_core_pos()` function. When a core is turned on, the normal world
-provides an MPIDR. The `plat_core_pos_by_mpidr()` function is used to validate
-the MPIDR before using it to find the corresponding core node. The non-core power
-domain nodes do not need to be identified.
diff --git a/docs/psci-pd-tree.rst b/docs/psci-pd-tree.rst
new file mode 100644
index 0000000..329106c
--- /dev/null
+++ b/docs/psci-pd-tree.rst
@@ -0,0 +1,312 @@
+PSCI Library Integration guide for ARMv8-A AArch32 systems
+==========================================================
+
+
+.. section-numbering::
+ :suffix: .
+
+.. contents::
+
+--------------
+
+Requirements
+------------
+
+#. A platform must export the ``plat_get_aff_count()`` and
+ ``plat_get_aff_state()`` APIs to enable the generic PSCI code to
+ populate a tree that describes the hierarchy of power domains in the
+ system. This approach is inflexible because a change to the topology
+ requires a change in the code.
+
+ It would be much simpler for the platform to describe its power domain tree
+ in a data structure.
+
+#. The generic PSCI code generates MPIDRs in order to populate the power domain
+ tree. It also uses an MPIDR to find a node in the tree. The assumption that
+ a platform will use exactly the same MPIDRs as generated by the generic PSCI
+ code is not scalable. The use of an MPIDR also restricts the number of
+ levels in the power domain tree to four.
+
+ Therefore, there is a need to decouple allocation of MPIDRs from the
+ mechanism used to populate the power domain topology tree.
+
+#. The current arrangement of the power domain tree requires a binary search
+ over the sibling nodes at a particular level to find a specified power
+ domain node. During a power management operation, the tree is traversed from
+ a 'start' to an 'end' power level. The binary search is required to find the
+ node at each level. The natural way to perform this traversal is to
+ start from a leaf node and follow the parent node pointer to reach the end
+ level.
+
+ Therefore, there is a need to define data structures that implement the tree in
+ a way which facilitates such a traversal.
+
+#. The attributes of a core power domain differ from the attributes of power
+ domains at higher levels. For example, only a core power domain can be identified
+ using an MPIDR. There is no requirement to perform state coordination while
+ performing a power management operation on the core power domain.
+
+ Therefore, there is a need to implement the tree in a way which facilitates this
+ distinction between a leaf and non-leaf node and any associated
+ optimizations.
+
+--------------
+
+Design
+------
+
+Describing a power domain tree
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To fulfill requirement 1., the existing platform APIs
+``plat_get_aff_count()`` and ``plat_get_aff_state()`` have been
+removed. A platform must define an array of unsigned chars such that:
+
+#. The first entry in the array specifies the number of power domains at the
+ highest power level implemented in the platform. This caters for platforms
+ where the power domain tree does not have a single root node, for example,
+ the FVP has two cluster power domains at the highest level (1).
+
+#. Each subsequent entry corresponds to a power domain and contains the number
+ of power domains that are its direct children.
+
+#. The size of the array minus the first entry will be equal to the number of
+ non-leaf power domains.
+
+#. The value in each entry in the array is used to find the number of entries
+ to consider at the next level. The sum of the values (number of children) of
+ all the entries at a level specifies the number of entries in the array for
+ the next level.
+
+The following example power domain topology tree will be used to describe the
+above text further. The leaf and non-leaf nodes in this tree have been numbered
+separately.
+
+::
+
+ +-+
+ |0|
+ +-+
+ / \
+ / \
+ / \
+ / \
+ / \
+ / \
+ / \
+ / \
+ / \
+ / \
+ +-+ +-+
+ |1| |2|
+ +-+ +-+
+ / \ / \
+ / \ / \
+ / \ / \
+ / \ / \
+ +-+ +-+ +-+ +-+
+ |3| |4| |5| |6|
+ +-+ +-+ +-+ +-+
+ +---+-----+ +----+----| +----+----+ +----+-----+-----+
+ | | | | | | | | | | | | |
+ | | | | | | | | | | | | |
+ v v v v v v v v v v v v v
+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +--+ +--+ +--+
+ |0| |1| |2| |3| |4| |5| |6| |7| |8| |9| |10| |11| |12|
+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +--+ +--+ +--+
+
+This tree is defined by the platform as the array described above as follows:
+
+::
+
+ #define PLAT_NUM_POWER_DOMAINS 20
+ #define PLATFORM_CORE_COUNT 13
+ #define PSCI_NUM_NON_CPU_PWR_DOMAINS \
+ (PLAT_NUM_POWER_DOMAINS - PLATFORM_CORE_COUNT)
+
+ unsigned char plat_power_domain_tree_desc[] = { 1, 2, 2, 2, 3, 3, 3, 4};
+
+Removing assumptions about MPIDRs used in a platform
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To fulfill requirement 2., it is assumed that the platform assigns a
+unique number (core index) between ``0`` and ``PLAT_CORE_COUNT - 1`` to each core
+power domain. MPIDRs could be allocated in any manner and will not be used to
+populate the tree.
+
+``plat_core_pos_by_mpidr(mpidr)`` will return the core index for the core
+corresponding to the MPIDR. It will return an error (-1) if an MPIDR is passed
+which is not allocated or corresponds to an absent core. The semantics of this
+platform API have changed since it is required to validate the passed MPIDR. It
+has been made a mandatory API as a result.
+
+Another mandatory API, ``plat_my_core_pos()`` has been added to return the core
+index for the calling core. This API provides a more lightweight mechanism to get
+the index since there is no need to validate the MPIDR of the calling core.
+
+The platform should assign the core indices (as illustrated in the diagram above)
+such that, if the core nodes are numbered from left to right, then the index
+for a core domain will be the same as the index returned by
+``plat_core_pos_by_mpidr()`` or ``plat_my_core_pos()`` for that core. This
+relationship allows the core nodes to be allocated in a separate array
+(requirement 4.) during ``psci_setup()`` in such an order that the index of the
+core in the array is the same as the return value from these APIs.
+
+Dealing with holes in MPIDR allocation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For platforms where the number of allocated MPIDRs is equal to the number of
+core power domains, for example, Juno and FVPs, the logic to convert an MPIDR to
+a core index should remain unchanged. Both Juno and FVP use a simple collision
+proof hash function to do this.
+
+It is possible that on some platforms, the allocation of MPIDRs is not
+contiguous or certain cores have been disabled. This essentially means that the
+MPIDRs have been sparsely allocated, that is, the size of the range of MPIDRs
+used by the platform is not equal to the number of core power domains.
+
+The platform could adopt one of the following approaches to deal with this
+scenario:
+
+#. Implement more complex logic to convert a valid MPIDR to a core index while
+ maintaining the relationship described earlier. This means that the power
+ domain tree descriptor will not describe any core power domains which are
+ disabled or absent. Entries will not be allocated in the tree for these
+ domains.
+
+#. Treat unallocated MPIDRs and disabled cores as absent but still describe them
+ in the power domain descriptor, that is, the number of core nodes described
+ is equal to the size of the range of MPIDRs allocated. This approach will
+ lead to memory wastage since entries will be allocated in the tree but will
+ allow use of a simpler logic to convert an MPIDR to a core index.
+
+Traversing through and distinguishing between core and non-core power domains
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To fulfill requirement 3 and 4, separate data structures have been defined
+to represent leaf and non-leaf power domain nodes in the tree.
+
+.. code:: c
+
+ /*******************************************************************************
+ * The following two data structures implement the power domain tree. The tree
+ * is used to track the state of all the nodes i.e. power domain instances
+ * described by the platform. The tree consists of nodes that describe CPU power
+ * domains i.e. leaf nodes and all other power domains which are parents of a
+ * CPU power domain i.e. non-leaf nodes.
+ ******************************************************************************/
+ typedef struct non_cpu_pwr_domain_node {
+ /*
+ * Index of the first CPU power domain node level 0 which has this node
+ * as its parent.
+ */
+ unsigned int cpu_start_idx;
+
+ /*
+ * Number of CPU power domains which are siblings of the domain indexed
+ * by 'cpu_start_idx' i.e. all the domains in the range 'cpu_start_idx
+ * -> cpu_start_idx + ncpus' have this node as their parent.
+ */
+ unsigned int ncpus;
+
+ /* Index of the parent power domain node */
+ unsigned int parent_node;
+
+ -----
+ } non_cpu_pd_node_t;
+
+ typedef struct cpu_pwr_domain_node {
+ u_register_t mpidr;
+
+ /* Index of the parent power domain node */
+ unsigned int parent_node;
+
+ -----
+ } cpu_pd_node_t;
+
+The power domain tree is implemented as a combination of the following data
+structures.
+
+::
+
+ non_cpu_pd_node_t psci_non_cpu_pd_nodes[PSCI_NUM_NON_CPU_PWR_DOMAINS];
+ cpu_pd_node_t psci_cpu_pd_nodes[PLATFORM_CORE_COUNT];
+
+Populating the power domain tree
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``populate_power_domain_tree()`` function in ``psci_setup.c`` implements the
+algorithm to parse the power domain descriptor exported by the platform to
+populate the two arrays. It is essentially a breadth-first-search. The nodes for
+each level starting from the root are laid out one after another in the
+``psci_non_cpu_pd_nodes`` and ``psci_cpu_pd_nodes`` arrays as follows:
+
+::
+
+ psci_non_cpu_pd_nodes -> [[Level 3 nodes][Level 2 nodes][Level 1 nodes]]
+ psci_cpu_pd_nodes -> [Level 0 nodes]
+
+For the example power domain tree illustrated above, the ``psci_cpu_pd_nodes``
+will be populated as follows. The value in each entry is the index of the parent
+node. Other fields have been ignored for simplicity.
+
+::
+
+ +-------------+ ^
+ CPU0 | 3 | |
+ +-------------+ |
+ CPU1 | 3 | |
+ +-------------+ |
+ CPU2 | 3 | |
+ +-------------+ |
+ CPU3 | 4 | |
+ +-------------+ |
+ CPU4 | 4 | |
+ +-------------+ |
+ CPU5 | 4 | | PLATFORM_CORE_COUNT
+ +-------------+ |
+ CPU6 | 5 | |
+ +-------------+ |
+ CPU7 | 5 | |
+ +-------------+ |
+ CPU8 | 5 | |
+ +-------------+ |
+ CPU9 | 6 | |
+ +-------------+ |
+ CPU10 | 6 | |
+ +-------------+ |
+ CPU11 | 6 | |
+ +-------------+ |
+ CPU12 | 6 | v
+ +-------------+
+
+The ``psci_non_cpu_pd_nodes`` array will be populated as follows. The value in
+each entry is the index of the parent node.
+
+::
+
+ +-------------+ ^
+ PD0 | -1 | |
+ +-------------+ |
+ PD1 | 0 | |
+ +-------------+ |
+ PD2 | 0 | |
+ +-------------+ |
+ PD3 | 1 | | PLAT_NUM_POWER_DOMAINS -
+ +-------------+ | PLATFORM_CORE_COUNT
+ PD4 | 1 | |
+ +-------------+ |
+ PD5 | 2 | |
+ +-------------+ |
+ PD6 | 2 | |
+ +-------------+ v
+
+Each core can find its node in the ``psci_cpu_pd_nodes`` array using the
+``plat_my_core_pos()`` function. When a core is turned on, the normal world
+provides an MPIDR. The ``plat_core_pos_by_mpidr()`` function is used to validate
+the MPIDR before using it to find the corresponding core node. The non-core power
+domain nodes do not need to be identified.
+
+--------------
+
+*Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.*
diff --git a/docs/reset-design.md b/docs/reset-design.rst
similarity index 62%
rename from docs/reset-design.md
rename to docs/reset-design.rst
index 3e45d41..0b14dec 100644
--- a/docs/reset-design.md
+++ b/docs/reset-design.rst
@@ -1,34 +1,28 @@
ARM Trusted Firmware Reset Design
=================================
-1. [Introduction](#1--introduction)
-2. [General reset code flow](#2--general-reset-code-flow)
-3. [Programmable CPU reset address](#3--programmable-cpu-reset-address)
-4. [Cold boot on a single CPU](#4--cold-boot-on-a-single-cpu)
-5. [Programmable CPU reset address, Cold boot on a single CPU](#5--programmable-cpu-reset-address-cold-boot-on-a-single-cpu)
-6. [Using BL31 entrypoint as the reset address](#6--using-bl31-entrypoint-as-the-reset-address)
+.. section-numbering::
+ :suffix: .
-1. Introduction
-----------------
+.. contents::
This document describes the high-level design of the framework to handle CPU
resets in ARM Trusted Firmware. It also describes how the platform integrator
can tailor this code to the system configuration to some extent, resulting in a
simplified and more optimised boot flow.
-This document should be used in conjunction with the [Firmware Design], which
+This document should be used in conjunction with the `Firmware Design`_, which
provides greater implementation details around the reset code, specifically
for the cold boot path.
-
-2. General reset code flow
----------------------------
+General reset code flow
+-----------------------
The ARM Trusted Firmware (TF) reset code is implemented in BL1 by default. The
following high-level diagram illustrates this:
-
+|Default reset code flow|
This diagram shows the default, unoptimised reset flow. Depending on the system
configuration, some of these steps might be unnecessary. The following sections
@@ -40,9 +34,8 @@
this case. Please refer to section 6 "Using BL31 entrypoint as the reset
address" for more information.
-
-3. Programmable CPU reset address
-----------------------------------
+Programmable CPU reset address
+------------------------------
By default, the TF assumes that the CPU reset address is not programmable.
Therefore, all CPUs start at the same address (typically address 0) whenever
@@ -50,23 +43,21 @@
warm boot to direct CPUs to the right execution path.
If the reset vector address (reflected in the reset vector base address register
-`RVBAR_EL3`) is programmable then it is possible to make each CPU start directly
+``RVBAR_EL3``) is programmable then it is possible to make each CPU start directly
at the right address, both on a cold and warm reset. Therefore, the boot type
detection can be skipped, resulting in the following boot flow:
-
+|Reset code flow with programmable reset address|
-To enable this boot flow, compile the TF with `PROGRAMMABLE_RESET_ADDRESS=1`.
+To enable this boot flow, compile the TF with ``PROGRAMMABLE_RESET_ADDRESS=1``.
This option only affects the TF reset image, which is BL1 by default or BL31 if
-`RESET_TO_BL31=1`.
+``RESET_TO_BL31=1``.
On both the FVP and Juno platforms, the reset vector address is not programmable
-so both ports use `PROGRAMMABLE_RESET_ADDRESS=0`.
+so both ports use ``PROGRAMMABLE_RESET_ADDRESS=0``.
-
-4. Cold boot on a single CPU
------------------------------
+Cold boot on a single CPU
+-------------------------
By default, the TF assumes that several CPUs may be released out of reset.
Therefore, the cold boot code has to arbitrate access to hardware resources
@@ -78,35 +69,32 @@
no arbitration is required. The notion of primary/secondary CPU itself no longer
applies. This results in the following boot flow:
-
+|Reset code flow with single CPU released out of reset|
-To enable this boot flow, compile the TF with `COLD_BOOT_SINGLE_CPU=1`. This
+To enable this boot flow, compile the TF with ``COLD_BOOT_SINGLE_CPU=1``. This
option only affects the TF reset image, which is BL1 by default or BL31 if
-`RESET_TO_BL31=1`.
+``RESET_TO_BL31=1``.
On both the FVP and Juno platforms, although only one core is powered up by
default, there are platform-specific ways to release any number of cores out of
-reset. Therefore, both platform ports use `COLD_BOOT_SINGLE_CPU=0`.
+reset. Therefore, both platform ports use ``COLD_BOOT_SINGLE_CPU=0``.
-
-5. Programmable CPU reset address, Cold boot on a single CPU
--------------------------------------------------------------
+Programmable CPU reset address, Cold boot on a single CPU
+---------------------------------------------------------
It is obviously possible to combine both optimisations on platforms that have
a programmable CPU reset address and which release a single CPU out of reset.
This results in the following boot flow:
-
-To enable this boot flow, compile the TF with both `COLD_BOOT_SINGLE_CPU=1`
-and `PROGRAMMABLE_RESET_ADDRESS=1`. These options only affect the TF reset
-image, which is BL1 by default or BL31 if `RESET_TO_BL31=1`.
+|Reset code flow with programmable reset address and single CPU released out of reset|
+To enable this boot flow, compile the TF with both ``COLD_BOOT_SINGLE_CPU=1``
+and ``PROGRAMMABLE_RESET_ADDRESS=1``. These options only affect the TF reset
+image, which is BL1 by default or BL31 if ``RESET_TO_BL31=1``.
-6. Using BL31 entrypoint as the reset address
-----------------------------------------------
+Using BL31 entrypoint as the reset address
+------------------------------------------
On some platforms the runtime firmware (BL3x images) for the application
processors are loaded by some firmware running on a secure system processor
@@ -114,11 +102,11 @@
processor. For this type of SoC it is desirable for the application processor
to always reset to BL31 which eliminates the need for BL1 and BL2.
-TF provides a build-time option `RESET_TO_BL31` that includes some additional
+TF provides a build-time option ``RESET_TO_BL31`` that includes some additional
logic in the BL31 entry point to support this use case.
In this configuration, the platform's Trusted Boot Firmware must ensure that
-BL31 is loaded to its runtime address, which must match the CPU's `RVBAR_EL3`
+BL31 is loaded to its runtime address, which must match the CPU's ``RVBAR_EL3``
reset vector base address, before the application processor is powered on.
Additionally, platform software is responsible for loading the other BL3x images
required and providing entry point information for them to BL31. Loading these
@@ -126,24 +114,25 @@
Although the ARM FVP platform does not support programming the reset base
address dynamically at run-time, it is possible to set the initial value of the
-`RVBAR_EL3` register at start-up. This feature is provided on the Base FVP only.
-It allows the ARM FVP port to support the `RESET_TO_BL31` configuration, in
-which case the `bl31.bin` image must be loaded to its run address in Trusted
-SRAM and all CPU reset vectors be changed from the default `0x0` to this run
-address. See the [User Guide] for details of running the FVP models in this way.
+``RVBAR_EL3`` register at start-up. This feature is provided on the Base FVP only.
+It allows the ARM FVP port to support the ``RESET_TO_BL31`` configuration, in
+which case the ``bl31.bin`` image must be loaded to its run address in Trusted
+SRAM and all CPU reset vectors be changed from the default ``0x0`` to this run
+address. See the `User Guide`_ for details of running the FVP models in this way.
Although technically it would be possible to program the reset base address with
the right support in the SCP firmware, this is currently not implemented so the
-Juno port doesn't support the `RESET_TO_BL31` configuration.
+Juno port doesn't support the ``RESET_TO_BL31`` configuration.
-The `RESET_TO_BL31` configuration requires some additions and changes in the
+The ``RESET_TO_BL31`` configuration requires some additions and changes in the
BL31 functionality:
-#### Determination of boot path
+Determination of boot path
+~~~~~~~~~~~~~~~~~~~~~~~~~~
In this configuration, BL31 uses the same reset framework and code as the one
described for BL1 above. Therefore, it is affected by the
-`PROGRAMMABLE_RESET_ADDRESS` and `COLD_BOOT_SINGLE_CPU` build options in the
+``PROGRAMMABLE_RESET_ADDRESS`` and ``COLD_BOOT_SINGLE_CPU`` build options in the
same way.
In the default, unoptimised BL31 reset flow, on a warm boot a CPU is directed
@@ -151,22 +140,27 @@
the platform must place any secondary CPUs into a safe state while the primary
CPU executes a modified BL31 initialization, as described below.
-#### Platform initialization
+Platform initialization
+~~~~~~~~~~~~~~~~~~~~~~~
In this configuration, when the CPU resets to BL31 there are no parameters that
can be passed in registers by previous boot stages. Instead, the platform code
in BL31 needs to know, or be able to determine, the location of the BL32 (if
required) and BL33 images and provide this information in response to the
-`bl31_plat_get_next_image_ep_info()` function.
+``bl31_plat_get_next_image_ep_info()`` function.
Additionally, platform software is responsible for carrying out any security
initialisation, for example programming a TrustZone address space controller.
This might be done by the Trusted Boot Firmware or by platform code in BL31.
-- - - - - - - - - - - - - - - - - - - - - - - - - -
+--------------
-_Copyright (c) 2015, ARM Limited and Contributors. All rights reserved._
+*Copyright (c) 2015, ARM Limited and Contributors. All rights reserved.*
+.. _Firmware Design: firmware-design.rst
+.. _User Guide: user-guide.rst
-[User Guide]: user-guide.md
-[Firmware Design]: firmware-design.md
+.. |Default reset code flow| image:: diagrams/default_reset_code.png?raw=true
+.. |Reset code flow with programmable reset address| image:: diagrams/reset_code_no_boot_type_check.png?raw=true
+.. |Reset code flow with single CPU released out of reset| image:: diagrams/reset_code_no_cpu_check.png?raw=true
+.. |Reset code flow with programmable reset address and single CPU released out of reset| image:: diagrams/reset_code_no_checks.png?raw=true
diff --git a/docs/rt-svc-writers-guide.md b/docs/rt-svc-writers-guide.md
deleted file mode 100644
index ea599ed..0000000
--- a/docs/rt-svc-writers-guide.md
+++ /dev/null
@@ -1,307 +0,0 @@
-EL3 Runtime Service Writers Guide for ARM Trusted Firmware
-==========================================================
-
-Contents
---------
-
-1. [Introduction](#1--introduction)
-2. [Owning Entities, Call Types and Function IDs](#2--owning-entities-call-types-and-function-ids)
-3. [Getting started](#3--getting-started)
-4. [Registering a runtime service](#4--registering-a-runtime-service)
-5. [Initializing a runtime service](#5-initializing-a-runtime-service)
-6. [Handling runtime service requests](#6--handling-runtime-service-requests)
-7. [Services that contain multiple sub-services](#7--services-that-contain-multiple-sub-services)
-8. [Secure-EL1 Payload Dispatcher service (SPD)](#8--secure-el1-payload-dispatcher-service-spd)
-
-- - - - - - - - - - - - - - - - - -
-
-1. Introduction
-----------------
-
-This document describes how to add a runtime service to the EL3 Runtime
-Firmware component of ARM Trusted Firmware (BL31).
-
-Software executing in the normal world and in the trusted world at exception
-levels lower than EL3 will request runtime services using the Secure Monitor
-Call (SMC) instruction. These requests will follow the convention described in
-the SMC Calling Convention PDD ([SMCCC]). The [SMCCC] assigns function
-identifiers to each SMC request and describes how arguments are passed and
-results are returned.
-
-SMC Functions are grouped together based on the implementor of the service, for
-example a subset of the Function IDs are designated as "OEM Calls" (see [SMCCC]
-for full details). The EL3 runtime services framework in BL31 enables the
-independent implementation of services for each group, which are then compiled
-into the BL31 image. This simplifies the integration of common software from
-ARM to support [PSCI], Secure Monitor for a Trusted OS and SoC specific
-software. The common runtime services framework ensures that SMC Functions are
-dispatched to their respective service implementation - the [Firmware Design]
-provides details of how this is achieved.
-
-The interface and operation of the runtime services depends heavily on the
-concepts and definitions described in the [SMCCC], in particular SMC Function
-IDs, Owning Entity Numbers (OEN), Fast and Standard calls, and the SMC32 and
-SMC64 calling conventions. Please refer to that document for a full explanation
-of these terms.
-
-
-2. Owning Entities, Call Types and Function IDs
-------------------------------------------------
-
-The SMC Function Identifier includes a OEN field. These values and their
-meaning are described in [SMCCC] and summarized in table 1 below. Some entities
-are allocated a range of of OENs. The OEN must be interpreted in conjunction
-with the SMC call type, which is either _Fast_ or _Yielding_. Fast calls are
-uninterruptible whereas Yielding calls can be pre-empted. The majority of
-Owning Entities only have allocated ranges for Fast calls: Yielding calls are
-reserved exclusively for Trusted OS providers or for interoperability with
-legacy 32-bit software that predates the [SMCCC].
-
- Type OEN Service
- Fast 0 ARM Architecture calls
- Fast 1 CPU Service calls
- Fast 2 SiP Service calls
- Fast 3 OEM Service calls
- Fast 4 Standard Service calls
- Fast 5-47 Reserved for future use
- Fast 48-49 Trusted Application calls
- Fast 50-63 Trusted OS calls
-
- Yielding 0- 1 Reserved for existing ARMv7 calls
- Yielding 2-63 Trusted OS Standard Calls
-
-_Table 1: Service types and their corresponding Owning Entity Numbers_
-
-Each individual entity can allocate the valid identifiers within the entity
-range as they need - it is not necessary to coordinate with other entities of
-the same type. For example, two SoC providers can use the same Function ID
-within the SiP Service calls OEN range to mean different things - as these
-calls should be specific to the SoC. The Standard Runtime Calls OEN is used for
-services defined by ARM standards, such as [PSCI].
-
-The SMC Function ID also indicates whether the call has followed the SMC32
-calling convention, where all parameters are 32-bit, or the SMC64 calling
-convention, where the parameters are 64-bit. The framework identifies and
-rejects invalid calls that use the SMC64 calling convention but that originate
-from an AArch32 caller.
-
-The EL3 runtime services framework uses the call type and OEN to identify a
-specific handler for each SMC call, but it is expected that an individual
-handler will be responsible for all SMC Functions within a given service type.
-
-
-3. Getting started
--------------------
-
-ARM Trusted Firmware has a [`services`] directory in the source tree under which
-each owning entity can place the implementation of its runtime service. The
-[PSCI] implementation is located here in the [`lib/psci`] directory.
-
-Runtime service sources will need to include the [`runtime_svc.h`] header file.
-
-
-4. Registering a runtime service
----------------------------------
-
-A runtime service is registered using the `DECLARE_RT_SVC()` macro, specifying
-the name of the service, the range of OENs covered, the type of service and
-initialization and call handler functions.
-
- #define DECLARE_RT_SVC(_name, _start, _end, _type, _setup, _smch)
-
-* `_name` is used to identify the data structure declared by this macro, and
- is also used for diagnostic purposes
-
-* `_start` and `_end` values must be based on the `OEN_*` values defined in
- [`smcc.h`]
-
-* `_type` must be one of `SMC_TYPE_FAST` or `SMC_TYPE_YIELD`
-
-* `_setup` is the initialization function with the `rt_svc_init` signature:
-
- typedef int32_t (*rt_svc_init)(void);
-
-* `_smch` is the SMC handler function with the `rt_svc_handle` signature:
-
- typedef uintptr_t (*rt_svc_handle_t)(uint32_t smc_fid,
- u_register_t x1, u_register_t x2,
- u_register_t x3, u_register_t x4,
- void *cookie,
- void *handle,
- u_register_t flags);
-
-Details of the requirements and behavior of the two callbacks is provided in
-the following sections.
-
-During initialization the services framework validates each declared service
-to ensure that the following conditions are met:
-
-1. The `_start` OEN is not greater than the `_end` OEN
-2. The `_end` OEN does not exceed the maximum OEN value (63)
-3. The `_type` is one of `SMC_TYPE_FAST` or `SMC_TYPE_YIELD`
-4. `_setup` and `_smch` routines have been specified
-
-[`std_svc_setup.c`] provides an example of registering a runtime service:
-
- /* Register Standard Service Calls as runtime service */
- DECLARE_RT_SVC(
- std_svc,
- OEN_STD_START,
- OEN_STD_END,
- SMC_TYPE_FAST,
- std_svc_setup,
- std_svc_smc_handler
- );
-
-
-5. Initializing a runtime service
----------------------------------
-
-Runtime services are initialized once, during cold boot, by the primary CPU
-after platform and architectural initialization is complete. The framework
-performs basic validation of the declared service before calling
-the service initialization function (`_setup` in the declaration). This
-function must carry out any essential EL3 initialization prior to receiving a
-SMC Function call via the handler function.
-
-On success, the initialization function must return `0`. Any other return value
-will cause the framework to issue a diagnostic:
-
- Error initializing runtime service <name of the service>
-
-and then ignore the service - the system will continue to boot but SMC calls
-will not be passed to the service handler and instead return the _Unknown SMC
-Function ID_ result `0xFFFFFFFF`.
-
-If the system must not be allowed to proceed without the service, the
-initialization function must itself cause the firmware boot to be halted.
-
-If the service uses per-CPU data this must either be initialized for all CPUs
-during this call, or be done lazily when a CPU first issues an SMC call to that
-service.
-
-
-6. Handling runtime service requests
--------------------------------------
-
-SMC calls for a service are forwarded by the framework to the service's SMC
-handler function (`_smch` in the service declaration). This function must have
-the following signature:
-
- typedef uintptr_t (*rt_svc_handle_t)(uint32_t smc_fid,
- u_register_t x1, u_register_t x2,
- u_register_t x3, u_register_t x4,
- void *cookie,
- void *handle,
- u_register_t flags);
-
-The handler is responsible for:
-
-1. Determining that `smc_fid` is a valid and supported SMC Function ID,
- otherwise completing the request with the _Unknown SMC Function ID_:
-
- SMC_RET1(handle, SMC_UNK);
-
-2. Determining if the requested function is valid for the calling security
- state. SMC Calls can be made from both the normal and trusted worlds and
- the framework will forward all calls to the service handler.
-
- The `flags` parameter to this function indicates the caller security state
- in bit[0], where a value of `1` indicates a non-secure caller. The
- `is_caller_secure(flags)` and `is_caller_non_secure(flags)` can be used to
- test this condition.
-
- If invalid, the request should be completed with:
-
- SMC_RET1(handle, SMC_UNK);
-
-3. Truncating parameters for calls made using the SMC32 calling convention.
- Such calls can be determined by checking the CC field in bit[30] of the
- `smc_fid` parameter, for example by using:
-
- if (GET_SMC_CC(smc_fid) == SMC_32) ...
-
- For such calls, the upper bits of the parameters x1-x4 and the saved
- parameters X5-X7 are UNDEFINED and must be explicitly ignored by the
- handler. This can be done by truncating the values to a suitable 32-bit
- integer type before use, for example by ensuring that functions defined
- to handle individual SMC Functions use appropriate 32-bit parameters.
-
-4. Providing the service requested by the SMC Function, utilizing the
- immediate parameters x1-x4 and/or the additional saved parameters X5-X7.
- The latter can be retrieved using the `SMC_GET_GP(handle, ref)` function,
- supplying the appropriate `CTX_GPREG_Xn` reference, e.g.
-
- uint64_t x6 = SMC_GET_GP(handle, CTX_GPREG_X6);
-
-5. Implementing the standard SMC32 Functions that provide information about
- the implementation of the service. These are the Call Count, Implementor
- UID and Revision Details for each service documented in section 6 of the
- [SMCCC].
-
- The ARM Trusted Firmware expects owning entities to follow this
- recommendation.
-
-5. Returning the result to the caller. The [SMCCC] allows for up to 256 bits
- of return value in SMC64 using X0-X3 and 128 bits in SMC32 using W0-W3. The
- framework provides a family of macros to set the multi-register return
- value and complete the handler:
-
- SMC_RET1(handle, x0);
- SMC_RET2(handle, x0, x1);
- SMC_RET3(handle, x0, x1, x2);
- SMC_RET4(handle, x0, x1, x2, x3);
-
-The `cookie` parameter to the handler is reserved for future use and can be
-ignored. The `handle` is returned by the SMC handler - completion of the
-handler function must always be via one of the `SMC_RETn()` macros.
-
-NOTE: The PSCI and Test Secure-EL1 Payload Dispatcher services do not follow
-all of the above requirements yet.
-
-
-7. Services that contain multiple sub-services
------------------------------------------------
-
-It is possible that a single owning entity implements multiple sub-services. For
-example, the Standard calls service handles `0x84000000`-`0x8400FFFF` and
-`0xC4000000`-`0xC400FFFF` functions. Within that range, the [PSCI] service
-handles the `0x84000000`-`0x8400001F` and `0xC4000000`-`0xC400001F` functions.
-In that respect, [PSCI] is a 'sub-service' of the Standard calls service. In
-future, there could be additional such sub-services in the Standard calls
-service which perform independent functions.
-
-In this situation it may be valuable to introduce a second level framework to
-enable independent implementation of sub-services. Such a framework might look
-very similar to the current runtime services framework, but using a different
-part of the SMC Function ID to identify the sub-service. Trusted Firmware does
-not provide such a framework at present.
-
-
-8. Secure-EL1 Payload Dispatcher service (SPD)
------------------------------------------------
-
-Services that handle SMC Functions targeting a Trusted OS, Trusted Application,
-or other Secure-EL1 Payload are special. These services need to manage the
-Secure-EL1 context, provide the _Secure Monitor_ functionality of switching
-between the normal and secure worlds, deliver SMC Calls through to Secure-EL1
-and generally manage the Secure-EL1 Payload through CPU power-state transitions.
-
-TODO: Provide details of the additional work required to implement a SPD and
-the BL31 support for these services. Or a reference to the document that will
-provide this information....
-
-
-- - - - - - - - - - - - - - - - - - - - - - - - - -
-
-_Copyright (c) 2014-2015, ARM Limited and Contributors. All rights reserved._
-
-
-[Firmware Design]: ./firmware-design.md
-[`services`]: ../services
-[`lib/psci`]: ../lib/psci
-[`std_svc_setup.c`]: ../services/std_svc/std_svc_setup.c
-[`runtime_svc.h`]: ../include/common/runtime_svc.h
-[`smcc.h`]: ../include/lib/smcc.h
-[PSCI]: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf "Power State Coordination Interface PDD (ARM DEN 0022C)"
-[SMCCC]: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html "SMC Calling Convention PDD (ARM DEN 0028A)"
diff --git a/docs/rt-svc-writers-guide.rst b/docs/rt-svc-writers-guide.rst
new file mode 100644
index 0000000..6a64ade
--- /dev/null
+++ b/docs/rt-svc-writers-guide.rst
@@ -0,0 +1,316 @@
+EL3 Runtime Service Writers Guide for ARM Trusted Firmware
+==========================================================
+
+
+.. section-numbering::
+ :suffix: .
+
+.. contents::
+
+--------------
+
+Introduction
+------------
+
+This document describes how to add a runtime service to the EL3 Runtime
+Firmware component of ARM Trusted Firmware (BL31).
+
+Software executing in the normal world and in the trusted world at exception
+levels lower than EL3 will request runtime services using the Secure Monitor
+Call (SMC) instruction. These requests will follow the convention described in
+the SMC Calling Convention PDD (`SMCCC`_). The `SMCCC`_ assigns function
+identifiers to each SMC request and describes how arguments are passed and
+results are returned.
+
+SMC Functions are grouped together based on the implementor of the service, for
+example a subset of the Function IDs are designated as "OEM Calls" (see `SMCCC`_
+for full details). The EL3 runtime services framework in BL31 enables the
+independent implementation of services for each group, which are then compiled
+into the BL31 image. This simplifies the integration of common software from
+ARM to support `PSCI`_, Secure Monitor for a Trusted OS and SoC specific
+software. The common runtime services framework ensures that SMC Functions are
+dispatched to their respective service implementation - the `Firmware Design`_
+provides details of how this is achieved.
+
+The interface and operation of the runtime services depends heavily on the
+concepts and definitions described in the `SMCCC`_, in particular SMC Function
+IDs, Owning Entity Numbers (OEN), Fast and Standard calls, and the SMC32 and
+SMC64 calling conventions. Please refer to that document for a full explanation
+of these terms.
+
+Owning Entities, Call Types and Function IDs
+--------------------------------------------
+
+The SMC Function Identifier includes a OEN field. These values and their
+meaning are described in `SMCCC`_ and summarized in table 1 below. Some entities
+are allocated a range of of OENs. The OEN must be interpreted in conjunction
+with the SMC call type, which is either *Fast* or *Yielding*. Fast calls are
+uninterruptible whereas Yielding calls can be pre-empted. The majority of
+Owning Entities only have allocated ranges for Fast calls: Yielding calls are
+reserved exclusively for Trusted OS providers or for interoperability with
+legacy 32-bit software that predates the `SMCCC`_.
+
+::
+
+ Type OEN Service
+ Fast 0 ARM Architecture calls
+ Fast 1 CPU Service calls
+ Fast 2 SiP Service calls
+ Fast 3 OEM Service calls
+ Fast 4 Standard Service calls
+ Fast 5-47 Reserved for future use
+ Fast 48-49 Trusted Application calls
+ Fast 50-63 Trusted OS calls
+
+ Yielding 0- 1 Reserved for existing ARMv7 calls
+ Yielding 2-63 Trusted OS Standard Calls
+
+*Table 1: Service types and their corresponding Owning Entity Numbers*
+
+Each individual entity can allocate the valid identifiers within the entity
+range as they need - it is not necessary to coordinate with other entities of
+the same type. For example, two SoC providers can use the same Function ID
+within the SiP Service calls OEN range to mean different things - as these
+calls should be specific to the SoC. The Standard Runtime Calls OEN is used for
+services defined by ARM standards, such as `PSCI`_.
+
+The SMC Function ID also indicates whether the call has followed the SMC32
+calling convention, where all parameters are 32-bit, or the SMC64 calling
+convention, where the parameters are 64-bit. The framework identifies and
+rejects invalid calls that use the SMC64 calling convention but that originate
+from an AArch32 caller.
+
+The EL3 runtime services framework uses the call type and OEN to identify a
+specific handler for each SMC call, but it is expected that an individual
+handler will be responsible for all SMC Functions within a given service type.
+
+Getting started
+---------------
+
+ARM Trusted Firmware has a `services`_ directory in the source tree under which
+each owning entity can place the implementation of its runtime service. The
+`PSCI`_ implementation is located here in the `lib/psci`_ directory.
+
+Runtime service sources will need to include the `runtime\_svc.h`_ header file.
+
+Registering a runtime service
+-----------------------------
+
+A runtime service is registered using the ``DECLARE_RT_SVC()`` macro, specifying
+the name of the service, the range of OENs covered, the type of service and
+initialization and call handler functions.
+
+::
+
+ #define DECLARE_RT_SVC(_name, _start, _end, _type, _setup, _smch)
+
+- ``_name`` is used to identify the data structure declared by this macro, and
+ is also used for diagnostic purposes
+
+- ``_start`` and ``_end`` values must be based on the ``OEN_*`` values defined in
+ `smcc.h`_
+
+- ``_type`` must be one of ``SMC_TYPE_FAST`` or ``SMC_TYPE_YIELD``
+
+- ``_setup`` is the initialization function with the ``rt_svc_init`` signature:
+
+ .. code:: c
+
+ typedef int32_t (*rt_svc_init)(void);
+
+- ``_smch`` is the SMC handler function with the ``rt_svc_handle`` signature:
+
+ .. code:: c
+
+ typedef uintptr_t (*rt_svc_handle_t)(uint32_t smc_fid,
+ u_register_t x1, u_register_t x2,
+ u_register_t x3, u_register_t x4,
+ void *cookie,
+ void *handle,
+ u_register_t flags);
+
+Details of the requirements and behavior of the two callbacks is provided in
+the following sections.
+
+During initialization the services framework validates each declared service
+to ensure that the following conditions are met:
+
+#. The ``_start`` OEN is not greater than the ``_end`` OEN
+#. The ``_end`` OEN does not exceed the maximum OEN value (63)
+#. The ``_type`` is one of ``SMC_TYPE_FAST`` or ``SMC_TYPE_YIELD``
+#. ``_setup`` and ``_smch`` routines have been specified
+
+`std\_svc\_setup.c`_ provides an example of registering a runtime service:
+
+.. code:: c
+
+ /* Register Standard Service Calls as runtime service */
+ DECLARE_RT_SVC(
+ std_svc,
+ OEN_STD_START,
+ OEN_STD_END,
+ SMC_TYPE_FAST,
+ std_svc_setup,
+ std_svc_smc_handler
+ );
+
+Initializing a runtime service
+------------------------------
+
+Runtime services are initialized once, during cold boot, by the primary CPU
+after platform and architectural initialization is complete. The framework
+performs basic validation of the declared service before calling
+the service initialization function (``_setup`` in the declaration). This
+function must carry out any essential EL3 initialization prior to receiving a
+SMC Function call via the handler function.
+
+On success, the initialization function must return ``0``. Any other return value
+will cause the framework to issue a diagnostic:
+
+::
+
+ Error initializing runtime service <name of the service>
+
+and then ignore the service - the system will continue to boot but SMC calls
+will not be passed to the service handler and instead return the *Unknown SMC
+Function ID* result ``0xFFFFFFFF``.
+
+If the system must not be allowed to proceed without the service, the
+initialization function must itself cause the firmware boot to be halted.
+
+If the service uses per-CPU data this must either be initialized for all CPUs
+during this call, or be done lazily when a CPU first issues an SMC call to that
+service.
+
+Handling runtime service requests
+---------------------------------
+
+SMC calls for a service are forwarded by the framework to the service's SMC
+handler function (``_smch`` in the service declaration). This function must have
+the following signature:
+
+.. code:: c
+
+ typedef uintptr_t (*rt_svc_handle_t)(uint32_t smc_fid,
+ u_register_t x1, u_register_t x2,
+ u_register_t x3, u_register_t x4,
+ void *cookie,
+ void *handle,
+ u_register_t flags);
+
+The handler is responsible for:
+
+#. Determining that ``smc_fid`` is a valid and supported SMC Function ID,
+ otherwise completing the request with the *Unknown SMC Function ID*:
+
+ .. code:: c
+
+ SMC_RET1(handle, SMC_UNK);
+
+#. Determining if the requested function is valid for the calling security
+ state. SMC Calls can be made from both the normal and trusted worlds and
+ the framework will forward all calls to the service handler.
+
+ The ``flags`` parameter to this function indicates the caller security state
+ in bit[0], where a value of ``1`` indicates a non-secure caller. The
+ ``is_caller_secure(flags)`` and ``is_caller_non_secure(flags)`` can be used to
+ test this condition.
+
+ If invalid, the request should be completed with:
+
+ .. code:: c
+
+ SMC_RET1(handle, SMC_UNK);
+
+#. Truncating parameters for calls made using the SMC32 calling convention.
+ Such calls can be determined by checking the CC field in bit[30] of the
+ ``smc_fid`` parameter, for example by using:
+
+ ::
+
+ if (GET_SMC_CC(smc_fid) == SMC_32) ...
+
+ For such calls, the upper bits of the parameters x1-x4 and the saved
+ parameters X5-X7 are UNDEFINED and must be explicitly ignored by the
+ handler. This can be done by truncating the values to a suitable 32-bit
+ integer type before use, for example by ensuring that functions defined
+ to handle individual SMC Functions use appropriate 32-bit parameters.
+
+#. Providing the service requested by the SMC Function, utilizing the
+ immediate parameters x1-x4 and/or the additional saved parameters X5-X7.
+ The latter can be retrieved using the ``SMC_GET_GP(handle, ref)`` function,
+ supplying the appropriate ``CTX_GPREG_Xn`` reference, e.g.
+
+ .. code:: c
+
+ uint64_t x6 = SMC_GET_GP(handle, CTX_GPREG_X6);
+
+#. Implementing the standard SMC32 Functions that provide information about
+ the implementation of the service. These are the Call Count, Implementor
+ UID and Revision Details for each service documented in section 6 of the
+ `SMCCC`_.
+
+ The ARM Trusted Firmware expects owning entities to follow this
+ recommendation.
+
+#. Returning the result to the caller. The `SMCCC`_ allows for up to 256 bits
+ of return value in SMC64 using X0-X3 and 128 bits in SMC32 using W0-W3. The
+ framework provides a family of macros to set the multi-register return
+ value and complete the handler:
+
+ .. code:: c
+
+ SMC_RET1(handle, x0);
+ SMC_RET2(handle, x0, x1);
+ SMC_RET3(handle, x0, x1, x2);
+ SMC_RET4(handle, x0, x1, x2, x3);
+
+The ``cookie`` parameter to the handler is reserved for future use and can be
+ignored. The ``handle`` is returned by the SMC handler - completion of the
+handler function must always be via one of the ``SMC_RETn()`` macros.
+
+NOTE: The PSCI and Test Secure-EL1 Payload Dispatcher services do not follow
+all of the above requirements yet.
+
+Services that contain multiple sub-services
+-------------------------------------------
+
+It is possible that a single owning entity implements multiple sub-services. For
+example, the Standard calls service handles ``0x84000000``-``0x8400FFFF`` and
+``0xC4000000``-``0xC400FFFF`` functions. Within that range, the `PSCI`_ service
+handles the ``0x84000000``-``0x8400001F`` and ``0xC4000000``-``0xC400001F`` functions.
+In that respect, `PSCI`_ is a 'sub-service' of the Standard calls service. In
+future, there could be additional such sub-services in the Standard calls
+service which perform independent functions.
+
+In this situation it may be valuable to introduce a second level framework to
+enable independent implementation of sub-services. Such a framework might look
+very similar to the current runtime services framework, but using a different
+part of the SMC Function ID to identify the sub-service. Trusted Firmware does
+not provide such a framework at present.
+
+Secure-EL1 Payload Dispatcher service (SPD)
+-------------------------------------------
+
+Services that handle SMC Functions targeting a Trusted OS, Trusted Application,
+or other Secure-EL1 Payload are special. These services need to manage the
+Secure-EL1 context, provide the *Secure Monitor* functionality of switching
+between the normal and secure worlds, deliver SMC Calls through to Secure-EL1
+and generally manage the Secure-EL1 Payload through CPU power-state transitions.
+
+TODO: Provide details of the additional work required to implement a SPD and
+the BL31 support for these services. Or a reference to the document that will
+provide this information....
+
+--------------
+
+*Copyright (c) 2014-2015, ARM Limited and Contributors. All rights reserved.*
+
+.. _SMCCC: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
+.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
+.. _Firmware Design: ./firmware-design.rst
+.. _services: ../services
+.. _lib/psci: ../lib/psci
+.. _runtime\_svc.h: ../include/common/runtime_svc.h
+.. _smcc.h: ../include/lib/smcc.h
+.. _std\_svc\_setup.c: ../services/std_svc/std_svc_setup.c
diff --git a/docs/spd/optee-dispatcher.md b/docs/spd/optee-dispatcher.md
deleted file mode 100644
index c154f6b..0000000
--- a/docs/spd/optee-dispatcher.md
+++ /dev/null
@@ -1,13 +0,0 @@
-OP-TEE Dispatcher
-=================
-
-[OP-TEE OS] is a Trusted OS running as Secure EL1.
-
-To build and execute [OP-TEE OS] follow the instructions at
-[ARM Trusted Firmware with OP-TEE] [OP-TEE OS]
-
-- - - - - - - - - - - - - - - - - - - - - - - - - -
-
-_Copyright (c) 2014, ARM Limited and Contributors. All rights reserved._
-
-[OP-TEE OS]: http://github.com/OP-TEE/optee_os/tree/master/documentation/arm_trusted_firmware.md
diff --git a/docs/spd/optee-dispatcher.rst b/docs/spd/optee-dispatcher.rst
new file mode 100644
index 0000000..e55926b
--- /dev/null
+++ b/docs/spd/optee-dispatcher.rst
@@ -0,0 +1,14 @@
+OP-TEE Dispatcher
+=================
+
+`OP-TEE OS`_ is a Trusted OS running as Secure EL1.
+
+To build and execute OP-TEE follow the instructions at
+`OP-TEE build.git`_
+
+--------------
+
+*Copyright (c) 2014-2017, ARM Limited and Contributors. All rights reserved.*
+
+.. _OP-TEE OS: https://github.com/OP-TEE/build
+.. _OP-TEE build.git: https://github.com/OP-TEE/build
diff --git a/docs/spd/tlk-dispatcher.md b/docs/spd/tlk-dispatcher.rst
similarity index 84%
rename from docs/spd/tlk-dispatcher.md
rename to docs/spd/tlk-dispatcher.rst
index 40c8344..cd37652 100644
--- a/docs/spd/tlk-dispatcher.md
+++ b/docs/spd/tlk-dispatcher.rst
@@ -1,5 +1,6 @@
Trusted Little Kernel (TLK) Dispatcher
-=======================================
+======================================
+
TLK dispatcher adds support for NVIDIA's Trusted Little Kernel (TLK) to work
with the Trusted Firmware. TLK-D can be compiled by including it in the
platform's makefile. TLK is primarily meant to work with Tegra SoCs, so until
@@ -15,6 +16,7 @@
Trusted Little Kernel (TLK)
===========================
+
TLK is a Trusted OS running as Secure EL1. It is a Free Open Source Software
(FOSS) release of the NVIDIA® Trusted Little Kernel (TLK) technology, which
extends technology made available with the development of the Little Kernel (LK).
@@ -47,24 +49,28 @@
• Debugging support over UART (USB planned)
TLK is hosted by NVIDIA on http://nv-tegra.nvidia.com under the
-3rdparty/ote_partner/tlk.git repository. Detailed information about
-TLK and OTE can be found in the Tegra_BSP_for_Android_TLK_FOSS_Reference.pdf
-manual located under the "documentation" directory_.
+3rdparty/ote\_partner/tlk.git repository. Detailed information about
+TLK and OTE can be found in the Tegra\_BSP\_for\_Android\_TLK\_FOSS\_Reference.pdf
+manual located under the "documentation" directory\_.
Build TLK
=========
+
To build and execute TLK, follow the instructions from "Building a TLK Device"
-section from Tegra_BSP_for_Android_TLK_FOSS_Reference.pdf manual.
+section from Tegra\_BSP\_for\_Android\_TLK\_FOSS\_Reference.pdf manual.
Input parameters to TLK
=======================
+
TLK expects the TZDRAM size and a structure containing the boot arguments. BL2
-passes this information to the EL3 software as members of the bl32_ep_info
-struct, where bl32_ep_info is part of bl31_params_t (passed by BL2 in X0)
+passes this information to the EL3 software as members of the bl32\_ep\_info
+struct, where bl32\_ep\_info is part of bl31\_params\_t (passed by BL2 in X0)
Example:
--------
+
+::
+
bl32_ep_info->args.arg0 = TZDRAM size available for BL32
bl32_ep_info->args.arg1 = unused (used only on ARMv7)
bl32_ep_info->args.arg2 = pointer to boot args
-
diff --git a/docs/spd/trusty-dispatcher.md b/docs/spd/trusty-dispatcher.rst
similarity index 99%
rename from docs/spd/trusty-dispatcher.md
rename to docs/spd/trusty-dispatcher.rst
index 0258959..f1982ea 100644
--- a/docs/spd/trusty-dispatcher.md
+++ b/docs/spd/trusty-dispatcher.rst
@@ -1,5 +1,6 @@
Trusty Dispatcher
=================
+
Trusty is a a set of software components, supporting a Trusted Execution
Environment (TEE) on mobile devices, published and maintained by Google.
@@ -9,7 +10,6 @@
Supported platforms
===================
+
Out of all the platforms supported by the ARM Trusted Firmware, Trusty is
verified and supported by NVIDIA's Tegra SoCs.
-
-
diff --git a/docs/trusted-board-boot.md b/docs/trusted-board-boot.md
deleted file mode 100644
index 833b5db..0000000
--- a/docs/trusted-board-boot.md
+++ /dev/null
@@ -1,251 +0,0 @@
-Trusted Board Boot Design Guide
-===============================
-
-Contents :
-
-1. [Introduction](#1--introduction)
-2. [Chain of Trust](#2--chain-of-trust)
-3. [Trusted Board Boot Sequence](#3--trusted-board-boot-sequence)
-4. [Authentication Framework](#4--authentication-framework)
-5. [Certificate Generation Tool](#5--certificate-generation-tool)
-
-
-1. Introduction
-----------------
-
-The Trusted Board Boot (TBB) feature prevents malicious firmware from running on
-the platform by authenticating all firmware images up to and including the
-normal world bootloader. It does this by establishing a Chain of Trust using
-Public-Key-Cryptography Standards (PKCS).
-
-This document describes the design of ARM Trusted Firmware TBB, which is an
-implementation of the Trusted Board Boot Requirements (TBBR) specification,
-ARM DEN0006C-1. It should be used in conjunction with the [Firmware Update]
-design document, which implements a specific aspect of the TBBR.
-
-
-2. Chain of Trust
-------------------
-
-A Chain of Trust (CoT) starts with a set of implicitly trusted components. On
-the ARM development platforms, these components are:
-
-* A SHA-256 hash of the Root of Trust Public Key (ROTPK). It is stored in the
- trusted root-key storage registers.
-
-* The BL1 image, on the assumption that it resides in ROM so cannot be
- tampered with.
-
-The remaining components in the CoT are either certificates or boot loader
-images. The certificates follow the [X.509 v3] standard. This standard
-enables adding custom extensions to the certificates, which are used to store
-essential information to establish the CoT.
-
-In the TBB CoT all certificates are self-signed. There is no need for a
-Certificate Authority (CA) because the CoT is not established by verifying the
-validity of a certificate's issuer but by the content of the certificate
-extensions. To sign the certificates, the PKCS#1 SHA-256 with RSA Encryption
-signature scheme is used with a RSA key length of 2048 bits. Future version of
-Trusted Firmware will support additional cryptographic algorithms.
-
-The certificates are categorised as "Key" and "Content" certificates. Key
-certificates are used to verify public keys which have been used to sign content
-certificates. Content certificates are used to store the hash of a boot loader
-image. An image can be authenticated by calculating its hash and matching it
-with the hash extracted from the content certificate. The SHA-256 function is
-used to calculate all hashes. The public keys and hashes are included as
-non-standard extension fields in the [X.509 v3] certificates.
-
-The keys used to establish the CoT are:
-
-* **Root of trust key**
-
- The private part of this key is used to sign the BL2 content certificate and
- the trusted key certificate. The public part is the ROTPK.
-
-* **Trusted world key**
-
- The private part is used to sign the key certificates corresponding to the
- secure world images (SCP_BL2, BL31 and BL32). The public part is stored in
- one of the extension fields in the trusted world certificate.
-
-* **Non-trusted world key**
-
- The private part is used to sign the key certificate corresponding to the
- non secure world image (BL33). The public part is stored in one of the
- extension fields in the trusted world certificate.
-
-* **BL3-X keys**
-
- For each of SCP_BL2, BL31, BL32 and BL33, the private part is used to
- sign the content certificate for the BL3-X image. The public part is stored
- in one of the extension fields in the corresponding key certificate.
-
-The following images are included in the CoT:
-
-* BL1
-* BL2
-* SCP_BL2 (optional)
-* BL31
-* BL33
-* BL32 (optional)
-
-The following certificates are used to authenticate the images.
-
-* **BL2 content certificate**
-
- It is self-signed with the private part of the ROT key. It contains a hash
- of the BL2 image.
-
-* **Trusted key certificate**
-
- It is self-signed with the private part of the ROT key. It contains the
- public part of the trusted world key and the public part of the non-trusted
- world key.
-
-* **SCP_BL2 key certificate**
-
- It is self-signed with the trusted world key. It contains the public part of
- the SCP_BL2 key.
-
-* **SCP_BL2 content certificate**
-
- It is self-signed with the SCP_BL2 key. It contains a hash of the SCP_BL2
- image.
-
-* **BL31 key certificate**
-
- It is self-signed with the trusted world key. It contains the public part of
- the BL31 key.
-
-* **BL31 content certificate**
-
- It is self-signed with the BL31 key. It contains a hash of the BL31 image.
-
-* **BL32 key certificate**
-
- It is self-signed with the trusted world key. It contains the public part of
- the BL32 key.
-
-* **BL32 content certificate**
-
- It is self-signed with the BL32 key. It contains a hash of the BL32 image.
-
-* **BL33 key certificate**
-
- It is self-signed with the non-trusted world key. It contains the public
- part of the BL33 key.
-
-* **BL33 content certificate**
-
- It is self-signed with the BL33 key. It contains a hash of the BL33 image.
-
-The SCP_BL2 and BL32 certificates are optional, but they must be present if the
-corresponding SCP_BL2 or BL32 images are present.
-
-
-3. Trusted Board Boot Sequence
--------------------------------
-
-The CoT is verified through the following sequence of steps. The system panics
-if any of the steps fail.
-
-* BL1 loads and verifies the BL2 content certificate. The issuer public key is
- read from the verified certificate. A hash of that key is calculated and
- compared with the hash of the ROTPK read from the trusted root-key storage
- registers. If they match, the BL2 hash is read from the certificate.
-
- Note: the matching operation is platform specific and is currently
- unimplemented on the ARM development platforms.
-
-* BL1 loads the BL2 image. Its hash is calculated and compared with the hash
- read from the certificate. Control is transferred to the BL2 image if all
- the comparisons succeed.
-
-* BL2 loads and verifies the trusted key certificate. The issuer public key is
- read from the verified certificate. A hash of that key is calculated and
- compared with the hash of the ROTPK read from the trusted root-key storage
- registers. If the comparison succeeds, BL2 reads and saves the trusted and
- non-trusted world public keys from the verified certificate.
-
-The next two steps are executed for each of the SCP_BL2, BL31 & BL32 images.
-The steps for the optional SCP_BL2 and BL32 images are skipped if these images
-are not present.
-
-* BL2 loads and verifies the BL3x key certificate. The certificate signature
- is verified using the trusted world public key. If the signature
- verification succeeds, BL2 reads and saves the BL3x public key from the
- certificate.
-
-* BL2 loads and verifies the BL3x content certificate. The signature is
- verified using the BL3x public key. If the signature verification succeeds,
- BL2 reads and saves the BL3x image hash from the certificate.
-
-The next two steps are executed only for the BL33 image.
-
-* BL2 loads and verifies the BL33 key certificate. If the signature
- verification succeeds, BL2 reads and saves the BL33 public key from the
- certificate.
-
-* BL2 loads and verifies the BL33 content certificate. If the signature
- verification succeeds, BL2 reads and saves the BL33 image hash from the
- certificate.
-
-The next step is executed for all the boot loader images.
-
-* BL2 calculates the hash of each image. It compares it with the hash obtained
- from the corresponding content certificate. The image authentication succeeds
- if the hashes match.
-
-The Trusted Board Boot implementation spans both generic and platform-specific
-BL1 and BL2 code, and in tool code on the host build machine. The feature is
-enabled through use of specific build flags as described in the [User Guide].
-
-On the host machine, a tool generates the certificates, which are included in
-the FIP along with the boot loader images. These certificates are loaded in
-Trusted SRAM using the IO storage framework. They are then verified by an
-Authentication module included in the Trusted Firmware.
-
-The mechanism used for generating the FIP and the Authentication module are
-described in the following sections.
-
-
-4. Authentication Framework
-----------------------------
-
-The authentication framework included in the Trusted Firmware provides support
-to implement the desired trusted boot sequence. ARM platforms use this framework
-to implement the boot requirements specified in the TBBR-client document.
-
-More information about the authentication framework can be found in the
-[Auth Framework] document.
-
-
-5. Certificate Generation Tool
--------------------------------
-
-The `cert_create` tool is built and runs on the host machine as part of the
-Trusted Firmware build process when `GENERATE_COT=1`. It takes the boot loader
-images and keys as inputs (keys must be in PEM format) and generates the
-certificates (in DER format) required to establish the CoT. New keys can be
-generated by the tool in case they are not provided. The certificates are then
-passed as inputs to the `fiptool` utility for creating the FIP.
-
-The certificates are also stored individually in the in the output build
-directory.
-
-The tool resides in the `tools/cert_create` directory. It uses OpenSSL SSL
-library version 1.0.1 or later to generate the X.509 certificates. Instructions
-for building and using the tool can be found in the [User Guide].
-
-
-- - - - - - - - - - - - - - - - - - - - - - - - - -
-
-_Copyright (c) 2015, ARM Limited and Contributors. All rights reserved._
-
-
-[X.509 v3]: http://www.ietf.org/rfc/rfc5280.txt
-[X.690]: http://www.itu.int/ITU-T/studygroups/com17/languages/X.690-0207.pdf
-[Auth Framework]: auth-framework.md
-[User Guide]: user-guide.md
-[Firmware Update]: firmware-update.md
diff --git a/docs/trusted-board-boot.rst b/docs/trusted-board-boot.rst
new file mode 100644
index 0000000..6a28da0
--- /dev/null
+++ b/docs/trusted-board-boot.rst
@@ -0,0 +1,238 @@
+Trusted Board Boot Design Guide
+===============================
+
+
+.. section-numbering::
+ :suffix: .
+
+.. contents::
+
+The Trusted Board Boot (TBB) feature prevents malicious firmware from running on
+the platform by authenticating all firmware images up to and including the
+normal world bootloader. It does this by establishing a Chain of Trust using
+Public-Key-Cryptography Standards (PKCS).
+
+This document describes the design of ARM Trusted Firmware TBB, which is an
+implementation of the Trusted Board Boot Requirements (TBBR) specification,
+ARM DEN0006C-1. It should be used in conjunction with the `Firmware Update`_
+design document, which implements a specific aspect of the TBBR.
+
+Chain of Trust
+--------------
+
+A Chain of Trust (CoT) starts with a set of implicitly trusted components. On
+the ARM development platforms, these components are:
+
+- A SHA-256 hash of the Root of Trust Public Key (ROTPK). It is stored in the
+ trusted root-key storage registers.
+
+- The BL1 image, on the assumption that it resides in ROM so cannot be
+ tampered with.
+
+The remaining components in the CoT are either certificates or boot loader
+images. The certificates follow the `X.509 v3`_ standard. This standard
+enables adding custom extensions to the certificates, which are used to store
+essential information to establish the CoT.
+
+In the TBB CoT all certificates are self-signed. There is no need for a
+Certificate Authority (CA) because the CoT is not established by verifying the
+validity of a certificate's issuer but by the content of the certificate
+extensions. To sign the certificates, the PKCS#1 SHA-256 with RSA Encryption
+signature scheme is used with a RSA key length of 2048 bits. Future version of
+Trusted Firmware will support additional cryptographic algorithms.
+
+The certificates are categorised as "Key" and "Content" certificates. Key
+certificates are used to verify public keys which have been used to sign content
+certificates. Content certificates are used to store the hash of a boot loader
+image. An image can be authenticated by calculating its hash and matching it
+with the hash extracted from the content certificate. The SHA-256 function is
+used to calculate all hashes. The public keys and hashes are included as
+non-standard extension fields in the `X.509 v3`_ certificates.
+
+The keys used to establish the CoT are:
+
+- **Root of trust key**
+
+ The private part of this key is used to sign the BL2 content certificate and
+ the trusted key certificate. The public part is the ROTPK.
+
+- **Trusted world key**
+
+ The private part is used to sign the key certificates corresponding to the
+ secure world images (SCP\_BL2, BL31 and BL32). The public part is stored in
+ one of the extension fields in the trusted world certificate.
+
+- **Non-trusted world key**
+
+ The private part is used to sign the key certificate corresponding to the
+ non secure world image (BL33). The public part is stored in one of the
+ extension fields in the trusted world certificate.
+
+- **BL3-X keys**
+
+ For each of SCP\_BL2, BL31, BL32 and BL33, the private part is used to
+ sign the content certificate for the BL3-X image. The public part is stored
+ in one of the extension fields in the corresponding key certificate.
+
+The following images are included in the CoT:
+
+- BL1
+- BL2
+- SCP\_BL2 (optional)
+- BL31
+- BL33
+- BL32 (optional)
+
+The following certificates are used to authenticate the images.
+
+- **BL2 content certificate**
+
+ It is self-signed with the private part of the ROT key. It contains a hash
+ of the BL2 image.
+
+- **Trusted key certificate**
+
+ It is self-signed with the private part of the ROT key. It contains the
+ public part of the trusted world key and the public part of the non-trusted
+ world key.
+
+- **SCP\_BL2 key certificate**
+
+ It is self-signed with the trusted world key. It contains the public part of
+ the SCP\_BL2 key.
+
+- **SCP\_BL2 content certificate**
+
+ It is self-signed with the SCP\_BL2 key. It contains a hash of the SCP\_BL2
+ image.
+
+- **BL31 key certificate**
+
+ It is self-signed with the trusted world key. It contains the public part of
+ the BL31 key.
+
+- **BL31 content certificate**
+
+ It is self-signed with the BL31 key. It contains a hash of the BL31 image.
+
+- **BL32 key certificate**
+
+ It is self-signed with the trusted world key. It contains the public part of
+ the BL32 key.
+
+- **BL32 content certificate**
+
+ It is self-signed with the BL32 key. It contains a hash of the BL32 image.
+
+- **BL33 key certificate**
+
+ It is self-signed with the non-trusted world key. It contains the public
+ part of the BL33 key.
+
+- **BL33 content certificate**
+
+ It is self-signed with the BL33 key. It contains a hash of the BL33 image.
+
+The SCP\_BL2 and BL32 certificates are optional, but they must be present if the
+corresponding SCP\_BL2 or BL32 images are present.
+
+Trusted Board Boot Sequence
+---------------------------
+
+The CoT is verified through the following sequence of steps. The system panics
+if any of the steps fail.
+
+- BL1 loads and verifies the BL2 content certificate. The issuer public key is
+ read from the verified certificate. A hash of that key is calculated and
+ compared with the hash of the ROTPK read from the trusted root-key storage
+ registers. If they match, the BL2 hash is read from the certificate.
+
+ Note: the matching operation is platform specific and is currently
+ unimplemented on the ARM development platforms.
+
+- BL1 loads the BL2 image. Its hash is calculated and compared with the hash
+ read from the certificate. Control is transferred to the BL2 image if all
+ the comparisons succeed.
+
+- BL2 loads and verifies the trusted key certificate. The issuer public key is
+ read from the verified certificate. A hash of that key is calculated and
+ compared with the hash of the ROTPK read from the trusted root-key storage
+ registers. If the comparison succeeds, BL2 reads and saves the trusted and
+ non-trusted world public keys from the verified certificate.
+
+The next two steps are executed for each of the SCP\_BL2, BL31 & BL32 images.
+The steps for the optional SCP\_BL2 and BL32 images are skipped if these images
+are not present.
+
+- BL2 loads and verifies the BL3x key certificate. The certificate signature
+ is verified using the trusted world public key. If the signature
+ verification succeeds, BL2 reads and saves the BL3x public key from the
+ certificate.
+
+- BL2 loads and verifies the BL3x content certificate. The signature is
+ verified using the BL3x public key. If the signature verification succeeds,
+ BL2 reads and saves the BL3x image hash from the certificate.
+
+The next two steps are executed only for the BL33 image.
+
+- BL2 loads and verifies the BL33 key certificate. If the signature
+ verification succeeds, BL2 reads and saves the BL33 public key from the
+ certificate.
+
+- BL2 loads and verifies the BL33 content certificate. If the signature
+ verification succeeds, BL2 reads and saves the BL33 image hash from the
+ certificate.
+
+The next step is executed for all the boot loader images.
+
+- BL2 calculates the hash of each image. It compares it with the hash obtained
+ from the corresponding content certificate. The image authentication succeeds
+ if the hashes match.
+
+The Trusted Board Boot implementation spans both generic and platform-specific
+BL1 and BL2 code, and in tool code on the host build machine. The feature is
+enabled through use of specific build flags as described in the `User Guide`_.
+
+On the host machine, a tool generates the certificates, which are included in
+the FIP along with the boot loader images. These certificates are loaded in
+Trusted SRAM using the IO storage framework. They are then verified by an
+Authentication module included in the Trusted Firmware.
+
+The mechanism used for generating the FIP and the Authentication module are
+described in the following sections.
+
+Authentication Framework
+------------------------
+
+The authentication framework included in the Trusted Firmware provides support
+to implement the desired trusted boot sequence. ARM platforms use this framework
+to implement the boot requirements specified in the TBBR-client document.
+
+More information about the authentication framework can be found in the
+`Auth Framework`_ document.
+
+Certificate Generation Tool
+---------------------------
+
+The ``cert_create`` tool is built and runs on the host machine as part of the
+Trusted Firmware build process when ``GENERATE_COT=1``. It takes the boot loader
+images and keys as inputs (keys must be in PEM format) and generates the
+certificates (in DER format) required to establish the CoT. New keys can be
+generated by the tool in case they are not provided. The certificates are then
+passed as inputs to the ``fiptool`` utility for creating the FIP.
+
+The certificates are also stored individually in the in the output build
+directory.
+
+The tool resides in the ``tools/cert_create`` directory. It uses OpenSSL SSL
+library version 1.0.1 or later to generate the X.509 certificates. Instructions
+for building and using the tool can be found in the `User Guide`_.
+
+--------------
+
+*Copyright (c) 2015, ARM Limited and Contributors. All rights reserved.*
+
+.. _Firmware Update: firmware-update.rst
+.. _X.509 v3: http://www.ietf.org/rfc/rfc5280.txt
+.. _User Guide: user-guide.rst
+.. _Auth Framework: auth-framework.rst
diff --git a/docs/user-guide.md b/docs/user-guide.md
deleted file mode 100644
index ea2874d..0000000
--- a/docs/user-guide.md
+++ /dev/null
@@ -1,1601 +0,0 @@
-ARM Trusted Firmware User Guide
-===============================
-
-Contents :
-
-1. [Introduction](#1--introduction)
-2. [Host machine requirements](#2--host-machine-requirements)
-3. [Tools](#3--tools)
-4. [Getting the Trusted Firmware source code](#4--getting-the-trusted-firmware-source-code)
-5. [Building the Trusted Firmware](#5--building-the-trusted-firmware)
-6. [Building a FIP for Juno and FVP](#6--building-a-fip-for-juno-and-fvp)
-7. [EL3 payloads alternative boot flow](#7--el3-payloads-alternative-boot-flow)
-8. [Preloaded BL33 alternative boot flow](#8--preloaded-bl33-alternative-boot-flow)
-9. [Running the software on FVP](#9--running-the-software-on-fvp)
-10. [Running the software on Juno](#10--running-the-software-on-juno)
-
-
-1. Introduction
-----------------
-
-This document describes how to build ARM Trusted Firmware (TF) and run it with a
-tested set of other software components using defined configurations on the Juno
-ARM development platform and ARM Fixed Virtual Platform (FVP) models. It is
-possible to use other software components, configurations and platforms but that
-is outside the scope of this document.
-
-This document assumes that the reader has previous experience running a fully
-bootable Linux software stack on Juno or FVP using the prebuilt binaries and
-filesystems provided by [Linaro][Linaro Release Notes]. Further information may
-be found in the [Instructions for using the Linaro software deliverables]
-[Linaro SW Instructions]. It also assumes that the user understands the role of
-the different software components required to boot a Linux system:
-
-* Specific firmware images required by the platform (e.g. SCP firmware on Juno)
-* Normal world bootloader (e.g. UEFI or U-Boot)
-* Device tree
-* Linux kernel image
-* Root filesystem
-
-Note: the ARM TF v1.3 release was tested with Linaro Release 16.06, and the
-latest version of ARM TF is tested with Linaro Release 17.01.
-
-This document also assumes that the user is familiar with the FVP models and
-the different command line options available to launch the model.
-
-This document should be used in conjunction with the [Firmware Design].
-
-
-2. Host machine requirements
------------------------------
-
-The minimum recommended machine specification for building the software and
-running the FVP models is a dual-core processor running at 2GHz with 12GB of
-RAM. For best performance, use a machine with a quad-core processor running at
-2.6GHz with 16GB of RAM.
-
-The software has been tested on Ubuntu 14.04 LTS (64-bit). Packages used for
-building the software were installed from that distribution unless otherwise
-specified.
-
-The software has also been built on Windows 7 Enterprise SP1, using CMD.EXE,
-Cygwin, and Msys (MinGW) shells, using version 4.9.1 of the GNU toolchain.
-
-3. Tools
----------
-
-Install the required packages to build Trusted Firmware with the following
-command:
-
- sudo apt-get install build-essential gcc make git libssl-dev
-
-Download and install the AArch32 or AArch64 little-endian GCC cross compiler.
-The [Linaro Release Notes][Linaro Release Notes] documents which version of the
-compiler to use for a given Linaro Release. Also, these
-[Linaro instructions][Linaro SW Instructions] provide further guidance.
-
-Optionally, Trusted Firmware can be built using clang or ARM Compiler 6.
-See instructions below on how to switch the default compiler.
-
-In addition, the following optional packages and tools may be needed:
-
-* `device-tree-compiler` package if you need to rebuild the Flattened Device
- Tree (FDT) source files (`.dts` files) provided with this software.
-
-* For debugging, ARM [Development Studio 5 (DS-5)][DS-5].
-
-
-4. Getting the Trusted Firmware source code
---------------------------------------------
-
-Download the Trusted Firmware source code from Github:
-
- git clone https://github.com/ARM-software/arm-trusted-firmware.git
-
-
-5. Building the Trusted Firmware
----------------------------------
-
-* Before building Trusted Firmware, the environment variable `CROSS_COMPILE`
- must point to the Linaro cross compiler.
-
- For AArch64:
-
- export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
-
- For AArch32:
-
- export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-linux-gnueabihf-
-
- It is possible to build Trusted Firmware using clang or ARM Compiler 6.
- To do so `CC` needs to point to the clang or armclang binary. Only the
- compiler is switched; the assembler and linker need to be provided by
- the GNU toolchain, thus `CROSS_COMPILE` should be set as described above.
-
- ARM Compiler 6 will be selected when the base name of the path assigned
- to `CC` matches the string 'armclang'.
-
- For AArch64 using ARM Compiler 6:
-
- export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
- make CC=<path-to-armclang>/bin/armclang PLAT=<platform> all
-
- Clang will be selected when the base name of the path assigned to `CC`
- contains the string 'clang'. This is to allow both clang and clang-X.Y
- to work.
-
- For AArch64 using clang:
-
- export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
- make CC=<path-to-clang>/bin/clang PLAT=<platform> all
-
-* Change to the root directory of the Trusted Firmware source tree and build.
-
- For AArch64:
-
- make PLAT=<platform> all
-
- For AArch32:
-
- make PLAT=<platform> ARCH=aarch32 AARCH32_SP=sp_min all
-
-
- Notes:
-
- * If `PLAT` is not specified, `fvp` is assumed by default. See the
- "Summary of build options" for more information on available build
- options.
-
- * (AArch32 only) Currently only `PLAT=fvp` is supported.
-
- * (AArch32 only) `AARCH32_SP` is the AArch32 EL3 Runtime Software and it
- corresponds to the BL32 image. A minimal `AARCH32_SP`, sp_min, is
- provided by ARM Trusted Firmware to demonstrate how PSCI Library can
- be integrated with an AArch32 EL3 Runtime Software. Some AArch32 EL3
- Runtime Software may include other runtime services, for example
- Trusted OS services. A guide to integrate PSCI library with AArch32
- EL3 Runtime Software can be found [here][PSCI Lib Integration].
-
- * (AArch64 only) The TSP (Test Secure Payload), corresponding to the BL32
- image, is not compiled in by default. Refer to the "Building the Test
- Secure Payload" section below.
-
- * By default this produces a release version of the build. To produce a
- debug version instead, refer to the "Debugging options" section below.
-
- * The build process creates products in a `build` directory tree, building
- the objects and binaries for each boot loader stage in separate
- sub-directories. The following boot loader binary files are created
- from the corresponding ELF files:
-
- * `build/<platform>/<build-type>/bl1.bin`
- * `build/<platform>/<build-type>/bl2.bin`
- * `build/<platform>/<build-type>/bl31.bin` (AArch64 only)
- * `build/<platform>/<build-type>/bl32.bin` (mandatory for AArch32)
-
- where `<platform>` is the name of the chosen platform and `<build-type>`
- is either `debug` or `release`. The actual number of images might differ
- depending on the platform.
-
-* Build products for a specific build variant can be removed using:
-
- make DEBUG=<D> PLAT=<platform> clean
-
- ... where `<D>` is `0` or `1`, as specified when building.
-
- The build tree can be removed completely using:
-
- make realclean
-
-### Summary of build options
-
-ARM Trusted Firmware build system supports the following build options. Unless
-mentioned otherwise, these options are expected to be specified at the build
-command line and are not to be modified in any component makefiles. Note that
-the build system doesn't track dependency for build options. Therefore, if any
-of the build options are changed from a previous build, a clean build must be
-performed.
-
-#### Common build options
-
-* `AARCH32_SP` : Choose the AArch32 Secure Payload component to be built as
- as the BL32 image when `ARCH=aarch32`. The value should be the path to the
- directory containing the SP source, relative to the `bl32/`; the directory
- is expected to contain a makefile called `<aarch32_sp-value>.mk`.
-
-* `ARCH` : Choose the target build architecture for ARM Trusted Firmware.
- It can take either `aarch64` or `aarch32` as values. By default, it is
- defined to `aarch64`.
-
-* `ARM_CCI_PRODUCT_ID`: Choice of ARM CCI product used by the platform. This
- is used to determine the number of valid slave interfaces available in the
- ARM CCI driver. Default is 400 (that is, CCI-400).
-
-* `ARM_ARCH_MAJOR`: The major version of ARM Architecture to target when
- compiling ARM Trusted Firmware. Its value must be numeric, and defaults to
- 8. See also, _ARMv8 Architecture Extensions_ in [Firmware Design].
-
-* `ARM_ARCH_MINOR`: The minor version of ARM Architecture to target when
- compiling ARM Trusted Firmware. Its value must be a numeric, and defaults
- to 0. See also, _ARMv8 Architecture Extensions_ in [Firmware Design].
-
-* `ARM_GIC_ARCH`: Choice of ARM GIC architecture version used by the ARM
- Legacy GIC driver for implementing the platform GIC API. This API is used
- by the interrupt management framework. Default is 2 (that is, version 2.0).
- This build option is deprecated.
-
-* `ARM_PLAT_MT`: This flag determines whether the ARM platform layer has to
- cater for the multi-threading `MT` bit when accessing MPIDR. When this
- flag is set, the functions which deal with MPIDR assume that the `MT` bit
- in MPIDR is set and access the bit-fields in MPIDR accordingly. Default
- value of this flag is 0.
-
-* `BL2`: This is an optional build option which specifies the path to BL2
- image for the `fip` target. In this case, the BL2 in the ARM Trusted
- Firmware will not be built.
-
-* `BL2U`: This is an optional build option which specifies the path to
- BL2U image. In this case, the BL2U in the ARM Trusted Firmware will not
- be built.
-
-* `BL31`: This is an optional build option which specifies the path to
- BL31 image for the `fip` target. In this case, the BL31 in the ARM
- Trusted Firmware will not be built.
-
-* `BL31_KEY`: This option is used when `GENERATE_COT=1`. It specifies the
- file that contains the BL31 private key in PEM format. If `SAVE_KEYS=1`,
- this file name will be used to save the key.
-
-* `BL32`: This is an optional build option which specifies the path to
- BL32 image for the `fip` target. In this case, the BL32 in the ARM
- Trusted Firmware will not be built.
-
-* `BL32_KEY`: This option is used when `GENERATE_COT=1`. It specifies the
- file that contains the BL32 private key in PEM format. If `SAVE_KEYS=1`,
- this file name will be used to save the key.
-
-* `BL33`: Path to BL33 image in the host file system. This is mandatory for
- `fip` target in case the BL2 from ARM Trusted Firmware is used.
-
-* `BL33_KEY`: This option is used when `GENERATE_COT=1`. It specifies the
- file that contains the BL33 private key in PEM format. If `SAVE_KEYS=1`,
- this file name will be used to save the key.
-
-* `BUILD_MESSAGE_TIMESTAMP`: String used to identify the time and date of the
- compilation of each build. It must be set to a C string (including quotes
- where applicable). Defaults to a string that contains the time and date of
- the compilation.
-
-* `BUILD_STRING`: Input string for VERSION_STRING, which allows the TF build
- to be uniquely identified. Defaults to the current git commit id.
-
-* `CFLAGS`: Extra user options appended on the compiler's command line in
- addition to the options set by the build system.
-
-* `COLD_BOOT_SINGLE_CPU`: This option indicates whether the platform may
- release several CPUs out of reset. It can take either 0 (several CPUs may be
- brought up) or 1 (only one CPU will ever be brought up during cold reset).
- Default is 0. If the platform always brings up a single CPU, there is no
- need to distinguish between primary and secondary CPUs and the boot path can
- be optimised. The `plat_is_my_cpu_primary()` and
- `plat_secondary_cold_boot_setup()` platform porting interfaces do not need
- to be implemented in this case.
-
-* `CRASH_REPORTING`: A non-zero value enables a console dump of processor
- register state when an unexpected exception occurs during execution of
- BL31. This option defaults to the value of `DEBUG` - i.e. by default
- this is only enabled for a debug build of the firmware.
-
-* `CREATE_KEYS`: This option is used when `GENERATE_COT=1`. It tells the
- certificate generation tool to create new keys in case no valid keys are
- present or specified. Allowed options are '0' or '1'. Default is '1'.
-
-* `CTX_INCLUDE_AARCH32_REGS` : Boolean option that, when set to 1, will cause
- the AArch32 system registers to be included when saving and restoring the
- CPU context. The option must be set to 0 for AArch64-only platforms (that
- is on hardware that does not implement AArch32, or at least not at EL1 and
- higher ELs). Default value is 1.
-
-* `CTX_INCLUDE_FPREGS`: Boolean option that, when set to 1, will cause the FP
- registers to be included when saving and restoring the CPU context. Default
- is 0.
-
-* `DEBUG`: Chooses between a debug and release build. It can take either 0
- (release) or 1 (debug) as values. 0 is the default.
-
-* `EL3_PAYLOAD_BASE`: This option enables booting an EL3 payload instead of
- the normal boot flow. It must specify the entry point address of the EL3
- payload. Please refer to the "Booting an EL3 payload" section for more
- details.
-
-* `ENABLE_ASSERTIONS`: This option controls whether or not calls to `assert()`
- are compiled out. For debug builds, this option defaults to 1, and calls to
- `assert()` are left in place. For release builds, this option defaults to 0
- and calls to `assert()` function are compiled out. This option can be set
- independently of `DEBUG`. It can also be used to hide any auxiliary code
- that is only required for the assertion and does not fit in the assertion
- itself.
-
-* `ENABLE_PMF`: Boolean option to enable support for optional Performance
- Measurement Framework(PMF). Default is 0.
-
-* `ENABLE_PSCI_STAT`: Boolean option to enable support for optional PSCI
- functions `PSCI_STAT_RESIDENCY` and `PSCI_STAT_COUNT`. Default is 0.
- In the absence of an alternate stat collection backend, `ENABLE_PMF` must
- be enabled. If `ENABLE_PMF` is set, the residency statistics are tracked in
- software.
-
-* `ENABLE_RUNTIME_INSTRUMENTATION`: Boolean option to enable runtime
- instrumentation which injects timestamp collection points into
- Trusted Firmware to allow runtime performance to be measured.
- Currently, only PSCI is instrumented. Enabling this option enables
- the `ENABLE_PMF` build option as well. Default is 0.
-
-* `ENABLE_STACK_PROTECTOR`: String option to enable the stack protection
- checks in GCC. Allowed values are "all", "strong" and "0" (default).
- "strong" is the recommended stack protection level if this feature is
- desired. 0 disables the stack protection. For all values other than 0, the
- `plat_get_stack_protector_canary()` platform hook needs to be implemented.
- The value is passed as the last component of the option
- `-fstack-protector-$ENABLE_STACK_PROTECTOR`.
-
-* `ERROR_DEPRECATED`: This option decides whether to treat the usage of
- deprecated platform APIs, helper functions or drivers within Trusted
- Firmware as error. It can take the value 1 (flag the use of deprecated
- APIs as error) or 0. The default is 0.
-
-* `FIP_NAME`: This is an optional build option which specifies the FIP
- filename for the `fip` target. Default is `fip.bin`.
-
-* `FWU_FIP_NAME`: This is an optional build option which specifies the FWU
- FIP filename for the `fwu_fip` target. Default is `fwu_fip.bin`.
-
-* `GENERATE_COT`: Boolean flag used to build and execute the `cert_create`
- tool to create certificates as per the Chain of Trust described in
- [Trusted Board Boot]. The build system then calls `fiptool` to
- include the certificates in the FIP and FWU_FIP. Default value is '0'.
-
- Specify both `TRUSTED_BOARD_BOOT=1` and `GENERATE_COT=1` to include support
- for the Trusted Board Boot feature in the BL1 and BL2 images, to generate
- the corresponding certificates, and to include those certificates in the
- FIP and FWU_FIP.
-
- Note that if `TRUSTED_BOARD_BOOT=0` and `GENERATE_COT=1`, the BL1 and BL2
- images will not include support for Trusted Board Boot. The FIP will still
- include the corresponding certificates. This FIP can be used to verify the
- Chain of Trust on the host machine through other mechanisms.
-
- Note that if `TRUSTED_BOARD_BOOT=1` and `GENERATE_COT=0`, the BL1 and BL2
- images will include support for Trusted Board Boot, but the FIP and FWU_FIP
- will not include the corresponding certificates, causing a boot failure.
-
-* `HANDLE_EA_EL3_FIRST`: When defined External Aborts and SError Interrupts
- will be always trapped in EL3 i.e. in BL31 at runtime.
-
-* `HW_ASSISTED_COHERENCY`: On most ARM systems to-date, platform-specific
- software operations are required for CPUs to enter and exit coherency.
- However, there exists newer systems where CPUs' entry to and exit from
- coherency is managed in hardware. Such systems require software to only
- initiate the operations, and the rest is managed in hardware, minimizing
- active software management. In such systems, this boolean option enables ARM
- Trusted Firmware to carry out build and run-time optimizations during boot
- and power management operations. This option defaults to 0 and if it is
- enabled, then it implies `WARMBOOT_ENABLE_DCACHE_EARLY` is also enabled.
-
-* `JUNO_AARCH32_EL3_RUNTIME`: This build flag enables you to execute EL3
- runtime software in AArch32 mode, which is required to run AArch32 on Juno.
- By default this flag is set to '0'. Enabling this flag builds BL1 and BL2 in
- AArch64 and facilitates the loading of `SP_MIN` and BL33 as AArch32 executable
- images.
-
-* `LDFLAGS`: Extra user options appended to the linkers' command line in
- addition to the one set by the build system.
-
-* `LOAD_IMAGE_V2`: Boolean option to enable support for new version (v2) of
- image loading, which provides more flexibility and scalability around what
- images are loaded and executed during boot. Default is 0.
- Note: `TRUSTED_BOARD_BOOT` is currently only supported for AArch64 when
- `LOAD_IMAGE_V2` is enabled.
-
-* `LOG_LEVEL`: Chooses the log level, which controls the amount of console log
- output compiled into the build. This should be one of the following:
-
- 0 (LOG_LEVEL_NONE)
- 10 (LOG_LEVEL_NOTICE)
- 20 (LOG_LEVEL_ERROR)
- 30 (LOG_LEVEL_WARNING)
- 40 (LOG_LEVEL_INFO)
- 50 (LOG_LEVEL_VERBOSE)
-
- All log output up to and including the log level is compiled into the build.
- The default value is 40 in debug builds and 20 in release builds.
-
-* `NON_TRUSTED_WORLD_KEY`: This option is used when `GENERATE_COT=1`. It
- specifies the file that contains the Non-Trusted World private key in PEM
- format. If `SAVE_KEYS=1`, this file name will be used to save the key.
-
-* `NS_BL2U`: Path to NS_BL2U image in the host file system. This image is
- optional. It is only needed if the platform makefile specifies that it
- is required in order to build the `fwu_fip` target.
-
-* `NS_TIMER_SWITCH`: Enable save and restore for non-secure timer register
- contents upon world switch. It can take either 0 (don't save and restore) or
- 1 (do save and restore). 0 is the default. An SPD may set this to 1 if it
- wants the timer registers to be saved and restored.
-
-* `PL011_GENERIC_UART`: Boolean option to indicate the PL011 driver that
- the underlying hardware is not a full PL011 UART but a minimally compliant
- generic UART, which is a subset of the PL011. The driver will not access
- any register that is not part of the SBSA generic UART specification.
- Default value is 0 (a full PL011 compliant UART is present).
-
-* `PLAT`: Choose a platform to build ARM Trusted Firmware for. The chosen
- platform name must be subdirectory of any depth under `plat/`, and must
- contain a platform makefile named `platform.mk`.
-
-* `PRELOADED_BL33_BASE`: This option enables booting a preloaded BL33 image
- instead of the normal boot flow. When defined, it must specify the entry
- point address for the preloaded BL33 image. This option is incompatible with
- `EL3_PAYLOAD_BASE`. If both are defined, `EL3_PAYLOAD_BASE` has priority
- over `PRELOADED_BL33_BASE`.
-
-* `PROGRAMMABLE_RESET_ADDRESS`: This option indicates whether the reset
- vector address can be programmed or is fixed on the platform. It can take
- either 0 (fixed) or 1 (programmable). Default is 0. If the platform has a
- programmable reset address, it is expected that a CPU will start executing
- code directly at the right address, both on a cold and warm reset. In this
- case, there is no need to identify the entrypoint on boot and the boot path
- can be optimised. The `plat_get_my_entrypoint()` platform porting interface
- does not need to be implemented in this case.
-
-* `PSCI_EXTENDED_STATE_ID`: As per PSCI1.0 Specification, there are 2 formats
- possible for the PSCI power-state parameter viz original and extended
- State-ID formats. This flag if set to 1, configures the generic PSCI layer
- to use the extended format. The default value of this flag is 0, which
- means by default the original power-state format is used by the PSCI
- implementation. This flag should be specified by the platform makefile
- and it governs the return value of PSCI_FEATURES API for CPU_SUSPEND
- smc function id. When this option is enabled on ARM platforms, the
- option `ARM_RECOM_STATE_ID_ENC` needs to be set to 1 as well.
-
-* `RESET_TO_BL31`: Enable BL31 entrypoint as the CPU reset vector instead
- of the BL1 entrypoint. It can take the value 0 (CPU reset to BL1
- entrypoint) or 1 (CPU reset to BL31 entrypoint).
- The default value is 0.
-
-* `RESET_TO_SP_MIN`: SP_MIN is the minimal AArch32 Secure Payload provided in
- ARM Trusted Firmware. This flag configures SP_MIN entrypoint as the CPU
- reset vector instead of the BL1 entrypoint. It can take the value 0 (CPU
- reset to BL1 entrypoint) or 1 (CPU reset to SP_MIN entrypoint). The default
- value is 0.
-
-* `ROT_KEY`: This option is used when `GENERATE_COT=1`. It specifies the
- file that contains the ROT private key in PEM format. If `SAVE_KEYS=1`, this
- file name will be used to save the key.
-
-* `SAVE_KEYS`: This option is used when `GENERATE_COT=1`. It tells the
- certificate generation tool to save the keys used to establish the Chain of
- Trust. Allowed options are '0' or '1'. Default is '0' (do not save).
-
-* `SCP_BL2`: Path to SCP_BL2 image in the host file system. This image is optional.
- If a SCP_BL2 image is present then this option must be passed for the `fip`
- target.
-
-* `SCP_BL2_KEY`: This option is used when `GENERATE_COT=1`. It specifies the
- file that contains the SCP_BL2 private key in PEM format. If `SAVE_KEYS=1`,
- this file name will be used to save the key.
-
-* `SCP_BL2U`: Path to SCP_BL2U image in the host file system. This image is
- optional. It is only needed if the platform makefile specifies that it
- is required in order to build the `fwu_fip` target.
-
-* `SEPARATE_CODE_AND_RODATA`: Whether code and read-only data should be
- isolated on separate memory pages. This is a trade-off between security and
- memory usage. See "Isolating code and read-only data on separate memory
- pages" section in [Firmware Design]. This flag is disabled by default and
- affects all BL images.
-
-* `SPD`: Choose a Secure Payload Dispatcher component to be built into the
- Trusted Firmware. This build option is only valid if `ARCH=aarch64`. The
- value should be the path to the directory containing the SPD source,
- relative to `services/spd/`; the directory is expected to
- contain a makefile called `<spd-value>.mk`.
-
-* `SPIN_ON_BL1_EXIT`: This option introduces an infinite loop in BL1. It can
- take either 0 (no loop) or 1 (add a loop). 0 is the default. This loop stops
- execution in BL1 just before handing over to BL31. At this point, all
- firmware images have been loaded in memory, and the MMU and caches are
- turned off. Refer to the "Debugging options" section for more details.
-
-* `TRUSTED_BOARD_BOOT`: Boolean flag to include support for the Trusted Board
- Boot feature. When set to '1', BL1 and BL2 images include support to load
- and verify the certificates and images in a FIP, and BL1 includes support
- for the Firmware Update. The default value is '0'. Generation and inclusion
- of certificates in the FIP and FWU_FIP depends upon the value of the
- `GENERATE_COT` option.
-
- Note: This option depends on `CREATE_KEYS` to be enabled. If the keys
- already exist in disk, they will be overwritten without further notice.
-
-* `TRUSTED_WORLD_KEY`: This option is used when `GENERATE_COT=1`. It
- specifies the file that contains the Trusted World private key in PEM
- format. If `SAVE_KEYS=1`, this file name will be used to save the key.
-
-* `TSP_INIT_ASYNC`: Choose BL32 initialization method as asynchronous or
- synchronous, (see "Initializing a BL32 Image" section in [Firmware
- Design]). It can take the value 0 (BL32 is initialized using
- synchronous method) or 1 (BL32 is initialized using asynchronous method).
- Default is 0.
-
-* `TSP_NS_INTR_ASYNC_PREEMPT`: A non zero value enables the interrupt
- routing model which routes non-secure interrupts asynchronously from TSP
- to EL3 causing immediate preemption of TSP. The EL3 is responsible
- for saving and restoring the TSP context in this routing model. The
- default routing model (when the value is 0) is to route non-secure
- interrupts to TSP allowing it to save its context and hand over
- synchronously to EL3 via an SMC.
-
-* `USE_COHERENT_MEM`: This flag determines whether to include the coherent
- memory region in the BL memory map or not (see "Use of Coherent memory in
- Trusted Firmware" section in [Firmware Design]). It can take the value 1
- (Coherent memory region is included) or 0 (Coherent memory region is
- excluded). Default is 1.
-
-* `V`: Verbose build. If assigned anything other than 0, the build commands
- are printed. Default is 0.
-
-* `VERSION_STRING`: String used in the log output for each TF image. Defaults
- to a string formed by concatenating the version number, build type and build
- string.
-
-* `WARMBOOT_ENABLE_DCACHE_EARLY` : Boolean option to enable D-cache early on
- the CPU after warm boot. This is applicable for platforms which do not
- require interconnect programming to enable cache coherency (eg: single
- cluster platforms). If this option is enabled, then warm boot path
- enables D-caches immediately after enabling MMU. This option defaults to 0.
-
-* `ENABLE_SPE_FOR_LOWER_ELS` : Boolean option to enable Statistical Profiling
- extensions. This is an optional architectural feature available only for
- AArch64 8.2 onwards. This option defaults to 1 but is automatically
- disabled when the target architecture is AArch32 or AArch64 8.0/8.1.
-
-#### ARM development platform specific build options
-
-* `ARM_BL31_IN_DRAM`: Boolean option to select loading of BL31 in TZC secured
- DRAM. By default, BL31 is in the secure SRAM. Set this flag to 1 to load
- BL31 in TZC secured DRAM. If TSP is present, then setting this option also
- sets the TSP location to DRAM and ignores the `ARM_TSP_RAM_LOCATION` build
- flag.
-
-* `ARM_BOARD_OPTIMISE_MEM`: Boolean option to enable or disable optimisation
- of the memory reserved for each image. This affects the maximum size of each
- BL image as well as the number of allocated memory regions and translation
- tables. By default this flag is 0, which means it uses the default
- unoptimised values for these macros. ARM development platforms that wish to
- optimise memory usage need to set this flag to 1 and must override the
- related macros.
-
-* `ARM_CONFIG_CNTACR`: boolean option to unlock access to the CNTBase<N>
- frame registers by setting the CNTCTLBase.CNTACR<N> register bits. The
- frame number <N> is defined by `PLAT_ARM_NSTIMER_FRAME_ID`, which should
- match the frame used by the Non-Secure image (normally the Linux kernel).
- Default is true (access to the frame is allowed).
-
-* `ARM_DISABLE_TRUSTED_WDOG`: boolean option to disable the Trusted Watchdog.
- By default, ARM platforms use a watchdog to trigger a system reset in case
- an error is encountered during the boot process (for example, when an image
- could not be loaded or authenticated). The watchdog is enabled in the early
- platform setup hook at BL1 and disabled in the BL1 prepare exit hook. The
- Trusted Watchdog may be disabled at build time for testing or development
- purposes.
-
-* `ARM_RECOM_STATE_ID_ENC`: The PSCI1.0 specification recommends an encoding
- for the construction of composite state-ID in the power-state parameter.
- The existing PSCI clients currently do not support this encoding of
- State-ID yet. Hence this flag is used to configure whether to use the
- recommended State-ID encoding or not. The default value of this flag is 0,
- in which case the platform is configured to expect NULL in the State-ID
- field of power-state parameter.
-
-* `ARM_ROTPK_LOCATION`: used when `TRUSTED_BOARD_BOOT=1`. It specifies the
- location of the ROTPK hash returned by the function `plat_get_rotpk_info()`
- for ARM platforms. Depending on the selected option, the proper private key
- must be specified using the `ROT_KEY` option when building the Trusted
- Firmware. This private key will be used by the certificate generation tool
- to sign the BL2 and Trusted Key certificates. Available options for
- `ARM_ROTPK_LOCATION` are:
-
- - `regs` : return the ROTPK hash stored in the Trusted root-key storage
- registers. The private key corresponding to this ROTPK hash is not
- currently available.
- - `devel_rsa` : return a development public key hash embedded in the BL1
- and BL2 binaries. This hash has been obtained from the RSA public key
- `arm_rotpk_rsa.der`, located in `plat/arm/board/common/rotpk`. To use
- this option, `arm_rotprivk_rsa.pem` must be specified as `ROT_KEY` when
- creating the certificates.
-
-* `ARM_TSP_RAM_LOCATION`: location of the TSP binary. Options:
- - `tsram` : Trusted SRAM (default option)
- - `tdram` : Trusted DRAM (if available)
- - `dram` : Secure region in DRAM (configured by the TrustZone controller)
-
-* `ARM_XLAT_TABLES_LIB_V1`: boolean option to compile the Trusted Firmware
- with version 1 of the translation tables library instead of version 2. It is
- set to 0 by default, which selects version 2.
-
-* `ARM_CRYPTOCELL_INTEG` : bool option to enable Trusted Firmware to invoke
- ARM® TrustZone® CryptoCell functionality for Trusted Board Boot on capable
- ARM platforms. If this option is specified, then the path to the CryptoCell
- SBROM library must be specified via `CCSBROM_LIB_PATH` flag.
-
-For a better understanding of these options, the ARM development platform memory
-map is explained in the [Firmware Design].
-
-#### ARM CSS platform specific build options
-
-* `CSS_DETECT_PRE_1_7_0_SCP`: Boolean flag to detect SCP version
- incompatibility. Version 1.7.0 of the SCP firmware made a non-backwards
- compatible change to the MTL protocol, used for AP/SCP communication.
- Trusted Firmware no longer supports earlier SCP versions. If this option is
- set to 1 then Trusted Firmware will detect if an earlier version is in use.
- Default is 1.
-
-* `CSS_LOAD_SCP_IMAGES`: Boolean flag, which when set, adds SCP_BL2 and
- SCP_BL2U to the FIP and FWU_FIP respectively, and enables them to be loaded
- during boot. Default is 1.
-
-* `CSS_USE_SCMI_DRIVER`: Boolean flag which selects SCMI driver instead of
- SCPI driver for communicating with the SCP during power management operations.
- If this option is set to 1, then SCMI driver will be used. Default is 0.
-
-#### ARM FVP platform specific build options
-
-* `FVP_CLUSTER_COUNT` : Configures the cluster count to be used to
- build the topology tree within Trusted Firmware. By default the
- Trusted Firmware is configured for dual cluster topology and this option
- can be used to override the default value.
-
-* `FVP_INTERCONNECT_DRIVER`: Selects the interconnect driver to be built. The
- default interconnect driver depends on the value of `FVP_CLUSTER_COUNT` as
- explained in the options below:
- - `FVP_CCI` : The CCI driver is selected. This is the default
- if 0 < `FVP_CLUSTER_COUNT` <= 2.
- - `FVP_CCN` : The CCN driver is selected. This is the default
- if `FVP_CLUSTER_COUNT` > 2.
-
-* `FVP_USE_GIC_DRIVER` : Selects the GIC driver to be built. Options:
- - `FVP_GIC600` : The GIC600 implementation of GICv3 is selected
- - `FVP_GICV2` : The GICv2 only driver is selected
- - `FVP_GICV3` : The GICv3 only driver is selected (default option)
- - `FVP_GICV3_LEGACY`: The Legacy GICv3 driver is selected (deprecated)
- Note: If Trusted Firmware is compiled with this option on FVPs with
- GICv3 hardware, then it configures the hardware to run in GICv2
- emulation mode
-
-* `FVP_USE_SP804_TIMER` : Use the SP804 timer instead of the Generic Timer
- for functions that wait for an arbitrary time length (udelay and mdelay).
- The default value is 0.
-
-### Debugging options
-
-To compile a debug version and make the build more verbose use
-
- make PLAT=<platform> DEBUG=1 V=1 all
-
-AArch64 GCC uses DWARF version 4 debugging symbols by default. Some tools (for
-example DS-5) might not support this and may need an older version of DWARF
-symbols to be emitted by GCC. This can be achieved by using the
-`-gdwarf-<version>` flag, with the version being set to 2 or 3. Setting the
-version to 2 is recommended for DS-5 versions older than 5.16.
-
-When debugging logic problems it might also be useful to disable all compiler
-optimizations by using `-O0`.
-
-NOTE: Using `-O0` could cause output images to be larger and base addresses
-might need to be recalculated (see the **Memory layout on ARM development
-platforms** section in the [Firmware Design]).
-
-Extra debug options can be passed to the build system by setting `CFLAGS` or
-`LDFLAGS`:
-
- CFLAGS='-O0 -gdwarf-2' \
- make PLAT=<platform> DEBUG=1 V=1 all
-
-Note that using `-Wl,` style compilation driver options in `CFLAGS` will be
-ignored as the linker is called directly.
-
-It is also possible to introduce an infinite loop to help in debugging the
-post-BL2 phase of the Trusted Firmware. This can be done by rebuilding BL1 with
-the `SPIN_ON_BL1_EXIT=1` build flag. Refer to the "Summary of build options"
-section. In this case, the developer may take control of the target using a
-debugger when indicated by the console output. When using DS-5, the following
-commands can be used:
-
- # Stop target execution
- interrupt
-
- #
- # Prepare your debugging environment, e.g. set breakpoints
- #
-
- # Jump over the debug loop
- set var $AARCH64::$Core::$PC = $AARCH64::$Core::$PC + 4
-
- # Resume execution
- continue
-
-
-### Building the Test Secure Payload
-
-The TSP is coupled with a companion runtime service in the BL31 firmware,
-called the TSPD. Therefore, if you intend to use the TSP, the BL31 image
-must be recompiled as well. For more information on SPs and SPDs, see the
-"Secure-EL1 Payloads and Dispatchers" section in the [Firmware Design].
-
-First clean the Trusted Firmware build directory to get rid of any previous
-BL31 binary. Then to build the TSP image use:
-
- make PLAT=<platform> SPD=tspd all
-
-An additional boot loader binary file is created in the `build` directory:
-
- build/<platform>/<build-type>/bl32.bin
-
-### Checking source code style
-
-When making changes to the source for submission to the project, the source
-must be in compliance with the Linux style guide, and to assist with this check
-the project Makefile contains two targets, which both utilise the
-`checkpatch.pl` script that ships with the Linux source tree.
-
-To check the entire source tree, you must first download a copy of
-`checkpatch.pl` (or the full Linux source), set the `CHECKPATCH` environment
-variable to point to the script and build the target checkcodebase:
-
- make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkcodebase
-
-To just check the style on the files that differ between your local branch and
-the remote master, use:
-
- make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkpatch
-
-If you wish to check your patch against something other than the remote master,
-set the `BASE_COMMIT` variable to your desired branch. By default, `BASE_COMMIT`
-is set to `origin/master`.
-
-
-### Building and using the FIP tool
-
-Firmware Image Package (FIP) is a packaging format used by the Trusted Firmware
-project to package firmware images in a single binary. The number and type of
-images that should be packed in a FIP is platform specific and may include TF
-images and other firmware images required by the platform. For example, most
-platforms require a BL33 image which corresponds to the normal world bootloader
-(e.g. UEFI or U-Boot).
-
-The TF build system provides the make target `fip` to create a FIP file for the
-specified platform using the FIP creation tool included in the TF project.
-Examples below show how to build a FIP file for FVP, packaging TF images and a
-BL33 image.
-
-For AArch64:
-
- make PLAT=fvp BL33=<path/to/bl33.bin> fip
-
-For AArch32:
-
- make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=<path/to/bl33.bin> fip
-
-Note that AArch32 support for Normal world boot loader (BL33), like U-boot or
-UEFI, on FVP is not available upstream. Hence custom solutions are required to
-allow Linux boot on FVP. These instructions assume such a custom boot loader
-(BL33) is available.
-
-The resulting FIP may be found in:
-
- build/fvp/<build-type>/fip.bin
-
-For advanced operations on FIP files, it is also possible to independently build
-the tool and create or modify FIPs using this tool. To do this, follow these
-steps:
-
-It is recommended to remove old artifacts before building the tool:
-
- make -C tools/fiptool clean
-
-Build the tool:
-
- make [DEBUG=1] [V=1] fiptool
-
-The tool binary can be located in:
-
- ./tools/fiptool/fiptool
-
-Invoking the tool with `--help` will print a help message with all available
-options.
-
-Example 1: create a new Firmware package `fip.bin` that contains BL2 and BL31:
-
- ./tools/fiptool/fiptool create \
- --tb-fw build/<platform>/<build-type>/bl2.bin \
- --soc-fw build/<platform>/<build-type>/bl31.bin \
- fip.bin
-
-Example 2: view the contents of an existing Firmware package:
-
- ./tools/fiptool/fiptool info <path-to>/fip.bin
-
-Example 3: update the entries of an existing Firmware package:
-
- # Change the BL2 from Debug to Release version
- ./tools/fiptool/fiptool update \
- --tb-fw build/<platform>/release/bl2.bin \
- build/<platform>/debug/fip.bin
-
-Example 4: unpack all entries from an existing Firmware package:
-
- # Images will be unpacked to the working directory
- ./tools/fiptool/fiptool unpack <path-to>/fip.bin
-
-Example 5: remove an entry from an existing Firmware package:
-
- ./tools/fiptool/fiptool remove \
- --tb-fw build/<platform>/debug/fip.bin
-
-Note that if the destination FIP file exists, the create, update and
-remove operations will automatically overwrite it.
-
-The unpack operation will fail if the images already exist at the
-destination. In that case, use -f or --force to continue.
-
-More information about FIP can be found in the [Firmware Design document]
-[Firmware Design].
-
-#### Migrating from fip_create to fiptool
-
-The previous version of fiptool was called fip_create. A compatibility script
-that emulates the basic functionality of the previous fip_create is provided.
-However, users are strongly encouraged to migrate to fiptool.
-
-* To create a new FIP file, replace "fip_create" with "fiptool create".
-* To update a FIP file, replace "fip_create" with "fiptool update".
-* To dump the contents of a FIP file, replace "fip_create --dump"
- with "fiptool info".
-
-### Building FIP images with support for Trusted Board Boot
-
-Trusted Board Boot primarily consists of the following two features:
-
-* Image Authentication, described in [Trusted Board Boot], and
-* Firmware Update, described in [Firmware Update]
-
-The following steps should be followed to build FIP and (optionally) FWU_FIP
-images with support for these features:
-
-1. Fulfill the dependencies of the `mbedtls` cryptographic and image parser
- modules by checking out a recent version of the [mbed TLS Repository]. It
- is important to use a version that is compatible with TF and fixes any
- known security vulnerabilities. See [mbed TLS Security Center] for more
- information. The latest version of TF is tested with tag `mbedtls-2.4.2`.
-
- The `drivers/auth/mbedtls/mbedtls_*.mk` files contain the list of mbed TLS
- source files the modules depend upon.
- `include/drivers/auth/mbedtls/mbedtls_config.h` contains the configuration
- options required to build the mbed TLS sources.
-
- Note that the mbed TLS library is licensed under the Apache version 2.0
- license. Using mbed TLS source code will affect the licensing of
- Trusted Firmware binaries that are built using this library.
-
-2. To build the FIP image, ensure the following command line variables are set
- while invoking `make` to build Trusted Firmware:
-
- * `MBEDTLS_DIR=<path of the directory containing mbed TLS sources>`
- * `TRUSTED_BOARD_BOOT=1`
- * `GENERATE_COT=1`
-
- In the case of ARM platforms, the location of the ROTPK hash must also be
- specified at build time. Two locations are currently supported (see
- `ARM_ROTPK_LOCATION` build option):
-
- * `ARM_ROTPK_LOCATION=regs`: the ROTPK hash is obtained from the Trusted
- root-key storage registers present in the platform. On Juno, this
- registers are read-only. On FVP Base and Cortex models, the registers
- are read-only, but the value can be specified using the command line
- option `bp.trusted_key_storage.public_key` when launching the model.
- On both Juno and FVP models, the default value corresponds to an
- ECDSA-SECP256R1 public key hash, whose private part is not currently
- available.
-
- * `ARM_ROTPK_LOCATION=devel_rsa`: use the ROTPK hash that is hardcoded
- in the ARM platform port. The private/public RSA key pair may be
- found in `plat/arm/board/common/rotpk`.
-
- Example of command line using RSA development keys:
-
- MBEDTLS_DIR=<path of the directory containing mbed TLS sources> \
- make PLAT=<platform> TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 \
- ARM_ROTPK_LOCATION=devel_rsa \
- ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \
- BL33=<path-to>/<bl33_image> \
- all fip
-
- The result of this build will be the bl1.bin and the fip.bin binaries. This
- FIP will include the certificates corresponding to the Chain of Trust
- described in the TBBR-client document. These certificates can also be found
- in the output build directory.
-
-3. The optional FWU_FIP contains any additional images to be loaded from
- Non-Volatile storage during the [Firmware Update] process. To build the
- FWU_FIP, any FWU images required by the platform must be specified on the
- command line. On ARM development platforms like Juno, these are:
-
- * NS_BL2U. The AP non-secure Firmware Updater image.
- * SCP_BL2U. The SCP Firmware Update Configuration image.
-
- Example of Juno command line for generating both `fwu` and `fwu_fip`
- targets using RSA development:
-
- MBEDTLS_DIR=<path of the directory containing mbed TLS sources> \
- make PLAT=juno TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 \
- ARM_ROTPK_LOCATION=devel_rsa \
- ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \
- BL33=<path-to>/<bl33_image> \
- SCP_BL2=<path-to>/<scp_bl2_image> \
- SCP_BL2U=<path-to>/<scp_bl2u_image> \
- NS_BL2U=<path-to>/<ns_bl2u_image> \
- all fip fwu_fip
-
- Note: The BL2U image will be built by default and added to the FWU_FIP.
- The user may override this by adding `BL2U=<path-to>/<bl2u_image>`
- to the command line above.
-
- Note: Building and installing the non-secure and SCP FWU images (NS_BL1U,
- NS_BL2U and SCP_BL2U) is outside the scope of this document.
-
- The result of this build will be bl1.bin, fip.bin and fwu_fip.bin binaries.
- Both the FIP and FWU_FIP will include the certificates corresponding to the
- Chain of Trust described in the TBBR-client document. These certificates
- can also be found in the output build directory.
-
-
-### Building the Certificate Generation Tool
-
-The `cert_create` tool is built as part of the TF build process when the `fip`
-make target is specified and TBB is enabled (as described in the previous
-section), but it can also be built separately with the following command:
-
- make PLAT=<platform> [DEBUG=1] [V=1] certtool
-
-For platforms that do not require their own IDs in certificate files,
-the generic 'cert_create' tool can be built with the following command:
-
- make USE_TBBR_DEFS=1 [DEBUG=1] [V=1] certtool
-
-`DEBUG=1` builds the tool in debug mode. `V=1` makes the build process more
-verbose. The following command should be used to obtain help about the tool:
-
- ./tools/cert_create/cert_create -h
-
-
-6. Building a FIP for Juno and FVP
------------------------------------
-
-This section provides Juno and FVP specific instructions to build Trusted
-Firmware, obtain the additional required firmware, and pack it all together in
-a single FIP binary. It assumes that a [Linaro Release][Linaro Release Notes]
-has been installed.
-
-Note: Linaro Release 16.06 only includes pre-built binaries for AArch64. For
-AArch32, pre-built binaries are only available from Linaro Release 16.12.
-
-Note: follow the full instructions for one platform before switching to a
-different one. Mixing instructions for different platforms may result in
-corrupted binaries.
-
-1. Clean the working directory
-
- make realclean
-
-2. Obtain SCP_BL2 (Juno) and BL33 (all platforms)
-
- Use the fiptool to extract the SCP_BL2 and BL33 images from the FIP
- package included in the Linaro release:
-
- # Build the fiptool
- make [DEBUG=1] [V=1] fiptool
-
- # Unpack firmware images from Linaro FIP
- ./tools/fiptool/fiptool unpack \
- <path/to/linaro/release>/fip.bin
-
- The unpack operation will result in a set of binary images extracted to the
- working directory. The SCP_BL2 image corresponds to `scp-fw.bin` and BL33
- corresponds to `nt-fw.bin`.
-
- Note: the fiptool will complain if the images to be unpacked already
- exist in the current directory. If that is the case, either delete those
- files or use the `--force` option to overwrite.
-
- Note for AArch32, the instructions below assume that nt-fw.bin is a custom
- Normal world boot loader that supports AArch32.
-
-3. Build TF images and create a new FIP for FVP
-
- # AArch64
- make PLAT=fvp BL33=nt-fw.bin all fip
-
- # AArch32
- make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=nt-fw.bin all fip
-
-4. Build TF images and create a new FIP for Juno
-
- For AArch64:
-
- Building for AArch64 on Juno simply requires the addition of `SCP_BL2`
- as a build parameter.
-
- make PLAT=juno all fip \
- BL33=<path-to-juno-oe-uboot>/SOFTWARE/bl33-uboot.bin \
- SCP_BL2=<path-to-juno-busybox-uboot>/SOFTWARE/scp_bl2.bin
-
- For AArch32:
-
- Hardware restrictions on Juno prevent cold reset into AArch32 execution mode,
- therefore BL1 and BL2 must be compiled for AArch64, and BL32 is compiled
- separately for AArch32.
-
- * Before building BL32, the environment variable `CROSS_COMPILE` must point
- to the AArch32 Linaro cross compiler.
-
- export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-linux-gnueabihf-
-
- * Build BL32 in AArch32.
-
- make ARCH=aarch32 PLAT=juno AARCH32_SP=sp_min \
- RESET_TO_SP_MIN=1 JUNO_AARCH32_EL3_RUNTIME=1 bl32
-
- * Before building BL1 and BL2, the environment variable `CROSS_COMPILE`
- must point to the AArch64 Linaro cross compiler.
-
- export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
-
- * The following parameters should be used to build BL1 and BL2 in AArch64
- and point to the BL32 file.
-
- make ARCH=aarch64 PLAT=juno LOAD_IMAGE_V2=1 JUNO_AARCH32_EL3_RUNTIME=1 \
- BL33=<path-to-juno32-oe-uboot>/SOFTWARE/bl33-uboot.bin \
- SCP_BL2=<path-to-juno32-oe-uboot>/SOFTWARE/scp_bl2.bin SPD=tspd \
- BL32=<path-to-bl32>/bl32.bin all fip
-
-The resulting BL1 and FIP images may be found in:
-
- # Juno
- ./build/juno/release/bl1.bin
- ./build/juno/release/fip.bin
-
- # FVP
- ./build/fvp/release/bl1.bin
- ./build/fvp/release/fip.bin
-
-
-7. EL3 payloads alternative boot flow
---------------------------------------
-
-On a pre-production system, the ability to execute arbitrary, bare-metal code at
-the highest exception level is required. It allows full, direct access to the
-hardware, for example to run silicon soak tests.
-
-Although it is possible to implement some baremetal secure firmware from
-scratch, this is a complex task on some platforms, depending on the level of
-configuration required to put the system in the expected state.
-
-Rather than booting a baremetal application, a possible compromise is to boot
-`EL3 payloads` through the Trusted Firmware instead. This is implemented as an
-alternative boot flow, where a modified BL2 boots an EL3 payload, instead of
-loading the other BL images and passing control to BL31. It reduces the
-complexity of developing EL3 baremetal code by:
-
-* putting the system into a known architectural state;
-* taking care of platform secure world initialization;
-* loading the SCP_BL2 image if required by the platform.
-
-When booting an EL3 payload on ARM standard platforms, the configuration of the
-TrustZone controller is simplified such that only region 0 is enabled and is
-configured to permit secure access only. This gives full access to the whole
-DRAM to the EL3 payload.
-
-The system is left in the same state as when entering BL31 in the default boot
-flow. In particular:
-
-* Running in EL3;
-* Current state is AArch64;
-* Little-endian data access;
-* All exceptions disabled;
-* MMU disabled;
-* Caches disabled.
-
-### Booting an EL3 payload
-
-The EL3 payload image is a standalone image and is not part of the FIP. It is
-not loaded by the Trusted Firmware. Therefore, there are 2 possible scenarios:
-
-* The EL3 payload may reside in non-volatile memory (NVM) and execute in
- place. In this case, booting it is just a matter of specifying the right
- address in NVM through `EL3_PAYLOAD_BASE` when building the TF.
-
-* The EL3 payload needs to be loaded in volatile memory (e.g. DRAM) at
- run-time.
-
-To help in the latter scenario, the `SPIN_ON_BL1_EXIT=1` build option can be
-used. The infinite loop that it introduces in BL1 stops execution at the right
-moment for a debugger to take control of the target and load the payload (for
-example, over JTAG).
-
-It is expected that this loading method will work in most cases, as a debugger
-connection is usually available in a pre-production system. The user is free to
-use any other platform-specific mechanism to load the EL3 payload, though.
-
-#### Booting an EL3 payload on FVP
-
-The EL3 payloads boot flow requires the CPU's mailbox to be cleared at reset for
-the secondary CPUs holding pen to work properly. Unfortunately, its reset value
-is undefined on the FVP platform and the FVP platform code doesn't clear it.
-Therefore, one must modify the way the model is normally invoked in order to
-clear the mailbox at start-up.
-
-One way to do that is to create an 8-byte file containing all zero bytes using
-the following command:
-
- dd if=/dev/zero of=mailbox.dat bs=1 count=8
-
-and pre-load it into the FVP memory at the mailbox address (i.e. `0x04000000`)
-using the following model parameters:
-
- --data cluster0.cpu0=mailbox.dat@0x04000000 [Base FVPs]
- --data=mailbox.dat@0x04000000 [Foundation FVP]
-
-To provide the model with the EL3 payload image, the following methods may be
-used:
-
-1. If the EL3 payload is able to execute in place, it may be programmed into
- flash memory. On Base Cortex and AEM FVPs, the following model parameter
- loads it at the base address of the NOR FLASH1 (the NOR FLASH0 is already
- used for the FIP):
-
- -C bp.flashloader1.fname="/path/to/el3-payload"
-
- On Foundation FVP, there is no flash loader component and the EL3 payload
- may be programmed anywhere in flash using method 3 below.
-
-2. When using the `SPIN_ON_BL1_EXIT=1` loading method, the following DS-5
- command may be used to load the EL3 payload ELF image over JTAG:
-
- load /path/to/el3-payload.elf
-
-3. The EL3 payload may be pre-loaded in volatile memory using the following
- model parameters:
-
- --data cluster0.cpu0="/path/to/el3-payload"@address [Base FVPs]
- --data="/path/to/el3-payload"@address [Foundation FVP]
-
- The address provided to the FVP must match the `EL3_PAYLOAD_BASE` address
- used when building the Trusted Firmware.
-
-#### Booting an EL3 payload on Juno
-
-If the EL3 payload is able to execute in place, it may be programmed in flash
-memory by adding an entry in the `SITE1/HBI0262x/images.txt` configuration file
-on the Juno SD card (where `x` depends on the revision of the Juno board).
-Refer to the [Juno Getting Started Guide], section 2.3 "Flash memory
-programming" for more information.
-
-Alternatively, the same DS-5 command mentioned in the FVP section above can
-be used to load the EL3 payload's ELF file over JTAG on Juno.
-
-
-8. Preloaded BL33 alternative boot flow
-----------------------------------------
-
-Some platforms have the ability to preload BL33 into memory instead of relying
-on Trusted Firmware to load it. This may simplify packaging of the normal world
-code and improve performance in a development environment. When secure world
-cold boot is complete, Trusted Firmware simply jumps to a BL33 base address
-provided at build time.
-
-For this option to be used, the `PRELOADED_BL33_BASE` build option has to be
-used when compiling the Trusted Firmware. For example, the following command
-will create a FIP without a BL33 and prepare to jump to a BL33 image loaded at
-address 0x80000000:
-
- make PRELOADED_BL33_BASE=0x80000000 PLAT=fvp all fip
-
-#### Boot of a preloaded bootwrapped kernel image on Base FVP
-
-The following example uses the AArch64 boot wrapper. This simplifies normal
-world booting while also making use of TF features. It can be obtained from its
-repository with:
-
- git clone git://git.kernel.org/pub/scm/linux/kernel/git/mark/boot-wrapper-aarch64.git
-
-After compiling it, an ELF file is generated. It can be loaded with the
-following command:
-
- <path-to>/FVP_Base_AEMv8A-AEMv8A \
- -C bp.secureflashloader.fname=bl1.bin \
- -C bp.flashloader0.fname=fip.bin \
- -a cluster0.cpu0=<bootwrapped-kernel.elf> \
- --start cluster0.cpu0=0x0
-
-The `-a cluster0.cpu0=<bootwrapped-kernel.elf>` option loads the ELF file. It
-also sets the PC register to the ELF entry point address, which is not the
-desired behaviour, so the `--start cluster0.cpu0=0x0` option forces the PC back
-to 0x0 (the BL1 entry point address) on CPU #0. The `PRELOADED_BL33_BASE` define
-used when compiling the FIP must match the ELF entry point.
-
-#### Boot of a preloaded bootwrapped kernel image on Juno
-
-The procedure to obtain and compile the boot wrapper is very similar to the case
-of the FVP. The execution must be stopped at the end of bl2_main(), and the
-loading method explained above in the EL3 payload boot flow section may be used
-to load the ELF file over JTAG on Juno.
-
-
-9. Running the software on FVP
--------------------------------
-
-The latest version of the AArch64 build of ARM Trusted Firmware has been tested
-on the following ARM FVPs (64-bit host machine only).
-
-* `Foundation_Platform` (Version 10.2, Build 10.2.20)
-* `FVP_Base_AEMv8A-AEMv8A` (Version 8.4, Build 0.8.8402)
-* `FVP_Base_Cortex-A57x4-A53x4` (Version 8.4, Build 0.8.8402)
-
-The latest version of the AArch32 build of ARM Trusted Firmware has been tested
-on the following ARM FVPs (64-bit host machine only).
-
-* `FVP_Base_AEMv8A-AEMv8A` (Version 8.4, Build 0.8.8402)
-* `FVP_Base_Cortex-A32x4` (Version 10.1, Build 10.1.32)
-
-NOTE: The build numbers quoted above are those reported by launching the FVP
-with the `--version` parameter.
-
-NOTE: The software will not work on Version 1.0 of the Foundation FVP.
-The commands below would report an `unhandled argument` error in this case.
-
-NOTE: FVPs can be launched with `--cadi-server` option such that a
-CADI-compliant debugger (for example, ARM DS-5) can connect to and control its
-execution.
-
-The Foundation FVP is a cut down version of the AArch64 Base FVP. It can be
-downloaded for free from [ARM's website][ARM FVP website].
-
-Please refer to the FVP documentation for a detailed description of the model
-parameter options. A brief description of the important ones that affect the ARM
-Trusted Firmware and normal world software behavior is provided below.
-
-Note the instructions in the following sections assume that Linaro Release 16.06
-is being used.
-
-### Obtaining the Flattened Device Trees
-
-Depending on the FVP configuration and Linux configuration used, different
-FDT files are required. FDTs for the Foundation and Base FVPs can be found in
-the Trusted Firmware source directory under `fdts/`. The Foundation FVP has a
-subset of the Base FVP components. For example, the Foundation FVP lacks CLCD
-and MMC support, and has only one CPU cluster.
-
-Note: It is not recommended to use the FDTs built along the kernel because not
-all FDTs are available from there.
-
-* `fvp-base-gicv2-psci.dtb`
-
- For use with both AEMv8 and Cortex-A57-A53 Base FVPs with
- Base memory map configuration.
-
-* `fvp-base-gicv2-psci-aarch32.dtb`
-
- For use with AEMv8 and Cortex-A32 Base FVPs running Linux in AArch32 state
- with Base memory map configuration.
-
-* `fvp-base-gicv3-psci.dtb`
-
- (Default) For use with both AEMv8 and Cortex-A57-A53 Base FVPs with Base
- memory map configuration and Linux GICv3 support.
-
-* `fvp-base-gicv3-psci-aarch32.dtb`
-
- For use with AEMv8 and Cortex-A32 Base FVPs running Linux in AArch32 state
- with Base memory map configuration and Linux GICv3 support.
-
-* `fvp-foundation-gicv2-psci.dtb`
-
- For use with Foundation FVP with Base memory map configuration.
-
-* `fvp-foundation-gicv3-psci.dtb`
-
- (Default) For use with Foundation FVP with Base memory map configuration
- and Linux GICv3 support.
-
-### Running on the Foundation FVP with reset to BL1 entrypoint
-
-The following `Foundation_Platform` parameters should be used to boot Linux with
-4 CPUs using the AArch64 build of ARM Trusted Firmware.
-
- <path-to>/Foundation_Platform \
- --cores=4 \
- --secure-memory \
- --visualization \
- --gicv3 \
- --data="<path-to>/<bl1-binary>"@0x0 \
- --data="<path-to>/<FIP-binary>"@0x08000000 \
- --data="<path-to>/<fdt>"@0x83000000 \
- --data="<path-to>/<kernel-binary>"@0x80080000 \
- --block-device="<path-to>/<file-system-image>"
-
-Notes:
-* BL1 is loaded at the start of the Trusted ROM.
-* The Firmware Image Package is loaded at the start of NOR FLASH0.
-* The Linux kernel image and device tree are loaded in DRAM.
-* The default use-case for the Foundation FVP is to use the `--gicv3` option
- and enable the GICv3 device in the model. Note that without this option,
- the Foundation FVP defaults to legacy (Versatile Express) memory map which
- is not supported by ARM Trusted Firmware.
-
-### Running on the AEMv8 Base FVP with reset to BL1 entrypoint
-
-The following `FVP_Base_AEMv8A-AEMv8A` parameters should be used to boot Linux
-with 8 CPUs using the AArch64 build of ARM Trusted Firmware.
-
- <path-to>/FVP_Base_AEMv8A-AEMv8A \
- -C pctl.startup=0.0.0.0 \
- -C bp.secure_memory=1 \
- -C bp.tzc_400.diagnostics=1 \
- -C cluster0.NUM_CORES=4 \
- -C cluster1.NUM_CORES=4 \
- -C cache_state_modelled=1 \
- -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \
- -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \
- --data cluster0.cpu0="<path-to>/<fdt>"@0x83000000 \
- --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
- -C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>"
-
-### Running on the AEMv8 Base FVP (AArch32) with reset to BL1 entrypoint
-
-The following `FVP_Base_AEMv8A-AEMv8A` parameters should be used to boot Linux
-with 8 CPUs using the AArch32 build of ARM Trusted Firmware.
-
- <path-to>/FVP_Base_AEMv8A-AEMv8A \
- -C pctl.startup=0.0.0.0 \
- -C bp.secure_memory=1 \
- -C bp.tzc_400.diagnostics=1 \
- -C cluster0.NUM_CORES=4 \
- -C cluster1.NUM_CORES=4 \
- -C cache_state_modelled=1 \
- -C cluster0.cpu0.CONFIG64=0 \
- -C cluster0.cpu1.CONFIG64=0 \
- -C cluster0.cpu2.CONFIG64=0 \
- -C cluster0.cpu3.CONFIG64=0 \
- -C cluster1.cpu0.CONFIG64=0 \
- -C cluster1.cpu1.CONFIG64=0 \
- -C cluster1.cpu2.CONFIG64=0 \
- -C cluster1.cpu3.CONFIG64=0 \
- -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \
- -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \
- --data cluster0.cpu0="<path-to>/<fdt>"@0x83000000 \
- --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
- -C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>"
-
-### Running on the Cortex-A57-A53 Base FVP with reset to BL1 entrypoint
-
-The following `FVP_Base_Cortex-A57x4-A53x4` model parameters should be used to
-boot Linux with 8 CPUs using the AArch64 build of ARM Trusted Firmware.
-
- <path-to>/FVP_Base_Cortex-A57x4-A53x4 \
- -C pctl.startup=0.0.0.0 \
- -C bp.secure_memory=1 \
- -C bp.tzc_400.diagnostics=1 \
- -C cache_state_modelled=1 \
- -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \
- -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \
- --data cluster0.cpu0="<path-to>/<fdt>"@0x83000000 \
- --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
- -C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>"
-
-### Running on the Cortex-A32 Base FVP (AArch32) with reset to BL1 entrypoint
-
-The following `FVP_Base_Cortex-A32x4` model parameters should be used to
-boot Linux with 4 CPUs using the AArch32 build of ARM Trusted Firmware.
-
- <path-to>/FVP_Base_Cortex-A32x4 \
- -C pctl.startup=0.0.0.0 \
- -C bp.secure_memory=1 \
- -C bp.tzc_400.diagnostics=1 \
- -C cache_state_modelled=1 \
- -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \
- -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \
- --data cluster0.cpu0="<path-to>/<fdt>"@0x83000000 \
- --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
- -C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>"
-
-### Running on the AEMv8 Base FVP with reset to BL31 entrypoint
-
-The following `FVP_Base_AEMv8A-AEMv8A` parameters should be used to boot Linux
-with 8 CPUs using the AArch64 build of ARM Trusted Firmware.
-
- <path-to>/FVP_Base_AEMv8A-AEMv8A \
- -C pctl.startup=0.0.0.0 \
- -C bp.secure_memory=1 \
- -C bp.tzc_400.diagnostics=1 \
- -C cluster0.NUM_CORES=4 \
- -C cluster1.NUM_CORES=4 \
- -C cache_state_modelled=1 \
- -C cluster0.cpu0.RVBAR=0x04023000 \
- -C cluster0.cpu1.RVBAR=0x04023000 \
- -C cluster0.cpu2.RVBAR=0x04023000 \
- -C cluster0.cpu3.RVBAR=0x04023000 \
- -C cluster1.cpu0.RVBAR=0x04023000 \
- -C cluster1.cpu1.RVBAR=0x04023000 \
- -C cluster1.cpu2.RVBAR=0x04023000 \
- -C cluster1.cpu3.RVBAR=0x04023000 \
- --data cluster0.cpu0="<path-to>/<bl31-binary>"@0x04023000 \
- --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04001000 \
- --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \
- --data cluster0.cpu0="<path-to>/<fdt>"@0x83000000 \
- --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
- -C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>"
-
-Notes:
-
-* Since a FIP is not loaded when using BL31 as reset entrypoint, the
- `--data="<path-to><bl31|bl32|bl33-binary>"@<base-address-of-binary>`
- parameter is needed to load the individual bootloader images in memory.
- BL32 image is only needed if BL31 has been built to expect a Secure-EL1
- Payload.
-
-* The `-C cluster<X>.cpu<Y>.RVBAR=@<base-address-of-bl31>` parameter, where
- X and Y are the cluster and CPU numbers respectively, is used to set the
- reset vector for each core.
-
-* Changing the default value of `ARM_TSP_RAM_LOCATION` will also require
- changing the value of
- `--data="<path-to><bl32-binary>"@<base-address-of-bl32>` to the new value of
- `BL32_BASE`.
-
-### Running on the AEMv8 Base FVP (AArch32) with reset to SP_MIN entrypoint
-
-The following `FVP_Base_AEMv8A-AEMv8A` parameters should be used to boot Linux
-with 8 CPUs using the AArch32 build of ARM Trusted Firmware.
-
- <path-to>/FVP_Base_AEMv8A-AEMv8A \
- -C pctl.startup=0.0.0.0 \
- -C bp.secure_memory=1 \
- -C bp.tzc_400.diagnostics=1 \
- -C cluster0.NUM_CORES=4 \
- -C cluster1.NUM_CORES=4 \
- -C cache_state_modelled=1 \
- -C cluster0.cpu0.CONFIG64=0 \
- -C cluster0.cpu1.CONFIG64=0 \
- -C cluster0.cpu2.CONFIG64=0 \
- -C cluster0.cpu3.CONFIG64=0 \
- -C cluster1.cpu0.CONFIG64=0 \
- -C cluster1.cpu1.CONFIG64=0 \
- -C cluster1.cpu2.CONFIG64=0 \
- -C cluster1.cpu3.CONFIG64=0 \
- -C cluster0.cpu0.RVBAR=0x04001000 \
- -C cluster0.cpu1.RVBAR=0x04001000 \
- -C cluster0.cpu2.RVBAR=0x04001000 \
- -C cluster0.cpu3.RVBAR=0x04001000 \
- -C cluster1.cpu0.RVBAR=0x04001000 \
- -C cluster1.cpu1.RVBAR=0x04001000 \
- -C cluster1.cpu2.RVBAR=0x04001000 \
- -C cluster1.cpu3.RVBAR=0x04001000 \
- --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04001000 \
- --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \
- --data cluster0.cpu0="<path-to>/<fdt>"@0x83000000 \
- --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
- -C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>"
-
-Note: The load address of `<bl32-binary>` depends on the value `BL32_BASE`.
-It should match the address programmed into the RVBAR register as well.
-
-### Running on the Cortex-A57-A53 Base FVP with reset to BL31 entrypoint
-
-The following `FVP_Base_Cortex-A57x4-A53x4` model parameters should be used to
-boot Linux with 8 CPUs using the AArch64 build of ARM Trusted Firmware.
-
- <path-to>/FVP_Base_Cortex-A57x4-A53x4 \
- -C pctl.startup=0.0.0.0 \
- -C bp.secure_memory=1 \
- -C bp.tzc_400.diagnostics=1 \
- -C cache_state_modelled=1 \
- -C cluster0.cpu0.RVBARADDR=0x04023000 \
- -C cluster0.cpu1.RVBARADDR=0x04023000 \
- -C cluster0.cpu2.RVBARADDR=0x04023000 \
- -C cluster0.cpu3.RVBARADDR=0x04023000 \
- -C cluster1.cpu0.RVBARADDR=0x04023000 \
- -C cluster1.cpu1.RVBARADDR=0x04023000 \
- -C cluster1.cpu2.RVBARADDR=0x04023000 \
- -C cluster1.cpu3.RVBARADDR=0x04023000 \
- --data cluster0.cpu0="<path-to>/<bl31-binary>"@0x04023000 \
- --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04001000 \
- --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \
- --data cluster0.cpu0="<path-to>/<fdt>"@0x83000000 \
- --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
- -C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>"
-
-### Running on the Cortex-A32 Base FVP (AArch32) with reset to SP_MIN entrypoint
-
-The following `FVP_Base_Cortex-A32x4` model parameters should be used to
-boot Linux with 4 CPUs using the AArch32 build of ARM Trusted Firmware.
-
- <path-to>/FVP_Base_Cortex-A32x4 \
- -C pctl.startup=0.0.0.0 \
- -C bp.secure_memory=1 \
- -C bp.tzc_400.diagnostics=1 \
- -C cache_state_modelled=1 \
- -C cluster0.cpu0.RVBARADDR=0x04001000 \
- -C cluster0.cpu1.RVBARADDR=0x04001000 \
- -C cluster0.cpu2.RVBARADDR=0x04001000 \
- -C cluster0.cpu3.RVBARADDR=0x04001000 \
- --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04001000 \
- --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \
- --data cluster0.cpu0="<path-to>/<fdt>"@0x83000000 \
- --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
- -C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>"
-
-10. Running the software on Juno
----------------------------------
-
-This version of the ARM Trusted Firmware has been tested on Juno r0 and Juno r1.
-
-To execute the software stack on Juno, the version of the Juno board recovery
-image indicated in the [Linaro Release Notes] must be installed. If you have an
-earlier version installed or are unsure which version is installed, please
-re-install the recovery image by following the [Instructions for using Linaro's
-deliverables on Juno][Juno Instructions].
-
-### Preparing Trusted Firmware images
-
-After building Trusted Firmware, the files `bl1.bin` and `fip.bin` need copying
-to the `SOFTWARE/` directory of the Juno SD card.
-
-### Other Juno software information
-
-Please visit the [ARM Platforms Portal] to get support and obtain any other Juno
-software information. Please also refer to the [Juno Getting Started Guide] to
-get more detailed information about the Juno ARM development platform and how to
-configure it.
-
-### Testing SYSTEM SUSPEND on Juno
-
-The SYSTEM SUSPEND is a PSCI API which can be used to implement system suspend
-to RAM. For more details refer to section 5.16 of [PSCI]. To test system suspend
-on Juno, at the linux shell prompt, issue the following command:
-
- echo +10 > /sys/class/rtc/rtc0/wakealarm
- echo -n mem > /sys/power/state
-
-The Juno board should suspend to RAM and then wakeup after 10 seconds due to
-wakeup interrupt from RTC.
-
-
-- - - - - - - - - - - - - - - - - - - - - - - - - -
-
-_Copyright (c) 2013-2017, ARM Limited and Contributors. All rights reserved._
-
-
-[Firmware Design]: firmware-design.md
-[ARM FVP website]: https://developer.arm.com/products/system-design/fixed-virtual-platforms
-[Linaro Release Notes]: https://community.arm.com/tools/dev-platforms/b/documents/posts/linaro-release-notes-deprecated
-[ARM Platforms Portal]: https://community.arm.com/groups/arm-development-platforms
-[Linaro SW Instructions]: https://community.arm.com/dev-platforms/b/documents/posts/instructions-for-using-the-linaro-software-deliverables
-[Juno Instructions]: https://community.arm.com/dev-platforms/b/documents/posts/using-linaros-deliverables-on-juno
-[Juno Getting Started Guide]: http://infocenter.arm.com/help/topic/com.arm.doc.dui0928e/DUI0928E_juno_arm_development_platform_gsg.pdf
-[DS-5]: http://www.arm.com/products/tools/software-tools/ds-5/index.php
-[mbed TLS Repository]: https://github.com/ARMmbed/mbedtls.git
-[mbed TLS Security Center]: https://tls.mbed.org/security
-[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)"
-[Trusted Board Boot]: trusted-board-boot.md
-[Firmware Update]: ./firmware-update.md
-[PSCI Lib Integration]: ./psci-lib-integration-guide.md
diff --git a/docs/user-guide.rst b/docs/user-guide.rst
new file mode 100644
index 0000000..6b82e3d
--- /dev/null
+++ b/docs/user-guide.rst
@@ -0,0 +1,1752 @@
+ARM Trusted Firmware User Guide
+===============================
+
+
+.. section-numbering::
+ :suffix: .
+
+.. contents::
+
+This document describes how to build ARM Trusted Firmware (TF) and run it with a
+tested set of other software components using defined configurations on the Juno
+ARM development platform and ARM Fixed Virtual Platform (FVP) models. It is
+possible to use other software components, configurations and platforms but that
+is outside the scope of this document.
+
+This document assumes that the reader has previous experience running a fully
+bootable Linux software stack on Juno or FVP using the prebuilt binaries and
+filesystems provided by `Linaro`_. Further information may be found in the
+`Linaro instructions`_. It also assumes that the user understands the role of
+the different software components required to boot a Linux system:
+
+- Specific firmware images required by the platform (e.g. SCP firmware on Juno)
+- Normal world bootloader (e.g. UEFI or U-Boot)
+- Device tree
+- Linux kernel image
+- Root filesystem
+
+This document also assumes that the user is familiar with the `FVP models`_ and
+the different command line options available to launch the model.
+
+This document should be used in conjunction with the `Firmware Design`_.
+
+Host machine requirements
+-------------------------
+
+The minimum recommended machine specification for building the software and
+running the FVP models is a dual-core processor running at 2GHz with 12GB of
+RAM. For best performance, use a machine with a quad-core processor running at
+2.6GHz with 16GB of RAM.
+
+The software has been tested on Ubuntu 14.04 LTS (64-bit). Packages used for
+building the software were installed from that distribution unless otherwise
+specified.
+
+The software has also been built on Windows 7 Enterprise SP1, using CMD.EXE,
+Cygwin, and Msys (MinGW) shells, using version 5.3.1 of the GNU toolchain.
+
+Tools
+-----
+
+Install the required packages to build Trusted Firmware with the following
+command:
+
+::
+
+ sudo apt-get install build-essential gcc make git libssl-dev
+
+ARM TF has been tested with `Linaro Release 17.04`_.
+
+Download and install the AArch32 or AArch64 little-endian GCC cross compiler.
+The `Linaro Release Notes`_ documents which version of the compiler to use for a
+given Linaro Release. Also, these `Linaro instructions`_ provide further
+guidance and a script, which can be used to download Linaro deliverables
+automatically.
+
+Optionally, Trusted Firmware can be built using clang or ARM Compiler 6.
+See instructions below on how to switch the default compiler.
+
+In addition, the following optional packages and tools may be needed:
+
+- ``device-tree-compiler`` package if you need to rebuild the Flattened Device
+ Tree (FDT) source files (``.dts`` files) provided with this software.
+
+- For debugging, ARM `Development Studio 5 (DS-5)`_.
+
+Getting the Trusted Firmware source code
+----------------------------------------
+
+Download the Trusted Firmware source code from Github:
+
+::
+
+ git clone https://github.com/ARM-software/arm-trusted-firmware.git
+
+Building the Trusted Firmware
+-----------------------------
+
+- Before building Trusted Firmware, the environment variable ``CROSS_COMPILE``
+ must point to the Linaro cross compiler.
+
+ For AArch64:
+
+ ::
+
+ export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
+
+ For AArch32:
+
+ ::
+
+ export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-linux-gnueabihf-
+
+ It is possible to build Trusted Firmware using clang or ARM Compiler 6.
+ To do so ``CC`` needs to point to the clang or armclang binary. Only the
+ compiler is switched; the assembler and linker need to be provided by
+ the GNU toolchain, thus ``CROSS_COMPILE`` should be set as described above.
+
+ ARM Compiler 6 will be selected when the base name of the path assigned
+ to ``CC`` matches the string 'armclang'.
+
+ For AArch64 using ARM Compiler 6:
+
+ ::
+
+ export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
+ make CC=<path-to-armclang>/bin/armclang PLAT=<platform> all
+
+ Clang will be selected when the base name of the path assigned to ``CC``
+ contains the string 'clang'. This is to allow both clang and clang-X.Y
+ to work.
+
+ For AArch64 using clang:
+
+ ::
+
+ export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
+ make CC=<path-to-clang>/bin/clang PLAT=<platform> all
+
+- Change to the root directory of the Trusted Firmware source tree and build.
+
+ For AArch64:
+
+ ::
+
+ make PLAT=<platform> all
+
+ For AArch32:
+
+ ::
+
+ make PLAT=<platform> ARCH=aarch32 AARCH32_SP=sp_min all
+
+ Notes:
+
+ - If ``PLAT`` is not specified, ``fvp`` is assumed by default. See the
+ `Summary of build options`_ for more information on available build
+ options.
+
+ - (AArch32 only) Currently only ``PLAT=fvp`` is supported.
+
+ - (AArch32 only) ``AARCH32_SP`` is the AArch32 EL3 Runtime Software and it
+ corresponds to the BL32 image. A minimal ``AARCH32_SP``, sp\_min, is
+ provided by ARM Trusted Firmware to demonstrate how PSCI Library can
+ be integrated with an AArch32 EL3 Runtime Software. Some AArch32 EL3
+ Runtime Software may include other runtime services, for example
+ Trusted OS services. A guide to integrate PSCI library with AArch32
+ EL3 Runtime Software can be found `here`_.
+
+ - (AArch64 only) The TSP (Test Secure Payload), corresponding to the BL32
+ image, is not compiled in by default. Refer to the
+ `Building the Test Secure Payload`_ section below.
+
+ - By default this produces a release version of the build. To produce a
+ debug version instead, refer to the "Debugging options" section below.
+
+ - The build process creates products in a ``build`` directory tree, building
+ the objects and binaries for each boot loader stage in separate
+ sub-directories. The following boot loader binary files are created
+ from the corresponding ELF files:
+
+ - ``build/<platform>/<build-type>/bl1.bin``
+ - ``build/<platform>/<build-type>/bl2.bin``
+ - ``build/<platform>/<build-type>/bl31.bin`` (AArch64 only)
+ - ``build/<platform>/<build-type>/bl32.bin`` (mandatory for AArch32)
+
+ where ``<platform>`` is the name of the chosen platform and ``<build-type>``
+ is either ``debug`` or ``release``. The actual number of images might differ
+ depending on the platform.
+
+- Build products for a specific build variant can be removed using:
+
+ ::
+
+ make DEBUG=<D> PLAT=<platform> clean
+
+ ... where ``<D>`` is ``0`` or ``1``, as specified when building.
+
+ The build tree can be removed completely using:
+
+ ::
+
+ make realclean
+
+Summary of build options
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+ARM Trusted Firmware build system supports the following build options. Unless
+mentioned otherwise, these options are expected to be specified at the build
+command line and are not to be modified in any component makefiles. Note that
+the build system doesn't track dependency for build options. Therefore, if any
+of the build options are changed from a previous build, a clean build must be
+performed.
+
+Common build options
+^^^^^^^^^^^^^^^^^^^^
+
+- ``AARCH32_SP`` : Choose the AArch32 Secure Payload component to be built as
+ as the BL32 image when ``ARCH=aarch32``. The value should be the path to the
+ directory containing the SP source, relative to the ``bl32/``; the directory
+ is expected to contain a makefile called ``<aarch32_sp-value>.mk``.
+
+- ``ARCH`` : Choose the target build architecture for ARM Trusted Firmware.
+ It can take either ``aarch64`` or ``aarch32`` as values. By default, it is
+ defined to ``aarch64``.
+
+- ``ARM_CCI_PRODUCT_ID``: Choice of ARM CCI product used by the platform. This
+ is used to determine the number of valid slave interfaces available in the
+ ARM CCI driver. Default is 400 (that is, CCI-400).
+
+- ``ARM_ARCH_MAJOR``: The major version of ARM Architecture to target when
+ compiling ARM Trusted Firmware. Its value must be numeric, and defaults to
+ 8 . See also, *ARMv8 Architecture Extensions* in `Firmware Design`_.
+
+- ``ARM_ARCH_MINOR``: The minor version of ARM Architecture to target when
+ compiling ARM Trusted Firmware. Its value must be a numeric, and defaults
+ to 0. See also, *ARMv8 Architecture Extensions* in `Firmware Design`_.
+
+- ``ARM_GIC_ARCH``: Choice of ARM GIC architecture version used by the ARM
+ Legacy GIC driver for implementing the platform GIC API. This API is used
+ by the interrupt management framework. Default is 2 (that is, version 2.0).
+ This build option is deprecated.
+
+- ``ARM_PLAT_MT``: This flag determines whether the ARM platform layer has to
+ cater for the multi-threading ``MT`` bit when accessing MPIDR. When this
+ flag is set, the functions which deal with MPIDR assume that the ``MT`` bit
+ in MPIDR is set and access the bit-fields in MPIDR accordingly. Default
+ value of this flag is 0.
+
+- ``BL2``: This is an optional build option which specifies the path to BL2
+ image for the ``fip`` target. In this case, the BL2 in the ARM Trusted
+ Firmware will not be built.
+
+- ``BL2U``: This is an optional build option which specifies the path to
+ BL2U image. In this case, the BL2U in the ARM Trusted Firmware will not
+ be built.
+
+- ``BL31``: This is an optional build option which specifies the path to
+ BL31 image for the ``fip`` target. In this case, the BL31 in the ARM
+ Trusted Firmware will not be built.
+
+- ``BL31_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the
+ file that contains the BL31 private key in PEM format. If ``SAVE_KEYS=1``,
+ this file name will be used to save the key.
+
+- ``BL32``: This is an optional build option which specifies the path to
+ BL32 image for the ``fip`` target. In this case, the BL32 in the ARM
+ Trusted Firmware will not be built.
+
+- ``BL32_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the
+ file that contains the BL32 private key in PEM format. If ``SAVE_KEYS=1``,
+ this file name will be used to save the key.
+
+- ``BL33``: Path to BL33 image in the host file system. This is mandatory for
+ ``fip`` target in case the BL2 from ARM Trusted Firmware is used.
+
+- ``BL33_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the
+ file that contains the BL33 private key in PEM format. If ``SAVE_KEYS=1``,
+ this file name will be used to save the key.
+
+- ``BUILD_MESSAGE_TIMESTAMP``: String used to identify the time and date of the
+ compilation of each build. It must be set to a C string (including quotes
+ where applicable). Defaults to a string that contains the time and date of
+ the compilation.
+
+- ``BUILD_STRING``: Input string for VERSION\_STRING, which allows the TF build
+ to be uniquely identified. Defaults to the current git commit id.
+
+- ``CFLAGS``: Extra user options appended on the compiler's command line in
+ addition to the options set by the build system.
+
+- ``COLD_BOOT_SINGLE_CPU``: This option indicates whether the platform may
+ release several CPUs out of reset. It can take either 0 (several CPUs may be
+ brought up) or 1 (only one CPU will ever be brought up during cold reset).
+ Default is 0. If the platform always brings up a single CPU, there is no
+ need to distinguish between primary and secondary CPUs and the boot path can
+ be optimised. The ``plat_is_my_cpu_primary()`` and
+ ``plat_secondary_cold_boot_setup()`` platform porting interfaces do not need
+ to be implemented in this case.
+
+- ``CRASH_REPORTING``: A non-zero value enables a console dump of processor
+ register state when an unexpected exception occurs during execution of
+ BL31. This option defaults to the value of ``DEBUG`` - i.e. by default
+ this is only enabled for a debug build of the firmware.
+
+- ``CREATE_KEYS``: This option is used when ``GENERATE_COT=1``. It tells the
+ certificate generation tool to create new keys in case no valid keys are
+ present or specified. Allowed options are '0' or '1'. Default is '1'.
+
+- ``CTX_INCLUDE_AARCH32_REGS`` : Boolean option that, when set to 1, will cause
+ the AArch32 system registers to be included when saving and restoring the
+ CPU context. The option must be set to 0 for AArch64-only platforms (that
+ is on hardware that does not implement AArch32, or at least not at EL1 and
+ higher ELs). Default value is 1.
+
+- ``CTX_INCLUDE_FPREGS``: Boolean option that, when set to 1, will cause the FP
+ registers to be included when saving and restoring the CPU context. Default
+ is 0.
+
+- ``DEBUG``: Chooses between a debug and release build. It can take either 0
+ (release) or 1 (debug) as values. 0 is the default.
+
+- ``EL3_PAYLOAD_BASE``: This option enables booting an EL3 payload instead of
+ the normal boot flow. It must specify the entry point address of the EL3
+ payload. Please refer to the "Booting an EL3 payload" section for more
+ details.
+
+- ``ENABLE_ASSERTIONS``: This option controls whether or not calls to ``assert()``
+ are compiled out. For debug builds, this option defaults to 1, and calls to
+ ``assert()`` are left in place. For release builds, this option defaults to 0
+ and calls to ``assert()`` function are compiled out. This option can be set
+ independently of ``DEBUG``. It can also be used to hide any auxiliary code
+ that is only required for the assertion and does not fit in the assertion
+ itself.
+
+- ``ENABLE_PMF``: Boolean option to enable support for optional Performance
+ Measurement Framework(PMF). Default is 0.
+
+- ``ENABLE_PSCI_STAT``: Boolean option to enable support for optional PSCI
+ functions ``PSCI_STAT_RESIDENCY`` and ``PSCI_STAT_COUNT``. Default is 0.
+ In the absence of an alternate stat collection backend, ``ENABLE_PMF`` must
+ be enabled. If ``ENABLE_PMF`` is set, the residency statistics are tracked in
+ software.
+
+- ``ENABLE_RUNTIME_INSTRUMENTATION``: Boolean option to enable runtime
+ instrumentation which injects timestamp collection points into
+ Trusted Firmware to allow runtime performance to be measured.
+ Currently, only PSCI is instrumented. Enabling this option enables
+ the ``ENABLE_PMF`` build option as well. Default is 0.
+
+- ``ENABLE_STACK_PROTECTOR``: String option to enable the stack protection
+ checks in GCC. Allowed values are "all", "strong" and "0" (default).
+ "strong" is the recommended stack protection level if this feature is
+ desired. 0 disables the stack protection. For all values other than 0, the
+ ``plat_get_stack_protector_canary()`` platform hook needs to be implemented.
+ The value is passed as the last component of the option
+ ``-fstack-protector-$ENABLE_STACK_PROTECTOR``.
+
+- ``ERROR_DEPRECATED``: This option decides whether to treat the usage of
+ deprecated platform APIs, helper functions or drivers within Trusted
+ Firmware as error. It can take the value 1 (flag the use of deprecated
+ APIs as error) or 0. The default is 0.
+
+- ``FIP_NAME``: This is an optional build option which specifies the FIP
+ filename for the ``fip`` target. Default is ``fip.bin``.
+
+- ``FWU_FIP_NAME``: This is an optional build option which specifies the FWU
+ FIP filename for the ``fwu_fip`` target. Default is ``fwu_fip.bin``.
+
+- ``GENERATE_COT``: Boolean flag used to build and execute the ``cert_create``
+ tool to create certificates as per the Chain of Trust described in
+ `Trusted Board Boot`_. The build system then calls ``fiptool`` to
+ include the certificates in the FIP and FWU\_FIP. Default value is '0'.
+
+ Specify both ``TRUSTED_BOARD_BOOT=1`` and ``GENERATE_COT=1`` to include support
+ for the Trusted Board Boot feature in the BL1 and BL2 images, to generate
+ the corresponding certificates, and to include those certificates in the
+ FIP and FWU\_FIP.
+
+ Note that if ``TRUSTED_BOARD_BOOT=0`` and ``GENERATE_COT=1``, the BL1 and BL2
+ images will not include support for Trusted Board Boot. The FIP will still
+ include the corresponding certificates. This FIP can be used to verify the
+ Chain of Trust on the host machine through other mechanisms.
+
+ Note that if ``TRUSTED_BOARD_BOOT=1`` and ``GENERATE_COT=0``, the BL1 and BL2
+ images will include support for Trusted Board Boot, but the FIP and FWU\_FIP
+ will not include the corresponding certificates, causing a boot failure.
+
+- ``HANDLE_EA_EL3_FIRST``: When defined External Aborts and SError Interrupts
+ will be always trapped in EL3 i.e. in BL31 at runtime.
+
+- ``HW_ASSISTED_COHERENCY``: On most ARM systems to-date, platform-specific
+ software operations are required for CPUs to enter and exit coherency.
+ However, there exists newer systems where CPUs' entry to and exit from
+ coherency is managed in hardware. Such systems require software to only
+ initiate the operations, and the rest is managed in hardware, minimizing
+ active software management. In such systems, this boolean option enables ARM
+ Trusted Firmware to carry out build and run-time optimizations during boot
+ and power management operations. This option defaults to 0 and if it is
+ enabled, then it implies ``WARMBOOT_ENABLE_DCACHE_EARLY`` is also enabled.
+
+- ``JUNO_AARCH32_EL3_RUNTIME``: This build flag enables you to execute EL3
+ runtime software in AArch32 mode, which is required to run AArch32 on Juno.
+ By default this flag is set to '0'. Enabling this flag builds BL1 and BL2 in
+ AArch64 and facilitates the loading of ``SP_MIN`` and BL33 as AArch32 executable
+ images.
+
+- ``LDFLAGS``: Extra user options appended to the linkers' command line in
+ addition to the one set by the build system.
+
+- ``LOAD_IMAGE_V2``: Boolean option to enable support for new version (v2) of
+ image loading, which provides more flexibility and scalability around what
+ images are loaded and executed during boot. Default is 0.
+ Note: ``TRUSTED_BOARD_BOOT`` is currently only supported for AArch64 when
+ ``LOAD_IMAGE_V2`` is enabled.
+
+- ``LOG_LEVEL``: Chooses the log level, which controls the amount of console log
+ output compiled into the build. This should be one of the following:
+
+ ::
+
+ 0 (LOG_LEVEL_NONE)
+ 10 (LOG_LEVEL_NOTICE)
+ 20 (LOG_LEVEL_ERROR)
+ 30 (LOG_LEVEL_WARNING)
+ 40 (LOG_LEVEL_INFO)
+ 50 (LOG_LEVEL_VERBOSE)
+
+ All log output up to and including the log level is compiled into the build.
+ The default value is 40 in debug builds and 20 in release builds.
+
+- ``NON_TRUSTED_WORLD_KEY``: This option is used when ``GENERATE_COT=1``. It
+ specifies the file that contains the Non-Trusted World private key in PEM
+ format. If ``SAVE_KEYS=1``, this file name will be used to save the key.
+
+- ``NS_BL2U``: Path to NS\_BL2U image in the host file system. This image is
+ optional. It is only needed if the platform makefile specifies that it
+ is required in order to build the ``fwu_fip`` target.
+
+- ``NS_TIMER_SWITCH``: Enable save and restore for non-secure timer register
+ contents upon world switch. It can take either 0 (don't save and restore) or
+ 1 (do save and restore). 0 is the default. An SPD may set this to 1 if it
+ wants the timer registers to be saved and restored.
+
+- ``PL011_GENERIC_UART``: Boolean option to indicate the PL011 driver that
+ the underlying hardware is not a full PL011 UART but a minimally compliant
+ generic UART, which is a subset of the PL011. The driver will not access
+ any register that is not part of the SBSA generic UART specification.
+ Default value is 0 (a full PL011 compliant UART is present).
+
+- ``PLAT``: Choose a platform to build ARM Trusted Firmware for. The chosen
+ platform name must be subdirectory of any depth under ``plat/``, and must
+ contain a platform makefile named ``platform.mk``. For example to build ARM
+ Trusted Firmware for ARM Juno board select PLAT=juno.
+
+- ``PRELOADED_BL33_BASE``: This option enables booting a preloaded BL33 image
+ instead of the normal boot flow. When defined, it must specify the entry
+ point address for the preloaded BL33 image. This option is incompatible with
+ ``EL3_PAYLOAD_BASE``. If both are defined, ``EL3_PAYLOAD_BASE`` has priority
+ over ``PRELOADED_BL33_BASE``.
+
+- ``PROGRAMMABLE_RESET_ADDRESS``: This option indicates whether the reset
+ vector address can be programmed or is fixed on the platform. It can take
+ either 0 (fixed) or 1 (programmable). Default is 0. If the platform has a
+ programmable reset address, it is expected that a CPU will start executing
+ code directly at the right address, both on a cold and warm reset. In this
+ case, there is no need to identify the entrypoint on boot and the boot path
+ can be optimised. The ``plat_get_my_entrypoint()`` platform porting interface
+ does not need to be implemented in this case.
+
+- ``PSCI_EXTENDED_STATE_ID``: As per PSCI1.0 Specification, there are 2 formats
+ possible for the PSCI power-state parameter viz original and extended
+ State-ID formats. This flag if set to 1, configures the generic PSCI layer
+ to use the extended format. The default value of this flag is 0, which
+ means by default the original power-state format is used by the PSCI
+ implementation. This flag should be specified by the platform makefile
+ and it governs the return value of PSCI\_FEATURES API for CPU\_SUSPEND
+ smc function id. When this option is enabled on ARM platforms, the
+ option ``ARM_RECOM_STATE_ID_ENC`` needs to be set to 1 as well.
+
+- ``RESET_TO_BL31``: Enable BL31 entrypoint as the CPU reset vector instead
+ of the BL1 entrypoint. It can take the value 0 (CPU reset to BL1
+ entrypoint) or 1 (CPU reset to BL31 entrypoint).
+ The default value is 0.
+
+- ``RESET_TO_SP_MIN``: SP\_MIN is the minimal AArch32 Secure Payload provided in
+ ARM Trusted Firmware. This flag configures SP\_MIN entrypoint as the CPU
+ reset vector instead of the BL1 entrypoint. It can take the value 0 (CPU
+ reset to BL1 entrypoint) or 1 (CPU reset to SP\_MIN entrypoint). The default
+ value is 0.
+
+- ``ROT_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the
+ file that contains the ROT private key in PEM format. If ``SAVE_KEYS=1``, this
+ file name will be used to save the key.
+
+- ``SAVE_KEYS``: This option is used when ``GENERATE_COT=1``. It tells the
+ certificate generation tool to save the keys used to establish the Chain of
+ Trust. Allowed options are '0' or '1'. Default is '0' (do not save).
+
+- ``SCP_BL2``: Path to SCP\_BL2 image in the host file system. This image is optional.
+ If a SCP\_BL2 image is present then this option must be passed for the ``fip``
+ target.
+
+- ``SCP_BL2_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the
+ file that contains the SCP\_BL2 private key in PEM format. If ``SAVE_KEYS=1``,
+ this file name will be used to save the key.
+
+- ``SCP_BL2U``: Path to SCP\_BL2U image in the host file system. This image is
+ optional. It is only needed if the platform makefile specifies that it
+ is required in order to build the ``fwu_fip`` target.
+
+- ``SEPARATE_CODE_AND_RODATA``: Whether code and read-only data should be
+ isolated on separate memory pages. This is a trade-off between security and
+ memory usage. See "Isolating code and read-only data on separate memory
+ pages" section in `Firmware Design`_. This flag is disabled by default and
+ affects all BL images.
+
+- ``SPD``: Choose a Secure Payload Dispatcher component to be built into the
+ Trusted Firmware. This build option is only valid if ``ARCH=aarch64``. The
+ value should be the path to the directory containing the SPD source,
+ relative to ``services/spd/``; the directory is expected to
+ contain a makefile called ``<spd-value>.mk``.
+
+- ``SPIN_ON_BL1_EXIT``: This option introduces an infinite loop in BL1. It can
+ take either 0 (no loop) or 1 (add a loop). 0 is the default. This loop stops
+ execution in BL1 just before handing over to BL31. At this point, all
+ firmware images have been loaded in memory, and the MMU and caches are
+ turned off. Refer to the "Debugging options" section for more details.
+
+- ``TRUSTED_BOARD_BOOT``: Boolean flag to include support for the Trusted Board
+ Boot feature. When set to '1', BL1 and BL2 images include support to load
+ and verify the certificates and images in a FIP, and BL1 includes support
+ for the Firmware Update. The default value is '0'. Generation and inclusion
+ of certificates in the FIP and FWU\_FIP depends upon the value of the
+ ``GENERATE_COT`` option.
+
+ Note: This option depends on ``CREATE_KEYS`` to be enabled. If the keys
+ already exist in disk, they will be overwritten without further notice.
+
+- ``TRUSTED_WORLD_KEY``: This option is used when ``GENERATE_COT=1``. It
+ specifies the file that contains the Trusted World private key in PEM
+ format. If ``SAVE_KEYS=1``, this file name will be used to save the key.
+
+- ``TSP_INIT_ASYNC``: Choose BL32 initialization method as asynchronous or
+ synchronous, (see "Initializing a BL32 Image" section in
+ `Firmware Design`_). It can take the value 0 (BL32 is initialized using
+ synchronous method) or 1 (BL32 is initialized using asynchronous method).
+ Default is 0.
+
+- ``TSP_NS_INTR_ASYNC_PREEMPT``: A non zero value enables the interrupt
+ routing model which routes non-secure interrupts asynchronously from TSP
+ to EL3 causing immediate preemption of TSP. The EL3 is responsible
+ for saving and restoring the TSP context in this routing model. The
+ default routing model (when the value is 0) is to route non-secure
+ interrupts to TSP allowing it to save its context and hand over
+ synchronously to EL3 via an SMC.
+
+- ``USE_COHERENT_MEM``: This flag determines whether to include the coherent
+ memory region in the BL memory map or not (see "Use of Coherent memory in
+ Trusted Firmware" section in `Firmware Design`_). It can take the value 1
+ (Coherent memory region is included) or 0 (Coherent memory region is
+ excluded). Default is 1.
+
+- ``V``: Verbose build. If assigned anything other than 0, the build commands
+ are printed. Default is 0.
+
+- ``VERSION_STRING``: String used in the log output for each TF image. Defaults
+ to a string formed by concatenating the version number, build type and build
+ string.
+
+- ``WARMBOOT_ENABLE_DCACHE_EARLY`` : Boolean option to enable D-cache early on
+ the CPU after warm boot. This is applicable for platforms which do not
+ require interconnect programming to enable cache coherency (eg: single
+ cluster platforms). If this option is enabled, then warm boot path
+ enables D-caches immediately after enabling MMU. This option defaults to 0.
+
+- ``ENABLE_SPE_FOR_LOWER_ELS`` : Boolean option to enable Statistical Profiling
+ extensions. This is an optional architectural feature available only for
+ AArch64 8.2 onwards. This option defaults to 1 but is automatically
+ disabled when the target architecture is AArch32 or AArch64 8.0/8.1.
+
+ARM development platform specific build options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- ``ARM_BL31_IN_DRAM``: Boolean option to select loading of BL31 in TZC secured
+ DRAM. By default, BL31 is in the secure SRAM. Set this flag to 1 to load
+ BL31 in TZC secured DRAM. If TSP is present, then setting this option also
+ sets the TSP location to DRAM and ignores the ``ARM_TSP_RAM_LOCATION`` build
+ flag.
+
+- ``ARM_BOARD_OPTIMISE_MEM``: Boolean option to enable or disable optimisation
+ of the memory reserved for each image. This affects the maximum size of each
+ BL image as well as the number of allocated memory regions and translation
+ tables. By default this flag is 0, which means it uses the default
+ unoptimised values for these macros. ARM development platforms that wish to
+ optimise memory usage need to set this flag to 1 and must override the
+ related macros.
+
+- ``ARM_CONFIG_CNTACR``: boolean option to unlock access to the ``CNTBase<N>``
+ frame registers by setting the ``CNTCTLBase.CNTACR<N>`` register bits. The
+ frame number ``<N>`` is defined by ``PLAT_ARM_NSTIMER_FRAME_ID``, which should
+ match the frame used by the Non-Secure image (normally the Linux kernel).
+ Default is true (access to the frame is allowed).
+
+- ``ARM_DISABLE_TRUSTED_WDOG``: boolean option to disable the Trusted Watchdog.
+ By default, ARM platforms use a watchdog to trigger a system reset in case
+ an error is encountered during the boot process (for example, when an image
+ could not be loaded or authenticated). The watchdog is enabled in the early
+ platform setup hook at BL1 and disabled in the BL1 prepare exit hook. The
+ Trusted Watchdog may be disabled at build time for testing or development
+ purposes.
+
+- ``ARM_RECOM_STATE_ID_ENC``: The PSCI1.0 specification recommends an encoding
+ for the construction of composite state-ID in the power-state parameter.
+ The existing PSCI clients currently do not support this encoding of
+ State-ID yet. Hence this flag is used to configure whether to use the
+ recommended State-ID encoding or not. The default value of this flag is 0,
+ in which case the platform is configured to expect NULL in the State-ID
+ field of power-state parameter.
+
+- ``ARM_ROTPK_LOCATION``: used when ``TRUSTED_BOARD_BOOT=1``. It specifies the
+ location of the ROTPK hash returned by the function ``plat_get_rotpk_info()``
+ for ARM platforms. Depending on the selected option, the proper private key
+ must be specified using the ``ROT_KEY`` option when building the Trusted
+ Firmware. This private key will be used by the certificate generation tool
+ to sign the BL2 and Trusted Key certificates. Available options for
+ ``ARM_ROTPK_LOCATION`` are:
+
+ - ``regs`` : return the ROTPK hash stored in the Trusted root-key storage
+ registers. The private key corresponding to this ROTPK hash is not
+ currently available.
+ - ``devel_rsa`` : return a development public key hash embedded in the BL1
+ and BL2 binaries. This hash has been obtained from the RSA public key
+ ``arm_rotpk_rsa.der``, located in ``plat/arm/board/common/rotpk``. To use
+ this option, ``arm_rotprivk_rsa.pem`` must be specified as ``ROT_KEY`` when
+ creating the certificates.
+
+- ``ARM_TSP_RAM_LOCATION``: location of the TSP binary. Options:
+
+ - ``tsram`` : Trusted SRAM (default option)
+ - ``tdram`` : Trusted DRAM (if available)
+ - ``dram`` : Secure region in DRAM (configured by the TrustZone controller)
+
+- ``ARM_XLAT_TABLES_LIB_V1``: boolean option to compile the Trusted Firmware
+ with version 1 of the translation tables library instead of version 2. It is
+ set to 0 by default, which selects version 2.
+
+- ``ARM_CRYPTOCELL_INTEG`` : bool option to enable Trusted Firmware to invoke
+ ARM® TrustZone® CryptoCell functionality for Trusted Board Boot on capable
+ ARM platforms. If this option is specified, then the path to the CryptoCell
+ SBROM library must be specified via ``CCSBROM_LIB_PATH`` flag.
+
+For a better understanding of these options, the ARM development platform memory
+map is explained in the `Firmware Design`_.
+
+ARM CSS platform specific build options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- ``CSS_DETECT_PRE_1_7_0_SCP``: Boolean flag to detect SCP version
+ incompatibility. Version 1.7.0 of the SCP firmware made a non-backwards
+ compatible change to the MTL protocol, used for AP/SCP communication.
+ Trusted Firmware no longer supports earlier SCP versions. If this option is
+ set to 1 then Trusted Firmware will detect if an earlier version is in use.
+ Default is 1.
+
+- ``CSS_LOAD_SCP_IMAGES``: Boolean flag, which when set, adds SCP\_BL2 and
+ SCP\_BL2U to the FIP and FWU\_FIP respectively, and enables them to be loaded
+ during boot. Default is 1.
+
+- ``CSS_USE_SCMI_DRIVER``: Boolean flag which selects SCMI driver instead of
+ SCPI driver for communicating with the SCP during power management operations.
+ If this option is set to 1, then SCMI driver will be used. Default is 0.
+
+ARM FVP platform specific build options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- ``FVP_CLUSTER_COUNT`` : Configures the cluster count to be used to
+ build the topology tree within Trusted Firmware. By default the
+ Trusted Firmware is configured for dual cluster topology and this option
+ can be used to override the default value.
+
+- ``FVP_INTERCONNECT_DRIVER``: Selects the interconnect driver to be built. The
+ default interconnect driver depends on the value of ``FVP_CLUSTER_COUNT`` as
+ explained in the options below:
+
+ - ``FVP_CCI`` : The CCI driver is selected. This is the default
+ if 0 < ``FVP_CLUSTER_COUNT`` <= 2.
+ - ``FVP_CCN`` : The CCN driver is selected. This is the default
+ if ``FVP_CLUSTER_COUNT`` > 2.
+
+- ``FVP_USE_GIC_DRIVER`` : Selects the GIC driver to be built. Options:
+
+ - ``FVP_GIC600`` : The GIC600 implementation of GICv3 is selected
+ - ``FVP_GICV2`` : The GICv2 only driver is selected
+ - ``FVP_GICV3`` : The GICv3 only driver is selected (default option)
+ - ``FVP_GICV3_LEGACY``: The Legacy GICv3 driver is selected (deprecated)
+ Note: If Trusted Firmware is compiled with this option on FVPs with
+ GICv3 hardware, then it configures the hardware to run in GICv2
+ emulation mode
+
+- ``FVP_USE_SP804_TIMER`` : Use the SP804 timer instead of the Generic Timer
+ for functions that wait for an arbitrary time length (udelay and mdelay).
+ The default value is 0.
+
+Debugging options
+~~~~~~~~~~~~~~~~~
+
+To compile a debug version and make the build more verbose use
+
+::
+
+ make PLAT=<platform> DEBUG=1 V=1 all
+
+AArch64 GCC uses DWARF version 4 debugging symbols by default. Some tools (for
+example DS-5) might not support this and may need an older version of DWARF
+symbols to be emitted by GCC. This can be achieved by using the
+``-gdwarf-<version>`` flag, with the version being set to 2 or 3. Setting the
+version to 2 is recommended for DS-5 versions older than 5.16.
+
+When debugging logic problems it might also be useful to disable all compiler
+optimizations by using ``-O0``.
+
+NOTE: Using ``-O0`` could cause output images to be larger and base addresses
+might need to be recalculated (see the **Memory layout on ARM development
+platforms** section in the `Firmware Design`_).
+
+Extra debug options can be passed to the build system by setting ``CFLAGS`` or
+``LDFLAGS``:
+
+.. code:: makefile
+
+ CFLAGS='-O0 -gdwarf-2' \
+ make PLAT=<platform> DEBUG=1 V=1 all
+
+Note that using ``-Wl,`` style compilation driver options in ``CFLAGS`` will be
+ignored as the linker is called directly.
+
+It is also possible to introduce an infinite loop to help in debugging the
+post-BL2 phase of the Trusted Firmware. This can be done by rebuilding BL1 with
+the ``SPIN_ON_BL1_EXIT=1`` build flag. Refer to the `Summary of build options`_
+section. In this case, the developer may take control of the target using a
+debugger when indicated by the console output. When using DS-5, the following
+commands can be used:
+
+::
+
+ # Stop target execution
+ interrupt
+
+ #
+ # Prepare your debugging environment, e.g. set breakpoints
+ #
+
+ # Jump over the debug loop
+ set var $AARCH64::$Core::$PC = $AARCH64::$Core::$PC + 4
+
+ # Resume execution
+ continue
+
+Building the Test Secure Payload
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The TSP is coupled with a companion runtime service in the BL31 firmware,
+called the TSPD. Therefore, if you intend to use the TSP, the BL31 image
+must be recompiled as well. For more information on SPs and SPDs, see the
+`Secure-EL1 Payloads and Dispatchers`_ section in the `Firmware Design`_.
+
+First clean the Trusted Firmware build directory to get rid of any previous
+BL31 binary. Then to build the TSP image use:
+
+::
+
+ make PLAT=<platform> SPD=tspd all
+
+An additional boot loader binary file is created in the ``build`` directory:
+
+::
+
+ build/<platform>/<build-type>/bl32.bin
+
+Checking source code style
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When making changes to the source for submission to the project, the source
+must be in compliance with the Linux style guide, and to assist with this check
+the project Makefile contains two targets, which both utilise the
+``checkpatch.pl`` script that ships with the Linux source tree.
+
+To check the entire source tree, you must first download a copy of
+``checkpatch.pl`` (or the full Linux source), set the ``CHECKPATCH`` environment
+variable to point to the script and build the target checkcodebase:
+
+::
+
+ make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkcodebase
+
+To just check the style on the files that differ between your local branch and
+the remote master, use:
+
+::
+
+ make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkpatch
+
+If you wish to check your patch against something other than the remote master,
+set the ``BASE_COMMIT`` variable to your desired branch. By default, ``BASE_COMMIT``
+is set to ``origin/master``.
+
+Building and using the FIP tool
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Firmware Image Package (FIP) is a packaging format used by the Trusted Firmware
+project to package firmware images in a single binary. The number and type of
+images that should be packed in a FIP is platform specific and may include TF
+images and other firmware images required by the platform. For example, most
+platforms require a BL33 image which corresponds to the normal world bootloader
+(e.g. UEFI or U-Boot).
+
+The TF build system provides the make target ``fip`` to create a FIP file for the
+specified platform using the FIP creation tool included in the TF project.
+Examples below show how to build a FIP file for FVP, packaging TF images and a
+BL33 image.
+
+For AArch64:
+
+::
+
+ make PLAT=fvp BL33=<path/to/bl33.bin> fip
+
+For AArch32:
+
+::
+
+ make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=<path/to/bl33.bin> fip
+
+Note that AArch32 support for Normal world boot loader (BL33), like U-boot or
+UEFI, on FVP is not available upstream. Hence custom solutions are required to
+allow Linux boot on FVP. These instructions assume such a custom boot loader
+(BL33) is available.
+
+The resulting FIP may be found in:
+
+::
+
+ build/fvp/<build-type>/fip.bin
+
+For advanced operations on FIP files, it is also possible to independently build
+the tool and create or modify FIPs using this tool. To do this, follow these
+steps:
+
+It is recommended to remove old artifacts before building the tool:
+
+::
+
+ make -C tools/fiptool clean
+
+Build the tool:
+
+::
+
+ make [DEBUG=1] [V=1] fiptool
+
+The tool binary can be located in:
+
+::
+
+ ./tools/fiptool/fiptool
+
+Invoking the tool with ``--help`` will print a help message with all available
+options.
+
+Example 1: create a new Firmware package ``fip.bin`` that contains BL2 and BL31:
+
+::
+
+ ./tools/fiptool/fiptool create \
+ --tb-fw build/<platform>/<build-type>/bl2.bin \
+ --soc-fw build/<platform>/<build-type>/bl31.bin \
+ fip.bin
+
+Example 2: view the contents of an existing Firmware package:
+
+::
+
+ ./tools/fiptool/fiptool info <path-to>/fip.bin
+
+Example 3: update the entries of an existing Firmware package:
+
+::
+
+ # Change the BL2 from Debug to Release version
+ ./tools/fiptool/fiptool update \
+ --tb-fw build/<platform>/release/bl2.bin \
+ build/<platform>/debug/fip.bin
+
+Example 4: unpack all entries from an existing Firmware package:
+
+::
+
+ # Images will be unpacked to the working directory
+ ./tools/fiptool/fiptool unpack <path-to>/fip.bin
+
+Example 5: remove an entry from an existing Firmware package:
+
+::
+
+ ./tools/fiptool/fiptool remove \
+ --tb-fw build/<platform>/debug/fip.bin
+
+Note that if the destination FIP file exists, the create, update and
+remove operations will automatically overwrite it.
+
+The unpack operation will fail if the images already exist at the
+destination. In that case, use -f or --force to continue.
+
+More information about FIP can be found in the `Firmware Design`_ document.
+
+Migrating from fip\_create to fiptool
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The previous version of fiptool was called fip\_create. A compatibility script
+that emulates the basic functionality of the previous fip\_create is provided.
+However, users are strongly encouraged to migrate to fiptool.
+
+- To create a new FIP file, replace "fip\_create" with "fiptool create".
+- To update a FIP file, replace "fip\_create" with "fiptool update".
+- To dump the contents of a FIP file, replace "fip\_create --dump"
+ with "fiptool info".
+
+Building FIP images with support for Trusted Board Boot
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Trusted Board Boot primarily consists of the following two features:
+
+- Image Authentication, described in `Trusted Board Boot`_, and
+- Firmware Update, described in `Firmware Update`_
+
+The following steps should be followed to build FIP and (optionally) FWU\_FIP
+images with support for these features:
+
+#. Fulfill the dependencies of the ``mbedtls`` cryptographic and image parser
+ modules by checking out a recent version of the `mbed TLS Repository`_. It
+ is important to use a version that is compatible with TF and fixes any
+ known security vulnerabilities. See `mbed TLS Security Center`_ for more
+ information. The latest version of TF is tested with tag ``mbedtls-2.4.2``.
+
+ The ``drivers/auth/mbedtls/mbedtls_*.mk`` files contain the list of mbed TLS
+ source files the modules depend upon.
+ ``include/drivers/auth/mbedtls/mbedtls_config.h`` contains the configuration
+ options required to build the mbed TLS sources.
+
+ Note that the mbed TLS library is licensed under the Apache version 2.0
+ license. Using mbed TLS source code will affect the licensing of
+ Trusted Firmware binaries that are built using this library.
+
+#. To build the FIP image, ensure the following command line variables are set
+ while invoking ``make`` to build Trusted Firmware:
+
+ - ``MBEDTLS_DIR=<path of the directory containing mbed TLS sources>``
+ - ``TRUSTED_BOARD_BOOT=1``
+ - ``GENERATE_COT=1``
+
+ In the case of ARM platforms, the location of the ROTPK hash must also be
+ specified at build time. Two locations are currently supported (see
+ ``ARM_ROTPK_LOCATION`` build option):
+
+ - ``ARM_ROTPK_LOCATION=regs``: the ROTPK hash is obtained from the Trusted
+ root-key storage registers present in the platform. On Juno, this
+ registers are read-only. On FVP Base and Cortex models, the registers
+ are read-only, but the value can be specified using the command line
+ option ``bp.trusted_key_storage.public_key`` when launching the model.
+ On both Juno and FVP models, the default value corresponds to an
+ ECDSA-SECP256R1 public key hash, whose private part is not currently
+ available.
+
+ - ``ARM_ROTPK_LOCATION=devel_rsa``: use the ROTPK hash that is hardcoded
+ in the ARM platform port. The private/public RSA key pair may be
+ found in ``plat/arm/board/common/rotpk``.
+
+ Example of command line using RSA development keys:
+
+ ::
+
+ MBEDTLS_DIR=<path of the directory containing mbed TLS sources> \
+ make PLAT=<platform> TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 \
+ ARM_ROTPK_LOCATION=devel_rsa \
+ ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \
+ BL33=<path-to>/<bl33_image> \
+ all fip
+
+ The result of this build will be the bl1.bin and the fip.bin binaries. This
+ FIP will include the certificates corresponding to the Chain of Trust
+ described in the TBBR-client document. These certificates can also be found
+ in the output build directory.
+
+#. The optional FWU\_FIP contains any additional images to be loaded from
+ Non-Volatile storage during the `Firmware Update`_ process. To build the
+ FWU\_FIP, any FWU images required by the platform must be specified on the
+ command line. On ARM development platforms like Juno, these are:
+
+ - NS\_BL2U. The AP non-secure Firmware Updater image.
+ - SCP\_BL2U. The SCP Firmware Update Configuration image.
+
+ Example of Juno command line for generating both ``fwu`` and ``fwu_fip``
+ targets using RSA development:
+
+ ::
+
+ MBEDTLS_DIR=<path of the directory containing mbed TLS sources> \
+ make PLAT=juno TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 \
+ ARM_ROTPK_LOCATION=devel_rsa \
+ ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \
+ BL33=<path-to>/<bl33_image> \
+ SCP_BL2=<path-to>/<scp_bl2_image> \
+ SCP_BL2U=<path-to>/<scp_bl2u_image> \
+ NS_BL2U=<path-to>/<ns_bl2u_image> \
+ all fip fwu_fip
+
+ Note: The BL2U image will be built by default and added to the FWU\_FIP.
+ The user may override this by adding ``BL2U=<path-to>/<bl2u_image>``
+ to the command line above.
+
+ Note: Building and installing the non-secure and SCP FWU images (NS\_BL1U,
+ NS\_BL2U and SCP\_BL2U) is outside the scope of this document.
+
+ The result of this build will be bl1.bin, fip.bin and fwu\_fip.bin binaries.
+ Both the FIP and FWU\_FIP will include the certificates corresponding to the
+ Chain of Trust described in the TBBR-client document. These certificates
+ can also be found in the output build directory.
+
+Building the Certificate Generation Tool
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``cert_create`` tool is built as part of the TF build process when the ``fip``
+make target is specified and TBB is enabled (as described in the previous
+section), but it can also be built separately with the following command:
+
+::
+
+ make PLAT=<platform> [DEBUG=1] [V=1] certtool
+
+For platforms that do not require their own IDs in certificate files,
+the generic 'cert\_create' tool can be built with the following command:
+
+::
+
+ make USE_TBBR_DEFS=1 [DEBUG=1] [V=1] certtool
+
+``DEBUG=1`` builds the tool in debug mode. ``V=1`` makes the build process more
+verbose. The following command should be used to obtain help about the tool:
+
+::
+
+ ./tools/cert_create/cert_create -h
+
+Building a FIP for Juno and FVP
+-------------------------------
+
+This section provides Juno and FVP specific instructions to build Trusted
+Firmware, obtain the additional required firmware, and pack it all together in
+a single FIP binary. It assumes that a `Linaro Release`_ has been installed.
+
+Note: Pre-built binaries for AArch32 are available from Linaro Release 16.12
+onwards. Before that release, pre-built binaries are only available for AArch64.
+
+Note: follow the full instructions for one platform before switching to a
+different one. Mixing instructions for different platforms may result in
+corrupted binaries.
+
+#. Clean the working directory
+
+ ::
+
+ make realclean
+
+#. Obtain SCP\_BL2 (Juno) and BL33 (all platforms)
+
+ Use the fiptool to extract the SCP\_BL2 and BL33 images from the FIP
+ package included in the Linaro release:
+
+ ::
+
+ # Build the fiptool
+ make [DEBUG=1] [V=1] fiptool
+
+ # Unpack firmware images from Linaro FIP
+ ./tools/fiptool/fiptool unpack \
+ <path/to/linaro/release>/fip.bin
+
+ The unpack operation will result in a set of binary images extracted to the
+ current working directory. The SCP\_BL2 image corresponds to
+ ``scp-fw.bin`` and BL33 corresponds to ``nt-fw.bin``.
+
+ Note: the fiptool will complain if the images to be unpacked already
+ exist in the current directory. If that is the case, either delete those
+ files or use the ``--force`` option to overwrite.
+
+ Note for AArch32, the instructions below assume that nt-fw.bin is a custom
+ Normal world boot loader that supports AArch32.
+
+#. Build TF images and create a new FIP for FVP
+
+ ::
+
+ # AArch64
+ make PLAT=fvp BL33=nt-fw.bin all fip
+
+ # AArch32
+ make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=nt-fw.bin all fip
+
+#. Build TF images and create a new FIP for Juno
+
+ For AArch64:
+
+ Building for AArch64 on Juno simply requires the addition of ``SCP_BL2``
+ as a build parameter.
+
+ ::
+
+ make PLAT=juno all fip \
+ BL33=<path-to-juno-oe-uboot>/SOFTWARE/bl33-uboot.bin \
+ SCP_BL2=<path-to-juno-busybox-uboot>/SOFTWARE/scp_bl2.bin
+
+ For AArch32:
+
+ Hardware restrictions on Juno prevent cold reset into AArch32 execution mode,
+ therefore BL1 and BL2 must be compiled for AArch64, and BL32 is compiled
+ separately for AArch32.
+
+ - Before building BL32, the environment variable ``CROSS_COMPILE`` must point
+ to the AArch32 Linaro cross compiler.
+
+ ::
+
+ export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-linux-gnueabihf-
+
+ - Build BL32 in AArch32.
+
+ ::
+
+ make ARCH=aarch32 PLAT=juno AARCH32_SP=sp_min \
+ RESET_TO_SP_MIN=1 JUNO_AARCH32_EL3_RUNTIME=1 bl32
+
+ - Before building BL1 and BL2, the environment variable ``CROSS_COMPILE``
+ must point to the AArch64 Linaro cross compiler.
+
+ ::
+
+ export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
+
+ - The following parameters should be used to build BL1 and BL2 in AArch64
+ and point to the BL32 file.
+
+ ::
+
+ make ARCH=aarch64 PLAT=juno LOAD_IMAGE_V2=1 JUNO_AARCH32_EL3_RUNTIME=1 \
+ BL33=<path-to-juno32-oe-uboot>/SOFTWARE/bl33-uboot.bin \
+ SCP_BL2=<path-to-juno32-oe-uboot>/SOFTWARE/scp_bl2.bin SPD=tspd \
+ BL32=<path-to-bl32>/bl32.bin all fip
+
+The resulting BL1 and FIP images may be found in:
+
+::
+
+ # Juno
+ ./build/juno/release/bl1.bin
+ ./build/juno/release/fip.bin
+
+ # FVP
+ ./build/fvp/release/bl1.bin
+ ./build/fvp/release/fip.bin
+
+EL3 payloads alternative boot flow
+----------------------------------
+
+On a pre-production system, the ability to execute arbitrary, bare-metal code at
+the highest exception level is required. It allows full, direct access to the
+hardware, for example to run silicon soak tests.
+
+Although it is possible to implement some baremetal secure firmware from
+scratch, this is a complex task on some platforms, depending on the level of
+configuration required to put the system in the expected state.
+
+Rather than booting a baremetal application, a possible compromise is to boot
+``EL3 payloads`` through the Trusted Firmware instead. This is implemented as an
+alternative boot flow, where a modified BL2 boots an EL3 payload, instead of
+loading the other BL images and passing control to BL31. It reduces the
+complexity of developing EL3 baremetal code by:
+
+- putting the system into a known architectural state;
+- taking care of platform secure world initialization;
+- loading the SCP\_BL2 image if required by the platform.
+
+When booting an EL3 payload on ARM standard platforms, the configuration of the
+TrustZone controller is simplified such that only region 0 is enabled and is
+configured to permit secure access only. This gives full access to the whole
+DRAM to the EL3 payload.
+
+The system is left in the same state as when entering BL31 in the default boot
+flow. In particular:
+
+- Running in EL3;
+- Current state is AArch64;
+- Little-endian data access;
+- All exceptions disabled;
+- MMU disabled;
+- Caches disabled.
+
+Booting an EL3 payload
+~~~~~~~~~~~~~~~~~~~~~~
+
+The EL3 payload image is a standalone image and is not part of the FIP. It is
+not loaded by the Trusted Firmware. Therefore, there are 2 possible scenarios:
+
+- The EL3 payload may reside in non-volatile memory (NVM) and execute in
+ place. In this case, booting it is just a matter of specifying the right
+ address in NVM through ``EL3_PAYLOAD_BASE`` when building the TF.
+
+- The EL3 payload needs to be loaded in volatile memory (e.g. DRAM) at
+ run-time.
+
+To help in the latter scenario, the ``SPIN_ON_BL1_EXIT=1`` build option can be
+used. The infinite loop that it introduces in BL1 stops execution at the right
+moment for a debugger to take control of the target and load the payload (for
+example, over JTAG).
+
+It is expected that this loading method will work in most cases, as a debugger
+connection is usually available in a pre-production system. The user is free to
+use any other platform-specific mechanism to load the EL3 payload, though.
+
+Booting an EL3 payload on FVP
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The EL3 payloads boot flow requires the CPU's mailbox to be cleared at reset for
+the secondary CPUs holding pen to work properly. Unfortunately, its reset value
+is undefined on the FVP platform and the FVP platform code doesn't clear it.
+Therefore, one must modify the way the model is normally invoked in order to
+clear the mailbox at start-up.
+
+One way to do that is to create an 8-byte file containing all zero bytes using
+the following command:
+
+::
+
+ dd if=/dev/zero of=mailbox.dat bs=1 count=8
+
+and pre-load it into the FVP memory at the mailbox address (i.e. ``0x04000000``)
+using the following model parameters:
+
+::
+
+ --data cluster0.cpu0=mailbox.dat@0x04000000 [Base FVPs]
+ --data=mailbox.dat@0x04000000 [Foundation FVP]
+
+To provide the model with the EL3 payload image, the following methods may be
+used:
+
+#. If the EL3 payload is able to execute in place, it may be programmed into
+ flash memory. On Base Cortex and AEM FVPs, the following model parameter
+ loads it at the base address of the NOR FLASH1 (the NOR FLASH0 is already
+ used for the FIP):
+
+ ::
+
+ -C bp.flashloader1.fname="/path/to/el3-payload"
+
+ On Foundation FVP, there is no flash loader component and the EL3 payload
+ may be programmed anywhere in flash using method 3 below.
+
+#. When using the ``SPIN_ON_BL1_EXIT=1`` loading method, the following DS-5
+ command may be used to load the EL3 payload ELF image over JTAG:
+
+ ::
+
+ load /path/to/el3-payload.elf
+
+#. The EL3 payload may be pre-loaded in volatile memory using the following
+ model parameters:
+
+ ::
+
+ --data cluster0.cpu0="/path/to/el3-payload"@address [Base FVPs]
+ --data="/path/to/el3-payload"@address [Foundation FVP]
+
+ The address provided to the FVP must match the ``EL3_PAYLOAD_BASE`` address
+ used when building the Trusted Firmware.
+
+Booting an EL3 payload on Juno
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If the EL3 payload is able to execute in place, it may be programmed in flash
+memory by adding an entry in the ``SITE1/HBI0262x/images.txt`` configuration file
+on the Juno SD card (where ``x`` depends on the revision of the Juno board).
+Refer to the `Juno Getting Started Guide`_, section 2.3 "Flash memory
+programming" for more information.
+
+Alternatively, the same DS-5 command mentioned in the FVP section above can
+be used to load the EL3 payload's ELF file over JTAG on Juno.
+
+Preloaded BL33 alternative boot flow
+------------------------------------
+
+Some platforms have the ability to preload BL33 into memory instead of relying
+on Trusted Firmware to load it. This may simplify packaging of the normal world
+code and improve performance in a development environment. When secure world
+cold boot is complete, Trusted Firmware simply jumps to a BL33 base address
+provided at build time.
+
+For this option to be used, the ``PRELOADED_BL33_BASE`` build option has to be
+used when compiling the Trusted Firmware. For example, the following command
+will create a FIP without a BL33 and prepare to jump to a BL33 image loaded at
+address 0x80000000:
+
+::
+
+ make PRELOADED_BL33_BASE=0x80000000 PLAT=fvp all fip
+
+Boot of a preloaded bootwrapped kernel image on Base FVP
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following example uses the AArch64 boot wrapper. This simplifies normal
+world booting while also making use of TF features. It can be obtained from its
+repository with:
+
+::
+
+ git clone git://git.kernel.org/pub/scm/linux/kernel/git/mark/boot-wrapper-aarch64.git
+
+After compiling it, an ELF file is generated. It can be loaded with the
+following command:
+
+::
+
+ <path-to>/FVP_Base_AEMv8A-AEMv8A \
+ -C bp.secureflashloader.fname=bl1.bin \
+ -C bp.flashloader0.fname=fip.bin \
+ -a cluster0.cpu0=<bootwrapped-kernel.elf> \
+ --start cluster0.cpu0=0x0
+
+The ``-a cluster0.cpu0=<bootwrapped-kernel.elf>`` option loads the ELF file. It
+also sets the PC register to the ELF entry point address, which is not the
+desired behaviour, so the ``--start cluster0.cpu0=0x0`` option forces the PC back
+to 0x0 (the BL1 entry point address) on CPU #0. The ``PRELOADED_BL33_BASE`` define
+used when compiling the FIP must match the ELF entry point.
+
+Boot of a preloaded bootwrapped kernel image on Juno
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The procedure to obtain and compile the boot wrapper is very similar to the case
+of the FVP. The execution must be stopped at the end of bl2\_main(), and the
+loading method explained above in the EL3 payload boot flow section may be used
+to load the ELF file over JTAG on Juno.
+
+Running the software on FVP
+---------------------------
+
+The latest version of the AArch64 build of ARM Trusted Firmware has been tested
+on the following ARM FVPs (64-bit host machine only).
+
+NOTE: Unless otherwise stated, the model version is Version 11.0 Build 11.0.34.
+
+- ``Foundation_Platform``
+- ``FVP_Base_AEMv8A-AEMv8A`` (Version 8.5, Build 0.8.8502)
+- ``FVP_Base_Cortex-A35x4``
+- ``FVP_Base_Cortex-A53x4``
+- ``FVP_Base_Cortex-A57x4-A53x4``
+- ``FVP_Base_Cortex-A57x4``
+- ``FVP_Base_Cortex-A72x4-A53x4``
+- ``FVP_Base_Cortex-A72x4``
+- ``FVP_Base_Cortex-A73x4-A53x4``
+- ``FVP_Base_Cortex-A73x4``
+
+The latest version of the AArch32 build of ARM Trusted Firmware has been tested
+on the following ARM FVPs (64-bit host machine only).
+
+- ``FVP_Base_AEMv8A-AEMv8A`` (Version 8.5, Build 0.8.8502)
+- ``FVP_Base_Cortex-A32x4``
+
+NOTE: The build numbers quoted above are those reported by launching the FVP
+with the ``--version`` parameter.
+
+NOTE: Linaro provides a ramdisk image in prebuilt FVP configurations and full
+file systems that can be downloaded separately. To run an FVP with a virtio
+file system image an additional FVP configuration option
+``-C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>`` can be
+used.
+
+NOTE: The software will not work on Version 1.0 of the Foundation FVP.
+The commands below would report an ``unhandled argument`` error in this case.
+
+NOTE: FVPs can be launched with ``--cadi-server`` option such that a
+CADI-compliant debugger (for example, ARM DS-5) can connect to and control its
+execution.
+
+The Foundation FVP is a cut down version of the AArch64 Base FVP. It can be
+downloaded for free from `ARM's website`_.
+
+The Cortex-A models listed above are also available to download from
+`ARM's website`_.
+
+Please refer to the FVP documentation for a detailed description of the model
+parameter options. A brief description of the important ones that affect the ARM
+Trusted Firmware and normal world software behavior is provided below.
+
+Obtaining the Flattened Device Trees
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Depending on the FVP configuration and Linux configuration used, different
+FDT files are required. FDTs for the Foundation and Base FVPs can be found in
+the Trusted Firmware source directory under ``fdts/``. The Foundation FVP has a
+subset of the Base FVP components. For example, the Foundation FVP lacks CLCD
+and MMC support, and has only one CPU cluster.
+
+Note: It is not recommended to use the FDTs built along the kernel because not
+all FDTs are available from there.
+
+- ``fvp-base-gicv2-psci.dtb``
+
+ For use with both AEMv8 and Cortex-A57-A53 Base FVPs with
+ Base memory map configuration.
+
+- ``fvp-base-gicv2-psci-aarch32.dtb``
+
+ For use with AEMv8 and Cortex-A32 Base FVPs running Linux in AArch32 state
+ with Base memory map configuration.
+
+- ``fvp-base-gicv3-psci.dtb``
+
+ (Default) For use with both AEMv8 and Cortex-A57-A53 Base FVPs with Base
+ memory map configuration and Linux GICv3 support.
+
+- ``fvp-base-gicv3-psci-aarch32.dtb``
+
+ For use with AEMv8 and Cortex-A32 Base FVPs running Linux in AArch32 state
+ with Base memory map configuration and Linux GICv3 support.
+
+- ``fvp-foundation-gicv2-psci.dtb``
+
+ For use with Foundation FVP with Base memory map configuration.
+
+- ``fvp-foundation-gicv3-psci.dtb``
+
+ (Default) For use with Foundation FVP with Base memory map configuration
+ and Linux GICv3 support.
+
+Running on the Foundation FVP with reset to BL1 entrypoint
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following ``Foundation_Platform`` parameters should be used to boot Linux with
+4 CPUs using the AArch64 build of ARM Trusted Firmware.
+
+::
+
+ <path-to>/Foundation_Platform \
+ --cores=4 \
+ --secure-memory \
+ --visualization \
+ --gicv3 \
+ --data="<path-to>/<bl1-binary>"@0x0 \
+ --data="<path-to>/<FIP-binary>"@0x08000000 \
+ --data="<path-to>/<fdt>"@0x82000000 \
+ --data="<path-to>/<kernel-binary>"@0x80080000 \
+ --data="<path-to>/<ramdisk-binary>"@0x84000000
+
+Notes:
+
+- BL1 is loaded at the start of the Trusted ROM.
+- The Firmware Image Package is loaded at the start of NOR FLASH0.
+- The Linux kernel image and device tree are loaded in DRAM.
+- The default use-case for the Foundation FVP is to use the ``--gicv3`` option
+ and enable the GICv3 device in the model. Note that without this option,
+ the Foundation FVP defaults to legacy (Versatile Express) memory map which
+ is not supported by ARM Trusted Firmware.
+
+Running on the AEMv8 Base FVP with reset to BL1 entrypoint
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux
+with 8 CPUs using the AArch64 build of ARM Trusted Firmware.
+
+::
+
+ <path-to>/FVP_Base_AEMv8A-AEMv8A \
+ -C pctl.startup=0.0.0.0 \
+ -C bp.secure_memory=1 \
+ -C bp.tzc_400.diagnostics=1 \
+ -C cluster0.NUM_CORES=4 \
+ -C cluster1.NUM_CORES=4 \
+ -C cache_state_modelled=1 \
+ -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \
+ -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \
+ --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \
+ --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
+ --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
+
+Running on the AEMv8 Base FVP (AArch32) with reset to BL1 entrypoint
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux
+with 8 CPUs using the AArch32 build of ARM Trusted Firmware.
+
+::
+
+ <path-to>/FVP_Base_AEMv8A-AEMv8A \
+ -C pctl.startup=0.0.0.0 \
+ -C bp.secure_memory=1 \
+ -C bp.tzc_400.diagnostics=1 \
+ -C cluster0.NUM_CORES=4 \
+ -C cluster1.NUM_CORES=4 \
+ -C cache_state_modelled=1 \
+ -C cluster0.cpu0.CONFIG64=0 \
+ -C cluster0.cpu1.CONFIG64=0 \
+ -C cluster0.cpu2.CONFIG64=0 \
+ -C cluster0.cpu3.CONFIG64=0 \
+ -C cluster1.cpu0.CONFIG64=0 \
+ -C cluster1.cpu1.CONFIG64=0 \
+ -C cluster1.cpu2.CONFIG64=0 \
+ -C cluster1.cpu3.CONFIG64=0 \
+ -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \
+ -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \
+ --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \
+ --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
+ --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
+
+Running on the Cortex-A57-A53 Base FVP with reset to BL1 entrypoint
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following ``FVP_Base_Cortex-A57x4-A53x4`` model parameters should be used to
+boot Linux with 8 CPUs using the AArch64 build of ARM Trusted Firmware.
+
+::
+
+ <path-to>/FVP_Base_Cortex-A57x4-A53x4 \
+ -C pctl.startup=0.0.0.0 \
+ -C bp.secure_memory=1 \
+ -C bp.tzc_400.diagnostics=1 \
+ -C cache_state_modelled=1 \
+ -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \
+ -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \
+ --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \
+ --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
+ --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
+
+Running on the Cortex-A32 Base FVP (AArch32) with reset to BL1 entrypoint
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following ``FVP_Base_Cortex-A32x4`` model parameters should be used to
+boot Linux with 4 CPUs using the AArch32 build of ARM Trusted Firmware.
+
+::
+
+ <path-to>/FVP_Base_Cortex-A32x4 \
+ -C pctl.startup=0.0.0.0 \
+ -C bp.secure_memory=1 \
+ -C bp.tzc_400.diagnostics=1 \
+ -C cache_state_modelled=1 \
+ -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \
+ -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \
+ --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \
+ --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
+ --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
+
+Running on the AEMv8 Base FVP with reset to BL31 entrypoint
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux
+with 8 CPUs using the AArch64 build of ARM Trusted Firmware.
+
+::
+
+ <path-to>/FVP_Base_AEMv8A-AEMv8A \
+ -C pctl.startup=0.0.0.0 \
+ -C bp.secure_memory=1 \
+ -C bp.tzc_400.diagnostics=1 \
+ -C cluster0.NUM_CORES=4 \
+ -C cluster1.NUM_CORES=4 \
+ -C cache_state_modelled=1 \
+ -C cluster0.cpu0.RVBAR=0x04023000 \
+ -C cluster0.cpu1.RVBAR=0x04023000 \
+ -C cluster0.cpu2.RVBAR=0x04023000 \
+ -C cluster0.cpu3.RVBAR=0x04023000 \
+ -C cluster1.cpu0.RVBAR=0x04023000 \
+ -C cluster1.cpu1.RVBAR=0x04023000 \
+ -C cluster1.cpu2.RVBAR=0x04023000 \
+ -C cluster1.cpu3.RVBAR=0x04023000 \
+ --data cluster0.cpu0="<path-to>/<bl31-binary>"@0x04023000 \
+ --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04001000 \
+ --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \
+ --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \
+ --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
+ --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
+
+Notes:
+
+- Since a FIP is not loaded when using BL31 as reset entrypoint, the
+ ``--data="<path-to><bl31|bl32|bl33-binary>"@<base-address-of-binary>``
+ parameter is needed to load the individual bootloader images in memory.
+ BL32 image is only needed if BL31 has been built to expect a Secure-EL1
+ Payload.
+
+- The ``-C cluster<X>.cpu<Y>.RVBAR=@<base-address-of-bl31>`` parameter, where
+ X and Y are the cluster and CPU numbers respectively, is used to set the
+ reset vector for each core.
+
+- Changing the default value of ``ARM_TSP_RAM_LOCATION`` will also require
+ changing the value of
+ ``--data="<path-to><bl32-binary>"@<base-address-of-bl32>`` to the new value of
+ ``BL32_BASE``.
+
+Running on the AEMv8 Base FVP (AArch32) with reset to SP\_MIN entrypoint
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux
+with 8 CPUs using the AArch32 build of ARM Trusted Firmware.
+
+::
+
+ <path-to>/FVP_Base_AEMv8A-AEMv8A \
+ -C pctl.startup=0.0.0.0 \
+ -C bp.secure_memory=1 \
+ -C bp.tzc_400.diagnostics=1 \
+ -C cluster0.NUM_CORES=4 \
+ -C cluster1.NUM_CORES=4 \
+ -C cache_state_modelled=1 \
+ -C cluster0.cpu0.CONFIG64=0 \
+ -C cluster0.cpu1.CONFIG64=0 \
+ -C cluster0.cpu2.CONFIG64=0 \
+ -C cluster0.cpu3.CONFIG64=0 \
+ -C cluster1.cpu0.CONFIG64=0 \
+ -C cluster1.cpu1.CONFIG64=0 \
+ -C cluster1.cpu2.CONFIG64=0 \
+ -C cluster1.cpu3.CONFIG64=0 \
+ -C cluster0.cpu0.RVBAR=0x04001000 \
+ -C cluster0.cpu1.RVBAR=0x04001000 \
+ -C cluster0.cpu2.RVBAR=0x04001000 \
+ -C cluster0.cpu3.RVBAR=0x04001000 \
+ -C cluster1.cpu0.RVBAR=0x04001000 \
+ -C cluster1.cpu1.RVBAR=0x04001000 \
+ -C cluster1.cpu2.RVBAR=0x04001000 \
+ -C cluster1.cpu3.RVBAR=0x04001000 \
+ --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04001000 \
+ --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \
+ --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \
+ --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
+ --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
+
+Note: The load address of ``<bl32-binary>`` depends on the value ``BL32_BASE``.
+It should match the address programmed into the RVBAR register as well.
+
+Running on the Cortex-A57-A53 Base FVP with reset to BL31 entrypoint
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following ``FVP_Base_Cortex-A57x4-A53x4`` model parameters should be used to
+boot Linux with 8 CPUs using the AArch64 build of ARM Trusted Firmware.
+
+::
+
+ <path-to>/FVP_Base_Cortex-A57x4-A53x4 \
+ -C pctl.startup=0.0.0.0 \
+ -C bp.secure_memory=1 \
+ -C bp.tzc_400.diagnostics=1 \
+ -C cache_state_modelled=1 \
+ -C cluster0.cpu0.RVBARADDR=0x04023000 \
+ -C cluster0.cpu1.RVBARADDR=0x04023000 \
+ -C cluster0.cpu2.RVBARADDR=0x04023000 \
+ -C cluster0.cpu3.RVBARADDR=0x04023000 \
+ -C cluster1.cpu0.RVBARADDR=0x04023000 \
+ -C cluster1.cpu1.RVBARADDR=0x04023000 \
+ -C cluster1.cpu2.RVBARADDR=0x04023000 \
+ -C cluster1.cpu3.RVBARADDR=0x04023000 \
+ --data cluster0.cpu0="<path-to>/<bl31-binary>"@0x04023000 \
+ --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04001000 \
+ --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \
+ --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \
+ --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
+ --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
+
+Running on the Cortex-A32 Base FVP (AArch32) with reset to SP\_MIN entrypoint
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following ``FVP_Base_Cortex-A32x4`` model parameters should be used to
+boot Linux with 4 CPUs using the AArch32 build of ARM Trusted Firmware.
+
+::
+
+ <path-to>/FVP_Base_Cortex-A32x4 \
+ -C pctl.startup=0.0.0.0 \
+ -C bp.secure_memory=1 \
+ -C bp.tzc_400.diagnostics=1 \
+ -C cache_state_modelled=1 \
+ -C cluster0.cpu0.RVBARADDR=0x04001000 \
+ -C cluster0.cpu1.RVBARADDR=0x04001000 \
+ -C cluster0.cpu2.RVBARADDR=0x04001000 \
+ -C cluster0.cpu3.RVBARADDR=0x04001000 \
+ --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04001000 \
+ --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \
+ --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \
+ --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
+ --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
+
+Running the software on Juno
+----------------------------
+
+This version of the ARM Trusted Firmware has been tested on variants r0, r1 and
+r2 of Juno.
+
+To execute the software stack on Juno, the version of the Juno board recovery
+image indicated in the `Linaro Release Notes`_ must be installed. If you have an
+earlier version installed or are unsure which version is installed, please
+re-install the recovery image by following the
+`Instructions for using Linaro's deliverables on Juno`_.
+
+Preparing Trusted Firmware images
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After building Trusted Firmware, the files ``bl1.bin`` and ``fip.bin`` need copying
+to the ``SOFTWARE/`` directory of the Juno SD card.
+
+Other Juno software information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Please visit the `ARM Platforms Portal`_ to get support and obtain any other Juno
+software information. Please also refer to the `Juno Getting Started Guide`_ to
+get more detailed information about the Juno ARM development platform and how to
+configure it.
+
+Testing SYSTEM SUSPEND on Juno
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The SYSTEM SUSPEND is a PSCI API which can be used to implement system suspend
+to RAM. For more details refer to section 5.16 of `PSCI`_. To test system suspend
+on Juno, at the linux shell prompt, issue the following command:
+
+::
+
+ echo +10 > /sys/class/rtc/rtc0/wakealarm
+ echo -n mem > /sys/power/state
+
+The Juno board should suspend to RAM and then wakeup after 10 seconds due to
+wakeup interrupt from RTC.
+
+--------------
+
+*Copyright (c) 2013-2017, ARM Limited and Contributors. All rights reserved.*
+
+.. _Linaro: `Linaro Release Notes`_
+.. _Linaro Release: `Linaro Release Notes`_
+.. _Linaro Release Notes: https://community.arm.com/tools/dev-platforms/b/documents/posts/linaro-release-notes-deprecated
+.. _Linaro Release 17.04: https://community.arm.com/tools/dev-platforms/b/documents/posts/linaro-release-notes-deprecated#LinaroRelease17.04
+.. _Linaro instructions: https://community.arm.com/dev-platforms/b/documents/posts/instructions-for-using-the-linaro-software-deliverables
+.. _Instructions for using Linaro's deliverables on Juno: https://community.arm.com/dev-platforms/b/documents/posts/using-linaros-deliverables-on-juno
+.. _ARM Platforms Portal: https://community.arm.com/dev-platforms/
+.. _Development Studio 5 (DS-5): http://www.arm.com/products/tools/software-tools/ds-5/index.php
+.. _here: psci-lib-integration-guide.rst
+.. _Trusted Board Boot: trusted-board-boot.rst
+.. _Secure-EL1 Payloads and Dispatchers: firmware-design.rst#user-content-secure-el1-payloads-and-dispatchers
+.. _Firmware Update: firmware-update.rst
+.. _Firmware Design: firmware-design.rst
+.. _mbed TLS Repository: https://github.com/ARMmbed/mbedtls.git
+.. _mbed TLS Security Center: https://tls.mbed.org/security
+.. _ARM's website: `FVP models`_
+.. _FVP models: https://developer.arm.com/products/system-design/fixed-virtual-platforms
+.. _Juno Getting Started Guide: http://infocenter.arm.com/help/topic/com.arm.doc.dui0928e/DUI0928E_juno_arm_development_platform_gsg.pdf
+.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
diff --git a/license.md b/license.rst
similarity index 65%
rename from license.md
rename to license.rst
index 185ecd1..c51e595 100644
--- a/license.md
+++ b/license.rst
@@ -3,16 +3,16 @@
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
-* Redistributions of source code must retain the above copyright notice, this
- list of conditions and the following disclaimer.
+- Redistributions of source code must retain the above copyright notice, this
+ list of conditions and the following disclaimer.
-* Redistributions in binary form must reproduce the above copyright notice, this
- list of conditions and the following disclaimer in the documentation and/or
- other materials provided with the distribution.
+- Redistributions in binary form must reproduce the above copyright notice, this
+ list of conditions and the following disclaimer in the documentation and/or
+ other materials provided with the distribution.
-* Neither the name of ARM nor the names of its contributors may be used to
- endorse or promote products derived from this software without specific prior
- written permission.
+- Neither the name of ARM nor the names of its contributors may be used to
+ endorse or promote products derived from this software without specific prior
+ written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
@@ -25,11 +25,14 @@
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
----------------------------------------------------------------------------
+--------------
+
Note:
Individual files contain the following tag instead of the full license text.
- SPDX-License-Identifier: BSD-3-Clause
+::
+
+ SPDX-License-Identifier: BSD-3-Clause
This enables machine processing of license information based on the SPDX
License Identifiers that are here available: http://spdx.org/licenses/
diff --git a/maintainers.md b/maintainers.md
deleted file mode 100644
index c8fc19d..0000000
--- a/maintainers.md
+++ /dev/null
@@ -1,84 +0,0 @@
-ARM Trusted Firmware Maintainers
-================================
-
-ARM Trusted Firmware is an ARM maintained project. All contributions are
-ultimately merged by the maintainers listed below. Technical ownership of some
-parts of the codebase is delegated to the sub-maintainers listed below. An
-acknowledgement from these sub-maintainers may be required before the
-maintainers merge a contribution.
-
-
-## Maintainers
-
-Dan Handley (dan.handley@arm.com, [danh-arm](https://github.com/danh-arm))
-
-David Cunado (david.cunado@arm.com, [davidcunado-arm](https://github.com/davidcunado-arm))
-
-
-## OPTEE and QEMU platform sub-maintainer
-
-Jens Wiklander (jens.wiklander@linaro.org, [jenswi-linaro](https://github.com/jenswi-linaro))
-
-Files:
-* docs/spd/optee-dispatcher.md
-* docs/plat/qemu.md
-* services/spd/opteed/*
-* plat/qemu/*
-
-
-## TLK/Trusty SPDs and NVidia platforms sub-maintainer
-
-Varun Wadekar (vwadekar@nvidia.com, [vwadekar](https://github.com/vwadekar))
-
-Files:
-* docs/spd/tlk-dispatcher.md
-* docs/spd/trusty-dispatcher.md
-* include/bl32/payloads/tlk.h
-* include/lib/cpus/aarch64/denver.h
-* lib/cpus/aarch64/denver.S
-* services/spd/tlkd/*
-* services/spd/trusty/*
-* plat/nvidia/*
-
-
-## eMMC/UFS drivers and HiSilicon platform sub-maintainer
-
-Haojian Zhuang (haojian.zhuang@linaro.org, [hzhuang1](https://github.com/hzhuang1))
-
-Files:
-* docs/plat/hikey.md
-* docs/plat/hikey960.md
-* drivers/emmc/*
-* drivers/partition/*
-* drivers/synopsys/emmc/*
-* drivers/synopsys/ufs/*
-* drivers/ufs/*
-* include/drivers/dw_ufs.h
-* include/drivers/emmc.h
-* include/drivers/ufs.h
-* include/drivers/synopsys/dw_mmc.h
-* plat/hisilicon/*
-
-
-## MediaTek platform sub-maintainer
-
-Yidi Lin (林以廸 yidi.lin@mediatek.com, [mtk09422](https://github.com/mtk09422))
-
-Files:
-* plat/mediatek/*
-
-
-## RockChip platform sub-maintainer
-Tony Xie (tony.xie@rock-chips.com, [TonyXie06](https://github.com/TonyXie06)
-or [rkchrome](https://github.com/rkchrome))
-
-Files:
-* plat/rockchip/*
-
-
-## Xilinx platform sub-maintainer
-Sören Brinkmann (soren.brinkmann@xilinx.com, [sorenb-xlnx](https://github.com/sorenb-xlnx))
-
-Files:
-* docs/plat/xilinx-zynqmp.md
-* plat/xilinx/*
diff --git a/maintainers.rst b/maintainers.rst
new file mode 100644
index 0000000..388073e
--- /dev/null
+++ b/maintainers.rst
@@ -0,0 +1,102 @@
+ARM Trusted Firmware Maintainers
+================================
+
+ARM Trusted Firmware is an ARM maintained project. All contributions are
+ultimately merged by the maintainers listed below. Technical ownership of some
+parts of the codebase is delegated to the sub-maintainers listed below. An
+acknowledgement from these sub-maintainers may be required before the
+maintainers merge a contribution.
+
+Maintainers
+-----------
+
+Dan Handley (dan.handley@arm.com, `danh-arm`_)
+
+David Cunado (david.cunado@arm.com, `davidcunado-arm`_)
+
+OPTEE and QEMU platform sub-maintainer
+--------------------------------------
+
+Jens Wiklander (jens.wiklander@linaro.org, `jenswi-linaro`_)
+
+Files:
+
+- docs/spd/optee-dispatcher.md
+- docs/plat/qemu.md
+- services/spd/opteed/\*
+- plat/qemu/\*
+
+TLK/Trusty SPDs and NVidia platforms sub-maintainer
+---------------------------------------------------
+
+Varun Wadekar (vwadekar@nvidia.com, `vwadekar`_)
+
+Files:
+
+- docs/spd/tlk-dispatcher.md
+- docs/spd/trusty-dispatcher.md
+- include/bl32/payloads/tlk.h
+- include/lib/cpus/aarch64/denver.h
+- lib/cpus/aarch64/denver.S
+- services/spd/tlkd/\*
+- services/spd/trusty/\*
+- plat/nvidia/\*
+
+eMMC/UFS drivers and HiSilicon platform sub-maintainer
+------------------------------------------------------
+
+Haojian Zhuang (haojian.zhuang@linaro.org, `hzhuang1`_)
+
+Files:
+
+- docs/plat/hikey.md
+- docs/plat/hikey960.md
+- drivers/emmc/\*
+- drivers/partition/\*
+- drivers/synopsys/emmc/\*
+- drivers/synopsys/ufs/\*
+- drivers/ufs/\*
+- include/drivers/dw\_ufs.h
+- include/drivers/emmc.h
+- include/drivers/ufs.h
+- include/drivers/synopsys/dw\_mmc.h
+- plat/hisilicon/\*
+
+MediaTek platform sub-maintainer
+--------------------------------
+
+Yidi Lin (林以廸 yidi.lin@mediatek.com, `mtk09422`_)
+
+Files:
+
+- plat/mediatek/\*
+
+RockChip platform sub-maintainer
+--------------------------------
+
+Tony Xie (tony.xie@rock-chips.com, `TonyXie06`_
+or `rkchrome`_)
+
+Files:
+
+- plat/rockchip/\*
+
+Xilinx platform sub-maintainer
+------------------------------
+
+Sören Brinkmann (soren.brinkmann@xilinx.com, `sorenb-xlnx`_)
+
+Files:
+
+- docs/plat/xilinx-zynqmp.md
+- plat/xilinx/\*
+
+.. _danh-arm: https://github.com/danh-arm
+.. _davidcunado-arm: https://github.com/davidcunado-arm
+.. _jenswi-linaro: https://github.com/jenswi-linaro
+.. _vwadekar: https://github.com/vwadekar
+.. _hzhuang1: https://github.com/hzhuang1
+.. _mtk09422: https://github.com/mtk09422
+.. _TonyXie06: https://github.com/TonyXie06
+.. _rkchrome: https://github.com/rkchrome
+.. _sorenb-xlnx: https://github.com/sorenb-xlnx
diff --git a/plat/hisilicon/hikey/platform.mk b/plat/hisilicon/hikey/platform.mk
index 85dc40d..08a3047 100644
--- a/plat/hisilicon/hikey/platform.mk
+++ b/plat/hisilicon/hikey/platform.mk
@@ -82,3 +82,7 @@
lib/pmf/pmf_smc.c
endif
+# Enable workarounds for selected Cortex-A53 errata.
+ERRATA_A53_836870 := 1
+ERRATA_A53_843419 := 1
+ERRATA_A53_855873 := 1
diff --git a/plat/rockchip/rk3399/drivers/dp/cdn_dp.c b/plat/rockchip/rk3399/drivers/dp/cdn_dp.c
new file mode 100644
index 0000000..d0e5986
--- /dev/null
+++ b/plat/rockchip/rk3399/drivers/dp/cdn_dp.c
@@ -0,0 +1,65 @@
+/*
+ * Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#include <cdn_dp.h>
+#include <smcc.h>
+#include <stdlib.h>
+#include <string.h>
+
+__asm__(
+ ".pushsection .text.hdcp_handler, \"ax\", %progbits\n"
+ ".global hdcp_handler\n"
+ ".balign 4\n"
+ "hdcp_handler:\n"
+ ".incbin \"" __XSTRING(HDCPFW) "\"\n"
+ ".type hdcp_handler, %function\n"
+ ".size hdcp_handler, .- hdcp_handler\n"
+ ".popsection\n"
+);
+
+static uint64_t *hdcp_key_pdata;
+static struct cdn_dp_hdcp_key_1x key;
+
+int hdcp_handler(struct cdn_dp_hdcp_key_1x *key);
+
+uint64_t dp_hdcp_ctrl(uint64_t type)
+{
+ switch (type) {
+ case HDCP_KEY_DATA_START_TRANSFER:
+ memset(&key, 0x00, sizeof(key));
+ hdcp_key_pdata = (uint64_t *)&key;
+ return 0;
+ case HDCP_KEY_DATA_START_DECRYPT:
+ if (hdcp_key_pdata == (uint64_t *)(&key + 1))
+ return hdcp_handler(&key);
+ else
+ return PSCI_E_INVALID_PARAMS;
+ default:
+ return SMC_UNK;
+ }
+}
+
+uint64_t dp_hdcp_store_key(uint64_t x1,
+ uint64_t x2,
+ uint64_t x3,
+ uint64_t x4,
+ uint64_t x5,
+ uint64_t x6)
+{
+ if (hdcp_key_pdata < (uint64_t *)&key ||
+ hdcp_key_pdata + 6 > (uint64_t *)(&key + 1))
+ return PSCI_E_INVALID_PARAMS;
+
+ hdcp_key_pdata[0] = x1;
+ hdcp_key_pdata[1] = x2;
+ hdcp_key_pdata[2] = x3;
+ hdcp_key_pdata[3] = x4;
+ hdcp_key_pdata[4] = x5;
+ hdcp_key_pdata[5] = x6;
+ hdcp_key_pdata += 6;
+
+ return 0;
+}
diff --git a/plat/rockchip/rk3399/drivers/dp/cdn_dp.h b/plat/rockchip/rk3399/drivers/dp/cdn_dp.h
new file mode 100644
index 0000000..3b9a108
--- /dev/null
+++ b/plat/rockchip/rk3399/drivers/dp/cdn_dp.h
@@ -0,0 +1,47 @@
+/*
+ * Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#ifndef __SOC_ROCKCHIP_RK3399_DP_H__
+#define __SOC_ROCKCHIP_RK3399_DP_H__
+#include <plat_private.h>
+
+enum {
+ CDN_DP_HDCP_1X_KSV_LEN = 5,
+ CDN_DP_HDCP_KSV_LEN = 8,
+ CDN_DP_HDCP_RESERVED_LEN = 10,
+ CDN_DP_HDCP_UID_LEN = 16,
+ CDN_DP_HDCP_SHA_LEN = 20,
+ CDN_DP_HDCP_DPK_LEN = 280,
+ CDN_DP_HDCP_1X_KEYS_LEN = 285,
+ CDN_DP_HDCP_KEY_LEN = 326,
+};
+
+struct cdn_dp_hdcp_key_1x {
+ uint8_t ksv[CDN_DP_HDCP_KSV_LEN];
+ uint8_t device_key[CDN_DP_HDCP_DPK_LEN];
+ uint8_t sha1[CDN_DP_HDCP_SHA_LEN];
+ uint8_t uid[CDN_DP_HDCP_UID_LEN];
+ uint16_t seed;
+ uint8_t reserved[CDN_DP_HDCP_RESERVED_LEN];
+};
+
+#define HDCP_KEY_DATA_START_TRANSFER 0
+#define HDCP_KEY_DATA_START_DECRYPT 1
+#define HDCP_KEY_1X_STORE_DATA_ALIGN_SIZE (6 * 64) / 8
+
+/* Checks the cdn_dp_hdcp_key_1x must be aligned on 6 x 64-bit word boundary */
+CASSERT(sizeof(struct cdn_dp_hdcp_key_1x) % HDCP_KEY_1X_STORE_DATA_ALIGN_SIZE, \
+ assert_hdcp_key_1x_store_data_align_size_mismatch);
+
+uint64_t dp_hdcp_ctrl(uint64_t type);
+
+uint64_t dp_hdcp_store_key(uint64_t x1,
+ uint64_t x2,
+ uint64_t x3,
+ uint64_t x4,
+ uint64_t x5,
+ uint64_t x6);
+#endif
diff --git a/plat/rockchip/rk3399/drivers/dp/hdcp.bin b/plat/rockchip/rk3399/drivers/dp/hdcp.bin
new file mode 100644
index 0000000..28db923
--- /dev/null
+++ b/plat/rockchip/rk3399/drivers/dp/hdcp.bin
Binary files differ
diff --git a/plat/rockchip/rk3399/plat_sip_calls.c b/plat/rockchip/rk3399/plat_sip_calls.c
index 77b7c3e..1a01604 100644
--- a/plat/rockchip/rk3399/plat_sip_calls.c
+++ b/plat/rockchip/rk3399/plat_sip_calls.c
@@ -4,6 +4,7 @@
* SPDX-License-Identifier: BSD-3-Clause
*/
+#include <cdn_dp.h>
#include <debug.h>
#include <mmio.h>
#include <plat_sip_calls.h>
@@ -22,6 +23,9 @@
#define DRAM_SET_PARAM 0x07
#define DRAM_SET_ODT_PD 0x08
+#define RK_SIP_HDCP_CONTROL 0x82000009
+#define RK_SIP_HDCP_KEY_DATA64 0xC200000A
+
uint32_t ddr_smc_handler(uint64_t arg0, uint64_t arg1,
uint64_t id, uint64_t arg2)
{
@@ -51,9 +55,17 @@
void *handle,
uint64_t flags)
{
+ uint64_t x5, x6;
+
switch (smc_fid) {
case RK_SIP_DDR_CFG:
SMC_RET1(handle, ddr_smc_handler(x1, x2, x3, x4));
+ case RK_SIP_HDCP_CONTROL:
+ SMC_RET1(handle, dp_hdcp_ctrl(x1));
+ case RK_SIP_HDCP_KEY_DATA64:
+ x5 = read_ctx_reg(get_gpregs_ctx(handle), CTX_GPREG_X5);
+ x6 = read_ctx_reg(get_gpregs_ctx(handle), CTX_GPREG_X6);
+ SMC_RET1(handle, dp_hdcp_store_key(x1, x2, x3, x4, x5, x6));
default:
ERROR("%s: unhandled SMC (0x%x)\n", __func__, smc_fid);
SMC_RET1(handle, SMC_UNK);
diff --git a/plat/rockchip/rk3399/platform.mk b/plat/rockchip/rk3399/platform.mk
index 6107124..85cca1b 100644
--- a/plat/rockchip/rk3399/platform.mk
+++ b/plat/rockchip/rk3399/platform.mk
@@ -18,6 +18,7 @@
-I${RK_PLAT_SOC}/drivers/secure/ \
-I${RK_PLAT_SOC}/drivers/soc/ \
-I${RK_PLAT_SOC}/drivers/dram/ \
+ -I${RK_PLAT_SOC}/drivers/dp/ \
-I${RK_PLAT_SOC}/include/ \
-I${RK_PLAT_SOC}/include/shared/ \
@@ -49,6 +50,7 @@
${RK_PLAT_COMMON}/aarch64/platform_common.c \
${RK_PLAT_COMMON}/rockchip_sip_svc.c \
${RK_PLAT_SOC}/plat_sip_calls.c \
+ ${RK_PLAT_SOC}/drivers/dp/cdn_dp.c \
${RK_PLAT_SOC}/drivers/gpio/rk3399_gpio.c \
${RK_PLAT_SOC}/drivers/pmu/pmu.c \
${RK_PLAT_SOC}/drivers/pmu/pmu_fw.c \
@@ -75,11 +77,17 @@
RK3399M0FW=${BUILD_M0}/${PLAT_M0}.bin
$(eval $(call add_define,RK3399M0FW))
+HDCPFW=${RK_PLAT_SOC}/drivers/dp/hdcp.bin
+$(eval $(call add_define,HDCPFW))
+
# CCACHE_EXTRAFILES is needed because ccache doesn't handle .incbin
export CCACHE_EXTRAFILES
${BUILD_PLAT}/bl31/pmu_fw.o: CCACHE_EXTRAFILES=$(RK3399M0FW)
${RK_PLAT_SOC}/drivers/pmu/pmu_fw.c: $(RK3399M0FW)
+${BUILD_PLAT}/bl31/cdn_dp.o: CCACHE_EXTRAFILES=$(HDCPFW)
+${RK_PLAT_SOC}/drivers/dp/cdn_dp.c: $(HDCPFW)
+
$(eval $(call MAKE_PREREQ_DIR,${BUILD_M0},))
.PHONY: $(RK3399M0FW)
$(RK3399M0FW): | ${BUILD_M0}
diff --git a/readme.md b/readme.md
deleted file mode 100644
index ef5f6ee..0000000
--- a/readme.md
+++ /dev/null
@@ -1,197 +0,0 @@
-ARM Trusted Firmware - version 1.3
-==================================
-
-ARM Trusted Firmware provides a reference implementation of secure world
-software for [ARMv8-A], including a [Secure Monitor] [TEE-SMC] executing at
-Exception Level 3 (EL3). It implements various ARM interface standards, such as
-the Power State Coordination Interface ([PSCI]), Trusted Board Boot Requirements
-(TBBR, ARM DEN0006C-1) and [SMC Calling Convention][SMCCC]. As far as possible
-the code is designed for reuse or porting to other ARMv8-A model and hardware
-platforms.
-
-ARM will continue development in collaboration with interested parties to
-provide a full reference implementation of PSCI, TBBR and Secure Monitor code
-to the benefit of all developers working with ARMv8-A TrustZone technology.
-
-
-License
--------
-
-The software is provided under a BSD-3-Clause [license]. Contributions to this
-project are accepted under the same license with developer sign-off as
-described in the [Contributing Guidelines].
-
-This project contains code from other projects as listed below. The original
-license text is included in those source files.
-
-* The stdlib source code is derived from FreeBSD code.
-
-* The libfdt source code is dual licensed. It is used by this project under
- the terms of the BSD-2-Clause license.
-
-
-This Release
-------------
-
-This release provides a suitable starting point for productization of secure
-world boot and runtime firmware, executing in either the AArch32 or AArch64
-execution state.
-
-Users are encouraged to do their own security validation, including penetration
-testing, on any secure world code derived from ARM Trusted Firmware.
-
-### Functionality
-
-* Initialization of the secure world (for example, exception vectors, control
- registers, interrupt controller and interrupts for the platform), before
- transitioning into the normal world at the Exception Level and Register
- Width specified by the platform.
-
-* Library support for CPU specific reset and power down sequences. This
- includes support for errata workarounds.
-
-* Drivers for both versions 2.0 and 3.0 of the ARM Generic Interrupt
- Controller specifications (GICv2 and GICv3). The latter also enables GICv3
- hardware systems that do not contain legacy GICv2 support.
-
-* Drivers to enable standard initialization of ARM System IP, for example
- Cache Coherent Interconnect (CCI), Cache Coherent Network (CCN), Network
- Interconnect (NIC) and TrustZone Controller (TZC).
-
-* SMC (Secure Monitor Call) handling, conforming to the [SMC Calling
- Convention][SMCCC] using an EL3 runtime services framework.
-
-* [PSCI] library support for the Secondary CPU Boot, CPU Hotplug, CPU Idle
- and System Shutdown/Reset/Suspend use-cases.
- This library is pre-integrated with the provided AArch64 EL3 Runtime
- Software, and is also suitable for integration into other EL3 Runtime
- Software.
-
-* A minimal AArch32 Secure Payload to demonstrate [PSCI] library integration
- on platforms with AArch32 EL3 Runtime Software.
-
-* Secure Monitor library code such as world switching, EL1 context management
- and interrupt routing.
- When using the provided AArch64 EL3 Runtime Software, this must be
- integrated with a Secure-EL1 Payload Dispatcher (SPD) component to
- customize the interaction with a Secure-EL1 Payload (SP), for example a
- Secure OS.
-
-* A Test Secure-EL1 Payload and Dispatcher to demonstrate AArch64 Secure
- Monitor functionality and Secure-EL1 interaction with PSCI.
-
-* AArch64 SPDs for the [OP-TEE Secure OS] and [NVidia Trusted Little Kernel]
- [NVidia TLK].
-
-* A Trusted Board Boot implementation, conforming to all mandatory TBBR
- requirements. This includes image authentication using certificates, a
- Firmware Update (or recovery mode) boot flow, and packaging of the various
- firmware images into a Firmware Image Package (FIP) to be loaded from
- non-volatile storage.
- The TBBR implementation is currently only supported in the AArch64 build.
-
-* Support for alternative boot flows. Some platforms have their own boot
- firmware and only require the AArch64 EL3 Runtime Software provided by this
- project. Other platforms require minimal initialization before booting
- into an arbitrary EL3 payload.
-
-For a full description of functionality and implementation details, please
-see the [Firmware Design] and supporting documentation. The [Change Log]
-provides details of changes made since the last release.
-
-### Platforms
-
-The AArch64 build of this release has been tested on variants r0, r1 and r2
-of the [Juno ARM Development Platform] [Juno] with [Linaro Release 16.06].
-
-The AArch64 build of this release has been tested on the following ARM
-[FVP]s (64-bit host machine only, with [Linaro Release 16.06]):
-
-* `Foundation_Platform` (Version 10.1, Build 10.1.32)
-* `FVP_Base_AEMv8A-AEMv8A` (Version 7.7, Build 0.8.7701)
-* `FVP_Base_Cortex-A57x4-A53x4` (Version 7.7, Build 0.8.7701)
-* `FVP_Base_Cortex-A57x1-A53x1` (Version 7.7, Build 0.8.7701)
-* `FVP_Base_Cortex-A57x2-A53x4` (Version 7.7, Build 0.8.7701)
-
-The AArch32 build of this release has been tested on the following ARM
-[FVP]s (64-bit host machine only, with [Linaro Release 16.06]):
-
-* `FVP_Base_AEMv8A-AEMv8A` (Version 7.7, Build 0.8.7701)
-* `FVP_Base_Cortex-A32x4` (Version 10.1, Build 10.1.32)
-
-The Foundation FVP can be downloaded free of charge. The Base FVPs can be
-licensed from ARM: see [www.arm.com/fvp] [FVP].
-
-This release also contains the following platform support:
-
-* MediaTek MT6795 and MT8173 SoCs
-* NVidia T210 and T132 SoCs
-* QEMU emulator
-* RockChip RK3368 and RK3399 SoCs
-* Xilinx Zynq UltraScale + MPSoC
-
-### Still to Come
-
-* AArch32 TBBR support and ongoing TBBR alignment.
-
-* More platform support.
-
-* Ongoing support for new architectural features, CPUs and System IP.
-
-* Ongoing [PSCI] alignment and feature support.
-
-* Ongoing security hardening, optimization and quality improvements.
-
-For a full list of detailed issues in the current code, please see the [Change
-Log] and the [GitHub issue tracker].
-
-
-Getting Started
----------------
-
-Get the Trusted Firmware source code from
-[GitHub](https://www.github.com/ARM-software/arm-trusted-firmware).
-
-See the [User Guide] for instructions on how to install, build and use
-the Trusted Firmware with the ARM [FVP]s.
-
-See the [Firmware Design] for information on how the ARM Trusted Firmware works.
-
-See the [Porting Guide] as well for information about how to use this
-software on another ARMv8-A platform.
-
-See the [Contributing Guidelines] for information on how to contribute to this
-project and the [Acknowledgments] file for a list of contributors to the
-project.
-
-### Feedback and support
-
-ARM welcomes any feedback on the Trusted Firmware. Please send feedback using
-the [GitHub issue tracker].
-
-ARM licensees may contact ARM directly via their partner managers.
-
-
-- - - - - - - - - - - - - - - - - - - - - - - - - -
-
-_Copyright (c) 2013-2016, ARM Limited and Contributors. All rights reserved._
-
-
-[License]: ./license.md "BSD license for ARM Trusted Firmware"
-[Contributing Guidelines]: ./contributing.md "Guidelines for contributors"
-[Acknowledgments]: ./acknowledgements.md "Contributor acknowledgments"
-[Change Log]: ./docs/change-log.md
-[User Guide]: ./docs/user-guide.md
-[Firmware Design]: ./docs/firmware-design.md
-[Porting Guide]: ./docs/porting-guide.md
-
-[ARMv8-A]: http://www.arm.com/products/processors/armv8-architecture.php "ARMv8-A Architecture"
-[FVP]: http://www.arm.com/fvp "ARM's Fixed Virtual Platforms"
-[Juno]: http://www.arm.com/products/tools/development-boards/versatile-express/juno-arm-development-platform.php "Juno ARM Development Platform"
-[PSCI]: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf "Power State Coordination Interface PDD (ARM DEN 0022C)"
-[SMCCC]: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html "SMC Calling Convention PDD (ARM DEN 0028A)"
-[TEE-SMC]: http://www.arm.com/products/processors/technologies/trustzone/tee-smc.php "Secure Monitor and TEEs"
-[GitHub issue tracker]: https://github.com/ARM-software/tf-issues/issues
-[OP-TEE Secure OS]: https://github.com/OP-TEE/optee_os
-[NVidia TLK]: http://nv-tegra.nvidia.com/gitweb/?p=3rdparty/ote_partner/tlk.git;a=summary
-[Linaro Release 16.06]: https://community.arm.com/docs/DOC-10952#jive_content_id_Linaro_Release_1606
diff --git a/readme.rst b/readme.rst
new file mode 100644
index 0000000..a83338f
--- /dev/null
+++ b/readme.rst
@@ -0,0 +1,219 @@
+ARM Trusted Firmware - version 1.4
+==================================
+
+ARM Trusted Firmware provides a reference implementation of secure world
+software for `ARMv8-A`_, including a `Secure Monitor`_ executing at
+Exception Level 3 (EL3). It implements various ARM interface standards, such as:
+
+- The `Power State Coordination Interface (PSCI)`_
+- Trusted Board Boot Requirements (TBBR, ARM DEN0006C-1)
+- `SMC Calling Convention`_
+- `System Control and Management Interface`_
+
+As far as possible the code is designed for reuse or porting to other ARMv8-A
+model and hardware platforms.
+
+ARM will continue development in collaboration with interested parties to
+provide a full reference implementation of Secure Monitor code and ARM standards
+to the benefit of all developers working with ARMv8-A TrustZone technology.
+
+License
+-------
+
+The software is provided under a BSD-3-Clause `license`_. Contributions to this
+project are accepted under the same license with developer sign-off as
+described in the `Contributing Guidelines`_.
+
+This project contains code from other projects as listed below. The original
+license text is included in those source files.
+
+- The stdlib source code is derived from FreeBSD code.
+
+- The libfdt source code is dual licensed. It is used by this project under
+ the terms of the BSD-2-Clause license.
+
+- The LLVM compiler-rt source code is dual licensed. It is used by this
+ project under the terms of the University of Illinois "BSD-Like" license.
+
+This Release
+------------
+
+This release provides a suitable starting point for productization of secure
+world boot and runtime firmware, in either the AArch32 or AArch64 execution
+state.
+
+Users are encouraged to do their own security validation, including penetration
+testing, on any secure world code derived from ARM Trusted Firmware.
+
+Functionality
+~~~~~~~~~~~~~
+
+- Initialization of the secure world, for example exception vectors, control
+ registers and interrupts for the platform.
+
+- Library support for CPU specific reset and power down sequences. This
+ includes support for errata workarounds and the latest ARM DynamIQ CPUs.
+
+- Drivers to enable standard initialization of ARM System IP, for example
+ Generic Interrupt Controller (GIC), Cache Coherent Interconnect (CCI),
+ Cache Coherent Network (CCN), Network Interconnect (NIC) and TrustZone
+ Controller (TZC).
+
+- A generic `SCMI`_ driver to interface with conforming power controllers, for
+ example the ARM System Control Processor (SCP).
+
+- SMC (Secure Monitor Call) handling, conforming to the `SMC Calling
+ Convention`_ using an EL3 runtime services framework.
+
+- `PSCI`_ library support for CPU, cluster and system power management
+ use-cases.
+ This library is pre-integrated with the AArch64 EL3 Runtime Software, and
+ is also suitable for integration with other AArch32 EL3 Runtime Software,
+ for example an AArch32 Secure OS.
+
+- A minimal AArch32 Secure Payload (SP\_MIN) to demonstrate `PSCI`_ library
+ integration with AArch32 EL3 Runtime Software.
+
+- Secure Monitor library code such as world switching, EL1 context management
+ and interrupt routing.
+ When a Secure-EL1 Payload (SP) is present, for example a Secure OS, the
+ AArch64 EL3 Runtime Software must be integrated with a dispatcher component
+ (SPD) to customize the interaction with the SP.
+
+- A Test SP/SPD to demonstrate AArch64 Secure Monitor functionality and SP
+ interaction with PSCI.
+
+- SPDs for the `OP-TEE Secure OS`_, `NVidia Trusted Little Kernel`_
+ and `Trusty Secure OS`_.
+
+- A Trusted Board Boot implementation, conforming to all mandatory TBBR
+ requirements. This includes image authentication, Firmware Update (or
+ recovery mode), and packaging of the various firmware images into a
+ Firmware Image Package (FIP).
+
+- Pre-integration of TBB with the ARM TrustZone CryptoCell product, to take
+ advantage of its hardware Root of Trust and crypto acceleration services.
+
+- Support for alternative boot flows, for example to support platforms where
+ the EL3 Runtime Software is loaded using other firmware or a separate
+ secure system processor.
+
+- Support for the GCC, LLVM and ARM Compiler 6 toolchains.
+
+For a full description of functionality and implementation details, please
+see the `Firmware Design`_ and supporting documentation. The `Change Log`_
+provides details of changes made since the last release.
+
+Platforms
+~~~~~~~~~
+
+Various AArch32 and AArch64 builds of this release has been tested on variants
+r0, r1 and r2 of the `Juno ARM Development Platform`_.
+
+Various AArch64 builds of this release have been tested on the following ARM
+`FVP`_\ s (64-bit host machine only):
+
+NOTE: Unless otherwise stated, the FVP Version is 11.0, Build 11.0.34.
+
+- ``Foundation_Platform``
+- ``FVP_Base_AEMv8A-AEMv8A`` (Version 8.5, Build 0.8.8502)
+- ``FVP_Base_Cortex-A35x4``
+- ``FVP_Base_Cortex-A53x4``
+- ``FVP_Base_Cortex-A57x4-A53x4``
+- ``FVP_Base_Cortex-A57x4``
+- ``FVP_Base_Cortex-A72x4-A53x4``
+- ``FVP_Base_Cortex-A72x4``
+- ``FVP_Base_Cortex-A73x4-A53x4``
+- ``FVP_Base_Cortex-A73x4``
+- ``FVP_CSS_SGM-775`` (Version 11.0, Build 11.0.36)
+
+Various AArch32 builds of this release has been tested on the following ARM
+`FVP`_\ s (64-bit host machine only):
+
+- ``FVP_Base_AEMv8A-AEMv8A`` (Version 8.5, Build 0.8.8502)
+- ``FVP_Base_Cortex-A32x4``
+
+The Foundation FVP can be downloaded free of charge. The Base FVPs can be
+licensed from ARM. See the `ARM FVP website`_.
+
+All the above platforms have been tested with `Linaro Release 17.04`_.
+
+This release also contains the following platform support:
+
+- HiKey and HiKey960 boards
+- MediaTek MT6795 and MT8173 SoCs
+- NVidia T132, T186 and T210 SoCs
+- QEMU emulator
+- RockChip RK3328, RK3368 and RK3399 SoCs
+- Socionext UniPhier SoC family
+- Xilinx Zynq UltraScale + MPSoC
+
+Still to Come
+~~~~~~~~~~~~~
+
+- More platform support.
+
+- Ongoing support for new architectural features, CPUs and System IP.
+
+- Ongoing support for new `PSCI`_, `SCMI`_ and TBBR features.
+
+- Ongoing security hardening, optimization and quality improvements.
+
+For a full list of detailed issues in the current code, please see the `Change
+Log`_ and the `GitHub issue tracker`_.
+
+Getting Started
+---------------
+
+Get the Trusted Firmware source code from `GitHub`_.
+
+See the `User Guide`_ for instructions on how to install, build and use
+the Trusted Firmware with the ARM `FVP`_\ s.
+
+See the `Firmware Design`_ for information on how the Trusted Firmware works.
+
+See the `Porting Guide`_ as well for information about how to use this
+software on another ARMv8-A platform.
+
+See the `Contributing Guidelines`_ for information on how to contribute to this
+project and the `Acknowledgments`_ file for a list of contributors to the
+project.
+
+Feedback and support
+~~~~~~~~~~~~~~~~~~~~
+
+ARM welcomes any feedback on Trusted Firmware. If you think you have found a
+security vulnerability, please report this using the process defined in the
+Trusted Firmware `Security Centre`_. For all other feedback, please use the
+`GitHub issue tracker`_.
+
+ARM licensees may contact ARM directly via their partner managers.
+
+--------------
+
+*Copyright (c) 2013-2017, ARM Limited and Contributors. All rights reserved.*
+
+.. _ARMv8-A: http://www.arm.com/products/processors/armv8-architecture.php
+.. _Secure Monitor: http://www.arm.com/products/processors/technologies/trustzone/tee-smc.php
+.. _Power State Coordination Interface (PSCI): PSCI_
+.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
+.. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
+.. _System Control and Management Interface: SCMI_
+.. _SCMI: http://infocenter.arm.com/help/topic/com.arm.doc.den0056a/DEN0056A_System_Control_and_Management_Interface.pdf
+.. _Juno ARM Development Platform: http://www.arm.com/products/tools/development-boards/versatile-express/juno-arm-development-platform.php
+.. _ARM FVP website: FVP_
+.. _FVP: https://developer.arm.com/products/system-design/fixed-virtual-platforms
+.. _Linaro Release 17.04: https://community.arm.com/dev-platforms/b/documents/posts/linaro-release-notes-deprecated#LinaroRelease17.04
+.. _OP-TEE Secure OS: https://github.com/OP-TEE/optee_os
+.. _NVidia Trusted Little Kernel: http://nv-tegra.nvidia.com/gitweb/?p=3rdparty/ote_partner/tlk.git;a=summary
+.. _Trusty Secure OS: https://source.android.com/security/trusty
+.. _GitHub: https://www.github.com/ARM-software/arm-trusted-firmware
+.. _GitHub issue tracker: https://github.com/ARM-software/tf-issues/issues
+.. _Security Centre: https://github.com/ARM-software/arm-trusted-firmware/wiki/ARM-Trusted-Firmware-Security-Centre
+.. _license: ./license.rst
+.. _Contributing Guidelines: ./contributing.rst
+.. _Acknowledgments: ./acknowledgements.rst
+.. _Firmware Design: ./docs/firmware-design.rst
+.. _Change Log: ./docs/change-log.rst
+.. _User Guide: ./docs/user-guide.rst
+.. _Porting Guide: ./docs/porting-guide.rst
