diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/design/firmware-design.rst | 8 | ||||
-rw-r--r-- | docs/getting_started/user-guide.rst | 52 |
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. |