LuminaSensum/arm-trusted-firmware
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Convert documentation to reStructuredText

Browse source 
Due to recent issues in the rendering of the documentation on GitHub and
some long-standing issues like the lack of automatic table of content in
Markdown, the documentation has been converted to reStructuredText.
Basic constructs looks pretty similar to Markdown.

Automatically convert GitHub markdown documentation to reStructuredText
using pandoc.

Change-Id: If20b695acedc6d1b49c8d9fb64efd6b6ba23f4a9
Signed-off-by: Douglas Raillard <douglas.raillard@arm.com>
This commit is contained in:
Douglas Raillard 2017-06-28 15:23:03 +01:00
parent 7af4d2b6ae
commit 6f62574767
29 changed files with 13880 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
acknowledgements.rst Normal file
View file

@ -0,0 +1,16 @@
Contributor Acknowledgements
============================
Companies
---------
Linaro Limited
NVIDIA Corporation
Socionext Inc.
Xilinx, Inc.
Individuals
-----------

129
contributing.rst Normal file
View file

@ -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

96
docs/arm-sip-service.rst Normal file
View file

@ -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

937
docs/auth-framework.rst Normal file
View file

@ -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

1083
docs/change-log.rst Normal file
View file

File diff suppressed because it is too large Load diff

127
docs/cpu-specific-build-macros.rst Normal file
View file

@ -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

2443
docs/firmware-design.rst Normal file
View file

File diff suppressed because it is too large Load diff

412
docs/firmware-update.rst Normal file
View file

