doc: Document Branch Protection

Add Branch Procection related information to the documentation.

Signed-off-by: Gabor Toth <gabor.toth2@arm.com>
Signed-off-by: Gyorgy Szing <gyorgy.szing@arm.com>
Change-Id: Ic67876afc577a28ec6b63ebe85204bb8e3239d30
diff --git a/docs/developer/index.rst b/docs/developer/index.rst
index 3204633..e6ba7ae 100644
--- a/docs/developer/index.rst
+++ b/docs/developer/index.rst
@@ -6,6 +6,7 @@
     :caption: Contents:
 
     arch-overview
+    supported-architectural-features
     project-structure
     service-deployment-model
     service-access-protocols
diff --git a/docs/developer/supported-architectural-features.rst b/docs/developer/supported-architectural-features.rst
new file mode 100644
index 0000000..4197b97
--- /dev/null
+++ b/docs/developer/supported-architectural-features.rst
@@ -0,0 +1,83 @@
+Supported Architectural Features
+================================
+
+Branch Protection
+-----------------
+
+Branch protection covers two architecture features for mitigating Return Oriented Programming (ROP) and Jump Oriented
+Programming (JOP) attacks. For generic overview of these features please see
+`Providing protection for complex software`_.
+
+Branch Protection related hardware features can not be controlled from S-EL0 and to enable these co-operation with
+components running at higher exception levels is needed. Please refer to the documentation of the these components for
+information on how to enable these HW features.
+
+Pointer Authentication (FEAT_PAUTH)
+'''''''''''''''''''''''''''''''''''
+
+Pointer Authentication (PAC) is an ARMv8.3 feature where the return address of each function is signed. The signature is
+calculated when the function is called and verified upon returning. This is to ensure the return address has not been
+tampered with.
+
+Branch Target Identification (FEAT_BTI)
+'''''''''''''''''''''''''''''''''''''''
+
+Branch Target Identification (BTI) is an ARMv8.5 feature which is used to guard against the execution of instructions
+that are not the intended target of an indirect branch.
+
+For raw-binary SPs the TS build system will will mark the executable regions with the BTI attribute in the SP manifest
+file. The SPMC implementation running the SP is required to support this memory attribute, or has to unconditionally
+enable BTI for all executable regions to get the feature working.
+
+Although GCC has BTI support since v9, no BTI enabled libraries are shipped with the current GNUARM releases. A possible
+workaround is to compile from source as described in the `FAQ section of the OP-TEE documentation`_.
+
+Configuring Branch Protection in the TS build system
+''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+The feature can be controlled using the ``BRANCH_PROTECTION`` variable. This can be set e.g. on the cmake command line
+by passing ``-DBRANCH_PROTECTION=<value>``. The default value is ``unset``. Please refer to `GCC manual`_ for the
+detailed description of the values.
+
+.. list-table:: Supported values of ``BRANCH_PROTECTION``
+   :name: branch_protection_table
+   :header-rows: 1
+
+   * - Value
+     - GCC option
+     - FEAT_PAUTH
+     - FEAT_BTI
+   * - unset
+     -
+     - usually `N` (depends on how GCC is compiled)
+     - usually `N` (depends on how GCC is compiled)
+   * - 0
+     - "none"
+     - N
+     - N
+   * - 1
+     - "standard"
+     - Y
+     - Y
+   * - 2
+     - "pac-ret"
+     - Y
+     - N
+   * - 3
+     - "pac-ret+leaf"
+     - Y
+     - N
+   * - 4
+     - "bti"
+     - N
+     - Y
+
+--------------
+
+.. _`FAQ section of the OP-TEE documentation`: https://optee.readthedocs.io/en/stable/faq/faq.html#faq-gcc-bti
+.. _`Providing protection for complex software` : https://developer.arm.com/documentation/102433/0200
+.. _`GCC Manual`: https://gcc.gnu.org/onlinedocs/gcc-9.1.0/gcc/AArch64-Options.html
+
+*Copyright (c) 2024, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause