diff options
Diffstat (limited to 'docs/getting_started/user-guide.rst')
| -rw-r--r-- | docs/getting_started/user-guide.rst | 52 |
1 files changed, 34 insertions, 18 deletions
diff --git a/docs/getting_started/user-guide.rst b/docs/getting_started/user-guide.rst index 60654644..db365488 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. |