@ -0,0 +1,412 @@
ARM Trusted Firmware - Firmware Update Design Guide
===================================================
.. section-numbering::
:suffix: .
.. contents::
--------------
Introduction
------------
This document describes the design of the Firmware Update (FWU) feature, which
enables authenticated firmware to update firmware images from external
interfaces such as USB, UART, SD-eMMC, NAND, NOR or Ethernet to SoC Non-Volatile
memories such as NAND Flash, LPPDR2-NVM or any memory determined by the
platform. This feature functions even when the current firmware in the system
is corrupt or missing; it therefore may be used as a recovery mode. It may also
be complemented by other, higher level firmware update software.
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
parts of the Trusted Firmware (TF) TBBR implementation.
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.
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
some parts of FWU to be implemented in other secure and normal world images.
Platform code may choose which parts are implemented in which images but the
general expectation is:
- BL1 handles:
- Detection and initiation of the FWU boot flow.
- Copying images from non-secure to secure memory
- FWU image authentication
- Context switching between the normal and secure world during the FWU
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:
#. 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`_.
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|
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`_
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.
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.
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
BL1 to update its FWU image state. The BL1 image states and valid state
transitions are shown in the diagram below. Note that secure images have a more
complex state machine than non-secure images.
|FWU state machine|
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``.
- 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.
- 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.
- INTERRUPTED: This is the state of a secure, executable image after it has
requested BL1 to resume normal world execution.
BL1 SMC Interface
-----------------
BL1\_SMC\_CALL\_COUNT
~~~~~~~~~~~~~~~~~~~~~
::
Arguments:
uint32_t function ID : 0x0
Return:
uint32_t
This SMC returns the number of SMCs supported by BL1.
BL1\_SMC\_UID
~~~~~~~~~~~~~
::
Arguments:
uint32_t function ID : 0x1
Return:
UUID : 32 bits in each of w0-w3 (or r0-r3 for AArch32 callers)
This SMC returns the 128-bit `Universally Unique Identifier`_ for the
BL1 SMC service.
BL1\_SMC\_VERSION
~~~~~~~~~~~~~~~~~
::
Argument:
uint32_t function ID : 0x3
Return:
uint32_t : Bits [31:16] Major Version
Bits [15:0] Minor Version
This SMC returns the current version of the BL1 SMC service.
BL1\_SMC\_RUN\_IMAGE
~~~~~~~~~~~~~~~~~~~~
::
Arguments:
uint32_t function ID : 0x4
entry_point_info_t *ep_info
Return:
void
Pre-conditions:
if (normal world caller) synchronous exception
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
for BL1 to pass execution control to BL31.
FWU\_SMC\_IMAGE\_COPY
~~~~~~~~~~~~~~~~~~~~~
::
Arguments:
uint32_t function ID : 0x10
unsigned int image_id
uintptr_t image_addr
unsigned int block_size
unsigned int image_size
Return:
int : 0 (Success)
: -ENOMEM
: -EPERM
Pre-conditions:
if (image_id is invalid) return -EPERM
if (image_id is non-secure image) return -EPERM
if (image_id state is not (RESET or COPYING)) return -EPERM
if (secure world caller) return -EPERM
if (image_addr + block_size overflows) return -ENOMEM
if (image destination address + image_size overflows) return -ENOMEM
if (source block is in secure memory) return -ENOMEM
if (source block is not mapped into BL1) return -ENOMEM
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
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
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 destination address is provided by the platform code.
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
transitions to the COPYING state (depending on the previous state).
When using multiple blocks, the source blocks do not necessarily need to be in
contiguous memory.
Once the SMC is handled, BL1 returns from exception to the normal world caller.
FWU\_SMC\_IMAGE\_AUTH
~~~~~~~~~~~~~~~~~~~~~
::
Arguments:
uint32_t function ID : 0x11
unsigned int image_id
uintptr_t image_addr
unsigned int image_size
Return:
int : 0 (Success)
: -ENOMEM
: -EPERM
: -EAUTH
Pre-conditions:
if (image_id is invalid) return -EPERM
if (secure world caller)
if (image_id state is not RESET) return -EPERM
if (image_addr/image_size is not mappped into BL1) return -ENOMEM
else // normal world caller
if (image_id is secure image)
if (image_id state is not COPIED) return -EPERM
else // image_id is non-secure image
if (image_id state is not RESET) return -EPERM
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
state, BL1 authenticates the image from the secure memory that BL1 previously
copied the image into.
BL1 returns from exception to the caller. If authentication succeeds then BL1
sets the image state to AUTHENTICATED. If authentication fails then BL1 returns
the -EAUTH error and sets the image state back to RESET.
FWU\_SMC\_IMAGE\_EXECUTE
~~~~~~~~~~~~~~~~~~~~~~~~
::
Arguments:
uint32_t function ID : 0x12
unsigned int image_id
Return:
int : 0 (Success)
: -EPERM
Pre-conditions:
if (image_id is invalid) return -EPERM
if (secure world caller) return -EPERM
if (image_id is non-secure image) return -EPERM
if (image_id is non-executable image) return -EPERM
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
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
~~~~~~~~~~~~~~~~~~~~~~~
::
Arguments:
uint32_t function ID : 0x13
register_t image_param
Return:
register_t : image_param (Success)
: -EPERM
Pre-conditions:
if (normal world caller and no INTERRUPTED secure image) return -EPERM
This SMC resumes execution in the other security world while there is a secure
image in the EXECUTED/INTERRUPTED state.
For normal world callers, BL1 sets the previously interrupted secure image state
to EXECUTED. For secure world callers, BL1 sets the previously executing secure
image state to INTERRUPTED. In either case, BL1 saves the calling world's
context, restores the resuming world's context and returns from exception into
the resuming world. If the call is successful then the caller provided
``image_param`` is returned to the resumed world, otherwise an error code is
returned to the caller.
FWU\_SMC\_SEC\_IMAGE\_DONE
~~~~~~~~~~~~~~~~~~~~~~~~~~
::
Arguments:
uint32_t function ID : 0x14
Return:
int : 0 (Success)
: -EPERM
Pre-conditions:
if (normal world caller) return -EPERM
This SMC indicates completion of a previously executing secure image.
BL1 sets the previously executing secure image state to the RESET state,
restores the normal world context and returns from exception into the normal
world.
FWU\_SMC\_UPDATE\_DONE
~~~~~~~~~~~~~~~~~~~~~~
::
Arguments:
uint32_t function ID : 0x15
register_t client_cookie
Return:
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.
FWU\_SMC\_IMAGE\_RESET
~~~~~~~~~~~~~~~~~~~~~~
::
Arguments:
uint32_t function ID : 0x16
unsigned int image_id
Return:
int : 0 (Success)
: -EPERM
Pre-conditions:
if (secure world caller) return -EPERM
if (image in EXECUTED) return -EPERM
This SMC sets the state of an image to RESET and zeroes the memory used by it.
This is only allowed if the image is not being executed.
--------------
*Copyright (c) 2015-2017, ARM Limited and Contributors. All rights reserved.*
.. _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
.. |Flow Diagram| image:: diagrams/fwu_flow.png?raw=true
.. |FWU state machine| image:: diagrams/fwu_states.png?raw=true

1003
docs/interrupt-framework-design.rst Normal file
View file

File diff suppressed because it is too large Load diff

156
docs/plat/hikey.rst Normal file
View file

@ -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

172
docs/plat/hikey960.rst Normal file
View file

@ -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

98
docs/plat/nvidia-tegra.rst Normal file
View file

@ -0,0 +1,98 @@
Tegra SoCs - Overview
=====================
- .. 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
support ARMv8, executing both 64-bit Aarch64 code, and 32-bit Aarch32 code
including legacy ARMv7 applications. The Cortex-A57 processors each have
48 KB Instruction and 32 KB Data Level 1 caches; and have a 2 MB shared
Level 2 unified cache. The Cortex-A53 processors each have 32 KB Instruction
and 32 KB Data Level 1 caches; and have a 512 KB shared Level 2 unified cache.
- .. 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
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
cache, which services both cores.
Denver implements an innovative process called Dynamic Code Optimization,
which optimizes frequently used software routines at runtime into dense,
highly tuned microcode-equivalent routines. These are stored in a
dedicated, 128MB main-memory-based optimization cache. After being read
into the instruction cache, the optimized micro-ops are executed,
re-fetched and executed from the instruction cache as long as needed and
capacity allows.
Effectively, this reduces the need to re-optimize the software routines.
Instead of using hardware to extract the instruction-level parallelism
(ILP) inherent in the code, Denver extracts the ILP once via software
techniques, and then executes those routines repeatedly, thus amortizing
the cost of ILP extraction over the many execution instances.
Denver also features new low latency power-state transitions, in addition
to extensive power-gating and dynamic voltage and clock scaling based on
workloads.
Directory structure
===================
- plat/nvidia/tegra/common - Common code for all Tegra SoCs
- plat/nvidia/tegra/soc/txxx - Chip specific code
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
vendors to use the upstream code and include their dispatchers in the image
without changing any makefiles.
Preparing the BL31 image to run on Tegra SoCs
=============================================
.. 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
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;
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 configs
=============
- '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.

48
docs/plat/qemu.rst Normal file
View file

@ -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

124
docs/plat/socionext-uniphier.rst Normal file
View file

@ -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

67
docs/plat/xilinx-zynqmp.rst Normal file
View file

@ -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.

596
docs/platform-migration-guide.rst Normal file
View file

@ -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

2599
docs/porting-guide.rst Normal file
View file

File diff suppressed because it is too large Load diff

564
docs/psci-lib-integration-guide.rst Normal file
View file

@ -0,0 +1,564 @@
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
`section 4`_) 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
`section 4`_, 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 `section 3`_ 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
`section 4`_ (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`_.
#. .. rubric:: PSCI CPU context management
:name: 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
`section 5.2`_.
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
`section 5.2`_) 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 `section 5.4`_,
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
.. _section 4: #user-content-psci-library-interface
.. _section 3: #user-content-psci-cpu-context-management
.. _PSCI specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
.. _section 5.2: #user-content-cpu-context-management-api
.. _PSCI Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
.. _section 5.4: #user-content-secure-payload-power-management-callback
.. _Porting Guide: porting-guide.rst
.. _Firmware Design: ./firmware-design.rst

