diff options
| author | Douglas Raillard <douglas.raillard@arm.com> | 2017-06-29 16:22:45 +0100 |
|---|---|---|
| committer | Douglas Raillard <douglas.raillard@arm.com> | 2017-06-29 16:22:45 +0100 |
| commit | 06fb4278e6abe0e71fba9eea69e1220c9d43b5ff (patch) | |
| tree | 251b6c1a65cc4e2a4a7ce07fe2441a84dfa440e3 | |
| parent | 668c5022e5edf6edf36180d04e9ef271829c94b5 (diff) | |
Remove Markdown documentation
Removed Markdown documents as they have been converted to
reStructuredText.
Change-Id: I3148222eb31258f158f64de4ddcdda4b232ce483
Signed-off-by: Douglas Raillard <douglas.raillard@arm.com>
29 files changed, 0 insertions, 13307 deletions
diff --git a/acknowledgements.md b/acknowledgements.md deleted file mode 100644 index 028f321d..00000000 --- a/acknowledgements.md +++ /dev/null @@ -1,15 +0,0 @@ -Contributor Acknowledgements -============================ - -Companies ---------- -Linaro Limited - -NVIDIA Corporation - -Socionext Inc. - -Xilinx, Inc. - -Individuals ------------ diff --git a/contributing.md b/contributing.md deleted file mode 100644 index d1be2810..00000000 --- a/contributing.md +++ /dev/null @@ -1,122 +0,0 @@ -Contributing to ARM Trusted Firmware -==================================== - -Getting Started ---------------- - -* Make sure you have a [GitHub account]. -* Create an [issue] for your work if one does not already exist. This gives - everyone visibility of whether others are working on something similar. ARM - licensees may contact ARM directly via their partner managers instead if - they prefer. - * Note that the [issue] tracker for this project is in a separate - [issue tracking repository]. Please follow the guidelines in that - repository. - * If you intend to include Third Party IP in your contribution, please - raise a separate [issue] for this and ensure that the changes that - include Third Party IP are made on a separate topic branch. -* [Fork][] [arm-trusted-firmware][] on GitHub. -* Clone the fork to your own machine. -* Create a local topic branch based on the [arm-trusted-firmware][] `master` - branch. - - -Making Changes --------------- - -* Make commits of logical units. See these general [Git guidelines] for - contributing to a project. -* Follow the [Linux coding style]; this style is enforced for the ARM Trusted - Firmware project (style errors only, not warnings). - * Use the checkpatch.pl script provided with the Linux source tree. A - Makefile target is provided for convenience (see section 2 in the - [User Guide]). -* Keep the commits on topic. If you need to fix another bug or make another - enhancement, please create a separate [issue] and address it on a separate - topic branch. -* Avoid long commit series. If you do have a long series, consider whether - some commits should be squashed together or addressed in a separate topic. -* Make sure your commit messages are in the proper format. If a commit fixes - a GitHub [issue], include a reference (e.g. - "fixes arm-software/tf-issues#45"); this ensures the [issue] is - [automatically closed] when merged into the [arm-trusted-firmware] `master` - branch. -* Where appropriate, please update the documentation. - * Consider whether the [User Guide], [Porting Guide], [Firmware Design] or - other in-source documentation needs updating. - * Ensure that each changed file has the correct copyright and license - information. Files that entirely consist of contributions to this - project should have the copyright notice and BSD-3-Clause SPDX license - identifier as shown in [license.md](./license.md). Files that contain - changes to imported Third Party IP should contain a notice as follows, - with the original copyright and license text retained: - ``` - Portions copyright (c) [XXXX-]YYYY, ARM Limited and Contributors. All rights reserved. - ``` - where XXXX is the year of first contribution (if different to YYYY) and - YYYY is the year of most recent contribution. - * If not done previously, you may add your name or your company name to - the [Acknowledgements] file. - * If you are submitting new files that you intend to be the technical - sub-maintainer for (for example, a new platform port), then also update - the [Maintainers] file. - * For topics with multiple commits, you should make all documentation - changes (and nothing else) in the last commit of the series. Otherwise, - include the documentation changes within the single commit. -* Please test your changes. As a minimum, ensure UEFI boots to the shell on - the Foundation FVP. See [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)][DCO]. -* Push your local changes to your fork of the repository. -* Submit a [pull request] to the [arm-trusted-firmware] `integration` branch. - * The changes in the [pull request] will then undergo further review and - testing by the [Maintainers]. Any review comments will be made as - comments on the [pull request]. This may require you to do some rework. -* When the changes are accepted, the [Maintainers] will integrate them. - * Typically, the [Maintainers] will merge the [pull request] into the - `integration` branch within the GitHub UI, creating a merge commit. - * Please avoid creating merge commits in the [pull request] itself. - * If the [pull request] is not based on a recent commit, the [Maintainers] - may rebase it onto the `master` branch first, or ask you to do this. - * If the [pull request] cannot be automatically merged, the [Maintainers] - will ask you to rebase it onto the `master` branch. - * After final integration testing, the [Maintainers] will push your merge - commit to the `master` branch. If a problem is found during integration, - the merge commit will be removed from the `integration` branch and the - [Maintainers] will ask you to create a new pull request to resolve the - problem. - * Please do not delete your topic branch until it is safely merged into - the `master` branch. - - -- - - - - - - - - - - - - - - - - - - - - - - - - - - -_Copyright (c) 2013-2017, ARM Limited and Contributors. All rights reserved._ - - -[User Guide]: ./docs/user-guide.md -[Running the software on FVP]: ./docs/user-guide.md#8--running-the-software-on-fvp -[Porting Guide]: ./docs/porting-guide.md -[Firmware Design]: ./docs/firmware-design.md -[Acknowledgements]: ./acknowledgements.md "Contributor acknowledgements" -[DCO]: ./dco.txt -[Maintainers]: ./maintainers.md - -[GitHub account]: https://github.com/signup/free -[Fork]: https://help.github.com/articles/fork-a-repo -[issue tracking repository]: https://github.com/ARM-software/tf-issues -[issue]: https://github.com/ARM-software/tf-issues/issues -[pull request]: https://help.github.com/articles/using-pull-requests -[automatically closed]: https://help.github.com/articles/closing-issues-via-commit-messages -[Git guidelines]: http://git-scm.com/book/ch5-2.html -[Linux coding style]: https://www.kernel.org/doc/Documentation/CodingStyle -[arm-trusted-firmware]: https://github.com/ARM-software/arm-trusted-firmware diff --git a/docs/arm-sip-service.md b/docs/arm-sip-service.md deleted file mode 100644 index 1d15b85e..00000000 --- a/docs/arm-sip-service.md +++ /dev/null @@ -1,93 +0,0 @@ - -ARM SiP Service -=============== - -This document enumerates and describes the ARM SiP (Silicon Provider) services. - -SiP services are non-standard, platform-specific services offered by the silicon -implementer or platform provider. They are accessed via. `SMC` ("SMC calls") -instruction executed from Exception Levels below EL3. SMC calls for SiP -services: - -* Follow [SMC Calling Convention][SMCCC]; -* Use SMC function IDs that fall in the SiP range, which are `0xc2000000` - - `0xc200ffff` for 64-bit calls, and `0x82000000` - `0x8200ffff` for 32-bit - calls. - -The ARM SiP implementation offers the following services: - -* Performance Measurement Framework (PMF) -* Execution State Switching service - -Source definitions for ARM SiP service are located in the `arm_sip_svc.h` header -file. - -Performance Measurement Framework (PMF) ---------------------------------------- - -The [Performance Measurement Framework](./firmware-design.md#13--performance-measurement-framework) -allows callers to retrieve timestamps captured at various paths in ARM Trusted -Firmware execution. It's described in detail in [Firmware Design document][Firmware Design]. - -Execution State Switching service ---------------------------------- - -Execution State Switching service provides a mechanism for a non-secure lower -Exception Level (either EL2, or NS EL1 if EL2 isn't implemented) to request to -switch its execution state (a.k.a. Register Width), either from AArch64 to -AArch32, or from AArch32 to AArch64, for the calling CPU. This service is only -available when ARM Trusted Firmware is built for AArch64 (i.e. when build option -`ARCH` is set to `aarch64`). - -### `ARM_SIP_SVC_EXE_STATE_SWITCH` - - Arguments: - uint32_t Function ID - uint32_t PC hi - uint32_t PC lo - uint32_t Cookie hi - uint32_t Cookie lo - - Return: - uint32_t - -The function ID parameter must be `0x82000020`. It uniquely identifies the -Execution State Switching service being requested. - -The parameters _PC hi_ and _PC lo_ defines upper and lower words, respectively, -of the entry point (physical address) at which execution should start, after -Execution State has been switched. When calling from AArch64, _PC hi_ must be 0. - -When execution starts at the supplied entry point after Execution State has been -switched, the parameters _Cookie hi_ and _Cookie lo_ are passed in CPU registers -0 and 1, respectively. When calling from AArch64, _Cookie hi_ must be 0. - -This call can only be made on the primary CPU, before any secondaries were -brought up with `CPU_ON` PSCI call. Otherwise, the call will always fail. - -The effect of switching execution state is as if the Exception Level were -entered for the first time, following power on. This means CPU registers that -have a defined reset value by the Architecture will assume that value. Other -registers should not be expected to hold their values before the call was made. -CPU endianness, however, is preserved from the previous execution state. Note -that this switches the execution state of the calling CPU only. This is not a -substitute for PSCI `SYSTEM_RESET`. - -The service may return the following error codes: - - - `STATE_SW_E_PARAM`: If any of the parameters were deemed invalid for - a specific request. - - `STATE_SW_E_DENIED`: If the call is not successful, or when ARM Trusted - Firmware is built for AArch32. - -If the call is successful, the caller wouldn't observe the SMC returning. -Instead, execution starts at the supplied entry point, with the CPU registers 0 -and 1 populated with the supplied _Cookie hi_ and _Cookie lo_ values, -respectively. - -- - - - - - - - - - - - - - - - - - - - - - - - - - - -_Copyright (c) 2017, ARM Limited and Contributors. All rights reserved._ - -[Firmware Design]: ./firmware-design.md -[SMCCC]: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html "SMC Calling Convention PDD (ARM DEN 0028A)" diff --git a/docs/auth-framework.md b/docs/auth-framework.md deleted file mode 100644 index b416acfc..00000000 --- a/docs/auth-framework.md +++ /dev/null @@ -1,925 +0,0 @@ -Abstracting a Chain of Trust -============================ - -Contents : - -1. [Introduction](#1--introduction) -2. [Framework design](#2--framework-design) -3. [Specifying a Chain of Trust](#3--specifying-a-chain-of-trust) -4. [Implementation example](#4--implementation-example) - - -1. Introduction ----------------- - -The aim of this document is to describe the authentication framework implemented -in the Trusted Firmware. This framework fulfills the following requirements: - -1. It should be possible for a platform port to specify the Chain of Trust in - terms of certificate hierarchy and the mechanisms used to verify a - particular image/certificate. - -2. The framework should distinguish between: - - - The mechanism used to encode and transport information, e.g. DER encoded - X.509v3 certificates to ferry Subject Public Keys, hashes and non-volatile - counters. - - - The mechanism used to verify the transported information i.e. the - cryptographic libraries. - -The framework has been designed following a modular approach illustrated in the -next diagram: - -``` - +---------------+---------------+------------+ - | Trusted | Trusted | Trusted | - | Firmware | Firmware | Firmware | - | Generic | IO Framework | Platform | - | Code i.e. | (IO) | Port | - | BL1/BL2 (GEN) | | (PP) | - +---------------+---------------+------------+ - ^ ^ ^ - | | | - v v v - +-----------+ +-----------+ +-----------+ - | | | | | Image | - | Crypto | | Auth | | Parser | - | Module |<->| Module |<->| Module | - | (CM) | | (AM) | | (IPM) | - | | | | | | - +-----------+ +-----------+ +-----------+ - ^ ^ - | | - v v - +----------------+ +-----------------+ - | Cryptographic | | Image Parser | - | Libraries (CL) | | Libraries (IPL) | - +----------------+ +-----------------+ - | | - | | - | | - v v - +-----------------+ - | Misc. Libs e.g. | - | ASN.1 decoder | - | | - +-----------------+ - - DIAGRAM 1. -``` - -This document describes the inner details of the authentication framework and -the abstraction mechanisms available to specify a Chain of Trust. - - -2. Framework design --------------------- - -This section describes some aspects of the framework design and the rationale -behind them. These aspects are key to verify a Chain of Trust. - -### 2.1 Chain of Trust - -A CoT is basically a sequence of authentication images which usually starts with -a root of trust and culminates in a single data image. The following diagram -illustrates how this maps to a CoT for the BL31 image described in the -TBBR-Client specification. - -``` - +------------------+ +-------------------+ - | ROTPK/ROTPK Hash |------>| Trusted Key | - +------------------+ | Certificate | - | (Auth Image) | - /+-------------------+ - / | - / | - / | - / | - L v - +------------------+ +-------------------+ - | Trusted World |------>| BL31 Key | - | Public Key | | Certificate | - +------------------+ | (Auth Image) | - +-------------------+ - / | - / | - / | - / | - / v - +------------------+ L +-------------------+ - | BL31 Content |------>| BL31 Content | - | Certificate PK | | Certificate | - +------------------+ | (Auth Image) | - +-------------------+ - / | - / | - / | - / | - / v - +------------------+ L +-------------------+ - | BL31 Hash |------>| BL31 Image | - | | | (Data Image) | - +------------------+ | | - +-------------------+ - - DIAGRAM 2. -``` - -The root of trust is usually a public key (ROTPK) that has been burnt in the -platform and cannot be modified. - -### 2.2 Image types - -Images in a CoT are categorised as authentication and data images. An -authentication image contains information to authenticate a data image or -another authentication image. A data image is usually a boot loader binary, but -it could be any other data that requires authentication. - -### 2.3 Component responsibilities - -For every image in a Chain of Trust, the following high level operations are -performed to verify it: - -1. Allocate memory for the image either statically or at runtime. - -2. Identify the image and load it in the allocated memory. - -3. Check the integrity of the image as per its type. - -4. Authenticate the image as per the cryptographic algorithms used. - -5. If the image is an authentication image, extract the information that will - be used to authenticate the next image in the CoT. - -In Diagram 1, each component is responsible for one or more of these operations. -The responsibilities are briefly described below. - - -#### 2.2.1 TF Generic code and IO framework (GEN/IO) - -These components are responsible for initiating the authentication process for a -particular image in BL1 or BL2. For each BL image that requires authentication, -the Generic code asks recursively the Authentication module what is the parent -image until either an authenticated image or the ROT is reached. Then the -Generic code calls the IO framewotk to load the image and calls the -Authentication module to authenticate it, following the CoT from ROT to Image. - - -#### 2.2.2 TF Platform Port (PP) - -The platform is responsible for: - -1. Specifying the CoT for each image that needs to be authenticated. Details of - how a CoT can be specified by the platform are explained later. The platform - also specifies the authentication methods and the parsing method used for - each image. - -2. Statically allocating memory for each parameter in each image which is - used for verifying the CoT, e.g. memory for public keys, hashes etc. - -3. Providing the ROTPK or a hash of it. - -4. Providing additional information to the IPM to enable it to identify and - extract authentication parameters contained in an image, e.g. if the - parameters are stored as X509v3 extensions, the corresponding OID must be - provided. - -5. Fulfill any other memory requirements of the IPM and the CM (not currently - described in this document). - -6. Export functions to verify an image which uses an authentication method that - cannot be interpreted by the CM, e.g. if an image has to be verified using a - NV counter, then the value of the counter to compare with can only be - provided by the platform. - -7. Export a custom IPM if a proprietary image format is being used (described - later). - - -#### 2.2.3 Authentication Module (AM) - -It is responsible for: - -1. Providing the necessary abstraction mechanisms to describe a CoT. Amongst - other things, the authentication and image parsing methods must be specified - by the PP in the CoT. - -2. Verifying the CoT passed by GEN by utilising functionality exported by the - PP, IPM and CM. - -3. Tracking which images have been verified. In case an image is a part of - multiple CoTs then it should be verified only once e.g. the Trusted World - Key Certificate in the TBBR-Client spec. contains information to verify - SCP_BL2, BL31, BL32 each of which have a separate CoT. (This - responsibility has not been described in this document but should be - trivial to implement). - -4. Reusing memory meant for a data image to verify authentication images e.g. - in the CoT described in Diagram 2, each certificate can be loaded and - verified in the memory reserved by the platform for the BL31 image. By the - time BL31 (the data image) is loaded, all information to authenticate it - will have been extracted from the parent image i.e. BL31 content - certificate. It is assumed that the size of an authentication image will - never exceed the size of a data image. It should be possible to verify this - at build time using asserts. - - -#### 2.2.4 Cryptographic Module (CM) - -The CM is responsible for providing an API to: - -1. Verify a digital signature. -2. Verify a hash. - -The CM does not include any cryptography related code, but it relies on an -external library to perform the cryptographic operations. A Crypto-Library (CL) -linking the CM and the external library must be implemented. The following -functions must be provided by the CL: - -``` -void (*init)(void); -int (*verify_signature)(void *data_ptr, unsigned int data_len, - void *sig_ptr, unsigned int sig_len, - void *sig_alg, unsigned int sig_alg_len, - void *pk_ptr, unsigned int pk_len); -int (*verify_hash)(void *data_ptr, unsigned int data_len, - void *digest_info_ptr, unsigned int digest_info_len); -``` - -These functions are registered in the CM using the macro: -``` -REGISTER_CRYPTO_LIB(_name, _init, _verify_signature, _verify_hash); -``` - -`_name` must be a string containing the name of the CL. This name is used for -debugging purposes. - -#### 2.2.5 Image Parser Module (IPM) - -The IPM is responsible for: - -1. Checking the integrity of each image loaded by the IO framework. -2. Extracting parameters used for authenticating an image based upon a - description provided by the platform in the CoT descriptor. - -Images may have different formats (for example, authentication images could be -x509v3 certificates, signed ELF files or any other platform specific format). -The IPM allows to register an Image Parser Library (IPL) for every image format -used in the CoT. This library must implement the specific methods to parse the -image. The IPM obtains the image format from the CoT and calls the right IPL to -check the image integrity and extract the authentication parameters. - -See Section "Describing the image parsing methods" for more details about the -mechanism the IPM provides to define and register IPLs. - - -### 2.3 Authentication methods - -The AM supports the following authentication methods: - -1. Hash -2. Digital signature - -The platform may specify these methods in the CoT in case it decides to define -a custom CoT instead of reusing a predefined one. - -If a data image uses multiple methods, then all the methods must be a part of -the same CoT. The number and type of parameters are method specific. These -parameters should be obtained from the parent image using the IPM. - -1. Hash - - Parameters: - - 1. A pointer to data to hash - 2. Length of the data - 4. A pointer to the hash - 5. Length of the hash - - The hash will be represented by the DER encoding of the following ASN.1 - type: - - ``` - DigestInfo ::= SEQUENCE { - digestAlgorithm DigestAlgorithmIdentifier, - digest Digest - } - ``` - - This ASN.1 structure makes it possible to remove any assumption about the - type of hash algorithm used as this information accompanies the hash. This - should allow the Cryptography Library (CL) to support multiple hash - algorithm implementations. - -2. Digital Signature - - Parameters: - - 1. A pointer to data to sign - 2. Length of the data - 3. Public Key Algorithm - 4. Public Key value - 5. Digital Signature Algorithm - 6. Digital Signature value - - The Public Key parameters will be represented by the DER encoding of the - following ASN.1 type: - - ``` - SubjectPublicKeyInfo ::= SEQUENCE { - algorithm AlgorithmIdentifier{PUBLIC-KEY,{PublicKeyAlgorithms}}, - subjectPublicKey BIT STRING } - ``` - - The Digital Signature Algorithm will be represented by the DER encoding of - the following ASN.1 types. - - ``` - AlgorithmIdentifier {ALGORITHM:IOSet } ::= SEQUENCE { - algorithm ALGORITHM.&id({IOSet}), - parameters ALGORITHM.&Type({IOSet}{@algorithm}) OPTIONAL - } - ``` - - The digital signature will be represented by: - ``` - signature ::= BIT STRING - ``` - -The authentication framework will use the image descriptor to extract all the -information related to authentication. - - -3. Specifying a Chain of Trust -------------------------------- - -A CoT can be described as a set of image descriptors linked together in a -particular order. The order dictates the sequence in which they must be -verified. Each image has a set of properties which allow the AM to verify it. -These properties are described below. - -The PP is responsible for defining a single or multiple CoTs for a data image. -Unless otherwise specified, the data structures described in the following -sections are populated by the PP statically. - - -### 3.1 Describing the image parsing methods - -The parsing method refers to the format of a particular image. For example, an -authentication image that represents a certificate could be in the X.509v3 -format. A data image that represents a boot loader stage could be in raw binary -or ELF format. The IPM supports three parsing methods. An image has to use one -of the three methods described below. An IPL is responsible for interpreting a -single parsing method. There has to be one IPL for every method used by the -platform. - -1. Raw format: This format is effectively a nop as an image using this method - is treated as being in raw binary format e.g. boot loader images used by ARM - TF. This method should only be used by data images. - -2. X509V3 method: This method uses industry standards like X.509 to represent - PKI certificates (authentication images). It is expected that open source - libraries will be available which can be used to parse an image represented - by this method. Such libraries can be used to write the corresponding IPL - e.g. the X.509 parsing library code in mbed TLS. - -3. Platform defined method: This method caters for platform specific - proprietary standards to represent authentication or data images. For - example, The signature of a data image could be appended to the data image - raw binary. A header could be prepended to the combined blob to specify the - extents of each component. The platform will have to implement the - corresponding IPL to interpret such a format. - -The following enum can be used to define these three methods. - -``` -typedef enum img_type_enum { - IMG_RAW, /* Binary image */ - IMG_PLAT, /* Platform specific format */ - IMG_CERT, /* X509v3 certificate */ - IMG_MAX_TYPES, -} img_type_t; -``` - -An IPL must provide functions with the following prototypes: - -``` -void init(void); -int check_integrity(void *img, unsigned int img_len); -int get_auth_param(const auth_param_type_desc_t *type_desc, - void *img, unsigned int img_len, - void **param, unsigned int *param_len); -``` - -An IPL for each type must be registered using the following macro: - -``` -REGISTER_IMG_PARSER_LIB(_type, _name, _init, _check_int, _get_param) -``` - -* `_type`: one of the types described above. -* `_name`: a string containing the IPL name for debugging purposes. -* `_init`: initialization function pointer. -* `_check_int`: check image integrity function pointer. -* `_get_param`: extract authentication parameter funcion pointer. - -The `init()` function will be used to initialize the IPL. - -The `check_integrity()` function is passed a pointer to the memory where the -image has been loaded by the IO framework and the image length. It should ensure -that the image is in the format corresponding to the parsing method and has not -been tampered with. For example, RFC-2459 describes a validation sequence for an -X.509 certificate. - -The `get_auth_param()` function is passed a parameter descriptor containing -information about the parameter (`type_desc` and `cookie`) to identify and -extract the data corresponding to that parameter from an image. This data will -be used to verify either the current or the next image in the CoT sequence. - -Each image in the CoT will specify the parsing method it uses. This information -will be used by the IPM to find the right parser descriptor for the image. - - -### 3.2 Describing the authentication method(s) - -As part of the CoT, each image has to specify one or more authentication methods -which will be used to verify it. As described in the Section "Authentication -methods", there are three methods supported by the AM. - -``` -typedef enum { - AUTH_METHOD_NONE, - AUTH_METHOD_HASH, - AUTH_METHOD_SIG, - AUTH_METHOD_NUM -} auth_method_type_t; -``` - -The AM defines the type of each parameter used by an authentication method. It -uses this information to: - -1. Specify to the `get_auth_param()` function exported by the IPM, which - parameter should be extracted from an image. - -2. Correctly marshall the parameters while calling the verification function - exported by the CM and PP. - -3. Extract authentication parameters from a parent image in order to verify a - child image e.g. to verify the certificate image, the public key has to be - obtained from the parent image. - -``` -typedef enum { - AUTH_PARAM_NONE, - AUTH_PARAM_RAW_DATA, /* Raw image data */ - AUTH_PARAM_SIG, /* The image signature */ - AUTH_PARAM_SIG_ALG, /* The image signature algorithm */ - AUTH_PARAM_HASH, /* A hash (including the algorithm) */ - AUTH_PARAM_PUB_KEY, /* A public key */ -} auth_param_type_t; -``` - -The AM defines the following structure to identify an authentication parameter -required to verify an image. - -``` -typedef struct auth_param_type_desc_s { - auth_param_type_t type; - void *cookie; -} auth_param_type_desc_t; -``` - -`cookie` is used by the platform to specify additional information to the IPM -which enables it to uniquely identify the parameter that should be extracted -from an image. For example, the hash of a BL3x image in its corresponding -content certificate is stored in an X509v3 custom extension field. An extension -field can only be identified using an OID. In this case, the `cookie` could -contain the pointer to the OID defined by the platform for the hash extension -field while the `type` field could be set to `AUTH_PARAM_HASH`. A value of 0 for -the `cookie` field means that it is not used. - -For each method, the AM defines a structure with the parameters required to -verify the image. - -``` -/* - * Parameters for authentication by hash matching - */ -typedef struct auth_method_param_hash_s { - auth_param_type_desc_t *data; /* Data to hash */ - auth_param_type_desc_t *hash; /* Hash to match with */ -} auth_method_param_hash_t; - -/* - * Parameters for authentication by signature - */ -typedef struct auth_method_param_sig_s { - auth_param_type_desc_t *pk; /* Public key */ - auth_param_type_desc_t *sig; /* Signature to check */ - auth_param_type_desc_t *alg; /* Signature algorithm */ - auth_param_type_desc_t *tbs; /* Data signed */ -} auth_method_param_sig_t; - -``` - -The AM defines the following structure to describe an authentication method for -verifying an image - -``` -/* - * Authentication method descriptor - */ -typedef struct auth_method_desc_s { - auth_method_type_t type; - union { - auth_method_param_hash_t hash; - auth_method_param_sig_t sig; - } param; -} auth_method_desc_t; -``` - -Using the method type specified in the `type` field, the AM finds out what field -needs to access within the `param` union. - -### 3.3 Storing Authentication parameters - -A parameter described by `auth_param_type_desc_t` to verify an image could be -obtained from either the image itself or its parent image. The memory allocated -for loading the parent image will be reused for loading the child image. Hence -parameters which are obtained from the parent for verifying a child image need -to have memory allocated for them separately where they can be stored. This -memory must be statically allocated by the platform port. - -The AM defines the following structure to store the data corresponding to an -authentication parameter. - -``` -typedef struct auth_param_data_desc_s { - void *auth_param_ptr; - unsigned int auth_param_len; -} auth_param_data_desc_t; -``` - -The `auth_param_ptr` field is initialized by the platform. The `auth_param_len` -field is used to specify the length of the data in the memory. - -For parameters that can be obtained from the child image itself, the IPM is -responsible for populating the `auth_param_ptr` and `auth_param_len` fields -while executing the `img_get_auth_param()` function. - -The AM defines the following structure to enable an image to describe the -parameters that should be extracted from it and used to verify the next image -(child) in a CoT. - -``` -typedef struct auth_param_desc_s { - auth_param_type_desc_t type_desc; - auth_param_data_desc_t data; -} auth_param_desc_t; -``` - -### 3.4 Describing an image in a CoT - -An image in a CoT is a consolidation of the following aspects of a CoT described -above. - -1. A unique identifier specified by the platform which allows the IO framework - to locate the image in a FIP and load it in the memory reserved for the data - image in the CoT. - -2. A parsing method which is used by the AM to find the appropriate IPM. - -3. Authentication methods and their parameters as described in the previous - section. These are used to verify the current image. - -4. Parameters which are used to verify the next image in the current CoT. These - parameters are specified only by authentication images and can be extracted - from the current image once it has been verified. - -The following data structure describes an image in a CoT. -``` -typedef struct auth_img_desc_s { - unsigned int img_id; - const struct auth_img_desc_s *parent; - img_type_t img_type; - auth_method_desc_t img_auth_methods[AUTH_METHOD_NUM]; - auth_param_desc_t authenticated_data[COT_MAX_VERIFIED_PARAMS]; -} auth_img_desc_t; -``` -A CoT is defined as an array of `auth_image_desc_t` structures linked together -by the `parent` field. Those nodes with no parent must be authenticated using -the ROTPK stored in the platform. - - -4. Implementation example --------------------------- - -This section is a detailed guide explaining a trusted boot implementation using -the authentication framework. This example corresponds to the Applicative -Functional Mode (AFM) as specified in the TBBR-Client document. It is -recommended to read this guide along with the source code. - -### 4.1 The TBBR CoT - -The CoT can be found in `drivers/auth/tbbr/tbbr_cot.c`. This CoT consists of an -array of image descriptors and it is registered in the framework using the macro -`REGISTER_COT(cot_desc)`, where 'cot_desc' must be the name of the array -(passing a pointer or any other type of indirection will cause the registration -process to fail). - -The number of images participating in the boot process depends on the CoT. There -is, however, a minimum set of images that are mandatory in the Trusted Firmware -and thus all CoTs must present: - -* `BL2` -* `SCP_BL2` (platform specific) -* `BL31` -* `BL32` (optional) -* `BL33` - -The TBBR specifies the additional certificates that must accompany these images -for a proper authentication. Details about the TBBR CoT may be found in the -[Trusted Board Boot] document. - -Following the [Platform Porting Guide], a platform must provide unique -identifiers for all the images and certificates that will be loaded during the -boot process. If a platform is using the TBBR as a reference for trusted boot, -these identifiers can be obtained from `include/common/tbbr/tbbr_img_def.h`. -ARM platforms include this file in `include/plat/arm/common/arm_def.h`. Other -platforms may also include this file or provide their own identifiers. - -**Important**: the authentication module uses these identifiers to index the -CoT array, so the descriptors location in the array must match the identifiers. - -Each image descriptor must specify: - -* `img_id`: the corresponding image unique identifier defined by the platform. -* `img_type`: the image parser module uses the image type to call the proper - parsing library to check the image integrity and extract the required - authentication parameters. Three types of images are currently supported: - * `IMG_RAW`: image is a raw binary. No parsing functions are available, - other than reading the whole image. - * `IMG_PLAT`: image format is platform specific. The platform may use this - type for custom images not directly supported by the authentication - framework. - * `IMG_CERT`: image is an x509v3 certificate. -* `parent`: pointer to the parent image descriptor. The parent will contain - the information required to authenticate the current image. If the parent - is NULL, the authentication parameters will be obtained from the platform - (i.e. the BL2 and Trusted Key certificates are signed with the ROT private - key, whose public part is stored in the platform). -* `img_auth_methods`: this array defines the authentication methods that must - be checked to consider an image authenticated. Each method consists of a - type and a list of parameter descriptors. A parameter descriptor consists of - a type and a cookie which will point to specific information required to - extract that parameter from the image (i.e. if the parameter is stored in an - x509v3 extension, the cookie will point to the extension OID). Depending on - the method type, a different number of parameters must be specified. - Supported methods are: - * `AUTH_METHOD_HASH`: the hash of the image must match the hash extracted - from the parent image. The following parameter descriptors must be - specified: - * `data`: data to be hashed (obtained from current image) - * `hash`: reference hash (obtained from parent image) - * `AUTH_METHOD_SIG`: the image (usually a certificate) must be signed with - the private key whose public part is extracted from the parent image (or - the platform if the parent is NULL). The following parameter descriptors - must be specified: - * `pk`: the public key (obtained from parent image) - * `sig`: the digital signature (obtained from current image) - * `alg`: the signature algorithm used (obtained from current image) - * `data`: the data to be signed (obtained from current image) -* `authenticated_data`: this array indicates what authentication parameters - must be extracted from an image once it has been authenticated. Each - parameter consists of a parameter descriptor and the buffer address/size - to store the parameter. The CoT is responsible for allocating the required - memory to store the parameters. - -In the `tbbr_cot.c` file, a set of buffers are allocated to store the parameters -extracted from the certificates. In the case of the TBBR CoT, these parameters -are hashes and public keys. In DER format, an RSA-2048 public key requires 294 -bytes, and a hash requires 51 bytes. Depending on the CoT and the authentication -process, some of the buffers may be reused at different stages during the boot. - -Next in that file, the parameter descriptors are defined. These descriptors will -be used to extract the parameter data from the corresponding image. - -#### 4.1.1 Example: the BL31 Chain of Trust - -Four image descriptors form the BL31 Chain of Trust: - -``` -[TRUSTED_KEY_CERT_ID] = { - .img_id = TRUSTED_KEY_CERT_ID, - .img_type = IMG_CERT, - .parent = NULL, - .img_auth_methods = { - [0] = { - .type = AUTH_METHOD_SIG, - .param.sig = { - .pk = &subject_pk, - .sig = &sig, - .alg = &sig_alg, - .data = &raw_data, - } - } - }, - .authenticated_data = { - [0] = { - .type_desc = &trusted_world_pk, - .data = { - .ptr = (void *)trusted_world_pk_buf, - .len = (unsigned int)PK_DER_LEN - } - }, - [1] = { - .type_desc = &non_trusted_world_pk, - .data = { - .ptr = (void *)non_trusted_world_pk_buf, - .len = (unsigned int)PK_DER_LEN - } - } - } -}, -[SOC_FW_KEY_CERT_ID] = { - .img_id = SOC_FW_KEY_CERT_ID, - .img_type = IMG_CERT, - .parent = &cot_desc[TRUSTED_KEY_CERT_ID], - .img_auth_methods = { - [0] = { - .type = AUTH_METHOD_SIG, - .param.sig = { - .pk = &trusted_world_pk, - .sig = &sig, - .alg = &sig_alg, - .data = &raw_data, - } - } - }, - .authenticated_data = { - [0] = { - .type_desc = &soc_fw_content_pk, - .data = { - .ptr = (void *)content_pk_buf, - .len = (unsigned int)PK_DER_LEN - } - } - } -}, -[SOC_FW_CONTENT_CERT_ID] = { - .img_id = SOC_FW_CONTENT_CERT_ID, - .img_type = IMG_CERT, - .parent = &cot_desc[SOC_FW_KEY_CERT_ID], - .img_auth_methods = { - [0] = { - .type = AUTH_METHOD_SIG, - .param.sig = { - .pk = &soc_fw_content_pk, - .sig = &sig, - .alg = &sig_alg, - .data = &raw_data, - } - } - }, - .authenticated_data = { - [0] = { - .type_desc = &soc_fw_hash, - .data = { - .ptr = (void *)soc_fw_hash_buf, - .len = (unsigned int)HASH_DER_LEN - } - } - } -}, -[BL31_IMAGE_ID] = { - .img_id = BL31_IMAGE_ID, - .img_type = IMG_RAW, - .parent = &cot_desc[SOC_FW_CONTENT_CERT_ID], - .img_auth_methods = { - [0] = { - .type = AUTH_METHOD_HASH, - .param.hash = { - .data = &raw_data, - .hash = &soc_fw_hash, - } - } - } -} -``` -The **Trusted Key certificate** is signed with the ROT private key and contains -the Trusted World public key and the Non-Trusted World public key as x509v3 -extensions. This must be specified in the image descriptor using the -`img_auth_methods` and `authenticated_data` arrays, respectively. - -The Trusted Key certificate is authenticated by checking its digital signature -using the ROTPK. Four parameters are required to check a signature: the public -key, the algorithm, the signature and the data that has been signed. Therefore, -four parameter descriptors must be specified with the authentication method: - -* `subject_pk`: parameter descriptor of type `AUTH_PARAM_PUB_KEY`. This type - is used to extract a public key from the parent image. If the cookie is an - OID, the key is extracted from the corresponding x509v3 extension. If the - cookie is NULL, the subject public key is retrieved. In this case, because - the parent image is NULL, the public key is obtained from the platform - (this key will be the ROTPK). -* `sig`: parameter descriptor of type `AUTH_PARAM_SIG`. It is used to extract - the signature from the certificate. -* `sig_alg`: parameter descriptor of type `AUTH_PARAM_SIG`. It is used to - extract the signature algorithm from the certificate. -* `raw_data`: parameter descriptor of type `AUTH_PARAM_RAW_DATA`. It is used - to extract the data to be signed from the certificate. - -Once the signature has been checked and the certificate authenticated, the -Trusted World public key needs to be extracted from the certificate. A new entry -is created in the `authenticated_data` array for that purpose. In that entry, -the corresponding parameter descriptor must be specified along with the buffer -address to store the parameter value. In this case, the `tz_world_pk` descriptor -is used to extract the public key from an x509v3 extension with OID -`TRUSTED_WORLD_PK_OID`. The BL31 key certificate will use this descriptor as -parameter in the signature authentication method. The key is stored in the -`plat_tz_world_pk_buf` buffer. - -The **BL31 Key certificate** is authenticated by checking its digital signature -using the Trusted World public key obtained previously from the Trusted Key -certificate. In the image descriptor, we specify a single authentication method -by signature whose public key is the `tz_world_pk`. Once this certificate has -been authenticated, we have to extract the BL31 public key, stored in the -extension specified by `bl31_content_pk`. This key will be copied to the -`plat_content_pk` buffer. - -The **BL31 certificate** is authenticated by checking its digital signature -using the BL31 public key obtained previously from the BL31 Key certificate. -We specify the authentication method using `bl31_content_pk` as public key. -After authentication, we need to extract the BL31 hash, stored in the extension -specified by `bl31_hash`. This hash will be copied to the `plat_bl31_hash_buf` -buffer. - -The **BL31 image** is authenticated by calculating its hash and matching it -with the hash obtained from the BL31 certificate. The image descriptor contains -a single authentication method by hash. The parameters to the hash method are -the reference hash, `bl31_hash`, and the data to be hashed. In this case, it is -the whole image, so we specify `raw_data`. - -### 4.2 The image parser library - -The image parser module relies on libraries to check the image integrity and -extract the authentication parameters. The number and type of parser libraries -depend on the images used in the CoT. Raw images do not need a library, so -only an x509v3 library is required for the TBBR CoT. - -ARM platforms will use an x509v3 library based on mbed TLS. This library may be -found in `drivers/auth/mbedtls/mbedtls_x509_parser.c`. It exports three -functions: - -``` -void init(void); -int check_integrity(void *img, unsigned int img_len); -int get_auth_param(const auth_param_type_desc_t *type_desc, - void *img, unsigned int img_len, - void **param, unsigned int *param_len); -``` - -The library is registered in the framework using the macro -`REGISTER_IMG_PARSER_LIB()`. Each time the image parser module needs to access -an image of type `IMG_CERT`, it will call the corresponding function exported -in this file. - -The build system must be updated to include the corresponding library and -mbed TLS sources. ARM platforms use the `arm_common.mk` file to pull the -sources. - -### 4.3 The cryptographic library - -The cryptographic module relies on a library to perform the required operations, -i.e. verify a hash or a digital signature. ARM platforms will use a library -based on mbed TLS, which can be found in -`drivers/auth/mbedtls/mbedtls_crypto.c`. This library is registered in the -authentication framework using the macro `REGISTER_CRYPTO_LIB()` and exports -three functions: - -``` -void init(void); -int verify_signature(void *data_ptr, unsigned int data_len, - void *sig_ptr, unsigned int sig_len, - void *sig_alg, unsigned int sig_alg_len, - void *pk_ptr, unsigned int pk_len); -int verify_hash(void *data_ptr, unsigned int data_len, - void *digest_info_ptr, unsigned int digest_info_len); -``` - -The key algorithm (rsa, ecdsa) must be specified in the build system using the -`TF_MBEDTLS_KEY_ALG` variable, so the Makefile can include the corresponding -sources in the build. - -Note: If code size is a concern, the build option `MBEDTLS_SHA256_SMALLER` can -be defined in the platform Makefile. It will make mbed TLS use an implementation -of SHA-256 with smaller memory footprint (~1.5 KB less) but slower (~30%). - -- - - - - - - - - - - - - - - - - - - - - - - - - - - -_Copyright (c) 2015, ARM Limited and Contributors. All rights reserved._ - - -[Trusted Board Boot]: ./trusted-board-boot.md -[Platform Porting Guide]: ./porting-guide.md diff --git a/docs/change-log.md b/docs/change-log.md deleted file mode 100644 index 4eb1254b..00000000 --- a/docs/change-log.md +++ /dev/null @@ -1,1103 +0,0 @@ - -ARM Trusted Firmware - version 1.3 -================================== - -New features ------------- - -* Added support for running Trusted Firmware in AArch32 execution state. - - The PSCI library has been refactored to allow integration with **EL3 Runtime - Software**. This is software that is executing at the highest secure - privilege which is EL3 in AArch64 or Secure SVC/Monitor mode in AArch32. See - [PSCI Integration Guide]. - - Included is a minimal AArch32 Secure Payload, **SP-MIN**, that illustrates - the usage and integration of the PSCI library with EL3 Runtime Software - running in AArch32 state. - - Booting to the BL1/BL2 images as well as booting straight to the Secure - Payload is supported. - -* Improvements to the initialization framework for the PSCI service and ARM - Standard Services in general. - - The PSCI service is now initialized as part of ARM Standard Service - initialization. This consolidates the initializations of any ARM Standard - Service that may be added in the future. - - A new function `get_arm_std_svc_args()` is introduced to get arguments - corresponding to each standard service and must be implemented by the EL3 - Runtime Software. - - For PSCI, a new versioned structure `psci_lib_args_t` is introduced to - initialize the PSCI Library. **Note** this is a compatibility break due to - the change in the prototype of `psci_setup()`. - -* To support AArch32 builds of BL1 and BL2, implemented a new, alternative - firmware image loading mechanism that adds flexibility. - - The current mechanism has a hard-coded set of images and execution order - (BL31, BL32, etc). The new mechanism is data-driven by a list of image - descriptors provided by the platform code. - - ARM platforms have been updated to support the new loading mechanism. - - The new mechanism is enabled by a build flag (`LOAD_IMAGE_V2`) which is - currently off by default for the AArch64 build. - - **Note** `TRUSTED_BOARD_BOOT` is currently not supported when - `LOAD_IMAGE_V2` is enabled. - -* Updated requirements for making contributions to ARM TF. - - Commits now must have a 'Signed-off-by:' field to certify that the - contribution has been made under the terms of the - [Developer Certificate of Origin]. - - A signed CLA is no longer required. - - The [Contribution Guide] has been updated to reflect this change. - -* Introduced Performance Measurement Framework (PMF) which provides support - for capturing, storing, dumping and retrieving time-stamps to measure the - execution time of critical paths in the firmware. This relies on defining - fixed sample points at key places in the code. - -* To support the QEMU platform port, imported libfdt v1.4.1 from - https://git.kernel.org/cgit/utils/dtc/dtc.git - -* Updated PSCI support: - - * Added support for PSCI NODE_HW_STATE API for ARM platforms. - - * New optional platform hook, `pwr_domain_pwr_down_wfi()`, in - `plat_psci_ops` to enable platforms to perform platform-specific actions - needed to enter powerdown, including the 'wfi' invocation. - - * PSCI STAT residency and count functions have been added on ARM platforms - by using PMF. - -* Enhancements to the translation table library: - - * Limited memory mapping support for region overlaps to only allow regions - to overlap that are identity mapped or have the same virtual to physical - address offset, and overlap completely but must not cover the same area. - - This limitation will enable future enhancements without having to - support complex edge cases that may not be necessary. - - * The initial translation lookup level is now inferred from the virtual - address space size. Previously, it was hard-coded. - - * Added support for mapping Normal, Inner Non-cacheable, Outer - Non-cacheable memory in the translation table library. - - This can be useful to map a non-cacheable memory region, such as a DMA - buffer. - - * Introduced the MT_EXECUTE/MT_EXECUTE_NEVER memory mapping attributes to - specify the access permissions for instruction execution of a memory - region. - -* Enabled support to isolate code and read-only data on separate memory pages, - allowing independent access control to be applied to each. - -* Enabled SCR_EL3.SIF (Secure Instruction Fetch) bit in BL1 and BL31 common - architectural setup code, preventing fetching instructions from non-secure - memory when in secure state. - -* Enhancements to FIP support: - - * Replaced `fip_create` with `fiptool` which provides a more consistent - and intuitive interface as well as additional support to remove an image - from a FIP file. - - * Enabled printing the SHA256 digest with info command, allowing quick - verification of an image within a FIP without having to extract the - image and running sha256sum on it. - - * Added support for unpacking the contents of an existing FIP file into - the working directory. - - * Aligned command line options for specifying images to use same naming - convention as specified by TBBR and already used in cert_create tool. - -* Refactored the TZC-400 driver to also support memory controllers that - integrate TZC functionality, for example ARM CoreLink DMC-500. Also added - DMC-500 specific support. - -* Implemented generic delay timer based on the system generic counter and - migrated all platforms to use it. - -* Enhanced support for ARM platforms: - - * Updated image loading support to make SCP images (SCP_BL2 and SCP_BL2U) - optional. - - * Enhanced topology description support to allow multi-cluster topology - definitions. - - * Added interconnect abstraction layer to help platform ports select the - right interconnect driver, CCI or CCN, for the platform. - - * Added support to allow loading BL31 in the TZC-secured DRAM instead of - the default secure SRAM. - - * Added support to use a System Security Control (SSC) Registers Unit - enabling ARM TF to be compiled to support multiple ARM platforms and - then select one at runtime. - - * Restricted mapping of Trusted ROM in BL1 to what is actually needed by - BL1 rather than entire Trusted ROM region. - - * Flash is now mapped as execute-never by default. This increases security - by restricting the executable region to what is strictly needed. - -* Applied following erratum workarounds for Cortex-A57: 833471, 826977, - 829520, 828024 and 826974. - -* Added support for Mediatek MT6795 platform. - -* Added support for QEMU virtualization ARMv8-A target. - -* Added support for Rockchip RK3368 and RK3399 platforms. - -* Added support for Xilinx Zynq UltraScale+ MPSoC platform. - -* Added support for ARM Cortex-A73 MPCore Processor. - -* Added support for ARM Cortex-A72 processor. - -* Added support for ARM Cortex-A35 processor. - -* Added support for ARM Cortex-A32 MPCore Processor. - -* Enabled preloaded BL33 alternative boot flow, in which BL2 does not load - BL33 from non-volatile storage and BL31 hands execution over to a preloaded - BL33. The User Guide has been updated with an example of how to use this - option with a bootwrapped kernel. - -* Added support to build ARM TF on a Windows-based host machine. - -* Updated Trusted Board Boot prototype implementation: - - * Enabled the ability for a production ROM with TBBR enabled to boot test - software before a real ROTPK is deployed (e.g. manufacturing mode). - Added support to use ROTPK in certificate without verifying against the - platform value when `ROTPK_NOT_DEPLOYED` bit is set. - - * Added support for non-volatile counter authentication to the - Authentication Module to protect against roll-back. - -* Updated GICv3 support: - - * Enabled processor power-down and automatic power-on using GICv3. - - * Enabled G1S or G0 interrupts to be configured independently. - - * Changed FVP default interrupt driver to be the GICv3-only driver. - **Note** the default build of Trusted Firmware will not be able to boot - Linux kernel with GICv2 FDT blob. - - * Enabled wake-up from CPU_SUSPEND to stand-by by temporarily re-routing - interrupts and then restoring after resume. - -Issues resolved since last release ----------------------------------- - -Known issues ------------- - -* The version of the AEMv8 Base FVP used in this release resets the model - instead of terminating its execution in response to a shutdown request using - the PSCI `SYSTEM_OFF` API. This issue will be fixed in a future version of - the model. - -* Building TF with compiler optimisations disabled (`-O0`) fails. - - -* ARM TF cannot be built with mbed TLS version v2.3.0 due to build warnings - that the ARM TF build system interprets as errors. - -* TBBR is not currently supported when running Trusted Firmware in AArch32 - state. - - -ARM Trusted Firmware - version 1.2 -================================== - -New features ------------- - -* The Trusted Board Boot implementation on ARM platforms now conforms to the - mandatory requirements of the TBBR specification. - - In particular, the boot process is now guarded by a Trusted Watchdog, which - will reset the system in case of an authentication or loading error. On ARM - platforms, a secure instance of ARM SP805 is used as the Trusted Watchdog. - - Also, a firmware update process has been implemented. It enables - authenticated firmware to update firmware images from external interfaces to - SoC Non-Volatile memories. This feature functions even when the current - firmware in the system is corrupt or missing; it therefore may be used as - a recovery mode. - -* Improvements have been made to the Certificate Generation Tool - (`cert_create`) as follows. - - * Added support for the Firmware Update process by extending the Chain - of Trust definition in the tool to include the Firmware Update - certificate and the required extensions. - - * Introduced a new API that allows one to specify command line options in - the Chain of Trust description. This makes the declaration of the tool's - arguments more flexible and easier to extend. - - * The tool has been reworked to follow a data driven approach, which - makes it easier to maintain and extend. - -* Extended the FIP tool (`fip_create`) to support the new set of images - involved in the Firmware Update process. - -* Various memory footprint improvements. In particular: - - * The bakery lock structure for coherent memory has been optimised. - - * The mbed TLS SHA1 functions are not needed, as SHA256 is used to - generate the certificate signature. Therefore, they have been compiled - out, reducing the memory footprint of BL1 and BL2 by approximately - 6 KB. - - * On ARM development platforms, each BL stage now individually defines - the number of regions that it needs to map in the MMU. - -* Added the following new design documents: - - * [Authentication framework] - * [Firmware Update] - * [TF Reset Design] - * [Power Domain Topology Design] - -* Applied the new image terminology to the code base and documentation, as - described on the [TF wiki on GitHub][TF Image Terminology]. - -* The build system has been reworked to improve readability and facilitate - adding future extensions. - -* On ARM standard platforms, BL31 uses the boot console during cold boot - but switches to the runtime console for any later logs at runtime. The TSP - uses the runtime console for all output. - -* Implemented a basic NOR flash driver for ARM platforms. It programs the - device using CFI (Common Flash Interface) standard commands. - -* Implemented support for booting EL3 payloads on ARM platforms, which - reduces the complexity of developing EL3 baremetal code by doing essential - baremetal initialization. - -* Provided separate drivers for GICv3 and GICv2. These expect the entire - software stack to use either GICv2 or GICv3; hybrid GIC software systems - are no longer supported and the legacy ARM GIC driver has been deprecated. - -* Added support for Juno r1 and r2. A single set of Juno TF binaries can run - on Juno r0, r1 and r2 boards. Note that this TF version depends on a Linaro - release that does *not* contain Juno r2 support. - -* Added support for MediaTek mt8173 platform. - -* Implemented a generic driver for ARM CCN IP. - -* Major rework of the PSCI implementation. - - * Added framework to handle composite power states. - - * Decoupled the notions of affinity instances (which describes the - hierarchical arrangement of cores) and of power domain topology, instead - of assuming a one-to-one mapping. - - * Better alignment with version 1.0 of the PSCI specification. - -* Added support for the SYSTEM_SUSPEND PSCI API on ARM platforms. When invoked - on the last running core on a supported platform, this puts the system - into a low power mode with memory retention. - -* Unified the reset handling code as much as possible across BL stages. - Also introduced some build options to enable optimization of the reset path - on platforms that support it. - -* Added a simple delay timer API, as well as an SP804 timer driver, which is - enabled on FVP. - -* Added support for NVidia Tegra T210 and T132 SoCs. - -* Reorganised ARM platforms ports to greatly improve code shareability and - facilitate the reuse of some of this code by other platforms. - -* Added support for ARM Cortex-A72 processor in the CPU specific framework. - -* Provided better error handling. Platform ports can now define their own - error handling, for example to perform platform specific bookkeeping or - post-error actions. - -* Implemented a unified driver for ARM Cache Coherent Interconnects used for - both CCI-400 & CCI-500 IPs. ARM platforms ports have been migrated to this - common driver. The standalone CCI-400 driver has been deprecated. - - -Issues resolved since last release ----------------------------------- - -* The Trusted Board Boot implementation has been redesigned to provide greater - modularity and scalability. See the [Authentication Framework] document. - All missing mandatory features are now implemented. - -* The FVP and Juno ports may now use the hash of the ROTPK stored in the - Trusted Key Storage registers to verify the ROTPK. Alternatively, a - development public key hash embedded in the BL1 and BL2 binaries might be - used instead. The location of the ROTPK is chosen at build-time using the - `ARM_ROTPK_LOCATION` build option. - -* GICv3 is now fully supported and stable. - - -Known issues ------------- - -* The version of the AEMv8 Base FVP used in this release resets the model - instead of terminating its execution in response to a shutdown request using - the PSCI `SYSTEM_OFF` API. This issue will be fixed in a future version of - the model. - -* While this version has low on-chip RAM requirements, there are further - RAM usage enhancements that could be made. - -* The upstream documentation could be improved for structural consistency, - clarity and completeness. In particular, the design documentation is - incomplete for PSCI, the TSP(D) and the Juno platform. - -* Building TF with compiler optimisations disabled (`-O0`) fails. - - -ARM Trusted Firmware - version 1.1 -================================== - -New features ------------- - -* A prototype implementation of Trusted Board Boot has been added. Boot - loader images are verified by BL1 and BL2 during the cold boot path. BL1 and - BL2 use the PolarSSL SSL library to verify certificates and images. The - OpenSSL library is used to create the X.509 certificates. Support has been - added to `fip_create` tool to package the certificates in a FIP. - -* Support for calling CPU and platform specific reset handlers upon entry into - BL3-1 during the cold and warm boot paths has been added. This happens after - another Boot ROM `reset_handler()` has already run. This enables a developer - to perform additional actions or undo actions already performed during the - first call of the reset handlers e.g. apply additional errata workarounds. - -* Support has been added to demonstrate routing of IRQs to EL3 instead of - S-EL1 when execution is in secure world. - -* The PSCI implementation now conforms to version 1.0 of the PSCI - specification. All the mandatory APIs and selected optional APIs are - supported. In particular, support for the `PSCI_FEATURES` API has been - added. A capability variable is constructed during initialization by - examining the `plat_pm_ops` and `spd_pm_ops` exported by the platform and - the Secure Payload Dispatcher. This is used by the PSCI FEATURES function - to determine which PSCI APIs are supported by the platform. - -* Improvements have been made to the PSCI code as follows. - - * The code has been refactored to remove redundant parameters from - internal functions. - - * Changes have been made to the code for PSCI `CPU_SUSPEND`, `CPU_ON` and - `CPU_OFF` calls to facilitate an early return to the caller in case a - failure condition is detected. For example, a PSCI `CPU_SUSPEND` call - returns `SUCCESS` to the caller if a pending interrupt is detected early - in the code path. - - * Optional platform APIs have been added to validate the `power_state` and - `entrypoint` parameters early in PSCI `CPU_ON` and `CPU_SUSPEND` code - paths. - - * PSCI migrate APIs have been reworked to invoke the SPD hook to determine - the type of Trusted OS and the CPU it is resident on (if - applicable). Also, during a PSCI `MIGRATE` call, the SPD hook to migrate - the Trusted OS is invoked. - -* It is now possible to build Trusted Firmware without marking at least an - extra page of memory as coherent. The build flag `USE_COHERENT_MEM` can be - used to choose between the two implementations. This has been made possible - through these changes. - - * An implementation of Bakery locks, where the locks are not allocated in - coherent memory has been added. - - * Memory which was previously marked as coherent is now kept coherent - through the use of software cache maintenance operations. - - Approximately, 4K worth of memory is saved for each boot loader stage when - `USE_COHERENT_MEM=0`. Enabling this option increases the latencies - associated with acquire and release of locks. It also requires changes to - the platform ports. - -* It is now possible to specify the name of the FIP at build time by defining - the `FIP_NAME` variable. - -* Issues with depedencies on the 'fiptool' makefile target have been - rectified. The `fip_create` tool is now rebuilt whenever its source files - change. - -* The BL3-1 runtime console is now also used as the crash console. The crash - console is changed to SoC UART0 (UART2) from the previous FPGA UART0 (UART0) - on Juno. In FVP, it is changed from UART0 to UART1. - -* CPU errata workarounds are applied only when the revision and part number - match. This behaviour has been made consistent across the debug and release - builds. The debug build additionally prints a warning if a mismatch is - detected. - -* It is now possible to issue cache maintenance operations by set/way for a - particular level of data cache. Levels 1-3 are currently supported. - -* The following improvements have been made to the FVP port. - - * The build option `FVP_SHARED_DATA_LOCATION` which allowed relocation of - shared data into the Trusted DRAM has been deprecated. Shared data is - now always located at the base of Trusted SRAM. - - * BL2 Translation tables have been updated to map only the region of - DRAM which is accessible to normal world. This is the region of the 2GB - DDR-DRAM memory at 0x80000000 excluding the top 16MB. The top 16MB is - accessible to only the secure world. - - * BL3-2 can now reside in the top 16MB of DRAM which is accessible only to - the secure world. This can be done by setting the build flag - `FVP_TSP_RAM_LOCATION` to the value `dram`. - -* Separate transation tables are created for each boot loader image. The - `IMAGE_BLx` build options are used to do this. This allows each stage to - create mappings only for areas in the memory map that it needs. - -* A Secure Payload Dispatcher (OPTEED) for the OP-TEE Trusted OS has been - added. Details of using it with ARM Trusted Firmware can be found in - [OP-TEE Dispatcher] - - - -Issues resolved since last release ----------------------------------- - -* The Juno port has been aligned with the FVP port as follows. - - * Support for reclaiming all BL1 RW memory and BL2 memory by overlaying - the BL3-1/BL3-2 NOBITS sections on top of them has been added to the - Juno port. - - * The top 16MB of the 2GB DDR-DRAM memory at 0x80000000 is configured - using the TZC-400 controller to be accessible only to the secure world. - - * The ARM GIC driver is used to configure the GIC-400 instead of using a - GIC driver private to the Juno port. - - * PSCI `CPU_SUSPEND` calls that target a standby state are now supported. - - * The TZC-400 driver is used to configure the controller instead of direct - accesses to the registers. - -* The Linux kernel version referred to in the user guide has DVFS and HMP - support enabled. - -* DS-5 v5.19 did not detect Version 5.8 of the Cortex-A57-A53 Base FVPs in - CADI server mode. This issue is not seen with DS-5 v5.20 and Version 6.2 of - the Cortex-A57-A53 Base FVPs. - - -Known issues ------------- - -* The Trusted Board Boot implementation is a prototype. There are issues with - the modularity and scalability of the design. Support for a Trusted - Watchdog, firmware update mechanism, recovery images and Trusted debug is - absent. These issues will be addressed in future releases. - -* The FVP and Juno ports do not use the hash of the ROTPK stored in the - Trusted Key Storage registers to verify the ROTPK in the - `plat_match_rotpk()` function. This prevents the correct establishment of - the Chain of Trust at the first step in the Trusted Board Boot process. - -* The version of the AEMv8 Base FVP used in this release resets the model - instead of terminating its execution in response to a shutdown request using - the PSCI `SYSTEM_OFF` API. This issue will be fixed in a future version of - the model. - -* GICv3 support is experimental. There are known issues with GICv3 - initialization in the ARM Trusted Firmware. - -* While this version greatly reduces the on-chip RAM requirements, there are - further RAM usage enhancements that could be made. - -* The firmware design documentation for the Test Secure-EL1 Payload (TSP) and - its dispatcher (TSPD) is incomplete. Similarly for the PSCI section. - -* The Juno-specific firmware design documentation is incomplete. - - -ARM Trusted Firmware - version 1.0 -================================== - -New features ------------- - -* It is now possible to map higher physical addresses using non-flat virtual - to physical address mappings in the MMU setup. - -* Wider use is now made of the per-CPU data cache in BL3-1 to store: - - * Pointers to the non-secure and secure security state contexts. - - * A pointer to the CPU-specific operations. - - * A pointer to PSCI specific information (for example the current power - state). - - * A crash reporting buffer. - -* The following RAM usage improvements result in a BL3-1 RAM usage reduction - from 96KB to 56KB (for FVP with TSPD), and a total RAM usage reduction - across all images from 208KB to 88KB, compared to the previous release. - - * Removed the separate `early_exception` vectors from BL3-1 (2KB code size - saving). - - * Removed NSRAM from the FVP memory map, allowing the removal of one - (4KB) translation table. - - * Eliminated the internal `psci_suspend_context` array, saving 2KB. - - * Correctly dimensioned the PSCI `aff_map_node` array, saving 1.5KB in the - FVP port. - - * Removed calling CPU mpidr from the bakery lock API, saving 160 bytes. - - * Removed current CPU mpidr from PSCI common code, saving 160 bytes. - - * Inlined the mmio accessor functions, saving 360 bytes. - - * Fully reclaimed all BL1 RW memory and BL2 memory on the FVP port by - overlaying the BL3-1/BL3-2 NOBITS sections on top of these at runtime. - - * Made storing the FP register context optional, saving 0.5KB per context - (8KB on the FVP port, with TSPD enabled and running on 8 CPUs). - - * Implemented a leaner `tf_printf()` function, allowing the stack to be - greatly reduced. - - * Removed coherent stacks from the codebase. Stacks allocated in normal - memory are now used before and after the MMU is enabled. This saves 768 - bytes per CPU in BL3-1. - - * Reworked the crash reporting in BL3-1 to use less stack. - - * Optimized the EL3 register state stored in the `cpu_context` structure - so that registers that do not change during normal execution are - re-initialized each time during cold/warm boot, rather than restored - from memory. This saves about 1.2KB. - - * As a result of some of the above, reduced the runtime stack size in all - BL images. For BL3-1, this saves 1KB per CPU. - -* PSCI SMC handler improvements to correctly handle calls from secure states - and from AArch32. - -* CPU contexts are now initialized from the `entry_point_info`. BL3-1 fully - determines the exception level to use for the non-trusted firmware (BL3-3) - based on the SPSR value provided by the BL2 platform code (or otherwise - provided to BL3-1). This allows platform code to directly run non-trusted - firmware payloads at either EL2 or EL1 without requiring an EL2 stub or OS - loader. - -* Code refactoring improvements: - - * Refactored `fvp_config` into a common platform header. - - * Refactored the fvp gic code to be a generic driver that no longer has an - explicit dependency on platform code. - - * Refactored the CCI-400 driver to not have dependency on platform code. - - * Simplified the IO driver so it's no longer necessary to call `io_init()` - and moved all the IO storage framework code to one place. - - * Simplified the interface the the TZC-400 driver. - - * Clarified the platform porting interface to the TSP. - - * Reworked the TSPD setup code to support the alternate BL3-2 - intialization flow where BL3-1 generic code hands control to BL3-2, - rather than expecting the TSPD to hand control directly to BL3-2. - - * Considerable rework to PSCI generic code to support CPU specific - operations. - -* Improved console log output, by: - - * Adding the concept of debug log levels. - - * Rationalizing the existing debug messages and adding new ones. - - * Printing out the version of each BL stage at runtime. - - * Adding support for printing console output from assembler code, - including when a crash occurs before the C runtime is initialized. - -* Moved up to the latest versions of the FVPs, toolchain, EDK2, kernel, Linaro - file system and DS-5. - -* On the FVP port, made the use of the Trusted DRAM region optional at build - time (off by default). Normal platforms will not have such a "ready-to-use" - DRAM area so it is not a good example to use it. - -* Added support for PSCI `SYSTEM_OFF` and `SYSTEM_RESET` APIs. - -* Added support for CPU specific reset sequences, power down sequences and - register dumping during crash reporting. The CPU specific reset sequences - include support for errata workarounds. - -* Merged the Juno port into the master branch. Added support for CPU hotplug - and CPU idle. Updated the user guide to describe how to build and run on the - Juno platform. - - -Issues resolved since last release ----------------------------------- - -* Removed the concept of top/bottom image loading. The image loader now - automatically detects the position of the image inside the current memory - layout and updates the layout to minimize fragementation. This resolves the - image loader limitations of previously releases. There are currently no - plans to support dynamic image loading. - -* CPU idle now works on the publicized version of the Foundation FVP. - -* All known issues relating to the compiler version used have now been - resolved. This TF version uses Linaro toolchain 14.07 (based on GCC 4.9). - - -Known issues ------------- - -* GICv3 support is experimental. The Linux kernel patches to support this are - not widely available. There are known issues with GICv3 initialization in - the ARM Trusted Firmware. - -* While this version greatly reduces the on-chip RAM requirements, there are - further RAM usage enhancements that could be made. - -* The firmware design documentation for the Test Secure-EL1 Payload (TSP) and - its dispatcher (TSPD) is incomplete. Similarly for the PSCI section. - -* The Juno-specific firmware design documentation is incomplete. - -* Some recent enhancements to the FVP port have not yet been translated into - the Juno port. These will be tracked via the tf-issues project. - -* The Linux kernel version referred to in the user guide has DVFS and HMP - support disabled due to some known instabilities at the time of this - release. A future kernel version will re-enable these features. - -* DS-5 v5.19 does not detect Version 5.8 of the Cortex-A57-A53 Base FVPs in - CADI server mode. This is because the `<SimName>` reported by the FVP in - this version has changed. For example, for the Cortex-A57x4-A53x4 Base FVP, - the `<SimName>` reported by the FVP is `FVP_Base_Cortex_A57x4_A53x4`, while - DS-5 expects it to be `FVP_Base_A57x4_A53x4`. - - The temporary fix to this problem is to change the name of the FVP in - `sw/debugger/configdb/Boards/ARM FVP/Base_A57x4_A53x4/cadi_config.xml`. - Change the following line: - - <SimName>System Generator:FVP_Base_A57x4_A53x4</SimName> - to - <SimName>System Generator:FVP_Base_Cortex-A57x4_A53x4</SimName> - - A similar change can be made to the other Cortex-A57-A53 Base FVP variants. - - -ARM Trusted Firmware - version 0.4 -================================== - -New features ------------- - -* Makefile improvements: - - * Improved dependency checking when building. - - * Removed `dump` target (build now always produces dump files). - - * Enabled platform ports to optionally make use of parts of the Trusted - Firmware (e.g. BL3-1 only), rather than being forced to use all parts. - Also made the `fip` target optional. - - * Specified the full path to source files and removed use of the `vpath` - keyword. - -* Provided translation table library code for potential re-use by platforms - other than the FVPs. - -* Moved architectural timer setup to platform-specific code. - -* Added standby state support to PSCI cpu_suspend implementation. - -* SRAM usage improvements: - - * Started using the `-ffunction-sections`, `-fdata-sections` and - `--gc-sections` compiler/linker options to remove unused code and data - from the images. Previously, all common functions were being built into - all binary images, whether or not they were actually used. - - * Placed all assembler functions in their own section to allow more unused - functions to be removed from images. - - * Updated BL1 and BL2 to use a single coherent stack each, rather than one - per CPU. - - * Changed variables that were unnecessarily declared and initialized as - non-const (i.e. in the .data section) so they are either uninitialized - (zero init) or const. - -* Moved the Test Secure-EL1 Payload (BL3-2) to execute in Trusted SRAM by - default. The option for it to run in Trusted DRAM remains. - -* Implemented a TrustZone Address Space Controller (TZC-400) driver. A - default configuration is provided for the Base FVPs. This means the model - parameter `-C bp.secure_memory=1` is now supported. - -* Started saving the PSCI cpu_suspend 'power_state' parameter prior to - suspending a CPU. This allows platforms that implement multiple power-down - states at the same affinity level to identify a specific state. - -* Refactored the entire codebase to reduce the amount of nesting in header - files and to make the use of system/user includes more consistent. Also - split platform.h to separate out the platform porting declarations from the - required platform porting definitions and the definitions/declarations - specific to the platform port. - -* Optimized the data cache clean/invalidate operations. - -* Improved the BL3-1 unhandled exception handling and reporting. Unhandled - exceptions now result in a dump of registers to the console. - -* Major rework to the handover interface between BL stages, in particular the - interface to BL3-1. The interface now conforms to a specification and is - more future proof. - -* Added support for optionally making the BL3-1 entrypoint a reset handler - (instead of BL1). This allows platforms with an alternative image loading - architecture to re-use BL3-1 with fewer modifications to generic code. - -* Reserved some DDR DRAM for secure use on FVP platforms to avoid future - compatibility problems with non-secure software. - -* Added support for secure interrupts targeting the Secure-EL1 Payload (SP) - (using GICv2 routing only). Demonstrated this working by adding an interrupt - target and supporting test code to the TSP. Also demonstrated non-secure - interrupt handling during TSP processing. - - -Issues resolved since last release ----------------------------------- - -* Now support use of the model parameter `-C bp.secure_memory=1` in the Base - FVPs (see **New features**). - -* Support for secure world interrupt handling now available (see **New - features**). - -* Made enough SRAM savings (see **New features**) to enable the Test Secure-EL1 - Payload (BL3-2) to execute in Trusted SRAM by default. - -* The tested filesystem used for this release (Linaro AArch64 OpenEmbedded - 14.04) now correctly reports progress in the console. - -* Improved the Makefile structure to make it easier to separate out parts of - the Trusted Firmware for re-use in platform ports. Also, improved target - dependency checking. - - -Known issues ------------- - -* GICv3 support is experimental. The Linux kernel patches to support this are - not widely available. There are known issues with GICv3 initialization in - the ARM Trusted Firmware. - -* Dynamic image loading is not available yet. The current image loader - implementation (used to load BL2 and all subsequent images) has some - limitations. Changing BL2 or BL3-1 load addresses in certain ways can lead - to loading errors, even if the images should theoretically fit in memory. - -* The ARM Trusted Firmware still uses too much on-chip Trusted SRAM. A number - of RAM usage enhancements have been identified to rectify this situation. - -* CPU idle does not work on the advertised version of the Foundation FVP. - Some FVP fixes are required that are not available externally at the time - of writing. This can be worked around by disabling CPU idle in the Linux - kernel. - -* Various bugs in ARM Trusted Firmware, UEFI and the Linux kernel have been - observed when using Linaro toolchain versions later than 13.11. Although - most of these have been fixed, some remain at the time of writing. These - mainly seem to relate to a subtle change in the way the compiler converts - between 64-bit and 32-bit values (e.g. during casting operations), which - reveals previously hidden bugs in client code. - -* The firmware design documentation for the Test Secure-EL1 Payload (TSP) and - its dispatcher (TSPD) is incomplete. Similarly for the PSCI section. - - -ARM Trusted Firmware - version 0.3 -================================== - -New features ------------- - -* Support for Foundation FVP Version 2.0 added. - The documented UEFI configuration disables some devices that are unavailable - in the Foundation FVP, including MMC and CLCD. The resultant UEFI binary can - be used on the AEMv8 and Cortex-A57-A53 Base FVPs, as well as the Foundation - FVP. - - NOTE: The software will not work on Version 1.0 of the Foundation FVP. - -* Enabled third party contributions. Added a new contributing.md containing - instructions for how to contribute and updated copyright text in all files - to acknowledge contributors. - -* The PSCI CPU_SUSPEND API has been stabilised to the extent where it can be - used for entry into power down states with the following restrictions: - - Entry into standby states is not supported. - - The API is only supported on the AEMv8 and Cortex-A57-A53 Base FVPs. - -* The PSCI AFFINITY_INFO api has undergone limited testing on the Base FVPs to - allow experimental use. - -* Required C library and runtime header files are now included locally in ARM - Trusted Firmware instead of depending on the toolchain standard include - paths. The local implementation has been cleaned up and reduced in scope. - -* Added I/O abstraction framework, primarily to allow generic code to load - images in a platform-independent way. The existing image loading code has - been reworked to use the new framework. Semi-hosting and NOR flash I/O - drivers are provided. - -* Introduced Firmware Image Package (FIP) handling code and tools. A FIP - combines multiple firmware images with a Table of Contents (ToC) into a - single binary image. The new FIP driver is another type of I/O driver. The - Makefile builds a FIP by default and the FVP platform code expect to load a - FIP from NOR flash, although some support for image loading using semi- - hosting is retained. - - NOTE: Building a FIP by default is a non-backwards-compatible change. - - NOTE: Generic BL2 code now loads a BL3-3 (non-trusted firmware) image into - DRAM instead of expecting this to be pre-loaded at known location. This is - also a non-backwards-compatible change. - - NOTE: Some non-trusted firmware (e.g. UEFI) will need to be rebuilt so that - it knows the new location to execute from and no longer needs to copy - particular code modules to DRAM itself. - -* Reworked BL2 to BL3-1 handover interface. A new composite structure - (bl31_args) holds the superset of information that needs to be passed from - BL2 to BL3-1, including information on how handover execution control to - BL3-2 (if present) and BL3-3 (non-trusted firmware). - -* Added library support for CPU context management, allowing the saving and - restoring of - - Shared system registers between Secure-EL1 and EL1. - - VFP registers. - - Essential EL3 system registers. - -* Added a framework for implementing EL3 runtime services. Reworked the PSCI - implementation to be one such runtime service. - -* Reworked the exception handling logic, making use of both SP_EL0 and SP_EL3 - stack pointers for determining the type of exception, managing general - purpose and system register context on exception entry/exit, and handling - SMCs. SMCs are directed to the correct EL3 runtime service. - -* Added support for a Test Secure-EL1 Payload (TSP) and a corresponding - Dispatcher (TSPD), which is loaded as an EL3 runtime service. The TSPD - implements Secure Monitor functionality such as world switching and - EL1 context management, and is responsible for communication with the TSP. - NOTE: The TSPD does not yet contain support for secure world interrupts. - NOTE: The TSP/TSPD is not built by default. - - -Issues resolved since last release ----------------------------------- - -* Support has been added for switching context between secure and normal - worlds in EL3. - -* PSCI API calls `AFFINITY_INFO` & `PSCI_VERSION` have now been tested (to - a limited extent). - -* The ARM Trusted Firmware build artifacts are now placed in the `./build` - directory and sub-directories instead of being placed in the root of the - project. - -* The ARM Trusted Firmware is now free from build warnings. Build warnings - are now treated as errors. - -* The ARM Trusted Firmware now provides C library support locally within the - project to maintain compatibility between toolchains/systems. - -* The PSCI locking code has been reworked so it no longer takes locks in an - incorrect sequence. - -* The RAM-disk method of loading a Linux file-system has been confirmed to - work with the ARM Trusted Firmware and Linux kernel version (based on - version 3.13) used in this release, for both Foundation and Base FVPs. - - -Known issues ------------- - -The following is a list of issues which are expected to be fixed in the future -releases of the ARM Trusted Firmware. - -* The TrustZone Address Space Controller (TZC-400) is not being programmed - yet. Use of model parameter `-C bp.secure_memory=1` is not supported. - -* No support yet for secure world interrupt handling. - -* GICv3 support is experimental. The Linux kernel patches to support this are - not widely available. There are known issues with GICv3 initialization in - the ARM Trusted Firmware. - -* Dynamic image loading is not available yet. The current image loader - implementation (used to load BL2 and all subsequent images) has some - limitations. Changing BL2 or BL3-1 load addresses in certain ways can lead - to loading errors, even if the images should theoretically fit in memory. - -* The ARM Trusted Firmware uses too much on-chip Trusted SRAM. Currently the - Test Secure-EL1 Payload (BL3-2) executes in Trusted DRAM since there is not - enough SRAM. A number of RAM usage enhancements have been identified to - rectify this situation. - -* CPU idle does not work on the advertised version of the Foundation FVP. - Some FVP fixes are required that are not available externally at the time - of writing. - -* Various bugs in ARM Trusted Firmware, UEFI and the Linux kernel have been - observed when using Linaro toolchain versions later than 13.11. Although - most of these have been fixed, some remain at the time of writing. These - mainly seem to relate to a subtle change in the way the compiler converts - between 64-bit and 32-bit values (e.g. during casting operations), which - reveals previously hidden bugs in client code. - -* The tested filesystem used for this release (Linaro AArch64 OpenEmbedded - 14.01) does not report progress correctly in the console. It only seems to - produce error output, not standard output. It otherwise appears to function - correctly. Other filesystem versions on the same software stack do not - exhibit the problem. - -* The Makefile structure doesn't make it easy to separate out parts of the - Trusted Firmware for re-use in platform ports, for example if only BL3-1 is - required in a platform port. Also, dependency checking in the Makefile is - flawed. - -* The firmware design documentation for the Test Secure-EL1 Payload (TSP) and - its dispatcher (TSPD) is incomplete. Similarly for the PSCI section. - - -ARM Trusted Firmware - version 0.2 -================================== - -New features ------------- - -* First source release. - -* Code for the PSCI suspend feature is supplied, although this is not enabled - by default since there are known issues (see below). - - -Issues resolved since last release ----------------------------------- - -* The "psci" nodes in the FDTs provided in this release now fully comply - with the recommendations made in the PSCI specification. - - -Known issues ------------- - -The following is a list of issues which are expected to be fixed in the future -releases of the ARM Trusted Firmware. - -* The TrustZone Address Space Controller (TZC-400) is not being programmed - yet. Use of model parameter `-C bp.secure_memory=1` is not supported. - -* No support yet for secure world interrupt handling or for switching context - between secure and normal worlds in EL3. - -* GICv3 support is experimental. The Linux kernel patches to support this are - not widely available. There are known issues with GICv3 initialization in - the ARM Trusted Firmware. - -* Dynamic image loading is not available yet. The current image loader - implementation (used to load BL2 and all subsequent images) has some - limitations. Changing BL2 or BL3-1 load addresses in certain ways can lead - to loading errors, even if the images should theoretically fit in memory. - -* Although support for PSCI `CPU_SUSPEND` is present, it is not yet stable - and ready for use. - -* PSCI API calls `AFFINITY_INFO` & `PSCI_VERSION` are implemented but have not - been tested. - -* The ARM Trusted Firmware make files result in all build artifacts being - placed in the root of the project. These should be placed in appropriate - sub-directories. - -* The compilation of ARM Trusted Firmware is not free from compilation - warnings. Some of these warnings have not been investigated yet so they - could mask real bugs. - -* The ARM Trusted Firmware currently uses toolchain/system include files like - stdio.h. It should provide versions of these within the project to maintain - compatibility between toolchains/systems. - -* The PSCI code takes some locks in an incorrect sequence. This may cause - problems with suspend and hotplug in certain conditions. - -* The Linux kernel used in this release is based on version 3.12-rc4. Using - this kernel with the ARM Trusted Firmware fails to start the file-system as - a RAM-disk. It fails to execute user-space `init` from the RAM-disk. As an - alternative, the VirtioBlock mechanism can be used to provide a file-system - to the kernel. - - -- - - - - - - - - - - - - - - - - - - - - - - - - - - -_Copyright (c) 2013-2016, ARM Limited and Contributors. All rights reserved._ - -[OP-TEE Dispatcher]: optee-dispatcher.md -[Power Domain Topology Design]: psci-pd-tree.md -[TF Image Terminology]: https://github.com/ARM-software/arm-trusted-firmware/wiki/ARM-Trusted-Firmware-Image-Terminology -[Authentication Framework]: auth-framework.md -[Firmware Update]: firmware-update.md -[TF Reset Design]: reset-design.md -[PSCI Integration Guide]: psci-lib-integration-guide.md -[Firmware Design]: firmware-design.md -[CPU Specific Build Macros]: cpu-specific-build-macros.md -[User Guide]: user-guide.md -[Porting Guide]: porting-guide.md -[Developer Certificate of Origin]: ../dco.txt -[Contribution Guide]: ../contributing.md diff --git a/docs/cpu-specific-build-macros.md b/docs/cpu-specific-build-macros.md deleted file mode 100644 index eb23bcd4..00000000 --- a/docs/cpu-specific-build-macros.md +++ /dev/null @@ -1,132 +0,0 @@ -ARM CPU Specific Build Macros -============================= - -Contents --------- - -1. [Introduction](#1--introduction) -2. [CPU Errata Workarounds](#2--cpu-errata-workarounds) -3. [CPU Specific optimizations](#3--cpu-specific-optimizations) - - -1. Introduction ----------------- - -This document describes the various build options present in the CPU specific -operations framework to enable errata workarounds and to enable optimizations -for a specific CPU on a platform. - -2. CPU Errata Workarounds --------------------------- - -ARM Trusted Firmware exports a series of build flags which control the -errata workarounds that are applied to each CPU by the reset handler. The -errata details can be found in the CPU specific errata documents published -by ARM: - -* [Cortex-A53 MPCore Software Developers Errata Notice][A53 Errata Notice] -* [Cortex-A57 MPCore Software Developers Errata Notice][A57 Errata Notice] - -The errata workarounds are implemented for a particular revision or a set of -processor revisions. This is checked by the reset handler at runtime. Each -errata workaround is identified by its `ID` as specified in the processor's -errata notice document. The format of the define used to enable/disable the -errata workaround is `ERRATA_<Processor name>_<ID>`, where the `Processor name` -is for example `A57` for the `Cortex_A57` CPU. - -Refer to the section _CPU errata status reporting_ in [Firmware Design -guide][Firmware Design] for information on to write errata workaround functions. - -All workarounds are disabled by default. The platform is responsible for -enabling these workarounds according to its requirement by defining the -errata workaround build flags in the platform specific makefile. In case -these workarounds are enabled for the wrong CPU revision then the errata -workaround is not applied. In the DEBUG build, this is indicated by -printing a warning to the crash console. - -In the current implementation, a platform which has more than 1 variant -with different revisions of a processor has no runtime mechanism available -for it to specify which errata workarounds should be enabled or not. - -The value of the build flags are 0 by default, that is, disabled. Any other -value will enable it. - -For Cortex-A53, following errata build flags are defined : - -* `ERRATA_A53_826319`: This applies errata 826319 workaround to Cortex-A53 - CPU. This needs to be enabled only for revision <= r0p2 of the CPU. - -* `ERRATA_A53_836870`: This applies errata 836870 workaround to Cortex-A53 - CPU. This needs to be enabled only for revision <= r0p3 of the CPU. From - r0p4 and onwards, this errata is enabled by default in hardware. - -* `ERRATA_A53_855873`: This applies errata 855873 workaround to Cortex-A53 - CPUs. Though the erratum is present in every revision of the CPU, - this workaround is only applied to CPUs from r0p3 onwards, which feature - a chicken bit in CPUACTLR_EL1 to enable a hardware workaround. - Earlier revisions of the CPU have other errata which require the same - workaround in software, so they should be covered anyway. - -For Cortex-A57, following errata build flags are defined : - -* `ERRATA_A57_806969`: This applies errata 806969 workaround to Cortex-A57 - CPU. This needs to be enabled only for revision r0p0 of the CPU. - -* `ERRATA_A57_813419`: This applies errata 813419 workaround to Cortex-A57 - CPU. This needs to be enabled only for revision r0p0 of the CPU. - -* `ERRATA_A57_813420`: This applies errata 813420 workaround to Cortex-A57 - CPU. This needs to be enabled only for revision r0p0 of the CPU. - -* `ERRATA_A57_826974`: This applies errata 826974 workaround to Cortex-A57 - CPU. This needs to be enabled only for revision <= r1p1 of the CPU. - -* `ERRATA_A57_826977`: This applies errata 826977 workaround to Cortex-A57 - CPU. This needs to be enabled only for revision <= r1p1 of the CPU. - -* `ERRATA_A57_828024`: This applies errata 828024 workaround to Cortex-A57 - CPU. This needs to be enabled only for revision <= r1p1 of the CPU. - -* `ERRATA_A57_829520`: This applies errata 829520 workaround to Cortex-A57 - CPU. This needs to be enabled only for revision <= r1p2 of the CPU. - -* `ERRATA_A57_833471`: This applies errata 833471 workaround to Cortex-A57 - CPU. This needs to be enabled only for revision <= r1p2 of the CPU. - -3. CPU Specific optimizations ------------------------------- - -This section describes some of the optimizations allowed by the CPU micro -architecture that can be enabled by the platform as desired. - -* `SKIP_A57_L1_FLUSH_PWR_DWN`: This flag enables an optimization in the - Cortex-A57 cluster power down sequence by not flushing the Level 1 data - cache. The L1 data cache and the L2 unified cache are inclusive. A flush - of the L2 by set/way flushes any dirty lines from the L1 as well. This - is a known safe deviation from the Cortex-A57 TRM defined power down - sequence. Each Cortex-A57 based platform must make its own decision on - whether to use the optimization. - -* `A53_DISABLE_NON_TEMPORAL_HINT`: This flag disables the cache non-temporal - hint. The LDNP/STNP instructions as implemented on Cortex-A53 do not behave - in a way most programmers expect, and will most probably result in a - significant speed degradation to any code that employs them. The ARMv8-A - architecture (see ARM DDI 0487A.h, section D3.4.3) allows cores to ignore - the non-temporal hint and treat LDNP/STNP as LDP/STP instead. Enabling this - flag enforces this behaviour. This needs to be enabled only for revisions - <= r0p3 of the CPU and is enabled by default. - -* `A57_DISABLE_NON_TEMPORAL_HINT`: This flag has the same behaviour as - `A53_DISABLE_NON_TEMPORAL_HINT` but for Cortex-A57. This needs to be - enabled only for revisions <= r1p2 of the CPU and is enabled by default, - as recommended in section "4.7 Non-Temporal Loads/Stores" of the - [Cortex-A57 Software Optimization Guide][A57 SW Optimization Guide]. - -- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -_Copyright (c) 2014-2016, ARM Limited and Contributors. All rights reserved._ - -[A57 SW Optimization Guide]: http://infocenter.arm.com/help/topic/com.arm.doc.uan0015b/Cortex_A57_Software_Optimization_Guide_external.pdf -[A53 Errata Notice]: http://infocenter.arm.com/help/topic/com.arm.doc.epm048406/index.html -[A57 Errata Notice]: http://infocenter.arm.com/help/topic/com.arm.doc.epm049219/cortex_a57_mpcore_software_developers_errata_notice.pdf -[Firmware Design]: firmware-design.md diff --git a/docs/firmware-design.md b/docs/firmware-design.md deleted file mode 100644 index 0d4578a5..00000000 --- a/docs/firmware-design.md +++ /dev/null @@ -1,2325 +0,0 @@ -ARM Trusted Firmware Design -=========================== - -Contents : - -1. [Introduction](#1--introduction) -2. [Cold boot](#2--cold-boot) -3. [EL3 runtime services framework](#3--el3-runtime-services-framework) -4. [Power State Coordination Interface](#4--power-state-coordination-interface) -5. [Secure-EL1 Payloads and Dispatchers](#5--secure-el1-payloads-and-dispatchers) -6. [Crash Reporting in BL31](#6--crash-reporting-in-bl31) -7. [Guidelines for Reset Handlers](#7--guidelines-for-reset-handlers) -8. [CPU specific operations framework](#8--cpu-specific-operations-framework) -9. [Memory layout of BL images](#9-memory-layout-of-bl-images) -10. [Firmware Image Package (FIP)](#10--firmware-image-package-fip) -11. [Use of coherent memory in Trusted Firmware](#11--use-of-coherent-memory-in-trusted-firmware) -12. [Isolating code and read-only data on separate memory pages](#12--isolating-code-and-read-only-data-on-separate-memory-pages) -13. [Performance Measurement Framework](#13--performance-measurement-framework) -14. [ARMv8 Architecture Extensions](#14--armv8-architecture-extensions) -15. [Code Structure](#15--code-structure) -16. [References](#16--references) - - -1. Introduction ----------------- - -The ARM Trusted Firmware implements a subset of the Trusted Board Boot -Requirements (TBBR) Platform Design Document (PDD) [1] for ARM reference -platforms. The TBB sequence starts when the platform is powered on and runs up -to the stage where it hands-off control to firmware running in the normal -world in DRAM. This is the cold boot path. - -The ARM Trusted Firmware also implements the Power State Coordination Interface -PDD [2] as a runtime service. PSCI is the interface from normal world software -to firmware implementing power management use-cases (for example, secondary CPU -boot, hotplug and idle). Normal world software can access ARM Trusted Firmware -runtime services via the ARM SMC (Secure Monitor Call) instruction. The SMC -instruction must be used as mandated by the SMC Calling Convention [3]. - -The ARM Trusted Firmware implements a framework for configuring and managing -interrupts generated in either security state. The details of the interrupt -management framework and its design can be found in ARM Trusted Firmware -Interrupt Management Design guide [4]. - -The ARM Trusted Firmware can be built to support either AArch64 or AArch32 -execution state. - -2. Cold boot -------------- - -The cold boot path starts when the platform is physically turned on. If -`COLD_BOOT_SINGLE_CPU=0`, one of the CPUs released from reset is chosen as the -primary CPU, and the remaining CPUs are considered secondary CPUs. The primary -CPU is chosen through platform-specific means. The cold boot path is mainly -executed by the primary CPU, other than essential CPU initialization executed by -all CPUs. The secondary CPUs are kept in a safe platform-specific state until -the primary CPU has performed enough initialization to boot them. - -Refer to the [Reset Design] for more information on the effect of the -`COLD_BOOT_SINGLE_CPU` platform build option. - -The cold boot path in this implementation of the ARM Trusted Firmware, -depends on the execution state. -For AArch64, it is divided into five steps (in order of execution): - -* Boot Loader stage 1 (BL1) _AP Trusted ROM_ -* Boot Loader stage 2 (BL2) _Trusted Boot Firmware_ -* Boot Loader stage 3-1 (BL31) _EL3 Runtime Software_ -* Boot Loader stage 3-2 (BL32) _Secure-EL1 Payload_ (optional) -* Boot Loader stage 3-3 (BL33) _Non-trusted Firmware_ - -For AArch32, it is divided into four steps (in order of execution): - -* Boot Loader stage 1 (BL1) _AP Trusted ROM_ -* Boot Loader stage 2 (BL2) _Trusted Boot Firmware_ -* Boot Loader stage 3-2 (BL32) _EL3 Runtime Software_ -* Boot Loader stage 3-3 (BL33) _Non-trusted Firmware_ - -ARM development platforms (Fixed Virtual Platforms (FVPs) and Juno) implement a -combination of the following types of memory regions. Each bootloader stage uses -one or more of these memory regions. - -* Regions accessible from both non-secure and secure states. For example, - non-trusted SRAM, ROM and DRAM. -* Regions accessible from only the secure state. For example, trusted SRAM and - ROM. The FVPs also implement the trusted DRAM which is statically - configured. Additionally, the Base FVPs and Juno development platform - configure the TrustZone Controller (TZC) to create a region in the DRAM - which is accessible only from the secure state. - - -The sections below provide the following details: - -* initialization and execution of the first three stages during cold boot -* specification of the EL3 Runtime Software (BL31 for AArch64 and BL32 for - AArch32) entrypoint requirements for use by alternative Trusted Boot - Firmware in place of the provided BL1 and BL2 - - -### BL1 - -This stage begins execution from the platform's reset vector at EL3. The reset -address is platform dependent but it is usually located in a Trusted ROM area. -The BL1 data section is copied to trusted SRAM at runtime. - -On the ARM development platforms, BL1 code starts execution from the reset -vector defined by the constant `BL1_RO_BASE`. The BL1 data section is copied -to the top of trusted SRAM as defined by the constant `BL1_RW_BASE`. - -The functionality implemented by this stage is as follows. - -#### Determination of boot path - -Whenever a CPU is released from reset, BL1 needs to distinguish between a warm -boot and a cold boot. This is done using platform-specific mechanisms (see the -`plat_get_my_entrypoint()` function in the [Porting Guide]). In the case of a -warm boot, a CPU is expected to continue execution from a separate -entrypoint. In the case of a cold boot, the secondary CPUs are placed in a safe -platform-specific state (see the `plat_secondary_cold_boot_setup()` function in -the [Porting Guide]) while the primary CPU executes the remaining cold boot path -as described in the following sections. - -This step only applies when `PROGRAMMABLE_RESET_ADDRESS=0`. Refer to the -[Reset Design] for more information on the effect of the -`PROGRAMMABLE_RESET_ADDRESS` platform build option. - -#### Architectural initialization - -BL1 performs minimal architectural initialization as follows. - -* Exception vectors - - BL1 sets up simple exception vectors for both synchronous and asynchronous - exceptions. The default behavior upon receiving an exception is to populate - a status code in the general purpose register `X0/R0` and call the - `plat_report_exception()` function (see the [Porting Guide]). The status - code is one of: - - For AArch64: - - 0x0 : Synchronous exception from Current EL with SP_EL0 - 0x1 : IRQ exception from Current EL with SP_EL0 - 0x2 : FIQ exception from Current EL with SP_EL0 - 0x3 : System Error exception from Current EL with SP_EL0 - 0x4 : Synchronous exception from Current EL with SP_ELx - 0x5 : IRQ exception from Current EL with SP_ELx - 0x6 : FIQ exception from Current EL with SP_ELx - 0x7 : System Error exception from Current EL with SP_ELx - 0x8 : Synchronous exception from Lower EL using aarch64 - 0x9 : IRQ exception from Lower EL using aarch64 - 0xa : FIQ exception from Lower EL using aarch64 - 0xb : System Error exception from Lower EL using aarch64 - 0xc : Synchronous exception from Lower EL using aarch32 - 0xd : IRQ exception from Lower EL using aarch32 - 0xe : FIQ exception from Lower EL using aarch32 - 0xf : System Error exception from Lower EL using aarch32 - - For AArch32: - - 0x10 : User mode - 0x11 : FIQ mode - 0x12 : IRQ mode - 0x13 : SVC mode - 0x16 : Monitor mode - 0x17 : Abort mode - 0x1a : Hypervisor mode - 0x1b : Undefined mode - 0x1f : System mode - - The `plat_report_exception()` implementation on the ARM FVP port programs - the Versatile Express System LED register in the following format to - indicate the occurence of an unexpected exception: - - SYS_LED[0] - Security state (Secure=0/Non-Secure=1) - SYS_LED[2:1] - Exception Level (EL3=0x3, EL2=0x2, EL1=0x1, EL0=0x0) - For AArch32 it is always 0x0 - SYS_LED[7:3] - Exception Class (Sync/Async & origin). This is the value - of the status code - - A write to the LED register reflects in the System LEDs (S6LED0..7) in the - CLCD window of the FVP. - - BL1 does not expect to receive any exceptions other than the SMC exception. - For the latter, BL1 installs a simple stub. The stub expects to receive a - limited set of SMC types (determined by their function IDs in the general - purpose register `X0/R0`): - - `BL1_SMC_RUN_IMAGE`: This SMC is raised by BL2 to make BL1 pass control - to EL3 Runtime Software. - - All SMCs listed in section "BL1 SMC Interface" in the [Firmware Update] - Design Guide are supported for AArch64 only. These SMCs are currently - not supported when BL1 is built for AArch32. - - Any other SMC leads to an assertion failure. - -* CPU initialization - - BL1 calls the `reset_handler()` function which in turn calls the CPU - specific reset handler function (see the section: "CPU specific operations - framework"). - -* Control register setup (for AArch64) - - `SCTLR_EL3`. Instruction cache is enabled by setting the `SCTLR_EL3.I` - bit. Alignment and stack alignment checking is enabled by setting the - `SCTLR_EL3.A` and `SCTLR_EL3.SA` bits. Exception endianness is set to - little-endian by clearing the `SCTLR_EL3.EE` bit. - - - `SCR_EL3`. The register width of the next lower exception level is set - to AArch64 by setting the `SCR.RW` bit. The `SCR.EA` bit is set to trap - both External Aborts and SError Interrupts in EL3. The `SCR.SIF` bit is - also set to disable instruction fetches from Non-secure memory when in - secure state. - - - `CPTR_EL3`. Accesses to the `CPACR_EL1` register from EL1 or EL2, or the - `CPTR_EL2` register from EL2 are configured to not trap to EL3 by - clearing the `CPTR_EL3.TCPAC` bit. Access to the trace functionality is - configured not to trap to EL3 by clearing the `CPTR_EL3.TTA` bit. - Instructions that access the registers associated with Floating Point - and Advanced SIMD execution are configured to not trap to EL3 by - clearing the `CPTR_EL3.TFP` bit. - - - `DAIF`. The SError interrupt is enabled by clearing the SError interrupt - mask bit. - - - `MDCR_EL3`. The trap controls, `MDCR_EL3.TDOSA`, `MDCR_EL3.TDA` and - `MDCR_EL3.TPM`, are set so that accesses to the registers they control - do not trap to EL3. AArch64 Secure self-hosted debug is disabled by - setting the `MDCR_EL3.SDD` bit. Also `MDCR_EL3.SPD32` is set to - disable AArch32 Secure self-hosted privileged debug from S-EL1. - -* Control register setup (for AArch32) - - `SCTLR`. Instruction cache is enabled by setting the `SCTLR.I` bit. - Alignment checking is enabled by setting the `SCTLR.A` bit. - Exception endianness is set to little-endian by clearing the - `SCTLR.EE` bit. - - - `SCR`. The `SCR.SIF` bit is set to disable instruction fetches from - Non-secure memory when in secure state. - - - `CPACR`. Allow execution of Advanced SIMD instructions at PL0 and PL1, - by clearing the `CPACR.ASEDIS` bit. Access to the trace functionality - is configured not to trap to undefined mode by clearing the - `CPACR.TRCDIS` bit. - - - `NSACR`. Enable non-secure access to Advanced SIMD functionality and - system register access to implemented trace registers. - - - `FPEXC`. Enable access to the Advanced SIMD and floating-point - functionality from all Exception levels. - - - `CPSR.A`. The Asynchronous data abort interrupt is enabled by clearing - the Asynchronous data abort interrupt mask bit. - - - `SDCR`. The `SDCR.SPD` field is set to disable AArch32 Secure - self-hosted privileged debug. - -#### Platform initialization - -On ARM platforms, BL1 performs the following platform initializations: - -* Enable the Trusted Watchdog. -* Initialize the console. -* Configure the Interconnect to enable hardware coherency. -* Enable the MMU and map the memory it needs to access. -* Configure any required platform storage to load the next bootloader image - (BL2). - -#### Firmware Update detection and execution - -After performing platform setup, BL1 common code calls -`bl1_plat_get_next_image_id()` to determine if [Firmware Update] is required or -to proceed with the normal boot process. If the platform code returns -`BL2_IMAGE_ID` then the normal boot sequence is executed as described in the -next section, else BL1 assumes that [Firmware Update] is required and execution -passes to the first image in the [Firmware Update] process. In either case, BL1 -retrieves a descriptor of the next image by calling `bl1_plat_get_image_desc()`. -The image descriptor contains an `entry_point_info_t` structure, which BL1 -uses to initialize the execution state of the next image. - -#### BL2 image load and execution - -In the normal boot flow, BL1 execution continues as follows: - -1. BL1 prints the following string from the primary CPU to indicate successful - execution of the BL1 stage: - - "Booting Trusted Firmware" - -2. BL1 determines the amount of free trusted SRAM memory available by - calculating the extent of its own data section, which also resides in - trusted SRAM. BL1 loads a BL2 raw binary image from platform storage, at a - platform-specific base address. If the BL2 image file is not present or if - there is not enough free trusted SRAM the following error message is - printed: - - "Failed to load BL2 firmware." - - BL1 calculates the amount of Trusted SRAM that can be used by the BL2 - image. The exact load location of the image is provided as a base address - in the platform header. Further description of the memory layout can be - found later in this document. - -3. BL1 passes control to the BL2 image at Secure EL1 (for AArch64) or at - Secure SVC mode (for AArch32), starting from its load address. - -4. BL1 also passes information about the amount of trusted SRAM used and - available for use. This information is populated at a platform-specific - memory address. - - -### BL2 - -BL1 loads and passes control to BL2 at Secure-EL1 (for AArch64) or at Secure -SVC mode (for AArch32) . BL2 is linked against and loaded at a platform-specific -base address (more information can be found later in this document). -The functionality implemented by BL2 is as follows. - -#### Architectural initialization - -For AArch64, BL2 performs the minimal architectural initialization required -for subsequent stages of the ARM Trusted Firmware and normal world software. -EL1 and EL0 are given access to Floating Point and Advanced SIMD registers -by clearing the `CPACR.FPEN` bits. - -For AArch32, the minimal architectural initialization required for subsequent -stages of the ARM Trusted Firmware and normal world software is taken care of -in BL1 as both BL1 and BL2 execute at PL1. - -#### Platform initialization - -On ARM platforms, BL2 performs the following platform initializations: - -* Initialize the console. -* Configure any required platform storage to allow loading further bootloader - images. -* Enable the MMU and map the memory it needs to access. -* Perform platform security setup to allow access to controlled components. -* Reserve some memory for passing information to the next bootloader image - EL3 Runtime Software and populate it. -* Define the extents of memory available for loading each subsequent - bootloader image. - -#### Image loading in BL2 - -Image loading scheme in BL2 depends on `LOAD_IMAGE_V2` build option. If the -flag is disabled, the BLxx images are loaded, by calling the respective -load_blxx() function from BL2 generic code. If the flag is enabled, the BL2 -generic code loads the images based on the list of loadable images provided -by the platform. BL2 passes the list of executable images provided by the -platform to the next handover BL image. By default, this flag is disabled for -AArch64 and the AArch32 build is supported only if this flag is enabled. - -#### SCP_BL2 (System Control Processor Firmware) image load - -Some systems have a separate System Control Processor (SCP) for power, clock, -reset and system control. BL2 loads the optional SCP_BL2 image from platform -storage into a platform-specific region of secure memory. The subsequent -handling of SCP_BL2 is platform specific. For example, on the Juno ARM -development platform port the image is transferred into SCP's internal memory -using the Boot Over MHU (BOM) protocol after being loaded in the trusted SRAM -memory. The SCP executes SCP_BL2 and signals to the Application Processor (AP) -for BL2 execution to continue. - -#### EL3 Runtime Software image load - -BL2 loads the EL3 Runtime Software image from platform storage into a platform- -specific address in trusted SRAM. If there is not enough memory to load the -image or image is missing it leads to an assertion failure. If `LOAD_IMAGE_V2` -is disabled and if image loads successfully, BL2 updates the amount of trusted -SRAM used and available for use by EL3 Runtime Software. This information is -populated at a platform-specific memory address. - -#### AArch64 BL32 (Secure-EL1 Payload) image load - -BL2 loads the optional BL32 image from platform storage into a platform- -specific region of secure memory. The image executes in the secure world. BL2 -relies on BL31 to pass control to the BL32 image, if present. Hence, BL2 -populates a platform-specific area of memory with the entrypoint/load-address -of the BL32 image. The value of the Saved Processor Status Register (`SPSR`) -for entry into BL32 is not determined by BL2, it is initialized by the -Secure-EL1 Payload Dispatcher (see later) within BL31, which is responsible for -managing interaction with BL32. This information is passed to BL31. - -#### BL33 (Non-trusted Firmware) image load - -BL2 loads the BL33 image (e.g. UEFI or other test or boot software) from -platform storage into non-secure memory as defined by the platform. - -BL2 relies on EL3 Runtime Software to pass control to BL33 once secure state -initialization is complete. Hence, BL2 populates a platform-specific area of -memory with the entrypoint and Saved Program Status Register (`SPSR`) of the -normal world software image. The entrypoint is the load address of the BL33 -image. The `SPSR` is determined as specified in Section 5.13 of the -[PSCI PDD][PSCI]. This information is passed to the EL3 Runtime Software. - -#### AArch64 BL31 (EL3 Runtime Software) execution - -BL2 execution continues as follows: - -1. BL2 passes control back to BL1 by raising an SMC, providing BL1 with the - BL31 entrypoint. The exception is handled by the SMC exception handler - installed by BL1. - -2. BL1 turns off the MMU and flushes the caches. It clears the - `SCTLR_EL3.M/I/C` bits, flushes the data cache to the point of coherency - and invalidates the TLBs. - -3. BL1 passes control to BL31 at the specified entrypoint at EL3. - - -### AArch64 BL31 - -The image for this stage is loaded by BL2 and BL1 passes control to BL31 at -EL3. BL31 executes solely in trusted SRAM. BL31 is linked against and -loaded at a platform-specific base address (more information can be found later -in this document). The functionality implemented by BL31 is as follows. - -#### Architectural initialization - -Currently, BL31 performs a similar architectural initialization to BL1 as -far as system register settings are concerned. Since BL1 code resides in ROM, -architectural initialization in BL31 allows override of any previous -initialization done by BL1. - -BL31 initializes the per-CPU data framework, which provides a cache of -frequently accessed per-CPU data optimised for fast, concurrent manipulation -on different CPUs. This buffer includes pointers to per-CPU contexts, crash -buffer, CPU reset and power down operations, PSCI data, platform data and so on. - -It then replaces the exception vectors populated by BL1 with its own. BL31 -exception vectors implement more elaborate support for handling SMCs since this -is the only mechanism to access the runtime services implemented by BL31 (PSCI -for example). BL31 checks each SMC for validity as specified by the -[SMC calling convention PDD][SMCCC] before passing control to the required SMC -handler routine. - -BL31 programs the `CNTFRQ_EL0` register with the clock frequency of the system -counter, which is provided by the platform. - -#### Platform initialization - -BL31 performs detailed platform initialization, which enables normal world -software to function correctly. - -On ARM platforms, this consists of the following: - -* Initialize the console. -* Configure the Interconnect to enable hardware coherency. -* Enable the MMU and map the memory it needs to access. -* Initialize the generic interrupt controller. -* Initialize the power controller device. -* Detect the system topology. - -#### Runtime services initialization - -BL31 is responsible for initializing the runtime services. One of them is PSCI. - -As part of the PSCI initializations, BL31 detects the system topology. It also -initializes the data structures that implement the state machine used to track -the state of power domain nodes. The state can be one of `OFF`, `RUN` or -`RETENTION`. All secondary CPUs are initially in the `OFF` state. The cluster -that the primary CPU belongs to is `ON`; any other cluster is `OFF`. It also -initializes the locks that protect them. BL31 accesses the state of a CPU or -cluster immediately after reset and before the data cache is enabled in the -warm boot path. It is not currently possible to use 'exclusive' based spinlocks, -therefore BL31 uses locks based on Lamport's Bakery algorithm instead. - -The runtime service framework and its initialization is described in more -detail in the "EL3 runtime services framework" section below. - -Details about the status of the PSCI implementation are provided in the -"Power State Coordination Interface" section below. - -#### AArch64 BL32 (Secure-EL1 Payload) image initialization - -If a BL32 image is present then there must be a matching Secure-EL1 Payload -Dispatcher (SPD) service (see later for details). During initialization -that service must register a function to carry out initialization of BL32 -once the runtime services are fully initialized. BL31 invokes such a -registered function to initialize BL32 before running BL33. This initialization -is not necessary for AArch32 SPs. - -Details on BL32 initialization and the SPD's role are described in the -"Secure-EL1 Payloads and Dispatchers" section below. - -#### BL33 (Non-trusted Firmware) execution - -EL3 Runtime Software initializes the EL2 or EL1 processor context for normal- -world cold boot, ensuring that no secure state information finds its way into -the non-secure execution state. EL3 Runtime Software uses the entrypoint -information provided by BL2 to jump to the Non-trusted firmware image (BL33) -at the highest available Exception Level (EL2 if available, otherwise EL1). - -### Using alternative Trusted Boot Firmware in place of BL1 & BL2 (AArch64 only) - -Some platforms have existing implementations of Trusted Boot Firmware that -would like to use ARM Trusted Firmware BL31 for the EL3 Runtime Software. To -enable this firmware architecture it is important to provide a fully documented -and stable interface between the Trusted Boot Firmware and BL31. - -Future changes to the BL31 interface will be done in a backwards compatible -way, and this enables these firmware components to be independently enhanced/ -updated to develop and exploit new functionality. - -#### Required CPU state when calling `bl31_entrypoint()` during cold boot - -This function must only be called by the primary CPU. - -On entry to this function the calling primary CPU must be executing in AArch64 -EL3, little-endian data access, and all interrupt sources masked: - - PSTATE.EL = 3 - PSTATE.RW = 1 - PSTATE.DAIF = 0xf - SCTLR_EL3.EE = 0 - -X0 and X1 can be used to pass information from the Trusted Boot Firmware to the -platform code in BL31: - - X0 : Reserved for common Trusted Firmware information - X1 : Platform specific information - -BL31 zero-init sections (e.g. `.bss`) should not contain valid data on entry, -these will be zero filled prior to invoking platform setup code. - -##### Use of the X0 and X1 parameters - -The parameters are platform specific and passed from `bl31_entrypoint()` to -`bl31_early_platform_setup()`. The value of these parameters is never directly -used by the common BL31 code. - -The convention is that `X0` conveys information regarding the BL31, BL32 and -BL33 images from the Trusted Boot firmware and `X1` can be used for other -platform specific purpose. This convention allows platforms which use ARM -Trusted Firmware's BL1 and BL2 images to transfer additional platform specific -information from Secure Boot without conflicting with future evolution of the -Trusted Firmware using `X0` to pass a `bl31_params` structure. - -BL31 common and SPD initialization code depends on image and entrypoint -information about BL33 and BL32, which is provided via BL31 platform APIs. -This information is required until the start of execution of BL33. This -information can be provided in a platform defined manner, e.g. compiled into -the platform code in BL31, or provided in a platform defined memory location -by the Trusted Boot firmware, or passed from the Trusted Boot Firmware via the -Cold boot Initialization parameters. This data may need to be cleaned out of -the CPU caches if it is provided by an earlier boot stage and then accessed by -BL31 platform code before the caches are enabled. - -ARM Trusted Firmware's BL2 implementation passes a `bl31_params` structure in -`X0` and the ARM development platforms interpret this in the BL31 platform -code. - -##### MMU, Data caches & Coherency - -BL31 does not depend on the enabled state of the MMU, data caches or -interconnect coherency on entry to `bl31_entrypoint()`. If these are disabled -on entry, these should be enabled during `bl31_plat_arch_setup()`. - -##### Data structures used in the BL31 cold boot interface - -These structures are designed to support compatibility and independent -evolution of the structures and the firmware images. For example, a version of -BL31 that can interpret the BL3x image information from different versions of -BL2, a platform that uses an extended entry_point_info structure to convey -additional register information to BL31, or a ELF image loader that can convey -more details about the firmware images. - -To support these scenarios the structures are versioned and sized, which enables -BL31 to detect which information is present and respond appropriately. The -`param_header` is defined to capture this information: - - typedef struct param_header { - uint8_t type; /* type of the structure */ - uint8_t version; /* version of this structure */ - uint16_t size; /* size of this structure in bytes */ - uint32_t attr; /* attributes: unused bits SBZ */ - } param_header_t; - -The structures using this format are `entry_point_info`, `image_info` and -`bl31_params`. The code that allocates and populates these structures must set -the header fields appropriately, and the `SET_PARAM_HEAD()` a macro is defined -to simplify this action. - -#### Required CPU state for BL31 Warm boot initialization - -When requesting a CPU power-on, or suspending a running CPU, ARM Trusted -Firmware provides the platform power management code with a Warm boot -initialization entry-point, to be invoked by the CPU immediately after the -reset handler. On entry to the Warm boot initialization function the calling -CPU must be in AArch64 EL3, little-endian data access and all interrupt sources -masked: - - PSTATE.EL = 3 - PSTATE.RW = 1 - PSTATE.DAIF = 0xf - SCTLR_EL3.EE = 0 - -The PSCI implementation will initialize the processor state and ensure that the -platform power management code is then invoked as required to initialize all -necessary system, cluster and CPU resources. - -### AArch32 EL3 Runtime Software entrypoint interface - -To enable this firmware architecture it is important to provide a fully -documented and stable interface between the Trusted Boot Firmware and the -AArch32 EL3 Runtime Software. - -Future changes to the entrypoint interface will be done in a backwards -compatible way, and this enables these firmware components to be independently -enhanced/updated to develop and exploit new functionality. - -#### Required CPU state when entering during cold boot - -This function must only be called by the primary CPU. - -On entry to this function the calling primary CPU must be executing in AArch32 -EL3, little-endian data access, and all interrupt sources masked: - - PSTATE.AIF = 0x7 - SCTLR.EE = 0 - -R0 and R1 are used to pass information from the Trusted Boot Firmware to the -platform code in AArch32 EL3 Runtime Software: - - R0 : Reserved for common Trusted Firmware information - R1 : Platform specific information - -##### Use of the R0 and R1 parameters - -The parameters are platform specific and the convention is that `R0` conveys -information regarding the BL3x images from the Trusted Boot firmware and `R1` -can be used for other platform specific purpose. This convention allows -platforms which use ARM Trusted Firmware's BL1 and BL2 images to transfer -additional platform specific information from Secure Boot without conflicting -with future evolution of the Trusted Firmware using `R0` to pass a `bl_params` -structure. - -The AArch32 EL3 Runtime Software is responsible for entry into BL33. This -information can be obtained in a platform defined manner, e.g. compiled into -the AArch32 EL3 Runtime Software, or provided in a platform defined memory -location by the Trusted Boot firmware, or passed from the Trusted Boot Firmware -via the Cold boot Initialization parameters. This data may need to be cleaned -out of the CPU caches if it is provided by an earlier boot stage and then -accessed by AArch32 EL3 Runtime Software before the caches are enabled. - -When using AArch32 EL3 Runtime Software, the ARM development platforms pass a -`bl_params` structure in `R0` from BL2 to be interpreted by AArch32 EL3 Runtime -Software platform code. - -##### MMU, Data caches & Coherency - -AArch32 EL3 Runtime Software must not depend on the enabled state of the MMU, -data caches or interconnect coherency in its entrypoint. They must be explicitly -enabled if required. - -##### Data structures used in cold boot interface - -The AArch32 EL3 Runtime Software cold boot interface uses `bl_params` instead -of `bl31_params`. The `bl_params` structure is based on the convention -described in AArch64 BL31 cold boot interface section. - -#### Required CPU state for warm boot initialization - -When requesting a CPU power-on, or suspending a running CPU, AArch32 EL3 -Runtime Software must ensure execution of a warm boot initialization entrypoint. -If ARM Trusted Firmware BL1 is used and the PROGRAMMABLE_RESET_ADDRESS build -flag is false, then AArch32 EL3 Runtime Software must ensure that BL1 branches -to the warm boot entrypoint by arranging for the BL1 platform function, -plat_get_my_entrypoint(), to return a non-zero value. - -In this case, the warm boot entrypoint must be in AArch32 EL3, little-endian -data access and all interrupt sources masked: - - PSTATE.AIF = 0x7 - SCTLR.EE = 0 - -The warm boot entrypoint may be implemented by using the ARM Trusted Firmware -`psci_warmboot_entrypoint()` function. In that case, the platform must fulfil -the pre-requisites mentioned in the [PSCI Library integration guide] -[PSCI Lib guide]. - -3. EL3 runtime services framework ----------------------------------- - -Software executing in the non-secure state and in the secure state at exception -levels lower than EL3 will request runtime services using the Secure Monitor -Call (SMC) instruction. These requests will follow the convention described in -the SMC Calling Convention PDD ([SMCCC]). The [SMCCC] assigns function -identifiers to each SMC request and describes how arguments are passed and -returned. - -The EL3 runtime services framework enables the development of services by -different providers that can be easily integrated into final product firmware. -The following sections describe the framework which facilitates the -registration, initialization and use of runtime services in EL3 Runtime -Software (BL31). - -The design of the runtime services depends heavily on the concepts and -definitions described in the [SMCCC], in particular SMC Function IDs, Owning -Entity Numbers (OEN), Fast and Yielding calls, and the SMC32 and SMC64 calling -conventions. Please refer to that document for more detailed explanation of -these terms. - -The following runtime services are expected to be implemented first. They have -not all been instantiated in the current implementation. - -1. Standard service calls - - This service is for management of the entire system. The Power State - Coordination Interface ([PSCI]) is the first set of standard service calls - defined by ARM (see PSCI section later). - -2. Secure-EL1 Payload Dispatcher service - - If a system runs a Trusted OS or other Secure-EL1 Payload (SP) then - it also requires a _Secure Monitor_ at EL3 to switch the EL1 processor - context between the normal world (EL1/EL2) and trusted world (Secure-EL1). - The Secure Monitor will make these world switches in response to SMCs. The - [SMCCC] provides for such SMCs with the Trusted OS Call and Trusted - Application Call OEN ranges. - - The interface between the EL3 Runtime Software and the Secure-EL1 Payload is - not defined by the [SMCCC] or any other standard. As a result, each - Secure-EL1 Payload requires a specific Secure Monitor that runs as a runtime - service - within ARM Trusted Firmware this service is referred to as the - Secure-EL1 Payload Dispatcher (SPD). - - ARM Trusted Firmware provides a Test Secure-EL1 Payload (TSP) and its - associated Dispatcher (TSPD). Details of SPD design and TSP/TSPD operation - are described in the "Secure-EL1 Payloads and Dispatchers" section below. - -3. CPU implementation service - - This service will provide an interface to CPU implementation specific - services for a given platform e.g. access to processor errata workarounds. - This service is currently unimplemented. - -Additional services for ARM Architecture, SiP and OEM calls can be implemented. -Each implemented service handles a range of SMC function identifiers as -described in the [SMCCC]. - - -### Registration - -A runtime service is registered using the `DECLARE_RT_SVC()` macro, specifying -the name of the service, the range of OENs covered, the type of service and -initialization and call handler functions. This macro instantiates a `const -struct rt_svc_desc` for the service with these details (see `runtime_svc.h`). -This structure is allocated in a special ELF section `rt_svc_descs`, enabling -the framework to find all service descriptors included into BL31. - -The specific service for a SMC Function is selected based on the OEN and call -type of the Function ID, and the framework uses that information in the service -descriptor to identify the handler for the SMC Call. - -The service descriptors do not include information to identify the precise set -of SMC function identifiers supported by this service implementation, the -security state from which such calls are valid nor the capability to support -64-bit and/or 32-bit callers (using SMC32 or SMC64). Responding appropriately -to these aspects of a SMC call is the responsibility of the service -implementation, the framework is focused on integration of services from -different providers and minimizing the time taken by the framework before the -service handler is invoked. - -Details of the parameters, requirements and behavior of the initialization and -call handling functions are provided in the following sections. - - -### Initialization - -`runtime_svc_init()` in `runtime_svc.c` initializes the runtime services -framework running on the primary CPU during cold boot as part of the BL31 -initialization. This happens prior to initializing a Trusted OS and running -Normal world boot firmware that might in turn use these services. -Initialization involves validating each of the declared runtime service -descriptors, calling the service initialization function and populating the -index used for runtime lookup of the service. - -The BL31 linker script collects all of the declared service descriptors into a -single array and defines symbols that allow the framework to locate and traverse -the array, and determine its size. - -The framework does basic validation of each descriptor to halt firmware -initialization if service declaration errors are detected. The framework does -not check descriptors for the following error conditions, and may behave in an -unpredictable manner under such scenarios: - -1. Overlapping OEN ranges -2. Multiple descriptors for the same range of OENs and `call_type` -3. Incorrect range of owning entity numbers for a given `call_type` - -Once validated, the service `init()` callback is invoked. This function carries -out any essential EL3 initialization before servicing requests. The `init()` -function is only invoked on the primary CPU during cold boot. If the service -uses per-CPU data this must either be initialized for all CPUs during this call, -or be done lazily when a CPU first issues an SMC call to that service. If -`init()` returns anything other than `0`, this is treated as an initialization -error and the service is ignored: this does not cause the firmware to halt. - -The OEN and call type fields present in the SMC Function ID cover a total of -128 distinct services, but in practice a single descriptor can cover a range of -OENs, e.g. SMCs to call a Trusted OS function. To optimize the lookup of a -service handler, the framework uses an array of 128 indices that map every -distinct OEN/call-type combination either to one of the declared services or to -indicate the service is not handled. This `rt_svc_descs_indices[]` array is -populated for all of the OENs covered by a service after the service `init()` -function has reported success. So a service that fails to initialize will never -have it's `handle()` function invoked. - -The following figure shows how the `rt_svc_descs_indices[]` index maps the SMC -Function ID call type and OEN onto a specific service handler in the -`rt_svc_descs[]` array. - - - - -### Handling an SMC - -When the EL3 runtime services framework receives a Secure Monitor Call, the SMC -Function ID is passed in W0 from the lower exception level (as per the -[SMCCC]). If the calling register width is AArch32, it is invalid to invoke an -SMC Function which indicates the SMC64 calling convention: such calls are -ignored and return the Unknown SMC Function Identifier result code `0xFFFFFFFF` -in R0/X0. - -Bit[31] (fast/yielding call) and bits[29:24] (owning entity number) of the SMC -Function ID are combined to index into the `rt_svc_descs_indices[]` array. The -resulting value might indicate a service that has no handler, in this case the -framework will also report an Unknown SMC Function ID. Otherwise, the value is -used as a further index into the `rt_svc_descs[]` array to locate the required -service and handler. - -The service's `handle()` callback is provided with five of the SMC parameters -directly, the others are saved into memory for retrieval (if needed) by the -handler. The handler is also provided with an opaque `handle` for use with the -supporting library for parameter retrieval, setting return values and context -manipulation; and with `flags` indicating the security state of the caller. The -framework finally sets up the execution stack for the handler, and invokes the -services `handle()` function. - -On return from the handler the result registers are populated in X0-X3 before -restoring the stack and CPU state and returning from the original SMC. - - -4. Power State Coordination Interface --------------------------------------- - -TODO: Provide design walkthrough of PSCI implementation. - -The PSCI v1.0 specification categorizes APIs as optional and mandatory. All the -mandatory APIs in PSCI v1.0 and all the APIs in PSCI v0.2 draft specification -[Power State Coordination Interface PDD] [PSCI] are implemented. The table lists -the PSCI v1.0 APIs and their support in generic code. - -An API implementation might have a dependency on platform code e.g. CPU_SUSPEND -requires the platform to export a part of the implementation. Hence the level -of support of the mandatory APIs depends upon the support exported by the -platform port as well. The Juno and FVP (all variants) platforms export all the -required support. - -| PSCI v1.0 API |Supported| Comments | -|:----------------------|:--------|:------------------------------------------| -|`PSCI_VERSION` | Yes | The version returned is 1.0 | -|`CPU_SUSPEND` | Yes* | | -|`CPU_OFF` | Yes* | | -|`CPU_ON` | Yes* | | -|`AFFINITY_INFO` | Yes | | -|`MIGRATE` | Yes** | | -|`MIGRATE_INFO_TYPE` | Yes** | | -|`MIGRATE_INFO_CPU` | Yes** | | -|`SYSTEM_OFF` | Yes* | | -|`SYSTEM_RESET` | Yes* | | -|`PSCI_FEATURES` | Yes | | -|`CPU_FREEZE` | No | | -|`CPU_DEFAULT_SUSPEND` | No | | -|`NODE_HW_STATE` | Yes* | | -|`SYSTEM_SUSPEND` | Yes* | | -|`PSCI_SET_SUSPEND_MODE`| No | | -|`PSCI_STAT_RESIDENCY` | Yes* | | -|`PSCI_STAT_COUNT` | Yes* | | - -*Note : These PSCI APIs require platform power management hooks to be -registered with the generic PSCI code to be supported. - -**Note : These PSCI APIs require appropriate Secure Payload Dispatcher -hooks to be registered with the generic PSCI code to be supported. - -The PSCI implementation in ARM Trusted Firmware is a library which can be -integrated with AArch64 or AArch32 EL3 Runtime Software for ARMv8-A systems. -A guide to integrating PSCI library with AArch32 EL3 Runtime Software -can be found [here][PSCI Lib guide]. - - -5. Secure-EL1 Payloads and Dispatchers ---------------------------------------- - -On a production system that includes a Trusted OS running in Secure-EL1/EL0, -the Trusted OS is coupled with a companion runtime service in the BL31 -firmware. This service is responsible for the initialisation of the Trusted -OS and all communications with it. The Trusted OS is the BL32 stage of the -boot flow in ARM Trusted Firmware. The firmware will attempt to locate, load -and execute a BL32 image. - -ARM Trusted Firmware uses a more general term for the BL32 software that runs -at Secure-EL1 - the _Secure-EL1 Payload_ - as it is not always a Trusted OS. - -The ARM Trusted Firmware provides a Test Secure-EL1 Payload (TSP) and a Test -Secure-EL1 Payload Dispatcher (TSPD) service as an example of how a Trusted OS -is supported on a production system using the Runtime Services Framework. On -such a system, the Test BL32 image and service are replaced by the Trusted OS -and its dispatcher service. The ARM Trusted Firmware build system expects that -the dispatcher will define the build flag `NEED_BL32` to enable it to include -the BL32 in the build either as a binary or to compile from source depending -on whether the `BL32` build option is specified or not. - -The TSP runs in Secure-EL1. It is designed to demonstrate synchronous -communication with the normal-world software running in EL1/EL2. Communication -is initiated by the normal-world software - -* either directly through a Fast SMC (as defined in the [SMCCC]) - -* or indirectly through a [PSCI] SMC. The [PSCI] implementation in turn - informs the TSPD about the requested power management operation. This allows - the TSP to prepare for or respond to the power state change - -The TSPD service is responsible for. - -* Initializing the TSP - -* Routing requests and responses between the secure and the non-secure - states during the two types of communications just described - -### Initializing a BL32 Image - -The Secure-EL1 Payload Dispatcher (SPD) service is responsible for initializing -the BL32 image. It needs access to the information passed by BL2 to BL31 to do -so. This is provided by: - - entry_point_info_t *bl31_plat_get_next_image_ep_info(uint32_t); - -which returns a reference to the `entry_point_info` structure corresponding to -the image which will be run in the specified security state. The SPD uses this -API to get entry point information for the SECURE image, BL32. - -In the absence of a BL32 image, BL31 passes control to the normal world -bootloader image (BL33). When the BL32 image is present, it is typical -that the SPD wants control to be passed to BL32 first and then later to BL33. - -To do this the SPD has to register a BL32 initialization function during -initialization of the SPD service. The BL32 initialization function has this -prototype: - - int32_t init(void); - -and is registered using the `bl31_register_bl32_init()` function. - -Trusted Firmware supports two approaches for the SPD to pass control to BL32 -before returning through EL3 and running the non-trusted firmware (BL33): - -1. In the BL32 setup function, use `bl31_set_next_image_type()` to - request that the exit from `bl31_main()` is to the BL32 entrypoint in - Secure-EL1. BL31 will exit to BL32 using the asynchronous method by - calling `bl31_prepare_next_image_entry()` and `el3_exit()`. - - When the BL32 has completed initialization at Secure-EL1, it returns to - BL31 by issuing an SMC, using a Function ID allocated to the SPD. On - receipt of this SMC, the SPD service handler should switch the CPU context - from trusted to normal world and use the `bl31_set_next_image_type()` and - `bl31_prepare_next_image_entry()` functions to set up the initial return to - the normal world firmware BL33. On return from the handler the framework - will exit to EL2 and run BL33. - -2. The BL32 setup function registers an initialization function using - `bl31_register_bl32_init()` which provides a SPD-defined mechanism to - invoke a 'world-switch synchronous call' to Secure-EL1 to run the BL32 - entrypoint. - NOTE: The Test SPD service included with the Trusted Firmware provides one - implementation of such a mechanism. - - On completion BL32 returns control to BL31 via a SMC, and on receipt the - SPD service handler invokes the synchronous call return mechanism to return - to the BL32 initialization function. On return from this function, - `bl31_main()` will set up the return to the normal world firmware BL33 and - continue the boot process in the normal world. - - -6. Crash Reporting in BL31 ----------------------------- - -BL31 implements a scheme for reporting the processor state when an unhandled -exception is encountered. The reporting mechanism attempts to preserve all the -register contents and report it via a dedicated UART (PL011 console). BL31 -reports the general purpose, EL3, Secure EL1 and some EL2 state registers. - -A dedicated per-CPU crash stack is maintained by BL31 and this is retrieved via -the per-CPU pointer cache. The implementation attempts to minimise the memory -required for this feature. The file `crash_reporting.S` contains the -implementation for crash reporting. - -The sample crash output is shown below. - - x0 :0x000000004F00007C - x1 :0x0000000007FFFFFF - x2 :0x0000000004014D50 - x3 :0x0000000000000000 - x4 :0x0000000088007998 - x5 :0x00000000001343AC - x6 :0x0000000000000016 - x7 :0x00000000000B8A38 - x8 :0x00000000001343AC - x9 :0x00000000000101A8 - x10 :0x0000000000000002 - x11 :0x000000000000011C - x12 :0x00000000FEFDC644 - x13 :0x00000000FED93FFC - x14 :0x0000000000247950 - x15 :0x00000000000007A2 - x16 :0x00000000000007A4 - x17 :0x0000000000247950 - x18 :0x0000000000000000 - x19 :0x00000000FFFFFFFF - x20 :0x0000000004014D50 - x21 :0x000000000400A38C - x22 :0x0000000000247950 - x23 :0x0000000000000010 - x24 :0x0000000000000024 - x25 :0x00000000FEFDC868 - x26 :0x00000000FEFDC86A - x27 :0x00000000019EDEDC - x28 :0x000000000A7CFDAA - x29 :0x0000000004010780 - x30 :0x000000000400F004 - scr_el3 :0x0000000000000D3D - sctlr_el3 :0x0000000000C8181F - cptr_el3 :0x0000000000000000 - tcr_el3 :0x0000000080803520 - daif :0x00000000000003C0 - mair_el3 :0x00000000000004FF - spsr_el3 :0x00000000800003CC - elr_el3 :0x000000000400C0CC - ttbr0_el3 :0x00000000040172A0 - esr_el3 :0x0000000096000210 - sp_el3 :0x0000000004014D50 - far_el3 :0x000000004F00007C - spsr_el1 :0x0000000000000000 - elr_el1 :0x0000000000000000 - spsr_abt :0x0000000000000000 - spsr_und :0x0000000000000000 - spsr_irq :0x0000000000000000 - spsr_fiq :0x0000000000000000 - sctlr_el1 :0x0000000030C81807 - actlr_el1 :0x0000000000000000 - cpacr_el1 :0x0000000000300000 - csselr_el1 :0x0000000000000002 - sp_el1 :0x0000000004028800 - esr_el1 :0x0000000000000000 - ttbr0_el1 :0x000000000402C200 - ttbr1_el1 :0x0000000000000000 - mair_el1 :0x00000000000004FF - amair_el1 :0x0000000000000000 - tcr_el1 :0x0000000000003520 - tpidr_el1 :0x0000000000000000 - tpidr_el0 :0x0000000000000000 - tpidrro_el0 :0x0000000000000000 - dacr32_el2 :0x0000000000000000 - ifsr32_el2 :0x0000000000000000 - par_el1 :0x0000000000000000 - far_el1 :0x0000000000000000 - afsr0_el1 :0x0000000000000000 - afsr1_el1 :0x0000000000000000 - contextidr_el1 :0x0000000000000000 - vbar_el1 :0x0000000004027000 - cntp_ctl_el0 :0x0000000000000000 - cntp_cval_el0 :0x0000000000000000 - cntv_ctl_el0 :0x0000000000000000 - cntv_cval_el0 :0x0000000000000000 - cntkctl_el1 :0x0000000000000000 - fpexc32_el2 :0x0000000004000700 - sp_el0 :0x0000000004010780 - -7. Guidelines for Reset Handlers ---------------------------------- - -Trusted Firmware implements a framework that allows CPU and platform ports to -perform actions very early after a CPU is released from reset in both the cold -and warm boot paths. This is done by calling the `reset_handler()` function in -both the BL1 and BL31 images. It in turn calls the platform and CPU specific -reset handling functions. - -Details for implementing a CPU specific reset handler can be found in -Section 8. Details for implementing a platform specific reset handler can be -found in the [Porting Guide] (see the `plat_reset_handler()` function). - -When adding functionality to a reset handler, keep in mind that if a different -reset handling behavior is required between the first and the subsequent -invocations of the reset handling code, this should be detected at runtime. -In other words, the reset handler should be able to detect whether an action has -already been performed and act as appropriate. Possible courses of actions are, -e.g. skip the action the second time, or undo/redo it. - -8. CPU specific operations framework -------------------------------------- - -Certain aspects of the ARMv8 architecture are implementation defined, -that is, certain behaviours are not architecturally defined, but must be defined -and documented by individual processor implementations. The ARM Trusted -Firmware implements a framework which categorises the common implementation -defined behaviours and allows a processor to export its implementation of that -behaviour. The categories are: - -1. Processor specific reset sequence. - -2. Processor specific power down sequences. - -3. Processor specific register dumping as a part of crash reporting. - -4. Errata status reporting. - -Each of the above categories fulfils a different requirement. - -1. allows any processor specific initialization before the caches and MMU - are turned on, like implementation of errata workarounds, entry into - the intra-cluster coherency domain etc. - -2. allows each processor to implement the power down sequence mandated in - its Technical Reference Manual (TRM). - -3. allows a processor to provide additional information to the developer - in the event of a crash, for example Cortex-A53 has registers which - can expose the data cache contents. - -4. allows a processor to define a function that inspects and reports the status - of all errata workarounds on that processor. - -Please note that only 2. is mandated by the TRM. - -The CPU specific operations framework scales to accommodate a large number of -different CPUs during power down and reset handling. The platform can specify -any CPU optimization it wants to enable for each CPU. It can also specify -the CPU errata workarounds to be applied for each CPU type during reset -handling by defining CPU errata compile time macros. Details on these macros -can be found in the [cpu-specific-build-macros.md][CPUBM] file. - -The CPU specific operations framework depends on the `cpu_ops` structure which -needs to be exported for each type of CPU in the platform. It is defined in -`include/lib/cpus/aarch64/cpu_macros.S` and has the following fields : `midr`, -`reset_func()`, `cpu_pwr_down_ops` (array of power down functions) and -`cpu_reg_dump()`. - -The CPU specific files in `lib/cpus` export a `cpu_ops` data structure with -suitable handlers for that CPU. For example, `lib/cpus/aarch64/cortex_a53.S` -exports the `cpu_ops` for Cortex-A53 CPU. According to the platform -configuration, these CPU specific files must be included in the build by -the platform makefile. The generic CPU specific operations framework code exists -in `lib/cpus/aarch64/cpu_helpers.S`. - -### CPU specific Reset Handling - -After a reset, the state of the CPU when it calls generic reset handler is: -MMU turned off, both instruction and data caches turned off and not part -of any coherency domain. - -The BL entrypoint code first invokes the `plat_reset_handler()` to allow -the platform to perform any system initialization required and any system -errata workarounds that needs to be applied. The `get_cpu_ops_ptr()` reads -the current CPU midr, finds the matching `cpu_ops` entry in the `cpu_ops` -array and returns it. Note that only the part number and implementer fields -in midr are used to find the matching `cpu_ops` entry. The `reset_func()` in -the returned `cpu_ops` is then invoked which executes the required reset -handling for that CPU and also any errata workarounds enabled by the platform. -This function must preserve the values of general purpose registers x20 to x29. - -Refer to Section "Guidelines for Reset Handlers" for general guidelines -regarding placement of code in a reset handler. - -### CPU specific power down sequence - -During the BL31 initialization sequence, the pointer to the matching `cpu_ops` -entry is stored in per-CPU data by `init_cpu_ops()` so that it can be quickly -retrieved during power down sequences. - -Various CPU drivers register handlers to perform power down at certain power -levels for that specific CPU. The PSCI service, upon receiving a power down -request, determines the highest power level at which to execute power down -sequence for a particular CPU. It uses the `prepare_cpu_pwr_dwn()` function to -pick the right power down handler for the requested level. The function -retrieves `cpu_ops` pointer member of per-CPU data, and from that, further -retrieves `cpu_pwr_down_ops` array, and indexes into the required level. If the -requested power level is higher than what a CPU driver supports, the handler -registered for highest level is invoked. - -At runtime the platform hooks for power down are invoked by the PSCI service to -perform platform specific operations during a power down sequence, for example -turning off CCI coherency during a cluster power down. - -### CPU specific register reporting during crash - -If the crash reporting is enabled in BL31, when a crash occurs, the crash -reporting framework calls `do_cpu_reg_dump` which retrieves the matching -`cpu_ops` using `get_cpu_ops_ptr()` function. The `cpu_reg_dump()` in -`cpu_ops` is invoked, which then returns the CPU specific register values to -be reported and a pointer to the ASCII list of register names in a format -expected by the crash reporting framework. - -### CPU errata status reporting - -Errata workarounds for CPUs supported in ARM Trusted Firmware are applied during -both cold and warm boots, shortly after reset. Individual Errata workarounds are -enabled as build options. Some errata workarounds have potential run-time -implications; therefore some are enabled by default, others not. Platform ports -shall override build options to enable or disable errata as appropriate. The CPU -drivers take care of applying errata workarounds that are enabled and applicable -to a given CPU. Refer to the section titled _CPU Errata Workarounds_ in [CPUBM] -for more information. - -Functions in CPU drivers that apply errata workaround must follow the -conventions listed below. - -The errata workaround must be authored as two separate functions: - -* One that checks for errata. This function must determine whether that errata - applies to the current CPU. Typically this involves matching the current - CPUs revision and variant against a value that's known to be affected by the - errata. If the function determines that the errata applies to this CPU, it - must return `ERRATA_APPLIES`; otherwise, it must return - `ERRATA_NOT_APPLIES`. The utility functions `cpu_get_rev_var` and - `cpu_rev_var_ls` functions may come in handy for this purpose. - - For an errata identified as `E`, the check function must be named - `check_errata_E`. - - This function will be invoked at different times, both from assembly and from - C run time. Therefore it must follow AAPCS, and must not use stack. - -* Another one that applies the errata workaround. This function would call the - check function described above, and applies errata workaround if required. - -CPU drivers that apply errata workaround can optionally implement an assembly -function that report the status of errata workarounds pertaining to that CPU. -For a driver that registers the CPU, for example, `cpux` via. `declare_cpu_ops` -macro, the errata reporting function, if it exists, must be named -`cpux_errata_report`. This function will always be called with MMU enabled; it -must follow AAPCS and may use stack. - -In a debug build of ARM Trusted Firmware, on a CPU that comes out of reset, both -BL1 and the run time firmware (BL31 in AArch64, and BL32 in AArch32) will invoke -errata status reporting function, if one exists, for that type of CPU. - -To report the status of each errata workaround, the function shall use the -assembler macro `report_errata`, passing it: - -* The build option that enables the errata; - -* The name of the CPU: this must be the same identifier that CPU driver - registered itself with, using `declare_cpu_ops`; - -* And the errata identifier: the identifier must match what's used in the - errata's check function described above. - -The errata status reporting function will be called once per CPU type/errata -combination during the software's active life time. - -It's expected that whenever an errata workaround is submitted to ARM Trusted -Firmware, the errata reporting function is appropriately extended to report its -status as well. - -Reporting the status of errata workaround is for informational purpose only; it -has no functional significance. - -9. Memory layout of BL images ------------------------------ - -Each bootloader image can be divided in 2 parts: - - * the static contents of the image. These are data actually stored in the - binary on the disk. In the ELF terminology, they are called `PROGBITS` - sections; - - * the run-time contents of the image. These are data that don't occupy any - space in the binary on the disk. The ELF binary just contains some - metadata indicating where these data will be stored at run-time and the - corresponding sections need to be allocated and initialized at run-time. - In the ELF terminology, they are called `NOBITS` sections. - -All PROGBITS sections are grouped together at the beginning of the image, -followed by all NOBITS sections. This is true for all Trusted Firmware images -and it is governed by the linker scripts. This ensures that the raw binary -images are as small as possible. If a NOBITS section was inserted in between -PROGBITS sections then the resulting binary file would contain zero bytes in -place of this NOBITS section, making the image unnecessarily bigger. Smaller -images allow faster loading from the FIP to the main memory. - -### Linker scripts and symbols - -Each bootloader stage image layout is described by its own linker script. The -linker scripts export some symbols into the program symbol table. Their values -correspond to particular addresses. The trusted firmware code can refer to these -symbols to figure out the image memory layout. - -Linker symbols follow the following naming convention in the trusted firmware. - -* `__<SECTION>_START__` - - Start address of a given section named `<SECTION>`. - -* `__<SECTION>_END__` - - End address of a given section named `<SECTION>`. If there is an alignment - constraint on the section's end address then `__<SECTION>_END__` corresponds - to the end address of the section's actual contents, rounded up to the right - boundary. Refer to the value of `__<SECTION>_UNALIGNED_END__` to know the - actual end address of the section's contents. - -* `__<SECTION>_UNALIGNED_END__` - - End address of a given section named `<SECTION>` without any padding or - rounding up due to some alignment constraint. - -* `__<SECTION>_SIZE__` - - Size (in bytes) of a given section named `<SECTION>`. If there is an - alignment constraint on the section's end address then `__<SECTION>_SIZE__` - corresponds to the size of the section's actual contents, rounded up to the - right boundary. In other words, `__<SECTION>_SIZE__ = __<SECTION>_END__ - - _<SECTION>_START__`. Refer to the value of `__<SECTION>_UNALIGNED_SIZE__` - to know the actual size of the section's contents. - -* `__<SECTION>_UNALIGNED_SIZE__` - - Size (in bytes) of a given section named `<SECTION>` without any padding or - rounding up due to some alignment constraint. In other words, - `__<SECTION>_UNALIGNED_SIZE__ = __<SECTION>_UNALIGNED_END__ - - __<SECTION>_START__`. - -Some of the linker symbols are mandatory as the trusted firmware code relies on -them to be defined. They are listed in the following subsections. Some of them -must be provided for each bootloader stage and some are specific to a given -bootloader stage. - -The linker scripts define some extra, optional symbols. They are not actually -used by any code but they help in understanding the bootloader images' memory -layout as they are easy to spot in the link map files. - -#### Common linker symbols - -All BL images share the following requirements: - -* The BSS section must be zero-initialised before executing any C code. -* The coherent memory section (if enabled) must be zero-initialised as well. -* The MMU setup code needs to know the extents of the coherent and read-only - memory regions to set the right memory attributes. When - `SEPARATE_CODE_AND_RODATA=1`, it needs to know more specifically how the - read-only memory region is divided between code and data. - -The following linker symbols are defined for this purpose: - -* `__BSS_START__` -* `__BSS_SIZE__` -* `__COHERENT_RAM_START__` Must be aligned on a page-size boundary. -* `__COHERENT_RAM_END__` Must be aligned on a page-size boundary. -* `__COHERENT_RAM_UNALIGNED_SIZE__` -* `__RO_START__` -* `__RO_END__` -* `__TEXT_START__` -* `__TEXT_END__` -* `__RODATA_START__` -* `__RODATA_END__` - -#### BL1's linker symbols - -BL1 being the ROM image, it has additional requirements. BL1 resides in ROM and -it is entirely executed in place but it needs some read-write memory for its -mutable data. Its `.data` section (i.e. its allocated read-write data) must be -relocated from ROM to RAM before executing any C code. - -The following additional linker symbols are defined for BL1: - -* `__BL1_ROM_END__` End address of BL1's ROM contents, covering its code - and `.data` section in ROM. -* `__DATA_ROM_START__` Start address of the `.data` section in ROM. Must be - aligned on a 16-byte boundary. -* `__DATA_RAM_START__` Address in RAM where the `.data` section should be - copied over. Must be aligned on a 16-byte boundary. -* `__DATA_SIZE__` Size of the `.data` section (in ROM or RAM). -* `__BL1_RAM_START__` Start address of BL1 read-write data. -* `__BL1_RAM_END__` End address of BL1 read-write data. - - -### How to choose the right base addresses for each bootloader stage image - -There is currently no support for dynamic image loading in the Trusted Firmware. -This means that all bootloader images need to be linked against their ultimate -runtime locations and the base addresses of each image must be chosen carefully -such that images don't overlap each other in an undesired way. As the code -grows, the base addresses might need adjustments to cope with the new memory -layout. - -The memory layout is completely specific to the platform and so there is no -general recipe for choosing the right base addresses for each bootloader image. -However, there are tools to aid in understanding the memory layout. These are -the link map files: `build/<platform>/<build-type>/bl<x>/bl<x>.map`, with `<x>` -being the stage bootloader. They provide a detailed view of the memory usage of -each image. Among other useful information, they provide the end address of -each image. - -* `bl1.map` link map file provides `__BL1_RAM_END__` address. -* `bl2.map` link map file provides `__BL2_END__` address. -* `bl31.map` link map file provides `__BL31_END__` address. -* `bl32.map` link map file provides `__BL32_END__` address. - -For each bootloader image, the platform code must provide its start address -as well as a limit address that it must not overstep. The latter is used in the -linker scripts to check that the image doesn't grow past that address. If that -happens, the linker will issue a message similar to the following: - - aarch64-none-elf-ld: BLx has exceeded its limit. - -Additionally, if the platform memory layout implies some image overlaying like -on FVP, BL31 and TSP need to know the limit address that their PROGBITS -sections must not overstep. The platform code must provide those. - -When LOAD_IMAGE_V2 is disabled, Trusted Firmware provides a mechanism to -verify at boot time that the memory to load a new image is free to prevent -overwriting a previously loaded image. For this mechanism to work, the platform -must specify the memory available in the system as regions, where each region -consists of base address, total size and the free area within it (as defined -in the `meminfo_t` structure). Trusted Firmware retrieves these memory regions -by calling the corresponding platform API: - -* `meminfo_t *bl1_plat_sec_mem_layout(void)` -* `meminfo_t *bl2_plat_sec_mem_layout(void)` -* `void bl2_plat_get_scp_bl2_meminfo(meminfo_t *scp_bl2_meminfo)` -* `void bl2_plat_get_bl32_meminfo(meminfo_t *bl32_meminfo)` -* `void bl2_plat_get_bl33_meminfo(meminfo_t *bl33_meminfo)` - -For example, in the case of BL1 loading BL2, `bl1_plat_sec_mem_layout()` will -return the region defined by the platform where BL1 intends to load BL2. The -`load_image()` function will check that the memory where BL2 will be loaded is -within the specified region and marked as free. - -The actual number of regions and their base addresses and sizes is platform -specific. The platform may return the same region or define a different one for -each API. However, the overlap verification mechanism applies only to a single -region. Hence, it is the platform responsibility to guarantee that different -regions do not overlap, or that if they do, the overlapping images are not -accessed at the same time. This could be used, for example, to load temporary -images (e.g. certificates) or firmware images prior to being transfered to its -corresponding processor (e.g. the SCP BL2 image). - -To reduce fragmentation and simplify the tracking of free memory, all the free -memory within a region is always located in one single buffer defined by its -base address and size. Trusted Firmware implements a top/bottom load approach: -after a new image is loaded, it checks how much memory remains free above and -below the image. The smallest area is marked as unavailable, while the larger -area becomes the new free memory buffer. Platforms should take this behaviour -into account when defining the base address for each of the images. For example, -if an image is loaded near the middle of the region, small changes in image size -could cause a flip between a top load and a bottom load, which may result in an -unexpected memory layout. - -The following diagram is an example of an image loaded in the bottom part of -the memory region. The region is initially free (nothing has been loaded yet): - - Memory region - +----------+ - | | - | | <<<<<<<<<<<<< Free - | | - |----------| +------------+ - | image | <<<<<<<<<<<<< | image | - |----------| +------------+ - | xxxxxxxx | <<<<<<<<<<<<< Marked as unavailable - +----------+ - -And the following diagram is an example of an image loaded in the top part: - - Memory region - +----------+ - | xxxxxxxx | <<<<<<<<<<<<< Marked as unavailable - |----------| +------------+ - | image | <<<<<<<<<<<<< | image | - |----------| +------------+ - | | - | | <<<<<<<<<<<<< Free - | | - +----------+ - - -When LOAD_IMAGE_V2 is enabled, Trusted Firmware does not provide any mechanism -to verify at boot time that the memory to load a new image is free to prevent -overwriting a previously loaded image. The platform must specify the memory -available in the system for all the relevant BL images to be loaded. - -For example, in the case of BL1 loading BL2, `bl1_plat_sec_mem_layout()` will -return the region defined by the platform where BL1 intends to load BL2. The -`load_image()` function performs bounds check for the image size based on the -base and maximum image size provided by the platforms. Platforms must take -this behaviour into account when defining the base/size for each of the images. - -#### Memory layout on ARM development platforms - -The following list describes the memory layout on the ARM development platforms: - -* A 4KB page of shared memory is used for communication between Trusted - Firmware and the platform's power controller. This is located at the base of - Trusted SRAM. The amount of Trusted SRAM available to load the bootloader - images is reduced by the size of the shared memory. - - The shared memory is used to store the CPUs' entrypoint mailbox. On Juno, - this is also used for the MHU payload when passing messages to and from the - SCP. - -* On FVP, BL1 is originally sitting in the Trusted ROM at address `0x0`. On - Juno, BL1 resides in flash memory at address `0x0BEC0000`. BL1 read-write - data are relocated to the top of Trusted SRAM at runtime. - -* EL3 Runtime Software, BL31 for AArch64 and BL32 for AArch32 (e.g. SP_MIN), - is loaded at the top of the Trusted SRAM, such that its NOBITS sections will - overwrite BL1 R/W data. This implies that BL1 global variables remain valid - only until execution reaches the EL3 Runtime Software entry point during a - cold boot. - -* BL2 is loaded below EL3 Runtime Software. - -* On Juno, SCP_BL2 is loaded temporarily into the EL3 Runtime Software memory - region and transfered to the SCP before being overwritten by EL3 Runtime - Software. - -* BL32 (for AArch64) can be loaded in one of the following locations: - - * Trusted SRAM - * Trusted DRAM (FVP only) - * Secure region of DRAM (top 16MB of DRAM configured by the TrustZone - controller) - - When BL32 (for AArch64) is loaded into Trusted SRAM, its NOBITS sections - are allowed to overlay BL2. This memory layout is designed to give the - BL32 image as much memory as possible when it is loaded into Trusted SRAM. - -When LOAD_IMAGE_V2 is disabled the memory regions for the overlap detection -mechanism at boot time are defined as follows (shown per API): - -* `meminfo_t *bl1_plat_sec_mem_layout(void)` - - This region corresponds to the whole Trusted SRAM except for the shared - memory at the base. This region is initially free. At boot time, BL1 will - mark the BL1(rw) section within this region as occupied. The BL1(rw) section - is placed at the top of Trusted SRAM. - -* `meminfo_t *bl2_plat_sec_mem_layout(void)` - - This region corresponds to the whole Trusted SRAM as defined by - `bl1_plat_sec_mem_layout()`, but with the BL1(rw) section marked as - occupied. This memory region is used to check that BL2 and BL31 do not - overlap with each other. BL2_BASE and BL1_RW_BASE are carefully chosen so - that the memory for BL31 is top loaded above BL2. - -* `void bl2_plat_get_scp_bl2_meminfo(meminfo_t *scp_bl2_meminfo)` - - This region is an exact copy of the region defined by - `bl2_plat_sec_mem_layout()`. Being a disconnected copy means that all the - changes made to this region by the Trusted Firmware will not be propagated. - This approach is valid because the SCP BL2 image is loaded temporarily - while it is being transferred to the SCP, so this memory is reused - afterwards. - -* `void bl2_plat_get_bl32_meminfo(meminfo_t *bl32_meminfo)` - - This region depends on the location of the BL32 image. Currently, ARM - platforms support three different locations (detailed below): Trusted SRAM, - Trusted DRAM and the TZC-Secured DRAM. - -* `void bl2_plat_get_bl33_meminfo(meminfo_t *bl33_meminfo)` - - This region corresponds to the Non-Secure DDR-DRAM, excluding the - TZC-Secured area. - -The location of the BL32 image will result in different memory maps. This is -illustrated for both FVP and Juno in the following diagrams, using the TSP as -an example. - -Note: Loading the BL32 image in TZC secured DRAM doesn't change the memory -layout of the other images in Trusted SRAM. - -**FVP with TSP in Trusted SRAM (default option):** -(These diagrams only cover the AArch64 case) - - Trusted SRAM - 0x04040000 +----------+ loaded by BL2 ------------------ - | BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS | - |----------| <<<<<<<<<<<<< |----------------| - | | <<<<<<<<<<<<< | BL31 PROGBITS | - |----------| ------------------ - | BL2 | <<<<<<<<<<<<< | BL32 NOBITS | - |----------| <<<<<<<<<<<<< |----------------| - | | <<<<<<<<<<<<< | BL32 PROGBITS | - 0x04001000 +----------+ ------------------ - | Shared | - 0x04000000 +----------+ - - Trusted ROM - 0x04000000 +----------+ - | BL1 (ro) | - 0x00000000 +----------+ - - -**FVP with TSP in Trusted DRAM:** - - Trusted DRAM - 0x08000000 +----------+ - | BL32 | - 0x06000000 +----------+ - - Trusted SRAM - 0x04040000 +----------+ loaded by BL2 ------------------ - | BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS | - |----------| <<<<<<<<<<<<< |----------------| - | | <<<<<<<<<<<<< | BL31 PROGBITS | - |----------| ------------------ - | BL2 | - |----------| - | | - 0x04001000 +----------+ - | Shared | - 0x04000000 +----------+ - - Trusted ROM - 0x04000000 +----------+ - | BL1 (ro) | - 0x00000000 +----------+ - -**FVP with TSP in TZC-Secured DRAM:** - - DRAM - 0xffffffff +----------+ - | BL32 | (secure) - 0xff000000 +----------+ - | | - : : (non-secure) - | | - 0x80000000 +----------+ - - Trusted SRAM - 0x04040000 +----------+ loaded by BL2 ------------------ - | BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS | - |----------| <<<<<<<<<<<<< |----------------| - | | <<<<<<<<<<<<< | BL31 PROGBITS | - |----------| ------------------ - | BL2 | - |----------| - | | - 0x04001000 +----------+ - | Shared | - 0x04000000 +----------+ - - Trusted ROM - 0x04000000 +----------+ - | BL1 (ro) | - 0x00000000 +----------+ - - -**Juno with BL32 in Trusted SRAM (default option):** - - Flash0 - 0x0C000000 +----------+ - : : - 0x0BED0000 |----------| - | BL1 (ro) | - 0x0BEC0000 |----------| - : : - 0x08000000 +----------+ BL31 is loaded - after SCP_BL2 has - Trusted SRAM been sent to SCP - 0x04040000 +----------+ loaded by BL2 ------------------ - | BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS | - |----------| <<<<<<<<<<<<< |----------------| - | SCP_BL2 | <<<<<<<<<<<<< | BL31 PROGBITS | - |----------| ------------------ - | BL2 | <<<<<<<<<<<<< | BL32 NOBITS | - |----------| <<<<<<<<<<<<< |----------------| - | | <<<<<<<<<<<<< | BL32 PROGBITS | - 0x04001000 +----------+ ------------------ - | MHU | - 0x04000000 +----------+ - - -**Juno with BL32 in TZC-secured DRAM:** - - DRAM - 0xFFE00000 +----------+ - | BL32 | (secure) - 0xFF000000 |----------| - | | - : : (non-secure) - | | - 0x80000000 +----------+ - - Flash0 - 0x0C000000 +----------+ - : : - 0x0BED0000 |----------| - | BL1 (ro) | - 0x0BEC0000 |----------| - : : - 0x08000000 +----------+ BL31 is loaded - after SCP_BL2 has - Trusted SRAM been sent to SCP - 0x04040000 +----------+ loaded by BL2 ------------------ - | BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS | - |----------| <<<<<<<<<<<<< |----------------| - | SCP_BL2 | <<<<<<<<<<<<< | BL31 PROGBITS | - |----------| ------------------ - | BL2 | - |----------| - | | - 0x04001000 +----------+ - | MHU | - 0x04000000 +----------+ - - -10. Firmware Image Package (FIP) ---------------------------------- - -Using a Firmware Image Package (FIP) allows for packing bootloader images (and -potentially other payloads) into a single archive that can be loaded by the ARM -Trusted Firmware from non-volatile platform storage. A driver to load images -from a FIP has been added to the storage layer and allows a package to be read -from supported platform storage. A tool to create Firmware Image Packages is -also provided and described below. - -### Firmware Image Package layout - -The FIP layout consists of a table of contents (ToC) followed by payload data. -The ToC itself has a header followed by one or more table entries. The ToC is -terminated by an end marker entry. All ToC entries describe some payload data -that has been appended to the end of the binary package. With the information -provided in the ToC entry the corresponding payload data can be retrieved. - - ------------------ - | ToC Header | - |----------------| - | ToC Entry 0 | - |----------------| - | ToC Entry 1 | - |----------------| - | ToC End Marker | - |----------------| - | | - | Data 0 | - | | - |----------------| - | | - | Data 1 | - | | - ------------------ - -The ToC header and entry formats are described in the header file -`include/tools_share/firmware_image_package.h`. This file is used by both the -tool and the ARM Trusted firmware. - -The ToC header has the following fields: - - `name`: The name of the ToC. This is currently used to validate the header. - `serial_number`: A non-zero number provided by the creation tool - `flags`: Flags associated with this data. - Bits 0-31: Reserved - Bits 32-47: Platform defined - Bits 48-63: Reserved - -A ToC entry has the following fields: - - `uuid`: All files are referred to by a pre-defined Universally Unique - IDentifier [UUID] . The UUIDs are defined in - `include/tools_share/firmware_image_package.h`. The platform translates - the requested image name into the corresponding UUID when accessing the - package. - `offset_address`: The offset address at which the corresponding payload data - can be found. The offset is calculated from the ToC base address. - `size`: The size of the corresponding payload data in bytes. - `flags`: Flags associated with this entry. Non are yet defined. - -### Firmware Image Package creation tool - -The FIP creation tool can be used to pack specified images into a binary package -that can be loaded by the ARM Trusted Firmware from platform storage. The tool -currently only supports packing bootloader images. Additional image definitions -can be added to the tool as required. - -The tool can be found in `tools/fiptool`. - -### Loading from a Firmware Image Package (FIP) - -The Firmware Image Package (FIP) driver can load images from a binary package on -non-volatile platform storage. For the ARM development platforms, this is -currently NOR FLASH. - -Bootloader images are loaded according to the platform policy as specified by -the function `plat_get_image_source()`. For the ARM development platforms, this -means the platform will attempt to load images from a Firmware Image Package -located at the start of NOR FLASH0. - -The ARM development platforms' policy is to only allow loading of a known set of -images. The platform policy can be modified to allow additional images. - - -11. Use of coherent memory in Trusted Firmware ------------------------------------------------ - -There might be loss of coherency when physical memory with mismatched -shareability, cacheability and memory attributes is accessed by multiple CPUs -(refer to section B2.9 of [ARM ARM] for more details). This possibility occurs -in Trusted Firmware during power up/down sequences when coherency, MMU and -caches are turned on/off incrementally. - -Trusted Firmware defines coherent memory as a region of memory with Device -nGnRE attributes in the translation tables. The translation granule size in -Trusted Firmware is 4KB. This is the smallest possible size of the coherent -memory region. - -By default, all data structures which are susceptible to accesses with -mismatched attributes from various CPUs are allocated in a coherent memory -region (refer to section 2.1 of [Porting Guide]). The coherent memory region -accesses are Outer Shareable, non-cacheable and they can be accessed -with the Device nGnRE attributes when the MMU is turned on. Hence, at the -expense of at least an extra page of memory, Trusted Firmware is able to work -around coherency issues due to mismatched memory attributes. - -The alternative to the above approach is to allocate the susceptible data -structures in Normal WriteBack WriteAllocate Inner shareable memory. This -approach requires the data structures to be designed so that it is possible to -work around the issue of mismatched memory attributes by performing software -cache maintenance on them. - -### Disabling the use of coherent memory in Trusted Firmware - -It might be desirable to avoid the cost of allocating coherent memory on -platforms which are memory constrained. Trusted Firmware enables inclusion of -coherent memory in firmware images through the build flag `USE_COHERENT_MEM`. -This flag is enabled by default. It can be disabled to choose the second -approach described above. - -The below sections analyze the data structures allocated in the coherent memory -region and the changes required to allocate them in normal memory. - -### Coherent memory usage in PSCI implementation - -The `psci_non_cpu_pd_nodes` data structure stores the platform's power domain -tree information for state management of power domains. By default, this data -structure is allocated in the coherent memory region in the Trusted Firmware -because it can be accessed by multple CPUs, either with caches enabled or -disabled. - - typedef struct non_cpu_pwr_domain_node { - /* - * Index of the first CPU power domain node level 0 which has this node - * as its parent. - */ - unsigned int cpu_start_idx; - - /* - * Number of CPU power domains which are siblings of the domain indexed - * by 'cpu_start_idx' i.e. all the domains in the range 'cpu_start_idx - * -> cpu_start_idx + ncpus' have this node as their parent. - */ - unsigned int ncpus; - - /* - * Index of the parent power domain node. - * TODO: Figure out whether to whether using pointer is more efficient. - */ - unsigned int parent_node; - - plat_local_state_t local_state; - - unsigned char level; - - /* For indexing the psci_lock array*/ - unsigned char lock_index; - } non_cpu_pd_node_t; - -In order to move this data structure to normal memory, the use of each of its -fields must be analyzed. Fields like `cpu_start_idx`, `ncpus`, `parent_node` -`level` and `lock_index` are only written once during cold boot. Hence removing -them from coherent memory involves only doing a clean and invalidate of the -cache lines after these fields are written. - -The field `local_state` can be concurrently accessed by multiple CPUs in -different cache states. A Lamport's Bakery lock `psci_locks` is used to ensure -mutual exlusion to this field and a clean and invalidate is needed after it -is written. - -### Bakery lock data - -The bakery lock data structure `bakery_lock_t` is allocated in coherent memory -and is accessed by multiple CPUs with mismatched attributes. `bakery_lock_t` is -defined as follows: - - typedef struct bakery_lock { - /* - * The lock_data is a bit-field of 2 members: - * Bit[0] : choosing. This field is set when the CPU is - * choosing its bakery number. - * Bits[1 - 15] : number. This is the bakery number allocated. - */ - volatile uint16_t lock_data[BAKERY_LOCK_MAX_CPUS]; - } bakery_lock_t; - -It is a characteristic of Lamport's Bakery algorithm that the volatile per-CPU -fields can be read by all CPUs but only written to by the owning CPU. - -Depending upon the data cache line size, the per-CPU fields of the -`bakery_lock_t` structure for multiple CPUs may exist on a single cache line. -These per-CPU fields can be read and written during lock contention by multiple -CPUs with mismatched memory attributes. Since these fields are a part of the -lock implementation, they do not have access to any other locking primitive to -safeguard against the resulting coherency issues. As a result, simple software -cache maintenance is not enough to allocate them in coherent memory. Consider -the following example. - -CPU0 updates its per-CPU field with data cache enabled. This write updates a -local cache line which contains a copy of the fields for other CPUs as well. Now -CPU1 updates its per-CPU field of the `bakery_lock_t` structure with data cache -disabled. CPU1 then issues a DCIVAC operation to invalidate any stale copies of -its field in any other cache line in the system. This operation will invalidate -the update made by CPU0 as well. - -To use bakery locks when `USE_COHERENT_MEM` is disabled, the lock data structure -has been redesigned. The changes utilise the characteristic of Lamport's Bakery -algorithm mentioned earlier. The bakery_lock structure only allocates the memory -for a single CPU. The macro `DEFINE_BAKERY_LOCK` allocates all the bakery locks -needed for a CPU into a section `bakery_lock`. The linker allocates the memory -for other cores by using the total size allocated for the bakery_lock section -and multiplying it with (PLATFORM_CORE_COUNT - 1). This enables software to -perform software cache maintenance on the lock data structure without running -into coherency issues associated with mismatched attributes. - -The bakery lock data structure `bakery_info_t` is defined for use when -`USE_COHERENT_MEM` is disabled as follows: - - typedef struct bakery_info { - /* - * The lock_data is a bit-field of 2 members: - * Bit[0] : choosing. This field is set when the CPU is - * choosing its bakery number. - * Bits[1 - 15] : number. This is the bakery number allocated. - */ - volatile uint16_t lock_data; - } bakery_info_t; - -The `bakery_info_t` represents a single per-CPU field of one lock and -the combination of corresponding `bakery_info_t` structures for all CPUs in the -system represents the complete bakery lock. The view in memory for a system -with n bakery locks are: - - bakery_lock section start - |----------------| - | `bakery_info_t`| <-- Lock_0 per-CPU field - | Lock_0 | for CPU0 - |----------------| - | `bakery_info_t`| <-- Lock_1 per-CPU field - | Lock_1 | for CPU0 - |----------------| - | .... | - |----------------| - | `bakery_info_t`| <-- Lock_N per-CPU field - | Lock_N | for CPU0 - ------------------ - | XXXXX | - | Padding to | - | next Cache WB | <--- Calculate PERCPU_BAKERY_LOCK_SIZE, allocate - | Granule | continuous memory for remaining CPUs. - ------------------ - | `bakery_info_t`| <-- Lock_0 per-CPU field - | Lock_0 | for CPU1 - |----------------| - | `bakery_info_t`| <-- Lock_1 per-CPU field - | Lock_1 | for CPU1 - |----------------| - | .... | - |----------------| - | `bakery_info_t`| <-- Lock_N per-CPU field - | Lock_N | for CPU1 - ------------------ - | XXXXX | - | Padding to | - | next Cache WB | - | Granule | - ------------------ - -Consider a system of 2 CPUs with 'N' bakery locks as shown above. For an -operation on Lock_N, the corresponding `bakery_info_t` in both CPU0 and CPU1 -`bakery_lock` section need to be fetched and appropriate cache operations need -to be performed for each access. - -On ARM Platforms, bakery locks are used in psci (`psci_locks`) and power controller -driver (`arm_lock`). - - -### Non Functional Impact of removing coherent memory - -Removal of the coherent memory region leads to the additional software overhead -of performing cache maintenance for the affected data structures. However, since -the memory where the data structures are allocated is cacheable, the overhead is -mostly mitigated by an increase in performance. - -There is however a performance impact for bakery locks, due to: -* Additional cache maintenance operations, and -* Multiple cache line reads for each lock operation, since the bakery locks - for each CPU are distributed across different cache lines. - -The implementation has been optimized to minimize this additional overhead. -Measurements indicate that when bakery locks are allocated in Normal memory, the -minimum latency of acquiring a lock is on an average 3-4 micro seconds whereas -in Device memory the same is 2 micro seconds. The measurements were done on the -Juno ARM development platform. - -As mentioned earlier, almost a page of memory can be saved by disabling -`USE_COHERENT_MEM`. Each platform needs to consider these trade-offs to decide -whether coherent memory should be used. If a platform disables -`USE_COHERENT_MEM` and needs to use bakery locks in the porting layer, it can -optionally define macro `PLAT_PERCPU_BAKERY_LOCK_SIZE` (see the [Porting -Guide]). Refer to the reference platform code for examples. - - -12. Isolating code and read-only data on separate memory pages ---------------------------------------------------------------- - -In the ARMv8 VMSA, translation table entries include fields that define the -properties of the target memory region, such as its access permissions. The -smallest unit of memory that can be addressed by a translation table entry is -a memory page. Therefore, if software needs to set different permissions on two -memory regions then it needs to map them using different memory pages. - -The default memory layout for each BL image is as follows: - - | ... | - +-------------------+ - | Read-write data | - +-------------------+ Page boundary - | <Padding> | - +-------------------+ - | Exception vectors | - +-------------------+ 2 KB boundary - | <Padding> | - +-------------------+ - | Read-only data | - +-------------------+ - | Code | - +-------------------+ BLx_BASE - -Note: The 2KB alignment for the exception vectors is an architectural -requirement. - -The read-write data start on a new memory page so that they can be mapped with -read-write permissions, whereas the code and read-only data below are configured -as read-only. - -However, the read-only data are not aligned on a page boundary. They are -contiguous to the code. Therefore, the end of the code section and the beginning -of the read-only data one might share a memory page. This forces both to be -mapped with the same memory attributes. As the code needs to be executable, this -means that the read-only data stored on the same memory page as the code are -executable as well. This could potentially be exploited as part of a security -attack. - -TF provides the build flag `SEPARATE_CODE_AND_RODATA` to isolate the code and -read-only data on separate memory pages. This in turn allows independent control -of the access permissions for the code and read-only data. In this case, -platform code gets a finer-grained view of the image layout and can -appropriately map the code region as executable and the read-only data as -execute-never. - -This has an impact on memory footprint, as padding bytes need to be introduced -between the code and read-only data to ensure the segragation of the two. To -limit the memory cost, this flag also changes the memory layout such that the -code and exception vectors are now contiguous, like so: - - | ... | - +-------------------+ - | Read-write data | - +-------------------+ Page boundary - | <Padding> | - +-------------------+ - | Read-only data | - +-------------------+ Page boundary - | <Padding> | - +-------------------+ - | Exception vectors | - +-------------------+ 2 KB boundary - | <Padding> | - +-------------------+ - | Code | - +-------------------+ BLx_BASE - -With this more condensed memory layout, the separation of read-only data will -add zero or one page to the memory footprint of each BL image. Each platform -should consider the trade-off between memory footprint and security. - -This build flag is disabled by default, minimising memory footprint. On ARM -platforms, it is enabled. - - -13. Performance Measurement Framework --------------------------------------- - -The Performance Measurement Framework (PMF) facilitates collection of -timestamps by registered services and provides interfaces to retrieve -them from within the ARM Trusted Firmware. A platform can choose to -expose appropriate SMCs to retrieve these collected timestamps. - -By default, the global physical counter is used for the timestamp -value and is read via `CNTPCT_EL0`. The framework allows to retrieve -timestamps captured by other CPUs. - -### Timestamp identifier format - -A PMF timestamp is uniquely identified across the system via the -timestamp ID or `tid`. The `tid` is composed as follows: - - Bits 0-7: The local timestamp identifier. - Bits 8-9: Reserved. - Bits 10-15: The service identifier. - Bits 16-31: Reserved. - -1. The service identifier. Each PMF service is identified by a - service name and a service identifier. Both the service name and - identifier are unique within the system as a whole. - -2. The local timestamp identifier. This identifier is unique within a given - service. - -### Registering a PMF service - -To register a PMF service, the `PMF_REGISTER_SERVICE()` macro from `pmf.h` -is used. The arguments required are the service name, the service ID, -the total number of local timestamps to be captured and a set of flags. - -The `flags` field can be specified as a bitwise-OR of the following values: - - PMF_STORE_ENABLE: The timestamp is stored in memory for later retrieval. - PMF_DUMP_ENABLE: The timestamp is dumped on the serial console. - -The `PMF_REGISTER_SERVICE()` reserves memory to store captured -timestamps in a PMF specific linker section at build time. -Additionally, it defines necessary functions to capture and -retrieve a particular timestamp for the given service at runtime. - -The macro `PMF_REGISTER_SERVICE()` only enables capturing PMF -timestamps from within ARM Trusted Firmware. In order to retrieve -timestamps from outside of ARM Trusted Firmware, the -`PMF_REGISTER_SERVICE_SMC()` macro must be used instead. This macro -accepts the same set of arguments as the `PMF_REGISTER_SERVICE()` -macro but additionally supports retrieving timestamps using SMCs. - -### Capturing a timestamp - -PMF timestamps are stored in a per-service timestamp region. On a -system with multiple CPUs, each timestamp is captured and stored -in a per-CPU cache line aligned memory region. - -Having registered the service, the `PMF_CAPTURE_TIMESTAMP()` macro can be -used to capture a timestamp at the location where it is used. The macro -takes the service name, a local timestamp identifier and a flag as arguments. - -The `flags` field argument can be zero, or `PMF_CACHE_MAINT` which -instructs PMF to do cache maintenance following the capture. Cache -maintenance is required if any of the service's timestamps are captured -with data cache disabled. - -To capture a timestamp in assembly code, the caller should use -`pmf_calc_timestamp_addr` macro (defined in `pmf_asm_macros.S`) to -calculate the address of where the timestamp would be stored. The -caller should then read `CNTPCT_EL0` register to obtain the timestamp -and store it at the determined address for later retrieval. - -### Retrieving a timestamp - -From within ARM Trusted Firmware, timestamps for individual CPUs can -be retrieved using either `PMF_GET_TIMESTAMP_BY_MPIDR()` or -`PMF_GET_TIMESTAMP_BY_INDEX()` macros. These macros accept the CPU's MPIDR -value, or its ordinal position, respectively. - -From outside ARM Trusted Firmware, timestamps for individual CPUs can be -retrieved by calling into `pmf_smc_handler()`. - - Interface : pmf_smc_handler() - Argument : unsigned int smc_fid, u_register_t x1, - u_register_t x2, u_register_t x3, - u_register_t x4, void *cookie, - void *handle, u_register_t flags - Return : uintptr_t - - smc_fid: Holds the SMC identifier which is either `PMF_SMC_GET_TIMESTAMP_32` - when the caller of the SMC is running in AArch32 mode - or `PMF_SMC_GET_TIMESTAMP_64` when the caller is running in AArch64 mode. - x1: Timestamp identifier. - x2: The `mpidr` of the CPU for which the timestamp has to be retrieved. - This can be the `mpidr` of a different core to the one initiating - the SMC. In that case, service specific cache maintenance may be - required to ensure the updated copy of the timestamp is returned. - x3: A flags value that is either 0 or `PMF_CACHE_MAINT`. If - `PMF_CACHE_MAINT` is passed, then the PMF code will perform a - cache invalidate before reading the timestamp. This ensures - an updated copy is returned. - -The remaining arguments, `x4`, `cookie`, `handle` and `flags` are unused -in this implementation. - -### PMF code structure - -1. `pmf_main.c` consists of core functions that implement service registration, - initialization, storing, dumping and retrieving timestamps. - -2. `pmf_smc.c` contains the SMC handling for registered PMF services. - -3. `pmf.h` contains the public interface to Performance Measurement Framework. - -4. `pmf_asm_macros.S` consists of macros to facilitate capturing timestamps in - assembly code. - -5. `pmf_helpers.h` is an internal header used by `pmf.h`. - - -14. ARMv8 Architecture Extensions ----------------------------------- - -ARM Trusted Firmware makes use of ARMv8 Architecture Extensions where -applicable. This section lists the usage of Architecture Extensions, and build -flags controlling them. - -In general, and unless individually mentioned, the build options -`ARM_ARCH_MAJOR` and `ARM_ARCH_MINOR` selects the Architecture Extension to -target when building ARM Trusted Firmware. Subsequent ARM Architecture -Extensions are backward compatible with previous versions. - -The build system only requires that `ARM_ARCH_MAJOR` and `ARM_ARCH_MINOR` have a -valid numeric value. These build options only control whether or not -Architecture Extension-specific code is included in the build. Otherwise, ARM -Trusted Firmware targets the base ARMv8.0 architecture; i.e. as if -`ARM_ARCH_MAJOR` == 8 and `ARM_ARCH_MINOR` == 0, which are also their respective -default values. - -See also the _Summary of build options_ in [User Guide]. - -For details on the Architecture Extension and available features, please refer -to the respective Architecture Extension Supplement. - -### ARMv8.1 - -This Architecture Extension is targeted when `ARM_ARCH_MAJOR` >= 8, or when -`ARM_ARCH_MAJOR` == 8 and `ARM_ARCH_MINOR` >= 1. - -* The Compare and Swap instruction is used to implement spinlocks. Otherwise, - the load-/store-exclusive instruction pair is used. - -15. Code Structure -------------------- - -Trusted Firmware code is logically divided between the three boot loader -stages mentioned in the previous sections. The code is also divided into the -following categories (present as directories in the source code): - -* **Platform specific.** Choice of architecture specific code depends upon - the platform. -* **Common code.** This is platform and architecture agnostic code. -* **Library code.** This code comprises of functionality commonly used by all - other code. The PSCI implementation and other EL3 runtime frameworks reside - as Library components. -* **Stage specific.** Code specific to a boot stage. -* **Drivers.** -* **Services.** EL3 runtime services (eg: SPD). Specific SPD services - reside in the `services/spd` directory (e.g. `services/spd/tspd`). - -Each boot loader stage uses code from one or more of the above mentioned -categories. Based upon the above, the code layout looks like this: - - Directory Used by BL1? Used by BL2? Used by BL31? - bl1 Yes No No - bl2 No Yes No - bl31 No No Yes - plat Yes Yes Yes - drivers Yes No Yes - common Yes Yes Yes - lib Yes Yes Yes - services No No Yes - -The build system provides a non configurable build option IMAGE_BLx for each -boot loader stage (where x = BL stage). e.g. for BL1 , IMAGE_BL1 will be -defined by the build system. This enables the Trusted Firmware to compile -certain code only for specific boot loader stages - -All assembler files have the `.S` extension. The linker source files for each -boot stage have the extension `.ld.S`. These are processed by GCC to create the -linker scripts which have the extension `.ld`. - -FDTs provide a description of the hardware platform and are used by the Linux -kernel at boot time. These can be found in the `fdts` directory. - - -16. References ---------------- - -1. Trusted Board Boot Requirements CLIENT PDD (ARM DEN 0006B-5). Available - under NDA through your ARM account representative. - -2. [Power State Coordination Interface PDD][PSCI] - -3. [SMC Calling Convention PDD][SMCCC] - -4. [ARM Trusted Firmware Interrupt Management Design guide][INTRG]. - -- - - - - - - - - - - - - - - - - - - - - - - - - - - -_Copyright (c) 2013-2016, ARM Limited and Contributors. All rights reserved._ - -[ARM ARM]: http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0487a.e/index.html "ARMv8-A Reference Manual (ARM DDI0487A.E)" -[PSCI]: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf "Power State Coordination Interface PDD (ARM DEN 0022D)" -[SMCCC]: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf "SMC Calling Convention PDD (ARM DEN 0028B)" -[UUID]: https://tools.ietf.org/rfc/rfc4122.txt "A Universally Unique IDentifier (UUID) URN Namespace" -[User Guide]: ./user-guide.md -[Porting Guide]: ./porting-guide.md -[Reset Design]: ./reset-design.md -[INTRG]: ./interrupt-framework-design.md -[CPUBM]: ./cpu-specific-build-macros.md -[Firmware Update]: ./firmware-update.md -[PSCI Lib guide]: ./psci-lib-integration-guide.md diff --git a/docs/firmware-update.md b/docs/firmware-update.md deleted file mode 100644 index b04586e3..00000000 --- a/docs/firmware-update.md +++ /dev/null @@ -1,388 +0,0 @@ -ARM Trusted Firmware - Firmware Update Design Guide -=================================================== - -Contents : - -1. [Introduction](#1--introduction) -2. [FWU Overview](#2--fwu-overview) -3. [Image Identification](#3--image-identification) -4. [FWU State Machine](#4--fwu-state-machine) -5. [BL1 SMC Interface](#5--bl1-smc-interface) - -- - - - - - - - - - - - - - - - - - - -1. 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. - - -2. 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: - -1. Export a BL1 SMC interface to interoperate with other FWU images executing - at other Exception Levels. -2. Export a platform interface to provide FWU common code with the information - it needs, and to enable platform specific FWU functionality. See the - [Porting Guide] for details of this interface. - -TF uses abbreviated image terminology for FWU images like for other TF images. -An overview of this terminology can be found [here][TF Image Terminology]. - -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. - - - - -3. Image Identification ------------------------- - -Each FWU image and certificate is identified by a unique ID, defined by the -platform, which BL1 uses to fetch an image descriptor (`image_desc_t`) via a -call to `bl1_plat_get_image_desc()`. The same ID is also used to prepare the -Chain of Trust (Refer to the [Authentication Framework Design][Auth Framework] -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. - - -4. 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. - - - -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. - - -5. 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][UUID] 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._ - - -[Porting Guide]: ./porting-guide.md -[Auth Framework]: ./auth-framework.md -[Trusted Board Boot]: ./trusted-board-boot.md -[TF Image Terminology]: https://github.com/ARM-software/arm-trusted-firmware/wiki/ARM-Trusted-Firmware-Image-Terminology -[UUID]: https://tools.ietf.org/rfc/rfc4122.txt "A Universally Unique IDentifier (UUID) URN Namespace" diff --git a/docs/interrupt-framework-design.md b/docs/interrupt-framework-design.md deleted file mode 100644 index 1deab023..00000000 --- a/docs/interrupt-framework-design.md +++ /dev/null @@ -1,997 +0,0 @@ -ARM Trusted Firmware Interrupt Management Design guide -====================================================== - -Contents : - -1. [Introduction](#1-introduction) - * [Concepts](#11-concepts) - - [Interrupt Types](#111-interrupt-types) - - [Routing Model](#112-routing-model) - - [Valid Routing Models](#113-valid-routing-models) - + [Secure-EL1 Interrupts](#1131-secure-el1-interrupts) - + [Non-secure Interrupts](#1132-non-secure-interrupts) - + [EL3 interrupts](#1133-el3-interrupts) - - [Mapping of Interrupt Type to Signal](#114-mapping-of-interrupt-type-to-signal) - + [Effect of mapping of several interrupt types to one signal](#1141-effect-of-mapping-of-several-interrupt-types-to-one-signal) - - [Assumptions in Interrupt Management Framework](#12-assumptions-in-interrupt-management-framework) - -2. [Interrupt Management](#2-interrupt-management) - * [Software Components](#21-software-components) - * [Interrupt Registration](#22-interrupt-registration) - - [EL3 Runtime Firmware](#221-el3-runtime-firmware) - - [Secure Payload Dispatcher](#222-secure-payload-dispatcher) - + [Test Secure Payload Dispatcher behavior](#2221-test-secure-payload-dispatcher-behavior) - - [Secure Payload](#223-secure-payload) - + [Secure Payload IHF design w.r.t Secure-EL1 interrupts](#2231-secure-payload-ihf-design-wrt-secure-el1-interrupts) - + [Secure Payload IHF design w.r.t Non-secure interrupts](#2232-secure-payload-ihf-design-wrt-non-secure-interrupts) - + [Test Secure Payload behavior](#2233-test-secure-payload-behavior) - * [Interrupt Handling](#23-interrupt-handling) - - [EL3 Runtime Firmware](#231-el3-runtime-firmware) - - [Secure Payload Dispatcher](#232-secure-payload-dispatcher) - + [Interrupt Entry](#2321-interrupt-entry) - + [Interrupt Exit](#2322-interrupt-exit) - + [Test secure payload dispatcher Secure-EL1 interrupt handling](#2323-test-secure-payload-dispatcher-secure-el1-interrupt-handling) - + [Test secure payload dispatcher non-secure interrupt handling](#2324-test-secure-payload-dispatcher-non-secure-interrupt-handling) - - [Secure Payload](#233-secure-payload) - + [Test Secure Payload behavior](#2331-test-secure-payload-behavior) - -3. [Other considerations](#3-other-considerations) - * [Implication of preempted SMC on Non-Secure Software](#31-implication-of-preempted-smc-on-non-secure-software) - - -1. Introduction ----------------- -This document describes the design of the Interrupt management framework in ARM -Trusted Firmware. This section briefly describes the requirements from this -framework. It also briefly explains some concepts and assumptions. They will -help in understanding the implementation of the framework explained in -subsequent sections. - -This framework is responsible for managing interrupts routed to EL3. It also -allows EL3 software to configure the interrupt routing behavior. Its main -objective is to implement the following two requirements. - -1. It should be possible to route interrupts meant to be handled by secure - software (Secure interrupts) to EL3, when execution is in non-secure state - (normal world). The framework should then take care of handing control of - the interrupt to either software in EL3 or Secure-EL1 depending upon the - software configuration and the GIC implementation. This requirement ensures - that secure interrupts are under the control of the secure software with - respect to their delivery and handling without the possibility of - intervention from non-secure software. - -2. It should be possible to route interrupts meant to be handled by - non-secure software (Non-secure interrupts) to the last executed exception - level in the normal world when the execution is in secure world at - exception levels lower than EL3. This could be done with or without the - knowledge of software executing in Secure-EL1/Secure-EL0. The choice of - approach should be governed by the secure software. This requirement - ensures that non-secure software is able to execute in tandem with the - secure software without overriding it. - -### 1.1 Concepts - -#### 1.1.1 Interrupt types -The framework categorises an interrupt to be one of the following depending upon -the exception level(s) it is handled in. - -1. Secure EL1 interrupt. This type of interrupt can be routed to EL3 or - Secure-EL1 depending upon the security state of the current execution - context. It is always handled in Secure-EL1. - -2. Non-secure interrupt. This type of interrupt can be routed to EL3, - Secure-EL1, Non-secure EL1 or EL2 depending upon the security state of the - current execution context. It is always handled in either Non-secure EL1 - or EL2. - -3. EL3 interrupt. This type of interrupt can be routed to EL3 or Secure-EL1 - depending upon the security state of the current execution context. It is - always handled in EL3. - -The following constants define the various interrupt types in the framework -implementation. - - #define INTR_TYPE_S_EL1 0 - #define INTR_TYPE_EL3 1 - #define INTR_TYPE_NS 2 - - -#### 1.1.2 Routing model -A type of interrupt can be either generated as an FIQ or an IRQ. The target -exception level of an interrupt type is configured through the FIQ and IRQ bits -in the Secure Configuration Register at EL3 (`SCR_EL3.FIQ` and `SCR_EL3.IRQ` -bits). When `SCR_EL3.FIQ`=1, FIQs are routed to EL3. Otherwise they are routed -to the First Exception Level (FEL) capable of handling interrupts. When -`SCR_EL3.IRQ`=1, IRQs are routed to EL3. Otherwise they are routed to the -FEL. This register is configured independently by EL3 software for each security -state prior to entry into a lower exception level in that security state. - -A routing model for a type of interrupt (generated as FIQ or IRQ) is defined as -its target exception level for each security state. It is represented by a -single bit for each security state. A value of `0` means that the interrupt -should be routed to the FEL. A value of `1` means that the interrupt should be -routed to EL3. A routing model is applicable only when execution is not in EL3. - -The default routing model for an interrupt type is to route it to the FEL in -either security state. - - -#### 1.1.3 Valid routing models -The framework considers certain routing models for each type of interrupt to be -incorrect as they conflict with the requirements mentioned in Section 1. The -following sub-sections describe all the possible routing models and specify -which ones are valid or invalid. EL3 interrupts are currently supported only -for GIC version 3.0 (ARM GICv3) and only the Secure-EL1 and Non-secure interrupt -types are supported for GIC version 2.0 (ARM GICv2) (See 1.2). The terminology -used in the following sub-sections is explained below. - -1. __CSS__. Current Security State. `0` when secure and `1` when non-secure - -2. __TEL3__. Target Exception Level 3. `0` when targeted to the FEL. `1` when - targeted to EL3. - - -##### 1.1.3.1 Secure-EL1 interrupts - -1. __CSS=0, TEL3=0__. Interrupt is routed to the FEL when execution is in - secure state. This is a valid routing model as secure software is in - control of handling secure interrupts. - -2. __CSS=0, TEL3=1__. Interrupt is routed to EL3 when execution is in secure - state. This is a valid routing model as secure software in EL3 can - handover the interrupt to Secure-EL1 for handling. - -3. __CSS=1, TEL3=0__. Interrupt is routed to the FEL when execution is in - non-secure state. This is an invalid routing model as a secure interrupt - is not visible to the secure software which violates the motivation behind - the ARM Security Extensions. - -4. __CSS=1, TEL3=1__. Interrupt is routed to EL3 when execution is in - non-secure state. This is a valid routing model as secure software in EL3 - can handover the interrupt to Secure-EL1 for handling. - - -##### 1.1.3.2 Non-secure interrupts - -1. __CSS=0, TEL3=0__. Interrupt is routed to the FEL when execution is in - secure state. This allows the secure software to trap non-secure - interrupts, perform its book-keeping and hand the interrupt to the - non-secure software through EL3. This is a valid routing model as secure - software is in control of how its execution is preempted by non-secure - interrupts. - -2. __CSS=0, TEL3=1__. Interrupt is routed to EL3 when execution is in secure - state. This is a valid routing model as secure software in EL3 can save - the state of software in Secure-EL1/Secure-EL0 before handing the - interrupt to non-secure software. This model requires additional - coordination between Secure-EL1 and EL3 software to ensure that the - former's state is correctly saved by the latter. - -3. __CSS=1, TEL3=0__. Interrupt is routed to FEL when execution is in - non-secure state. This is an valid routing model as a non-secure interrupt - is handled by non-secure software. - -4. __CSS=1, TEL3=1__. Interrupt is routed to EL3 when execution is in - non-secure state. This is an invalid routing model as there is no valid - reason to route the interrupt to EL3 software and then hand it back to - non-secure software for handling. - - -##### 1.1.3.3 EL3 interrupts - -1. __CSS=0, TEL3=0__. Interrupt is routed to the FEL when execution is in - Secure-EL1/Secure-EL0. This is a valid routing model as secure software - in Secure-EL1/Secure-EL0 is in control of how its execution is preempted - by EL3 interrupt and can handover the interrupt to EL3 for handling. - -2. __CSS=0, TEL3=1__. Interrupt is routed to EL3 when execution is in - Secure-EL1/Secure-EL0. This is a valid routing model as secure software - in EL3 can handle the interrupt. - -3. __CSS=1, TEL3=0__. Interrupt is routed to the FEL when execution is in - non-secure state. This is an invalid routing model as a secure interrupt - is not visible to the secure software which violates the motivation behind - the ARM Security Extensions. - -4. __CSS=1, TEL3=1__. Interrupt is routed to EL3 when execution is in - non-secure state. This is a valid routing model as secure software in EL3 - can handle the interrupt. - - -#### 1.1.4 Mapping of interrupt type to signal -The framework is meant to work with any interrupt controller implemented by a -platform. A interrupt controller could generate a type of interrupt as either an -FIQ or IRQ signal to the CPU depending upon the current security state. The -mapping between the type and signal is known only to the platform. The framework -uses this information to determine whether the IRQ or the FIQ bit should be -programmed in `SCR_EL3` while applying the routing model for a type of -interrupt. The platform provides this information through the -`plat_interrupt_type_to_line()` API (described in the [Porting -Guide]). For example, on the FVP port when the platform uses an ARM GICv2 -interrupt controller, Secure-EL1 interrupts are signaled through the FIQ signal -while Non-secure interrupts are signaled through the IRQ signal. This applies -when execution is in either security state. - - -##### 1.1.4.1 Effect of mapping of several interrupt types to one signal -It should be noted that if more than one interrupt type maps to a single -interrupt signal, and if any one of the interrupt type sets __TEL3=1__ for a -particular security state, then interrupt signal will be routed to EL3 when in -that security state. This means that all the other interrupt types using the -same interrupt signal will be forced to the same routing model. This should be -borne in mind when choosing the routing model for an interrupt type. - -For example, in ARM GICv3, when the execution context is Secure-EL1/ -Secure-EL0, both the EL3 and the non secure interrupt types map to the FIQ -signal. So if either one of the interrupt type sets the routing model so -that __TEL3=1__ when __CSS=0__, the FIQ bit in `SCR_EL3` will be programmed to -route the FIQ signal to EL3 when executing in Secure-EL1/Secure-EL0, thereby -effectively routing the other interrupt type also to EL3. - - -### 1.2 Assumptions in Interrupt Management Framework -The framework makes the following assumptions to simplify its implementation. - -1. Although the framework has support for 2 types of secure interrupts (EL3 - and Secure-EL1 interrupt), only interrupt controller architectures - like ARM GICv3 has architectural support for EL3 interrupts in the form of - Group 0 interrupts. In ARM GICv2, all secure interrupts are assumed to be - handled in Secure-EL1. They can be delivered to Secure-EL1 via EL3 but they - cannot be handled in EL3. - -2. Interrupt exceptions (`PSTATE.I` and `F` bits) are masked during execution - in EL3. - - -2. Interrupt management ------------------------ -The following sections describe how interrupts are managed by the interrupt -handling framework. This entails: - -1. Providing an interface to allow registration of a handler and specification - of the routing model for a type of interrupt. - -2. Implementing support to hand control of an interrupt type to its registered - handler when the interrupt is generated. - -Both aspects of interrupt management involve various components in the secure -software stack spanning from EL3 to Secure-EL1. These components are described -in the section 2.1. The framework stores information associated with each type -of interrupt in the following data structure. - -``` -typedef struct intr_type_desc { - interrupt_type_handler_t handler; - uint32_t flags; - uint32_t scr_el3[2]; -} intr_type_desc_t; -``` - -The `flags` field stores the routing model for the interrupt type in -bits[1:0]. Bit[0] stores the routing model when execution is in the secure -state. Bit[1] stores the routing model when execution is in the non-secure -state. As mentioned in Section 1.2.2, a value of `0` implies that the interrupt -should be targeted to the FEL. A value of `1` implies that it should be targeted -to EL3. The remaining bits are reserved and SBZ. The helper macro -`set_interrupt_rm_flag()` should be used to set the bits in the `flags` -parameter. - -The `scr_el3[2]` field also stores the routing model but as a mapping of the -model in the `flags` field to the corresponding bit in the `SCR_EL3` for each -security state. - -The framework also depends upon the platform port to configure the interrupt -controller to distinguish between secure and non-secure interrupts. The platform -is expected to be aware of the secure devices present in the system and their -associated interrupt numbers. It should configure the interrupt controller to -enable the secure interrupts, ensure that their priority is always higher than -the non-secure interrupts and target them to the primary CPU. It should also -export the interface described in the [Porting Guide] to enable -handling of interrupts. - -In the remainder of this document, for the sake of simplicity a ARM GICv2 system -is considered and it is assumed that the FIQ signal is used to generate Secure-EL1 -interrupts and the IRQ signal is used to generate non-secure interrupts in either -security state. EL3 interrupts are not considered. - - -### 2.1 Software components -Roles and responsibilities for interrupt management are sub-divided between the -following components of software running in EL3 and Secure-EL1. Each component is -briefly described below. - -1. EL3 Runtime Firmware. This component is common to all ports of the ARM - Trusted Firmware. - -2. Secure Payload Dispatcher (SPD) service. This service interfaces with the - Secure Payload (SP) software which runs in Secure-EL1/Secure-EL0 and is - responsible for switching execution between secure and non-secure states. - A switch is triggered by a Secure Monitor Call and it uses the APIs - exported by the Context management library to implement this functionality. - Switching execution between the two security states is a requirement for - interrupt management as well. This results in a significant dependency on - the SPD service. ARM Trusted firmware implements an example Test Secure - Payload Dispatcher (TSPD) service. - - An SPD service plugs into the EL3 runtime firmware and could be common to - some ports of the ARM Trusted Firmware. - -3. Secure Payload (SP). On a production system, the Secure Payload corresponds - to a Secure OS which runs in Secure-EL1/Secure-EL0. It interfaces with the - SPD service to manage communication with non-secure software. ARM Trusted - Firmware implements an example secure payload called Test Secure Payload - (TSP) which runs only in Secure-EL1. - - A Secure payload implementation could be common to some ports of the ARM - Trusted Firmware just like the SPD service. - - -### 2.2 Interrupt registration -This section describes in detail the role of each software component (see 2.1) -during the registration of a handler for an interrupt type. - - -#### 2.2.1 EL3 runtime firmware -This component declares the following prototype for a handler of an interrupt type. - - typedef uint64_t (*interrupt_type_handler_t)(uint32_t id, - uint32_t flags, - void *handle, - void *cookie); - -The `id` is parameter is reserved and could be used in the future for passing -the interrupt id of the highest pending interrupt only if there is a foolproof -way of determining the id. Currently it contains `INTR_ID_UNAVAILABLE`. - -The `flags` parameter contains miscellaneous information as follows. - -1. Security state, bit[0]. This bit indicates the security state of the lower - exception level when the interrupt was generated. A value of `1` means - that it was in the non-secure state. A value of `0` indicates that it was - in the secure state. This bit can be used by the handler to ensure that - interrupt was generated and routed as per the routing model specified - during registration. - -2. Reserved, bits[31:1]. The remaining bits are reserved for future use. - -The `handle` parameter points to the `cpu_context` structure of the current CPU -for the security state specified in the `flags` parameter. - -Once the handler routine completes, execution will return to either the secure -or non-secure state. The handler routine must return a pointer to -`cpu_context` structure of the current CPU for the target security state. On -AArch64, this return value is currently ignored by the caller as the -appropriate `cpu_context` to be used is expected to be set by the handler -via the context management library APIs. -A portable interrupt handler implementation must set the target context both in -the structure pointed to by the returned pointer and via the context management -library APIs. The handler should treat all error conditions as critical errors -and take appropriate action within its implementation e.g. use assertion -failures. - -The runtime firmware provides the following API for registering a handler for a -particular type of interrupt. A Secure Payload Dispatcher service should use -this API to register a handler for Secure-EL1 and optionally for non-secure -interrupts. This API also requires the caller to specify the routing model for -the type of interrupt. - - int32_t register_interrupt_type_handler(uint32_t type, - interrupt_type_handler handler, - uint64_t flags); - - -The `type` parameter can be one of the three interrupt types listed above i.e. -`INTR_TYPE_S_EL1`, `INTR_TYPE_NS` & `INTR_TYPE_EL3`. The `flags` parameter -is as described in Section 2. - -The function will return `0` upon a successful registration. It will return -`-EALREADY` in case a handler for the interrupt type has already been -registered. If the `type` is unrecognised or the `flags` or the `handler` are -invalid it will return `-EINVAL`. - -Interrupt routing is governed by the configuration of the `SCR_EL3.FIQ/IRQ` bits -prior to entry into a lower exception level in either security state. The -context management library maintains a copy of the `SCR_EL3` system register for -each security state in the `cpu_context` structure of each CPU. It exports the -following APIs to let EL3 Runtime Firmware program and retrieve the routing -model for each security state for the current CPU. The value of `SCR_EL3` stored -in the `cpu_context` is used by the `el3_exit()` function to program the -`SCR_EL3` register prior to returning from the EL3 exception level. - - uint32_t cm_get_scr_el3(uint32_t security_state); - void cm_write_scr_el3_bit(uint32_t security_state, - uint32_t bit_pos, - uint32_t value); - -`cm_get_scr_el3()` returns the value of the `SCR_EL3` register for the specified -security state of the current CPU. `cm_write_scr_el3()` writes a `0` or `1` to -the bit specified by `bit_pos`. `register_interrupt_type_handler()` invokes -`set_routing_model()` API which programs the `SCR_EL3` according to the routing -model using the `cm_get_scr_el3()` and `cm_write_scr_el3_bit()` APIs. - -It is worth noting that in the current implementation of the framework, the EL3 -runtime firmware is responsible for programming the routing model. The SPD is -responsible for ensuring that the routing model has been adhered to upon -receiving an interrupt. - - -#### 2.2.2 Secure payload dispatcher -A SPD service is responsible for determining and maintaining the interrupt -routing model supported by itself and the Secure Payload. It is also responsible -for ferrying interrupts between secure and non-secure software depending upon -the routing model. It could determine the routing model at build time or at -runtime. It must use this information to register a handler for each interrupt -type using the `register_interrupt_type_handler()` API in EL3 runtime firmware. - -If the routing model is not known to the SPD service at build time, then it must -be provided by the SP as the result of its initialisation. The SPD should -program the routing model only after SP initialisation has completed e.g. in the -SPD initialisation function pointed to by the `bl32_init` variable. - -The SPD should determine the mechanism to pass control to the Secure Payload -after receiving an interrupt from the EL3 runtime firmware. This information -could either be provided to the SPD service at build time or by the SP at -runtime. - - -#### 2.2.2.1 Test secure payload dispatcher behavior -The TSPD only handles Secure-EL1 interrupts and is provided with the following -routing model at build time. - -* Secure-EL1 interrupts are routed to EL3 when execution is in non-secure - state and are routed to the FEL when execution is in the secure state - i.e __CSS=0, TEL3=0__ & __CSS=1, TEL3=1__ for Secure-EL1 interrupts - -* When the build flag `TSP_NS_INTR_ASYNC_PREEMPT` is zero, the default routing - model is used for non-secure interrupts. They are routed to the FEL in - either security state i.e __CSS=0, TEL3=0__ & __CSS=1, TEL3=0__ for - Non-secure interrupts. - -* When the build flag `TSP_NS_INTR_ASYNC_PREEMPT` is defined to 1, then the - non secure interrupts are routed to EL3 when execution is in secure state - i.e __CSS=0, TEL3=1__ for non-secure interrupts. This effectively preempts - Secure-EL1. The default routing model is used for non secure interrupts in - non-secure state. i.e __CSS=1, TEL3=0__. - -It performs the following actions in the `tspd_init()` function to fulfill the -requirements mentioned earlier. - -1. It passes control to the Test Secure Payload to perform its - initialisation. The TSP provides the address of the vector table - `tsp_vectors` in the SP which also includes the handler for Secure-EL1 - interrupts in the `sel1_intr_entry` field. The TSPD passes control to the TSP at - this address when it receives a Secure-EL1 interrupt. - - The handover agreement between the TSP and the TSPD requires that the TSPD - masks all interrupts (`PSTATE.DAIF` bits) when it calls - `tsp_sel1_intr_entry()`. The TSP has to preserve the callee saved general - purpose, SP_EL1/Secure-EL0, LR, VFP and system registers. It can use - `x0-x18` to enable its C runtime. - -2. The TSPD implements a handler function for Secure-EL1 interrupts. This - function is registered with the EL3 runtime firmware using the - `register_interrupt_type_handler()` API as follows - - /* Forward declaration */ - interrupt_type_handler tspd_secure_el1_interrupt_handler; - int32_t rc, flags = 0; - set_interrupt_rm_flag(flags, NON_SECURE); - rc = register_interrupt_type_handler(INTR_TYPE_S_EL1, - tspd_secure_el1_interrupt_handler, - flags); - if (rc) - panic(); - -3. When the build flag `TSP_NS_INTR_ASYNC_PREEMPT` is defined to 1, the TSPD - implements a handler function for non-secure interrupts. This function is - registered with the EL3 runtime firmware using the - `register_interrupt_type_handler()` API as follows - - /* Forward declaration */ - interrupt_type_handler tspd_ns_interrupt_handler; - int32_t rc, flags = 0; - set_interrupt_rm_flag(flags, SECURE); - rc = register_interrupt_type_handler(INTR_TYPE_NS, - tspd_ns_interrupt_handler, - flags); - if (rc) - panic(); - - -#### 2.2.3 Secure payload -A Secure Payload must implement an interrupt handling framework at Secure-EL1 -(Secure-EL1 IHF) to support its chosen interrupt routing model. Secure payload -execution will alternate between the below cases. - -1. In the code where IRQ, FIQ or both interrupts are enabled, if an interrupt - type is targeted to the FEL, then it will be routed to the Secure-EL1 - exception vector table. This is defined as the __asynchronous mode__ of - handling interrupts. This mode applies to both Secure-EL1 and non-secure - interrupts. - -2. In the code where both interrupts are disabled, if an interrupt type is - targeted to the FEL, then execution will eventually migrate to the - non-secure state. Any non-secure interrupts will be handled as described - in the routing model where __CSS=1 and TEL3=0__. Secure-EL1 interrupts - will be routed to EL3 (as per the routing model where __CSS=1 and - TEL3=1__) where the SPD service will hand them to the SP. This is defined - as the __synchronous mode__ of handling interrupts. - -The interrupt handling framework implemented by the SP should support one or -both these interrupt handling models depending upon the chosen routing model. - -The following list briefly describes how the choice of a valid routing model -(See 1.2.3) effects the implementation of the Secure-EL1 IHF. If the choice of -the interrupt routing model is not known to the SPD service at compile time, -then the SP should pass this information to the SPD service at runtime during -its initialisation phase. - -As mentioned earlier, a ARM GICv2 system is considered and it is assumed that -the FIQ signal is used to generate Secure-EL1 interrupts and the IRQ signal -is used to generate non-secure interrupts in either security state. - - -##### 2.2.3.1 Secure payload IHF design w.r.t secure-EL1 interrupts -1. __CSS=0, TEL3=0__. If `PSTATE.F=0`, Secure-EL1 interrupts will be - triggered at one of the Secure-EL1 FIQ exception vectors. The Secure-EL1 - IHF should implement support for handling FIQ interrupts asynchronously. - - If `PSTATE.F=1` then Secure-EL1 interrupts will be handled as per the - synchronous interrupt handling model. The SP could implement this scenario - by exporting a separate entrypoint for Secure-EL1 interrupts to the SPD - service during the registration phase. The SPD service would also need to - know the state of the system, general purpose and the `PSTATE` registers - in which it should arrange to return execution to the SP. The SP should - provide this information in an implementation defined way during the - registration phase if it is not known to the SPD service at build time. - -2. __CSS=1, TEL3=1__. Interrupts are routed to EL3 when execution is in - non-secure state. They should be handled through the synchronous interrupt - handling model as described in 1. above. - -3. __CSS=0, TEL3=1__. Secure-EL1 interrupts are routed to EL3 when execution - is in secure state. They will not be visible to the SP. The `PSTATE.F` bit - in Secure-EL1/Secure-EL0 will not mask FIQs. The EL3 runtime firmware will - call the handler registered by the SPD service for Secure-EL1 interrupts. - Secure-EL1 IHF should then handle all Secure-EL1 interrupt through the - synchronous interrupt handling model described in 1. above. - - -##### 2.2.3.2 Secure payload IHF design w.r.t non-secure interrupts -1. __CSS=0, TEL3=0__. If `PSTATE.I=0`, non-secure interrupts will be - triggered at one of the Secure-EL1 IRQ exception vectors . The Secure-EL1 - IHF should co-ordinate with the SPD service to transfer execution to the - non-secure state where the interrupt should be handled e.g the SP could - allocate a function identifier to issue a SMC64 or SMC32 to the SPD - service which indicates that the SP execution has been preempted by a - non-secure interrupt. If this function identifier is not known to the SPD - service at compile time then the SP could provide it during the - registration phase. - - If `PSTATE.I=1` then the non-secure interrupt will pend until execution - resumes in the non-secure state. - -2. __CSS=0, TEL3=1__. Non-secure interrupts are routed to EL3. They will not - be visible to the SP. The `PSTATE.I` bit in Secure-EL1/Secure-EL0 will - have not effect. The SPD service should register a non-secure interrupt - handler which should save the SP state correctly and resume execution in - the non-secure state where the interrupt will be handled. The Secure-EL1 - IHF does not need to take any action. - -3. __CSS=1, TEL3=0__. Non-secure interrupts are handled in the FEL in - non-secure state (EL1/EL2) and are not visible to the SP. This routing - model does not affect the SP behavior. - -A Secure Payload must also ensure that all Secure-EL1 interrupts are correctly -configured at the interrupt controller by the platform port of the EL3 runtime -firmware. It should configure any additional Secure-EL1 interrupts which the EL3 -runtime firmware is not aware of through its platform port. - - -#### 2.2.3.3 Test secure payload behavior -The routing model for Secure-EL1 and non-secure interrupts chosen by the TSP is -described in Section 2.2.2. It is known to the TSPD service at build time. - -The TSP implements an entrypoint (`tsp_sel1_intr_entry()`) for handling Secure-EL1 -interrupts taken in non-secure state and routed through the TSPD service -(synchronous handling model). It passes the reference to this entrypoint via -`tsp_vectors` to the TSPD service. - -The TSP also replaces the default exception vector table referenced through the -`early_exceptions` variable, with a vector table capable of handling FIQ and IRQ -exceptions taken at the same (Secure-EL1) exception level. This table is -referenced through the `tsp_exceptions` variable and programmed into the -VBAR_EL1. It caters for the asynchronous handling model. - -The TSP also programs the Secure Physical Timer in the ARM Generic Timer block -to raise a periodic interrupt (every half a second) for the purpose of testing -interrupt management across all the software components listed in 2.1 - - -### 2.3 Interrupt handling -This section describes in detail the role of each software component (see -Section 2.1) in handling an interrupt of a particular type. - - -#### 2.3.1 EL3 runtime firmware -The EL3 runtime firmware populates the IRQ and FIQ exception vectors referenced -by the `runtime_exceptions` variable as follows. - -1. IRQ and FIQ exceptions taken from the current exception level with - `SP_EL0` or `SP_EL3` are reported as irrecoverable error conditions. As - mentioned earlier, EL3 runtime firmware always executes with the - `PSTATE.I` and `PSTATE.F` bits set. - -2. The following text describes how the IRQ and FIQ exceptions taken from a - lower exception level using AArch64 or AArch32 are handled. - -When an interrupt is generated, the vector for each interrupt type is -responsible for: - -1. Saving the entire general purpose register context (x0-x30) immediately - upon exception entry. The registers are saved in the per-cpu `cpu_context` - data structure referenced by the `SP_EL3`register. - -2. Saving the `ELR_EL3`, `SP_EL0` and `SPSR_EL3` system registers in the - per-cpu `cpu_context` data structure referenced by the `SP_EL3` register. - -3. Switching to the C runtime stack by restoring the `CTX_RUNTIME_SP` value - from the per-cpu `cpu_context` data structure in `SP_EL0` and - executing the `msr spsel, #0` instruction. - -4. Determining the type of interrupt. Secure-EL1 interrupts will be signaled - at the FIQ vector. Non-secure interrupts will be signaled at the IRQ - vector. The platform should implement the following API to determine the - type of the pending interrupt. - - uint32_t plat_ic_get_interrupt_type(void); - - It should return either `INTR_TYPE_S_EL1` or `INTR_TYPE_NS`. - -5. Determining the handler for the type of interrupt that has been generated. - The following API has been added for this purpose. - - interrupt_type_handler get_interrupt_type_handler(uint32_t interrupt_type); - - It returns the reference to the registered handler for this interrupt - type. The `handler` is retrieved from the `intr_type_desc_t` structure as - described in Section 2. `NULL` is returned if no handler has been - registered for this type of interrupt. This scenario is reported as an - irrecoverable error condition. - -6. Calling the registered handler function for the interrupt type generated. - The `id` parameter is set to `INTR_ID_UNAVAILABLE` currently. The id along - with the current security state and a reference to the `cpu_context_t` - structure for the current security state are passed to the handler function - as its arguments. - - The handler function returns a reference to the per-cpu `cpu_context_t` - structure for the target security state. - -7. Calling `el3_exit()` to return from EL3 into a lower exception level in - the security state determined by the handler routine. The `el3_exit()` - function is responsible for restoring the register context from the - `cpu_context_t` data structure for the target security state. - - -#### 2.3.2 Secure payload dispatcher - -##### 2.3.2.1 Interrupt entry -The SPD service begins handling an interrupt when the EL3 runtime firmware calls -the handler function for that type of interrupt. The SPD service is responsible -for the following: - -1. Validating the interrupt. This involves ensuring that the interrupt was - generating according to the interrupt routing model specified by the SPD - service during registration. It should use the security state of the - exception level (passed in the `flags` parameter of the handler) where - the interrupt was taken from to determine this. If the interrupt is not - recognised then the handler should treat it as an irrecoverable error - condition. - - A SPD service can register a handler for Secure-EL1 and/or Non-secure - interrupts. A non-secure interrupt should never be routed to EL3 from - from non-secure state. Also if a routing model is chosen where Secure-EL1 - interrupts are routed to S-EL1 when execution is in Secure state, then a - S-EL1 interrupt should never be routed to EL3 from secure state. The handler - could use the security state flag to check this. - -2. Determining whether a context switch is required. This depends upon the - routing model and interrupt type. For non secure and S-EL1 interrupt, - if the security state of the execution context where the interrupt was - generated is not the same as the security state required for handling - the interrupt, a context switch is required. The following 2 cases - require a context switch from secure to non-secure or vice-versa: - - 1. A Secure-EL1 interrupt taken from the non-secure state should be - routed to the Secure Payload. - - 2. A non-secure interrupt taken from the secure state should be routed - to the last known non-secure exception level. - - The SPD service must save the system register context of the current - security state. It must then restore the system register context of the - target security state. It should use the `cm_set_next_eret_context()` API - to ensure that the next `cpu_context` to be restored is of the target - security state. - - If the target state is secure then execution should be handed to the SP as - per the synchronous interrupt handling model it implements. A Secure-EL1 - interrupt can be routed to EL3 while execution is in the SP. This implies - that SP execution can be preempted while handling an interrupt by a - another higher priority Secure-EL1 interrupt or a EL3 interrupt. The SPD - service should be able to handle this preemption or manage secure interrupt - priorities before handing control to the SP. - -3. Setting the return value of the handler to the per-cpu `cpu_context` if - the interrupt has been successfully validated and ready to be handled at a - lower exception level. - -The routing model allows non-secure interrupts to interrupt Secure-EL1 when in -secure state if it has been configured to do so. The SPD service and the SP -should implement a mechanism for routing these interrupts to the last known -exception level in the non-secure state. The former should save the SP context, -restore the non-secure context and arrange for entry into the non-secure state -so that the interrupt can be handled. - - -##### 2.3.2.2 Interrupt exit -When the Secure Payload has finished handling a Secure-EL1 interrupt, it could -return control back to the SPD service through a SMC32 or SMC64. The SPD service -should handle this secure monitor call so that execution resumes in the -exception level and the security state from where the Secure-EL1 interrupt was -originally taken. - - -##### 2.3.2.3 Test secure payload dispatcher Secure-EL1 interrupt handling -The example TSPD service registers a handler for Secure-EL1 interrupts taken -from the non-secure state. During execution in S-EL1, the TSPD expects that the -Secure-EL1 interrupts are handled in S-EL1 by TSP. Its handler -`tspd_secure_el1_interrupt_handler()` expects only to be invoked for Secure-EL1 -originating from the non-secure state. It takes the following actions upon being -invoked. - -1. It uses the security state provided in the `flags` parameter to ensure - that the secure interrupt originated from the non-secure state. It asserts - if this is not the case. - -2. It saves the system register context for the non-secure state by calling - `cm_el1_sysregs_context_save(NON_SECURE);`. - -3. It sets the `ELR_EL3` system register to `tsp_sel1_intr_entry` and sets the - `SPSR_EL3.DAIF` bits in the secure CPU context. It sets `x0` to - `TSP_HANDLE_SEL1_INTR_AND_RETURN`. If the TSP was preempted earlier by a non - secure interrupt during `yielding` SMC processing, save the registers that - will be trashed, which is the `ELR_EL3` and `SPSR_EL3`, in order to be able - to re-enter TSP for Secure-EL1 interrupt processing. It does not need to - save any other secure context since the TSP is expected to preserve it - (see Section 2.2.2.1). - -4. It restores the system register context for the secure state by calling - `cm_el1_sysregs_context_restore(SECURE);`. - -5. It ensures that the secure CPU context is used to program the next - exception return from EL3 by calling `cm_set_next_eret_context(SECURE);`. - -6. It returns the per-cpu `cpu_context` to indicate that the interrupt can - now be handled by the SP. `x1` is written with the value of `elr_el3` - register for the non-secure state. This information is used by the SP for - debugging purposes. - -The figure below describes how the interrupt handling is implemented by the TSPD -when a Secure-EL1 interrupt is generated when execution is in the non-secure -state. - - - -The TSP issues an SMC with `TSP_HANDLED_S_EL1_INTR` as the function identifier to -signal completion of interrupt handling. - -The TSPD service takes the following actions in `tspd_smc_handler()` function -upon receiving an SMC with `TSP_HANDLED_S_EL1_INTR` as the function identifier: - -1. It ensures that the call originated from the secure state otherwise - execution returns to the non-secure state with `SMC_UNK` in `x0`. - -2. It restores the saved `ELR_EL3` and `SPSR_EL3` system registers back to - the secure CPU context (see step 3 above) in case the TSP had been preempted - by a non secure interrupt earlier. - -3. It restores the system register context for the non-secure state by - calling `cm_el1_sysregs_context_restore(NON_SECURE)`. - -4. It ensures that the non-secure CPU context is used to program the next - exception return from EL3 by calling `cm_set_next_eret_context(NON_SECURE)`. - -5. `tspd_smc_handler()` returns a reference to the non-secure `cpu_context` - as the return value. - - -##### 2.3.2.4 Test secure payload dispatcher non-secure interrupt handling -The TSP in Secure-EL1 can be preempted by a non-secure interrupt during -`yielding` SMC processing or by a higher priority EL3 interrupt during -Secure-EL1 interrupt processing. Currently only non-secure interrupts can -cause preemption of TSP since there are no EL3 interrupts in the -system. - -It should be noted that while TSP is preempted, the TSPD only allows entry into -the TSP either for Secure-EL1 interrupt handling or for resuming the preempted -`yielding` SMC in response to the `TSP_FID_RESUME` SMC from the normal world. -(See Section 3). - -The non-secure interrupt triggered in Secure-EL1 during `yielding` SMC processing -can be routed to either EL3 or Secure-EL1 and is controlled by build option -`TSP_NS_INTR_ASYNC_PREEMPT` (see Section 2.2.2.1). If the build option is set, -the TSPD will set the routing model for the non-secure interrupt to be routed to -EL3 from secure state i.e. __TEL3=1, CSS=0__ and registers -`tspd_ns_interrupt_handler()` as the non-secure interrupt handler. The -`tspd_ns_interrupt_handler()` on being invoked ensures that the interrupt -originated from the secure state and disables routing of non-secure interrupts -from secure state to EL3. This is to prevent further preemption (by a non-secure -interrupt) when TSP is reentered for handling Secure-EL1 interrupts that -triggered while execution was in the normal world. The -`tspd_ns_interrupt_handler()` then invokes `tspd_handle_sp_preemption()` for -further handling. - -If the `TSP_NS_INTR_ASYNC_PREEMPT` build option is zero (default), the default -routing model for non-secure interrupt in secure state is in effect -i.e. __TEL3=0, CSS=0__. During `yielding` SMC processing, the IRQ -exceptions are unmasked i.e. `PSTATE.I=0`, and a non-secure interrupt will -trigger at Secure-EL1 IRQ exception vector. The TSP saves the general purpose -register context and issues an SMC with `TSP_PREEMPTED` as the function -identifier to signal preemption of TSP. The TSPD SMC handler, -`tspd_smc_handler()`, ensures that the SMC call originated from the -secure state otherwise execution returns to the non-secure state with -`SMC_UNK` in `x0`. It then invokes `tspd_handle_sp_preemption()` for -further handling. - -The `tspd_handle_sp_preemption()` takes the following actions upon being -invoked: - -1. It saves the system register context for the secure state by calling - `cm_el1_sysregs_context_save(SECURE)`. - -2. It restores the system register context for the non-secure state by - calling `cm_el1_sysregs_context_restore(NON_SECURE)`. - -3. It ensures that the non-secure CPU context is used to program the next - exception return from EL3 by calling `cm_set_next_eret_context(NON_SECURE)`. - -4. `SMC_PREEMPTED` is set in x0 and return to non secure state after - restoring non secure context. - -The Normal World is expected to resume the TSP after the `yielding` SMC preemption -by issuing an SMC with `TSP_FID_RESUME` as the function identifier (see section 3). -The TSPD service takes the following actions in `tspd_smc_handler()` function -upon receiving this SMC: - -1. It ensures that the call originated from the non secure state. An - assertion is raised otherwise. - -2. Checks whether the TSP needs a resume i.e check if it was preempted. It - then saves the system register context for the non-secure state by calling - `cm_el1_sysregs_context_save(NON_SECURE)`. - -3. Restores the secure context by calling - `cm_el1_sysregs_context_restore(SECURE)` - -4. It ensures that the secure CPU context is used to program the next - exception return from EL3 by calling `cm_set_next_eret_context(SECURE)`. - -5. `tspd_smc_handler()` returns a reference to the secure `cpu_context` as the - return value. - -The figure below describes how the TSP/TSPD handle a non-secure interrupt when -it is generated during execution in the TSP with `PSTATE.I` = 0 when the -`TSP_NS_INTR_ASYNC_PREEMPT` build flag is 0. - - - - -#### 2.3.3 Secure payload -The SP should implement one or both of the synchronous and asynchronous -interrupt handling models depending upon the interrupt routing model it has -chosen (as described in 2.2.3). - -In the synchronous model, it should begin handling a Secure-EL1 interrupt after -receiving control from the SPD service at an entrypoint agreed upon during build -time or during the registration phase. Before handling the interrupt, the SP -should save any Secure-EL1 system register context which is needed for resuming -normal execution in the SP later e.g. `SPSR_EL1, `ELR_EL1`. After handling the -interrupt, the SP could return control back to the exception level and security -state where the interrupt was originally taken from. The SP should use an SMC32 -or SMC64 to ask the SPD service to do this. - -In the asynchronous model, the Secure Payload is responsible for handling -non-secure and Secure-EL1 interrupts at the IRQ and FIQ vectors in its exception -vector table when `PSTATE.I` and `PSTATE.F` bits are 0. As described earlier, -when a non-secure interrupt is generated, the SP should coordinate with the SPD -service to pass control back to the non-secure state in the last known exception -level. This will allow the non-secure interrupt to be handled in the non-secure -state. - - -##### 2.3.3.1 Test secure payload behavior -The TSPD hands control of a Secure-EL1 interrupt to the TSP at the -`tsp_sel1_intr_entry()`. The TSP handles the interrupt while ensuring that the -handover agreement described in Section 2.2.2.1 is maintained. It updates some -statistics by calling `tsp_update_sync_sel1_intr_stats()`. It then calls -`tsp_common_int_handler()` which. - -1. Checks whether the interrupt is the secure physical timer interrupt. It - uses the platform API `plat_ic_get_pending_interrupt_id()` to get the - interrupt number. If it is not the secure physical timer interrupt, then - that means that a higher priority interrupt has preempted it. Invoke - `tsp_handle_preemption()` to handover control back to EL3 by issuing - an SMC with `TSP_PREEMPTED` as the function identifier. - -2. Handles the secure timer interrupt interrupt by acknowledging it using the - `plat_ic_acknowledge_interrupt()` platform API, calling - `tsp_generic_timer_handler()` to reprogram the secure physical generic - timer and calling the `plat_ic_end_of_interrupt()` platform API to signal - end of interrupt processing. - -The TSP passes control back to the TSPD by issuing an SMC64 with -`TSP_HANDLED_S_EL1_INTR` as the function identifier. - -The TSP handles interrupts under the asynchronous model as follows. - -1. Secure-EL1 interrupts are handled by calling the `tsp_common_int_handler()` - function. The function has been described above. - -2. Non-secure interrupts are handled by by calling the `tsp_common_int_handler()` - function which ends up invoking `tsp_handle_preemption()` and issuing an - SMC64 with `TSP_PREEMPTED` as the function identifier. Execution resumes at - the instruction that follows this SMC instruction when the TSPD hands - control to the TSP in response to an SMC with `TSP_FID_RESUME` as the - function identifier from the non-secure state (see section 2.3.2.4). - - -3. Other considerations ------------------------ - -### 3.1 Implication of preempted SMC on Non-Secure Software -A `yielding` SMC call to Secure payload can be preempted by a non-secure -interrupt and the execution can return to the non-secure world for handling -the interrupt (For details on `yielding` SMC refer [SMC calling convention]). -In this case, the SMC call has not completed its execution and the execution -must return back to the secure payload to resume the preempted SMC call. -This can be achieved by issuing an SMC call which instructs to resume the -preempted SMC. - -A `fast` SMC cannot be preempted and hence this case will not happen for -a fast SMC call. - -In the Test Secure Payload implementation, `TSP_FID_RESUME` is designated -as the resume SMC FID. It is important to note that `TSP_FID_RESUME` is a -`yielding` SMC which means it too can be be preempted. The typical non -secure software sequence for issuing a `yielding` SMC would look like this, -assuming `P.STATE.I=0` in the non secure state : - - int rc; - rc = smc(TSP_YIELD_SMC_FID, ...); /* Issue a Yielding SMC call */ - /* The pending non-secure interrupt is handled by the interrupt handler - and returns back here. */ - while (rc == SMC_PREEMPTED) { /* Check if the SMC call is preempted */ - rc = smc(TSP_FID_RESUME); /* Issue resume SMC call */ - } - -The `TSP_YIELD_SMC_FID` is any `yielding` SMC function identifier and the smc() -function invokes a SMC call with the required arguments. The pending non-secure -interrupt causes an IRQ exception and the IRQ handler registered at the -exception vector handles the non-secure interrupt and returns. The return value -from the SMC call is tested for `SMC_PREEMPTED` to check whether it is -preempted. If it is, then the resume SMC call `TSP_FID_RESUME` is issued. The -return value of the SMC call is tested again to check if it is preempted. -This is done in a loop till the SMC call succeeds or fails. If a `yielding` -SMC is preempted, until it is resumed using `TSP_FID_RESUME` SMC and -completed, the current TSPD prevents any other SMC call from re-entering -TSP by returning `SMC_UNK` error. - - -- - - - - - - - - - - - - - - - - - - - - - - - - - - -_Copyright (c) 2014-2015, ARM Limited and Contributors. All rights reserved._ - -[Porting Guide]: ./porting-guide.md -[SMC calling convention]: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html "SMC Calling Convention PDD (ARM DEN 0028A)" diff --git a/docs/plat/hikey.md b/docs/plat/hikey.md deleted file mode 100644 index 5e62a5bc..00000000 --- a/docs/plat/hikey.md +++ /dev/null @@ -1,147 +0,0 @@ - -Description -==================== -HiKey is one of 96boards. Hisilicon Kirin6220 processor is installed on HiKey. - -More information are listed in [link](https://github.com/96boards/documentation/blob/master/ConsumerEdition/HiKey/Quickstart/README.md). - - -How to build -==================== - -1. Code Locations ------------------ - - * ARM Trusted Firmware: - [link](https://github.com/ARM-software/arm-trusted-firmware) - - * edk2: - [link](https://github.com/96boards-hikey/edk2/tree/testing/hikey960_v2.5) - - * OpenPlatformPkg: - [link](https://github.com/96boards-hikey/OpenPlatformPkg/tree/testing/hikey960_v1.3.4) - - * l-loader: - [link](https://github.com/96boards-hikey/l-loader/tree/testing/hikey960_v1.2) - - * uefi-tools: - [link](https://github.com/96boards-hikey/uefi-tools/tree/testing/hikey960_v1) - - * atf-fastboot: - [link](https://github.com/96boards-hikey/atf-fastboot/tree/master) - - -2. Build Procedure ------------------- - - * Fetch all the above repositories into local host. - Make all the repositories in the same ${BUILD_PATH}. - - * Create the symbol link to OpenPlatformPkg in edk2. - ```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.__ - ```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. - ```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. - ```shell - $PTABLE=aosp-4g SECTOR_SIZE=512 bash -x generate_ptable.sh - ``` - - -3. Setup Console ----------------- - - * Install ser2net. Use telnet as the console since UEFI fails to display Boot Manager GUI in minicom. __If you don't need Boot Manager GUI, just ignore this section.__ - ```shell - $sudo apt-get install ser2net - ``` - - * Configure ser2net. - ```shell - $sudo vi /etc/ser2net.conf - ``` - - Append one line for serial-over-USB in below. - _#ser2net.conf_ - ```shell - 2004:telnet:0:/dev/ttyUSB0:115200 8DATABITS NONE 1STOPBIT banner - ``` - - * Open the console. - ```shell - $telnet localhost 2004 - ``` - - And you could open the console remotely, too. - - -4. Flush images in recovery mode ------------------------------ - - * Make sure Pin3-Pin4 on J15 are connected for recovery mode. Then power on HiKey. - - * Remove the modemmanager package. This package may cause the idt tool failure. - ```shell - $sudo apt-get purge modemmanager - ``` - - * Run the command to download l-loader.bin into HiKey. - ```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/). - ```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 - ``` - - -5. Boot UEFI in normal mode ------------------------------ - - * Make sure Pin3-Pin4 on J15 are open for normal boot mode. Then power on HiKey. - - * Reference [link](https://github.com/96boards-hikey/tools-images-hikey960/blob/master/build-from-source/README-ATF-UEFI-build-from-source.md) diff --git a/docs/plat/hikey960.md b/docs/plat/hikey960.md deleted file mode 100644 index 8442a189..00000000 --- a/docs/plat/hikey960.md +++ /dev/null @@ -1,159 +0,0 @@ - -Description -==================== -HiKey960 is one of 96boards. Hisilicon Hi3660 processor is installed on HiKey960. - -More information are listed in [link](http://www.96boards.org/documentation/ConsumerEdition/HiKey960/README.md). - - -How to build -==================== - -1. Code Locations ------------------ - - * ARM Trusted Firmware: - [link](https://github.com/ARM-software/arm-trusted-firmware) - - * edk2: - [link](https://github.com/96boards-hikey/edk2/tree/testing/hikey960_v2.5) - - * OpenPlatformPkg: - [link](https://github.com/96boards-hikey/OpenPlatformPkg/tree/testing/hikey960_v1.3.4) - - * l-loader: - [link](https://github.com/96boards-hikey/l-loader/tree/testing/hikey960_v1.2) - - * uefi-tools: - [link](https://github.com/96boards-hikey/uefi-tools/tree/hikey960_v1) - - -2. Build Procedure ------------------- - - * Fetch all the above 5 repositories into local host. - Make all the repositories in the same ${BUILD_PATH}. - - * Create the symbol link to OpenPlatformPkg in edk2. - ```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.__ - ```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. - ```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._ - ```shell - $PTABLE=aosp-32g SECTOR_SIZE=4096 SGDISK=./sgdisk bash -x generate_ptable.sh - ``` - - -3. Setup Console ----------------- - - * Install ser2net. Use telnet as the console since UEFI will output window - that fails to display in minicom. - ```shell - $sudo apt-get install ser2net - ``` - - * Configure ser2net. - ```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. - ```shell - $telnet localhost 2004 - ``` - And you could open the console remotely, too. - - -4. Boot UEFI in recovery mode ------------------------------ - - * Fetch that are used in recovery mode. The code location is in below. - [link](https://github.com/96boards-hikey/tools-images-hikey960) - - * Generate l-loader.bin. - ```shell - $cd tools-images-hikey960 - $ln -sf ${BUILD_PATH}/l-loader/l-loader.bin - ``` - - * Prepare config file. - ```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. - ```shell - $sudo apt-get purge modemmanager - ``` - - * Run the command to download l-loader.bin into HiKey960. - ```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. - ```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. - - -5. Boot UEFI in normal mode ------------------------------ - - * Make sure "Boot Mode" switch is OFF for normal boot mode. Then power on HiKey960. - - * Reference [link](https://github.com/96boards-hikey/tools-images-hikey960/blob/master/build-from-source/README-ATF-UEFI-build-from-source.md) diff --git a/docs/plat/nvidia-tegra.md b/docs/plat/nvidia-tegra.md deleted file mode 100644 index 3cb16827..00000000 --- a/docs/plat/nvidia-tegra.md +++ /dev/null @@ -1,95 +0,0 @@ -Tegra SoCs - Overview -====================== - -* 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. - -* 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 -=================================================== -```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. diff --git a/docs/plat/qemu.md b/docs/plat/qemu.md deleted file mode 100644 index 5e6bcbce..00000000 --- a/docs/plat/qemu.md +++ /dev/null @@ -1,44 +0,0 @@ -ARM Trusted Firmware for QEMU virt ARMv8-A -========================================== - -ARM Trusted Firmware implements the EL3 firmware layer for QEMU virt -ARMv8-A. BL1 is used as the BootROM, supplied with the -bios argument. -When QEMU starts all CPUs are released simultaneously, BL1 selects a -primary CPU to handle the boot and the secondaries are placed in a polling -loop to be released by normal world via PSCI. - -BL2 edits the Flattened Device Tree, FDT, generated by QEMU at run-time to -add a node describing PSCI and also enable methods for the CPUs. - -An ARM64 defonfig v4.5 Linux kernel is known to boot, FTD doesn't need to be -provided as it's generated by QEMU. - -Current limitations: -* Only cold boot is supported -* No build instructions for QEMU_EFI.fd and rootfs-arm64.cpio.gz -* No instructions for how to load a BL32 (Secure Payload) - -`QEMU_EFI.fd` can be dowloaded from -http://snapshots.linaro.org/components/kernel/leg-virt-tianocore-edk2-upstream/latest/QEMU-KERNEL-AARCH64/RELEASE_GCC49/QEMU_EFI.fd - -Boot binaries, except BL1, are primarily loaded via semi-hosting so all -binaries has to reside in the same directory as QEMU is started from. This -is conveniently achieved with symlinks the local names as: -* `bl2.bin` -> BL2 -* `bl31.bin` -> BL31 -* `bl33.bin` -> BL33 (`QEMU_EFI.fd`) -* `Image` -> linux/Image - -To build: -``` -make CROSS_COMPILE=aarch64-none-elf- PLAT=qemu -``` - -To start (QEMU v2.6.0): -``` -qemu-system-aarch64 -nographic -machine virt,secure=on -cpu cortex-a57 \ - -kernel Image \ - -append console=ttyAMA0,38400 keep_bootcon root=/dev/vda2 \ - -initrd rootfs-arm64.cpio.gz -smp 2 -m 1024 -bios bl1.bin \ - -d unimp -semihosting-config enable,target=native -``` diff --git a/docs/plat/socionext-uniphier.md b/docs/plat/socionext-uniphier.md deleted file mode 100644 index 91d72ec0..00000000 --- a/docs/plat/socionext-uniphier.md +++ /dev/null @@ -1,130 +0,0 @@ -ARM Trusted Firmware for Socionext UniPhier SoCs -================================================ - -Socionext UniPhier ARMv8-A SoCs use ARM Trusted Firmware as the secure world -firmware, supporting BL1, BL2, and BL31. - -UniPhier SoC family implements its internal boot ROM, so BL1 is used as pseudo -ROM (i.e. runs in RAM). The internal boot ROM loads 64KB [1] image from a -non-volatile storage to the on-chip SRAM. Unfortunately, BL1 does not fit in -the 64KB limit if [Trusted Board Boot] (TBB) is enabled. To solve this problem, -Socionext provides a first stage loader called [UniPhier BL]. This loader runs -in the on-chip SRAM, initializes the DRAM, expands BL1 there, and hands the -control over to it. Therefore, all images of ARM Trusted Firmware run in DRAM. - -The UniPhier platform works with/without TBB. See below for the build process -of each case. The image authentication for the UniPhier platform fully -complies with the Trusted Board Boot Requirements (TBBR) specification. - -The UniPhier BL does not implement the authentication functionality, that is, -it can not verify the BL1 image by itself. Instead, the UniPhier BL assures -the BL1 validity in a different way; BL1 is GZIP-compressed and appended to -the UniPhier BL. The concatenation of the UniPhier BL and the compressed BL1 -fits in the 64KB limit. The concatenated image is loaded by the boot ROM -(and verified if the chip fuses are blown). - -[1]: Some SoCs can load 80KB, but the software implementation must be aligned - to the lowest common denominator. - -[Trusted Board Boot]: ../trusted-board-boot.md - -[UniPhier BL]: https://github.com/uniphier/uniphier-bl - - -Boot Flow ---------- - -1. The Boot ROM - - This is hard-wired ROM, so never corrupted. It loads the UniPhier BL (with - compressed-BL1 appended) into the on-chip SRAM. If the SoC fuses are blown, - the image is verified by the SoC's own method. - -2. UniPhier BL - - This runs in the on-chip SRAM. After the minimum SoC initialization and DRAM - setup, it decompresses the appended BL1 image into the DRAM, then jumps to - the BL1 entry. - -3. BL1 - - This runs in the DRAM. It extracts BL2 from FIP (Firmware Image Package). - If TBB is enabled, the BL2 is authenticated by the standard mechanism of ARM - Trusted Firmware. - -4. BL2, BL31, and more - - They all run in the DRAM, and are authenticated by the standard mechanism if - TBB is enabled. See [Firmware Design] for details. - -[Firmware Design]: ../firmware-design.md - - -Basic Build ------------ - -BL1 must be compressed for the reason above. The UniPhier's platform makefile -provides a build target `bl1_gzip` for this. - -For a non-secure boot loader (aka BL33), U-Boot is well supported for UniPhier -SoCs. The U-Boot image (`u-boot.bin`) must be built in advance. For the build -procedure of U-Boot, refer to the document in the [U-Boot] project. - -[U-Boot]: https://www.denx.de/wiki/U-Boot - -To build minimum functionality for UniPhier (without TBB): - -``` -make CROSS_COMPILE=<gcc-prefix> PLAT=uniphier BL33=<path-to-BL33> bl1_gzip fip -``` - -Output images: - -- `bl1.bin.gzip` -- `fip.bin` - - -Optional features ------------------ - -- Trusted Board Boot - -[mbed TLS] is needed as the cryptographic and image parser modules. -Refer to the [User Guide] for the appropriate version of mbed TLS. - -To enable TBB, add the following options to the build command: - -``` - TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 MBEDTLS_DIR=<path-to-mbedtls> -``` - -[mbed TLS]: https://tls.mbed.org/ - -[User Guide]: ../user-guide.md - -- System Control Processor (SCP) - -If desired, FIP can include an SCP BL2 image. If BL2 finds an SCP BL2 image -in FIP, BL2 loads it into DRAM and kicks the SCP. Most of UniPhier boards -still work without SCP, but SCP provides better power management support. - -To include SCP_BL2, add the following option to the build command: - -``` - SCP_BL2=<path-to-SCP> -``` - -- BL32 (Secure Payload) - -To enable BL32, add the following option to the build command: - -``` - SPD=<spd> BL32=<path-to-BL32> -``` - -If you use TSP for BL32, `BL32=<path-to-BL32>` is not required. Just add the -following: - -``` - SPD=tspd -``` diff --git a/docs/plat/xilinx-zynqmp.md b/docs/plat/xilinx-zynqmp.md deleted file mode 100644 index d2dc8b76..00000000 --- a/docs/plat/xilinx-zynqmp.md +++ /dev/null @@ -1,56 +0,0 @@ -ARM Trusted Firmware for Xilinx Zynq UltraScale+ MPSoC -================================ - -ARM Trusted Firmware implements the EL3 firmware layer for Xilinx Zynq -UltraScale + MPSoC. -The platform only uses the runtime part of ATF as ZynqMP already has a -BootROM (BL1) and FSBL (BL2). - -BL31 is ATF. -BL32 is an optional Secure Payload. -BL33 is the non-secure world software (U-Boot, Linux etc). - -To build: -```bash -make ERROR_DEPRECATED=1 CROSS_COMPILE=aarch64-none-elf- PLAT=zynqmp bl31 -``` - -To build bl32 TSP you have to rebuild bl31 too: -```bash -make ERROR_DEPRECATED=1 CROSS_COMPILE=aarch64-none-elf- PLAT=zynqmp SPD=tspd bl31 bl32 -``` - -# ZynqMP platform specific build options -* `ZYNQMP_ATF_MEM_BASE`: Specifies the base address of the bl31 binary. -* `ZYNQMP_ATF_MEM_SIZE`: Specifies the size of the memory region of the bl31 binary. -* `ZYNQMP_BL32_MEM_BASE`: Specifies the base address of the bl32 binary. -* `ZYNQMP_BL32_MEM_SIZE`: Specifies the size of the memory region of the bl32 binary. - -* `ZYNQMP_CONSOLE`: Select the console driver. Options: - - `cadence`, `cadence0`: Cadence UART 0 - - `cadence1` : Cadence UART 1 - -# FSBL->ATF Parameter Passing -The FSBL populates a data structure with image information for the ATF. The ATF -uses that data to hand off to the loaded images. The address of the handoff data -structure is passed in the ```PMU_GLOBAL.GLOBAL_GEN_STORAGE6``` register. The -register is free to be used by other software once the ATF is bringing up -further firmware images. - -# Power Domain Tree -The following power domain tree represents the power domain model used by the -ATF for ZynqMP: -``` - +-+ - |0| - +-+ - +-------+---+---+-------+ - | | | | - | | | | - v v v v - +-+ +-+ +-+ +-+ - |0| |1| |2| |3| - +-+ +-+ +-+ +-+ -``` -The 4 leaf power domains represent the individual A53 cores, while resources -common to the cluster are grouped in the power domain on the top. diff --git a/docs/platform-migration-guide.md b/docs/platform-migration-guide.md deleted file mode 100644 index 27cd0671..00000000 --- a/docs/platform-migration-guide.md +++ /dev/null @@ -1,575 +0,0 @@ -Guide to migrate to new Platform porting interface -================================================== - -Contents --------- - -1. [Introduction](#1--introduction) -2. [Platform API modification due to PSCI framework changes](#2--platform-api-modification-due-to-psci-framework-changes) - * [Power domain topology framework platform API modifications](#21-power-domain-topology-framework-platform-api-modifications) - * [Composite power state framework platform API modifications](#22-composite-power-state-framework-platform-api-modifications) - * [Miscellaneous modifications](#23-miscellaneous-modifications) -3. [Compatibility layer](#3--compatibility-layer) -4. [Deprecated Platform API](#4--deprecated-platform-api) - -- - - - - - - - - - - - - - - - - - - - -1. Introduction ----------------- - -The PSCI implementation in Trusted Firmware has undergone a redesign because of -three requirements that the PSCI 1.0 specification introduced : - -* Removing the framework assumption about the structure of the MPIDR, and - its relation to the power topology enables support for deeper and more - complex hierarchies. - -* Reworking the power state coordination implementation in the framework - to support the more detailed PSCI 1.0 requirements and reduce platform - port complexity - -* Enable the use of the extended power_state parameter and the larger StateID - field - -The PSCI 1.0 implementation introduces new frameworks to fulfill the above -requirements. These framework changes mean that the platform porting API must -also be modified. This document is a guide to assist migration of the existing -platform ports to the new platform API. - -This document describes the new platform API and compares it with the -deprecated API. It also describes the compatibility layer that enables the -existing platform ports to work with the PSCI 1.0 implementation. The -deprecated platform API is documented for reference. - - -2. Platform API modification due to PSCI framework changes ------------------------------------------------------------ - -This section describes changes to the platform APIs. - - -2.1 Power domain topology framework platform API modifications --------------------------------------------------------------- - -This removes the assumption in the PSCI implementation that MPIDR -based affinity instances map directly to power domains. A power domain, as -described in section 4.2 of [PSCI], could contain a core or a logical group -of cores (a cluster) which share some state on which power management -operations can be performed. The existing affinity instance based APIs -`plat_get_aff_count()` and `plat_get_aff_state()` are deprecated. The new -platform interfaces that are introduced for this framework are: - -* `plat_core_pos_by_mpidr()` -* `plat_my_core_pos()` -* `plat_get_power_domain_tree_desc()` - -`plat_my_core_pos()` and `plat_core_pos_by_mpidr()` are mandatory -and are meant to replace the existing `platform_get_core_pos()` API. -The description of these APIs can be found in the [Porting Guide][my_core_pos]. -These are used by the power domain topology framework such that: - -1. The generic PSCI code does not generate MPIDRs or use them to query the - platform about the number of power domains at a particular power level. The - `plat_get_power_domain_tree_desc()` provides a description of the power - domain tree on the SoC through a pointer to the byte array containing the - power domain topology tree description data structure. - -2. The linear indices returned by `plat_core_pos_by_mpidr()` and - `plat_my_core_pos()` are used to retrieve core power domain nodes from - the power domain tree. These core indices are unique for a core and it is a - number between `0` and `PLATFORM_CORE_COUNT - 1`. The platform can choose - to implement a static mapping between `MPIDR` and core index or implement - a dynamic mapping, choosing to skip the unavailable/unused cores to compact - the core indices. - -In addition, the platforms must define the macros `PLAT_NUM_PWR_DOMAINS` and -`PLAT_MAX_PWR_LVL` which replace the macros `PLAT_NUM_AFFS` and -`PLATFORM_MAX_AFFLVL` respectively. On platforms where the affinity instances -correspond to power domains, the values of new macros remain the same as the -old ones. - -More details on the power domain topology description and its platform -interface can be found in [psci pd tree]. - - -2.2 Composite power state framework platform API modifications --------------------------------------------------------------- - -The state-ID field in the power-state parameter of a CPU_SUSPEND call can be -used to describe the composite power states specific to a platform. The existing -PSCI state coordination had the limitation that it operates on a run/off -granularity of power states and it did not interpret the state-ID field. This -was acceptable as the specification requirement in PSCI 0.2 and the framework's -approach to coordination only required maintaining a reference -count of the number of cores that have requested the cluster to remain powered. - -In the PSCI 1.0 specification, this approach is non optimal. If composite -power states are used, the PSCI implementation cannot make global -decisions about state coordination required because it does not understand the -platform specific states. - -The PSCI 1.0 implementation now defines a generic representation of the -power-state parameter : - - typedef struct psci_power_state { - plat_local_state_t pwr_domain_state[PLAT_MAX_PWR_LVL + 1]; - } psci_power_state_t; - - -`pwr_domain_state` is an array where each index corresponds to a power level. -Each entry in the array contains the local power state the power domain at -that power level could enter. The meaning of the local power state value is -platform defined, and can vary between levels in a single platform. The PSCI -implementation constraints the values only so that it can classify the state -as RUN, RETENTION or OFF as required by the specification: - -1. Zero means RUN - -2. All OFF state values at all levels must be higher than all - RETENTION state values at all levels - -The platform is required to define the macros `PLAT_MAX_RET_STATE` and -`PLAT_MAX_OFF_STATE` to the framework. The requirement for these macros can -be found in the [Porting Guide]. - -The PSCI 1.0 implementation adds support to involve the platform in state -coordination. This enables the platform to decide the final target state. -During a request to place a power domain in a low power state, the platform -is passed an array of requested `plat_local_state_t` for that power domain by -each core within it through the `plat_get_target_pwr_state()` API. This API -coordinates amongst these requested states to determine a target -`plat_local_state_t` for that power domain. A default weak implementation of -this API is provided in the platform layer which returns the minimum of the -requested local states back to the PSCI state coordination. More details -of `plat_get_target_pwr_state()` API can be found in the -[Porting Guide][get_target_pwr_state]. - -The PSCI Generic implementation expects platform ports to populate the handlers -for the `plat_psci_ops` structure which is declared as : - - typedef struct plat_psci_ops { - void (*cpu_standby)(plat_local_state_t cpu_state); - int (*pwr_domain_on)(u_register_t mpidr); - void (*pwr_domain_off)(const psci_power_state_t *target_state); - void (*pwr_domain_suspend)(const psci_power_state_t *target_state); - void (*pwr_domain_on_finish)(const psci_power_state_t *target_state); - void (*pwr_domain_suspend_finish)( - const psci_power_state_t *target_state); - void (*system_off)(void) __dead2; - void (*system_reset)(void) __dead2; - int (*validate_power_state)(unsigned int power_state, - psci_power_state_t *req_state); - int (*validate_ns_entrypoint)(unsigned long ns_entrypoint); - void (*get_sys_suspend_power_state)( - psci_power_state_t *req_state); - } plat_psci_ops_t; - -The description of these handlers can be found in the [Porting Guide][psci_ops]. -The previous `plat_pm_ops` structure is deprecated. Compared with the previous -handlers, the major differences are: - -* Difference in parameters - -The PSCI 1.0 implementation depends on the `validate_power_state` handler to -convert the power-state parameter (possibly encoding a composite power state) -passed in a PSCI `CPU_SUSPEND` to the `psci_power_state` format. This handler -is now mandatory for PSCI `CPU_SUSPEND` support. - -The `plat_psci_ops` handlers, `pwr_domain_off` and `pwr_domain_suspend`, are -passed the target local state for each affected power domain. The platform -must execute operations specific to these target states. Similarly, -`pwr_domain_on_finish` and `pwr_domain_suspend_finish` are passed the local -states of the affected power domains before wakeup. The platform -must execute actions to restore these power domains from these specific -local states. - -* Difference in invocation - -Whereas the power management handlers in `plat_pm_ops` used to be invoked -for each affinity level till the target affinity level, the new handlers -are only invoked once. The `target_state` encodes the target low power -state or the low power state woken up from for each affected power domain. - -* Difference in semantics - -Although the previous `suspend` handlers could be used for power down as well -as retention at different affinity levels, the new handlers make this support -explicit. The `pwr_domain_suspend` can be used to specify powerdown and -retention at various power domain levels subject to the conditions mentioned -in section 4.2.1 of [PSCI] - -Unlike the previous `standby` handler, the `cpu_standby()` handler is only used -as a fast path for placing a core power domain into a standby or retention -state. - -The below diagram shows the sequence of a PSCI SUSPEND call and the interaction -with the platform layer depicting the exchange of data between PSCI Generic -layer and the platform layer. - - - -Refer [plat/arm/board/fvp/fvp_pm.c] for the implementation details of -these handlers for the FVP. The commit 38dce70f51fb83b27958ba3e2ad15f5635cb1061 -demonstrates the migration of ARM reference platforms to the new platform API. - - -2.3 Miscellaneous modifications -------------------------------- - -In addition to the framework changes, unification of warm reset entry points on -wakeup from low power modes has led to a change in the platform API. In the -earlier implementation, the warm reset entry used to be programmed into the -mailboxes by the 'ON' and 'SUSPEND' power management hooks. In the PSCI 1.0 -implementation, this information is not required, because it can figure that -out by querying affinity info state whether to execute the 'suspend_finisher` -or 'on_finisher'. - -As a result, the warm reset entry point must be programmed only once. The -`plat_setup_psci_ops()` API takes the secure entry point as an -additional parameter to enable the platforms to configure their mailbox. The -plat_psci_ops handlers `pwr_domain_on` and `pwr_domain_suspend` no longer take -the warm reset entry point as a parameter. - -Also, some platform APIs which took `MPIDR` as an argument were only ever -invoked to perform actions specific to the caller core which makes the argument -redundant. Therefore the platform APIs `plat_get_my_entrypoint()`, -`plat_is_my_cpu_primary()`, `plat_set_my_stack()` and -`plat_get_my_stack()` are defined which are meant to be invoked only for -operations on the current caller core instead of `platform_get_entrypoint()`, -`platform_is_primary_cpu()`, `platform_set_stack()` and `platform_get_stack()`. - - -3. Compatibility layer ----------------------- - -To ease the migration of the platform ports to the new porting interface, -a compatibility layer is introduced that essentially implements a glue layer -between the old platform API and the new API. The build flag -`ENABLE_PLAT_COMPAT` (enabled by default), specifies whether to enable this -layer or not. A platform port which has migrated to the new API can disable -this flag within the platform specific makefile. - -The compatibility layer works on the assumption that the onus of -state coordination, in case multiple low power states are supported, -is with the platform. The generic PSCI implementation only takes into -account whether the suspend request is power down or not. This corresponds -with the behavior of the PSCI implementation before the introduction of -new frameworks. Also, it assumes that the affinity levels of the platform -correspond directly to the power domain levels. - -The compatibility layer dynamically constructs the new topology -description array by querying the platform using `plat_get_aff_count()` -and `plat_get_aff_state()` APIs. The linear index returned by -`platform_get_core_pos()` is used as the core index for the cores. The -higher level (non-core) power domain nodes must know the cores contained -within its domain. It does so by storing the core index of first core -within it and number of core indexes following it. This means that core -indices returned by `platform_get_core_pos()` for cores within a particular -power domain must be consecutive. We expect that this is the case for most -platform ports including ARM reference platforms. - -The old PSCI helpers like `psci_get_suspend_powerstate()`, -`psci_get_suspend_stateid()`, `psci_get_suspend_stateid_by_mpidr()`, -`psci_get_max_phys_off_afflvl()` and `psci_get_suspend_afflvl()` are also -implemented for the compatibility layer. This allows the existing -platform ports to work with the new PSCI frameworks without significant -rework. - - -4. Deprecated Platform API ---------------------------- - -This section documents the deprecated platform porting API. - -## Common mandatory modifications - -The mandatory macros to be defined by the platform port in `platform_def.h` - -* **#define : PLATFORM_NUM_AFFS** - - Defines the total number of nodes in the affinity hierarchy at all affinity - levels used by the platform. - -* **#define : PLATFORM_MAX_AFFLVL** - - Defines the maximum affinity level that the power management operations - should apply to. ARMv8-A has support for four affinity levels. It is likely - that hardware will implement fewer affinity levels. This macro allows the - PSCI implementation to consider only those affinity levels in the system - that the platform implements. For example, the Base AEM FVP implements two - clusters with a configurable number of cores. It reports the maximum - affinity level as 1, resulting in PSCI power control up to the cluster - level. - -The following functions must be implemented by the platform port to enable -the reset vector code to perform the required tasks. - -### Function : platform_get_entrypoint() [mandatory] - - Argument : unsigned long - Return : unsigned long - -This function is called with the `SCTLR.M` and `SCTLR.C` bits disabled. The core -is identified by its `MPIDR`, which is passed as the argument. The function is -responsible for distinguishing between a warm and cold reset using platform- -specific means. If it is a warm reset, it returns the entrypoint into the -BL31 image that the core must jump to. If it is a cold reset, this function -must return zero. - -This function is also responsible for implementing a platform-specific mechanism -to handle the condition where the core has been warm reset but there is no -entrypoint to jump to. - -This function does not follow the Procedure Call Standard used by the -Application Binary Interface for the ARM 64-bit architecture. The caller should -not assume that callee saved registers are preserved across a call to this -function. - -### Function : platform_is_primary_cpu() [mandatory] - - Argument : unsigned long - Return : unsigned int - -This function identifies a core by its `MPIDR`, which is passed as the argument, -to determine whether this core is the primary core or a secondary core. A return -value of zero indicates that the core is not the primary core, while a non-zero -return value indicates that the core is the primary core. - -## Common optional modifications - -### Function : platform_get_core_pos() - - Argument : unsigned long - Return : int - -A platform may need to convert the `MPIDR` of a core to an absolute number, which -can be used as a core-specific linear index into blocks of memory (for example -while allocating per-core stacks). This routine contains a simple mechanism -to perform this conversion, using the assumption that each cluster contains a -maximum of four cores: - - linear index = cpu_id + (cluster_id * 4) - - cpu_id = 8-bit value in MPIDR at affinity level 0 - cluster_id = 8-bit value in MPIDR at affinity level 1 - - -### Function : platform_set_stack() - - Argument : unsigned long - Return : void - -This function sets the current stack pointer to the normal memory stack that -has been allocated for the core specified by MPIDR. For BL images that only -require a stack for the primary core the parameter is ignored. The size of -the stack allocated to each core is specified by the platform defined constant -`PLATFORM_STACK_SIZE`. - -Common implementations of this function for the UP and MP BL images are -provided in [plat/common/aarch64/platform_up_stack.S] and -[plat/common/aarch64/platform_mp_stack.S] - - -### Function : platform_get_stack() - - Argument : unsigned long - Return : unsigned long - -This function returns the base address of the normal memory stack that -has been allocated for the core specificed by MPIDR. For BL images that only -require a stack for the primary core the parameter is ignored. The size of -the stack allocated to each core is specified by the platform defined constant -`PLATFORM_STACK_SIZE`. - -Common implementations of this function for the UP and MP BL images are -provided in [plat/common/aarch64/platform_up_stack.S] and -[plat/common/aarch64/platform_mp_stack.S] - - -## Modifications for Power State Coordination Interface (in BL31) - -The following functions must be implemented to initialize PSCI functionality in -the ARM Trusted Firmware. - - -### Function : plat_get_aff_count() [mandatory] - - Argument : unsigned int, unsigned long - Return : unsigned int - -This function may execute with the MMU and data caches enabled if the platform -port does the necessary initializations in `bl31_plat_arch_setup()`. It is only -called by the primary core. - -This function is called by the PSCI initialization code to detect the system -topology. Its purpose is to return the number of affinity instances implemented -at a given `affinity level` (specified by the first argument) and a given -`MPIDR` (specified by the second argument). For example, on a dual-cluster -system where first cluster implements two cores and the second cluster -implements four cores, a call to this function with an `MPIDR` corresponding -to the first cluster (`0x0`) and affinity level 0, would return 2. A call -to this function with an `MPIDR` corresponding to the second cluster (`0x100`) -and affinity level 0, would return 4. - - -### Function : plat_get_aff_state() [mandatory] - - Argument : unsigned int, unsigned long - Return : unsigned int - -This function may execute with the MMU and data caches enabled if the platform -port does the necessary initializations in `bl31_plat_arch_setup()`. It is only -called by the primary core. - -This function is called by the PSCI initialization code. Its purpose is to -return the state of an affinity instance. The affinity instance is determined by -the affinity ID at a given `affinity level` (specified by the first argument) -and an `MPIDR` (specified by the second argument). The state can be one of -`PSCI_AFF_PRESENT` or `PSCI_AFF_ABSENT`. The latter state is used to cater for -system topologies where certain affinity instances are unimplemented. For -example, consider a platform that implements a single cluster with four cores and -another core implemented directly on the interconnect with the cluster. The -`MPIDR`s of the cluster would range from `0x0-0x3`. The `MPIDR` of the single -core is 0x100 to indicate that it does not belong to cluster 0. Cluster 1 -is missing but needs to be accounted for to reach this single core in the -topology tree. Therefore it is marked as `PSCI_AFF_ABSENT`. - - -### Function : platform_setup_pm() [mandatory] - - Argument : const plat_pm_ops ** - Return : int - -This function may execute with the MMU and data caches enabled if the platform -port does the necessary initializations in `bl31_plat_arch_setup()`. It is only -called by the primary core. - -This function is called by PSCI initialization code. Its purpose is to export -handler routines for platform-specific power management actions by populating -the passed pointer with a pointer to the private `plat_pm_ops` structure of -BL31. - -A description of each member of this structure is given below. A platform port -is expected to implement these handlers if the corresponding PSCI operation -is to be supported and these handlers are expected to succeed if the return -type is `void`. - -#### plat_pm_ops.affinst_standby() - -Perform the platform-specific setup to enter the standby state indicated by the -passed argument. The generic code expects the handler to succeed. - -#### plat_pm_ops.affinst_on() - -Perform the platform specific setup to power on an affinity instance, specified -by the `MPIDR` (first argument) and `affinity level` (third argument). The -`state` (fourth argument) contains the current state of that affinity instance -(ON or OFF). This is useful to determine whether any action must be taken. For -example, while powering on a core, the cluster that contains this core might -already be in the ON state. The platform decides what actions must be taken to -transition from the current state to the target state (indicated by the power -management operation). The generic code expects the platform to return -E_SUCCESS on success or E_INTERN_FAIL for any failure. - -#### plat_pm_ops.affinst_off() - -Perform the platform specific setup to power off an affinity instance of the -calling core. It is called by the PSCI `CPU_OFF` API implementation. - -The `affinity level` (first argument) and `state` (second argument) have -a similar meaning as described in the `affinst_on()` operation. They -identify the affinity instance on which the call is made and its -current state. This gives the platform port an indication of the -state transition it must make to perform the requested action. For example, if -the calling core is the last powered on core in the cluster, after powering down -affinity level 0 (the core), the platform port should power down affinity -level 1 (the cluster) as well. The generic code expects the handler to succeed. - -#### plat_pm_ops.affinst_suspend() - -Perform the platform specific setup to power off an affinity instance of the -calling core. It is called by the PSCI `CPU_SUSPEND` API and `SYSTEM_SUSPEND` -API implementation - -The `affinity level` (second argument) and `state` (third argument) have a -similar meaning as described in the `affinst_on()` operation. They are used to -identify the affinity instance on which the call is made and its current state. -This gives the platform port an indication of the state transition it must -make to perform the requested action. For example, if the calling core is the -last powered on core in the cluster, after powering down affinity level 0 -(the core), the platform port should power down affinity level 1 (the cluster) -as well. - -The difference between turning an affinity instance off and suspending it -is that in the former case, the affinity instance is expected to re-initialize -its state when it is next powered on (see `affinst_on_finish()`). In the latter -case, the affinity instance is expected to save enough state so that it can -resume execution by restoring this state when it is powered on (see -`affinst_suspend_finish()`).The generic code expects the handler to succeed. - -#### plat_pm_ops.affinst_on_finish() - -This function is called by the PSCI implementation after the calling core is -powered on and released from reset in response to an earlier PSCI `CPU_ON` call. -It performs the platform-specific setup required to initialize enough state for -this core to enter the Normal world and also provide secure runtime firmware -services. - -The `affinity level` (first argument) and `state` (second argument) have a -similar meaning as described in the previous operations. The generic code -expects the handler to succeed. - -#### plat_pm_ops.affinst_suspend_finish() - -This function is called by the PSCI implementation after the calling core is -powered on and released from reset in response to an asynchronous wakeup -event, for example a timer interrupt that was programmed by the core during the -`CPU_SUSPEND` call or `SYSTEM_SUSPEND` call. It performs the platform-specific -setup required to restore the saved state for this core to resume execution -in the Normal world and also provide secure runtime firmware services. - -The `affinity level` (first argument) and `state` (second argument) have a -similar meaning as described in the previous operations. The generic code -expects the platform to succeed. - -#### plat_pm_ops.validate_power_state() - -This function is called by the PSCI implementation during the `CPU_SUSPEND` -call to validate the `power_state` parameter of the PSCI API. If the -`power_state` is known to be invalid, the platform must return -PSCI_E_INVALID_PARAMS as an error, which is propagated back to the Normal -world PSCI client. - -#### plat_pm_ops.validate_ns_entrypoint() - -This function is called by the PSCI implementation during the `CPU_SUSPEND`, -`SYSTEM_SUSPEND` and `CPU_ON` calls to validate the Non-secure `entry_point` -parameter passed by the Normal world. If the `entry_point` is known to be -invalid, the platform must return PSCI_E_INVALID_PARAMS as an error, which is -propagated back to the Normal world PSCI client. - -#### plat_pm_ops.get_sys_suspend_power_state() - -This function is called by the PSCI implementation during the `SYSTEM_SUSPEND` -call to return the `power_state` parameter. This allows the platform to encode -the appropriate State-ID field within the `power_state` parameter which can be -utilized in `affinst_suspend()` to suspend to system affinity level. The -`power_state` parameter should be in the same format as specified by the -PSCI specification for the CPU_SUSPEND API. - -- - - - - - - - - - - - - - - - - - - - - - - - - - - -_Copyright (c) 2015, ARM Limited and Contributors. All rights reserved._ - - -[Porting Guide]: porting-guide.md -[Power Domain Topology Design]: psci-pd-tree.md -[PSCI]: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf -[psci pd tree]: psci-pd-tree.md -[my_core_pos]: porting-guide.md#function--plat_my_core_pos -[get_target_pwr_state]: porting-guide.md#function--plat_get_target_pwr_state-optional -[psci_ops]: porting-guide.md#function--plat_setup_psci_ops-mandatory -[plat/arm/board/fvp/fvp_pm.c]: ../plat/arm/board/fvp/fvp_pm.c -[plat/common/aarch64/platform_mp_stack.S]: ../plat/common/aarch64/platform_mp_stack.S -[plat/common/aarch64/platform_up_stack.S]: ../plat/common/aarch64/platform_up_stack.S diff --git a/docs/porting-guide.md b/docs/porting-guide.md deleted file mode 100644 index 047e2250..00000000 --- a/docs/porting-guide.md +++ /dev/null @@ -1,2413 +0,0 @@ -ARM Trusted Firmware Porting Guide -================================== - -Contents --------- - -1. [Introduction](#1--introduction) -2. [Common Modifications](#2--common-modifications) - * [Common mandatory modifications](#21-common-mandatory-modifications) - * [Handling reset](#22-handling-reset) - * [Common mandatory function modifications](#23-common-mandatory-function-modifications) - * [Common optional modifications](#24-common-optional-modifications) -3. [Boot Loader stage specific modifications](#3--modifications-specific-to-a-boot-loader-stage) - * [Boot Loader stage 1 (BL1)](#31-boot-loader-stage-1-bl1) - * [Boot Loader stage 2 (BL2)](#32-boot-loader-stage-2-bl2) - * [FWU Boot Loader stage 2 (BL2U)](#33-fwu-boot-loader-stage-2-bl2u) - * [Boot Loader stage 3-1 (BL31)](#34-boot-loader-stage-3-1-bl31) - * [PSCI implementation (in BL31)](#35-power-state-coordination-interface-in-bl31) - * [Interrupt Management framework (in BL31)](#36--interrupt-management-framework-in-bl31) - * [Crash Reporting mechanism (in BL31)](#37--crash-reporting-mechanism-in-bl31) -4. [Build flags](#4--build-flags) -5. [C Library](#5--c-library) -6. [Storage abstraction layer](#6--storage-abstraction-layer) - -- - - - - - - - - - - - - - - - - - - -1. Introduction ----------------- - -Please note that this document has been updated for the new platform API -as required by the PSCI v1.0 implementation. Please refer to the -[Migration Guide] for the previous platform API. - -Porting the ARM Trusted Firmware to a new platform involves making some -mandatory and optional modifications for both the cold and warm boot paths. -Modifications consist of: - -* Implementing a platform-specific function or variable, -* Setting up the execution context in a certain way, or -* Defining certain constants (for example #defines). - -The platform-specific functions and variables are declared in -[include/plat/common/platform.h]. The firmware provides a default implementation -of variables and functions to fulfill the optional requirements. These -implementations are all weakly defined; they are provided to ease the porting -effort. Each platform port can override them with its own implementation if the -default implementation is inadequate. - -Platform ports that want to be aligned with standard ARM platforms (for example -FVP and Juno) may also use [include/plat/arm/common/plat_arm.h] and the -corresponding source files in `plat/arm/common/`. These provide standard -implementations for some of the required platform porting functions. However, -using these functions requires the platform port to implement additional -ARM standard platform porting functions. These additional functions are not -documented here. - -Some modifications are common to all Boot Loader (BL) stages. Section 2 -discusses these in detail. The subsequent sections discuss the remaining -modifications for each BL stage in detail. - -This document should be read in conjunction with the ARM Trusted Firmware -[User Guide]. - - -2. Common modifications ------------------------- - -This section covers the modifications that should be made by the platform for -each BL stage to correctly port the firmware stack. They are categorized as -either mandatory or optional. - - -2.1 Common mandatory modifications ----------------------------------- - -A platform port must enable the Memory Management Unit (MMU) as well as the -instruction and data caches for each BL stage. Setting up the translation -tables is the responsibility of the platform port because memory maps differ -across platforms. A memory translation library (see `lib/xlat_tables/`) is -provided to help in this setup. Note that although this library supports -non-identity mappings, this is intended only for re-mapping peripheral physical -addresses and allows platforms with high I/O addresses to reduce their virtual -address space. All other addresses corresponding to code and data must currently -use an identity mapping. - -In ARM standard platforms, each BL stage configures the MMU in the -platform-specific architecture setup function, `blX_plat_arch_setup()`, and uses -an identity mapping for all addresses. - -If the build option `USE_COHERENT_MEM` is enabled, each platform can allocate a -block of identity mapped secure memory with Device-nGnRE attributes aligned to -page boundary (4K) for each BL stage. All sections which allocate coherent -memory are grouped under `coherent_ram`. For ex: Bakery locks are placed in a -section identified by name `bakery_lock` inside `coherent_ram` so that its -possible for the firmware to place variables in it using the following C code -directive: - - __section("bakery_lock") - -Or alternatively the following assembler code directive: - - .section bakery_lock - -The `coherent_ram` section is a sum of all sections like `bakery_lock` which are -used to allocate any data structures that are accessed both when a CPU is -executing with its MMU and caches enabled, and when it's running with its MMU -and caches disabled. Examples are given below. - -The following variables, functions and constants must be defined by the platform -for the firmware to work correctly. - - -### File : platform_def.h [mandatory] - -Each platform must ensure that a header file of this name is in the system -include path with the following constants defined. This may require updating the -list of `PLAT_INCLUDES` in the `platform.mk` file. In the ARM development -platforms, this file is found in `plat/arm/board/<plat_name>/include/`. - -Platform ports may optionally use the file [include/plat/common/common_def.h], -which provides typical values for some of the constants below. These values are -likely to be suitable for all platform ports. - -Platform ports that want to be aligned with standard ARM platforms (for example -FVP and Juno) may also use [include/plat/arm/common/arm_def.h], which provides -standard values for some of the constants below. However, this requires the -platform port to define additional platform porting constants in -`platform_def.h`. These additional constants are not documented here. - -* **#define : PLATFORM_LINKER_FORMAT** - - Defines the linker format used by the platform, for example - `elf64-littleaarch64`. - -* **#define : PLATFORM_LINKER_ARCH** - - Defines the processor architecture for the linker by the platform, for - example `aarch64`. - -* **#define : PLATFORM_STACK_SIZE** - - Defines the normal stack memory available to each CPU. This constant is used - by [plat/common/aarch64/platform_mp_stack.S] and - [plat/common/aarch64/platform_up_stack.S]. - -* **define : CACHE_WRITEBACK_GRANULE** - - Defines the size in bits of the largest cache line across all the cache - levels in the platform. - -* **#define : FIRMWARE_WELCOME_STR** - - Defines the character string printed by BL1 upon entry into the `bl1_main()` - function. - -* **#define : PLATFORM_CORE_COUNT** - - Defines the total number of CPUs implemented by the platform across all - clusters in the system. - -* **#define : PLAT_NUM_PWR_DOMAINS** - - Defines the total number of nodes in the power domain topology - tree at all the power domain levels used by the platform. - This macro is used by the PSCI implementation to allocate - data structures to represent power domain topology. - -* **#define : PLAT_MAX_PWR_LVL** - - Defines the maximum power domain level that the power management operations - should apply to. More often, but not always, the power domain level - corresponds to affinity level. This macro allows the PSCI implementation - to know the highest power domain level that it should consider for power - management operations in the system that the platform implements. For - example, the Base AEM FVP implements two clusters with a configurable - number of CPUs and it reports the maximum power domain level as 1. - -* **#define : PLAT_MAX_OFF_STATE** - - Defines the local power state corresponding to the deepest power down - possible at every power domain level in the platform. The local power - states for each level may be sparsely allocated between 0 and this value - with 0 being reserved for the RUN state. The PSCI implementation uses this - value to initialize the local power states of the power domain nodes and - to specify the requested power state for a PSCI_CPU_OFF call. - -* **#define : PLAT_MAX_RET_STATE** - - Defines the local power state corresponding to the deepest retention state - possible at every power domain level in the platform. This macro should be - a value less than PLAT_MAX_OFF_STATE and greater than 0. It is used by the - PSCI implementation to distinguish between retention and power down local - power states within PSCI_CPU_SUSPEND call. - -* **#define : PLAT_MAX_PWR_LVL_STATES** - - Defines the maximum number of local power states per power domain level - that the platform supports. The default value of this macro is 2 since - most platforms just support a maximum of two local power states at each - power domain level (power-down and retention). If the platform needs to - account for more local power states, then it must redefine this macro. - - Currently, this macro is used by the Generic PSCI implementation to size - the array used for PSCI_STAT_COUNT/RESIDENCY accounting. - -* **#define : BL1_RO_BASE** - - Defines the base address in secure ROM where BL1 originally lives. Must be - aligned on a page-size boundary. - -* **#define : BL1_RO_LIMIT** - - Defines the maximum address in secure ROM that BL1's actual content (i.e. - excluding any data section allocated at runtime) can occupy. - -* **#define : BL1_RW_BASE** - - Defines the base address in secure RAM where BL1's read-write data will live - at runtime. Must be aligned on a page-size boundary. - -* **#define : BL1_RW_LIMIT** - - Defines the maximum address in secure RAM that BL1's read-write data can - occupy at runtime. - -* **#define : BL2_BASE** - - Defines the base address in secure RAM where BL1 loads the BL2 binary image. - Must be aligned on a page-size boundary. - -* **#define : BL2_LIMIT** - - Defines the maximum address in secure RAM that the BL2 image can occupy. - -* **#define : BL31_BASE** - - Defines the base address in secure RAM where BL2 loads the BL31 binary - image. Must be aligned on a page-size boundary. - -* **#define : BL31_LIMIT** - - Defines the maximum address in secure RAM that the BL31 image can occupy. - -For every image, the platform must define individual identifiers that will be -used by BL1 or BL2 to load the corresponding image into memory from non-volatile -storage. For the sake of performance, integer numbers will be used as -identifiers. The platform will use those identifiers to return the relevant -information about the image to be loaded (file handler, load address, -authentication information, etc.). The following image identifiers are -mandatory: - -* **#define : BL2_IMAGE_ID** - - BL2 image identifier, used by BL1 to load BL2. - -* **#define : BL31_IMAGE_ID** - - BL31 image identifier, used by BL2 to load BL31. - -* **#define : BL33_IMAGE_ID** - - BL33 image identifier, used by BL2 to load BL33. - -If Trusted Board Boot is enabled, the following certificate identifiers must -also be defined: - -* **#define : TRUSTED_BOOT_FW_CERT_ID** - - BL2 content certificate identifier, used by BL1 to load the BL2 content - certificate. - -* **#define : TRUSTED_KEY_CERT_ID** - - Trusted key certificate identifier, used by BL2 to load the trusted key - certificate. - -* **#define : SOC_FW_KEY_CERT_ID** - - BL31 key certificate identifier, used by BL2 to load the BL31 key - certificate. - -* **#define : SOC_FW_CONTENT_CERT_ID** - - BL31 content certificate identifier, used by BL2 to load the BL31 content - certificate. - -* **#define : NON_TRUSTED_FW_KEY_CERT_ID** - - BL33 key certificate identifier, used by BL2 to load the BL33 key - certificate. - -* **#define : NON_TRUSTED_FW_CONTENT_CERT_ID** - - BL33 content certificate identifier, used by BL2 to load the BL33 content - certificate. - -* **#define : FWU_CERT_ID** - - Firmware Update (FWU) certificate identifier, used by NS_BL1U to load the - FWU content certificate. - -* **#define : PLAT_CRYPTOCELL_BASE** - - This defines the base address of ARM® TrustZone® CryptoCell and must be - defined if CryptoCell crypto driver is used for Trusted Board Boot. For - capable ARM platforms, this driver is used if `ARM_CRYPTOCELL_INTEG` is - set. - -If the AP Firmware Updater Configuration image, BL2U is used, the following -must also be defined: - -* **#define : BL2U_BASE** - - Defines the base address in secure memory where BL1 copies the BL2U binary - image. Must be aligned on a page-size boundary. - -* **#define : BL2U_LIMIT** - - Defines the maximum address in secure memory that the BL2U image can occupy. - -* **#define : BL2U_IMAGE_ID** - - BL2U image identifier, used by BL1 to fetch an image descriptor - corresponding to BL2U. - -If the SCP Firmware Update Configuration Image, SCP_BL2U is used, the following -must also be defined: - -* **#define : SCP_BL2U_IMAGE_ID** - - SCP_BL2U image identifier, used by BL1 to fetch an image descriptor - corresponding to SCP_BL2U. - NOTE: TF does not provide source code for this image. - -If the Non-Secure Firmware Updater ROM, NS_BL1U is used, the following must -also be defined: - -* **#define : NS_BL1U_BASE** - - Defines the base address in non-secure ROM where NS_BL1U executes. - Must be aligned on a page-size boundary. - NOTE: TF does not provide source code for this image. - -* **#define : NS_BL1U_IMAGE_ID** - - NS_BL1U image identifier, used by BL1 to fetch an image descriptor - corresponding to NS_BL1U. - -If the Non-Secure Firmware Updater, NS_BL2U is used, the following must also -be defined: - -* **#define : NS_BL2U_BASE** - - Defines the base address in non-secure memory where NS_BL2U executes. - Must be aligned on a page-size boundary. - NOTE: TF does not provide source code for this image. - -* **#define : NS_BL2U_IMAGE_ID** - - NS_BL2U image identifier, used by BL1 to fetch an image descriptor - corresponding to NS_BL2U. - -For the the Firmware update capability of TRUSTED BOARD BOOT, the following -macros may also be defined: - -* **#define : PLAT_FWU_MAX_SIMULTANEOUS_IMAGES** - - Total number of images that can be loaded simultaneously. If the platform - doesn't specify any value, it defaults to 10. - -If a SCP_BL2 image is supported by the platform, the following constants must -also be defined: - -* **#define : SCP_BL2_IMAGE_ID** - - SCP_BL2 image identifier, used by BL2 to load SCP_BL2 into secure memory - from platform storage before being transfered to the SCP. - -* **#define : SCP_FW_KEY_CERT_ID** - - SCP_BL2 key certificate identifier, used by BL2 to load the SCP_BL2 key - certificate (mandatory when Trusted Board Boot is enabled). - -* **#define : SCP_FW_CONTENT_CERT_ID** - - SCP_BL2 content certificate identifier, used by BL2 to load the SCP_BL2 - content certificate (mandatory when Trusted Board Boot is enabled). - -If a BL32 image is supported by the platform, the following constants must -also be defined: - -* **#define : BL32_IMAGE_ID** - - BL32 image identifier, used by BL2 to load BL32. - -* **#define : TRUSTED_OS_FW_KEY_CERT_ID** - - BL32 key certificate identifier, used by BL2 to load the BL32 key - certificate (mandatory when Trusted Board Boot is enabled). - -* **#define : TRUSTED_OS_FW_CONTENT_CERT_ID** - - BL32 content certificate identifier, used by BL2 to load the BL32 content - certificate (mandatory when Trusted Board Boot is enabled). - -* **#define : BL32_BASE** - - Defines the base address in secure memory where BL2 loads the BL32 binary - image. Must be aligned on a page-size boundary. - -* **#define : BL32_LIMIT** - - Defines the maximum address that the BL32 image can occupy. - -If the Test Secure-EL1 Payload (TSP) instantiation of BL32 is supported by the -platform, the following constants must also be defined: - -* **#define : TSP_SEC_MEM_BASE** - - Defines the base address of the secure memory used by the TSP image on the - platform. This must be at the same address or below `BL32_BASE`. - -* **#define : TSP_SEC_MEM_SIZE** - - Defines the size of the secure memory used by the BL32 image on the - platform. `TSP_SEC_MEM_BASE` and `TSP_SEC_MEM_SIZE` must fully accomodate - the memory required by the BL32 image, defined by `BL32_BASE` and - `BL32_LIMIT`. - -* **#define : TSP_IRQ_SEC_PHY_TIMER** - - Defines the ID of the secure physical generic timer interrupt used by the - TSP's interrupt handling code. - -If the platform port uses the translation table library code, the following -constants must also be defined: - -* **#define : PLAT_XLAT_TABLES_DYNAMIC** - - Optional flag that can be set per-image to enable the dynamic allocation of - regions even when the MMU is enabled. If not defined, only static - functionality will be available, if defined and set to 1 it will also - include the dynamic functionality. - -* **#define : MAX_XLAT_TABLES** - - Defines the maximum number of translation tables that are allocated by the - translation table library code. To minimize the amount of runtime memory - used, choose the smallest value needed to map the required virtual addresses - for each BL stage. If `PLAT_XLAT_TABLES_DYNAMIC` flag is enabled for a BL - image, `MAX_XLAT_TABLES` must be defined to accommodate the dynamic regions - as well. - -* **#define : MAX_MMAP_REGIONS** - - Defines the maximum number of regions that are allocated by the translation - table library code. A region consists of physical base address, virtual base - address, size and attributes (Device/Memory, RO/RW, Secure/Non-Secure), as - defined in the `mmap_region_t` structure. The platform defines the regions - that should be mapped. Then, the translation table library will create the - corresponding tables and descriptors at runtime. To minimize the amount of - runtime memory used, choose the smallest value needed to register the - required regions for each BL stage. If `PLAT_XLAT_TABLES_DYNAMIC` flag is - enabled for a BL image, `MAX_MMAP_REGIONS` must be defined to accommodate - the dynamic regions as well. - -* **#define : ADDR_SPACE_SIZE** - - Defines the total size of the address space in bytes. For example, for a 32 - bit address space, this value should be `(1ull << 32)`. This definition is - now deprecated, platforms should use `PLAT_PHY_ADDR_SPACE_SIZE` and - `PLAT_VIRT_ADDR_SPACE_SIZE` instead. - -* **#define : PLAT_VIRT_ADDR_SPACE_SIZE** - - Defines the total size of the virtual address space in bytes. For example, - for a 32 bit virtual address space, this value should be `(1ull << 32)`. - -* **#define : PLAT_PHY_ADDR_SPACE_SIZE** - - Defines the total size of the physical address space in bytes. For example, - for a 32 bit physical address space, this value should be `(1ull << 32)`. - -If the platform port uses the IO storage framework, the following constants -must also be defined: - -* **#define : MAX_IO_DEVICES** - - Defines the maximum number of registered IO devices. Attempting to register - more devices than this value using `io_register_device()` will fail with - -ENOMEM. - -* **#define : MAX_IO_HANDLES** - - Defines the maximum number of open IO handles. Attempting to open more IO - entities than this value using `io_open()` will fail with -ENOMEM. - -* **#define : MAX_IO_BLOCK_DEVICES** - - Defines the maximum number of registered IO block devices. Attempting to - register more devices this value using `io_dev_open()` will fail - with -ENOMEM. MAX_IO_BLOCK_DEVICES should be less than MAX_IO_DEVICES. - With this macro, multiple block devices could be supported at the same - time. - -If the platform needs to allocate data within the per-cpu data framework in -BL31, it should define the following macro. Currently this is only required if -the platform decides not to use the coherent memory section by undefining the -`USE_COHERENT_MEM` build flag. In this case, the framework allocates the -required memory within the the per-cpu data to minimize wastage. - -* **#define : PLAT_PCPU_DATA_SIZE** - - Defines the memory (in bytes) to be reserved within the per-cpu data - structure for use by the platform layer. - -The following constants are optional. They should be defined when the platform -memory layout implies some image overlaying like in ARM standard platforms. - -* **#define : BL31_PROGBITS_LIMIT** - - Defines the maximum address in secure RAM that the BL31's progbits sections - can occupy. - -* **#define : TSP_PROGBITS_LIMIT** - - Defines the maximum address that the TSP's progbits sections can occupy. - -If the platform port uses the PL061 GPIO driver, the following constant may -optionally be defined: - -* **PLAT_PL061_MAX_GPIOS** - Maximum number of GPIOs required by the platform. This allows control how - much memory is allocated for PL061 GPIO controllers. The default value is - 32. - [For example, define the build flag in platform.mk]: - PLAT_PL061_MAX_GPIOS := 160 - $(eval $(call add_define,PLAT_PL061_MAX_GPIOS)) - -If the platform port uses the partition driver, the following constant may -optionally be defined: - -* **PLAT_PARTITION_MAX_ENTRIES** - Maximum number of partition entries required by the platform. This allows - control how much memory is allocated for partition entries. The default - value is 128. - [For example, define the build flag in platform.mk]: - PLAT_PARTITION_MAX_ENTRIES := 12 - $(eval $(call add_define,PLAT_PARTITION_MAX_ENTRIES)) - -The following constant is optional. It should be defined to override the default -behaviour of the `assert()` function (for example, to save memory). - -* **PLAT_LOG_LEVEL_ASSERT** - If `PLAT_LOG_LEVEL_ASSERT` is higher or equal than `LOG_LEVEL_VERBOSE`, - `assert()` prints the name of the file, the line number and the asserted - expression. Else if it is higher than `LOG_LEVEL_INFO`, it prints the file - name and the line number. Else if it is lower than `LOG_LEVEL_INFO`, it - doesn't print anything to the console. If `PLAT_LOG_LEVEL_ASSERT` isn't - defined, it defaults to `LOG_LEVEL`. - - -### File : plat_macros.S [mandatory] - -Each platform must ensure a file of this name is in the system include path with -the following macro defined. In the ARM development platforms, this file is -found in `plat/arm/board/<plat_name>/include/plat_macros.S`. - -* **Macro : plat_crash_print_regs** - - This macro allows the crash reporting routine to print relevant platform - registers in case of an unhandled exception in BL31. This aids in debugging - and this macro can be defined to be empty in case register reporting is not - desired. - - For instance, GIC or interconnect registers may be helpful for - troubleshooting. - - -2.2 Handling Reset ------------------- - -BL1 by default implements the reset vector where execution starts from a cold -or warm boot. BL31 can be optionally set as a reset vector using the -`RESET_TO_BL31` make variable. - -For each CPU, the reset vector code is responsible for the following tasks: - -1. Distinguishing between a cold boot and a warm boot. - -2. In the case of a cold boot and the CPU being a secondary CPU, ensuring that - the CPU is placed in a platform-specific state until the primary CPU - performs the necessary steps to remove it from this state. - -3. In the case of a warm boot, ensuring that the CPU jumps to a platform- - specific address in the BL31 image in the same processor mode as it was - when released from reset. - -The following functions need to be implemented by the platform port to enable -reset vector code to perform the above tasks. - - -### Function : plat_get_my_entrypoint() [mandatory when PROGRAMMABLE_RESET_ADDRESS == 0] - - Argument : void - Return : uintptr_t - -This function is called with the MMU and caches disabled -(`SCTLR_EL3.M` = 0 and `SCTLR_EL3.C` = 0). The function is responsible for -distinguishing between a warm and cold reset for the current CPU using -platform-specific means. If it's a warm reset, then it returns the warm -reset entrypoint point provided to `plat_setup_psci_ops()` during -BL31 initialization. If it's a cold reset then this function must return zero. - -This function does not follow the Procedure Call Standard used by the -Application Binary Interface for the ARM 64-bit architecture. The caller should -not assume that callee saved registers are preserved across a call to this -function. - -This function fulfills requirement 1 and 3 listed above. - -Note that for platforms that support programming the reset address, it is -expected that a CPU will start executing code directly at the right address, -both on a cold and warm reset. In this case, there is no need to identify the -type of reset nor to query the warm reset entrypoint. Therefore, implementing -this function is not required on such platforms. - - -### Function : plat_secondary_cold_boot_setup() [mandatory when COLD_BOOT_SINGLE_CPU == 0] - - Argument : void - -This function is called with the MMU and data caches disabled. It is responsible -for placing the executing secondary CPU in a platform-specific state until the -primary CPU performs the necessary actions to bring it out of that state and -allow entry into the OS. This function must not return. - -In the ARM FVP port, when using the normal boot flow, each secondary CPU powers -itself off. The primary CPU is responsible for powering up the secondary CPUs -when normal world software requires them. When booting an EL3 payload instead, -they stay powered on and are put in a holding pen until their mailbox gets -populated. - -This function fulfills requirement 2 above. - -Note that for platforms that can't release secondary CPUs out of reset, only the -primary CPU will execute the cold boot code. Therefore, implementing this -function is not required on such platforms. - - -### Function : plat_is_my_cpu_primary() [mandatory when COLD_BOOT_SINGLE_CPU == 0] - - Argument : void - Return : unsigned int - -This function identifies whether the current CPU is the primary CPU or a -secondary CPU. A return value of zero indicates that the CPU is not the -primary CPU, while a non-zero return value indicates that the CPU is the -primary CPU. - -Note that for platforms that can't release secondary CPUs out of reset, only the -primary CPU will execute the cold boot code. Therefore, there is no need to -distinguish between primary and secondary CPUs and implementing this function is -not required. - - -### Function : platform_mem_init() [mandatory] - - Argument : void - Return : void - -This function is called before any access to data is made by the firmware, in -order to carry out any essential memory initialization. - - -### Function: plat_get_rotpk_info() - - Argument : void *, void **, unsigned int *, unsigned int * - Return : int - -This function is mandatory when Trusted Board Boot is enabled. It returns a -pointer to the ROTPK stored in the platform (or a hash of it) and its length. -The ROTPK must be encoded in DER format according to the following ASN.1 -structure: - - AlgorithmIdentifier ::= SEQUENCE { - algorithm OBJECT IDENTIFIER, - parameters ANY DEFINED BY algorithm OPTIONAL - } - - SubjectPublicKeyInfo ::= SEQUENCE { - algorithm AlgorithmIdentifier, - subjectPublicKey BIT STRING - } - -In case the function returns a hash of the key: - - DigestInfo ::= SEQUENCE { - digestAlgorithm AlgorithmIdentifier, - digest OCTET STRING - } - -The function returns 0 on success. Any other value is treated as error by the -Trusted Board Boot. The function also reports extra information related -to the ROTPK in the flags parameter: - - ROTPK_IS_HASH : Indicates that the ROTPK returned by the platform is a - hash. - ROTPK_NOT_DEPLOYED : This allows the platform to skip certificate ROTPK - verification while the platform ROTPK is not deployed. - When this flag is set, the function does not need to - return a platform ROTPK, and the authentication - framework uses the ROTPK in the certificate without - verifying it against the platform value. This flag - must not be used in a deployed production environment. - -### Function: plat_get_nv_ctr() - - Argument : void *, unsigned int * - Return : int - -This function is mandatory when Trusted Board Boot is enabled. It returns the -non-volatile counter value stored in the platform in the second argument. The -cookie in the first argument may be used to select the counter in case the -platform provides more than one (for example, on platforms that use the default -TBBR CoT, the cookie will correspond to the OID values defined in -TRUSTED_FW_NVCOUNTER_OID or NON_TRUSTED_FW_NVCOUNTER_OID). - -The function returns 0 on success. Any other value means the counter value could -not be retrieved from the platform. - - -### Function: plat_set_nv_ctr() - - Argument : void *, unsigned int - Return : int - -This function is mandatory when Trusted Board Boot is enabled. It sets a new -counter value in the platform. The cookie in the first argument may be used to -select the counter (as explained in plat_get_nv_ctr()). The second argument is -the updated counter value to be written to the NV counter. - -The function returns 0 on success. Any other value means the counter value could -not be updated. - - -### Function: plat_set_nv_ctr2() - - Argument : void *, const auth_img_desc_t *, unsigned int - Return : int - -This function is optional when Trusted Board Boot is enabled. If this -interface is defined, then `plat_set_nv_ctr()` need not be defined. The -first argument passed is a cookie and is typically used to -differentiate between a Non Trusted NV Counter and a Trusted NV -Counter. The second argument is a pointer to an authentication image -descriptor and may be used to decide if the counter is allowed to be -updated or not. The third argument is the updated counter value to -be written to the NV counter. - -The function returns 0 on success. Any other value means the counter value -either could not be updated or the authentication image descriptor indicates -that it is not allowed to be updated. - - -2.3 Common mandatory function modifications ---------------------------------- - -The following functions are mandatory functions which need to be implemented -by the platform port. - -### Function : plat_my_core_pos() - - Argument : void - Return : unsigned int - -This funtion returns the index of the calling CPU which is used as a -CPU-specific linear index into blocks of memory (for example while allocating -per-CPU stacks). This function will be invoked very early in the -initialization sequence which mandates that this function should be -implemented in assembly and should not rely on the avalability of a C -runtime environment. This function can clobber x0 - x8 and must preserve -x9 - x29. - -This function plays a crucial role in the power domain topology framework in -PSCI and details of this can be found in [Power Domain Topology Design]. - -### Function : plat_core_pos_by_mpidr() - - Argument : u_register_t - Return : int - -This function validates the `MPIDR` of a CPU and converts it to an index, -which can be used as a CPU-specific linear index into blocks of memory. In -case the `MPIDR` is invalid, this function returns -1. This function will only -be invoked by BL31 after the power domain topology is initialized and can -utilize the C runtime environment. For further details about how ARM Trusted -Firmware represents the power domain topology and how this relates to the -linear CPU index, please refer [Power Domain Topology Design]. - - -2.4 Common optional modifications ---------------------------------- - -The following are helper functions implemented by the firmware that perform -common platform-specific tasks. A platform may choose to override these -definitions. - -### Function : plat_set_my_stack() - - Argument : void - Return : void - -This function sets the current stack pointer to the normal memory stack that -has been allocated for the current CPU. For BL images that only require a -stack for the primary CPU, the UP version of the function is used. The size -of the stack allocated to each CPU is specified by the platform defined -constant `PLATFORM_STACK_SIZE`. - -Common implementations of this function for the UP and MP BL images are -provided in [plat/common/aarch64/platform_up_stack.S] and -[plat/common/aarch64/platform_mp_stack.S] - - -### Function : plat_get_my_stack() - - Argument : void - Return : uintptr_t - -This function returns the base address of the normal memory stack that -has been allocated for the current CPU. For BL images that only require a -stack for the primary CPU, the UP version of the function is used. The size -of the stack allocated to each CPU is specified by the platform defined -constant `PLATFORM_STACK_SIZE`. - -Common implementations of this function for the UP and MP BL images are -provided in [plat/common/aarch64/platform_up_stack.S] and -[plat/common/aarch64/platform_mp_stack.S] - - -### Function : plat_report_exception() - - Argument : unsigned int - Return : void - -A platform may need to report various information about its status when an -exception is taken, for example the current exception level, the CPU security -state (secure/non-secure), the exception type, and so on. This function is -called in the following circumstances: - -* In BL1, whenever an exception is taken. -* In BL2, whenever an exception is taken. - -The default implementation doesn't do anything, to avoid making assumptions -about the way the platform displays its status information. - -For AArch64, this function receives the exception type as its argument. -Possible values for exceptions types are listed in the -[include/common/bl_common.h] header file. Note that these constants are not -related to any architectural exception code; they are just an ARM Trusted -Firmware convention. - -For AArch32, this function receives the exception mode as its argument. -Possible values for exception modes are listed in the -[include/lib/aarch32/arch.h] header file. - -### Function : plat_reset_handler() - - Argument : void - Return : void - -A platform may need to do additional initialization after reset. This function -allows the platform to do the platform specific intializations. Platform -specific errata workarounds could also be implemented here. The api should -preserve the values of callee saved registers x19 to x29. - -The default implementation doesn't do anything. If a platform needs to override -the default implementation, refer to the [Firmware Design] for general -guidelines. - -### Function : plat_disable_acp() - - Argument : void - Return : void - -This api allows a platform to disable the Accelerator Coherency Port (if -present) during a cluster power down sequence. The default weak implementation -doesn't do anything. Since this api is called during the power down sequence, -it has restrictions for stack usage and it can use the registers x0 - x17 as -scratch registers. It should preserve the value in x18 register as it is used -by the caller to store the return address. - -### Function : plat_error_handler() - - Argument : int - Return : void - -This API is called when the generic code encounters an error situation from -which it cannot continue. It allows the platform to perform error reporting or -recovery actions (for example, reset the system). This function must not return. - -The parameter indicates the type of error using standard codes from `errno.h`. -Possible errors reported by the generic code are: - -* `-EAUTH`: a certificate or image could not be authenticated (when Trusted - Board Boot is enabled) -* `-ENOENT`: the requested image or certificate could not be found or an IO - error was detected -* `-ENOMEM`: resources exhausted. Trusted Firmware does not use dynamic - memory, so this error is usually an indication of an incorrect array size - -The default implementation simply spins. - -### Function : plat_panic_handler() - - Argument : void - Return : void - -This API is called when the generic code encounters an unexpected error -situation from which it cannot recover. This function must not return, -and must be implemented in assembly because it may be called before the C -environment is initialized. - -Note: The address from where it was called is stored in x30 (Link Register). -The default implementation simply spins. - - -### Function : plat_get_bl_image_load_info() - - Argument : void - Return : bl_load_info_t * - -This function returns pointer to the list of images that the platform has -populated to load. This function is currently invoked in BL2 to load the -BL3xx images, when LOAD_IMAGE_V2 is enabled. - -### Function : plat_get_next_bl_params() - - Argument : void - Return : bl_params_t * - -This function returns a pointer to the shared memory that the platform has -kept aside to pass trusted firmware related information that next BL image -needs. This function is currently invoked in BL2 to pass this information to -the next BL image, when LOAD_IMAGE_V2 is enabled. - -### Function : plat_get_stack_protector_canary() - Argument : void - Return : u_register_t - -This function returns a random value that is used to initialize the canary used -when the stack protector is enabled with ENABLE_STACK_PROTECTOR. A predictable -value will weaken the protection as the attacker could easily write the right -value as part of the attack most of the time. Therefore, it should return a -true random number. - -Note: For the protection to be effective, the global data need to be placed at -a lower address than the stack bases. Failure to do so would allow an attacker -to overwrite the canary as part of the stack buffer overflow attack. - -### Function : plat_flush_next_bl_params() - - Argument : void - Return : void - -This function flushes to main memory all the image params that are passed to -next image. This function is currently invoked in BL2 to flush this information -to the next BL image, when LOAD_IMAGE_V2 is enabled. - -3. Modifications specific to a Boot Loader stage -------------------------------------------------- - -3.1 Boot Loader Stage 1 (BL1) ------------------------------ - -BL1 implements the reset vector where execution starts from after a cold or -warm boot. For each CPU, BL1 is responsible for the following tasks: - -1. Handling the reset as described in section 2.2 - -2. In the case of a cold boot and the CPU being the primary CPU, ensuring that - only this CPU executes the remaining BL1 code, including loading and passing - control to the BL2 stage. - -3. Identifying and starting the Firmware Update process (if required). - -4. Loading the BL2 image from non-volatile storage into secure memory at the - address specified by the platform defined constant `BL2_BASE`. - -5. Populating a `meminfo` structure with the following information in memory, - accessible by BL2 immediately upon entry. - - meminfo.total_base = Base address of secure RAM visible to BL2 - meminfo.total_size = Size of secure RAM visible to BL2 - meminfo.free_base = Base address of secure RAM available for - allocation to BL2 - meminfo.free_size = Size of secure RAM available for allocation to BL2 - - BL1 places this `meminfo` structure at the beginning of the free memory - available for its use. Since BL1 cannot allocate memory dynamically at the - moment, its free memory will be available for BL2's use as-is. However, this - means that BL2 must read the `meminfo` structure before it starts using its - free memory (this is discussed in Section 3.2). - - In future releases of the ARM Trusted Firmware it will be possible for - the platform to decide where it wants to place the `meminfo` structure for - BL2. - - BL1 implements the `bl1_init_bl2_mem_layout()` function to populate the - BL2 `meminfo` structure. The platform may override this implementation, for - example if the platform wants to restrict the amount of memory visible to - BL2. Details of how to do this are given below. - -The following functions need to be implemented by the platform port to enable -BL1 to perform the above tasks. - - -### Function : bl1_early_platform_setup() [mandatory] - - Argument : void - Return : void - -This function executes with the MMU and data caches disabled. It is only called -by the primary CPU. - -On ARM standard platforms, this function: - -* Enables a secure instance of SP805 to act as the Trusted Watchdog. - -* Initializes a UART (PL011 console), which enables access to the `printf` - family of functions in BL1. - -* Enables issuing of snoop and DVM (Distributed Virtual Memory) requests to - the CCI slave interface corresponding to the cluster that includes the - primary CPU. - -### Function : bl1_plat_arch_setup() [mandatory] - - Argument : void - Return : void - -This function performs any platform-specific and architectural setup that the -platform requires. Platform-specific setup might include configuration of -memory controllers and the interconnect. - -In ARM standard platforms, this function enables the MMU. - -This function helps fulfill requirement 2 above. - - -### Function : bl1_platform_setup() [mandatory] - - Argument : void - Return : void - -This function executes with the MMU and data caches enabled. It is responsible -for performing any remaining platform-specific setup that can occur after the -MMU and data cache have been enabled. - -In ARM standard platforms, this function initializes the storage abstraction -layer used to load the next bootloader image. - -This function helps fulfill requirement 4 above. - - -### Function : bl1_plat_sec_mem_layout() [mandatory] - - Argument : void - Return : meminfo * - -This function should only be called on the cold boot path. It executes with the -MMU and data caches enabled. The pointer returned by this function must point to -a `meminfo` structure containing the extents and availability of secure RAM for -the BL1 stage. - - meminfo.total_base = Base address of secure RAM visible to BL1 - meminfo.total_size = Size of secure RAM visible to BL1 - meminfo.free_base = Base address of secure RAM available for allocation - to BL1 - meminfo.free_size = Size of secure RAM available for allocation to BL1 - -This information is used by BL1 to load the BL2 image in secure RAM. BL1 also -populates a similar structure to tell BL2 the extents of memory available for -its own use. - -This function helps fulfill requirements 4 and 5 above. - - -### Function : bl1_init_bl2_mem_layout() [optional] - - Argument : meminfo *, meminfo * - Return : void - -BL1 needs to tell the next stage the amount of secure RAM available -for it to use. This information is populated in a `meminfo` -structure. - -Depending upon where BL2 has been loaded in secure RAM (determined by -`BL2_BASE`), BL1 calculates the amount of free memory available for BL2 to use. -BL1 also ensures that its data sections resident in secure RAM are not visible -to BL2. An illustration of how this is done in ARM standard platforms is given -in the **Memory layout on ARM development platforms** section in the -[Firmware Design]. - - -### Function : bl1_plat_prepare_exit() [optional] - - Argument : entry_point_info_t * - Return : void - -This function is called prior to exiting BL1 in response to the -`BL1_SMC_RUN_IMAGE` SMC request raised by BL2. It should be used to perform -platform specific clean up or bookkeeping operations before transferring -control to the next image. It receives the address of the `entry_point_info_t` -structure passed from BL2. This function runs with MMU disabled. - -### Function : bl1_plat_set_ep_info() [optional] - - Argument : unsigned int image_id, entry_point_info_t *ep_info - Return : void - -This function allows platforms to override `ep_info` for the given `image_id`. - -The default implementation just returns. - -### Function : bl1_plat_get_next_image_id() [optional] - - Argument : void - Return : unsigned int - -This and the following function must be overridden to enable the FWU feature. - -BL1 calls this function after platform setup to identify the next image to be -loaded and executed. If the platform returns `BL2_IMAGE_ID` then BL1 proceeds -with the normal boot sequence, which loads and executes BL2. If the platform -returns a different image id, BL1 assumes that Firmware Update is required. - -The default implementation always returns `BL2_IMAGE_ID`. The ARM development -platforms override this function to detect if firmware update is required, and -if so, return the first image in the firmware update process. - -### Function : bl1_plat_get_image_desc() [optional] - - Argument : unsigned int image_id - Return : image_desc_t * - -BL1 calls this function to get the image descriptor information `image_desc_t` -for the provided `image_id` from the platform. - -The default implementation always returns a common BL2 image descriptor. ARM -standard platforms return an image descriptor corresponding to BL2 or one of -the firmware update images defined in the Trusted Board Boot Requirements -specification. - -### Function : bl1_plat_fwu_done() [optional] - - Argument : unsigned int image_id, uintptr_t image_src, - unsigned int image_size - Return : void - -BL1 calls this function when the FWU process is complete. It must not return. -The platform may override this function to take platform specific action, for -example to initiate the normal boot flow. - -The default implementation spins forever. - -### Function : bl1_plat_mem_check() [mandatory] - - Argument : uintptr_t mem_base, unsigned int mem_size, - unsigned int flags - Return : int - -BL1 calls this function while handling FWU related SMCs, more specifically when -copying or authenticating an image. Its responsibility is to ensure that the -region of memory identified by `mem_base` and `mem_size` is mapped in BL1, and -that this memory corresponds to either a secure or non-secure memory region as -indicated by the security state of the `flags` argument. - -This function can safely assume that the value resulting from the addition of -`mem_base` and `mem_size` fits into a `uintptr_t` type variable and does not -overflow. - -This function must return 0 on success, a non-null error code otherwise. - -The default implementation of this function asserts therefore platforms must -override it when using the FWU feature. - - -3.2 Boot Loader Stage 2 (BL2) ------------------------------ - -The BL2 stage is executed only by the primary CPU, which is determined in BL1 -using the `platform_is_primary_cpu()` function. BL1 passed control to BL2 at -`BL2_BASE`. BL2 executes in Secure EL1 and is responsible for: - -1. (Optional) Loading the SCP_BL2 binary image (if present) from platform - provided non-volatile storage. To load the SCP_BL2 image, BL2 makes use of - the `meminfo` returned by the `bl2_plat_get_scp_bl2_meminfo()` function. - The platform also defines the address in memory where SCP_BL2 is loaded - through the optional constant `SCP_BL2_BASE`. BL2 uses this information - to determine if there is enough memory to load the SCP_BL2 image. - Subsequent handling of the SCP_BL2 image is platform-specific and is - implemented in the `bl2_plat_handle_scp_bl2()` function. - If `SCP_BL2_BASE` is not defined then this step is not performed. - -2. Loading the BL31 binary image into secure RAM from non-volatile storage. To - load the BL31 image, BL2 makes use of the `meminfo` structure passed to it - by BL1. This structure allows BL2 to calculate how much secure RAM is - available for its use. The platform also defines the address in secure RAM - where BL31 is loaded through the constant `BL31_BASE`. BL2 uses this - information to determine if there is enough memory to load the BL31 image. - -3. (Optional) Loading the BL32 binary image (if present) from platform - provided non-volatile storage. To load the BL32 image, BL2 makes use of - the `meminfo` returned by the `bl2_plat_get_bl32_meminfo()` function. - The platform also defines the address in memory where BL32 is loaded - through the optional constant `BL32_BASE`. BL2 uses this information - to determine if there is enough memory to load the BL32 image. - If `BL32_BASE` is not defined then this and the next step is not performed. - -4. (Optional) Arranging to pass control to the BL32 image (if present) that - has been pre-loaded at `BL32_BASE`. BL2 populates an `entry_point_info` - structure in memory provided by the platform with information about how - BL31 should pass control to the BL32 image. - -5. (Optional) Loading the normal world BL33 binary image (if not loaded by - other means) into non-secure DRAM from platform storage and arranging for - BL31 to pass control to this image. This address is determined using the - `plat_get_ns_image_entrypoint()` function described below. - -6. BL2 populates an `entry_point_info` structure in memory provided by the - platform with information about how BL31 should pass control to the - other BL images. - -The following functions must be implemented by the platform port to enable BL2 -to perform the above tasks. - - -### Function : bl2_early_platform_setup() [mandatory] - - Argument : meminfo * - Return : void - -This function executes with the MMU and data caches disabled. It is only called -by the primary CPU. The arguments to this function is the address of the -`meminfo` structure populated by BL1. - -The platform may copy the contents of the `meminfo` structure into a private -variable as the original memory may be subsequently overwritten by BL2. The -copied structure is made available to all BL2 code through the -`bl2_plat_sec_mem_layout()` function. - -On ARM standard platforms, this function also: - -* Initializes a UART (PL011 console), which enables access to the `printf` - family of functions in BL2. - -* Initializes the storage abstraction layer used to load further bootloader - images. It is necessary to do this early on platforms with a SCP_BL2 image, - since the later `bl2_platform_setup` must be done after SCP_BL2 is loaded. - - -### Function : bl2_plat_arch_setup() [mandatory] - - Argument : void - Return : void - -This function executes with the MMU and data caches disabled. It is only called -by the primary CPU. - -The purpose of this function is to perform any architectural initialization -that varies across platforms. - -On ARM standard platforms, this function enables the MMU. - -### Function : bl2_platform_setup() [mandatory] - - Argument : void - Return : void - -This function may execute with the MMU and data caches enabled if the platform -port does the necessary initialization in `bl2_plat_arch_setup()`. It is only -called by the primary CPU. - -The purpose of this function is to perform any platform initialization -specific to BL2. - -In ARM standard platforms, this function performs security setup, including -configuration of the TrustZone controller to allow non-secure masters access -to most of DRAM. Part of DRAM is reserved for secure world use. - - -### Function : bl2_plat_sec_mem_layout() [mandatory] - - Argument : void - Return : meminfo * - -This function should only be called on the cold boot path. It may execute with -the MMU and data caches enabled if the platform port does the necessary -initialization in `bl2_plat_arch_setup()`. It is only called by the primary CPU. - -The purpose of this function is to return a pointer to a `meminfo` structure -populated with the extents of secure RAM available for BL2 to use. See -`bl2_early_platform_setup()` above. - - -Following function is required only when LOAD_IMAGE_V2 is enabled. - -### Function : bl2_plat_handle_post_image_load() [mandatory] - - Argument : unsigned int - Return : int - -This function can be used by the platforms to update/use image information -for given `image_id`. This function is currently invoked in BL2 to handle -BL image specific information based on the `image_id` passed, when -LOAD_IMAGE_V2 is enabled. - -Following functions are required only when LOAD_IMAGE_V2 is disabled. - -### Function : bl2_plat_get_scp_bl2_meminfo() [mandatory] - - Argument : meminfo * - Return : void - -This function is used to get the memory limits where BL2 can load the -SCP_BL2 image. The meminfo provided by this is used by load_image() to -validate whether the SCP_BL2 image can be loaded within the given -memory from the given base. - - -### Function : bl2_plat_handle_scp_bl2() [mandatory] - - Argument : image_info * - Return : int - -This function is called after loading SCP_BL2 image and it is used to perform -any platform-specific actions required to handle the SCP firmware. Typically it -transfers the image into SCP memory using a platform-specific protocol and waits -until SCP executes it and signals to the Application Processor (AP) for BL2 -execution to continue. - -This function returns 0 on success, a negative error code otherwise. - - -### Function : bl2_plat_get_bl31_params() [mandatory] - - Argument : void - Return : bl31_params * - -BL2 platform code needs to return a pointer to a `bl31_params` structure it -will use for passing information to BL31. The `bl31_params` structure carries -the following information. - - Header describing the version information for interpreting the bl31_param - structure - - Information about executing the BL33 image in the `bl33_ep_info` field - - Information about executing the BL32 image in the `bl32_ep_info` field - - Information about the type and extents of BL31 image in the - `bl31_image_info` field - - Information about the type and extents of BL32 image in the - `bl32_image_info` field - - Information about the type and extents of BL33 image in the - `bl33_image_info` field - -The memory pointed by this structure and its sub-structures should be -accessible from BL31 initialisation code. BL31 might choose to copy the -necessary content, or maintain the structures until BL33 is initialised. - - -### Funtion : bl2_plat_get_bl31_ep_info() [mandatory] - - Argument : void - Return : entry_point_info * - -BL2 platform code returns a pointer which is used to populate the entry point -information for BL31 entry point. The location pointed by it should be -accessible from BL1 while processing the synchronous exception to run to BL31. - -In ARM standard platforms this is allocated inside a bl2_to_bl31_params_mem -structure in BL2 memory. - - -### Function : bl2_plat_set_bl31_ep_info() [mandatory] - - Argument : image_info *, entry_point_info * - Return : void - -In the normal boot flow, this function is called after loading BL31 image and -it can be used to overwrite the entry point set by loader and also set the -security state and SPSR which represents the entry point system state for BL31. - -When booting an EL3 payload instead, this function is called after populating -its entry point address and can be used for the same purpose for the payload -image. It receives a null pointer as its first argument in this case. - -### Function : bl2_plat_set_bl32_ep_info() [mandatory] - - Argument : image_info *, entry_point_info * - Return : void - -This function is called after loading BL32 image and it can be used to -overwrite the entry point set by loader and also set the security state -and SPSR which represents the entry point system state for BL32. - - -### Function : bl2_plat_set_bl33_ep_info() [mandatory] - - Argument : image_info *, entry_point_info * - Return : void - -This function is called after loading BL33 image and it can be used to -overwrite the entry point set by loader and also set the security state -and SPSR which represents the entry point system state for BL33. - -In the preloaded BL33 alternative boot flow, this function is called after -populating its entry point address. It is passed a null pointer as its first -argument in this case. - - -### Function : bl2_plat_get_bl32_meminfo() [mandatory] - - Argument : meminfo * - Return : void - -This function is used to get the memory limits where BL2 can load the -BL32 image. The meminfo provided by this is used by load_image() to -validate whether the BL32 image can be loaded with in the given -memory from the given base. - -### Function : bl2_plat_get_bl33_meminfo() [mandatory] - - Argument : meminfo * - Return : void - -This function is used to get the memory limits where BL2 can load the -BL33 image. The meminfo provided by this is used by load_image() to -validate whether the BL33 image can be loaded with in the given -memory from the given base. - -This function isn't needed if either `PRELOADED_BL33_BASE` or `EL3_PAYLOAD_BASE` -build options are used. - -### Function : bl2_plat_flush_bl31_params() [mandatory] - - Argument : void - Return : void - -Once BL2 has populated all the structures that needs to be read by BL1 -and BL31 including the bl31_params structures and its sub-structures, -the bl31_ep_info structure and any platform specific data. It flushes -all these data to the main memory so that it is available when we jump to -later Bootloader stages with MMU off - -### Function : plat_get_ns_image_entrypoint() [mandatory] - - Argument : void - Return : uintptr_t - -As previously described, BL2 is responsible for arranging for control to be -passed to a normal world BL image through BL31. This function returns the -entrypoint of that image, which BL31 uses to jump to it. - -BL2 is responsible for loading the normal world BL33 image (e.g. UEFI). - -This function isn't needed if either `PRELOADED_BL33_BASE` or `EL3_PAYLOAD_BASE` -build options are used. - - -3.3 FWU Boot Loader Stage 2 (BL2U) ----------------------------------- - -The AP Firmware Updater Configuration, BL2U, is an optional part of the FWU -process and is executed only by the primary CPU. BL1 passes control to BL2U at -`BL2U_BASE`. BL2U executes in Secure-EL1 and is responsible for: - -1. (Optional) Transfering the optional SCP_BL2U binary image from AP secure - memory to SCP RAM. BL2U uses the SCP_BL2U `image_info` passed by BL1. - `SCP_BL2U_BASE` defines the address in AP secure memory where SCP_BL2U - should be copied from. Subsequent handling of the SCP_BL2U image is - implemented by the platform specific `bl2u_plat_handle_scp_bl2u()` function. - If `SCP_BL2U_BASE` is not defined then this step is not performed. - -2. Any platform specific setup required to perform the FWU process. For - example, ARM standard platforms initialize the TZC controller so that the - normal world can access DDR memory. - -The following functions must be implemented by the platform port to enable -BL2U to perform the tasks mentioned above. - -### Function : bl2u_early_platform_setup() [mandatory] - - Argument : meminfo *mem_info, void *plat_info - Return : void - -This function executes with the MMU and data caches disabled. It is only -called by the primary CPU. The arguments to this function is the address -of the `meminfo` structure and platform specific info provided by BL1. - -The platform may copy the contents of the `mem_info` and `plat_info` into -private storage as the original memory may be subsequently overwritten by BL2U. - -On ARM CSS platforms `plat_info` is interpreted as an `image_info_t` structure, -to extract SCP_BL2U image information, which is then copied into a private -variable. - -### Function : bl2u_plat_arch_setup() [mandatory] - - Argument : void - Return : void - -This function executes with the MMU and data caches disabled. It is only -called by the primary CPU. - -The purpose of this function is to perform any architectural initialization -that varies across platforms, for example enabling the MMU (since the memory -map differs across platforms). - -### Function : bl2u_platform_setup() [mandatory] - - Argument : void - Return : void - -This function may execute with the MMU and data caches enabled if the platform -port does the necessary initialization in `bl2u_plat_arch_setup()`. It is only -called by the primary CPU. - -The purpose of this function is to perform any platform initialization -specific to BL2U. - -In ARM standard platforms, this function performs security setup, including -configuration of the TrustZone controller to allow non-secure masters access -to most of DRAM. Part of DRAM is reserved for secure world use. - -### Function : bl2u_plat_handle_scp_bl2u() [optional] - - Argument : void - Return : int - -This function is used to perform any platform-specific actions required to -handle the SCP firmware. Typically it transfers the image into SCP memory using -a platform-specific protocol and waits until SCP executes it and signals to the -Application Processor (AP) for BL2U execution to continue. - -This function returns 0 on success, a negative error code otherwise. -This function is included if SCP_BL2U_BASE is defined. - - -3.4 Boot Loader Stage 3-1 (BL31) ---------------------------------- - -During cold boot, the BL31 stage is executed only by the primary CPU. This is -determined in BL1 using the `platform_is_primary_cpu()` function. BL1 passes -control to BL31 at `BL31_BASE`. During warm boot, BL31 is executed by all -CPUs. BL31 executes at EL3 and is responsible for: - -1. Re-initializing all architectural and platform state. Although BL1 performs - some of this initialization, BL31 remains resident in EL3 and must ensure - that EL3 architectural and platform state is completely initialized. It - should make no assumptions about the system state when it receives control. - -2. Passing control to a normal world BL image, pre-loaded at a platform- - specific address by BL2. BL31 uses the `entry_point_info` structure that BL2 - populated in memory to do this. - -3. Providing runtime firmware services. Currently, BL31 only implements a - subset of the Power State Coordination Interface (PSCI) API as a runtime - service. See Section 3.3 below for details of porting the PSCI - implementation. - -4. Optionally passing control to the BL32 image, pre-loaded at a platform- - specific address by BL2. BL31 exports a set of apis that allow runtime - services to specify the security state in which the next image should be - executed and run the corresponding image. BL31 uses the `entry_point_info` - structure populated by BL2 to do this. - -If BL31 is a reset vector, It also needs to handle the reset as specified in -section 2.2 before the tasks described above. - -The following functions must be implemented by the platform port to enable BL31 -to perform the above tasks. - - -### Function : bl31_early_platform_setup() [mandatory] - - Argument : bl31_params *, void * - Return : void - -This function executes with the MMU and data caches disabled. It is only called -by the primary CPU. The arguments to this function are: - -* The address of the `bl31_params` structure populated by BL2. -* An opaque pointer that the platform may use as needed. - -The platform can copy the contents of the `bl31_params` structure and its -sub-structures into private variables if the original memory may be -subsequently overwritten by BL31 and similarly the `void *` pointing -to the platform data also needs to be saved. - -In ARM standard platforms, BL2 passes a pointer to a `bl31_params` structure -in BL2 memory. BL31 copies the information in this pointer to internal data -structures. It also performs the following: - -* Initialize a UART (PL011 console), which enables access to the `printf` - family of functions in BL31. - -* Enable issuing of snoop and DVM (Distributed Virtual Memory) requests to the - CCI slave interface corresponding to the cluster that includes the primary - CPU. - - -### Function : bl31_plat_arch_setup() [mandatory] - - Argument : void - Return : void - -This function executes with the MMU and data caches disabled. It is only called -by the primary CPU. - -The purpose of this function is to perform any architectural initialization -that varies across platforms. - -On ARM standard platforms, this function enables the MMU. - - -### Function : bl31_platform_setup() [mandatory] - - Argument : void - Return : void - -This function may execute with the MMU and data caches enabled if the platform -port does the necessary initialization in `bl31_plat_arch_setup()`. It is only -called by the primary CPU. - -The purpose of this function is to complete platform initialization so that both -BL31 runtime services and normal world software can function correctly. - -On ARM standard platforms, this function does the following: - -* Initialize the generic interrupt controller. - - Depending on the GIC driver selected by the platform, the appropriate GICv2 - or GICv3 initialization will be done, which mainly consists of: - - - Enable secure interrupts in the GIC CPU interface. - - Disable the legacy interrupt bypass mechanism. - - Configure the priority mask register to allow interrupts of all priorities - to be signaled to the CPU interface. - - Mark SGIs 8-15 and the other secure interrupts on the platform as secure. - - Target all secure SPIs to CPU0. - - Enable these secure interrupts in the GIC distributor. - - Configure all other interrupts as non-secure. - - Enable signaling of secure interrupts in the GIC distributor. - -* Enable system-level implementation of the generic timer counter through the - memory mapped interface. - -* Grant access to the system counter timer module - -* Initialize the power controller device. - - In particular, initialise the locks that prevent concurrent accesses to the - power controller device. - - -### Function : bl31_plat_runtime_setup() [optional] - - Argument : void - Return : void - -The purpose of this function is allow the platform to perform any BL31 runtime -setup just prior to BL31 exit during cold boot. The default weak -implementation of this function will invoke `console_uninit()` which will -suppress any BL31 runtime logs. - -In ARM Standard platforms, this function will initialize the BL31 runtime -console which will cause all further BL31 logs to be output to the -runtime console. - - -### Function : bl31_get_next_image_info() [mandatory] - - Argument : unsigned int - Return : entry_point_info * - -This function may execute with the MMU and data caches enabled if the platform -port does the necessary initializations in `bl31_plat_arch_setup()`. - -This function is called by `bl31_main()` to retrieve information provided by -BL2 for the next image in the security state specified by the argument. BL31 -uses this information to pass control to that image in the specified security -state. This function must return a pointer to the `entry_point_info` structure -(that was copied during `bl31_early_platform_setup()`) if the image exists. It -should return NULL otherwise. - -### Function : plat_get_syscnt_freq2() [mandatory] - - Argument : void - Return : unsigned int - -This function is used by the architecture setup code to retrieve the counter -frequency for the CPU's generic timer. This value will be programmed into the -`CNTFRQ_EL0` register. In ARM standard platforms, it returns the base frequency -of the system counter, which is retrieved from the first entry in the frequency -modes table. - - -### #define : PLAT_PERCPU_BAKERY_LOCK_SIZE [optional] - - When `USE_COHERENT_MEM = 0`, this constant defines the total memory (in - bytes) aligned to the cache line boundary that should be allocated per-cpu to - accommodate all the bakery locks. - - If this constant is not defined when `USE_COHERENT_MEM = 0`, the linker - calculates the size of the `bakery_lock` input section, aligns it to the - nearest `CACHE_WRITEBACK_GRANULE`, multiplies it with `PLATFORM_CORE_COUNT` - and stores the result in a linker symbol. This constant prevents a platform - from relying on the linker and provide a more efficient mechanism for - accessing per-cpu bakery lock information. - - If this constant is defined and its value is not equal to the value - calculated by the linker then a link time assertion is raised. A compile time - assertion is raised if the value of the constant is not aligned to the cache - line boundary. - -3.5 Power State Coordination Interface (in BL31) ------------------------------------------------- - -The ARM Trusted Firmware's implementation of the PSCI API is based around the -concept of a _power domain_. A _power domain_ is a CPU or a logical group of -CPUs which share some state on which power management operations can be -performed as specified by [PSCI]. Each CPU in the system is assigned a cpu -index which is a unique number between `0` and `PLATFORM_CORE_COUNT - 1`. -The _power domains_ are arranged in a hierarchical tree structure and -each _power domain_ can be identified in a system by the cpu index of any CPU -that is part of that domain and a _power domain level_. A processing element -(for example, a CPU) is at level 0. If the _power domain_ node above a CPU is -a logical grouping of CPUs that share some state, then level 1 is that group -of CPUs (for example, a cluster), and level 2 is a group of clusters -(for example, the system). More details on the power domain topology and its -organization can be found in [Power Domain Topology Design]. - -BL31's platform initialization code exports a pointer to the platform-specific -power management operations required for the PSCI implementation to function -correctly. This information is populated in the `plat_psci_ops` structure. The -PSCI implementation calls members of the `plat_psci_ops` structure for performing -power management operations on the power domains. For example, the target -CPU is specified by its `MPIDR` in a PSCI `CPU_ON` call. The `pwr_domain_on()` -handler (if present) is called for the CPU power domain. - -The `power-state` parameter of a PSCI `CPU_SUSPEND` call can be used to -describe composite power states specific to a platform. The PSCI implementation -defines a generic representation of the power-state parameter viz which is an -array of local power states where each index corresponds to a power domain -level. Each entry contains the local power state the power domain at that power -level could enter. It depends on the `validate_power_state()` handler to -convert the power-state parameter (possibly encoding a composite power state) -passed in a PSCI `CPU_SUSPEND` call to this representation. - -The following functions form part of platform port of PSCI functionality. - - -### Function : plat_psci_stat_accounting_start() [optional] - - Argument : const psci_power_state_t * - Return : void - -This is an optional hook that platforms can implement for residency statistics -accounting before entering a low power state. The `pwr_domain_state` field of -`state_info` (first argument) can be inspected if stat accounting is done -differently at CPU level versus higher levels. As an example, if the element at -index 0 (CPU power level) in the `pwr_domain_state` array indicates a power down -state, special hardware logic may be programmed in order to keep track of the -residency statistics. For higher levels (array indices > 0), the residency -statistics could be tracked in software using PMF. If `ENABLE_PMF` is set, the -default implementation will use PMF to capture timestamps. - -### Function : plat_psci_stat_accounting_stop() [optional] - - Argument : const psci_power_state_t * - Return : void - -This is an optional hook that platforms can implement for residency statistics -accounting after exiting from a low power state. The `pwr_domain_state` field -of `state_info` (first argument) can be inspected if stat accounting is done -differently at CPU level versus higher levels. As an example, if the element at -index 0 (CPU power level) in the `pwr_domain_state` array indicates a power down -state, special hardware logic may be programmed in order to keep track of the -residency statistics. For higher levels (array indices > 0), the residency -statistics could be tracked in software using PMF. If `ENABLE_PMF` is set, the -default implementation will use PMF to capture timestamps. - -### Function : plat_psci_stat_get_residency() [optional] - - Argument : unsigned int, const psci_power_state_t *, int - Return : u_register_t - -This is an optional interface that is is invoked after resuming from a low power -state and provides the time spent resident in that low power state by the power -domain at a particular power domain level. When a CPU wakes up from suspend, -all its parent power domain levels are also woken up. The generic PSCI code -invokes this function for each parent power domain that is resumed and it -identified by the `lvl` (first argument) parameter. The `state_info` (second -argument) describes the low power state that the power domain has resumed from. -The current CPU is the first CPU in the power domain to resume from the low -power state and the `last_cpu_idx` (third parameter) is the index of the last -CPU in the power domain to suspend and may be needed to calculate the residency -for that power domain. - -### Function : plat_get_target_pwr_state() [optional] - - Argument : unsigned int, const plat_local_state_t *, unsigned int - Return : plat_local_state_t - -The PSCI generic code uses this function to let the platform participate in -state coordination during a power management operation. The function is passed -a pointer to an array of platform specific local power state `states` (second -argument) which contains the requested power state for each CPU at a particular -power domain level `lvl` (first argument) within the power domain. The function -is expected to traverse this array of upto `ncpus` (third argument) and return -a coordinated target power state by the comparing all the requested power -states. The target power state should not be deeper than any of the requested -power states. - -A weak definition of this API is provided by default wherein it assumes -that the platform assigns a local state value in order of increasing depth -of the power state i.e. for two power states X & Y, if X < Y -then X represents a shallower power state than Y. As a result, the -coordinated target local power state for a power domain will be the minimum -of the requested local power state values. - - -### Function : plat_get_power_domain_tree_desc() [mandatory] - - Argument : void - Return : const unsigned char * - -This function returns a pointer to the byte array containing the power domain -topology tree description. The format and method to construct this array are -described in [Power Domain Topology Design]. The BL31 PSCI initilization code -requires this array to be described by the platform, either statically or -dynamically, to initialize the power domain topology tree. In case the array -is populated dynamically, then plat_core_pos_by_mpidr() and -plat_my_core_pos() should also be implemented suitably so that the topology -tree description matches the CPU indices returned by these APIs. These APIs -together form the platform interface for the PSCI topology framework. - - -## Function : plat_setup_psci_ops() [mandatory] - - Argument : uintptr_t, const plat_psci_ops ** - Return : int - -This function may execute with the MMU and data caches enabled if the platform -port does the necessary initializations in `bl31_plat_arch_setup()`. It is only -called by the primary CPU. - -This function is called by PSCI initialization code. Its purpose is to let -the platform layer know about the warm boot entrypoint through the -`sec_entrypoint` (first argument) and to export handler routines for -platform-specific psci power management actions by populating the passed -pointer with a pointer to BL31's private `plat_psci_ops` structure. - -A description of each member of this structure is given below. Please refer to -the ARM FVP specific implementation of these handlers in -[plat/arm/board/fvp/fvp_pm.c] as an example. For each PSCI function that the -platform wants to support, the associated operation or operations in this -structure must be provided and implemented (Refer section 4 of -[Firmware Design] for the PSCI API supported in Trusted Firmware). To disable -a PSCI function in a platform port, the operation should be removed from this -structure instead of providing an empty implementation. - -#### plat_psci_ops.cpu_standby() - -Perform the platform-specific actions to enter the standby state for a cpu -indicated by the passed argument. This provides a fast path for CPU standby -wherein overheads of PSCI state management and lock acquistion is avoided. -For this handler to be invoked by the PSCI `CPU_SUSPEND` API implementation, -the suspend state type specified in the `power-state` parameter should be -STANDBY and the target power domain level specified should be the CPU. The -handler should put the CPU into a low power retention state (usually by -issuing a wfi instruction) and ensure that it can be woken up from that -state by a normal interrupt. The generic code expects the handler to succeed. - -#### plat_psci_ops.pwr_domain_on() - -Perform the platform specific actions to power on a CPU, specified -by the `MPIDR` (first argument). The generic code expects the platform to -return PSCI_E_SUCCESS on success or PSCI_E_INTERN_FAIL for any failure. - -#### plat_psci_ops.pwr_domain_off() - -Perform the platform specific actions to prepare to power off the calling CPU -and its higher parent power domain levels as indicated by the `target_state` -(first argument). It is called by the PSCI `CPU_OFF` API implementation. - -The `target_state` encodes the platform coordinated target local power states -for the CPU power domain and its parent power domain levels. The handler -needs to perform power management operation corresponding to the local state -at each power level. - -For this handler, the local power state for the CPU power domain will be a -power down state where as it could be either power down, retention or run state -for the higher power domain levels depending on the result of state -coordination. The generic code expects the handler to succeed. - -#### plat_psci_ops.pwr_domain_suspend() - -Perform the platform specific actions to prepare to suspend the calling -CPU and its higher parent power domain levels as indicated by the -`target_state` (first argument). It is called by the PSCI `CPU_SUSPEND` -API implementation. - -The `target_state` has a similar meaning as described in -the `pwr_domain_off()` operation. It encodes the platform coordinated -target local power states for the CPU power domain and its parent -power domain levels. The handler needs to perform power management operation -corresponding to the local state at each power level. The generic code -expects the handler to succeed. - -The difference between turning a power domain off versus suspending it -is that in the former case, the power domain is expected to re-initialize -its state when it is next powered on (see `pwr_domain_on_finish()`). In the -latter case, the power domain is expected to save enough state so that it can -resume execution by restoring this state when its powered on (see -`pwr_domain_suspend_finish()`). - -#### plat_psci_ops.pwr_domain_pwr_down_wfi() - -This is an optional function and, if implemented, is expected to perform -platform specific actions including the `wfi` invocation which allows the -CPU to powerdown. Since this function is invoked outside the PSCI locks, -the actions performed in this hook must be local to the CPU or the platform -must ensure that races between multiple CPUs cannot occur. - -The `target_state` has a similar meaning as described in the `pwr_domain_off()` -operation and it encodes the platform coordinated target local power states for -the CPU power domain and its parent power domain levels. This function must -not return back to the caller. - -If this function is not implemented by the platform, PSCI generic -implementation invokes `psci_power_down_wfi()` for power down. - -#### plat_psci_ops.pwr_domain_on_finish() - -This function is called by the PSCI implementation after the calling CPU is -powered on and released from reset in response to an earlier PSCI `CPU_ON` call. -It performs the platform-specific setup required to initialize enough state for -this CPU to enter the normal world and also provide secure runtime firmware -services. - -The `target_state` (first argument) is the prior state of the power domains -immediately before the CPU was turned on. It indicates which power domains -above the CPU might require initialization due to having previously been in -low power states. The generic code expects the handler to succeed. - -#### plat_psci_ops.pwr_domain_suspend_finish() - -This function is called by the PSCI implementation after the calling CPU is -powered on and released from reset in response to an asynchronous wakeup -event, for example a timer interrupt that was programmed by the CPU during the -`CPU_SUSPEND` call or `SYSTEM_SUSPEND` call. It performs the platform-specific -setup required to restore the saved state for this CPU to resume execution -in the normal world and also provide secure runtime firmware services. - -The `target_state` (first argument) has a similar meaning as described in -the `pwr_domain_on_finish()` operation. The generic code expects the platform -to succeed. - -#### plat_psci_ops.system_off() - -This function is called by PSCI implementation in response to a `SYSTEM_OFF` -call. It performs the platform-specific system poweroff sequence after -notifying the Secure Payload Dispatcher. - -#### plat_psci_ops.system_reset() - -This function is called by PSCI implementation in response to a `SYSTEM_RESET` -call. It performs the platform-specific system reset sequence after -notifying the Secure Payload Dispatcher. - -#### plat_psci_ops.validate_power_state() - -This function is called by the PSCI implementation during the `CPU_SUSPEND` -call to validate the `power_state` parameter of the PSCI API and if valid, -populate it in `req_state` (second argument) array as power domain level -specific local states. If the `power_state` is invalid, the platform must -return PSCI_E_INVALID_PARAMS as error, which is propagated back to the -normal world PSCI client. - -#### plat_psci_ops.validate_ns_entrypoint() - -This function is called by the PSCI implementation during the `CPU_SUSPEND`, -`SYSTEM_SUSPEND` and `CPU_ON` calls to validate the non-secure `entry_point` -parameter passed by the normal world. If the `entry_point` is invalid, -the platform must return PSCI_E_INVALID_ADDRESS as error, which is -propagated back to the normal world PSCI client. - -#### plat_psci_ops.get_sys_suspend_power_state() - -This function is called by the PSCI implementation during the `SYSTEM_SUSPEND` -call to get the `req_state` parameter from platform which encodes the power -domain level specific local states to suspend to system affinity level. The -`req_state` will be utilized to do the PSCI state coordination and -`pwr_domain_suspend()` will be invoked with the coordinated target state to -enter system suspend. - -#### plat_psci_ops.get_pwr_lvl_state_idx() - -This is an optional function and, if implemented, is invoked by the PSCI -implementation to convert the `local_state` (first argument) at a specified -`pwr_lvl` (second argument) to an index between 0 and -`PLAT_MAX_PWR_LVL_STATES` - 1. This function is only needed if the platform -supports more than two local power states at each power domain level, that is -`PLAT_MAX_PWR_LVL_STATES` is greater than 2, and needs to account for these -local power states. - -#### plat_psci_ops.translate_power_state_by_mpidr() - -This is an optional function and, if implemented, verifies the `power_state` -(second argument) parameter of the PSCI API corresponding to a target power -domain. The target power domain is identified by using both `MPIDR` (first -argument) and the power domain level encoded in `power_state`. The power domain -level specific local states are to be extracted from `power_state` and be -populated in the `output_state` (third argument) array. The functionality -is similar to the `validate_power_state` function described above and is -envisaged to be used in case the validity of `power_state` depend on the -targeted power domain. If the `power_state` is invalid for the targeted power -domain, the platform must return PSCI_E_INVALID_PARAMS as error. If this -function is not implemented, then the generic implementation relies on -`validate_power_state` function to translate the `power_state`. - -This function can also be used in case the platform wants to support local -power state encoding for `power_state` parameter of PSCI_STAT_COUNT/RESIDENCY -APIs as described in Section 5.18 of [PSCI]. - -#### plat_psci_ops.get_node_hw_state() - -This is an optional function. If implemented this function is intended to return -the power state of a node (identified by the first parameter, the `MPIDR`) in -the power domain topology (identified by the second parameter, `power_level`), -as retrieved from a power controller or equivalent component on the platform. -Upon successful completion, the implementation must map and return the final -status among `HW_ON`, `HW_OFF` or `HW_STANDBY`. Upon encountering failures, it -must return either `PSCI_E_INVALID_PARAMS` or `PSCI_E_NOT_SUPPORTED` as -appropriate. - -Implementations are not expected to handle `power_levels` greater than -`PLAT_MAX_PWR_LVL`. - -3.6 Interrupt Management framework (in BL31) ----------------------------------------------- -BL31 implements an Interrupt Management Framework (IMF) to manage interrupts -generated in either security state and targeted to EL1 or EL2 in the non-secure -state or EL3/S-EL1 in the secure state. The design of this framework is -described in the [IMF Design Guide] - -A platform should export the following APIs to support the IMF. The following -text briefly describes each api and its implementation in ARM standard -platforms. The API implementation depends upon the type of interrupt controller -present in the platform. ARM standard platform layer supports both [ARM Generic -Interrupt Controller version 2.0 (GICv2)][ARM GIC Architecture Specification 2.0] -and [3.0 (GICv3)][ARM GIC Architecture Specification 3.0]. Juno builds the ARM -Standard layer to use GICv2 and the FVP can be configured to use either GICv2 or -GICv3 depending on the build flag `FVP_USE_GIC_DRIVER` (See FVP platform -specific build options in [User Guide] for more details). - -### Function : plat_interrupt_type_to_line() [mandatory] - - Argument : uint32_t, uint32_t - Return : uint32_t - -The ARM processor signals an interrupt exception either through the IRQ or FIQ -interrupt line. The specific line that is signaled depends on how the interrupt -controller (IC) reports different interrupt types from an execution context in -either security state. The IMF uses this API to determine which interrupt line -the platform IC uses to signal each type of interrupt supported by the framework -from a given security state. This API must be invoked at EL3. - -The first parameter will be one of the `INTR_TYPE_*` values (see [IMF Design -Guide]) indicating the target type of the interrupt, the second parameter is the -security state of the originating execution context. The return result is the -bit position in the `SCR_EL3` register of the respective interrupt trap: IRQ=1, -FIQ=2. - -In the case of ARM standard platforms using GICv2, S-EL1 interrupts are -configured as FIQs and Non-secure interrupts as IRQs from either security -state. - -In the case of ARM standard platforms using GICv3, the interrupt line to be -configured depends on the security state of the execution context when the -interrupt is signalled and are as follows: -* The S-EL1 interrupts are signaled as IRQ in S-EL0/1 context and as FIQ in - NS-EL0/1/2 context. -* The Non secure interrupts are signaled as FIQ in S-EL0/1 context and as IRQ - in the NS-EL0/1/2 context. -* The EL3 interrupts are signaled as FIQ in both S-EL0/1 and NS-EL0/1/2 - context. - - -### Function : plat_ic_get_pending_interrupt_type() [mandatory] - - Argument : void - Return : uint32_t - -This API returns the type of the highest priority pending interrupt at the -platform IC. The IMF uses the interrupt type to retrieve the corresponding -handler function. `INTR_TYPE_INVAL` is returned when there is no interrupt -pending. The valid interrupt types that can be returned are `INTR_TYPE_EL3`, -`INTR_TYPE_S_EL1` and `INTR_TYPE_NS`. This API must be invoked at EL3. - -In the case of ARM standard platforms using GICv2, the _Highest Priority -Pending Interrupt Register_ (`GICC_HPPIR`) is read to determine the id of -the pending interrupt. The type of interrupt depends upon the id value as -follows. - -1. id < 1022 is reported as a S-EL1 interrupt -2. id = 1022 is reported as a Non-secure interrupt. -3. id = 1023 is reported as an invalid interrupt type. - -In the case of ARM standard platforms using GICv3, the system register -`ICC_HPPIR0_EL1`, _Highest Priority Pending group 0 Interrupt Register_, -is read to determine the id of the pending interrupt. The type of interrupt -depends upon the id value as follows. - -1. id = `PENDING_G1S_INTID` (1020) is reported as a S-EL1 interrupt -2. id = `PENDING_G1NS_INTID` (1021) is reported as a Non-secure interrupt. -3. id = `GIC_SPURIOUS_INTERRUPT` (1023) is reported as an invalid interrupt type. -4. All other interrupt id's are reported as EL3 interrupt. - - -### Function : plat_ic_get_pending_interrupt_id() [mandatory] - - Argument : void - Return : uint32_t - -This API returns the id of the highest priority pending interrupt at the -platform IC. `INTR_ID_UNAVAILABLE` is returned when there is no interrupt -pending. - -In the case of ARM standard platforms using GICv2, the _Highest Priority -Pending Interrupt Register_ (`GICC_HPPIR`) is read to determine the id of the -pending interrupt. The id that is returned by API depends upon the value of -the id read from the interrupt controller as follows. - -1. id < 1022. id is returned as is. -2. id = 1022. The _Aliased Highest Priority Pending Interrupt Register_ - (`GICC_AHPPIR`) is read to determine the id of the non-secure interrupt. - This id is returned by the API. -3. id = 1023. `INTR_ID_UNAVAILABLE` is returned. - -In the case of ARM standard platforms using GICv3, if the API is invoked from -EL3, the system register `ICC_HPPIR0_EL1`, _Highest Priority Pending Interrupt -group 0 Register_, is read to determine the id of the pending interrupt. The id -that is returned by API depends upon the value of the id read from the -interrupt controller as follows. - -1. id < `PENDING_G1S_INTID` (1020). id is returned as is. -2. id = `PENDING_G1S_INTID` (1020) or `PENDING_G1NS_INTID` (1021). The system - register `ICC_HPPIR1_EL1`, _Highest Priority Pending Interrupt group 1 - Register_ is read to determine the id of the group 1 interrupt. This id - is returned by the API as long as it is a valid interrupt id -3. If the id is any of the special interrupt identifiers, - `INTR_ID_UNAVAILABLE` is returned. - -When the API invoked from S-EL1 for GICv3 systems, the id read from system -register `ICC_HPPIR1_EL1`, _Highest Priority Pending group 1 Interrupt -Register_, is returned if is not equal to GIC_SPURIOUS_INTERRUPT (1023) else -`INTR_ID_UNAVAILABLE` is returned. - -### Function : plat_ic_acknowledge_interrupt() [mandatory] - - Argument : void - Return : uint32_t - -This API is used by the CPU to indicate to the platform IC that processing of -the highest pending interrupt has begun. It should return the id of the -interrupt which is being processed. - -This function in ARM standard platforms using GICv2, reads the _Interrupt -Acknowledge Register_ (`GICC_IAR`). This changes the state of the highest -priority pending interrupt from pending to active in the interrupt controller. -It returns the value read from the `GICC_IAR`. This value is the id of the -interrupt whose state has been changed. - -In the case of ARM standard platforms using GICv3, if the API is invoked -from EL3, the function reads the system register `ICC_IAR0_EL1`, _Interrupt -Acknowledge Register group 0_. If the API is invoked from S-EL1, the function -reads the system register `ICC_IAR1_EL1`, _Interrupt Acknowledge Register -group 1_. The read changes the state of the highest pending interrupt from -pending to active in the interrupt controller. The value read is returned -and is the id of the interrupt whose state has been changed. - -The TSP uses this API to start processing of the secure physical timer -interrupt. - - -### Function : plat_ic_end_of_interrupt() [mandatory] - - Argument : uint32_t - Return : void - -This API is used by the CPU to indicate to the platform IC that processing of -the interrupt corresponding to the id (passed as the parameter) has -finished. The id should be the same as the id returned by the -`plat_ic_acknowledge_interrupt()` API. - -ARM standard platforms write the id to the _End of Interrupt Register_ -(`GICC_EOIR`) in case of GICv2, and to `ICC_EOIR0_EL1` or `ICC_EOIR1_EL1` -system register in case of GICv3 depending on where the API is invoked from, -EL3 or S-EL1. This deactivates the corresponding interrupt in the interrupt -controller. - -The TSP uses this API to finish processing of the secure physical timer -interrupt. - - -### Function : plat_ic_get_interrupt_type() [mandatory] - - Argument : uint32_t - Return : uint32_t - -This API returns the type of the interrupt id passed as the parameter. -`INTR_TYPE_INVAL` is returned if the id is invalid. If the id is valid, a valid -interrupt type (one of `INTR_TYPE_EL3`, `INTR_TYPE_S_EL1` and `INTR_TYPE_NS`) is -returned depending upon how the interrupt has been configured by the platform -IC. This API must be invoked at EL3. - -ARM standard platforms using GICv2 configures S-EL1 interrupts as Group0 interrupts -and Non-secure interrupts as Group1 interrupts. It reads the group value -corresponding to the interrupt id from the relevant _Interrupt Group Register_ -(`GICD_IGROUPRn`). It uses the group value to determine the type of interrupt. - -In the case of ARM standard platforms using GICv3, both the _Interrupt Group -Register_ (`GICD_IGROUPRn`) and _Interrupt Group Modifier Register_ -(`GICD_IGRPMODRn`) is read to figure out whether the interrupt is configured -as Group 0 secure interrupt, Group 1 secure interrupt or Group 1 NS interrupt. - - -3.7 Crash Reporting mechanism (in BL31) ----------------------------------------------- -BL31 implements a crash reporting mechanism which prints the various registers -of the CPU to enable quick crash analysis and debugging. It requires that a -console is designated as the crash console by the platform which will be used to -print the register dump. - -The following functions must be implemented by the platform if it wants crash -reporting mechanism in BL31. The functions are implemented in assembly so that -they can be invoked without a C Runtime stack. - -### Function : plat_crash_console_init - - Argument : void - Return : int - -This API is used by the crash reporting mechanism to initialize the crash -console. It must only use the general purpose registers x0 to x4 to do the -initialization and returns 1 on success. - -### Function : plat_crash_console_putc - - Argument : int - Return : int - -This API is used by the crash reporting mechanism to print a character on the -designated crash console. It must only use general purpose registers x1 and -x2 to do its work. The parameter and the return value are in general purpose -register x0. - -### Function : plat_crash_console_flush - - Argument : void - Return : int - -This API is used by the crash reporting mechanism to force write of all buffered -data on the designated crash console. It should only use general purpose -registers x0 and x1 to do its work. The return value is 0 on successful -completion; otherwise the return value is -1. - - -4. Build flags ---------------- - -* **ENABLE_PLAT_COMPAT** - All the platforms ports conforming to this API specification should define - the build flag `ENABLE_PLAT_COMPAT` to 0 as the compatibility layer should - be disabled. For more details on compatibility layer, refer - [Migration Guide]. - -There are some build flags which can be defined by the platform to control -inclusion or exclusion of certain BL stages from the FIP image. These flags -need to be defined in the platform makefile which will get included by the -build system. - -* **NEED_BL33** - By default, this flag is defined `yes` by the build system and `BL33` - build option should be supplied as a build option. The platform has the - option of excluding the BL33 image in the `fip` image by defining this flag - to `no`. If any of the options `EL3_PAYLOAD_BASE` or `PRELOADED_BL33_BASE` - are used, this flag will be set to `no` automatically. - -5. C Library -------------- - -To avoid subtle toolchain behavioral dependencies, the header files provided -by the compiler are not used. The software is built with the `-nostdinc` flag -to ensure no headers are included from the toolchain inadvertently. Instead the -required headers are included in the ARM Trusted Firmware source tree. The -library only contains those C library definitions required by the local -implementation. If more functionality is required, the needed library functions -will need to be added to the local implementation. - -Versions of [FreeBSD] headers can be found in `include/lib/stdlib`. Some of -these headers have been cut down in order to simplify the implementation. In -order to minimize changes to the header files, the [FreeBSD] layout has been -maintained. The generic C library definitions can be found in -`include/lib/stdlib` with more system and machine specific declarations in -`include/lib/stdlib/sys` and `include/lib/stdlib/machine`. - -The local C library implementations can be found in `lib/stdlib`. In order to -extend the C library these files may need to be modified. It is recommended to -use a release version of [FreeBSD] as a starting point. - -The C library header files in the [FreeBSD] source tree are located in the -`include` and `sys/sys` directories. [FreeBSD] machine specific definitions -can be found in the `sys/<machine-type>` directories. These files define things -like 'the size of a pointer' and 'the range of an integer'. Since an AArch64 -port for [FreeBSD] does not yet exist, the machine specific definitions are -based on existing machine types with similar properties (for example SPARC64). - -Where possible, C library function implementations were taken from [FreeBSD] -as found in the `lib/libc` directory. - -A copy of the [FreeBSD] sources can be downloaded with `git`. - - git clone git://github.com/freebsd/freebsd.git -b origin/release/9.2.0 - - -6. Storage abstraction layer ------------------------------ - -In order to improve platform independence and portability an storage abstraction -layer is used to load data from non-volatile platform storage. - -Each platform should register devices and their drivers via the Storage layer. -These drivers then need to be initialized by bootloader phases as -required in their respective `blx_platform_setup()` functions. Currently -storage access is only required by BL1 and BL2 phases. The `load_image()` -function uses the storage layer to access non-volatile platform storage. - -It is mandatory to implement at least one storage driver. For the ARM -development platforms the Firmware Image Package (FIP) driver is provided as -the default means to load data from storage (see the "Firmware Image Package" -section in the [User Guide]). The storage layer is described in the header file -`include/drivers/io/io_storage.h`. The implementation of the common library -is in `drivers/io/io_storage.c` and the driver files are located in -`drivers/io/`. - -Each IO driver must provide `io_dev_*` structures, as described in -`drivers/io/io_driver.h`. These are returned via a mandatory registration -function that is called on platform initialization. The semi-hosting driver -implementation in `io_semihosting.c` can be used as an example. - -The Storage layer provides mechanisms to initialize storage devices before -IO operations are called. The basic operations supported by the layer -include `open()`, `close()`, `read()`, `write()`, `size()` and `seek()`. -Drivers do not have to implement all operations, but each platform must -provide at least one driver for a device capable of supporting generic -operations such as loading a bootloader image. - -The current implementation only allows for known images to be loaded by the -firmware. These images are specified by using their identifiers, as defined in -[include/plat/common/platform_def.h] (or a separate header file included from -there). The platform layer (`plat_get_image_source()`) then returns a reference -to a device and a driver-specific `spec` which will be understood by the driver -to allow access to the image data. - -The layer is designed in such a way that is it possible to chain drivers with -other drivers. For example, file-system drivers may be implemented on top of -physical block devices, both represented by IO devices with corresponding -drivers. In such a case, the file-system "binding" with the block device may -be deferred until the file-system device is initialised. - -The abstraction currently depends on structures being statically allocated -by the drivers and callers, as the system does not yet provide a means of -dynamically allocating memory. This may also have the affect of limiting the -amount of open resources per driver. - - -- - - - - - - - - - - - - - - - - - - - - - - - - - - -_Copyright (c) 2013-2016, ARM Limited and Contributors. All rights reserved._ - - -[ARM GIC Architecture Specification 2.0]: http://infocenter.arm.com/help/topic/com.arm.doc.ihi0048b/index.html -[ARM GIC Architecture Specification 3.0]: http://infocenter.arm.com/help/topic/com.arm.doc.ihi0069b/index.html -[IMF Design Guide]: interrupt-framework-design.md -[User Guide]: user-guide.md -[FreeBSD]: http://www.freebsd.org -[Firmware Design]: firmware-design.md -[Power Domain Topology Design]: psci-pd-tree.md -[PSCI]: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf -[Migration Guide]: platform-migration-guide.md -[Firmware Update]: firmware-update.md - -[plat/common/aarch64/platform_mp_stack.S]: ../plat/common/aarch64/platform_mp_stack.S -[plat/common/aarch64/platform_up_stack.S]: ../plat/common/aarch64/platform_up_stack.S -[plat/arm/board/fvp/fvp_pm.c]: ../plat/arm/board/fvp/fvp_pm.c -[include/common/bl_common.h]: ../include/common/bl_common.h -[include/lib/aarch32/arch.h]: ../include/lib/aarch32/arch.h -[include/plat/arm/common/arm_def.h]: ../include/plat/arm/common/arm_def.h -[include/plat/common/common_def.h]: ../include/plat/common/common_def.h -[include/plat/common/platform.h]: ../include/plat/common/platform.h -[include/plat/arm/common/plat_arm.h]: ../include/plat/arm/common/plat_arm.h] diff --git a/docs/psci-lib-integration-guide.md b/docs/psci-lib-integration-guide.md deleted file mode 100644 index ab0276b0..00000000 --- a/docs/psci-lib-integration-guide.md +++ /dev/null @@ -1,536 +0,0 @@ -PSCI Library Integration guide for ARMv8-A AArch32 systems -========================================================== - -Contents - -1. [Introduction](#1-introduction) -2. [Generic call sequence for PSCI Library interface (AArch32)](#2-generic-call-sequence-for-psci-library-interface-aarch32) -3. [PSCI CPU context management](#3-psci-cpu-context-management) -4. [PSCI Library Interface](#4-psci-library-interface) -5. [EL3 Runtime Software dependencies](#5-el3-runtime-software-dependencies) - - -1. Introduction ---------------- - -This document describes the PSCI library interface with a focus on how to -integrate with a suitable Trusted OS for an ARMv8-A AArch32 system. The PSCI -Library implements the PSCI Standard as described in [PSCI spec] and is meant -to be integrated with EL3 Runtime Software which invokes the PSCI Library -interface appropriately. **EL3 Runtime Software** refers to software executing -at the highest secure privileged mode, which is EL3 in AArch64 or Secure SVC/ -Monitor mode in AArch32, and provides runtime services to the non-secure world. -The runtime service request is made via SMC (Secure Monitor Call) and the call -must adhere to [SMCCC]. In AArch32, EL3 Runtime Software may additionally -include Trusted OS functionality. A minimal AArch32 Secure Payload, SP-MIN, is -provided in ARM Trusted Firmware to illustrate the usage and integration of the -PSCI library. The description of PSCI library interface and its integration -with EL3 Runtime Software in this document is targeted towards AArch32 systems. - -2. Generic call sequence for PSCI Library interface (AArch32) -------------------------------------------------------------- - -The generic call sequence of PSCI Library interfaces (see -[section 4](#4-psci-library-interface)) during cold boot in AArch32 -system is described below: - -1. After cold reset, the EL3 Runtime Software performs its cold boot - initialization including the PSCI library pre-requisites mentioned in - [section 4](#4-psci-library-interface), and also the necessary platform - setup. - -2. Call `psci_setup()` in Monitor mode. - -3. Optionally call `psci_register_spd_pm_hook()` to register callbacks to - do bookkeeping for the EL3 Runtime Software during power management. - -4. Call `psci_prepare_next_non_secure_ctx()` to initialize the non-secure CPU - context. - -5. Get the non-secure `cpu_context_t` for the current CPU by calling - `cm_get_context()` , then programming the registers in the non-secure - context and exiting to non-secure world. If the EL3 Runtime Software needs - additional configuration to be set for non-secure context, like routing - FIQs to the secure world, the values of the registers can be modified prior - to programming. See [section 3](#3-psci-cpu-context-management) for more - details on CPU context management. - -The generic call sequence of PSCI library interfaces during warm boot in -AArch32 systems is described below: - -1. After warm reset, the EL3 Runtime Software performs the necessary warm - boot initialization including the PSCI library pre-requisites mentioned in - [section 4](#4-psci-library-interface) (Note that the Data cache - **must not** be enabled). - -2. Call `psci_warmboot_entrypoint()` in Monitor mode. This interface - initializes/restores the non-secure CPU context as well. - -3. Do step 5 of the cold boot call sequence described above. - -The generic call sequence of PSCI library interfaces on receipt of a PSCI SMC -on an AArch32 system is described below: - -1. On receipt of an SMC, save the register context as per [SMCCC]. - -2. If the SMC function identifier corresponds to a SMC32 PSCI API, construct - the appropriate arguments and call the `psci_smc_handler()` interface. - The invocation may or may not return back to the caller depending on - whether the PSCI API resulted in power down of the CPU. - -3. If `psci_smc_handler()` returns, populate the return value in R0 (AArch32)/ - X0 (AArch64) and restore other registers as per [SMCCC]. - - -3. PSCI CPU context management ------------------------------- - -PSCI library is in charge of initializing/restoring the non-secure CPU system -registers according to [PSCI specification][PSCI spec] during cold/warm boot. -This is referred to as `PSCI CPU Context Management`. Registers that need to -be preserved across CPU power down/power up cycles are maintained in -`cpu_context_t` data structure. The initialization of other non-secure CPU -system registers which do not require coordination with the EL3 Runtime -Software is done directly by the PSCI library (see `cm_prepare_el3_exit()`). - -The EL3 Runtime Software is responsible for managing register context -during switch between Normal and Secure worlds. The register context to be -saved and restored depends on the mechanism used to trigger the world switch. -For example, if the world switch was triggered by an SMC call, then the -registers need to be saved and restored according to [SMCCC]. In AArch64, -due to the tight integration with BL31, both BL31 and PSCI library -use the same `cpu_context_t` data structure for PSCI CPU context management -and register context management during world switch. This cannot be assumed -for AArch32 EL3 Runtime Software since most AArch32 Trusted OSes already implement -a mechanism for register context management during world switch. Hence, when -the PSCI library is integrated with a AArch32 EL3 Runtime Software, the -`cpu_context_t` is stripped down for just PSCI CPU context management. - -During cold/warm boot, after invoking appropriate PSCI library interfaces, it -is expected that the EL3 Runtime Software will query the `cpu_context_t` and -write appropriate values to the corresponding system registers. This mechanism -resolves 2 additional problems for AArch32 EL3 Runtime Software: - -1. Values for certain system registers like SCR and SCTLR cannot be - unilaterally determined by PSCI library and need inputs from the EL3 - Runtime Software. Using `cpu_context_t` as an intermediary data store - allows EL3 Runtime Software to modify the register values appropriately - before programming them. - -2. The PSCI library provides appropriate LR and SPSR values (entrypoint - information) for exit into non-secure world. Using `cpu_context_t` as an - intermediary data store allows the EL3 Runtime Software to store these - values safely until it is ready for exit to non-secure world. - -Currently the `cpu_context_t` data structure for AArch32 stores the following -registers: R0 - R3, LR (R14), SCR, SPSR, SCTLR. - -The EL3 Runtime Software must implement accessors to get/set pointers -to CPU context `cpu_context_t` data and these are described in -[section 5.2](#52-cpu-context-management-api). - - -4. PSCI Library Interface -------------------------- - -The PSCI library implements the [PSCI Specification][PSCI spec]. The interfaces -to this library are declared in `psci.h` and are as listed below: - -``` - u_register_t psci_smc_handler(uint32_t smc_fid, u_register_t x1, - u_register_t x2, u_register_t x3, - u_register_t x4, void *cookie, - void *handle, u_register_t flags); - int psci_setup(const psci_lib_args_t *lib_args); - void psci_warmboot_entrypoint(void); - void psci_register_spd_pm_hook(const spd_pm_ops_t *pm); - void psci_prepare_next_non_secure_ctx(entry_point_info_t *next_image_info); -``` - -The CPU context data 'cpu_context_t' is programmed to the registers differently -when PSCI is integrated with an AArch32 EL3 Runtime Software compared to -when the PSCI is integrated with an AArch64 EL3 Runtime Software (BL31). For -example, in the case of AArch64, there is no need to retrieve `cpu_context_t` -data and program the registers as it will done implicitly as part of -`el3_exit`. The description below of the PSCI interfaces is targeted at -integration with an AArch32 EL3 Runtime Software. - -The PSCI library is responsible for initializing/restoring the non-secure world -to an appropriate state after boot and may choose to directly program the -non-secure system registers. The PSCI generic code takes care not to directly -modify any of the system registers affecting the secure world and instead -returns the values to be programmed to these registers via `cpu_context_t`. -The EL3 Runtime Software is responsible for programming those registers and -can use the proposed values provided in the `cpu_context_t`, modifying the -values if required. - -PSCI library needs the flexibility to access both secure and non-secure -copies of banked registers. Hence it needs to be invoked in Monitor mode -for AArch32 and in EL3 for AArch64. The NS bit in SCR (in AArch32) or SCR_EL3 -(in AArch64) must be set to 0. Additional requirements for the PSCI library -interfaces are: - - * Instruction cache must be enabled - * Both IRQ and FIQ must be masked for the current CPU - * The page tables must be setup and the MMU enabled - * The C runtime environment must be setup and stack initialized - * The Data cache must be enabled prior to invoking any of the PSCI library - interfaces except for `psci_warmboot_entrypoint()`. For - `psci_warmboot_entrypoint()`, if the build option `HW_ASSISTED_COHERENCY` - is enabled however, data caches are expected to be enabled. - -Further requirements for each interface can be found in the interface -description. - -### 4.1 Interface : psci_setup() - - Argument : const psci_lib_args_t *lib_args - Return : void - -This function is to be called by the primary CPU during cold boot before -any other interface to the PSCI library. It takes `lib_args`, a const pointer -to `psci_lib_args_t`, as the argument. The `psci_lib_args_t` is a versioned -structure and is declared in `psci.h` header as follows: - -``` - typedef struct psci_lib_args { - /* The version information of PSCI Library Interface */ - param_header_t h; - /* The warm boot entrypoint function */ - mailbox_entrypoint_t mailbox_ep; - } psci_lib_args_t; -``` - -The first field `h`, of `param_header_t` type, provides the version -information. The second field `mailbox_ep` is the warm boot entrypoint address -and is used to configure the platform mailbox. Helper macros are provided in -psci.h to construct the `lib_args` argument statically or during runtime. Prior -to calling the `psci_setup()` interface, the platform setup for cold boot -must have completed. Major actions performed by this interface are: - - * Initializes architecture. - * Initializes PSCI power domain and state coordination data structures. - * Calls `plat_setup_psci_ops()` with warm boot entrypoint `mailbox_ep` as - argument. - * Calls `cm_set_context_by_index()` (see - [section 5.2](#52-cpu-context-management-api)) for all the CPUs in the - platform - -### 4.2 Interface : psci_prepare_next_non_secure_ctx() - - Argument : entry_point_info_t *next_image_info - Return : void - -After `psci_setup()` and prior to exit to the non-secure world, this function -must be called by the EL3 Runtime Software to initialize the non-secure world -context. The non-secure world entrypoint information `next_image_info` (first -argument) will be used to determine the non-secure context. After this function -returns, the EL3 Runtime Software must retrieve the `cpu_context_t` (using -cm_get_context()) for the current CPU and program the registers prior to exit -to the non-secure world. - -### 4.3 Interface : psci_register_spd_pm_hook() - - Argument : const spd_pm_ops_t * - Return : void - -As explained in [section 5.4](#54-secure-payload-power-management-callback), -the EL3 Runtime Software may want to perform some bookkeeping during power -management operations. This function is used to register the `spd_pm_ops_t` -(first argument) callbacks with the PSCI library which will be called -ppropriately during power management. Calling this function is optional and -need to be called by the primary CPU during the cold boot sequence after -`psci_setup()` has completed. - -### 4.4 Interface : psci_smc_handler() - - Argument : uint32_t smc_fid, u_register_t x1, - u_register_t x2, u_register_t x3, - u_register_t x4, void *cookie, - void *handle, u_register_t flags - Return : u_register_t - -This function is the top level handler for SMCs which fall within the -PSCI service range specified in [SMCCC]. The function ID `smc_fid` (first -argument) determines the PSCI API to be called. The `x1` to `x4` (2nd to 5th -arguments), are the values of the registers r1 - r4 (in AArch32) or x1 - x4 -(in AArch64) when the SMC is received. These are the arguments to PSCI API as -described in [PSCI spec]. The 'flags' (8th argument) is a bit field parameter -and is detailed in 'smcc.h' header. It includes whether the call is from the -secure or non-secure world. The `cookie` (6th argument) and the `handle` -(7th argument) are not used and are reserved for future use. - -The return value from this interface is the return value from the underlying -PSCI API corresponding to `smc_fid`. This function may not return back to the -caller if PSCI API causes power down of the CPU. In this case, when the CPU -wakes up, it will start execution from the warm reset address. - -### 4.5 Interface : psci_warmboot_entrypoint() - - Argument : void - Return : void - -This function performs the warm boot initialization/restoration as mandated by -[PSCI spec]. For AArch32, on wakeup from power down the CPU resets to secure SVC -mode and the EL3 Runtime Software must perform the prerequisite initializations -mentioned at top of this section. This function must be called with Data cache -disabled (unless build option `HW_ASSISTED_COHERENCY` is enabled) but with MMU -initialized and enabled. The major actions performed by this function are: - - * Invalidates the stack and enables the data cache. - * Initializes architecture and PSCI state coordination. - * Restores/Initializes the peripheral drivers to the required state via - appropriate `plat_psci_ops_t` hooks - * Restores the EL3 Runtime Software context via appropriate `spd_pm_ops_t` - callbacks. - * Restores/Initializes the non-secure context and populates the - `cpu_context_t` for the current CPU. - -Upon the return of this function, the EL3 Runtime Software must retrieve the -non-secure `cpu_context_t` using `cm_get_context()` and program the registers -prior to exit to the non-secure world. - - -5. EL3 Runtime Software dependencies ---------------------------------------- - -The PSCI Library includes supporting frameworks like context management, -cpu operations (cpu_ops) and per-cpu data framework. Other helper library -functions like bakery locks and spin locks are also included in the library. -The dependencies which must be fulfilled by the EL3 Runtime Software -for integration with PSCI library are described below. - -### 5.1 General dependencies - -The PSCI library being a Multiprocessor (MP) implementation, EL3 Runtime -Software must provide an SMC handling framework capable of MP adhering to -[SMCCC] specification. - -The EL3 Runtime Software must also export cache maintenance primitives -and some helper utilities for assert, print and memory operations as listed -below. The ARM Trusted Firmware source tree provides implementations for all -these functions but the EL3 Runtime Software may use its own implementation. - -**Functions : assert(), memcpy(), memset** - -These must be implemented as described in ISO C Standard. - -**Function : flush_dcache_range()** - - Argument : uintptr_t addr, size_t size - Return : void - -This function cleans and invalidates (flushes) the data cache for memory -at address `addr` (first argument) address and of size `size` (second argument). - -**Function : inv_dcache_range()** - - Argument : uintptr_t addr, size_t size - Return : void - -This function invalidates (flushes) the data cache for memory at address -`addr` (first argument) address and of size `size` (second argument). - -**Function : do_panic()** - - Argument : void - Return : void - -This function will be called by the PSCI library on encountering a critical -failure that cannot be recovered from. This function **must not** return. - -**Function : tf_printf()** - -This is printf-compatible function, but unlike printf, it does not return any -value. The ARM Trusted Firmware source tree provides an implementation which -is optimized for stack usage and supports only a subset of format specifiers. -The details of the format specifiers supported can be found in the -`tf_printf.c` file in ARM Trusted Firmware source tree. - -### 5.2 CPU Context management API - -The CPU context management data memory is statically allocated by PSCI library -in BSS section. The PSCI library requires the EL3 Runtime Software to implement -APIs to store and retrieve pointers to this CPU context data. SP-MIN -demonstrates how these APIs can be implemented but the EL3 Runtime Software can -choose a more optimal implementation (like dedicating the secure TPIDRPRW -system register (in AArch32) for storing these pointers). - -**Function : cm_set_context_by_index()** - - Argument : unsigned int cpu_idx, void *context, unsigned int security_state - Return : void - -This function is called during cold boot when the `psci_setup()` PSCI library -interface is called. - -This function must store the pointer to the CPU context data, `context` (2nd -argument), for the specified `security_state` (3rd argument) and CPU identified -by `cpu_idx` (first argument). The `security_state` will always be non-secure -when called by PSCI library and this argument is retained for compatibility -with BL31. The `cpu_idx` will correspond to the index returned by the -`plat_core_pos_by_mpidr()` for `mpidr` of the CPU. - -The actual method of storing the `context` pointers is implementation specific. -For example, SP-MIN stores the pointers in the array `sp_min_cpu_ctx_ptr` -declared in `sp_min_main.c`. - -**Function : cm_get_context()** - - Argument : uint32_t security_state - Return : void * - -This function must return the pointer to the `cpu_context_t` structure for -the specified `security_state` (first argument) for the current CPU. The caller -must ensure that `cm_set_context_by_index` is called first and the appropriate -context pointers are stored prior to invoking this API. The `security_state` -will always be non-secure when called by PSCI library and this argument -is retained for compatibility with BL31. - -**Function : cm_get_context_by_index()** - - Argument : unsigned int cpu_idx, unsigned int security_state - Return : void * - -This function must return the pointer to the `cpu_context_t` structure for -the specified `security_state` (second argument) for the CPU identified by -`cpu_idx` (first argument). The caller must ensure that -`cm_set_context_by_index` is called first and the appropriate context -pointers are stored prior to invoking this API. The `security_state` will -always be non-secure when called by PSCI library and this argument is -retained for compatibility with BL31. The `cpu_idx` will correspond to the -index returned by the `plat_core_pos_by_mpidr()` for `mpidr` of the CPU. - -### 5.3 Platform API - -The platform layer abstracts the platform-specific details from the generic -PSCI library. The following platform APIs/macros must be defined by the EL3 -Runtime Software for integration with the PSCI library. - -The mandatory platform APIs are: - - * plat_my_core_pos - * plat_core_pos_by_mpidr - * plat_get_syscnt_freq2 - * plat_get_power_domain_tree_desc - * plat_setup_psci_ops - * plat_reset_handler - * plat_panic_handler - * plat_get_my_stack - -The mandatory platform macros are: - - * PLATFORM_CORE_COUNT - * PLAT_MAX_PWR_LVL - * PLAT_NUM_PWR_DOMAINS - * CACHE_WRITEBACK_GRANULE - * PLAT_MAX_OFF_STATE - * PLAT_MAX_RET_STATE - * PLAT_MAX_PWR_LVL_STATES (optional) - * PLAT_PCPU_DATA_SIZE (optional) - -The details of these APIs/macros can be found in [Porting Guide]. - -All platform specific operations for power management are done via -`plat_psci_ops_t` callbacks registered by the platform when -`plat_setup_psci_ops()` API is called. The description of each of -the callbacks in `plat_psci_ops_t` can be found in PSCI section of the -[Porting Guide]. If any these callbacks are not registered, then the -PSCI API associated with that callback will not be supported by PSCI -library. - -### 5.4 Secure payload power management callback - -During PSCI power management operations, the EL3 Runtime Software may -need to perform some bookkeeping, and PSCI library provides -`spd_pm_ops_t` callbacks for this purpose. These hooks must be -populated and registered by using `psci_register_spd_pm_hook()` PSCI -library interface. - -Typical bookkeeping during PSCI power management calls include save/restore -of the EL3 Runtime Software context. Also if the EL3 Runtime Software makes -use of secure interrupts, then these interrupts must also be managed -appropriately during CPU power down/power up. Any secure interrupt targeted -to the current CPU must be disabled or re-targeted to other running CPU prior -to power down of the current CPU. During power up, these interrupt can be -enabled/re-targeted back to the current CPU. - -``` - typedef struct spd_pm_ops { - void (*svc_on)(u_register_t target_cpu); - int32_t (*svc_off)(u_register_t __unused); - void (*svc_suspend)(u_register_t max_off_pwrlvl); - void (*svc_on_finish)(u_register_t __unused); - void (*svc_suspend_finish)(u_register_t max_off_pwrlvl); - int32_t (*svc_migrate)(u_register_t from_cpu, u_register_t to_cpu); - int32_t (*svc_migrate_info)(u_register_t *resident_cpu); - void (*svc_system_off)(void); - void (*svc_system_reset)(void); - } spd_pm_ops_t; -``` -A brief description of each callback is given below: - -* svc_on, svc_off, svc_on_finish - - The `svc_on`, `svc_off` callbacks are called during PSCI_CPU_ON, - PSCI_CPU_OFF APIs respectively. The `svc_on_finish` is called when the - target CPU of PSCI_CPU_ON API powers up and executes the - `psci_warmboot_entrypoint()` PSCI library interface. - -* svc_suspend, svc_suspend_finish - - The `svc_suspend` callback is called during power down bu either - PSCI_SUSPEND or PSCI_SYSTEM_SUSPEND APIs. The `svc_suspend_finish` is - called when the CPU wakes up from suspend and executes the - `psci_warmboot_entrypoint()` PSCI library interface. The `max_off_pwrlvl` - (first parameter) denotes the highest power domain level being powered down - to or woken up from suspend. - -* svc_system_off, svc_system_reset - - These callbacks are called during PSCI_SYSTEM_OFF and PSCI_SYSTEM_RESET - PSCI APIs respectively. - -* svc_migrate_info - - This callback is called in response to PSCI_MIGRATE_INFO_TYPE or - PSCI_MIGRATE_INFO_UP_CPU APIs. The return value of this callback must - correspond to the return value of PSCI_MIGRATE_INFO_TYPE API as described - in [PSCI spec]. If the secure payload is a Uniprocessor (UP) - implementation, then it must update the mpidr of the CPU it is resident in - via `resident_cpu` (first argument). The updates to `resident_cpu` is - ignored if the secure payload is a multiprocessor (MP) implementation. - -* svc_migrate - - This callback is only relevant if the secure payload in EL3 Runtime - Software is a Uniprocessor (UP) implementation and supports migration from - the current CPU `from_cpu` (first argument) to another CPU `to_cpu` - (second argument). This callback is called in response to PSCI_MIGRATE - API. This callback is never called if the secure payload is a - Multiprocessor (MP) implementation. - -### 5.5 CPU operations - -The CPU operations (cpu_ops) framework implement power down sequence specific -to the CPU and the details of which can be found in the `CPU specific -operations framework` section of [Firmware Design]. The ARM Trusted Firmware -tree implements the `cpu_ops` for various supported CPUs and the EL3 Runtime -Software needs to include the required `cpu_ops` in its build. The start and -end of the `cpu_ops` descriptors must be exported by the EL3 Runtime Software -via the `__CPU_OPS_START__` and `__CPU_OPS_END__` linker symbols. - -The `cpu_ops` descriptors also include reset sequences and may include errata -workarounds for the CPU. The EL3 Runtime Software can choose to call this -during cold/warm reset if it does not implement its own reset sequence/errata -workarounds. - - -- - - - - - - - - - - - - - - - - - - - - - - - - - - -_Copyright (c) 2016, ARM Limited and Contributors. All rights reserved._ - -[PSCI spec]: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf "Power State Coordination Interface PDD (ARM DEN 0022C)" -[SMCCC]: https://silver.arm.com/download/ARM_and_AMBA_Architecture/AR570-DA-80002-r0p0-00rel0/ARM_DEN0028A_SMC_Calling_Convention.pdf "SMC Calling Convention" -[Porting Guide]: porting-guide.md -[Firmware Design]: ./firmware-design.md diff --git a/docs/psci-pd-tree.md b/docs/psci-pd-tree.md deleted file mode 100644 index a847f06b..00000000 --- a/docs/psci-pd-tree.md +++ /dev/null @@ -1,308 +0,0 @@ -PSCI Library Integration guide for ARMv8-A AArch32 systems -========================================================== - -Contents --------- - -1. [Requirements](#requirements) -2. [Design](#design) - ------------- -Requirements ------------- - -1. A platform must export the `plat_get_aff_count()` and - `plat_get_aff_state()` APIs to enable the generic PSCI code to - populate a tree that describes the hierarchy of power domains in the - system. This approach is inflexible because a change to the topology - requires a change in the code. - - It would be much simpler for the platform to describe its power domain tree - in a data structure. - -2. The generic PSCI code generates MPIDRs in order to populate the power domain - tree. It also uses an MPIDR to find a node in the tree. The assumption that - a platform will use exactly the same MPIDRs as generated by the generic PSCI - code is not scalable. The use of an MPIDR also restricts the number of - levels in the power domain tree to four. - - Therefore, there is a need to decouple allocation of MPIDRs from the - mechanism used to populate the power domain topology tree. - -3. The current arrangement of the power domain tree requires a binary search - over the sibling nodes at a particular level to find a specified power - domain node. During a power management operation, the tree is traversed from - a 'start' to an 'end' power level. The binary search is required to find the - node at each level. The natural way to perform this traversal is to - start from a leaf node and follow the parent node pointer to reach the end - level. - - Therefore, there is a need to define data structures that implement the tree in - a way which facilitates such a traversal. - -4. The attributes of a core power domain differ from the attributes of power - domains at higher levels. For example, only a core power domain can be identified - using an MPIDR. There is no requirement to perform state coordination while - performing a power management operation on the core power domain. - - Therefore, there is a need to implement the tree in a way which facilitates this - distinction between a leaf and non-leaf node and any associated - optimizations. - - ------- -Design ------- - -### Describing a power domain tree - -To fulfill requirement 1., the existing platform APIs -`plat_get_aff_count()` and `plat_get_aff_state()` have been -removed. A platform must define an array of unsigned chars such that: - -1. The first entry in the array specifies the number of power domains at the - highest power level implemented in the platform. This caters for platforms - where the power domain tree does not have a single root node, for example, - the FVP has two cluster power domains at the highest level (1). - -2. Each subsequent entry corresponds to a power domain and contains the number - of power domains that are its direct children. - -3. The size of the array minus the first entry will be equal to the number of - non-leaf power domains. - -4. The value in each entry in the array is used to find the number of entries - to consider at the next level. The sum of the values (number of children) of - all the entries at a level specifies the number of entries in the array for - the next level. - -The following example power domain topology tree will be used to describe the -above text further. The leaf and non-leaf nodes in this tree have been numbered -separately. - -``` - +-+ - |0| - +-+ - / \ - / \ - / \ - / \ - / \ - / \ - / \ - / \ - / \ - / \ - +-+ +-+ - |1| |2| - +-+ +-+ - / \ / \ - / \ / \ - / \ / \ - / \ / \ - +-+ +-+ +-+ +-+ - |3| |4| |5| |6| - +-+ +-+ +-+ +-+ - +---+-----+ +----+----| +----+----+ +----+-----+-----+ - | | | | | | | | | | | | | - | | | | | | | | | | | | | - v v v v v v v v v v v v v - +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +--+ +--+ +--+ - |0| |1| |2| |3| |4| |5| |6| |7| |8| |9| |10| |11| |12| - +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +--+ +--+ +--+ -``` - - -This tree is defined by the platform as the array described above as follows: - -``` - #define PLAT_NUM_POWER_DOMAINS 20 - #define PLATFORM_CORE_COUNT 13 - #define PSCI_NUM_NON_CPU_PWR_DOMAINS \ - (PLAT_NUM_POWER_DOMAINS - PLATFORM_CORE_COUNT) - - unsigned char plat_power_domain_tree_desc[] = { 1, 2, 2, 2, 3, 3, 3, 4}; -``` - -### Removing assumptions about MPIDRs used in a platform - -To fulfill requirement 2., it is assumed that the platform assigns a -unique number (core index) between `0` and `PLAT_CORE_COUNT - 1` to each core -power domain. MPIDRs could be allocated in any manner and will not be used to -populate the tree. - -`plat_core_pos_by_mpidr(mpidr)` will return the core index for the core -corresponding to the MPIDR. It will return an error (-1) if an MPIDR is passed -which is not allocated or corresponds to an absent core. The semantics of this -platform API have changed since it is required to validate the passed MPIDR. It -has been made a mandatory API as a result. - -Another mandatory API, `plat_my_core_pos()` has been added to return the core -index for the calling core. This API provides a more lightweight mechanism to get -the index since there is no need to validate the MPIDR of the calling core. - -The platform should assign the core indices (as illustrated in the diagram above) -such that, if the core nodes are numbered from left to right, then the index -for a core domain will be the same as the index returned by - `plat_core_pos_by_mpidr()` or `plat_my_core_pos()` for that core. This -relationship allows the core nodes to be allocated in a separate array -(requirement 4.) during `psci_setup()` in such an order that the index of the -core in the array is the same as the return value from these APIs. - -#### Dealing with holes in MPIDR allocation - -For platforms where the number of allocated MPIDRs is equal to the number of -core power domains, for example, Juno and FVPs, the logic to convert an MPIDR to -a core index should remain unchanged. Both Juno and FVP use a simple collision -proof hash function to do this. - -It is possible that on some platforms, the allocation of MPIDRs is not -contiguous or certain cores have been disabled. This essentially means that the -MPIDRs have been sparsely allocated, that is, the size of the range of MPIDRs -used by the platform is not equal to the number of core power domains. - -The platform could adopt one of the following approaches to deal with this -scenario: - -1. Implement more complex logic to convert a valid MPIDR to a core index while - maintaining the relationship described earlier. This means that the power - domain tree descriptor will not describe any core power domains which are - disabled or absent. Entries will not be allocated in the tree for these - domains. - -2. Treat unallocated MPIDRs and disabled cores as absent but still describe them - in the power domain descriptor, that is, the number of core nodes described - is equal to the size of the range of MPIDRs allocated. This approach will - lead to memory wastage since entries will be allocated in the tree but will - allow use of a simpler logic to convert an MPIDR to a core index. - - -### Traversing through and distinguishing between core and non-core power domains - -To fulfill requirement 3 and 4, separate data structures have been defined -to represent leaf and non-leaf power domain nodes in the tree. - -``` -/******************************************************************************* - * The following two data structures implement the power domain tree. The tree - * is used to track the state of all the nodes i.e. power domain instances - * described by the platform. The tree consists of nodes that describe CPU power - * domains i.e. leaf nodes and all other power domains which are parents of a - * CPU power domain i.e. non-leaf nodes. - ******************************************************************************/ -typedef struct non_cpu_pwr_domain_node { - /* - * Index of the first CPU power domain node level 0 which has this node - * as its parent. - */ - unsigned int cpu_start_idx; - - /* - * Number of CPU power domains which are siblings of the domain indexed - * by 'cpu_start_idx' i.e. all the domains in the range 'cpu_start_idx - * -> cpu_start_idx + ncpus' have this node as their parent. - */ - unsigned int ncpus; - - /* Index of the parent power domain node */ - unsigned int parent_node; - - ----- -} non_cpu_pd_node_t; - -typedef struct cpu_pwr_domain_node { - u_register_t mpidr; - - /* Index of the parent power domain node */ - unsigned int parent_node; - - ----- -} cpu_pd_node_t; -``` - -The power domain tree is implemented as a combination of the following data -structures. - -``` -non_cpu_pd_node_t psci_non_cpu_pd_nodes[PSCI_NUM_NON_CPU_PWR_DOMAINS]; -cpu_pd_node_t psci_cpu_pd_nodes[PLATFORM_CORE_COUNT]; -``` - -### Populating the power domain tree - -The `populate_power_domain_tree()` function in `psci_setup.c` implements the -algorithm to parse the power domain descriptor exported by the platform to -populate the two arrays. It is essentially a breadth-first-search. The nodes for -each level starting from the root are laid out one after another in the -`psci_non_cpu_pd_nodes` and `psci_cpu_pd_nodes` arrays as follows: - -``` -psci_non_cpu_pd_nodes -> [[Level 3 nodes][Level 2 nodes][Level 1 nodes]] -psci_cpu_pd_nodes -> [Level 0 nodes] -``` - -For the example power domain tree illustrated above, the `psci_cpu_pd_nodes` -will be populated as follows. The value in each entry is the index of the parent -node. Other fields have been ignored for simplicity. - -``` - +-------------+ ^ - CPU0 | 3 | | - +-------------+ | - CPU1 | 3 | | - +-------------+ | - CPU2 | 3 | | - +-------------+ | - CPU3 | 4 | | - +-------------+ | - CPU4 | 4 | | - +-------------+ | - CPU5 | 4 | | PLATFORM_CORE_COUNT - +-------------+ | - CPU6 | 5 | | - +-------------+ | - CPU7 | 5 | | - +-------------+ | - CPU8 | 5 | | - +-------------+ | - CPU9 | 6 | | - +-------------+ | - CPU10 | 6 | | - +-------------+ | - CPU11 | 6 | | - +-------------+ | - CPU12 | 6 | v - +-------------+ -``` - -The `psci_non_cpu_pd_nodes` array will be populated as follows. The value in -each entry is the index of the parent node. - -``` - +-------------+ ^ - PD0 | -1 | | - +-------------+ | - PD1 | 0 | | - +-------------+ | - PD2 | 0 | | - +-------------+ | - PD3 | 1 | | PLAT_NUM_POWER_DOMAINS - - +-------------+ | PLATFORM_CORE_COUNT - PD4 | 1 | | - +-------------+ | - PD5 | 2 | | - +-------------+ | - PD6 | 2 | | - +-------------+ v -``` - -Each core can find its node in the `psci_cpu_pd_nodes` array using the -`plat_my_core_pos()` function. When a core is turned on, the normal world -provides an MPIDR. The `plat_core_pos_by_mpidr()` function is used to validate -the MPIDR before using it to find the corresponding core node. The non-core power -domain nodes do not need to be identified. - -- - - - - - - - - - - - - - - - - - - - - - - - - - - -_Copyright (c) 2017, ARM Limited and Contributors. All rights reserved._ diff --git a/docs/reset-design.md b/docs/reset-design.md deleted file mode 100644 index 3e45d417..00000000 --- a/docs/reset-design.md +++ /dev/null @@ -1,172 +0,0 @@ -ARM Trusted Firmware Reset Design -================================= - -1. [Introduction](#1--introduction) -2. [General reset code flow](#2--general-reset-code-flow) -3. [Programmable CPU reset address](#3--programmable-cpu-reset-address) -4. [Cold boot on a single CPU](#4--cold-boot-on-a-single-cpu) -5. [Programmable CPU reset address, Cold boot on a single CPU](#5--programmable-cpu-reset-address-cold-boot-on-a-single-cpu) -6. [Using BL31 entrypoint as the reset address](#6--using-bl31-entrypoint-as-the-reset-address) - - -1. Introduction ----------------- - -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. - - -2. General reset code flow ---------------------------- - -The ARM Trusted Firmware (TF) reset code is implemented in BL1 by default. The -following high-level diagram illustrates this: - - - -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. - - -3. 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: - - - -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`. - - -4. 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: - - - -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`. - - -5. Programmable CPU reset address, Cold boot on a single CPU -------------------------------------------------------------- - -It is obviously possible to combine both optimisations on platforms that have -a programmable CPU reset address and which release a single CPU out of reset. -This results in the following boot flow: - - - -To enable this boot flow, compile the TF with both `COLD_BOOT_SINGLE_CPU=1` -and `PROGRAMMABLE_RESET_ADDRESS=1`. These options only affect the TF reset -image, which is BL1 by default or BL31 if `RESET_TO_BL31=1`. - - -6. 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._ - - -[User Guide]: user-guide.md -[Firmware Design]: firmware-design.md diff --git a/docs/rt-svc-writers-guide.md b/docs/rt-svc-writers-guide.md deleted file mode 100644 index ea599ed9..00000000 --- a/docs/rt-svc-writers-guide.md +++ /dev/null @@ -1,307 +0,0 @@ -EL3 Runtime Service Writers Guide for ARM Trusted Firmware -========================================================== - -Contents --------- - -1. [Introduction](#1--introduction) -2. [Owning Entities, Call Types and Function IDs](#2--owning-entities-call-types-and-function-ids) -3. [Getting started](#3--getting-started) -4. [Registering a runtime service](#4--registering-a-runtime-service) -5. [Initializing a runtime service](#5-initializing-a-runtime-service) -6. [Handling runtime service requests](#6--handling-runtime-service-requests) -7. [Services that contain multiple sub-services](#7--services-that-contain-multiple-sub-services) -8. [Secure-EL1 Payload Dispatcher service (SPD)](#8--secure-el1-payload-dispatcher-service-spd) - -- - - - - - - - - - - - - - - - - - - -1. Introduction ----------------- - -This document describes how to add a runtime service to the EL3 Runtime -Firmware component of ARM Trusted Firmware (BL31). - -Software executing in the normal world and in the trusted world at exception -levels lower than EL3 will request runtime services using the Secure Monitor -Call (SMC) instruction. These requests will follow the convention described in -the SMC Calling Convention PDD ([SMCCC]). The [SMCCC] assigns function -identifiers to each SMC request and describes how arguments are passed and -results are returned. - -SMC Functions are grouped together based on the implementor of the service, for -example a subset of the Function IDs are designated as "OEM Calls" (see [SMCCC] -for full details). The EL3 runtime services framework in BL31 enables the -independent implementation of services for each group, which are then compiled -into the BL31 image. This simplifies the integration of common software from -ARM to support [PSCI], Secure Monitor for a Trusted OS and SoC specific -software. The common runtime services framework ensures that SMC Functions are -dispatched to their respective service implementation - the [Firmware Design] -provides details of how this is achieved. - -The interface and operation of the runtime services depends heavily on the -concepts and definitions described in the [SMCCC], in particular SMC Function -IDs, Owning Entity Numbers (OEN), Fast and Standard calls, and the SMC32 and -SMC64 calling conventions. Please refer to that document for a full explanation -of these terms. - - -2. Owning Entities, Call Types and Function IDs ------------------------------------------------- - -The SMC Function Identifier includes a OEN field. These values and their -meaning are described in [SMCCC] and summarized in table 1 below. Some entities -are allocated a range of of OENs. The OEN must be interpreted in conjunction -with the SMC call type, which is either _Fast_ or _Yielding_. Fast calls are -uninterruptible whereas Yielding calls can be pre-empted. The majority of -Owning Entities only have allocated ranges for Fast calls: Yielding calls are -reserved exclusively for Trusted OS providers or for interoperability with -legacy 32-bit software that predates the [SMCCC]. - - Type OEN Service - Fast 0 ARM Architecture calls - Fast 1 CPU Service calls - Fast 2 SiP Service calls - Fast 3 OEM Service calls - Fast 4 Standard Service calls - Fast 5-47 Reserved for future use - Fast 48-49 Trusted Application calls - Fast 50-63 Trusted OS calls - - Yielding 0- 1 Reserved for existing ARMv7 calls - Yielding 2-63 Trusted OS Standard Calls - -_Table 1: Service types and their corresponding Owning Entity Numbers_ - -Each individual entity can allocate the valid identifiers within the entity -range as they need - it is not necessary to coordinate with other entities of -the same type. For example, two SoC providers can use the same Function ID -within the SiP Service calls OEN range to mean different things - as these -calls should be specific to the SoC. The Standard Runtime Calls OEN is used for -services defined by ARM standards, such as [PSCI]. - -The SMC Function ID also indicates whether the call has followed the SMC32 -calling convention, where all parameters are 32-bit, or the SMC64 calling -convention, where the parameters are 64-bit. The framework identifies and -rejects invalid calls that use the SMC64 calling convention but that originate -from an AArch32 caller. - -The EL3 runtime services framework uses the call type and OEN to identify a -specific handler for each SMC call, but it is expected that an individual -handler will be responsible for all SMC Functions within a given service type. - - -3. Getting started -------------------- - -ARM Trusted Firmware has a [`services`] directory in the source tree under which -each owning entity can place the implementation of its runtime service. The -[PSCI] implementation is located here in the [`lib/psci`] directory. - -Runtime service sources will need to include the [`runtime_svc.h`] header file. - - -4. Registering a runtime service ---------------------------------- - -A runtime service is registered using the `DECLARE_RT_SVC()` macro, specifying -the name of the service, the range of OENs covered, the type of service and -initialization and call handler functions. - - #define DECLARE_RT_SVC(_name, _start, _end, _type, _setup, _smch) - -* `_name` is used to identify the data structure declared by this macro, and - is also used for diagnostic purposes - -* `_start` and `_end` values must be based on the `OEN_*` values defined in - [`smcc.h`] - -* `_type` must be one of `SMC_TYPE_FAST` or `SMC_TYPE_YIELD` - -* `_setup` is the initialization function with the `rt_svc_init` signature: - - typedef int32_t (*rt_svc_init)(void); - -* `_smch` is the SMC handler function with the `rt_svc_handle` signature: - - typedef uintptr_t (*rt_svc_handle_t)(uint32_t smc_fid, - u_register_t x1, u_register_t x2, - u_register_t x3, u_register_t x4, - void *cookie, - void *handle, - u_register_t flags); - -Details of the requirements and behavior of the two callbacks is provided in -the following sections. - -During initialization the services framework validates each declared service -to ensure that the following conditions are met: - -1. The `_start` OEN is not greater than the `_end` OEN -2. The `_end` OEN does not exceed the maximum OEN value (63) -3. The `_type` is one of `SMC_TYPE_FAST` or `SMC_TYPE_YIELD` -4. `_setup` and `_smch` routines have been specified - -[`std_svc_setup.c`] provides an example of registering a runtime service: - - /* Register Standard Service Calls as runtime service */ - DECLARE_RT_SVC( - std_svc, - OEN_STD_START, - OEN_STD_END, - SMC_TYPE_FAST, - std_svc_setup, - std_svc_smc_handler - ); - - -5. Initializing a runtime service ---------------------------------- - -Runtime services are initialized once, during cold boot, by the primary CPU -after platform and architectural initialization is complete. The framework -performs basic validation of the declared service before calling -the service initialization function (`_setup` in the declaration). This -function must carry out any essential EL3 initialization prior to receiving a -SMC Function call via the handler function. - -On success, the initialization function must return `0`. Any other return value -will cause the framework to issue a diagnostic: - - Error initializing runtime service <name of the service> - -and then ignore the service - the system will continue to boot but SMC calls -will not be passed to the service handler and instead return the _Unknown SMC -Function ID_ result `0xFFFFFFFF`. - -If the system must not be allowed to proceed without the service, the -initialization function must itself cause the firmware boot to be halted. - -If the service uses per-CPU data this must either be initialized for all CPUs -during this call, or be done lazily when a CPU first issues an SMC call to that -service. - - -6. Handling runtime service requests -------------------------------------- - -SMC calls for a service are forwarded by the framework to the service's SMC -handler function (`_smch` in the service declaration). This function must have -the following signature: - - typedef uintptr_t (*rt_svc_handle_t)(uint32_t smc_fid, - u_register_t x1, u_register_t x2, - u_register_t x3, u_register_t x4, - void *cookie, - void *handle, - u_register_t flags); - -The handler is responsible for: - -1. Determining that `smc_fid` is a valid and supported SMC Function ID, - otherwise completing the request with the _Unknown SMC Function ID_: - - SMC_RET1(handle, SMC_UNK); - -2. Determining if the requested function is valid for the calling security - state. SMC Calls can be made from both the normal and trusted worlds and - the framework will forward all calls to the service handler. - - The `flags` parameter to this function indicates the caller security state - in bit[0], where a value of `1` indicates a non-secure caller. The - `is_caller_secure(flags)` and `is_caller_non_secure(flags)` can be used to - test this condition. - - If invalid, the request should be completed with: - - SMC_RET1(handle, SMC_UNK); - -3. Truncating parameters for calls made using the SMC32 calling convention. - Such calls can be determined by checking the CC field in bit[30] of the - `smc_fid` parameter, for example by using: - - if (GET_SMC_CC(smc_fid) == SMC_32) ... - - For such calls, the upper bits of the parameters x1-x4 and the saved - parameters X5-X7 are UNDEFINED and must be explicitly ignored by the - handler. This can be done by truncating the values to a suitable 32-bit - integer type before use, for example by ensuring that functions defined - to handle individual SMC Functions use appropriate 32-bit parameters. - -4. Providing the service requested by the SMC Function, utilizing the - immediate parameters x1-x4 and/or the additional saved parameters X5-X7. - The latter can be retrieved using the `SMC_GET_GP(handle, ref)` function, - supplying the appropriate `CTX_GPREG_Xn` reference, e.g. - - uint64_t x6 = SMC_GET_GP(handle, CTX_GPREG_X6); - -5. Implementing the standard SMC32 Functions that provide information about - the implementation of the service. These are the Call Count, Implementor - UID and Revision Details for each service documented in section 6 of the - [SMCCC]. - - The ARM Trusted Firmware expects owning entities to follow this - recommendation. - -5. Returning the result to the caller. The [SMCCC] allows for up to 256 bits - of return value in SMC64 using X0-X3 and 128 bits in SMC32 using W0-W3. The - framework provides a family of macros to set the multi-register return - value and complete the handler: - - SMC_RET1(handle, x0); - SMC_RET2(handle, x0, x1); - SMC_RET3(handle, x0, x1, x2); - SMC_RET4(handle, x0, x1, x2, x3); - -The `cookie` parameter to the handler is reserved for future use and can be -ignored. The `handle` is returned by the SMC handler - completion of the -handler function must always be via one of the `SMC_RETn()` macros. - -NOTE: The PSCI and Test Secure-EL1 Payload Dispatcher services do not follow -all of the above requirements yet. - - -7. Services that contain multiple sub-services ------------------------------------------------ - -It is possible that a single owning entity implements multiple sub-services. For -example, the Standard calls service handles `0x84000000`-`0x8400FFFF` and -`0xC4000000`-`0xC400FFFF` functions. Within that range, the [PSCI] service -handles the `0x84000000`-`0x8400001F` and `0xC4000000`-`0xC400001F` functions. -In that respect, [PSCI] is a 'sub-service' of the Standard calls service. In -future, there could be additional such sub-services in the Standard calls -service which perform independent functions. - -In this situation it may be valuable to introduce a second level framework to -enable independent implementation of sub-services. Such a framework might look -very similar to the current runtime services framework, but using a different -part of the SMC Function ID to identify the sub-service. Trusted Firmware does -not provide such a framework at present. - - -8. Secure-EL1 Payload Dispatcher service (SPD) ------------------------------------------------ - -Services that handle SMC Functions targeting a Trusted OS, Trusted Application, -or other Secure-EL1 Payload are special. These services need to manage the -Secure-EL1 context, provide the _Secure Monitor_ functionality of switching -between the normal and secure worlds, deliver SMC Calls through to Secure-EL1 -and generally manage the Secure-EL1 Payload through CPU power-state transitions. - -TODO: Provide details of the additional work required to implement a SPD and -the BL31 support for these services. Or a reference to the document that will -provide this information.... - - -- - - - - - - - - - - - - - - - - - - - - - - - - - - -_Copyright (c) 2014-2015, ARM Limited and Contributors. All rights reserved._ - - -[Firmware Design]: ./firmware-design.md -[`services`]: ../services -[`lib/psci`]: ../lib/psci -[`std_svc_setup.c`]: ../services/std_svc/std_svc_setup.c -[`runtime_svc.h`]: ../include/common/runtime_svc.h -[`smcc.h`]: ../include/lib/smcc.h -[PSCI]: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf "Power State Coordination Interface PDD (ARM DEN 0022C)" -[SMCCC]: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html "SMC Calling Convention PDD (ARM DEN 0028A)" diff --git a/docs/spd/optee-dispatcher.md b/docs/spd/optee-dispatcher.md deleted file mode 100644 index 1971d9a6..00000000 --- a/docs/spd/optee-dispatcher.md +++ /dev/null @@ -1,13 +0,0 @@ -OP-TEE Dispatcher -================= - -[OP-TEE OS] is a Trusted OS running as Secure EL1. - -To build and execute OP-TEE follow the instructions at -[OP-TEE build.git][OP-TEE OS] - -- - - - - - - - - - - - - - - - - - - - - - - - - - - -_Copyright (c) 2014-2017, ARM Limited and Contributors. All rights reserved._ - -[OP-TEE OS]: https://github.com/OP-TEE/build diff --git a/docs/spd/tlk-dispatcher.md b/docs/spd/tlk-dispatcher.md deleted file mode 100644 index 40c83444..00000000 --- a/docs/spd/tlk-dispatcher.md +++ /dev/null @@ -1,70 +0,0 @@ -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 - diff --git a/docs/spd/trusty-dispatcher.md b/docs/spd/trusty-dispatcher.md deleted file mode 100644 index 0258959d..00000000 --- a/docs/spd/trusty-dispatcher.md +++ /dev/null @@ -1,15 +0,0 @@ -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. - - diff --git a/docs/trusted-board-boot.md b/docs/trusted-board-boot.md deleted file mode 100644 index 833b5dbf..00000000 --- a/docs/trusted-board-boot.md +++ /dev/null @@ -1,251 +0,0 @@ -Trusted Board Boot Design Guide -=============================== - -Contents : - -1. [Introduction](#1--introduction) -2. [Chain of Trust](#2--chain-of-trust) -3. [Trusted Board Boot Sequence](#3--trusted-board-boot-sequence) -4. [Authentication Framework](#4--authentication-framework) -5. [Certificate Generation Tool](#5--certificate-generation-tool) - - -1. Introduction ----------------- - -The Trusted Board Boot (TBB) feature prevents malicious firmware from running on -the platform by authenticating all firmware images up to and including the -normal world bootloader. It does this by establishing a Chain of Trust using -Public-Key-Cryptography Standards (PKCS). - -This document describes the design of ARM Trusted Firmware TBB, which is an -implementation of the Trusted Board Boot Requirements (TBBR) specification, -ARM DEN0006C-1. It should be used in conjunction with the [Firmware Update] -design document, which implements a specific aspect of the TBBR. - - -2. Chain of Trust ------------------- - -A Chain of Trust (CoT) starts with a set of implicitly trusted components. On -the ARM development platforms, these components are: - -* A SHA-256 hash of the Root of Trust Public Key (ROTPK). It is stored in the - trusted root-key storage registers. - -* The BL1 image, on the assumption that it resides in ROM so cannot be - tampered with. - -The remaining components in the CoT are either certificates or boot loader -images. The certificates follow the [X.509 v3] standard. This standard -enables adding custom extensions to the certificates, which are used to store -essential information to establish the CoT. - -In the TBB CoT all certificates are self-signed. There is no need for a -Certificate Authority (CA) because the CoT is not established by verifying the -validity of a certificate's issuer but by the content of the certificate -extensions. To sign the certificates, the PKCS#1 SHA-256 with RSA Encryption -signature scheme is used with a RSA key length of 2048 bits. Future version of -Trusted Firmware will support additional cryptographic algorithms. - -The certificates are categorised as "Key" and "Content" certificates. Key -certificates are used to verify public keys which have been used to sign content -certificates. Content certificates are used to store the hash of a boot loader -image. An image can be authenticated by calculating its hash and matching it -with the hash extracted from the content certificate. The SHA-256 function is -used to calculate all hashes. The public keys and hashes are included as -non-standard extension fields in the [X.509 v3] certificates. - -The keys used to establish the CoT are: - -* **Root of trust key** - - The private part of this key is used to sign the BL2 content certificate and - the trusted key certificate. The public part is the ROTPK. - -* **Trusted world key** - - The private part is used to sign the key certificates corresponding to the - secure world images (SCP_BL2, BL31 and BL32). The public part is stored in - one of the extension fields in the trusted world certificate. - -* **Non-trusted world key** - - The private part is used to sign the key certificate corresponding to the - non secure world image (BL33). The public part is stored in one of the - extension fields in the trusted world certificate. - -* **BL3-X keys** - - For each of SCP_BL2, BL31, BL32 and BL33, the private part is used to - sign the content certificate for the BL3-X image. The public part is stored - in one of the extension fields in the corresponding key certificate. - -The following images are included in the CoT: - -* BL1 -* BL2 -* SCP_BL2 (optional) -* BL31 -* BL33 -* BL32 (optional) - -The following certificates are used to authenticate the images. - -* **BL2 content certificate** - - It is self-signed with the private part of the ROT key. It contains a hash - of the BL2 image. - -* **Trusted key certificate** - - It is self-signed with the private part of the ROT key. It contains the - public part of the trusted world key and the public part of the non-trusted - world key. - -* **SCP_BL2 key certificate** - - It is self-signed with the trusted world key. It contains the public part of - the SCP_BL2 key. - -* **SCP_BL2 content certificate** - - It is self-signed with the SCP_BL2 key. It contains a hash of the SCP_BL2 - image. - -* **BL31 key certificate** - - It is self-signed with the trusted world key. It contains the public part of - the BL31 key. - -* **BL31 content certificate** - - It is self-signed with the BL31 key. It contains a hash of the BL31 image. - -* **BL32 key certificate** - - It is self-signed with the trusted world key. It contains the public part of - the BL32 key. - -* **BL32 content certificate** - - It is self-signed with the BL32 key. It contains a hash of the BL32 image. - -* **BL33 key certificate** - - It is self-signed with the non-trusted world key. It contains the public - part of the BL33 key. - -* **BL33 content certificate** - - It is self-signed with the BL33 key. It contains a hash of the BL33 image. - -The SCP_BL2 and BL32 certificates are optional, but they must be present if the -corresponding SCP_BL2 or BL32 images are present. - - -3. Trusted Board Boot Sequence -------------------------------- - -The CoT is verified through the following sequence of steps. The system panics -if any of the steps fail. - -* BL1 loads and verifies the BL2 content certificate. The issuer public key is - read from the verified certificate. A hash of that key is calculated and - compared with the hash of the ROTPK read from the trusted root-key storage - registers. If they match, the BL2 hash is read from the certificate. - - Note: the matching operation is platform specific and is currently - unimplemented on the ARM development platforms. - -* BL1 loads the BL2 image. Its hash is calculated and compared with the hash - read from the certificate. Control is transferred to the BL2 image if all - the comparisons succeed. - -* BL2 loads and verifies the trusted key certificate. The issuer public key is - read from the verified certificate. A hash of that key is calculated and - compared with the hash of the ROTPK read from the trusted root-key storage - registers. If the comparison succeeds, BL2 reads and saves the trusted and - non-trusted world public keys from the verified certificate. - -The next two steps are executed for each of the SCP_BL2, BL31 & BL32 images. -The steps for the optional SCP_BL2 and BL32 images are skipped if these images -are not present. - -* BL2 loads and verifies the BL3x key certificate. The certificate signature - is verified using the trusted world public key. If the signature - verification succeeds, BL2 reads and saves the BL3x public key from the - certificate. - -* BL2 loads and verifies the BL3x content certificate. The signature is - verified using the BL3x public key. If the signature verification succeeds, - BL2 reads and saves the BL3x image hash from the certificate. - -The next two steps are executed only for the BL33 image. - -* BL2 loads and verifies the BL33 key certificate. If the signature - verification succeeds, BL2 reads and saves the BL33 public key from the - certificate. - -* BL2 loads and verifies the BL33 content certificate. If the signature - verification succeeds, BL2 reads and saves the BL33 image hash from the - certificate. - -The next step is executed for all the boot loader images. - -* BL2 calculates the hash of each image. It compares it with the hash obtained - from the corresponding content certificate. The image authentication succeeds - if the hashes match. - -The Trusted Board Boot implementation spans both generic and platform-specific -BL1 and BL2 code, and in tool code on the host build machine. The feature is -enabled through use of specific build flags as described in the [User Guide]. - -On the host machine, a tool generates the certificates, which are included in -the FIP along with the boot loader images. These certificates are loaded in -Trusted SRAM using the IO storage framework. They are then verified by an -Authentication module included in the Trusted Firmware. - -The mechanism used for generating the FIP and the Authentication module are -described in the following sections. - - -4. Authentication Framework ----------------------------- - -The authentication framework included in the Trusted Firmware provides support -to implement the desired trusted boot sequence. ARM platforms use this framework -to implement the boot requirements specified in the TBBR-client document. - -More information about the authentication framework can be found in the -[Auth Framework] document. - - -5. Certificate Generation Tool -------------------------------- - -The `cert_create` tool is built and runs on the host machine as part of the -Trusted Firmware build process when `GENERATE_COT=1`. It takes the boot loader -images and keys as inputs (keys must be in PEM format) and generates the -certificates (in DER format) required to establish the CoT. New keys can be -generated by the tool in case they are not provided. The certificates are then -passed as inputs to the `fiptool` utility for creating the FIP. - -The certificates are also stored individually in the in the output build -directory. - -The tool resides in the `tools/cert_create` directory. It uses OpenSSL SSL -library version 1.0.1 or later to generate the X.509 certificates. Instructions -for building and using the tool can be found in the [User Guide]. - - -- - - - - - - - - - - - - - - - - - - - - - - - - - - -_Copyright (c) 2015, ARM Limited and Contributors. All rights reserved._ - - -[X.509 v3]: http://www.ietf.org/rfc/rfc5280.txt -[X.690]: http://www.itu.int/ITU-T/studygroups/com17/languages/X.690-0207.pdf -[Auth Framework]: auth-framework.md -[User Guide]: user-guide.md -[Firmware Update]: firmware-update.md diff --git a/docs/user-guide.md b/docs/user-guide.md deleted file mode 100644 index 678bb424..00000000 --- a/docs/user-guide.md +++ /dev/null @@ -1,1600 +0,0 @@ -ARM Trusted Firmware User Guide -=============================== - -Contents : - -1. [Introduction](#1--introduction) -2. [Host machine requirements](#2--host-machine-requirements) -3. [Tools](#3--tools) -4. [Getting the Trusted Firmware source code](#4--getting-the-trusted-firmware-source-code) -5. [Building the Trusted Firmware](#5--building-the-trusted-firmware) -6. [Building a FIP for Juno and FVP](#6--building-a-fip-for-juno-and-fvp) -7. [EL3 payloads alternative boot flow](#7--el3-payloads-alternative-boot-flow) -8. [Preloaded BL33 alternative boot flow](#8--preloaded-bl33-alternative-boot-flow) -9. [Running the software on FVP](#9--running-the-software-on-fvp) -10. [Running the software on Juno](#10--running-the-software-on-juno) - - -1. Introduction ----------------- - -This document describes how to build ARM Trusted Firmware (TF) and run it with a -tested set of other software components using defined configurations on the Juno -ARM development platform and ARM Fixed Virtual Platform (FVP) models. It is -possible to use other software components, configurations and platforms but that -is outside the scope of this document. - -This document assumes that the reader has previous experience running a fully -bootable Linux software stack on Juno or FVP using the prebuilt binaries and -filesystems provided by [Linaro][Linaro Release Notes]. Further information may -be found in the [Instructions for using the Linaro software deliverables] -[Linaro SW Instructions]. It also assumes that the user understands the role of -the different software components required to boot a Linux system: - -* Specific firmware images required by the platform (e.g. SCP firmware on Juno) -* Normal world bootloader (e.g. UEFI or U-Boot) -* Device tree -* Linux kernel image -* Root filesystem - -Note: the ARM TF v1.3 release was tested with Linaro Release 16.06, and the -latest version of ARM TF is tested with Linaro Release 17.01. - -This document also assumes that the user is familiar with the FVP models and -the different command line options available to launch the model. - -This document should be used in conjunction with the [Firmware Design]. - - -2. Host machine requirements ------------------------------ - -The minimum recommended machine specification for building the software and -running the FVP models is a dual-core processor running at 2GHz with 12GB of -RAM. For best performance, use a machine with a quad-core processor running at -2.6GHz with 16GB of RAM. - -The software has been tested on Ubuntu 14.04 LTS (64-bit). Packages used for -building the software were installed from that distribution unless otherwise -specified. - -The software has also been built on Windows 7 Enterprise SP1, using CMD.EXE, -Cygwin, and Msys (MinGW) shells, using version 4.9.1 of the GNU toolchain. - -3. Tools ---------- - -Install the required packages to build Trusted Firmware with the following -command: - - sudo apt-get install build-essential gcc make git libssl-dev - -Download and install the AArch32 or AArch64 little-endian GCC cross compiler. -The [Linaro Release Notes][Linaro Release Notes] documents which version of the -compiler to use for a given Linaro Release. Also, these -[Linaro instructions][Linaro SW Instructions] provide further guidance. - -Optionally, Trusted Firmware can be built using clang or ARM Compiler 6. -See instructions below on how to switch the default compiler. - -In addition, the following optional packages and tools may be needed: - -* `device-tree-compiler` package if you need to rebuild the Flattened Device - Tree (FDT) source files (`.dts` files) provided with this software. - -* For debugging, ARM [Development Studio 5 (DS-5)][DS-5]. - - -4. Getting the Trusted Firmware source code --------------------------------------------- - -Download the Trusted Firmware source code from Github: - - git clone https://github.com/ARM-software/arm-trusted-firmware.git - - -5. Building the Trusted Firmware ---------------------------------- - -* Before building Trusted Firmware, the environment variable `CROSS_COMPILE` - must point to the Linaro cross compiler. - - For AArch64: - - export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu- - - For AArch32: - - export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-linux-gnueabihf- - - It is possible to build Trusted Firmware using clang or ARM Compiler 6. - To do so `CC` needs to point to the clang or armclang binary. Only the - compiler is switched; the assembler and linker need to be provided by - the GNU toolchain, thus `CROSS_COMPILE` should be set as described above. - - ARM Compiler 6 will be selected when the base name of the path assigned - to `CC` matches the string 'armclang'. - - For AArch64 using ARM Compiler 6: - - export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu- - make CC=<path-to-armclang>/bin/armclang PLAT=<platform> all - - Clang will be selected when the base name of the path assigned to `CC` - contains the string 'clang'. This is to allow both clang and clang-X.Y - to work. - - For AArch64 using clang: - - export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu- - make CC=<path-to-clang>/bin/clang PLAT=<platform> all - -* Change to the root directory of the Trusted Firmware source tree and build. - - For AArch64: - - make PLAT=<platform> all - - For AArch32: - - make PLAT=<platform> ARCH=aarch32 AARCH32_SP=sp_min all - - - Notes: - - * If `PLAT` is not specified, `fvp` is assumed by default. See the - [Summary of build options](#summary-of-build-options) for more information on available build - options. - - * (AArch32 only) Currently only `PLAT=fvp` is supported. - - * (AArch32 only) `AARCH32_SP` is the AArch32 EL3 Runtime Software and it - corresponds to the BL32 image. A minimal `AARCH32_SP`, sp_min, is - provided by ARM Trusted Firmware to demonstrate how PSCI Library can - be integrated with an AArch32 EL3 Runtime Software. Some AArch32 EL3 - Runtime Software may include other runtime services, for example - Trusted OS services. A guide to integrate PSCI library with AArch32 - EL3 Runtime Software can be found [here][PSCI Lib Integration]. - - * (AArch64 only) The TSP (Test Secure Payload), corresponding to the BL32 - image, is not compiled in by default. Refer to the [Building the Test - Secure Payload](#building-the-test-secure-payload) section below. - - * By default this produces a release version of the build. To produce a - debug version instead, refer to the "Debugging options" section below. - - * The build process creates products in a `build` directory tree, building - the objects and binaries for each boot loader stage in separate - sub-directories. The following boot loader binary files are created - from the corresponding ELF files: - - * `build/<platform>/<build-type>/bl1.bin` - * `build/<platform>/<build-type>/bl2.bin` - * `build/<platform>/<build-type>/bl31.bin` (AArch64 only) - * `build/<platform>/<build-type>/bl32.bin` (mandatory for AArch32) - - where `<platform>` is the name of the chosen platform and `<build-type>` - is either `debug` or `release`. The actual number of images might differ - depending on the platform. - -* Build products for a specific build variant can be removed using: - - make DEBUG=<D> PLAT=<platform> clean - - ... where `<D>` is `0` or `1`, as specified when building. - - The build tree can be removed completely using: - - make realclean - -### Summary of build options - -ARM Trusted Firmware build system supports the following build options. Unless -mentioned otherwise, these options are expected to be specified at the build -command line and are not to be modified in any component makefiles. Note that -the build system doesn't track dependency for build options. Therefore, if any -of the build options are changed from a previous build, a clean build must be -performed. - -#### Common build options - -* `AARCH32_SP` : Choose the AArch32 Secure Payload component to be built as - as the BL32 image when `ARCH=aarch32`. The value should be the path to the - directory containing the SP source, relative to the `bl32/`; the directory - is expected to contain a makefile called `<aarch32_sp-value>.mk`. - -* `ARCH` : Choose the target build architecture for ARM Trusted Firmware. - It can take either `aarch64` or `aarch32` as values. By default, it is - defined to `aarch64`. - -* `ARM_CCI_PRODUCT_ID`: Choice of ARM CCI product used by the platform. This - is used to determine the number of valid slave interfaces available in the - ARM CCI driver. Default is 400 (that is, CCI-400). - -* `ARM_ARCH_MAJOR`: The major version of ARM Architecture to target when - compiling ARM Trusted Firmware. Its value must be numeric, and defaults to - 8 . See also, _ARMv8 Architecture Extensions_ in [Firmware Design]. - -* `ARM_ARCH_MINOR`: The minor version of ARM Architecture to target when - compiling ARM Trusted Firmware. Its value must be a numeric, and defaults - to 0. See also, _ARMv8 Architecture Extensions_ in [Firmware Design]. - -* `ARM_GIC_ARCH`: Choice of ARM GIC architecture version used by the ARM - Legacy GIC driver for implementing the platform GIC API. This API is used - by the interrupt management framework. Default is 2 (that is, version 2.0). - This build option is deprecated. - -* `ARM_PLAT_MT`: This flag determines whether the ARM platform layer has to - cater for the multi-threading `MT` bit when accessing MPIDR. When this - flag is set, the functions which deal with MPIDR assume that the `MT` bit - in MPIDR is set and access the bit-fields in MPIDR accordingly. Default - value of this flag is 0. - -* `BL2`: This is an optional build option which specifies the path to BL2 - image for the `fip` target. In this case, the BL2 in the ARM Trusted - Firmware will not be built. - -* `BL2U`: This is an optional build option which specifies the path to - BL2U image. In this case, the BL2U in the ARM Trusted Firmware will not - be built. - -* `BL31`: This is an optional build option which specifies the path to - BL31 image for the `fip` target. In this case, the BL31 in the ARM - Trusted Firmware will not be built. - -* `BL31_KEY`: This option is used when `GENERATE_COT=1`. It specifies the - file that contains the BL31 private key in PEM format. If `SAVE_KEYS=1`, - this file name will be used to save the key. - -* `BL32`: This is an optional build option which specifies the path to - BL32 image for the `fip` target. In this case, the BL32 in the ARM - Trusted Firmware will not be built. - -* `BL32_KEY`: This option is used when `GENERATE_COT=1`. It specifies the - file that contains the BL32 private key in PEM format. If `SAVE_KEYS=1`, - this file name will be used to save the key. - -* `BL33`: Path to BL33 image in the host file system. This is mandatory for - `fip` target in case the BL2 from ARM Trusted Firmware is used. - -* `BL33_KEY`: This option is used when `GENERATE_COT=1`. It specifies the - file that contains the BL33 private key in PEM format. If `SAVE_KEYS=1`, - this file name will be used to save the key. - -* `BUILD_MESSAGE_TIMESTAMP`: String used to identify the time and date of the - compilation of each build. It must be set to a C string (including quotes - where applicable). Defaults to a string that contains the time and date of - the compilation. - -* `BUILD_STRING`: Input string for VERSION_STRING, which allows the TF build - to be uniquely identified. Defaults to the current git commit id. - -* `CFLAGS`: Extra user options appended on the compiler's command line in - addition to the options set by the build system. - -* `COLD_BOOT_SINGLE_CPU`: This option indicates whether the platform may - release several CPUs out of reset. It can take either 0 (several CPUs may be - brought up) or 1 (only one CPU will ever be brought up during cold reset). - Default is 0. If the platform always brings up a single CPU, there is no - need to distinguish between primary and secondary CPUs and the boot path can - be optimised. The `plat_is_my_cpu_primary()` and - `plat_secondary_cold_boot_setup()` platform porting interfaces do not need - to be implemented in this case. - -* `CRASH_REPORTING`: A non-zero value enables a console dump of processor - register state when an unexpected exception occurs during execution of - BL31. This option defaults to the value of `DEBUG` - i.e. by default - this is only enabled for a debug build of the firmware. - -* `CREATE_KEYS`: This option is used when `GENERATE_COT=1`. It tells the - certificate generation tool to create new keys in case no valid keys are - present or specified. Allowed options are '0' or '1'. Default is '1'. - -* `CTX_INCLUDE_AARCH32_REGS` : Boolean option that, when set to 1, will cause - the AArch32 system registers to be included when saving and restoring the - CPU context. The option must be set to 0 for AArch64-only platforms (that - is on hardware that does not implement AArch32, or at least not at EL1 and - higher ELs). Default value is 1. - -* `CTX_INCLUDE_FPREGS`: Boolean option that, when set to 1, will cause the FP - registers to be included when saving and restoring the CPU context. Default - is 0. - -* `DEBUG`: Chooses between a debug and release build. It can take either 0 - (release) or 1 (debug) as values. 0 is the default. - -* `EL3_PAYLOAD_BASE`: This option enables booting an EL3 payload instead of - the normal boot flow. It must specify the entry point address of the EL3 - payload. Please refer to the "Booting an EL3 payload" section for more - details. - -* `ENABLE_ASSERTIONS`: This option controls whether or not calls to `assert()` - are compiled out. For debug builds, this option defaults to 1, and calls to - `assert()` are left in place. For release builds, this option defaults to 0 - and calls to `assert()` function are compiled out. This option can be set - independently of `DEBUG`. It can also be used to hide any auxiliary code - that is only required for the assertion and does not fit in the assertion - itself. - -* `ENABLE_PMF`: Boolean option to enable support for optional Performance - Measurement Framework(PMF). Default is 0. - -* `ENABLE_PSCI_STAT`: Boolean option to enable support for optional PSCI - functions `PSCI_STAT_RESIDENCY` and `PSCI_STAT_COUNT`. Default is 0. - In the absence of an alternate stat collection backend, `ENABLE_PMF` must - be enabled. If `ENABLE_PMF` is set, the residency statistics are tracked in - software. - -* `ENABLE_RUNTIME_INSTRUMENTATION`: Boolean option to enable runtime - instrumentation which injects timestamp collection points into - Trusted Firmware to allow runtime performance to be measured. - Currently, only PSCI is instrumented. Enabling this option enables - the `ENABLE_PMF` build option as well. Default is 0. - -* `ENABLE_STACK_PROTECTOR`: String option to enable the stack protection - checks in GCC. Allowed values are "all", "strong" and "0" (default). - "strong" is the recommended stack protection level if this feature is - desired. 0 disables the stack protection. For all values other than 0, the - `plat_get_stack_protector_canary()` platform hook needs to be implemented. - The value is passed as the last component of the option - `-fstack-protector-$ENABLE_STACK_PROTECTOR`. - -* `ERROR_DEPRECATED`: This option decides whether to treat the usage of - deprecated platform APIs, helper functions or drivers within Trusted - Firmware as error. It can take the value 1 (flag the use of deprecated - APIs as error) or 0. The default is 0. - -* `FIP_NAME`: This is an optional build option which specifies the FIP - filename for the `fip` target. Default is `fip.bin`. - -* `FWU_FIP_NAME`: This is an optional build option which specifies the FWU - FIP filename for the `fwu_fip` target. Default is `fwu_fip.bin`. - -* `GENERATE_COT`: Boolean flag used to build and execute the `cert_create` - tool to create certificates as per the Chain of Trust described in - [Trusted Board Boot]. The build system then calls `fiptool` to - include the certificates in the FIP and FWU_FIP. Default value is '0'. - - Specify both `TRUSTED_BOARD_BOOT=1` and `GENERATE_COT=1` to include support - for the Trusted Board Boot feature in the BL1 and BL2 images, to generate - the corresponding certificates, and to include those certificates in the - FIP and FWU_FIP. - - Note that if `TRUSTED_BOARD_BOOT=0` and `GENERATE_COT=1`, the BL1 and BL2 - images will not include support for Trusted Board Boot. The FIP will still - include the corresponding certificates. This FIP can be used to verify the - Chain of Trust on the host machine through other mechanisms. - - Note that if `TRUSTED_BOARD_BOOT=1` and `GENERATE_COT=0`, the BL1 and BL2 - images will include support for Trusted Board Boot, but the FIP and FWU_FIP - will not include the corresponding certificates, causing a boot failure. - -* `HANDLE_EA_EL3_FIRST`: When defined External Aborts and SError Interrupts - will be always trapped in EL3 i.e. in BL31 at runtime. - -* `HW_ASSISTED_COHERENCY`: On most ARM systems to-date, platform-specific - software operations are required for CPUs to enter and exit coherency. - However, there exists newer systems where CPUs' entry to and exit from - coherency is managed in hardware. Such systems require software to only - initiate the operations, and the rest is managed in hardware, minimizing - active software management. In such systems, this boolean option enables ARM - Trusted Firmware to carry out build and run-time optimizations during boot - and power management operations. This option defaults to 0 and if it is - enabled, then it implies `WARMBOOT_ENABLE_DCACHE_EARLY` is also enabled. - -* `JUNO_AARCH32_EL3_RUNTIME`: This build flag enables you to execute EL3 - runtime software in AArch32 mode, which is required to run AArch32 on Juno. - By default this flag is set to '0'. Enabling this flag builds BL1 and BL2 in - AArch64 and facilitates the loading of `SP_MIN` and BL33 as AArch32 executable - images. - -* `LDFLAGS`: Extra user options appended to the linkers' command line in - addition to the one set by the build system. - -* `LOAD_IMAGE_V2`: Boolean option to enable support for new version (v2) of - image loading, which provides more flexibility and scalability around what - images are loaded and executed during boot. Default is 0. - Note: `TRUSTED_BOARD_BOOT` is currently only supported for AArch64 when - `LOAD_IMAGE_V2` is enabled. - -* `LOG_LEVEL`: Chooses the log level, which controls the amount of console log - output compiled into the build. This should be one of the following: - - 0 (LOG_LEVEL_NONE) - 10 (LOG_LEVEL_NOTICE) - 20 (LOG_LEVEL_ERROR) - 30 (LOG_LEVEL_WARNING) - 40 (LOG_LEVEL_INFO) - 50 (LOG_LEVEL_VERBOSE) - - All log output up to and including the log level is compiled into the build. - The default value is 40 in debug builds and 20 in release builds. - -* `NON_TRUSTED_WORLD_KEY`: This option is used when `GENERATE_COT=1`. It - specifies the file that contains the Non-Trusted World private key in PEM - format. If `SAVE_KEYS=1`, this file name will be used to save the key. - -* `NS_BL2U`: Path to NS_BL2U image in the host file system. This image is - optional. It is only needed if the platform makefile specifies that it - is required in order to build the `fwu_fip` target. - -* `NS_TIMER_SWITCH`: Enable save and restore for non-secure timer register - contents upon world switch. It can take either 0 (don't save and restore) or - 1 (do save and restore). 0 is the default. An SPD may set this to 1 if it - wants the timer registers to be saved and restored. - -* `PL011_GENERIC_UART`: Boolean option to indicate the PL011 driver that - the underlying hardware is not a full PL011 UART but a minimally compliant - generic UART, which is a subset of the PL011. The driver will not access - any register that is not part of the SBSA generic UART specification. - Default value is 0 (a full PL011 compliant UART is present). - -* `PLAT`: Choose a platform to build ARM Trusted Firmware for. The chosen - platform name must be subdirectory of any depth under `plat/`, and must - contain a platform makefile named `platform.mk`. - -* `PRELOADED_BL33_BASE`: This option enables booting a preloaded BL33 image - instead of the normal boot flow. When defined, it must specify the entry - point address for the preloaded BL33 image. This option is incompatible with - `EL3_PAYLOAD_BASE`. If both are defined, `EL3_PAYLOAD_BASE` has priority - over `PRELOADED_BL33_BASE`. - -* `PROGRAMMABLE_RESET_ADDRESS`: This option indicates whether the reset - vector address can be programmed or is fixed on the platform. It can take - either 0 (fixed) or 1 (programmable). Default is 0. If the platform has a - programmable reset address, it is expected that a CPU will start executing - code directly at the right address, both on a cold and warm reset. In this - case, there is no need to identify the entrypoint on boot and the boot path - can be optimised. The `plat_get_my_entrypoint()` platform porting interface - does not need to be implemented in this case. - -* `PSCI_EXTENDED_STATE_ID`: As per PSCI1.0 Specification, there are 2 formats - possible for the PSCI power-state parameter viz original and extended - State-ID formats. This flag if set to 1, configures the generic PSCI layer - to use the extended format. The default value of this flag is 0, which - means by default the original power-state format is used by the PSCI - implementation. This flag should be specified by the platform makefile - and it governs the return value of PSCI_FEATURES API for CPU_SUSPEND - smc function id. When this option is enabled on ARM platforms, the - option `ARM_RECOM_STATE_ID_ENC` needs to be set to 1 as well. - -* `RESET_TO_BL31`: Enable BL31 entrypoint as the CPU reset vector instead - of the BL1 entrypoint. It can take the value 0 (CPU reset to BL1 - entrypoint) or 1 (CPU reset to BL31 entrypoint). - The default value is 0. - -* `RESET_TO_SP_MIN`: SP_MIN is the minimal AArch32 Secure Payload provided in - ARM Trusted Firmware. This flag configures SP_MIN entrypoint as the CPU - reset vector instead of the BL1 entrypoint. It can take the value 0 (CPU - reset to BL1 entrypoint) or 1 (CPU reset to SP_MIN entrypoint). The default - value is 0. - -* `ROT_KEY`: This option is used when `GENERATE_COT=1`. It specifies the - file that contains the ROT private key in PEM format. If `SAVE_KEYS=1`, this - file name will be used to save the key. - -* `SAVE_KEYS`: This option is used when `GENERATE_COT=1`. It tells the - certificate generation tool to save the keys used to establish the Chain of - Trust. Allowed options are '0' or '1'. Default is '0' (do not save). - -* `SCP_BL2`: Path to SCP_BL2 image in the host file system. This image is optional. - If a SCP_BL2 image is present then this option must be passed for the `fip` - target. - -* `SCP_BL2_KEY`: This option is used when `GENERATE_COT=1`. It specifies the - file that contains the SCP_BL2 private key in PEM format. If `SAVE_KEYS=1`, - this file name will be used to save the key. - -* `SCP_BL2U`: Path to SCP_BL2U image in the host file system. This image is - optional. It is only needed if the platform makefile specifies that it - is required in order to build the `fwu_fip` target. - -* `SEPARATE_CODE_AND_RODATA`: Whether code and read-only data should be - isolated on separate memory pages. This is a trade-off between security and - memory usage. See "Isolating code and read-only data on separate memory - pages" section in [Firmware Design]. This flag is disabled by default and - affects all BL images. - -* `SPD`: Choose a Secure Payload Dispatcher component to be built into the - Trusted Firmware. This build option is only valid if `ARCH=aarch64`. The - value should be the path to the directory containing the SPD source, - relative to `services/spd/`; the directory is expected to - contain a makefile called `<spd-value>.mk`. - -* `SPIN_ON_BL1_EXIT`: This option introduces an infinite loop in BL1. It can - take either 0 (no loop) or 1 (add a loop). 0 is the default. This loop stops - execution in BL1 just before handing over to BL31. At this point, all - firmware images have been loaded in memory, and the MMU and caches are - turned off. Refer to the "Debugging options" section for more details. - -* `TRUSTED_BOARD_BOOT`: Boolean flag to include support for the Trusted Board - Boot feature. When set to '1', BL1 and BL2 images include support to load - and verify the certificates and images in a FIP, and BL1 includes support - for the Firmware Update. The default value is '0'. Generation and inclusion - of certificates in the FIP and FWU_FIP depends upon the value of the - `GENERATE_COT` option. - - Note: This option depends on `CREATE_KEYS` to be enabled. If the keys - already exist in disk, they will be overwritten without further notice. - -* `TRUSTED_WORLD_KEY`: This option is used when `GENERATE_COT=1`. It - specifies the file that contains the Trusted World private key in PEM - format. If `SAVE_KEYS=1`, this file name will be used to save the key. - -* `TSP_INIT_ASYNC`: Choose BL32 initialization method as asynchronous or - synchronous, (see "Initializing a BL32 Image" section in [Firmware - Design]). It can take the value 0 (BL32 is initialized using - synchronous method) or 1 (BL32 is initialized using asynchronous method). - Default is 0. - -* `TSP_NS_INTR_ASYNC_PREEMPT`: A non zero value enables the interrupt - routing model which routes non-secure interrupts asynchronously from TSP - to EL3 causing immediate preemption of TSP. The EL3 is responsible - for saving and restoring the TSP context in this routing model. The - default routing model (when the value is 0) is to route non-secure - interrupts to TSP allowing it to save its context and hand over - synchronously to EL3 via an SMC. - -* `USE_COHERENT_MEM`: This flag determines whether to include the coherent - memory region in the BL memory map or not (see "Use of Coherent memory in - Trusted Firmware" section in [Firmware Design]). It can take the value 1 - (Coherent memory region is included) or 0 (Coherent memory region is - excluded). Default is 1. - -* `V`: Verbose build. If assigned anything other than 0, the build commands - are printed. Default is 0. - -* `VERSION_STRING`: String used in the log output for each TF image. Defaults - to a string formed by concatenating the version number, build type and build - string. - -* `WARMBOOT_ENABLE_DCACHE_EARLY` : Boolean option to enable D-cache early on - the CPU after warm boot. This is applicable for platforms which do not - require interconnect programming to enable cache coherency (eg: single - cluster platforms). If this option is enabled, then warm boot path - enables D-caches immediately after enabling MMU. This option defaults to 0. - -* `ENABLE_SPE_FOR_LOWER_ELS` : Boolean option to enable Statistical Profiling - extensions. This is an optional architectural feature available only for - AArch64 8.2 onwards. This option defaults to 1 but is automatically - disabled when the target architecture is AArch32 or AArch64 8.0/8.1. - -#### ARM development platform specific build options - -* `ARM_BL31_IN_DRAM`: Boolean option to select loading of BL31 in TZC secured - DRAM. By default, BL31 is in the secure SRAM. Set this flag to 1 to load - BL31 in TZC secured DRAM. If TSP is present, then setting this option also - sets the TSP location to DRAM and ignores the `ARM_TSP_RAM_LOCATION` build - flag. - -* `ARM_BOARD_OPTIMISE_MEM`: Boolean option to enable or disable optimisation - of the memory reserved for each image. This affects the maximum size of each - BL image as well as the number of allocated memory regions and translation - tables. By default this flag is 0, which means it uses the default - unoptimised values for these macros. ARM development platforms that wish to - optimise memory usage need to set this flag to 1 and must override the - related macros. - -* `ARM_CONFIG_CNTACR`: boolean option to unlock access to the `CNTBase<N>` - frame registers by setting the `CNTCTLBase.CNTACR<N>` register bits. The - frame number `<N>` is defined by `PLAT_ARM_NSTIMER_FRAME_ID`, which should - match the frame used by the Non-Secure image (normally the Linux kernel). - Default is true (access to the frame is allowed). - -* `ARM_DISABLE_TRUSTED_WDOG`: boolean option to disable the Trusted Watchdog. - By default, ARM platforms use a watchdog to trigger a system reset in case - an error is encountered during the boot process (for example, when an image - could not be loaded or authenticated). The watchdog is enabled in the early - platform setup hook at BL1 and disabled in the BL1 prepare exit hook. The - Trusted Watchdog may be disabled at build time for testing or development - purposes. - -* `ARM_RECOM_STATE_ID_ENC`: The PSCI1.0 specification recommends an encoding - for the construction of composite state-ID in the power-state parameter. - The existing PSCI clients currently do not support this encoding of - State-ID yet. Hence this flag is used to configure whether to use the - recommended State-ID encoding or not. The default value of this flag is 0, - in which case the platform is configured to expect NULL in the State-ID - field of power-state parameter. - -* `ARM_ROTPK_LOCATION`: used when `TRUSTED_BOARD_BOOT=1`. It specifies the - location of the ROTPK hash returned by the function `plat_get_rotpk_info()` - for ARM platforms. Depending on the selected option, the proper private key - must be specified using the `ROT_KEY` option when building the Trusted - Firmware. This private key will be used by the certificate generation tool - to sign the BL2 and Trusted Key certificates. Available options for - `ARM_ROTPK_LOCATION` are: - - - `regs` : return the ROTPK hash stored in the Trusted root-key storage - registers. The private key corresponding to this ROTPK hash is not - currently available. - - `devel_rsa` : return a development public key hash embedded in the BL1 - and BL2 binaries. This hash has been obtained from the RSA public key - `arm_rotpk_rsa.der`, located in `plat/arm/board/common/rotpk`. To use - this option, `arm_rotprivk_rsa.pem` must be specified as `ROT_KEY` when - creating the certificates. - -* `ARM_TSP_RAM_LOCATION`: location of the TSP binary. Options: - - `tsram` : Trusted SRAM (default option) - - `tdram` : Trusted DRAM (if available) - - `dram` : Secure region in DRAM (configured by the TrustZone controller) - -* `ARM_XLAT_TABLES_LIB_V1`: boolean option to compile the Trusted Firmware - with version 1 of the translation tables library instead of version 2. It is - set to 0 by default, which selects version 2. - -* `ARM_CRYPTOCELL_INTEG` : bool option to enable Trusted Firmware to invoke - ARM® TrustZone® CryptoCell functionality for Trusted Board Boot on capable - ARM platforms. If this option is specified, then the path to the CryptoCell - SBROM library must be specified via `CCSBROM_LIB_PATH` flag. - -For a better understanding of these options, the ARM development platform memory -map is explained in the [Firmware Design]. - -#### ARM CSS platform specific build options - -* `CSS_DETECT_PRE_1_7_0_SCP`: Boolean flag to detect SCP version - incompatibility. Version 1.7.0 of the SCP firmware made a non-backwards - compatible change to the MTL protocol, used for AP/SCP communication. - Trusted Firmware no longer supports earlier SCP versions. If this option is - set to 1 then Trusted Firmware will detect if an earlier version is in use. - Default is 1. - -* `CSS_LOAD_SCP_IMAGES`: Boolean flag, which when set, adds SCP_BL2 and - SCP_BL2U to the FIP and FWU_FIP respectively, and enables them to be loaded - during boot. Default is 1. - -* `CSS_USE_SCMI_DRIVER`: Boolean flag which selects SCMI driver instead of - SCPI driver for communicating with the SCP during power management operations. - If this option is set to 1, then SCMI driver will be used. Default is 0. - -#### ARM FVP platform specific build options - -* `FVP_CLUSTER_COUNT` : Configures the cluster count to be used to - build the topology tree within Trusted Firmware. By default the - Trusted Firmware is configured for dual cluster topology and this option - can be used to override the default value. - -* `FVP_INTERCONNECT_DRIVER`: Selects the interconnect driver to be built. The - default interconnect driver depends on the value of `FVP_CLUSTER_COUNT` as - explained in the options below: - - `FVP_CCI` : The CCI driver is selected. This is the default - if 0 < `FVP_CLUSTER_COUNT` <= 2. - - `FVP_CCN` : The CCN driver is selected. This is the default - if `FVP_CLUSTER_COUNT` > 2. - -* `FVP_USE_GIC_DRIVER` : Selects the GIC driver to be built. Options: - - `FVP_GIC600` : The GIC600 implementation of GICv3 is selected - - `FVP_GICV2` : The GICv2 only driver is selected - - `FVP_GICV3` : The GICv3 only driver is selected (default option) - - `FVP_GICV3_LEGACY`: The Legacy GICv3 driver is selected (deprecated) - Note: If Trusted Firmware is compiled with this option on FVPs with - GICv3 hardware, then it configures the hardware to run in GICv2 - emulation mode - -* `FVP_USE_SP804_TIMER` : Use the SP804 timer instead of the Generic Timer - for functions that wait for an arbitrary time length (udelay and mdelay). - The default value is 0. - -### Debugging options - -To compile a debug version and make the build more verbose use - - make PLAT=<platform> DEBUG=1 V=1 all - -AArch64 GCC uses DWARF version 4 debugging symbols by default. Some tools (for -example DS-5) might not support this and may need an older version of DWARF -symbols to be emitted by GCC. This can be achieved by using the -`-gdwarf-<version>` flag, with the version being set to 2 or 3. Setting the -version to 2 is recommended for DS-5 versions older than 5.16. - -When debugging logic problems it might also be useful to disable all compiler -optimizations by using `-O0`. - -NOTE: Using `-O0` could cause output images to be larger and base addresses -might need to be recalculated (see the **Memory layout on ARM development -platforms** section in the [Firmware Design]). - -Extra debug options can be passed to the build system by setting `CFLAGS` or -`LDFLAGS`: - - CFLAGS='-O0 -gdwarf-2' \ - make PLAT=<platform> DEBUG=1 V=1 all - -Note that using `-Wl,` style compilation driver options in `CFLAGS` will be -ignored as the linker is called directly. - -It is also possible to introduce an infinite loop to help in debugging the -post-BL2 phase of the Trusted Firmware. This can be done by rebuilding BL1 with -the `SPIN_ON_BL1_EXIT=1` build flag. Refer to the "Summary of build options" -section. In this case, the developer may take control of the target using a -debugger when indicated by the console output. When using DS-5, the following -commands can be used: - - # Stop target execution - interrupt - - # - # Prepare your debugging environment, e.g. set breakpoints - # - - # Jump over the debug loop - set var $AARCH64::$Core::$PC = $AARCH64::$Core::$PC + 4 - - # Resume execution - continue - - -### Building the Test Secure Payload - -The TSP is coupled with a companion runtime service in the BL31 firmware, -called the TSPD. Therefore, if you intend to use the TSP, the BL31 image -must be recompiled as well. For more information on SPs and SPDs, see the -[Secure-EL1 Payloads and Dispatchers](firmware-design.rst#secure-el1-payloads-and-dispatchers) section in the [Firmware Design]. - -First clean the Trusted Firmware build directory to get rid of any previous -BL31 binary. Then to build the TSP image use: - - make PLAT=<platform> SPD=tspd all - -An additional boot loader binary file is created in the `build` directory: - - build/<platform>/<build-type>/bl32.bin - -### Checking source code style - -When making changes to the source for submission to the project, the source -must be in compliance with the Linux style guide, and to assist with this check -the project Makefile contains two targets, which both utilise the -`checkpatch.pl` script that ships with the Linux source tree. - -To check the entire source tree, you must first download a copy of -`checkpatch.pl` (or the full Linux source), set the `CHECKPATCH` environment -variable to point to the script and build the target checkcodebase: - - make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkcodebase - -To just check the style on the files that differ between your local branch and -the remote master, use: - - make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkpatch - -If you wish to check your patch against something other than the remote master, -set the `BASE_COMMIT` variable to your desired branch. By default, `BASE_COMMIT` -is set to `origin/master`. - - -### Building and using the FIP tool - -Firmware Image Package (FIP) is a packaging format used by the Trusted Firmware -project to package firmware images in a single binary. The number and type of -images that should be packed in a FIP is platform specific and may include TF -images and other firmware images required by the platform. For example, most -platforms require a BL33 image which corresponds to the normal world bootloader -(e.g. UEFI or U-Boot). - -The TF build system provides the make target `fip` to create a FIP file for the -specified platform using the FIP creation tool included in the TF project. -Examples below show how to build a FIP file for FVP, packaging TF images and a -BL33 image. - -For AArch64: - - make PLAT=fvp BL33=<path/to/bl33.bin> fip - -For AArch32: - - make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=<path/to/bl33.bin> fip - -Note that AArch32 support for Normal world boot loader (BL33), like U-boot or -UEFI, on FVP is not available upstream. Hence custom solutions are required to -allow Linux boot on FVP. These instructions assume such a custom boot loader -(BL33) is available. - -The resulting FIP may be found in: - - build/fvp/<build-type>/fip.bin - -For advanced operations on FIP files, it is also possible to independently build -the tool and create or modify FIPs using this tool. To do this, follow these -steps: - -It is recommended to remove old artifacts before building the tool: - - make -C tools/fiptool clean - -Build the tool: - - make [DEBUG=1] [V=1] fiptool - -The tool binary can be located in: - - ./tools/fiptool/fiptool - -Invoking the tool with `--help` will print a help message with all available -options. - -Example 1: create a new Firmware package `fip.bin` that contains BL2 and BL31: - - ./tools/fiptool/fiptool create \ - --tb-fw build/<platform>/<build-type>/bl2.bin \ - --soc-fw build/<platform>/<build-type>/bl31.bin \ - fip.bin - -Example 2: view the contents of an existing Firmware package: - - ./tools/fiptool/fiptool info <path-to>/fip.bin - -Example 3: update the entries of an existing Firmware package: - - # Change the BL2 from Debug to Release version - ./tools/fiptool/fiptool update \ - --tb-fw build/<platform>/release/bl2.bin \ - build/<platform>/debug/fip.bin - -Example 4: unpack all entries from an existing Firmware package: - - # Images will be unpacked to the working directory - ./tools/fiptool/fiptool unpack <path-to>/fip.bin - -Example 5: remove an entry from an existing Firmware package: - - ./tools/fiptool/fiptool remove \ - --tb-fw build/<platform>/debug/fip.bin - -Note that if the destination FIP file exists, the create, update and -remove operations will automatically overwrite it. - -The unpack operation will fail if the images already exist at the -destination. In that case, use -f or --force to continue. - -More information about FIP can be found in the [Firmware Design] document. - -#### Migrating from fip_create to fiptool - -The previous version of fiptool was called fip_create. A compatibility script -that emulates the basic functionality of the previous fip_create is provided. -However, users are strongly encouraged to migrate to fiptool. - -* To create a new FIP file, replace "fip_create" with "fiptool create". -* To update a FIP file, replace "fip_create" with "fiptool update". -* To dump the contents of a FIP file, replace "fip_create --dump" - with "fiptool info". - -### Building FIP images with support for Trusted Board Boot - -Trusted Board Boot primarily consists of the following two features: - -* Image Authentication, described in [Trusted Board Boot], and -* Firmware Update, described in [Firmware Update] - -The following steps should be followed to build FIP and (optionally) FWU_FIP -images with support for these features: - -1. Fulfill the dependencies of the `mbedtls` cryptographic and image parser - modules by checking out a recent version of the [mbed TLS Repository]. It - is important to use a version that is compatible with TF and fixes any - known security vulnerabilities. See [mbed TLS Security Center] for more - information. The latest version of TF is tested with tag `mbedtls-2.4.2`. - - The `drivers/auth/mbedtls/mbedtls_*.mk` files contain the list of mbed TLS - source files the modules depend upon. - `include/drivers/auth/mbedtls/mbedtls_config.h` contains the configuration - options required to build the mbed TLS sources. - - Note that the mbed TLS library is licensed under the Apache version 2.0 - license. Using mbed TLS source code will affect the licensing of - Trusted Firmware binaries that are built using this library. - -2. To build the FIP image, ensure the following command line variables are set - while invoking `make` to build Trusted Firmware: - - * `MBEDTLS_DIR=<path of the directory containing mbed TLS sources>` - * `TRUSTED_BOARD_BOOT=1` - * `GENERATE_COT=1` - - In the case of ARM platforms, the location of the ROTPK hash must also be - specified at build time. Two locations are currently supported (see - `ARM_ROTPK_LOCATION` build option): - - * `ARM_ROTPK_LOCATION=regs`: the ROTPK hash is obtained from the Trusted - root-key storage registers present in the platform. On Juno, this - registers are read-only. On FVP Base and Cortex models, the registers - are read-only, but the value can be specified using the command line - option `bp.trusted_key_storage.public_key` when launching the model. - On both Juno and FVP models, the default value corresponds to an - ECDSA-SECP256R1 public key hash, whose private part is not currently - available. - - * `ARM_ROTPK_LOCATION=devel_rsa`: use the ROTPK hash that is hardcoded - in the ARM platform port. The private/public RSA key pair may be - found in `plat/arm/board/common/rotpk`. - - Example of command line using RSA development keys: - - MBEDTLS_DIR=<path of the directory containing mbed TLS sources> \ - make PLAT=<platform> TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 \ - ARM_ROTPK_LOCATION=devel_rsa \ - ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \ - BL33=<path-to>/<bl33_image> \ - all fip - - The result of this build will be the bl1.bin and the fip.bin binaries. This - FIP will include the certificates corresponding to the Chain of Trust - described in the TBBR-client document. These certificates can also be found - in the output build directory. - -3. The optional FWU_FIP contains any additional images to be loaded from - Non-Volatile storage during the [Firmware Update] process. To build the - FWU_FIP, any FWU images required by the platform must be specified on the - command line. On ARM development platforms like Juno, these are: - - * NS_BL2U. The AP non-secure Firmware Updater image. - * SCP_BL2U. The SCP Firmware Update Configuration image. - - Example of Juno command line for generating both `fwu` and `fwu_fip` - targets using RSA development: - - MBEDTLS_DIR=<path of the directory containing mbed TLS sources> \ - make PLAT=juno TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 \ - ARM_ROTPK_LOCATION=devel_rsa \ - ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \ - BL33=<path-to>/<bl33_image> \ - SCP_BL2=<path-to>/<scp_bl2_image> \ - SCP_BL2U=<path-to>/<scp_bl2u_image> \ - NS_BL2U=<path-to>/<ns_bl2u_image> \ - all fip fwu_fip - - Note: The BL2U image will be built by default and added to the FWU_FIP. - The user may override this by adding `BL2U=<path-to>/<bl2u_image>` - to the command line above. - - Note: Building and installing the non-secure and SCP FWU images (NS_BL1U, - NS_BL2U and SCP_BL2U) is outside the scope of this document. - - The result of this build will be bl1.bin, fip.bin and fwu_fip.bin binaries. - Both the FIP and FWU_FIP will include the certificates corresponding to the - Chain of Trust described in the TBBR-client document. These certificates - can also be found in the output build directory. - - -### Building the Certificate Generation Tool - -The `cert_create` tool is built as part of the TF build process when the `fip` -make target is specified and TBB is enabled (as described in the previous -section), but it can also be built separately with the following command: - - make PLAT=<platform> [DEBUG=1] [V=1] certtool - -For platforms that do not require their own IDs in certificate files, -the generic 'cert_create' tool can be built with the following command: - - make USE_TBBR_DEFS=1 [DEBUG=1] [V=1] certtool - -`DEBUG=1` builds the tool in debug mode. `V=1` makes the build process more -verbose. The following command should be used to obtain help about the tool: - - ./tools/cert_create/cert_create -h - - -6. Building a FIP for Juno and FVP ------------------------------------ - -This section provides Juno and FVP specific instructions to build Trusted -Firmware, obtain the additional required firmware, and pack it all together in -a single FIP binary. It assumes that a [Linaro Release][Linaro Release Notes] -has been installed. - -Note: Linaro Release 16.06 only includes pre-built binaries for AArch64. For -AArch32, pre-built binaries are only available from Linaro Release 16.12. - -Note: follow the full instructions for one platform before switching to a -different one. Mixing instructions for different platforms may result in -corrupted binaries. - -1. Clean the working directory - - make realclean - -2. Obtain SCP_BL2 (Juno) and BL33 (all platforms) - - Use the fiptool to extract the SCP_BL2 and BL33 images from the FIP - package included in the Linaro release: - - # Build the fiptool - make [DEBUG=1] [V=1] fiptool - - # Unpack firmware images from Linaro FIP - ./tools/fiptool/fiptool unpack \ - <path/to/linaro/release>/fip.bin - - The unpack operation will result in a set of binary images extracted to the - working directory. The SCP_BL2 image corresponds to `scp-fw.bin` and BL33 - corresponds to `nt-fw.bin`. - - Note: the fiptool will complain if the images to be unpacked already - exist in the current directory. If that is the case, either delete those - files or use the `--force` option to overwrite. - - Note for AArch32, the instructions below assume that nt-fw.bin is a custom - Normal world boot loader that supports AArch32. - -3. Build TF images and create a new FIP for FVP - - # AArch64 - make PLAT=fvp BL33=nt-fw.bin all fip - - # AArch32 - make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=nt-fw.bin all fip - -4. Build TF images and create a new FIP for Juno - - For AArch64: - - Building for AArch64 on Juno simply requires the addition of `SCP_BL2` - as a build parameter. - - make PLAT=juno all fip \ - BL33=<path-to-juno-oe-uboot>/SOFTWARE/bl33-uboot.bin \ - SCP_BL2=<path-to-juno-busybox-uboot>/SOFTWARE/scp_bl2.bin - - For AArch32: - - Hardware restrictions on Juno prevent cold reset into AArch32 execution mode, - therefore BL1 and BL2 must be compiled for AArch64, and BL32 is compiled - separately for AArch32. - - * Before building BL32, the environment variable `CROSS_COMPILE` must point - to the AArch32 Linaro cross compiler. - - export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-linux-gnueabihf- - - * Build BL32 in AArch32. - - make ARCH=aarch32 PLAT=juno AARCH32_SP=sp_min \ - RESET_TO_SP_MIN=1 JUNO_AARCH32_EL3_RUNTIME=1 bl32 - - * Before building BL1 and BL2, the environment variable `CROSS_COMPILE` - must point to the AArch64 Linaro cross compiler. - - export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu- - - * The following parameters should be used to build BL1 and BL2 in AArch64 - and point to the BL32 file. - - make ARCH=aarch64 PLAT=juno LOAD_IMAGE_V2=1 JUNO_AARCH32_EL3_RUNTIME=1 \ - BL33=<path-to-juno32-oe-uboot>/SOFTWARE/bl33-uboot.bin \ - SCP_BL2=<path-to-juno32-oe-uboot>/SOFTWARE/scp_bl2.bin SPD=tspd \ - BL32=<path-to-bl32>/bl32.bin all fip - -The resulting BL1 and FIP images may be found in: - - # Juno - ./build/juno/release/bl1.bin - ./build/juno/release/fip.bin - - # FVP - ./build/fvp/release/bl1.bin - ./build/fvp/release/fip.bin - - -7. EL3 payloads alternative boot flow --------------------------------------- - -On a pre-production system, the ability to execute arbitrary, bare-metal code at -the highest exception level is required. It allows full, direct access to the -hardware, for example to run silicon soak tests. - -Although it is possible to implement some baremetal secure firmware from -scratch, this is a complex task on some platforms, depending on the level of -configuration required to put the system in the expected state. - -Rather than booting a baremetal application, a possible compromise is to boot -`EL3 payloads` through the Trusted Firmware instead. This is implemented as an -alternative boot flow, where a modified BL2 boots an EL3 payload, instead of -loading the other BL images and passing control to BL31. It reduces the -complexity of developing EL3 baremetal code by: - -* putting the system into a known architectural state; -* taking care of platform secure world initialization; -* loading the SCP_BL2 image if required by the platform. - -When booting an EL3 payload on ARM standard platforms, the configuration of the -TrustZone controller is simplified such that only region 0 is enabled and is -configured to permit secure access only. This gives full access to the whole -DRAM to the EL3 payload. - -The system is left in the same state as when entering BL31 in the default boot -flow. In particular: - -* Running in EL3; -* Current state is AArch64; -* Little-endian data access; -* All exceptions disabled; -* MMU disabled; -* Caches disabled. - -### Booting an EL3 payload - -The EL3 payload image is a standalone image and is not part of the FIP. It is -not loaded by the Trusted Firmware. Therefore, there are 2 possible scenarios: - -* The EL3 payload may reside in non-volatile memory (NVM) and execute in - place. In this case, booting it is just a matter of specifying the right - address in NVM through `EL3_PAYLOAD_BASE` when building the TF. - -* The EL3 payload needs to be loaded in volatile memory (e.g. DRAM) at - run-time. - -To help in the latter scenario, the `SPIN_ON_BL1_EXIT=1` build option can be -used. The infinite loop that it introduces in BL1 stops execution at the right -moment for a debugger to take control of the target and load the payload (for -example, over JTAG). - -It is expected that this loading method will work in most cases, as a debugger -connection is usually available in a pre-production system. The user is free to -use any other platform-specific mechanism to load the EL3 payload, though. - -#### Booting an EL3 payload on FVP - -The EL3 payloads boot flow requires the CPU's mailbox to be cleared at reset for -the secondary CPUs holding pen to work properly. Unfortunately, its reset value -is undefined on the FVP platform and the FVP platform code doesn't clear it. -Therefore, one must modify the way the model is normally invoked in order to -clear the mailbox at start-up. - -One way to do that is to create an 8-byte file containing all zero bytes using -the following command: - - dd if=/dev/zero of=mailbox.dat bs=1 count=8 - -and pre-load it into the FVP memory at the mailbox address (i.e. `0x04000000`) -using the following model parameters: - - --data cluster0.cpu0=mailbox.dat@0x04000000 [Base FVPs] - --data=mailbox.dat@0x04000000 [Foundation FVP] - -To provide the model with the EL3 payload image, the following methods may be -used: - -1. If the EL3 payload is able to execute in place, it may be programmed into - flash memory. On Base Cortex and AEM FVPs, the following model parameter - loads it at the base address of the NOR FLASH1 (the NOR FLASH0 is already - used for the FIP): - - -C bp.flashloader1.fname="/path/to/el3-payload" - - On Foundation FVP, there is no flash loader component and the EL3 payload - may be programmed anywhere in flash using method 3 below. - -2. When using the `SPIN_ON_BL1_EXIT=1` loading method, the following DS-5 - command may be used to load the EL3 payload ELF image over JTAG: - - load /path/to/el3-payload.elf - -3. The EL3 payload may be pre-loaded in volatile memory using the following - model parameters: - - --data cluster0.cpu0="/path/to/el3-payload"@address [Base FVPs] - --data="/path/to/el3-payload"@address [Foundation FVP] - - The address provided to the FVP must match the `EL3_PAYLOAD_BASE` address - used when building the Trusted Firmware. - -#### Booting an EL3 payload on Juno - -If the EL3 payload is able to execute in place, it may be programmed in flash -memory by adding an entry in the `SITE1/HBI0262x/images.txt` configuration file -on the Juno SD card (where `x` depends on the revision of the Juno board). -Refer to the [Juno Getting Started Guide], section 2.3 "Flash memory -programming" for more information. - -Alternatively, the same DS-5 command mentioned in the FVP section above can -be used to load the EL3 payload's ELF file over JTAG on Juno. - - -8. Preloaded BL33 alternative boot flow ----------------------------------------- - -Some platforms have the ability to preload BL33 into memory instead of relying -on Trusted Firmware to load it. This may simplify packaging of the normal world -code and improve performance in a development environment. When secure world -cold boot is complete, Trusted Firmware simply jumps to a BL33 base address -provided at build time. - -For this option to be used, the `PRELOADED_BL33_BASE` build option has to be -used when compiling the Trusted Firmware. For example, the following command -will create a FIP without a BL33 and prepare to jump to a BL33 image loaded at -address 0x80000000: - - make PRELOADED_BL33_BASE=0x80000000 PLAT=fvp all fip - -#### Boot of a preloaded bootwrapped kernel image on Base FVP - -The following example uses the AArch64 boot wrapper. This simplifies normal -world booting while also making use of TF features. It can be obtained from its -repository with: - - git clone git://git.kernel.org/pub/scm/linux/kernel/git/mark/boot-wrapper-aarch64.git - -After compiling it, an ELF file is generated. It can be loaded with the -following command: - - <path-to>/FVP_Base_AEMv8A-AEMv8A \ - -C bp.secureflashloader.fname=bl1.bin \ - -C bp.flashloader0.fname=fip.bin \ - -a cluster0.cpu0=<bootwrapped-kernel.elf> \ - --start cluster0.cpu0=0x0 - -The `-a cluster0.cpu0=<bootwrapped-kernel.elf>` option loads the ELF file. It -also sets the PC register to the ELF entry point address, which is not the -desired behaviour, so the `--start cluster0.cpu0=0x0` option forces the PC back -to 0x0 (the BL1 entry point address) on CPU #0. The `PRELOADED_BL33_BASE` define -used when compiling the FIP must match the ELF entry point. - -#### Boot of a preloaded bootwrapped kernel image on Juno - -The procedure to obtain and compile the boot wrapper is very similar to the case -of the FVP. The execution must be stopped at the end of bl2_main(), and the -loading method explained above in the EL3 payload boot flow section may be used -to load the ELF file over JTAG on Juno. - - -9. Running the software on FVP -------------------------------- - -The latest version of the AArch64 build of ARM Trusted Firmware has been tested -on the following ARM FVPs (64-bit host machine only). - -* `Foundation_Platform` (Version 10.2, Build 10.2.20) -* `FVP_Base_AEMv8A-AEMv8A` (Version 8.4, Build 0.8.8402) -* `FVP_Base_Cortex-A57x4-A53x4` (Version 8.4, Build 0.8.8402) - -The latest version of the AArch32 build of ARM Trusted Firmware has been tested -on the following ARM FVPs (64-bit host machine only). - -* `FVP_Base_AEMv8A-AEMv8A` (Version 8.4, Build 0.8.8402) -* `FVP_Base_Cortex-A32x4` (Version 10.1, Build 10.1.32) - -NOTE: The build numbers quoted above are those reported by launching the FVP -with the `--version` parameter. - -NOTE: The software will not work on Version 1.0 of the Foundation FVP. -The commands below would report an `unhandled argument` error in this case. - -NOTE: FVPs can be launched with `--cadi-server` option such that a -CADI-compliant debugger (for example, ARM DS-5) can connect to and control its -execution. - -The Foundation FVP is a cut down version of the AArch64 Base FVP. It can be -downloaded for free from [ARM's website][ARM FVP website]. - -Please refer to the FVP documentation for a detailed description of the model -parameter options. A brief description of the important ones that affect the ARM -Trusted Firmware and normal world software behavior is provided below. - -Note the instructions in the following sections assume that Linaro Release 16.06 -is being used. - -### Obtaining the Flattened Device Trees - -Depending on the FVP configuration and Linux configuration used, different -FDT files are required. FDTs for the Foundation and Base FVPs can be found in -the Trusted Firmware source directory under `fdts/`. The Foundation FVP has a -subset of the Base FVP components. For example, the Foundation FVP lacks CLCD -and MMC support, and has only one CPU cluster. - -Note: It is not recommended to use the FDTs built along the kernel because not -all FDTs are available from there. - -* `fvp-base-gicv2-psci.dtb` - - For use with both AEMv8 and Cortex-A57-A53 Base FVPs with - Base memory map configuration. - -* `fvp-base-gicv2-psci-aarch32.dtb` - - For use with AEMv8 and Cortex-A32 Base FVPs running Linux in AArch32 state - with Base memory map configuration. - -* `fvp-base-gicv3-psci.dtb` - - (Default) For use with both AEMv8 and Cortex-A57-A53 Base FVPs with Base - memory map configuration and Linux GICv3 support. - -* `fvp-base-gicv3-psci-aarch32.dtb` - - For use with AEMv8 and Cortex-A32 Base FVPs running Linux in AArch32 state - with Base memory map configuration and Linux GICv3 support. - -* `fvp-foundation-gicv2-psci.dtb` - - For use with Foundation FVP with Base memory map configuration. - -* `fvp-foundation-gicv3-psci.dtb` - - (Default) For use with Foundation FVP with Base memory map configuration - and Linux GICv3 support. - -### Running on the Foundation FVP with reset to BL1 entrypoint - -The following `Foundation_Platform` parameters should be used to boot Linux with -4 CPUs using the AArch64 build of ARM Trusted Firmware. - - <path-to>/Foundation_Platform \ - --cores=4 \ - --secure-memory \ - --visualization \ - --gicv3 \ - --data="<path-to>/<bl1-binary>"@0x0 \ - --data="<path-to>/<FIP-binary>"@0x08000000 \ - --data="<path-to>/<fdt>"@0x83000000 \ - --data="<path-to>/<kernel-binary>"@0x80080000 \ - --block-device="<path-to>/<file-system-image>" - -Notes: -* BL1 is loaded at the start of the Trusted ROM. -* The Firmware Image Package is loaded at the start of NOR FLASH0. -* The Linux kernel image and device tree are loaded in DRAM. -* The default use-case for the Foundation FVP is to use the `--gicv3` option - and enable the GICv3 device in the model. Note that without this option, - the Foundation FVP defaults to legacy (Versatile Express) memory map which - is not supported by ARM Trusted Firmware. - -### Running on the AEMv8 Base FVP with reset to BL1 entrypoint - -The following `FVP_Base_AEMv8A-AEMv8A` parameters should be used to boot Linux -with 8 CPUs using the AArch64 build of ARM Trusted Firmware. - - <path-to>/FVP_Base_AEMv8A-AEMv8A \ - -C pctl.startup=0.0.0.0 \ - -C bp.secure_memory=1 \ - -C bp.tzc_400.diagnostics=1 \ - -C cluster0.NUM_CORES=4 \ - -C cluster1.NUM_CORES=4 \ - -C cache_state_modelled=1 \ - -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \ - -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \ - --data cluster0.cpu0="<path-to>/<fdt>"@0x83000000 \ - --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ - -C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>" - -### Running on the AEMv8 Base FVP (AArch32) with reset to BL1 entrypoint - -The following `FVP_Base_AEMv8A-AEMv8A` parameters should be used to boot Linux -with 8 CPUs using the AArch32 build of ARM Trusted Firmware. - - <path-to>/FVP_Base_AEMv8A-AEMv8A \ - -C pctl.startup=0.0.0.0 \ - -C bp.secure_memory=1 \ - -C bp.tzc_400.diagnostics=1 \ - -C cluster0.NUM_CORES=4 \ - -C cluster1.NUM_CORES=4 \ - -C cache_state_modelled=1 \ - -C cluster0.cpu0.CONFIG64=0 \ - -C cluster0.cpu1.CONFIG64=0 \ - -C cluster0.cpu2.CONFIG64=0 \ - -C cluster0.cpu3.CONFIG64=0 \ - -C cluster1.cpu0.CONFIG64=0 \ - -C cluster1.cpu1.CONFIG64=0 \ - -C cluster1.cpu2.CONFIG64=0 \ - -C cluster1.cpu3.CONFIG64=0 \ - -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \ - -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \ - --data cluster0.cpu0="<path-to>/<fdt>"@0x83000000 \ - --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ - -C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>" - -### Running on the Cortex-A57-A53 Base FVP with reset to BL1 entrypoint - -The following `FVP_Base_Cortex-A57x4-A53x4` model parameters should be used to -boot Linux with 8 CPUs using the AArch64 build of ARM Trusted Firmware. - - <path-to>/FVP_Base_Cortex-A57x4-A53x4 \ - -C pctl.startup=0.0.0.0 \ - -C bp.secure_memory=1 \ - -C bp.tzc_400.diagnostics=1 \ - -C cache_state_modelled=1 \ - -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \ - -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \ - --data cluster0.cpu0="<path-to>/<fdt>"@0x83000000 \ - --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ - -C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>" - -### Running on the Cortex-A32 Base FVP (AArch32) with reset to BL1 entrypoint - -The following `FVP_Base_Cortex-A32x4` model parameters should be used to -boot Linux with 4 CPUs using the AArch32 build of ARM Trusted Firmware. - - <path-to>/FVP_Base_Cortex-A32x4 \ - -C pctl.startup=0.0.0.0 \ - -C bp.secure_memory=1 \ - -C bp.tzc_400.diagnostics=1 \ - -C cache_state_modelled=1 \ - -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \ - -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \ - --data cluster0.cpu0="<path-to>/<fdt>"@0x83000000 \ - --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ - -C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>" - -### Running on the AEMv8 Base FVP with reset to BL31 entrypoint - -The following `FVP_Base_AEMv8A-AEMv8A` parameters should be used to boot Linux -with 8 CPUs using the AArch64 build of ARM Trusted Firmware. - - <path-to>/FVP_Base_AEMv8A-AEMv8A \ - -C pctl.startup=0.0.0.0 \ - -C bp.secure_memory=1 \ - -C bp.tzc_400.diagnostics=1 \ - -C cluster0.NUM_CORES=4 \ - -C cluster1.NUM_CORES=4 \ - -C cache_state_modelled=1 \ - -C cluster0.cpu0.RVBAR=0x04023000 \ - -C cluster0.cpu1.RVBAR=0x04023000 \ - -C cluster0.cpu2.RVBAR=0x04023000 \ - -C cluster0.cpu3.RVBAR=0x04023000 \ - -C cluster1.cpu0.RVBAR=0x04023000 \ - -C cluster1.cpu1.RVBAR=0x04023000 \ - -C cluster1.cpu2.RVBAR=0x04023000 \ - -C cluster1.cpu3.RVBAR=0x04023000 \ - --data cluster0.cpu0="<path-to>/<bl31-binary>"@0x04023000 \ - --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04001000 \ - --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \ - --data cluster0.cpu0="<path-to>/<fdt>"@0x83000000 \ - --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ - -C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>" - -Notes: - -* Since a FIP is not loaded when using BL31 as reset entrypoint, the - `--data="<path-to><bl31|bl32|bl33-binary>"@<base-address-of-binary>` - parameter is needed to load the individual bootloader images in memory. - BL32 image is only needed if BL31 has been built to expect a Secure-EL1 - Payload. - -* The `-C cluster<X>.cpu<Y>.RVBAR=@<base-address-of-bl31>` parameter, where - X and Y are the cluster and CPU numbers respectively, is used to set the - reset vector for each core. - -* Changing the default value of `ARM_TSP_RAM_LOCATION` will also require - changing the value of - `--data="<path-to><bl32-binary>"@<base-address-of-bl32>` to the new value of - `BL32_BASE`. - -### Running on the AEMv8 Base FVP (AArch32) with reset to SP_MIN entrypoint - -The following `FVP_Base_AEMv8A-AEMv8A` parameters should be used to boot Linux -with 8 CPUs using the AArch32 build of ARM Trusted Firmware. - - <path-to>/FVP_Base_AEMv8A-AEMv8A \ - -C pctl.startup=0.0.0.0 \ - -C bp.secure_memory=1 \ - -C bp.tzc_400.diagnostics=1 \ - -C cluster0.NUM_CORES=4 \ - -C cluster1.NUM_CORES=4 \ - -C cache_state_modelled=1 \ - -C cluster0.cpu0.CONFIG64=0 \ - -C cluster0.cpu1.CONFIG64=0 \ - -C cluster0.cpu2.CONFIG64=0 \ - -C cluster0.cpu3.CONFIG64=0 \ - -C cluster1.cpu0.CONFIG64=0 \ - -C cluster1.cpu1.CONFIG64=0 \ - -C cluster1.cpu2.CONFIG64=0 \ - -C cluster1.cpu3.CONFIG64=0 \ - -C cluster0.cpu0.RVBAR=0x04001000 \ - -C cluster0.cpu1.RVBAR=0x04001000 \ - -C cluster0.cpu2.RVBAR=0x04001000 \ - -C cluster0.cpu3.RVBAR=0x04001000 \ - -C cluster1.cpu0.RVBAR=0x04001000 \ - -C cluster1.cpu1.RVBAR=0x04001000 \ - -C cluster1.cpu2.RVBAR=0x04001000 \ - -C cluster1.cpu3.RVBAR=0x04001000 \ - --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04001000 \ - --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \ - --data cluster0.cpu0="<path-to>/<fdt>"@0x83000000 \ - --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ - -C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>" - -Note: The load address of `<bl32-binary>` depends on the value `BL32_BASE`. -It should match the address programmed into the RVBAR register as well. - -### Running on the Cortex-A57-A53 Base FVP with reset to BL31 entrypoint - -The following `FVP_Base_Cortex-A57x4-A53x4` model parameters should be used to -boot Linux with 8 CPUs using the AArch64 build of ARM Trusted Firmware. - - <path-to>/FVP_Base_Cortex-A57x4-A53x4 \ - -C pctl.startup=0.0.0.0 \ - -C bp.secure_memory=1 \ - -C bp.tzc_400.diagnostics=1 \ - -C cache_state_modelled=1 \ - -C cluster0.cpu0.RVBARADDR=0x04023000 \ - -C cluster0.cpu1.RVBARADDR=0x04023000 \ - -C cluster0.cpu2.RVBARADDR=0x04023000 \ - -C cluster0.cpu3.RVBARADDR=0x04023000 \ - -C cluster1.cpu0.RVBARADDR=0x04023000 \ - -C cluster1.cpu1.RVBARADDR=0x04023000 \ - -C cluster1.cpu2.RVBARADDR=0x04023000 \ - -C cluster1.cpu3.RVBARADDR=0x04023000 \ - --data cluster0.cpu0="<path-to>/<bl31-binary>"@0x04023000 \ - --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04001000 \ - --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \ - --data cluster0.cpu0="<path-to>/<fdt>"@0x83000000 \ - --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ - -C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>" - -### Running on the Cortex-A32 Base FVP (AArch32) with reset to SP_MIN entrypoint - -The following `FVP_Base_Cortex-A32x4` model parameters should be used to -boot Linux with 4 CPUs using the AArch32 build of ARM Trusted Firmware. - - <path-to>/FVP_Base_Cortex-A32x4 \ - -C pctl.startup=0.0.0.0 \ - -C bp.secure_memory=1 \ - -C bp.tzc_400.diagnostics=1 \ - -C cache_state_modelled=1 \ - -C cluster0.cpu0.RVBARADDR=0x04001000 \ - -C cluster0.cpu1.RVBARADDR=0x04001000 \ - -C cluster0.cpu2.RVBARADDR=0x04001000 \ - -C cluster0.cpu3.RVBARADDR=0x04001000 \ - --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04001000 \ - --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \ - --data cluster0.cpu0="<path-to>/<fdt>"@0x83000000 \ - --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ - -C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>" - -10. Running the software on Juno ---------------------------------- - -This version of the ARM Trusted Firmware has been tested on Juno r0 and Juno r1. - -To execute the software stack on Juno, the version of the Juno board recovery -image indicated in the [Linaro Release Notes] must be installed. If you have an -earlier version installed or are unsure which version is installed, please -re-install the recovery image by following the [Instructions for using Linaro's -deliverables on Juno][Juno Instructions]. - -### Preparing Trusted Firmware images - -After building Trusted Firmware, the files `bl1.bin` and `fip.bin` need copying -to the `SOFTWARE/` directory of the Juno SD card. - -### Other Juno software information - -Please visit the [ARM Platforms Portal] to get support and obtain any other Juno -software information. Please also refer to the [Juno Getting Started Guide] to -get more detailed information about the Juno ARM development platform and how to -configure it. - -### Testing SYSTEM SUSPEND on Juno - -The SYSTEM SUSPEND is a PSCI API which can be used to implement system suspend -to RAM. For more details refer to section 5.16 of [PSCI]. To test system suspend -on Juno, at the linux shell prompt, issue the following command: - - echo +10 > /sys/class/rtc/rtc0/wakealarm - echo -n mem > /sys/power/state - -The Juno board should suspend to RAM and then wakeup after 10 seconds due to -wakeup interrupt from RTC. - - -- - - - - - - - - - - - - - - - - - - - - - - - - - - -_Copyright (c) 2013-2017, ARM Limited and Contributors. All rights reserved._ - - -[Firmware Design]: firmware-design.md -[ARM FVP website]: https://developer.arm.com/products/system-design/fixed-virtual-platforms -[Linaro Release Notes]: https://community.arm.com/tools/dev-platforms/b/documents/posts/linaro-release-notes-deprecated -[ARM Platforms Portal]: https://community.arm.com/groups/arm-development-platforms -[Linaro SW Instructions]: https://community.arm.com/dev-platforms/b/documents/posts/instructions-for-using-the-linaro-software-deliverables -[Juno Instructions]: https://community.arm.com/dev-platforms/b/documents/posts/using-linaros-deliverables-on-juno -[Juno Getting Started Guide]: http://infocenter.arm.com/help/topic/com.arm.doc.dui0928e/DUI0928E_juno_arm_development_platform_gsg.pdf -[DS-5]: http://www.arm.com/products/tools/software-tools/ds-5/index.php -[mbed TLS Repository]: https://github.com/ARMmbed/mbedtls.git -[mbed TLS Security Center]: https://tls.mbed.org/security -[PSCI]: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf "Power State Coordination Interface PDD (ARM DEN 0022C)" -[Trusted Board Boot]: trusted-board-boot.md -[Firmware Update]: ./firmware-update.md -[PSCI Lib Integration]: ./psci-lib-integration-guide.md diff --git a/license.md b/license.md deleted file mode 100644 index 185ecd1f..00000000 --- a/license.md +++ /dev/null @@ -1,35 +0,0 @@ -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/ diff --git a/maintainers.md b/maintainers.md deleted file mode 100644 index c8fc19db..00000000 --- a/maintainers.md +++ /dev/null @@ -1,84 +0,0 @@ -ARM Trusted Firmware Maintainers -================================ - -ARM Trusted Firmware is an ARM maintained project. All contributions are -ultimately merged by the maintainers listed below. Technical ownership of some -parts of the codebase is delegated to the sub-maintainers listed below. An -acknowledgement from these sub-maintainers may be required before the -maintainers merge a contribution. - - -## Maintainers - -Dan Handley (dan.handley@arm.com, [danh-arm](https://github.com/danh-arm)) - -David Cunado (david.cunado@arm.com, [davidcunado-arm](https://github.com/davidcunado-arm)) - - -## OPTEE and QEMU platform sub-maintainer - -Jens Wiklander (jens.wiklander@linaro.org, [jenswi-linaro](https://github.com/jenswi-linaro)) - -Files: -* docs/spd/optee-dispatcher.md -* docs/plat/qemu.md -* services/spd/opteed/* -* plat/qemu/* - - -## TLK/Trusty SPDs and NVidia platforms sub-maintainer - -Varun Wadekar (vwadekar@nvidia.com, [vwadekar](https://github.com/vwadekar)) - -Files: -* docs/spd/tlk-dispatcher.md -* docs/spd/trusty-dispatcher.md -* include/bl32/payloads/tlk.h -* include/lib/cpus/aarch64/denver.h -* lib/cpus/aarch64/denver.S -* services/spd/tlkd/* -* services/spd/trusty/* -* plat/nvidia/* - - -## eMMC/UFS drivers and HiSilicon platform sub-maintainer - -Haojian Zhuang (haojian.zhuang@linaro.org, [hzhuang1](https://github.com/hzhuang1)) - -Files: -* docs/plat/hikey.md -* docs/plat/hikey960.md -* drivers/emmc/* -* drivers/partition/* -* drivers/synopsys/emmc/* -* drivers/synopsys/ufs/* -* drivers/ufs/* -* include/drivers/dw_ufs.h -* include/drivers/emmc.h -* include/drivers/ufs.h -* include/drivers/synopsys/dw_mmc.h -* plat/hisilicon/* - - -## MediaTek platform sub-maintainer - -Yidi Lin (林以廸 yidi.lin@mediatek.com, [mtk09422](https://github.com/mtk09422)) - -Files: -* plat/mediatek/* - - -## RockChip platform sub-maintainer -Tony Xie (tony.xie@rock-chips.com, [TonyXie06](https://github.com/TonyXie06) -or [rkchrome](https://github.com/rkchrome)) - -Files: -* plat/rockchip/* - - -## Xilinx platform sub-maintainer -Sören Brinkmann (soren.brinkmann@xilinx.com, [sorenb-xlnx](https://github.com/sorenb-xlnx)) - -Files: -* docs/plat/xilinx-zynqmp.md -* plat/xilinx/* diff --git a/readme.md b/readme.md deleted file mode 100644 index ef5f6eea..00000000 --- a/readme.md +++ /dev/null @@ -1,197 +0,0 @@ -ARM Trusted Firmware - version 1.3 -================================== - -ARM Trusted Firmware provides a reference implementation of secure world -software for [ARMv8-A], including a [Secure Monitor] [TEE-SMC] executing at -Exception Level 3 (EL3). It implements various ARM interface standards, such as -the Power State Coordination Interface ([PSCI]), Trusted Board Boot Requirements -(TBBR, ARM DEN0006C-1) and [SMC Calling Convention][SMCCC]. As far as possible -the code is designed for reuse or porting to other ARMv8-A model and hardware -platforms. - -ARM will continue development in collaboration with interested parties to -provide a full reference implementation of PSCI, TBBR and Secure Monitor code -to the benefit of all developers working with ARMv8-A TrustZone technology. - - -License -------- - -The software is provided under a BSD-3-Clause [license]. Contributions to this -project are accepted under the same license with developer sign-off as -described in the [Contributing Guidelines]. - -This project contains code from other projects as listed below. The original -license text is included in those source files. - -* The stdlib source code is derived from FreeBSD code. - -* The libfdt source code is dual licensed. It is used by this project under - the terms of the BSD-2-Clause license. - - -This Release ------------- - -This release provides a suitable starting point for productization of secure -world boot and runtime firmware, executing in either the AArch32 or AArch64 -execution state. - -Users are encouraged to do their own security validation, including penetration -testing, on any secure world code derived from ARM Trusted Firmware. - -### Functionality - -* Initialization of the secure world (for example, exception vectors, control - registers, interrupt controller and interrupts for the platform), before - transitioning into the normal world at the Exception Level and Register - Width specified by the platform. - -* Library support for CPU specific reset and power down sequences. This - includes support for errata workarounds. - -* Drivers for both versions 2.0 and 3.0 of the ARM Generic Interrupt - Controller specifications (GICv2 and GICv3). The latter also enables GICv3 - hardware systems that do not contain legacy GICv2 support. - -* Drivers to enable standard initialization of ARM System IP, for example - Cache Coherent Interconnect (CCI), Cache Coherent Network (CCN), Network - Interconnect (NIC) and TrustZone Controller (TZC). - -* SMC (Secure Monitor Call) handling, conforming to the [SMC Calling - Convention][SMCCC] using an EL3 runtime services framework. - -* [PSCI] library support for the Secondary CPU Boot, CPU Hotplug, CPU Idle - and System Shutdown/Reset/Suspend use-cases. - This library is pre-integrated with the provided AArch64 EL3 Runtime - Software, and is also suitable for integration into other EL3 Runtime - Software. - -* A minimal AArch32 Secure Payload to demonstrate [PSCI] library integration - on platforms with AArch32 EL3 Runtime Software. - -* Secure Monitor library code such as world switching, EL1 context management - and interrupt routing. - When using the provided AArch64 EL3 Runtime Software, this must be - integrated with a Secure-EL1 Payload Dispatcher (SPD) component to - customize the interaction with a Secure-EL1 Payload (SP), for example a - Secure OS. - -* A Test Secure-EL1 Payload and Dispatcher to demonstrate AArch64 Secure - Monitor functionality and Secure-EL1 interaction with PSCI. - -* AArch64 SPDs for the [OP-TEE Secure OS] and [NVidia Trusted Little Kernel] - [NVidia TLK]. - -* A Trusted Board Boot implementation, conforming to all mandatory TBBR - requirements. This includes image authentication using certificates, a - Firmware Update (or recovery mode) boot flow, and packaging of the various - firmware images into a Firmware Image Package (FIP) to be loaded from - non-volatile storage. - The TBBR implementation is currently only supported in the AArch64 build. - -* Support for alternative boot flows. Some platforms have their own boot - firmware and only require the AArch64 EL3 Runtime Software provided by this - project. Other platforms require minimal initialization before booting - into an arbitrary EL3 payload. - -For a full description of functionality and implementation details, please -see the [Firmware Design] and supporting documentation. The [Change Log] -provides details of changes made since the last release. - -### Platforms - -The AArch64 build of this release has been tested on variants r0, r1 and r2 -of the [Juno ARM Development Platform] [Juno] with [Linaro Release 16.06]. - -The AArch64 build of this release has been tested on the following ARM -[FVP]s (64-bit host machine only, with [Linaro Release 16.06]): - -* `Foundation_Platform` (Version 10.1, Build 10.1.32) -* `FVP_Base_AEMv8A-AEMv8A` (Version 7.7, Build 0.8.7701) -* `FVP_Base_Cortex-A57x4-A53x4` (Version 7.7, Build 0.8.7701) -* `FVP_Base_Cortex-A57x1-A53x1` (Version 7.7, Build 0.8.7701) -* `FVP_Base_Cortex-A57x2-A53x4` (Version 7.7, Build 0.8.7701) - -The AArch32 build of this release has been tested on the following ARM -[FVP]s (64-bit host machine only, with [Linaro Release 16.06]): - -* `FVP_Base_AEMv8A-AEMv8A` (Version 7.7, Build 0.8.7701) -* `FVP_Base_Cortex-A32x4` (Version 10.1, Build 10.1.32) - -The Foundation FVP can be downloaded free of charge. The Base FVPs can be -licensed from ARM: see [www.arm.com/fvp] [FVP]. - -This release also contains the following platform support: - -* MediaTek MT6795 and MT8173 SoCs -* NVidia T210 and T132 SoCs -* QEMU emulator -* RockChip RK3368 and RK3399 SoCs -* Xilinx Zynq UltraScale + MPSoC - -### Still to Come - -* AArch32 TBBR support and ongoing TBBR alignment. - -* More platform support. - -* Ongoing support for new architectural features, CPUs and System IP. - -* Ongoing [PSCI] alignment and feature support. - -* Ongoing security hardening, optimization and quality improvements. - -For a full list of detailed issues in the current code, please see the [Change -Log] and the [GitHub issue tracker]. - - -Getting Started ---------------- - -Get the Trusted Firmware source code from -[GitHub](https://www.github.com/ARM-software/arm-trusted-firmware). - -See the [User Guide] for instructions on how to install, build and use -the Trusted Firmware with the ARM [FVP]s. - -See the [Firmware Design] for information on how the ARM Trusted Firmware works. - -See the [Porting Guide] as well for information about how to use this -software on another ARMv8-A platform. - -See the [Contributing Guidelines] for information on how to contribute to this -project and the [Acknowledgments] file for a list of contributors to the -project. - -### Feedback and support - -ARM welcomes any feedback on the Trusted Firmware. Please send feedback using -the [GitHub issue tracker]. - -ARM licensees may contact ARM directly via their partner managers. - - -- - - - - - - - - - - - - - - - - - - - - - - - - - - -_Copyright (c) 2013-2016, ARM Limited and Contributors. All rights reserved._ - - -[License]: ./license.md "BSD license for ARM Trusted Firmware" -[Contributing Guidelines]: ./contributing.md "Guidelines for contributors" -[Acknowledgments]: ./acknowledgements.md "Contributor acknowledgments" -[Change Log]: ./docs/change-log.md -[User Guide]: ./docs/user-guide.md -[Firmware Design]: ./docs/firmware-design.md -[Porting Guide]: ./docs/porting-guide.md - -[ARMv8-A]: http://www.arm.com/products/processors/armv8-architecture.php "ARMv8-A Architecture" -[FVP]: http://www.arm.com/fvp "ARM's Fixed Virtual Platforms" -[Juno]: http://www.arm.com/products/tools/development-boards/versatile-express/juno-arm-development-platform.php "Juno ARM Development Platform" -[PSCI]: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf "Power State Coordination Interface PDD (ARM DEN 0022C)" -[SMCCC]: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html "SMC Calling Convention PDD (ARM DEN 0028A)" -[TEE-SMC]: http://www.arm.com/products/processors/technologies/trustzone/tee-smc.php "Secure Monitor and TEEs" -[GitHub issue tracker]: https://github.com/ARM-software/tf-issues/issues -[OP-TEE Secure OS]: https://github.com/OP-TEE/optee_os -[NVidia TLK]: http://nv-tegra.nvidia.com/gitweb/?p=3rdparty/ote_partner/tlk.git;a=summary -[Linaro Release 16.06]: https://community.arm.com/docs/DOC-10952#jive_content_id_Linaro_Release_1606 |