aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/design/firmware-design.rst8
-rw-r--r--docs/getting_started/user-guide.rst52
2 files changed, 41 insertions, 19 deletions
diff --git a/docs/design/firmware-design.rst b/docs/design/firmware-design.rst
index 21b8234633..e4e2bc1d8c 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 606546447d..db36548880 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.