312
docs/psci-pd-tree.rst Normal file
View file

@ -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.*

166
docs/reset-design.rst Normal file
View file

@ -0,0 +1,166 @@
ARM Trusted Firmware Reset Design
=================================
.. section-numbering::
:suffix: .
.. 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
provides greater implementation details around the reset code, specifically
for the cold boot path.
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
guide the platform integrator by indicating which build options exclude which
steps, depending on the capability of the platform.
Note: If BL31 is used as the Trusted Firmware entry point instead of BL1, the
diagram above is still relevant, as all these operations will occur in BL31 in
this case. Please refer to section 6 "Using BL31 entrypoint as the reset
address" for more information.
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
they reset. Further logic is then required to identify whether it is a cold or
warm boot to direct CPUs to the right execution path.
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
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``.
This option only affects the TF reset image, which is BL1 by default or BL31 if
``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``.
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
shared amongst CPUs. This is done by nominating one of the CPUs as the primary,
which is responsible for initialising shared hardware and coordinating the boot
flow with the other CPUs.
If the platform guarantees that only a single CPU will ever be brought up then
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
option only affects the TF reset image, which is BL1 by default or BL31 if
``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``.
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:
|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``.
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
on the SoC, rather than by BL1 and BL2 running on the primary application
processor. For this type of SoC it is desirable for the application processor
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
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``
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
images might be done by the Trusted Boot Firmware or by platform code in BL31.
Although the ARM FVP platform does not support programming the reset base
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.
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.
The ``RESET_TO_BL31`` configuration requires some additions and changes in the
BL31 functionality:
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
same way.
In the default, unoptimised BL31 reset flow, on a warm boot a CPU is directed
to the PSCI implementation via a platform defined mechanism. On a cold boot,
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
~~~~~~~~~~~~~~~~~~~~~~~
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.
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.*
.. _Firmware Design: firmware-design.rst
.. _User Guide: user-guide.rst
.. |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

