aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorAntonio Niño Díaz <antonio.ninodiaz@arm.com>2019-02-27 14:32:35 +0000
committerGitHub <noreply@github.com>2019-02-27 14:32:35 +0000
commit57bc6424cd7021e64d2af876b7d79b685893a208 (patch)
tree7ac40b1632b32078b667add460c4f1a3a0b5ed5b /docs
parentfc159c62ed6779bbf64882535e245629dd059e98 (diff)
parent67b6ff9f8ccd84cea1627d738f3e2d4eb0a789e1 (diff)
downloadtrusted-firmware-a-57bc6424cd7021e64d2af876b7d79b685893a208.tar.gz
Merge pull request #1829 from antonio-nino-diaz-arm/an/pauth
Add Pointer Authentication (ARMv8.3-PAuth) support to the TF
Diffstat (limited to 'docs')
-rw-r--r--docs/firmware-design.rst14
-rw-r--r--docs/porting-guide.rst16
-rw-r--r--docs/user-guide.rst13
3 files changed, 41 insertions, 2 deletions
diff --git a/docs/firmware-design.rst b/docs/firmware-design.rst
index 299654fc26..ead7297d9d 100644
--- a/docs/firmware-design.rst
+++ b/docs/firmware-design.rst
@@ -2558,8 +2558,18 @@ Armv8.2-A
Armv8.3-A
~~~~~~~~~
-- Pointer Authentication features of Armv8.3-A are unconditionally enabled so
- that lower ELs are allowed to use them without causing a trap to EL3.
+- Pointer authentication features of Armv8.3-A are unconditionally enabled in
+ the Non-secure world so that lower ELs are allowed to use them without
+ causing a trap to EL3.
+
+ In order to enable the Secure world to use it, ``CTX_INCLUDE_PAUTH_REGS``
+ must be set to 1. This will add all pointer authentication system registers
+ to the context that is saved when doing a world switch.
+
+ The Trusted Firmware itself has support for pointer authentication at runtime
+ that can be enabled by setting both options ``ENABLE_PAUTH`` and
+ ``CTX_INCLUDE_PAUTH_REGS`` to 1. This enables pointer authentication in BL1,
+ BL2, BL31, and the TSP if it is used.
Armv7-A
~~~~~~~
diff --git a/docs/porting-guide.rst b/docs/porting-guide.rst
index 7a3963bda8..c3df389f81 100644
--- a/docs/porting-guide.rst
+++ b/docs/porting-guide.rst
@@ -1792,6 +1792,22 @@ defined by the translation library, and can be found in the file
On DynamIQ systems, this function must not use stack while enabling MMU, which
is how the function in xlat table library version 2 is implemented.
+Function : plat_init_apiakey [optional]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Argument : void
+ Return : uint64_t *
+
+This function populates the ``plat_apiakey`` array that contains the values used
+to set the ``APIAKey{Hi,Lo}_EL1`` registers. It returns a pointer to this array.
+
+The value should be obtained from a reliable source of randomness.
+
+This function is only needed if ARMv8.3 pointer authentication is used in the
+Trusted Firmware by building with ``ENABLE_PAUTH=1``.
+
Function : plat_get_syscnt_freq2() [mandatory]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/user-guide.rst b/docs/user-guide.rst
index 4ff1c72707..b420127577 100644
--- a/docs/user-guide.rst
+++ b/docs/user-guide.rst
@@ -358,6 +358,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, will cause
+ the ARMv8.3-PAuth registers to be included when saving and restoring the CPU
+ context. Note that if the hardware supports this extension and this option is
+ set to 0 the value of the registers will be leaked between Secure and
+ Non-secure worlds if PAuth is used on both sides. The 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.
@@ -405,6 +411,13 @@ 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
+ (``ARMv8.3-PAuth``) support in the Trusted Firmware itself. Note that this
+ option doesn't affect the saving of the registers introduced with this
+ extension, they are always saved if they are detected regardless of the value
+ of this option. If enabled, it is needed to use a compiler that supports the
+ option ``-msign-return-address``. It defaults to 0.
+
- ``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.