aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/change-log.rst1
-rw-r--r--docs/components/sdei.rst3
-rw-r--r--docs/contents.rst165
-rw-r--r--docs/design/firmware-design.rst8
-rw-r--r--docs/getting_started/user-guide.rst52
-rw-r--r--docs/process/security.rst30
-rw-r--r--docs/security_advisories/security-advisory-tfv-6.rst12
7 files changed, 231 insertions, 40 deletions
diff --git a/docs/change-log.rst b/docs/change-log.rst
index 5941a8ba0..22effb135 100644
--- a/docs/change-log.rst
+++ b/docs/change-log.rst
@@ -2428,6 +2428,7 @@ releases of TF-A.
.. _Contribution Guide: ./contributing.rst
.. _Authentication framework: ./design/auth-framework.rst
.. _Firmware Update: ./design/firmware-update.rst
+.. _Firmware Design: ./design/firmware-design.rst
.. _TF-A Reset Design: ./design/reset-design.rst
.. _Power Domain Topology Design: ./design/psci-pd-tree.rst
.. _TF-A wiki on GitHub: https://github.com/ARM-software/arm-trusted-firmware/wiki/ARM-Trusted-Firmware-Image-Terminology
diff --git a/docs/components/sdei.rst b/docs/components/sdei.rst
index 845a29556..6d0e1563d 100644
--- a/docs/components/sdei.rst
+++ b/docs/components/sdei.rst
@@ -41,7 +41,7 @@ execute the registered handler [10]. The client terminates its execution with
original EL2 execution [13]. Note that the SDEI interrupt remains active until
the client handler completes, at which point EL3 does EOI [12].
-Other than events bound to interrupts (as depicted in the sequence above, SDEI
+Other than events bound to interrupts, as depicted in the sequence above, SDEI
events can be explicitly dispatched in response to other exceptions, for
example, upon receiving an *SError* or *Synchronous External Abort*. See
`Explicit dispatch of events`_.
@@ -370,3 +370,4 @@ implemented in assembly, following a similar pattern as below:
.. _SDEI specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf
.. _SDEI porting requirements: ../getting_started/porting-guide.rst#sdei-porting-requirements
+.. _Software Delegated Exception Interface: `SDEI specification`_
diff --git a/docs/contents.rst b/docs/contents.rst
new file mode 100644
index 000000000..4909dabe6
--- /dev/null
+++ b/docs/contents.rst
@@ -0,0 +1,165 @@
+Trusted Firmware-A Documentation Contents
+=========================================
+
+This document serves as a list of the documentation that is included with the
+Trusted Firmware-A source.
+
+Introduction
+------------
+
+`About Trusted Firmware-A`_
+
+Getting Started
+---------------
+
+`Frequently-Asked Questions (FAQ)`_
+
+`Image Terminology`_
+
+`Porting Guide`_
+
+`User Guide`_
+
+Contributing
+------------
+
+`Coding Style and Guidelines`_
+
+`Contributor Acknowledgements`_
+
+`Contributor's Guide`_
+
+`License`_
+
+`Maintainers`_
+
+Processes and Policies
+----------------------
+
+`Platform Compatibility Policy`_
+
+`Release Processes`_
+
+Secure Payload Dispatch
+-----------------------
+
+`OP-TEE Dispatcher`_
+
+`Trusted Little Kernel (TLK) Dispatcher`_
+
+`Trusty Dispatcher`_
+
+System Design and Components
+----------------------------
+
+`Arm CPU Specific Build Macros`_
+
+`Arm SiP Services`_
+
+`Authentication Framework & Chain of Trust`_
+
+`CPU Reset`_
+
+`EL3 Runtime Service Writer’s Guide`_
+
+`Exception Handling Framework`_
+
+`Firmware Design Overview`_
+
+`Firmware Update (FWU)`_
+
+`Interrupt Management Framework`_
+
+`Library at ROM`_
+
+`Platform Interrupt Controller API`_
+
+`PSCI Library Integration Guide for Armv8-A AArch32 systems`_
+
+`PSCI Power Domain Tree design`_
+
+`Reliability, Availability, and Serviceability (RAS) Extensions`_
+
+`Secure Partition Manager`_
+
+`Software Delegated Exception Interface`_
+
+`Translation (XLAT) Tables Library`_
+
+`Trusted Board Boot Design Guide`_
+
+Performance and Testing
+-----------------------
+
+`PSCI Performance Measurements on Arm Juno Development Platform`_
+
+Security and Advisories
+-----------------------
+
+`Security Processes`_
+
+`TFV-1`_
+
+`TFV-2`_
+
+`TFV-3`_
+
+`TFV-4`_
+
+`TFV-5`_
+
+`TFV-6`_
+
+`TFV-7`_
+
+`TFV-8`_
+
+Other Documents
+---------------
+
+`Change Log`_
+
+.. _About Trusted Firmware-A: ../readme.rst
+.. _Frequently-Asked Questions (FAQ): ./process/faq.rst
+.. _Image Terminology: ./getting_started/image-terminology.rst
+.. _Porting Guide: ./getting_started/porting-guide.rst
+.. _User Guide: ./getting_started/user-guide.rst
+.. _Coding Style and Guidelines: ./process/coding-guidelines.rst
+.. _Contributor Acknowledgements: ./acknowledgements.rst
+.. _`Contributor's Guide`: ./process/contributing.rst
+.. _License: ../license.rst
+.. _Maintainers: ./maintainers.rst
+.. _Platform Compatibility Policy: ./process/platform-compatibility-policy.rst
+.. _Release Processes: ./process/release-information.rst
+.. _Arm SiP Services: ./components/arm-sip-service.rst
+.. _Exception Handling Framework: ./components/exception-handling.rst
+.. _Firmware Update (FWU): ./components/firmware-update.rst
+.. _Interrupt Management Framework: ./design/interrupt-framework-design.rst
+.. _Library at ROM: ./components/romlib-design.rst
+.. _Platform Interrupt Controller API: ./components/platform-interrupt-controller-API.rst
+.. _`Reliability, Availability, and Serviceability (RAS) Extensions`: ./components/ras.rst
+.. _Secure Partition Manager: ./components/secure-partition-manager-design.rst
+.. _Software Delegated Exception Interface: ./components/sdei.rst
+.. _Translation (XLAT) Tables Library: ./components/xlat-tables-lib-v2-design.rst
+.. _OP-TEE Dispatcher: ./components/spd/optee-dispatcher.rst
+.. _Trusted Little Kernel (TLK) Dispatcher: ./components/spd/tlk-dispatcher.rst
+.. _Trusty Dispatcher: ./components/spd/trusty-dispatcher.rst
+.. _Arm CPU Specific Build Macros: ./design/cpu-specific-build-macros.rst
+.. _`Authentication Framework & Chain of Trust`: ./design/auth-framework.rst
+.. _CPU Reset: ./design/reset-design.rst
+.. _`EL3 Runtime Service Writer’s Guide`: ./getting_started/rt-svc-writers-guide.rst
+.. _Firmware Design Overview: ./design/firmware-design.rst
+.. _PSCI Library Integration Guide for Armv8-A AArch32 systems: ./getting_started/psci-lib-integration-guide.rst
+.. _PSCI Power Domain Tree design: ./design/psci-pd-tree.rst
+.. _Trusted Board Boot Design Guide: ./design/trusted-board-boot.rst
+.. _PSCI Performance Measurements on Arm Juno Development Platform: ./perf/psci-performance-juno.rst
+.. _Security Processes: ./process/security.rst
+.. _Change Log: ./change-log.rst
+.. _TFV-1: ./security_advisories/security-advisory-tfv-1.rst
+.. _TFV-2: ./security_advisories/security-advisory-tfv-2.rst
+.. _TFV-3: ./security_advisories/security-advisory-tfv-3.rst
+.. _TFV-4: ./security_advisories/security-advisory-tfv-4.rst
+.. _TFV-5: ./security_advisories/security-advisory-tfv-5.rst
+.. _TFV-6: ./security_advisories/security-advisory-tfv-6.rst
+.. _TFV-7: ./security_advisories/security-advisory-tfv-7.rst
+.. _TFV-8: ./security_advisories/security-advisory-tfv-8.rst
diff --git a/docs/design/firmware-design.rst b/docs/design/firmware-design.rst
index 21b823463..e4e2bc1d8 100644
--- a/docs/design/firmware-design.rst
+++ b/docs/design/firmware-design.rst
@@ -2564,7 +2564,7 @@ Armv8.3-A
to the context that is saved when doing a world switch.
The TF-A itself has support for pointer authentication at runtime
- that can be enabled by setting both options ``ENABLE_PAUTH`` and
+ that can be enabled by setting ``BRANCH_PROTECTION`` option to non-zero and
``CTX_INCLUDE_PAUTH_REGS`` to 1. This enables pointer authentication in BL1,
BL2, BL31, and the TSP if it is used.
@@ -2577,6 +2577,12 @@ Armv8.3-A
enabling PAuth is lower because the compiler will use the optimized
PAuth instructions rather than the backwards-compatible ones.
+Armv8.5-A
+~~~~~~~~~
+
+- Branch Target Identification feature is selected by ``BRANCH_PROTECTION``
+ option set to 1. This option defaults to 0 and this is an experimental feature.
+
Armv7-A
~~~~~~~
diff --git a/docs/getting_started/user-guide.rst b/docs/getting_started/user-guide.rst
index 606546447..db3654888 100644
--- a/docs/getting_started/user-guide.rst
+++ b/docs/getting_started/user-guide.rst
@@ -315,6 +315,34 @@ Common build options
file that contains the BL33 private key in PEM format. If ``SAVE_KEYS=1``,
this file name will be used to save the key.
+- ``BRANCH_PROTECTION``: Numeric value to enable ARMv8.3 Pointer Authentication
+ and ARMv8.5 Branch Target Identification support for TF-A BL images themselves.
+ If enabled, it is needed to use a compiler that supports the option
+ ``-mbranch-protection``. Selects the branch protection features to use:
+- 0: Default value turns off all types of branch protection
+- 1: Enables all types of branch protection features
+- 2: Return address signing to its standard level
+- 3: Extend the signing to include leaf functions
+
+ The table below summarizes ``BRANCH_PROTECTION`` values, GCC compilation options
+ and resulting PAuth/BTI features.
+
+ +-------+--------------+-------+-----+
+ | Value | GCC option | PAuth | BTI |
+ +=======+==============+=======+=====+
+ | 0 | none | N | N |
+ +-------+--------------+-------+-----+
+ | 1 | standard | Y | Y |
+ +-------+--------------+-------+-----+
+ | 2 | pac-ret | Y | N |
+ +-------+--------------+-------+-----+
+ | 3 | pac-ret+leaf | Y | N |
+ +-------+--------------+-------+-----+
+
+ This option defaults to 0 and this is an experimental feature.
+ Note that Pointer Authentication is enabled for Non-secure world
+ irrespective of the value of this option if the CPU supports it.
+
- ``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
@@ -354,17 +382,12 @@ Common build options
registers to be included when saving and restoring the CPU context. Default
is 0.
-- ``CTX_INCLUDE_PAUTH_REGS``: Boolean option that, when set to 1, allows
- Pointer Authentication for **Secure world**. This will cause the
- Armv8.3-PAuth registers to be included when saving and restoring the CPU
- context as part of a world switch. Default value is 0. Pointer Authentication
- is an experimental feature.
-
- Note that, if the CPU supports it, Pointer Authentication is allowed for
- Non-secure world irrespectively of the value of this flag. "Allowed" means
- that accesses to PAuth-related registers or execution of PAuth-related
- instructions will not be trapped to EL3. As such, usage or not of PAuth in
- Non-secure world images, depends on those images themselves.
+- ``CTX_INCLUDE_PAUTH_REGS``: Boolean option that, when set to 1, enables
+ Pointer Authentication for Secure world. This will cause the ARMv8.3-PAuth
+ registers to be included when saving and restoring the CPU context as
+ part of world switch. Default value is 0 and this is an experimental feature.
+ Note that Pointer Authentication is enabled for Non-secure world irrespective
+ of the value of this flag if the CPU supports it.
- ``DEBUG``: Chooses between a debug and release build. It can take either 0
(release) or 1 (debug) as values. 0 is the default.
@@ -417,13 +440,6 @@ Common build options
partitioning in EL3, however. Platform initialisation code should configure
and use partitions in EL3 as required. This option defaults to ``0``.
-- ``ENABLE_PAUTH``: Boolean option to enable Armv8.3 Pointer Authentication
- for **TF-A BL images themselves**. If enabled, the compiler must support the
- ``-msign-return-address`` option. This flag defaults to 0. Pointer
- Authentication is an experimental feature.
-
- If this flag is enabled, ``CTX_INCLUDE_PAUTH_REGS`` must also be enabled.
-
- ``ENABLE_PIE``: Boolean option to enable Position Independent Executable(PIE)
support within generic code in TF-A. This option is currently only supported
in BL31. Default is 0.
diff --git a/docs/process/security.rst b/docs/process/security.rst
index b4831c822..d1c997ba4 100644
--- a/docs/process/security.rst
+++ b/docs/process/security.rst
@@ -4,28 +4,29 @@ Security Handling
Security Disclosures
--------------------
-We disclose all security vulnerabilities we find or are advised about that are
-relevant for ARM Trusted Firmware (TF). We encourage responsible disclosure of
+We disclose all security vulnerabilities we find, or are advised about, that are
+relevant to Trusted Firmware-A. We encourage responsible disclosure of
vulnerabilities and inform users as best we can about all possible issues.
-We disclose TF vulnerabilities as Security Advisories. These are listed at the
-bottom of this page and announced as issues in the `GitHub issue tracker`_ with
-the "security-advisory" tag. You can receive notification emails for these by
-watching that project.
+We disclose TF-A vulnerabilities as Security Advisories, all of which are listed
+at the bottom of this page. Any new ones will, additionally, be announced as
+issues in the project's `issue tracker`_ with the ``security-advisory`` tag. You
+can receive notification emails for these by watching the "Trusted Firmware-A"
+project at https://developer.trustedfirmware.org/.
Found a Security Issue?
-----------------------
-Although we try to keep TF secure, we can only do so with the help of the
+Although we try to keep TF-A secure, we can only do so with the help of the
community of developers and security researchers.
-If you think you have found a security vulnerability, please *do not* report it
-in the `GitHub issue tracker`_. Instead send an email to
+If you think you have found a security vulnerability, please **do not** report it
+in the `issue tracker`_. Instead send an email to
trusted-firmware-security@arm.com
Please include:
-* Trusted Firmware version (or commit) affected
+* Trusted Firmware-A version (or commit) affected
* A description of the concern or vulnerability
@@ -49,10 +50,11 @@ If you would like replies to be encrypted, please provide your public key.
Please give us the time to respond to you and fix the vulnerability before going
public. We do our best to respond and fix any issues quickly. We also need to
-ensure providers of products that use TF have a chance to consider the
+ensure providers of products that use TF-A have a chance to consider the
implications of the vulnerability and its remedy.
-Afterwards, we encourage you to write-up your findings about the TF source code.
+Afterwards, we encourage you to write-up your findings about the TF-A source
+code.
Attribution
-----------
@@ -81,7 +83,7 @@ Security Advisories
| `TFV-5`_ | Not initializing or saving/restoring PMCR_EL0 can leak secure |
| | world timing information |
+-----------+------------------------------------------------------------------+
-| `TFV-6`_ | Arm Trusted Firmware exposure to speculative processor |
+| `TFV-6`_ | Trusted Firmware-A exposure to speculative processor |
| | vulnerabilities using cache timing side-channels |
+-----------+------------------------------------------------------------------+
| `TFV-7`_ | Trusted Firmware-A exposure to cache speculation vulnerability |
@@ -91,7 +93,7 @@ Security Advisories
| | Normal World SMC client to another |
+-----------+------------------------------------------------------------------+
-.. _GitHub issue tracker: https://github.com/ARM-software/tf-issues/issues
+.. _issue tracker: https://developer.trustedfirmware.org/project/board/1/
.. _this PGP/GPG key: security-reporting.asc
.. _TFV-1: ./security_advisories/security-advisory-tfv-1.rst
.. _TFV-2: ./security_advisories/security-advisory-tfv-2.rst
diff --git a/docs/security_advisories/security-advisory-tfv-6.rst b/docs/security_advisories/security-advisory-tfv-6.rst
index f968262c2..495edddae 100644
--- a/docs/security_advisories/security-advisory-tfv-6.rst
+++ b/docs/security_advisories/security-advisory-tfv-6.rst
@@ -2,7 +2,7 @@ Advisory TFV-6 (CVE-2017-5753, CVE-2017-5715, CVE-2017-5754)
============================================================
+----------------+-------------------------------------------------------------+
-| Title | Arm Trusted Firmware exposure to speculative processor |
+| Title | Trusted Firmware-A exposure to speculative processor |
| | vulnerabilities using cache timing side-channels |
+================+=============================================================+
| CVE ID | `CVE-2017-5753`_ / `CVE-2017-5715`_ / `CVE-2017-5754`_ |
@@ -24,11 +24,11 @@ Advisory TFV-6 (CVE-2017-5753, CVE-2017-5715, CVE-2017-5754)
| Credit | Google / Arm |
+----------------+-------------------------------------------------------------+
-This security advisory describes the current understanding of the Arm Trusted
-Firmware (TF) exposure to the speculative processor vulnerabilities identified
-by `Google Project Zero`_. To understand the background and wider impact of
-these vulnerabilities on Arm systems, please refer to the `Arm Processor
-Security Update`_.
+This security advisory describes the current understanding of the Trusted
+Firmware-A exposure to the speculative processor vulnerabilities identified by
+`Google Project Zero`_. To understand the background and wider impact of these
+vulnerabilities on Arm systems, please refer to the `Arm Processor Security
+Update`_.
Variant 1 (`CVE-2017-5753`_)
----------------------------
generated by cgit v1.2.3 (git 2.25.1) at 2025-06-15 07:22:12 +0000