316
docs/rt-svc-writers-guide.rst Normal file
View file

@ -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

14
docs/spd/optee-dispatcher.rst Normal file
View file

@ -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

76
docs/spd/tlk-dispatcher.rst Normal file
View file

@ -0,0 +1,76 @@
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
Trusted Firmware starts supporting Tegra, the dispatcher code can only be
compiled for other platforms.
In order to compile TLK-D, we need a BL32 image to be present. Since, TLKD
just needs to compile, any BL32 image would do. To use TLK as the BL32, please
refer to the "Build TLK" section.
Once a BL32 is ready, TLKD can be included in the image by adding "SPD=tlkd"
to the build command.
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).
You can download the LK modular embedded preemptive kernel for use on ARM,
x86, and AVR32 systems from https://github.com/travisg/lk
NVIDIA implemented its Trusted Little Kernel (TLK) technology, designed as a
free and open-source trusted execution environment (OTE).
TLK features include:
• Small, pre-emptive kernel
• Supports multi-threading, IPCs, and thread scheduling
• Added TrustZone features
• Added Secure Storage
• Under MIT/FreeBSD license
NVIDIA extensions to Little Kernel (LK) include:
• User mode
• Address-space separation for TAs
• TLK Client Application (CA) library
• TLK TA library
• Crypto library (encrypt/decrypt, key handling) via OpenSSL
• Linux kernel driver
• Cortex A9/A15 support
• Power Management
• TrustZone memory carve-out (reconfigurable)
• Page table management
• 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\_.
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.
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)
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

15
docs/spd/trusty-dispatcher.rst Normal file
View file

@ -0,0 +1,15 @@
Trusty Dispatcher
=================
Trusty is a a set of software components, supporting a Trusted Execution
Environment (TEE) on mobile devices, published and maintained by Google.
Detailed information and build instructions can be found on the Android
Open Source Project (AOSP) webpage for Trusty hosted at
https://source.android.com/security/trusty
Supported platforms
===================
Out of all the platforms supported by the ARM Trusted Firmware, Trusty is
verified and supported by NVIDIA's Tegra SoCs.

238
docs/trusted-board-boot.rst Normal file
View file

@ -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

1737
docs/user-guide.rst Normal file
View file

File diff suppressed because it is too large Load diff

38
license.rst Normal file
View file

@ -0,0 +1,38 @@
Copyright (c) 2013-2017, ARM Limited and Contributors. All rights reserved.
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 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.
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
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(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
This enables machine processing of license information based on the SPDX
License Identifiers that are here available: http://spdx.org/licenses/

102
maintainers.rst Normal file
View file

@ -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

196
readme.rst Normal file
View file

@ -0,0 +1,196 @@
ARM Trusted Firmware - version 1.3
==================================
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) and `SMC Calling Convention`_. 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`_ 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`_.
- 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`_ 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`_.
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`_.
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.*
.. _ARMv8-A: http://www.arm.com/products/processors/armv8-architecture.php
.. _Secure Monitor: http://www.arm.com/products/processors/technologies/trustzone/tee-smc.php
.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
.. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
.. _license: ./license.rst
.. _Contributing Guidelines: ./contributing.rst
.. _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
.. _Firmware Design: ./docs/firmware-design.rst
.. _Change Log: ./docs/change-log.rst
.. _Juno ARM Development Platform: http://www.arm.com/products/tools/development-boards/versatile-express/juno-arm-development-platform.php
.. _Linaro Release 16.06: https://community.arm.com/docs/DOC-10952#jive_content_id_Linaro_Release_1606
.. _FVP: http://www.arm.com/fvp
.. _www.arm.com/fvp: http://www.arm.com/fvp
.. _GitHub issue tracker: https://github.com/ARM-software/tf-issues/issues
.. _GitHub: https://www.github.com/ARM-software/arm-trusted-firmware
.. _User Guide: ./docs/user-guide.rst
.. _Porting Guide: ./docs/porting-guide.rst
.. _Acknowledgments: ./acknowledgements.rst