Adding upstream version 2.10.0+dfsg.upstream/2.10.0+dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

10 files changed, 3053 insertions, 0 deletions

diff --git a/docs/getting_started/build-internals.rst b/docs/getting_started/build-internals.rst
new file mode 100644
index 0000000..390c367
--- /dev/null
+++ b/docs/getting_started/build-internals.rst
@@ -0,0 +1,21 @@
+Internal Build Options
+======================
+
+|TF-A| internally uses certain options that are not exposed directly through
+:ref:`build-options <build options>` but enabled or disabled indirectly and
+depends on certain options to be enabled or disabled.
+
+.. _build_options_internal:
+
+-  ``CTX_INCLUDE_EL2_REGS``: This boolean option provides context save/restore
+   operations when entering/exiting an EL2 execution context. This is of primary
+   interest when Armv8.4-SecEL2 or RME extension is implemented.
+   Default is 0 (disabled). This option will be set to 1 (enabled) when ``SPD=spmd``
+   and ``SPMD_SPM_AT_SEL2`` is set or when ``ENABLE_RME`` is set to 1 (enabled).
+
+- ``FFH_SUPPORT``: This boolean option provides support to enable Firmware First
+  handling (FFH) of External aborts and SError interrupts originating from lower
+  ELs which gets trapped in EL3. This option will be set to 1 (enabled) if
+  ``HANDLE_EA_EL3_FIRST_NS`` is set. Currently only NS world routes EA to EL3 but
+  in future when Secure/Realm wants to use FFH then they can introduce new macros
+  which will enable this option implicitly.
diff --git a/docs/getting_started/build-options.rst b/docs/getting_started/build-options.rst
new file mode 100644
index 0000000..80baf9c
--- /dev/null
+++ b/docs/getting_started/build-options.rst
@@ -0,0 +1,1327 @@
+Build Options
+=============
+
+The TF-A build system supports the following build options. Unless mentioned
+otherwise, these options are expected to be specified at the build command
+line and are not to be modified in any component makefiles. Note that the
+build system doesn't track dependency for build options. Therefore, if any of
+the build options are changed from a previous build, a clean build must be
+performed.
+
+.. _build_options_common:
+
+Common build options
+--------------------
+
+-  ``AARCH32_INSTRUCTION_SET``: Choose the AArch32 instruction set that the
+   compiler should use. Valid values are T32 and A32. It defaults to T32 due to
+   code having a smaller resulting size.
+
+-  ``AARCH32_SP`` : Choose the AArch32 Secure Payload component to be built as
+   as the BL32 image when ``ARCH=aarch32``. The value should be the path to the
+   directory containing the SP source, relative to the ``bl32/``; the directory
+   is expected to contain a makefile called ``<aarch32_sp-value>.mk``.
+
+-  ``AMU_RESTRICT_COUNTERS``: Register reads to the group 1 counters will return
+   zero at all but the highest implemented exception level.  Reads from the
+   memory mapped view are unaffected by this control.
+
+-  ``ARCH`` : Choose the target build architecture for TF-A. It can take either
+   ``aarch64`` or ``aarch32`` as values. By default, it is defined to
+   ``aarch64``.
+
+-  ``ARM_ARCH_FEATURE``: Optional Arm Architecture build option which specifies
+   one or more feature modifiers. This option has the form ``[no]feature+...``
+   and defaults to ``none``. It translates into compiler option
+   ``-march=armvX[.Y]-a+[no]feature+...``. See compiler's documentation for the
+   list of supported feature modifiers.
+
+-  ``ARM_ARCH_MAJOR``: The major version of Arm Architecture to target when
+   compiling TF-A. Its value must be numeric, and defaults to 8 . See also,
+   *Armv8 Architecture Extensions* and *Armv7 Architecture Extensions* in
+   :ref:`Firmware Design`.
+
+-  ``ARM_ARCH_MINOR``: The minor version of Arm Architecture to target when
+   compiling TF-A. Its value must be a numeric, and defaults to 0. See also,
+   *Armv8 Architecture Extensions* in :ref:`Firmware Design`.
+
+-  ``ARM_BL2_SP_LIST_DTS``: Path to DTS file snippet to override the hardcoded
+   SP nodes in tb_fw_config.
+
+-  ``ARM_SPMC_MANIFEST_DTS`` : path to an alternate manifest file used as the
+   SPMC Core manifest. Valid when ``SPD=spmd`` is selected.
+
+-  ``BL2``: This is an optional build option which specifies the path to BL2
+   image for the ``fip`` target. In this case, the BL2 in the TF-A will not be
+   built.
+
+-  ``BL2U``: This is an optional build option which specifies the path to
+   BL2U image. In this case, the BL2U in TF-A will not be built.
+
+-  ``RESET_TO_BL2``: Boolean option to enable BL2 entrypoint as the CPU reset
+   vector instead of the BL1 entrypoint. It can take the value 0 (CPU reset to BL1
+   entrypoint) or 1 (CPU reset to BL2 entrypoint).
+   The default value is 0.
+
+-  ``BL2_RUNS_AT_EL3``: This is an implicit flag to denote that BL2 runs at EL3.
+   While it is explicitly set to 1 when RESET_TO_BL2 is set to 1 it can also be
+   true in a 4-world system where RESET_TO_BL2 is 0.
+
+-  ``BL2_ENABLE_SP_LOAD``: Boolean option to enable loading SP packages from the
+   FIP. Automatically enabled if ``SP_LAYOUT_FILE`` is provided.
+
+-  ``BL2_IN_XIP_MEM``: In some use-cases BL2 will be stored in eXecute In Place
+   (XIP) memory, like BL1. In these use-cases, it is necessary to initialize
+   the RW sections in RAM, while leaving the RO sections in place. This option
+   enable this use-case. For now, this option is only supported
+   when RESET_TO_BL2 is set to '1'.
+
+-  ``BL31``: This is an optional build option which specifies the path to
+   BL31 image for the ``fip`` target. In this case, the BL31 in TF-A will not
+   be built.
+
+-  ``BL31_KEY``: This option is used when ``GENERATE_COT=1``. It specifies a
+   file that contains the BL31 private key in PEM format or a PKCS11 URI. If
+   ``SAVE_KEYS=1``, only a file is accepted and it will be used to save the key.
+
+-  ``BL32``: This is an optional build option which specifies the path to
+   BL32 image for the ``fip`` target. In this case, the BL32 in TF-A will not
+   be built.
+
+-  ``BL32_EXTRA1``: This is an optional build option which specifies the path to
+   Trusted OS Extra1 image for the  ``fip`` target.
+
+-  ``BL32_EXTRA2``: This is an optional build option which specifies the path to
+   Trusted OS Extra2 image for the ``fip`` target.
+
+-  ``BL32_KEY``: This option is used when ``GENERATE_COT=1``. It specifies a
+   file that contains the BL32 private key in PEM format or a PKCS11 URI. If
+   ``SAVE_KEYS=1``, only a file is accepted and it will be used to save the key.
+
+-  ``BL33``: Path to BL33 image in the host file system. This is mandatory for
+   ``fip`` target in case TF-A BL2 is used.
+
+-  ``BL33_KEY``: This option is used when ``GENERATE_COT=1``. It specifies a
+   file that contains the BL33 private key in PEM format or a PKCS11 URI. If
+   ``SAVE_KEYS=1``, only a file is accepted and it 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
+-  4: Turn on branch target identification mechanism
+
+   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  |
+   +-------+--------------+-------+-----+
+   |   4   |     bti      |   N   |  Y  |
+   +-------+--------------+-------+-----+
+
+   This option defaults to 0.
+   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
+   the compilation.
+
+-  ``BUILD_STRING``: Input string for VERSION_STRING, which allows the TF-A
+   build to be uniquely identified. Defaults to the current git commit id.
+
+-  ``BUILD_BASE``: Output directory for the build. Defaults to ``./build``
+
+-  ``CFLAGS``: Extra user options appended on the compiler's command line in
+   addition to the options set by the build system.
+
+-  ``COLD_BOOT_SINGLE_CPU``: This option indicates whether the platform may
+   release several CPUs out of reset. It can take either 0 (several CPUs may be
+   brought up) or 1 (only one CPU will ever be brought up during cold reset).
+   Default is 0. If the platform always brings up a single CPU, there is no
+   need to distinguish between primary and secondary CPUs and the boot path can
+   be optimised. The ``plat_is_my_cpu_primary()`` and
+   ``plat_secondary_cold_boot_setup()`` platform porting interfaces do not need
+   to be implemented in this case.
+
+-  ``COT``: When Trusted Boot is enabled, selects the desired chain of trust.
+   Defaults to ``tbbr``.
+
+-  ``CRASH_REPORTING``: A non-zero value enables a console dump of processor
+   register state when an unexpected exception occurs during execution of
+   BL31. This option defaults to the value of ``DEBUG`` - i.e. by default
+   this is only enabled for a debug build of the firmware.
+
+-  ``CREATE_KEYS``: This option is used when ``GENERATE_COT=1``. It tells the
+   certificate generation tool to create new keys in case no valid keys are
+   present or specified. Allowed options are '0' or '1'. Default is '1'.
+
+-  ``CTX_INCLUDE_AARCH32_REGS`` : Boolean option that, when set to 1, will cause
+   the AArch32 system registers to be included when saving and restoring the
+   CPU context. The option must be set to 0 for AArch64-only platforms (that
+   is on hardware that does not implement AArch32, or at least not at EL1 and
+   higher ELs). Default value is 1.
+
+-  ``CTX_INCLUDE_FPREGS``: Boolean option that, when set to 1, will cause the FP
+   registers to be included when saving and restoring the CPU context. Default
+   is 0.
+
+-  ``CTX_INCLUDE_MTE_REGS``: Numeric value to include Memory Tagging Extension
+   registers in cpu context. This must be enabled, if the platform wants to use
+   this feature in the Secure world and MTE is enabled at ELX. This flag can
+   take values 0 to 2, to align with the ``FEATURE_DETECTION`` mechanism.
+   Default value is 0.
+
+-  ``CTX_INCLUDE_NEVE_REGS``: Numeric value, when set will cause the Armv8.4-NV
+   registers to be saved/restored when entering/exiting an EL2 execution
+   context. This flag can take values 0 to 2, to align with the
+   ``FEATURE_DETECTION`` mechanism. Default value is 0.
+
+-  ``CTX_INCLUDE_PAUTH_REGS``: Numeric value to enable the 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. This flag can take values 0 to 2, to align with ``FEATURE_DETECTION``
+   mechanism. Default value is 0.
+
+   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.
+
+-  ``DECRYPTION_SUPPORT``: This build flag enables the user to select the
+   authenticated decryption algorithm to be used to decrypt firmware/s during
+   boot. It accepts 2 values: ``aes_gcm`` and ``none``. The default value of
+   this flag is ``none`` to disable firmware decryption which is an optional
+   feature as per TBBR.
+
+-  ``DISABLE_BIN_GENERATION``: Boolean option to disable the generation
+   of the binary image. If set to 1, then only the ELF image is built.
+   0 is the default.
+
+-  ``DISABLE_MTPMU``: Numeric option to disable ``FEAT_MTPMU`` (Multi Threaded
+   PMU). ``FEAT_MTPMU`` is an optional feature available on Armv8.6 onwards.
+   This flag can take values 0 to 2, to align with the ``FEATURE_DETECTION``
+   mechanism. Default is ``0``.
+
+-  ``DYN_DISABLE_AUTH``: Provides the capability to dynamically disable Trusted
+   Board Boot authentication at runtime. This option is meant to be enabled only
+   for development platforms. ``TRUSTED_BOARD_BOOT`` flag must be set if this
+   flag has to be enabled. 0 is the default.
+
+-  ``E``: Boolean option to make warnings into errors. Default is 1.
+
+   When specifying higher warnings levels (``W=1`` and higher), this option
+   defaults to 0. This is done to encourage contributors to use them, as they
+   are expected to produce warnings that would otherwise fail the build. New
+   contributions are still expected to build with ``W=0`` and ``E=1`` (the
+   default).
+
+-  ``EL3_PAYLOAD_BASE``: This option enables booting an EL3 payload instead of
+   the normal boot flow. It must specify the entry point address of the EL3
+   payload. Please refer to the "Booting an EL3 payload" section for more
+   details.
+
+-  ``ENABLE_AMU_AUXILIARY_COUNTERS``: Enables support for AMU auxiliary counters
+   (also known as group 1 counters). These are implementation-defined counters,
+   and as such require additional platform configuration. Default is 0.
+
+-  ``ENABLE_AMU_FCONF``: Enables configuration of the AMU through FCONF, which
+   allows platforms with auxiliary counters to describe them via the
+   ``HW_CONFIG`` device tree blob. Default is 0.
+
+-  ``ENABLE_ASSERTIONS``: This option controls whether or not calls to ``assert()``
+   are compiled out. For debug builds, this option defaults to 1, and calls to
+   ``assert()`` are left in place. For release builds, this option defaults to 0
+   and calls to ``assert()`` function are compiled out. This option can be set
+   independently of ``DEBUG``. It can also be used to hide any auxiliary code
+   that is only required for the assertion and does not fit in the assertion
+   itself.
+
+-  ``ENABLE_BACKTRACE``: This option controls whether to enable backtrace
+   dumps or not. It is supported in both AArch64 and AArch32. However, in
+   AArch32 the format of the frame records are not defined in the AAPCS and they
+   are defined by the implementation. This implementation of backtrace only
+   supports the format used by GCC when T32 interworking is disabled. For this
+   reason enabling this option in AArch32 will force the compiler to only
+   generate A32 code. This option is enabled by default only in AArch64 debug
+   builds, but this behaviour can be overridden in each platform's Makefile or
+   in the build command line.
+
+-  ``ENABLE_FEAT_AMU``: Numeric value to enable Activity Monitor Unit
+   extensions. This flag can take the values 0 to 2, to align with the
+   ``FEATURE_DETECTION`` mechanism. This is an optional architectural feature
+   available on v8.4 onwards. Some v8.2 implementations also implement an AMU
+   and this option can be used to enable this feature on those systems as well.
+   This flag can take the values 0 to 2, the default is 0.
+
+-  ``ENABLE_FEAT_AMUv1p1``: Numeric value to enable the ``FEAT_AMUv1p1``
+   extension. ``FEAT_AMUv1p1`` is an optional feature available on Arm v8.6
+   onwards. This flag can take the values 0 to 2, to align with the
+   ``FEATURE_DETECTION`` mechanism. Default value is ``0``.
+
+-  ``ENABLE_FEAT_CSV2_2``: Numeric value to enable the ``FEAT_CSV2_2``
+   extension. It allows access to the SCXTNUM_EL2 (Software Context Number)
+   register during EL2 context save/restore operations. ``FEAT_CSV2_2`` is an
+   optional feature available on Arm v8.0 onwards. This flag can take values
+   0 to 2, to align with the ``FEATURE_DETECTION`` mechanism.
+   Default value is ``0``.
+
+-  ``ENABLE_FEAT_DIT``: Numeric value to enable ``FEAT_DIT`` (Data Independent
+   Timing) extension. It allows setting the ``DIT`` bit of PSTATE in EL3.
+   ``FEAT_DIT`` is a mandatory  architectural feature and is enabled from v8.4
+   and upwards. This flag can take the values 0 to 2, to align  with the
+   ``FEATURE_DETECTION`` mechanism. Default value is ``0``.
+
+-  ``ENABLE_FEAT_ECV``: Numeric value to enable support for the Enhanced Counter
+   Virtualization feature, allowing for access to the CNTPOFF_EL2 (Counter-timer
+   Physical Offset register) during EL2 to EL3 context save/restore operations.
+   Its a mandatory architectural feature and is enabled from v8.6 and upwards.
+   This flag can take the values 0 to 2, to align  with the ``FEATURE_DETECTION``
+   mechanism. Default value is ``0``.
+
+-  ``ENABLE_FEAT_FGT``: Numeric value to enable support for FGT (Fine Grain Traps)
+   feature allowing for access to the HDFGRTR_EL2 (Hypervisor Debug Fine-Grained
+   Read Trap Register) during EL2 to EL3 context save/restore operations.
+   Its a mandatory architectural feature and is enabled from v8.6 and upwards.
+   This flag can take the values 0 to 2, to align  with the ``FEATURE_DETECTION``
+   mechanism. Default value is ``0``.
+
+-  ``ENABLE_FEAT_HCX``: Numeric value to set the bit SCR_EL3.HXEn in EL3 to
+   allow access to HCRX_EL2 (extended hypervisor control register) from EL2 as
+   well as adding HCRX_EL2 to the EL2 context save/restore operations. Its a
+   mandatory architectural feature and is enabled from v8.7 and upwards. This
+   flag can take the values 0 to 2, to align  with the ``FEATURE_DETECTION``
+   mechanism. Default value is ``0``.
+
+-  ``ENABLE_FEAT_MTE_PERM``: Numeric value to enable support for
+   ``FEAT_MTE_PERM``, which introduces Allocation tag access permission to
+   memory region attributes. ``FEAT_MTE_PERM`` is a optional architectural
+   feature available from v8.9 and upwards.  This flag can take the values 0 to
+   2, to align  with the ``FEATURE_DETECTION`` mechanism. Default value is
+   ``0``.
+
+-  ``ENABLE_FEAT_PAN``: Numeric value to enable the ``FEAT_PAN`` (Privileged
+   Access Never) extension. ``FEAT_PAN`` adds a bit to PSTATE, generating a
+   permission fault for any privileged data access from EL1/EL2 to virtual
+   memory address, accessible at EL0, provided (HCR_EL2.E2H=1). It is a
+   mandatory architectural feature and is enabled from v8.1 and upwards. This
+   flag can take values 0 to 2, to align  with the ``FEATURE_DETECTION``
+   mechanism. Default value is ``0``.
+
+-  ``ENABLE_FEAT_RNG``: Numeric value to enable the ``FEAT_RNG`` extension.
+   ``FEAT_RNG`` is an optional feature available on Arm v8.5 onwards. This
+   flag can take the values 0 to 2, to align with the ``FEATURE_DETECTION``
+   mechanism. Default value is ``0``.
+
+-  ``ENABLE_FEAT_RNG_TRAP``: Numeric value to enable the ``FEAT_RNG_TRAP``
+   extension. This feature is only supported in AArch64 state. This flag can
+   take values 0 to 2, to align with the ``FEATURE_DETECTION`` mechanism.
+   Default value is ``0``. ``FEAT_RNG_TRAP`` is an optional feature from
+   Armv8.5 onwards.
+
+-  ``ENABLE_FEAT_SB``: Boolean option to let the TF-A code use the ``FEAT_SB``
+   (Speculation Barrier) instruction ``FEAT_SB`` is an optional feature and
+   defaults to ``0`` for pre-Armv8.5 CPUs, but is mandatory for Armv8.5 or
+   later CPUs. It is enabled from v8.5 and upwards and if needed can be
+   overidden from platforms explicitly.
+
+-  ``ENABLE_FEAT_SEL2``: Numeric value to enable the ``FEAT_SEL2`` (Secure EL2)
+   extension. ``FEAT_SEL2`` is a mandatory feature available on Arm v8.4.
+   This flag can take values 0 to 2, to align with the ``FEATURE_DETECTION``
+   mechanism. Default is ``0``.
+
+-  ``ENABLE_FEAT_TWED``: Numeric value to enable the ``FEAT_TWED`` (Delayed
+   trapping of WFE Instruction) extension. ``FEAT_TWED`` is a optional feature
+   available on Arm v8.6. This flag can take values 0 to 2, to align with the
+   ``FEATURE_DETECTION`` mechanism. Default is ``0``.
+
+    When ``ENABLE_FEAT_TWED`` is set to ``1``, WFE instruction trapping gets
+    delayed by the amount of value in ``TWED_DELAY``.
+
+-  ``ENABLE_FEAT_VHE``: Numeric value to enable the ``FEAT_VHE`` (Virtualization
+   Host Extensions) extension. It allows access to CONTEXTIDR_EL2 register
+   during EL2 context save/restore operations.``FEAT_VHE`` is a mandatory
+   architectural feature and is enabled from v8.1 and upwards. It can take
+   values 0 to 2, to align  with the ``FEATURE_DETECTION`` mechanism.
+   Default value is ``0``.
+
+-  ``ENABLE_FEAT_TCR2``: Numeric value to set the bit SCR_EL3.ENTCR2 in EL3 to
+   allow access to TCR2_EL2 (extended translation control) from EL2 as
+   well as adding TCR2_EL2 to the EL2 context save/restore operations. Its a
+   mandatory architectural feature and is enabled from v8.9 and upwards. This
+   flag can take the values 0 to 2, to align  with the ``FEATURE_DETECTION``
+   mechanism. Default value is ``0``.
+
+-  ``ENABLE_FEAT_S2PIE``: Numeric value to enable support for FEAT_S2PIE
+   at EL2 and below, and context switch relevant registers.  This flag
+   can take the values 0 to 2, to align  with the ``FEATURE_DETECTION``
+   mechanism. Default value is ``0``.
+
+-  ``ENABLE_FEAT_S1PIE``: Numeric value to enable support for FEAT_S1PIE
+   at EL2 and below, and context switch relevant registers.  This flag
+   can take the values 0 to 2, to align  with the ``FEATURE_DETECTION``
+   mechanism. Default value is ``0``.
+
+-  ``ENABLE_FEAT_S2POE``: Numeric value to enable support for FEAT_S2POE
+   at EL2 and below, and context switch relevant registers.  This flag
+   can take the values 0 to 2, to align  with the ``FEATURE_DETECTION``
+   mechanism. Default value is ``0``.
+
+-  ``ENABLE_FEAT_S1POE``: Numeric value to enable support for FEAT_S1POE
+   at EL2 and below, and context switch relevant registers.  This flag
+   can take the values 0 to 2, to align  with the ``FEATURE_DETECTION``
+   mechanism. Default value is ``0``.
+
+-  ``ENABLE_FEAT_GCS``: Numeric value to set the bit SCR_EL3.GCSEn in EL3 to
+   allow use of Guarded Control Stack from EL2 as well as adding the GCS
+   registers to the EL2 context save/restore operations. This flag can take
+   the values 0 to 2, to align  with the ``FEATURE_DETECTION`` mechanism.
+   Default value is ``0``.
+
+-  ``ENABLE_LTO``: Boolean option to enable Link Time Optimization (LTO)
+   support in GCC for TF-A. This option is currently only supported for
+   AArch64. Default is 0.
+
+-  ``ENABLE_FEAT_MPAM``: Numeric value to enable lower ELs to use MPAM
+   feature. MPAM is an optional Armv8.4 extension that enables various memory
+   system components and resources to define partitions; software running at
+   various ELs can assign themselves to desired partition to control their
+   performance aspects.
+
+   This flag can take values 0 to 2, to align  with the ``FEATURE_DETECTION``
+   mechanism. When this option is set to ``1`` or ``2``, EL3 allows lower ELs to
+   access their own MPAM registers without trapping into EL3. This option
+   doesn't make use of partitioning in EL3, however. Platform initialisation
+   code should configure and use partitions in EL3 as required. This option
+   defaults to ``2`` since MPAM is enabled by default for NS world only.
+   The flag is automatically disabled when the target
+   architecture is AArch32.
+
+-  ``ENABLE_MPMM``: Boolean option to enable support for the Maximum Power
+   Mitigation Mechanism supported by certain Arm cores, which allows the SoC
+   firmware to detect and limit high activity events to assist in SoC processor
+   power domain dynamic power budgeting and limit the triggering of whole-rail
+   (i.e. clock chopping) responses to overcurrent conditions. Defaults to ``0``.
+
+-  ``ENABLE_MPMM_FCONF``: Enables configuration of MPMM through FCONF, which
+   allows platforms with cores supporting MPMM to describe them via the
+   ``HW_CONFIG`` device tree blob. Default is 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 BL2, BL31, and BL32 (TSP) for AARCH64 binaries, and
+   in BL32 (SP_min) for AARCH32. Default is 0.
+
+-  ``ENABLE_PMF``: Boolean option to enable support for optional Performance
+   Measurement Framework(PMF). Default is 0.
+
+-  ``ENABLE_PSCI_STAT``: Boolean option to enable support for optional PSCI
+   functions ``PSCI_STAT_RESIDENCY`` and ``PSCI_STAT_COUNT``. Default is 0.
+   In the absence of an alternate stat collection backend, ``ENABLE_PMF`` must
+   be enabled. If ``ENABLE_PMF`` is set, the residency statistics are tracked in
+   software.
+
+-  ``ENABLE_RUNTIME_INSTRUMENTATION``: Boolean option to enable runtime
+   instrumentation which injects timestamp collection points into TF-A to
+   allow runtime performance to be measured. Currently, only PSCI is
+   instrumented. Enabling this option enables the ``ENABLE_PMF`` build option
+   as well. Default is 0.
+
+-  ``ENABLE_SPE_FOR_NS`` : Numeric value to enable Statistical Profiling
+   extensions. This is an optional architectural feature for AArch64.
+   This flag can take the values 0 to 2, to align with the ``FEATURE_DETECTION``
+   mechanism. The default is 2 but is automatically disabled when the target
+   architecture is AArch32.
+
+-  ``ENABLE_SVE_FOR_NS``: Numeric value to enable Scalable Vector Extension
+   (SVE) for the Non-secure world only. SVE is an optional architectural feature
+   for AArch64. Note that when SVE is enabled for the Non-secure world, access
+   to SIMD and floating-point functionality from the Secure world is disabled by
+   default and controlled with ENABLE_SVE_FOR_SWD.
+   This is to avoid corruption of the Non-secure world data in the Z-registers
+   which are aliased by the SIMD and FP registers. The build option is not
+   compatible with the ``CTX_INCLUDE_FPREGS`` build option, and will raise an
+   assert on platforms where SVE is implemented and ``ENABLE_SVE_FOR_NS``
+   enabled.  This flag can take the values 0 to 2, to align with the
+   ``FEATURE_DETECTION`` mechanism. At this time, this build option cannot be
+   used on systems that have SPM_MM enabled. The default is 1.
+
+-  ``ENABLE_SVE_FOR_SWD``: Boolean option to enable SVE for the Secure world.
+   SVE is an optional architectural feature for AArch64. Note that this option
+   requires ENABLE_SVE_FOR_NS to be enabled. The default is 0 and it is
+   automatically disabled when the target architecture is AArch32.
+
+-  ``ENABLE_STACK_PROTECTOR``: String option to enable the stack protection
+   checks in GCC. Allowed values are "all", "strong", "default" and "none". The
+   default value is set to "none". "strong" is the recommended stack protection
+   level if this feature is desired. "none" disables the stack protection. For
+   all values other than "none", the ``plat_get_stack_protector_canary()``
+   platform hook needs to be implemented. The value is passed as the last
+   component of the option ``-fstack-protector-$ENABLE_STACK_PROTECTOR``.
+
+-  ``ENCRYPT_BL31``: Binary flag to enable encryption of BL31 firmware. This
+   flag depends on ``DECRYPTION_SUPPORT`` build flag.
+
+-  ``ENCRYPT_BL32``: Binary flag to enable encryption of Secure BL32 payload.
+   This flag depends on ``DECRYPTION_SUPPORT`` build flag.
+
+-  ``ENC_KEY``: A 32-byte (256-bit) symmetric key in hex string format. It could
+   either be SSK or BSSK depending on ``FW_ENC_STATUS`` flag. This value depends
+   on ``DECRYPTION_SUPPORT`` build flag.
+
+-  ``ENC_NONCE``: A 12-byte (96-bit) encryption nonce or Initialization Vector
+   (IV) in hex string format. This value depends on ``DECRYPTION_SUPPORT``
+   build flag.
+
+-  ``ERROR_DEPRECATED``: This option decides whether to treat the usage of
+   deprecated platform APIs, helper functions or drivers within Trusted
+   Firmware as error. It can take the value 1 (flag the use of deprecated
+   APIs as error) or 0. The default is 0.
+
+-  ``ETHOSN_NPU_DRIVER``: boolean option to enable a SiP service that can
+   configure an Arm® Ethos™-N NPU. To use this service the target platform's
+   ``HW_CONFIG`` must include the device tree nodes for the NPU. Currently, only
+   the Arm Juno platform has this included in its ``HW_CONFIG`` and the platform
+   only loads the ``HW_CONFIG`` in AArch64 builds. Default is 0.
+
+-  ``ETHOSN_NPU_TZMP1``: boolean option to enable TZMP1 support for the
+   Arm® Ethos™-N NPU. Requires ``ETHOSN_NPU_DRIVER`` and
+   ``TRUSTED_BOARD_BOOT`` to be enabled.
+
+-  ``ETHOSN_NPU_FW``: location of the NPU firmware binary
+   (```ethosn.bin```). This firmware image will be included in the FIP and
+   loaded at runtime.
+
+-  ``EL3_EXCEPTION_HANDLING``: When set to ``1``, enable handling of exceptions
+   targeted at EL3. When set ``0`` (default), no exceptions are expected or
+   handled at EL3, and a panic will result. The exception to this rule is when
+   ``SPMD_SPM_AT_SEL2`` is set to ``1``, in which case, only exceptions
+   occuring during normal world execution, are trapped to EL3. Any exception
+   trapped during secure world execution are trapped to the SPMC. This is
+   supported only for AArch64 builds.
+
+-  ``EVENT_LOG_LEVEL``: Chooses the log level to use for Measured Boot when
+   ``MEASURED_BOOT`` is enabled. For a list of valid values, see ``LOG_LEVEL``.
+   Default value is 40 (LOG_LEVEL_INFO).
+
+-  ``FAULT_INJECTION_SUPPORT``: ARMv8.4 extensions introduced support for fault
+   injection from lower ELs, and this build option enables lower ELs to use
+   Error Records accessed via System Registers to inject faults. This is
+   applicable only to AArch64 builds.
+
+   This feature is intended for testing purposes only, and is advisable to keep
+   disabled for production images.
+
+-  ``FIP_NAME``: This is an optional build option which specifies the FIP
+   filename for the ``fip`` target. Default is ``fip.bin``.
+
+-  ``FWU_FIP_NAME``: This is an optional build option which specifies the FWU
+   FIP filename for the ``fwu_fip`` target. Default is ``fwu_fip.bin``.
+
+-  ``FW_ENC_STATUS``: Top level firmware's encryption numeric flag, values:
+
+   ::
+
+     0: Encryption is done with Secret Symmetric Key (SSK) which is common
+        for a class of devices.
+     1: Encryption is done with Binding Secret Symmetric Key (BSSK) which is
+        unique per device.
+
+   This flag depends on ``DECRYPTION_SUPPORT`` build flag.
+
+-  ``GENERATE_COT``: Boolean flag used to build and execute the ``cert_create``
+   tool to create certificates as per the Chain of Trust described in
+   :ref:`Trusted Board Boot`. The build system then calls ``fiptool`` to
+   include the certificates in the FIP and FWU_FIP. Default value is '0'.
+
+   Specify both ``TRUSTED_BOARD_BOOT=1`` and ``GENERATE_COT=1`` to include support
+   for the Trusted Board Boot feature in the BL1 and BL2 images, to generate
+   the corresponding certificates, and to include those certificates in the
+   FIP and FWU_FIP.
+
+   Note that if ``TRUSTED_BOARD_BOOT=0`` and ``GENERATE_COT=1``, the BL1 and BL2
+   images will not include support for Trusted Board Boot. The FIP will still
+   include the corresponding certificates. This FIP can be used to verify the
+   Chain of Trust on the host machine through other mechanisms.
+
+   Note that if ``TRUSTED_BOARD_BOOT=1`` and ``GENERATE_COT=0``, the BL1 and BL2
+   images will include support for Trusted Board Boot, but the FIP and FWU_FIP
+   will not include the corresponding certificates, causing a boot failure.
+
+-  ``GICV2_G0_FOR_EL3``: Unlike GICv3, the GICv2 architecture doesn't have
+   inherent support for specific EL3 type interrupts. Setting this build option
+   to ``1`` assumes GICv2 *Group 0* interrupts are expected to target EL3, both
+   by :ref:`platform abstraction layer<platform Interrupt Controller API>` and
+   :ref:`Interrupt Management Framework<Interrupt Management Framework>`.
+   This allows GICv2 platforms to enable features requiring EL3 interrupt type.
+   This also means that all GICv2 Group 0 interrupts are delivered to EL3, and
+   the Secure Payload interrupts needs to be synchronously handed over to Secure
+   EL1 for handling. The default value of this option is ``0``, which means the
+   Group 0 interrupts are assumed to be handled by Secure EL1.
+
+-  ``HANDLE_EA_EL3_FIRST_NS``: When set to ``1``, External Aborts and SError
+   Interrupts, resulting from errors in NS world, will be always trapped in
+   EL3 i.e. in BL31 at runtime. When set to ``0`` (default), these exceptions
+   will be trapped in the current exception level (or in EL1 if the current
+   exception level is EL0).
+
+-  ``HW_ASSISTED_COHERENCY``: On most Arm systems to-date, platform-specific
+   software operations are required for CPUs to enter and exit coherency.
+   However, newer systems exist where CPUs' entry to and exit from coherency
+   is managed in hardware. Such systems require software to only initiate these
+   operations, and the rest is managed in hardware, minimizing active software
+   management. In such systems, this boolean option enables TF-A to carry out
+   build and run-time optimizations during boot and power management operations.
+   This option defaults to 0 and if it is enabled, then it implies
+   ``WARMBOOT_ENABLE_DCACHE_EARLY`` is also enabled.
+
+   If this flag is disabled while the platform which TF-A is compiled for
+   includes cores that manage coherency in hardware, then a compilation error is
+   generated. This is based on the fact that a system cannot have, at the same
+   time, cores that manage coherency in hardware and cores that don't. In other
+   words, a platform cannot have, at the same time, cores that require
+   ``HW_ASSISTED_COHERENCY=1`` and cores that require
+   ``HW_ASSISTED_COHERENCY=0``.
+
+   Note that, when ``HW_ASSISTED_COHERENCY`` is enabled, version 2 of
+   translation library (xlat tables v2) must be used; version 1 of translation
+   library is not supported.
+
+-  ``IMPDEF_SYSREG_TRAP``: Numeric value to enable the handling traps for
+   implementation defined system register accesses from lower ELs. Default
+   value is ``0``.
+
+-  ``INVERTED_MEMMAP``: memmap tool print by default lower addresses at the
+   bottom, higher addresses at the top. This build flag can be set to '1' to
+   invert this behavior. Lower addresses will be printed at the top and higher
+   addresses at the bottom.
+
+-  ``KEY_ALG``: This build flag enables the user to select the algorithm to be
+   used for generating the PKCS keys and subsequent signing of the certificate.
+   It accepts 5 values: ``rsa``, ``rsa_1_5``, ``ecdsa``, ``ecdsa-brainpool-regular``
+   and ``ecdsa-brainpool-twisted``. The option ``rsa_1_5`` is the legacy PKCS#1
+   RSA 1.5 algorithm which is not TBBR compliant and is retained only for
+   compatibility. The default value of this flag is ``rsa`` which is the TBBR
+   compliant PKCS#1 RSA 2.1 scheme.
+
+-  ``KEY_SIZE``: This build flag enables the user to select the key size for
+   the algorithm specified by ``KEY_ALG``. The valid values for ``KEY_SIZE``
+   depend on the chosen algorithm and the cryptographic module.
+
+   +---------------------------+------------------------------------+
+   |         KEY_ALG           |        Possible key sizes          |
+   +===========================+====================================+
+   |           rsa             | 1024 , 2048 (default), 3072, 4096  |
+   +---------------------------+------------------------------------+
+   |          ecdsa            |         256 (default), 384         |
+   +---------------------------+------------------------------------+
+   |  ecdsa-brainpool-regular  |            unavailable             |
+   +---------------------------+------------------------------------+
+   |  ecdsa-brainpool-twisted  |            unavailable             |
+   +---------------------------+------------------------------------+
+
+-  ``HASH_ALG``: This build flag enables the user to select the secure hash
+   algorithm. It accepts 3 values: ``sha256``, ``sha384`` and ``sha512``.
+   The default value of this flag is ``sha256``.
+
+-  ``LDFLAGS``: Extra user options appended to the linkers' command line in
+   addition to the one set by the build system.
+
+-  ``LOG_LEVEL``: Chooses the log level, which controls the amount of console log
+   output compiled into the build. This should be one of the following:
+
+   ::
+
+       0  (LOG_LEVEL_NONE)
+       10 (LOG_LEVEL_ERROR)
+       20 (LOG_LEVEL_NOTICE)
+       30 (LOG_LEVEL_WARNING)
+       40 (LOG_LEVEL_INFO)
+       50 (LOG_LEVEL_VERBOSE)
+
+   All log output up to and including the selected log level is compiled into
+   the build. The default value is 40 in debug builds and 20 in release builds.
+
+-  ``MEASURED_BOOT``: Boolean flag to include support for the Measured Boot
+   feature. This flag can be enabled with ``TRUSTED_BOARD_BOOT`` in order to
+   provide trust that the code taking the measurements and recording them has
+   not been tampered with.
+
+   This option defaults to 0.
+
+-  ``MARCH_DIRECTIVE``: used to pass a -march option from the platform build
+   options to the compiler. An example usage:
+
+   .. code:: make
+
+      MARCH_DIRECTIVE := -march=armv8.5-a
+
+-  ``NON_TRUSTED_WORLD_KEY``: This option is used when ``GENERATE_COT=1``. It
+   specifies a file that contains the Non-Trusted World private key in PEM
+   format or a PKCS11 URI. If ``SAVE_KEYS=1``, only a file is accepted and it
+   will be used to save the key.
+
+-  ``NS_BL2U``: Path to NS_BL2U image in the host file system. This image is
+   optional. It is only needed if the platform makefile specifies that it
+   is required in order to build the ``fwu_fip`` target.
+
+-  ``NS_TIMER_SWITCH``: Enable save and restore for non-secure timer register
+   contents upon world switch. It can take either 0 (don't save and restore) or
+   1 (do save and restore). 0 is the default. An SPD may set this to 1 if it
+   wants the timer registers to be saved and restored.
+
+-  ``OPTEE_SP_FW_CONFIG``: DTC build flag to include OP-TEE as SP in
+   tb_fw_config device tree. This flag is defined only when
+   ``ARM_SPMC_MANIFEST_DTS`` manifest file name contains pattern optee_sp.
+
+-  ``OVERRIDE_LIBC``: This option allows platforms to override the default libc
+   for the BL image. It can be either 0 (include) or 1 (remove). The default
+   value is 0.
+
+-  ``PL011_GENERIC_UART``: Boolean option to indicate the PL011 driver that
+   the underlying hardware is not a full PL011 UART but a minimally compliant
+   generic UART, which is a subset of the PL011. The driver will not access
+   any register that is not part of the SBSA generic UART specification.
+   Default value is 0 (a full PL011 compliant UART is present).
+
+-  ``PLAT``: Choose a platform to build TF-A for. The chosen platform name
+   must be subdirectory of any depth under ``plat/``, and must contain a
+   platform makefile named ``platform.mk``. For example, to build TF-A for the
+   Arm Juno board, select PLAT=juno.
+
+-  ``PRELOADED_BL33_BASE``: This option enables booting a preloaded BL33 image
+   instead of the normal boot flow. When defined, it must specify the entry
+   point address for the preloaded BL33 image. This option is incompatible with
+   ``EL3_PAYLOAD_BASE``. If both are defined, ``EL3_PAYLOAD_BASE`` has priority
+   over ``PRELOADED_BL33_BASE``.
+
+-  ``PROGRAMMABLE_RESET_ADDRESS``: This option indicates whether the reset
+   vector address can be programmed or is fixed on the platform. It can take
+   either 0 (fixed) or 1 (programmable). Default is 0. If the platform has a
+   programmable reset address, it is expected that a CPU will start executing
+   code directly at the right address, both on a cold and warm reset. In this
+   case, there is no need to identify the entrypoint on boot and the boot path
+   can be optimised. The ``plat_get_my_entrypoint()`` platform porting interface
+   does not need to be implemented in this case.
+
+-  ``PSCI_EXTENDED_STATE_ID``: As per PSCI1.0 Specification, there are 2 formats
+   possible for the PSCI power-state parameter: original and extended State-ID
+   formats. This flag if set to 1, configures the generic PSCI layer to use the
+   extended format. The default value of this flag is 0, which means by default
+   the original power-state format is used by the PSCI implementation. This flag
+   should be specified by the platform makefile and it governs the return value
+   of PSCI_FEATURES API for CPU_SUSPEND smc function id. When this option is
+   enabled on Arm platforms, the option ``ARM_RECOM_STATE_ID_ENC`` needs to be
+   set to 1 as well.
+
+-  ``PSCI_OS_INIT_MODE``: Boolean flag to enable support for optional PSCI
+   OS-initiated mode. This option defaults to 0.
+
+-  ``ENABLE_FEAT_RAS``: Boolean flag to enable Armv8.2 RAS features. RAS features
+   are an optional extension for pre-Armv8.2 CPUs, but are mandatory for Armv8.2
+   or later CPUs. This flag can take the values 0 or 1. The default value is 0.
+   NOTE: This flag enables use of IESB capability to reduce entry latency into
+   EL3 even when RAS error handling is not performed on the platform. Hence this
+   flag is recommended to be turned on Armv8.2 and later CPUs.
+
+-  ``RESET_TO_BL31``: Enable BL31 entrypoint as the CPU reset vector instead
+   of the BL1 entrypoint. It can take the value 0 (CPU reset to BL1
+   entrypoint) or 1 (CPU reset to BL31 entrypoint).
+   The default value is 0.
+
+-  ``RESET_TO_SP_MIN``: SP_MIN is the minimal AArch32 Secure Payload provided
+   in TF-A. This flag configures SP_MIN entrypoint as the CPU reset vector
+   instead of the BL1 entrypoint. It can take the value 0 (CPU reset to BL1
+   entrypoint) or 1 (CPU reset to SP_MIN entrypoint). The default value is 0.
+
+-  ``ROT_KEY``: This option is used when ``GENERATE_COT=1``. It specifies a
+   file that contains the ROT private key in PEM format or a PKCS11 URI and
+   enforces public key hash generation. If ``SAVE_KEYS=1``, only a file is
+   accepted and it will be used to save the key.
+
+-  ``SAVE_KEYS``: This option is used when ``GENERATE_COT=1``. It tells the
+   certificate generation tool to save the keys used to establish the Chain of
+   Trust. Allowed options are '0' or '1'. Default is '0' (do not save).
+
+-  ``SCP_BL2``: Path to SCP_BL2 image in the host file system. This image is optional.
+   If a SCP_BL2 image is present then this option must be passed for the ``fip``
+   target.
+
+-  ``SCP_BL2_KEY``: This option is used when ``GENERATE_COT=1``. It specifies a
+   file that contains the SCP_BL2 private key in PEM format or a PKCS11 URI.
+   If ``SAVE_KEYS=1``, only a file is accepted and it will be used to save the key.
+
+-  ``SCP_BL2U``: Path to SCP_BL2U image in the host file system. This image is
+   optional. It is only needed if the platform makefile specifies that it
+   is required in order to build the ``fwu_fip`` target.
+
+-  ``SDEI_SUPPORT``: Setting this to ``1`` enables support for Software
+   Delegated Exception Interface to BL31 image. This defaults to ``0``.
+
+   When set to ``1``, the build option ``EL3_EXCEPTION_HANDLING`` must also be
+   set to ``1``.
+
+-  ``SEPARATE_CODE_AND_RODATA``: Whether code and read-only data should be
+   isolated on separate memory pages. This is a trade-off between security and
+   memory usage. See "Isolating code and read-only data on separate memory
+   pages" section in :ref:`Firmware Design`. This flag is disabled by default
+   and affects all BL images.
+
+-  ``SEPARATE_NOBITS_REGION``: Setting this option to ``1`` allows the NOBITS
+   sections of BL31 (.bss, stacks, page tables, and coherent memory) to be
+   allocated in RAM discontiguous from the loaded firmware image. When set, the
+   platform is expected to provide definitions for ``BL31_NOBITS_BASE`` and
+   ``BL31_NOBITS_LIMIT``. When the option is ``0`` (the default), NOBITS
+   sections are placed in RAM immediately following the loaded firmware image.
+
+-  ``SEPARATE_BL2_NOLOAD_REGION``: Setting this option to ``1`` allows the
+   NOLOAD sections of BL2 (.bss, stacks, page tables) to be allocated in RAM
+   discontiguous from loaded firmware images. When set, the platform need to
+   provide definitions of ``BL2_NOLOAD_START`` and ``BL2_NOLOAD_LIMIT``. This
+   flag is disabled by default and NOLOAD sections are placed in RAM immediately
+   following the loaded firmware image.
+
+-  ``SMC_PCI_SUPPORT``: This option allows platforms to handle PCI configuration
+   access requests via a standard SMCCC defined in `DEN0115`_. When combined with
+   UEFI+ACPI this can provide a certain amount of OS forward compatibility
+   with newer platforms that aren't ECAM compliant.
+
+-  ``SPD``: Choose a Secure Payload Dispatcher component to be built into TF-A.
+   This build option is only valid if ``ARCH=aarch64``. The value should be
+   the path to the directory containing the SPD source, relative to
+   ``services/spd/``; the directory is expected to contain a makefile called
+   ``<spd-value>.mk``. The SPM Dispatcher standard service is located in
+   services/std_svc/spmd and enabled by ``SPD=spmd``. The SPM Dispatcher
+   cannot be enabled when the ``SPM_MM`` option is enabled.
+
+-  ``SPIN_ON_BL1_EXIT``: This option introduces an infinite loop in BL1. It can
+   take either 0 (no loop) or 1 (add a loop). 0 is the default. This loop stops
+   execution in BL1 just before handing over to BL31. At this point, all
+   firmware images have been loaded in memory, and the MMU and caches are
+   turned off. Refer to the "Debugging options" section for more details.
+
+-  ``SPMC_AT_EL3`` : This boolean option is used jointly with the SPM
+   Dispatcher option (``SPD=spmd``). When enabled (1) it indicates the SPMC
+   component runs at the EL3 exception level. The default value is ``0`` (
+   disabled). This configuration supports pre-Armv8.4 platforms (aka not
+   implementing the ``FEAT_SEL2`` extension).
+
+-  ``SPMC_AT_EL3_SEL0_SP`` : Boolean option to enable SEL0 SP load support when
+   ``SPMC_AT_EL3`` is enabled. The default value if ``0`` (disabled). This
+   option cannot be enabled (``1``) when (``SPMC_AT_EL3``) is disabled.
+
+-  ``SPMC_OPTEE`` : This boolean option is used jointly with the SPM
+   Dispatcher option (``SPD=spmd``) and with ``SPMD_SPM_AT_SEL2=0`` to
+   indicate that the SPMC at S-EL1 is OP-TEE and an OP-TEE specific loading
+   mechanism should be used.
+
+-  ``SPMD_SPM_AT_SEL2`` : This boolean option is used jointly with the SPM
+   Dispatcher option (``SPD=spmd``). When enabled (1) it indicates the SPMC
+   component runs at the S-EL2 exception level provided by the ``FEAT_SEL2``
+   extension. This is the default when enabling the SPM Dispatcher. When
+   disabled (0) it indicates the SPMC component runs at the S-EL1 execution
+   state or at EL3 if ``SPMC_AT_EL3`` is enabled. The latter configurations
+   support pre-Armv8.4 platforms (aka not implementing the ``FEAT_SEL2``
+   extension).
+
+-  ``SPM_MM`` : Boolean option to enable the Management Mode (MM)-based Secure
+   Partition Manager (SPM) implementation. The default value is ``0``
+   (disabled). This option cannot be enabled (``1``) when SPM Dispatcher is
+   enabled (``SPD=spmd``).
+
+-  ``SP_LAYOUT_FILE``: Platform provided path to JSON file containing the
+   description of secure partitions. The build system will parse this file and
+   package all secure partition blobs into the FIP. This file is not
+   necessarily part of TF-A tree. Only available when ``SPD=spmd``.
+
+-  ``SP_MIN_WITH_SECURE_FIQ``: Boolean flag to indicate the SP_MIN handles
+   secure interrupts (caught through the FIQ line). Platforms can enable
+   this directive if they need to handle such interruption. When enabled,
+   the FIQ are handled in monitor mode and non secure world is not allowed
+   to mask these events. Platforms that enable FIQ handling in SP_MIN shall
+   implement the api ``sp_min_plat_fiq_handler()``. The default value is 0.
+
+-  ``SVE_VECTOR_LEN``: SVE vector length to configure in ZCR_EL3.
+   Platforms can configure this if they need to lower the hardware
+   limit, for example due to asymmetric configuration or limitations of
+   software run at lower ELs. The default is the architectural maximum
+   of 2048 which should be suitable for most configurations, the
+   hardware will limit the effective VL to the maximum physically supported
+   VL.
+
+-  ``TRNG_SUPPORT``: Setting this to ``1`` enables support for True
+   Random Number Generator Interface to BL31 image. This defaults to ``0``.
+
+-  ``TRUSTED_BOARD_BOOT``: Boolean flag to include support for the Trusted Board
+   Boot feature. When set to '1', BL1 and BL2 images include support to load
+   and verify the certificates and images in a FIP, and BL1 includes support
+   for the Firmware Update. The default value is '0'. Generation and inclusion
+   of certificates in the FIP and FWU_FIP depends upon the value of the
+   ``GENERATE_COT`` option.
+
+   .. warning::
+      This option depends on ``CREATE_KEYS`` to be enabled. If the keys
+      already exist in disk, they will be overwritten without further notice.
+
+-  ``TRUSTED_WORLD_KEY``: This option is used when ``GENERATE_COT=1``. It
+   specifies a file that contains the Trusted World private key in PEM
+   format or a PKCS11 URI. If ``SAVE_KEYS=1``, only a file is accepted and
+   it will be used to save the key.
+
+-  ``TSP_INIT_ASYNC``: Choose BL32 initialization method as asynchronous or
+   synchronous, (see "Initializing a BL32 Image" section in
+   :ref:`Firmware Design`). It can take the value 0 (BL32 is initialized using
+   synchronous method) or 1 (BL32 is initialized using asynchronous method).
+   Default is 0.
+
+-  ``TSP_NS_INTR_ASYNC_PREEMPT``: A non zero value enables the interrupt
+   routing model which routes non-secure interrupts asynchronously from TSP
+   to EL3 causing immediate preemption of TSP. The EL3 is responsible
+   for saving and restoring the TSP context in this routing model. The
+   default routing model (when the value is 0) is to route non-secure
+   interrupts to TSP allowing it to save its context and hand over
+   synchronously to EL3 via an SMC.
+
+   .. note::
+      When ``EL3_EXCEPTION_HANDLING`` is ``1``, ``TSP_NS_INTR_ASYNC_PREEMPT``
+      must also be set to ``1``.
+
+-  ``TS_SP_FW_CONFIG``: DTC build flag to include Trusted Services (Crypto and
+   internal-trusted-storage) as SP in tb_fw_config device tree.
+
+-  ``TWED_DELAY``: Numeric value to be set in order to delay the trapping of
+   WFE instruction. ``ENABLE_FEAT_TWED`` build option must be enabled to set
+   this delay. It can take values in the range (0-15). Default value is ``0``
+   and based on this value, 2^(TWED_DELAY + 8) cycles will be delayed.
+   Platforms need to explicitly update this value based on their requirements.
+
+-  ``USE_ARM_LINK``: This flag determines whether to enable support for ARM
+   linker. When the ``LINKER`` build variable points to the armlink linker,
+   this flag is enabled automatically. To enable support for armlink, platforms
+   will have to provide a scatter file for the BL image. Currently, Tegra
+   platforms use the armlink support to compile BL3-1 images.
+
+-  ``USE_COHERENT_MEM``: This flag determines whether to include the coherent
+   memory region in the BL memory map or not (see "Use of Coherent memory in
+   TF-A" section in :ref:`Firmware Design`). It can take the value 1
+   (Coherent memory region is included) or 0 (Coherent memory region is
+   excluded). Default is 1.
+
+-  ``ARM_IO_IN_DTB``: This flag determines whether to use IO based on the
+   firmware configuration framework. This will move the io_policies into a
+   configuration device tree, instead of static structure in the code base.
+
+-  ``COT_DESC_IN_DTB``: This flag determines whether to create COT descriptors
+   at runtime using fconf. If this flag is enabled, COT descriptors are
+   statically captured in tb_fw_config file in the form of device tree nodes
+   and properties. Currently, COT descriptors used by BL2 are moved to the
+   device tree and COT descriptors used by BL1 are retained in the code
+   base statically.
+
+-  ``SDEI_IN_FCONF``: This flag determines whether to configure SDEI setup in
+   runtime using firmware configuration framework. The platform specific SDEI
+   shared and private events configuration is retrieved from device tree rather
+   than static C structures at compile time. This is only supported if
+   SDEI_SUPPORT build flag is enabled.
+
+-  ``SEC_INT_DESC_IN_FCONF``: This flag determines whether to configure Group 0
+   and Group1 secure interrupts using the firmware configuration framework. The
+   platform specific secure interrupt property descriptor is retrieved from
+   device tree in runtime rather than depending on static C structure at compile
+   time.
+
+-  ``USE_ROMLIB``: This flag determines whether library at ROM will be used.
+   This feature creates a library of functions to be placed in ROM and thus
+   reduces SRAM usage. Refer to :ref:`Library at ROM` for further details. Default
+   is 0.
+
+-  ``V``: Verbose build. If assigned anything other than 0, the build commands
+   are printed. Default is 0.
+
+-  ``VERSION_STRING``: String used in the log output for each TF-A image.
+   Defaults to a string formed by concatenating the version number, build type
+   and build string.
+
+-  ``W``: Warning level. Some compiler warning options of interest have been
+   regrouped and put in the root Makefile. This flag can take the values 0 to 3,
+   each level enabling more warning options. Default is 0.
+
+   This option is closely related to the ``E`` option, which enables
+   ``-Werror``.
+
+   - ``W=0`` (default)
+
+     Enables a wide assortment of warnings, most notably ``-Wall`` and
+     ``-Wextra``, as well as various bad practices and things that are likely to
+     result in errors. Includes some compiler specific flags. No warnings are
+     expected at this level for any build.
+
+   - ``W=1``
+
+     Enables warnings we want the generic build to include but are too time
+     consuming to fix at the moment. It re-enables warnings taken out for
+     ``W=0`` builds (a few of the ``-Wextra`` additions). This level is expected
+     to eventually be merged into ``W=0``. Some warnings are expected on some
+     builds, but new contributions should not introduce new ones.
+
+   - ``W=2`` (recommended)
+
+    Enables warnings we want the generic build to include but cannot be enabled
+    due to external libraries. This level is expected to eventually be merged
+    into ``W=0``. Lots of warnings are expected, primarily from external
+    libraries like zlib and compiler-rt, but new controbutions should not
+    introduce new ones.
+
+   - ``W=3``
+
+     Enables warnings that are informative but not necessary and generally too
+     verbose and frequently ignored. A very large number of warnings are
+     expected.
+
+   The exact set of warning flags depends on the compiler and TF-A warning
+   level, however they are all succinctly set in the top-level Makefile. Please
+   refer to the `GCC`_ or `Clang`_ documentation for more information on the
+   individual flags.
+
+-  ``WARMBOOT_ENABLE_DCACHE_EARLY`` : Boolean option to enable D-cache early on
+   the CPU after warm boot. This is applicable for platforms which do not
+   require interconnect programming to enable cache coherency (eg: single
+   cluster platforms). If this option is enabled, then warm boot path
+   enables D-caches immediately after enabling MMU. This option defaults to 0.
+
+-  ``SUPPORT_STACK_MEMTAG``: This flag determines whether to enable memory
+   tagging for stack or not. It accepts 2 values: ``yes`` and ``no``. The
+   default value of this flag is ``no``. Note this option must be enabled only
+   for ARM architecture greater than Armv8.5-A.
+
+-  ``ERRATA_SPECULATIVE_AT``: This flag determines whether to enable ``AT``
+   speculative errata workaround or not. It accepts 2 values: ``1`` and ``0``.
+   The default value of this flag is ``0``.
+
+   ``AT`` speculative errata workaround disables stage1 page table walk for
+   lower ELs (EL1 and EL0) in EL3 so that ``AT`` speculative fetch at any point
+   produces either the correct result or failure without TLB allocation.
+
+   This boolean option enables errata for all below CPUs.
+
+   +---------+--------------+-------------------------+
+   | Errata  |      CPU     |     Workaround Define   |
+   +=========+==============+=========================+
+   | 1165522 |  Cortex-A76  |  ``ERRATA_A76_1165522`` |
+   +---------+--------------+-------------------------+
+   | 1319367 |  Cortex-A72  |  ``ERRATA_A72_1319367`` |
+   +---------+--------------+-------------------------+
+   | 1319537 |  Cortex-A57  |  ``ERRATA_A57_1319537`` |
+   +---------+--------------+-------------------------+
+   | 1530923 |  Cortex-A55  |  ``ERRATA_A55_1530923`` |
+   +---------+--------------+-------------------------+
+   | 1530924 |  Cortex-A53  |  ``ERRATA_A53_1530924`` |
+   +---------+--------------+-------------------------+
+
+   .. note::
+      This option is enabled by build only if platform sets any of above defines
+      mentioned in ’Workaround Define' column in the table.
+      If this option is enabled for the EL3 software then EL2 software also must
+      implement this workaround due to the behaviour of the errata mentioned
+      in new SDEN document which will get published soon.
+
+- ``RAS_TRAP_NS_ERR_REC_ACCESS``: This flag enables/disables the SCR_EL3.TERR
+  bit, to trap access to the RAS ERR and RAS ERX registers from lower ELs.
+  This flag is disabled by default.
+
+- ``OPENSSL_DIR``: This option is used to provide the path to a directory on the
+  host machine where a custom installation of OpenSSL is located, which is used
+  to build the certificate generation, firmware encryption and FIP tools. If
+  this option is not set, the default OS installation will be used.
+
+- ``USE_SP804_TIMER``: Use the SP804 timer instead of the Generic Timer for
+  functions that wait for an arbitrary time length (udelay and mdelay). The
+  default value is 0.
+
+- ``ENABLE_BRBE_FOR_NS``: Numeric value to enable access to the branch record
+  buffer registers from NS ELs when FEAT_BRBE is implemented. BRBE is an
+  optional architectural feature for AArch64. This flag can take the values
+  0 to 2, to align with the ``FEATURE_DETECTION`` mechanism. The default is 0
+  and it is automatically disabled when the target architecture is AArch32.
+
+- ``ENABLE_TRBE_FOR_NS``: Numeric value to enable access of trace buffer
+  control registers from NS ELs, NS-EL2 or NS-EL1(when NS-EL2 is implemented
+  but unused) when FEAT_TRBE is implemented. TRBE is an optional architectural
+  feature for AArch64. This flag can take the values  0 to 2, to align with the
+  ``FEATURE_DETECTION`` mechanism. The default is 0 and it is automatically
+  disabled when the target architecture is AArch32.
+
+- ``ENABLE_SYS_REG_TRACE_FOR_NS``: Numeric value to enable trace system
+  registers access from NS ELs, NS-EL2 or NS-EL1 (when NS-EL2 is implemented
+  but unused). This feature is available if trace unit such as ETMv4.x, and
+  ETE(extending ETM feature) is implemented. This flag can take the values
+  0 to 2, to align with the ``FEATURE_DETECTION`` mechanism. The default is 0.
+
+- ``ENABLE_TRF_FOR_NS``: Numeric value to enable trace filter control registers
+  access from NS ELs, NS-EL2 or NS-EL1 (when NS-EL2 is implemented but unused),
+  if FEAT_TRF is implemented. This flag can take the values 0 to 2, to align
+  with the ``FEATURE_DETECTION`` mechanism. This flag is disabled by default.
+
+- ``PLAT_RSS_NOT_SUPPORTED``: Boolean option to enable the usage of the PSA
+  APIs on platforms that doesn't support RSS (providing Arm CCA HES
+  functionalities). When enabled (``1``), a mocked version of the APIs are used.
+  The default value is 0.
+
+- ``CONDITIONAL_CMO``: Boolean option to enable call to platform-defined routine
+  ``plat_can_cmo`` which will return zero if cache management operations should
+  be skipped and non-zero otherwise. By default, this option is disabled which
+  means platform hook won't be checked and CMOs will always be performed when
+  related functions are called.
+
+- ``ERRATA_ABI_SUPPORT``: Boolean option to enable support for Errata management
+  firmware interface for the BL31 image. By default its disabled (``0``).
+
+- ``ERRATA_NON_ARM_INTERCONNECT``: Boolean option to enable support for the
+  errata mitigation for platforms with a non-arm interconnect using the errata
+  ABI. By default its disabled (``0``).
+
+- ``ENABLE_CONSOLE_GETC``: Boolean option to enable `getc()` feature in console
+  driver(s). By default it is disabled (``0``) because it constitutes an attack
+  vector into TF-A by potentially allowing an attacker to inject arbitrary data.
+  This option should only be enabled on a need basis if there is a use case for
+  reading characters from the console.
+
+GICv3 driver options
+--------------------
+
+GICv3 driver files are included using directive:
+
+``include drivers/arm/gic/v3/gicv3.mk``
+
+The driver can be configured with the following options set in the platform
+makefile:
+
+-  ``GICV3_SUPPORT_GIC600``: Add support for the GIC-600 variants of GICv3.
+   Enabling this option will add runtime detection support for the
+   GIC-600, so is safe to select even for a GIC500 implementation.
+   This option defaults to 0.
+
+- ``GICV3_SUPPORT_GIC600AE_FMU``: Add support for the Fault Management Unit
+   for GIC-600 AE. Enabling this option will introduce support to initialize
+   the FMU. Platforms should call the init function during boot to enable the
+   FMU and its safety mechanisms. This option defaults to 0.
+
+-  ``GICV3_IMPL_GIC600_MULTICHIP``: Selects GIC-600 variant with multichip
+   functionality. This option defaults to 0
+
+-  ``GICV3_OVERRIDE_DISTIF_PWR_OPS``: Allows override of default implementation
+   of ``arm_gicv3_distif_pre_save`` and ``arm_gicv3_distif_post_restore``
+   functions. This is required for FVP platform which need to simulate GIC save
+   and restore during SYSTEM_SUSPEND without powering down GIC. Default is 0.
+
+-  ``GIC_ENABLE_V4_EXTN`` : Enables GICv4 related changes in GICv3 driver.
+   This option defaults to 0.
+
+-  ``GIC_EXT_INTID``: When set to ``1``, GICv3 driver will support extended
+   PPI (1056-1119) and SPI (4096-5119) range. This option defaults to 0.
+
+Debugging options
+-----------------
+
+To compile a debug version and make the build more verbose use
+
+.. code:: shell
+
+    make PLAT=<platform> DEBUG=1 V=1 all
+
+AArch64 GCC 11 uses DWARF version 5 debugging symbols by default. Some tools
+(for example Arm-DS) might not support this and may need an older version of
+DWARF symbols to be emitted by GCC. This can be achieved by using the
+``-gdwarf-<version>`` flag, with the version being set to 2, 3, 4 or 5. Setting
+the version to 4 is recommended for Arm-DS.
+
+When debugging logic problems it might also be useful to disable all compiler
+optimizations by using ``-O0``.
+
+.. warning::
+   Using ``-O0`` could cause output images to be larger and base addresses
+   might need to be recalculated (see the **Memory layout on Arm development
+   platforms** section in the :ref:`Firmware Design`).
+
+Extra debug options can be passed to the build system by setting ``CFLAGS`` or
+``LDFLAGS``:
+
+.. code:: shell
+
+    CFLAGS='-O0 -gdwarf-2'                                     \
+    make PLAT=<platform> DEBUG=1 V=1 all
+
+Note that using ``-Wl,`` style compilation driver options in ``CFLAGS`` will be
+ignored as the linker is called directly.
+
+It is also possible to introduce an infinite loop to help in debugging the
+post-BL2 phase of TF-A. This can be done by rebuilding BL1 with the
+``SPIN_ON_BL1_EXIT=1`` build flag. Refer to the :ref:`build_options_common`
+section. In this case, the developer may take control of the target using a
+debugger when indicated by the console output. When using Arm-DS, the following
+commands can be used:
+
+::
+
+    # Stop target execution
+    interrupt
+
+    #
+    # Prepare your debugging environment, e.g. set breakpoints
+    #
+
+    # Jump over the debug loop
+    set var $AARCH64::$Core::$PC = $AARCH64::$Core::$PC + 4
+
+    # Resume execution
+    continue
+
+.. _build_options_experimental:
+
+Experimental build options
+---------------------------
+
+Common build options
+~~~~~~~~~~~~~~~~~~~~
+
+-  ``DRTM_SUPPORT``: Boolean flag to enable support for Dynamic Root of Trust
+   for Measurement (DRTM). This feature has trust dependency on BL31 for taking
+   the measurements and recording them as per `PSA DRTM specification`_. For
+   platforms which use BL2 to load/authenticate BL31 ``TRUSTED_BOARD_BOOT`` can
+   be used and for the platforms which use ``RESET_TO_BL31`` platform owners
+   should have mechanism to authenticate BL31. This option defaults to 0.
+
+-  ``ENABLE_RME``: Numeric value to enable support for the ARMv9 Realm
+   Management Extension. This flag can take the values 0 to 2, to align with
+   the ``FEATURE_DETECTION`` mechanism. Default value is 0.
+
+-  ``ENABLE_SME_FOR_NS``: Numeric value to enable Scalable Matrix Extension
+   (SME), SVE, and FPU/SIMD for the non-secure world only. These features share
+   registers so are enabled together. Using this option without
+   ENABLE_SME_FOR_SWD=1 will cause SME, SVE, and FPU/SIMD instructions in secure
+   world to trap to EL3. Requires ``ENABLE_SVE_FOR_NS`` to be set as SME is a
+   superset of SVE. SME is an optional architectural feature for AArch64.
+   At this time, this build option cannot be used on systems that have
+   SPD=spmd/SPM_MM and atempting to build with this option will fail.
+   This flag can take the values 0 to 2, to align with the ``FEATURE_DETECTION``
+   mechanism. Default is 0.
+
+-  ``ENABLE_SME2_FOR_NS``: Numeric value to enable Scalable Matrix Extension
+   version 2 (SME2) for the non-secure world only. SME2 is an optional
+   architectural feature for AArch64.
+   This should be set along with ENABLE_SME_FOR_NS=1, if not, the default SME
+   accesses will still be trapped. This flag can take the values 0 to 2, to
+   align with the ``FEATURE_DETECTION`` mechanism. Default is 0.
+
+-  ``ENABLE_SME_FOR_SWD``: Boolean option to enable the Scalable Matrix
+   Extension for secure world. Used along with SVE and FPU/SIMD.
+   ENABLE_SME_FOR_NS and ENABLE_SVE_FOR_SWD must also be set to use this.
+   Default is 0.
+
+-  ``ENABLE_SPMD_LP`` : This boolean option is used jointly with the SPM
+   Dispatcher option (``SPD=spmd``). When enabled (1) it indicates support
+   for logical partitions in EL3, managed by the SPMD as defined in the
+   FF-A v1.2 specification. This flag is disabled by default. This flag
+   must not be used if ``SPMC_AT_EL3`` is enabled.
+
+-  ``FEATURE_DETECTION``: Boolean option to enable the architectural features
+   detection mechanism. It detects whether the Architectural features enabled
+   through feature specific build flags are supported by the PE or not by
+   validating them either at boot phase or at runtime based on the value
+   possessed by the feature flag (0 to 2) and report error messages at an early
+   stage. This flag will also enable errata ordering checking for ``DEBUG``
+   builds.
+
+   This prevents and benefits us from EL3 runtime exceptions during context save
+   and restore routines guarded by these build flags. Henceforth validating them
+   before their usage provides more control on the actions taken under them.
+
+   The mechanism permits the build flags to take values 0, 1 or 2 and
+   evaluates them accordingly.
+
+   Lets consider ``ENABLE_FEAT_HCX``, build flag for ``FEAT_HCX`` as an example:
+
+   ::
+
+     ENABLE_FEAT_HCX = 0: Feature disabled statically at compile time.
+     ENABLE_FEAT_HCX = 1: Feature Enabled and the flag is validated at boottime.
+     ENABLE_FEAT_HCX = 2: Feature Enabled and the flag is validated at runtime.
+
+   In the above example, if the feature build flag, ``ENABLE_FEAT_HCX`` set to
+   0, feature is disabled statically during compilation. If it is defined as 1,
+   feature is validated, wherein FEAT_HCX is detected at boot time. In case not
+   implemented by the PE, a hard panic is generated. Finally, if the flag is set
+   to 2, feature is validated at runtime.
+
+   Note that the entire implementation is divided into two phases, wherein as
+   as part of phase-1 we are supporting the values 0,1. Value 2 is currently not
+   supported and is planned to be handled explicilty in phase-2 implementation.
+
+   ``FEATURE_DETECTION`` macro is disabled by default. Platforms can explicitly
+   make use of this by mechanism, by enabling it to validate whether they have
+   set their build flags properly at an early phase.
+
+-  ``PSA_CRYPTO``: Boolean option for enabling MbedTLS PSA crypto APIs support.
+   The platform will use PSA compliant Crypto APIs during authentication and
+   image measurement process by enabling this option. It uses APIs defined as
+   per the `PSA Crypto API specification`_. This feature is only supported if
+   using MbedTLS 3.x version. It is disabled (``0``) by default.
+
+-  ``TRANSFER_LIST``: Setting this to ``1`` enables support for Firmware
+   Handoff using Transfer List defined in `Firmware Handoff specification`_.
+   This defaults to ``0``. Current implementation follows the Firmware Handoff
+   specification v0.9.
+
+-  ``USE_DEBUGFS``: When set to 1 this option exposes a virtual filesystem
+   interface through BL31 as a SiP SMC function.
+   Default is disabled (0).
+
+Firmware update options
+~~~~~~~~~~~~~~~~~~~~~~~
+
+-  ``PSA_FWU_SUPPORT``: Enable the firmware update mechanism as per the
+   `PSA FW update specification`_. The default value is 0.
+   PSA firmware update implementation has few limitations, such as:
+
+   -  BL2 is not part of the protocol-updatable images. If BL2 needs to
+      be updated, then it should be done through another platform-defined
+      mechanism.
+
+   -  It assumes the platform's hardware supports CRC32 instructions.
+
+-  ``NR_OF_FW_BANKS``: Define the number of firmware banks. This flag is used
+   in defining the firmware update metadata structure. This flag is by default
+   set to '2'.
+
+-  ``NR_OF_IMAGES_IN_FW_BANK``: Define the number of firmware images in each
+   firmware bank. Each firmware bank must have the same number of images as per
+   the `PSA FW update specification`_.
+   This flag is used in defining the firmware update metadata structure. This
+   flag is by default set to '1'.
+
+--------------
+
+*Copyright (c) 2019-2023, Arm Limited. All rights reserved.*
+
+.. _DEN0115: https://developer.arm.com/docs/den0115/latest
+.. _PSA FW update specification: https://developer.arm.com/documentation/den0118/a/
+.. _PSA DRTM specification: https://developer.arm.com/documentation/den0113/a
+.. _GCC: https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html
+.. _Clang: https://clang.llvm.org/docs/DiagnosticsReference.html
+.. _Firmware Handoff specification: https://github.com/FirmwareHandoff/firmware_handoff/releases/tag/v0.9
+.. _PSA Crypto API specification: https://armmbed.github.io/mbed-crypto/html/
diff --git a/docs/getting_started/docs-build.rst b/docs/getting_started/docs-build.rst
new file mode 100644
index 0000000..50fff57
--- /dev/null
+++ b/docs/getting_started/docs-build.rst
@@ -0,0 +1,148 @@
+Building Documentation
+======================
+
+To create a rendered copy of this documentation locally you can use the
+`Sphinx`_ tool to build and package the plain-text documents into HTML-formatted
+pages.
+
+If you are building the documentation for the first time then you will need to
+check that you have the required software packages, as described in the
+*Prerequisites* section that follows.
+
+.. note::
+   An online copy of the documentation is available at
+   https://www.trustedfirmware.org/docs/tf-a, if you want to view a rendered
+   copy without doing a local build.
+
+Prerequisites
+-------------
+
+For building a local copy of the |TF-A| documentation you will need:
+
+- Python 3 (3.8 or later)
+- PlantUML (1.2017.15 or later)
+- `Poetry`_ (Python dependency manager)
+- Optionally, the `Dia`_ application can be installed if you need to edit
+  existing ``.dia`` diagram files, or create new ones.
+
+
+Below is an example set of instructions to get a working environment (tested on
+Ubuntu):
+
+.. code:: shell
+
+    sudo apt install python3 python3-pip plantuml [dia]
+    curl -sSL https://install.python-poetry.org | python3 -
+
+Building rendered documentation
+-------------------------------
+
+To install Python dependencies using Poetry:
+
+.. code:: shell
+
+    poetry install
+
+Poetry will create a new virtual environment and install all dependencies listed
+in ``pyproject.toml``. You can get information about this environment, such as
+its location and the Python version, with the command:
+
+.. code:: shell
+
+    poetry env info
+
+If you have already sourced a virtual environment, Poetry will respect this and
+install dependencies there.
+
+Once all dependencies are installed, the documentation can be compiled into
+HTML-formatted pages from the project root directory by running:
+
+.. code:: shell
+
+   poetry run make doc
+
+Output from the build process will be placed in: ``docs/build/html``.
+
+Other Output Formats
+~~~~~~~~~~~~~~~~~~~~
+
+We also support building documentation in other formats. From the ``docs``
+directory of the project, run the following command to see the supported
+formats.
+
+.. code:: shell
+
+   poetry run make -C docs help
+
+To build the documentation in PDF format, additionally ensure that the following
+packages are installed:
+
+- FreeSerif font
+- latexmk
+- librsvg2-bin
+- xelatex
+- xindy
+
+Below is an example set of instructions to install the required packages
+(tested on Ubuntu):
+
+.. code:: shell
+
+	sudo apt install fonts-freefont-otf latexmk librsvg2-bin texlive-xetex xindy
+
+Once all the dependencies are installed, run the command ``poetry run make -C
+docs latexpdf`` to build the documentation. Output from the build process
+(``trustedfirmware-a.pdf``) can be found in ``docs/build/latex``.
+
+Building rendered documentation from Poetry's virtual environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The command ``poetry run`` used in the steps above executes the input command
+from inside the project's virtual environment. The easiest way to activate this
+virtual environment is with the ``poetry shell`` command.
+
+Running ``poetry shell`` from the directory containing this project, activates
+the same virtual environment. This creates a sub-shell through which you can
+build the documentation directly with ``make``.
+
+.. code:: shell
+
+    poetry shell
+    make doc
+
+Type ``exit`` to deactivate the virtual environment and exit this new shell. For
+other use cases, please see the official `Poetry`_ documentation.
+
+Building rendered documentation from a container
+------------------------------------------------
+
+There may be cases where you can not either install or upgrade required
+dependencies to generate the documents, so in this case, one way to
+create the documentation is through a docker container. The first step is
+to check if `docker`_ is installed in your host, otherwise check main docker
+page for installation instructions. Once installed, run the following script
+from project root directory
+
+.. code:: shell
+
+   docker run --rm -v $PWD:/tf-a sphinxdoc/sphinx \
+        bash -c 'cd /tf-a &&
+            apt-get update && apt-get install -y curl plantuml &&
+            curl -sSL https://install.python-poetry.org | python3 - &&
+            ~/.local/bin/poetry install && ~/.local/bin/poetry run make doc'
+
+The above command fetches the ``sphinxdoc/sphinx`` container from `docker
+hub`_, launches the container, installs documentation requirements and finally
+creates the documentation. Once done, exit the container and output from the
+build process will be placed in: ``docs/build/html``.
+
+--------------
+
+*Copyright (c) 2019-2023, Arm Limited. All rights reserved.*
+
+.. _Sphinx: http://www.sphinx-doc.org/en/master/
+.. _Poetry: https://python-poetry.org/docs/
+.. _pip homepage: https://pip.pypa.io/en/stable/
+.. _Dia: https://wiki.gnome.org/Apps/Dia
+.. _docker: https://www.docker.com/
+.. _docker hub: https://hub.docker.com/repository/docker/sphinxdoc/sphinx
diff --git a/docs/getting_started/image-terminology.rst b/docs/getting_started/image-terminology.rst
new file mode 100644
index 0000000..66f47e8
--- /dev/null
+++ b/docs/getting_started/image-terminology.rst
@@ -0,0 +1,192 @@
+Image Terminology
+=================
+
+This page contains the current name, abbreviated name and purpose of the various
+images referred to in the Trusted Firmware project.
+
+Common Image Features
+---------------------
+
+- Some of the names and abbreviated names have changed to accommodate new
+  requirements. The changed names are as backward compatible as possible to
+  minimize confusion. Where applicable, the previous names are indicated. Some
+  code, documentation and build artefacts may still refer to the previous names;
+  these will inevitably take time to catch up.
+
+- The main name change is to prefix each image with the processor it corresponds
+  to (for example ``AP_``, ``SCP_``, ...). In situations where there is no
+  ambiguity (for example, within AP specific code/documentation), it is
+  permitted to omit the processor prefix (for example, just BL1 instead of
+  ``AP_BL1``).
+
+- Previously, the format for 3rd level images had 2 forms; ``BL3`` was either
+  suffixed with a dash ("-") followed by a number (for example, ``BL3-1``) or a
+  subscript number, depending on whether rich text formatting was available.
+  This was confusing and often the dash gets omitted in practice. Therefore the
+  new form is to just omit the dash and not use subscript formatting.
+
+- The names no longer contain dash ("-") characters at all. In some places (for
+  example, function names) it's not possible to use this character. All dashes
+  are either removed or replaced by underscores ("_").
+
+- The abbreviation BL stands for BootLoader. This is a historical anomaly.
+  Clearly, many of these images are not BootLoaders, they are simply firmware
+  images. However, the BL abbreviation is now widely used and is retained for
+  backwards compatibility.
+
+- The image names are not case sensitive. For example, ``bl1`` is
+  interchangeable with ``BL1``, although mixed case should be avoided.
+
+Trusted Firmware Images
+-----------------------
+
+Firmware Image Package: ``FIP``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is a packaging format used by TF-A to package firmware images in a single
+binary. The number and type of images that should be packed in a FIP is
+platform-specific and may include TF-A images and other firmware images
+required by the platform. For example, most platforms require a BL33 image
+which corresponds to the normal world bootloader (e.g. UEFI or U-Boot).
+
+AP Boot ROM: ``AP_BL1``
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Typically, this is the first code to execute on the AP and cannot be modified.
+Its primary purpose is to perform the minimum initialization necessary to load
+and authenticate an updateable AP firmware image into an executable RAM
+location, then hand-off control to that image.
+
+AP RAM Firmware: ``AP_BL2``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is the 2nd stage AP firmware. It is currently also known as the "Trusted
+Boot Firmware". Its primary purpose is to perform any additional initialization
+required to load and authenticate all 3rd level firmware images into their
+executable RAM locations, then hand-off control to the EL3 Runtime Firmware.
+
+EL3 Runtime Firmware: ``AP_BL31``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Also known as "SoC AP firmware" or "EL3 monitor firmware". Its primary purpose
+is to handle transitions between the normal and secure world.
+
+Secure-EL1 Payload (SP): ``AP_BL32``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Typically this is a TEE or Trusted OS, providing runtime secure services to the
+normal world. However, it may refer to a more abstract Secure-EL1 Payload (SP).
+Note that this abbreviation should only be used in systems where there is a
+single or primary image executing at Secure-EL1. In systems where there are
+potentially multiple SPs and there is no concept of a primary SP, this
+abbreviation should be avoided; use the recommended **Other AP 3rd level
+images** abbreviation instead.
+
+AP Normal World Firmware: ``AP_BL33``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For example, UEFI or uboot. Its primary purpose is to boot a normal world OS.
+
+Other AP 3rd level images: ``AP_BL3_XXX``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The abbreviated names of the existing 3rd level images imply a load/execution
+ordering (for example, ``AP_BL31 -> AP_BL32 -> AP_BL33``).  Some systems may
+have additional images and/or a different load/execution ordering. The
+abbreviated names of the existing images are retained for backward compatibility
+but new 3rd level images should be suffixed with an underscore followed by text
+identifier, not a number.
+
+In systems where 3rd level images are provided by different vendors, the
+abbreviated name should identify the vendor as well as the image
+function. For example, ``AP_BL3_ARM_RAS``.
+
+Realm Monitor Management Firmware: ``RMM``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is the Realm-EL2 firmware. It is required if
+:ref:`Realm Management Extension (RME)` feature is enabled. If a path to RMM
+image is not provided, TF-A builds Test Realm Payload (TRP) image by default
+and uses it as the RMM image.
+
+SCP Boot ROM: ``SCP_BL1`` (previously ``BL0``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Typically, this is the first code to execute on the SCP and cannot be modified.
+Its primary purpose is to perform the minimum initialization necessary to load
+and authenticate an updateable SCP firmware image into an executable RAM
+location, then hand-off control to that image. This may be performed in
+conjunction with other processor firmware (for example, ``AP_BL1`` and
+``AP_BL2``).
+
+This image was previously abbreviated as ``BL0`` but in some systems, the SCP
+may directly load/authenticate its own firmware. In these systems, it doesn't
+make sense to interleave the image terminology for AP and SCP; both AP and SCP
+Boot ROMs are ``BL1`` from their own point of view.
+
+SCP RAM Firmware: ``SCP_BL2`` (previously ``BL3-0``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is the 2nd stage SCP firmware. It is currently also known as the "SCP
+runtime firmware" but it could potentially be an intermediate firmware if the
+SCP needs to load/authenticate multiple 3rd level images in future.
+
+This image was previously abbreviated as BL3-0 but from the SCP's point of view,
+this has always been the 2nd stage firmware. The previous name is too
+AP-centric.
+
+Firmware Update (FWU) Images
+----------------------------
+
+The terminology for these images has not been widely adopted yet but they have
+to be considered in a production Trusted Board Boot solution.
+
+AP Firmware Update Boot ROM: ``AP_NS_BL1U``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Typically, this is the first normal world code to execute on the AP during a
+firmware update operation, and cannot be modified. Its primary purpose is to
+load subsequent firmware update images from an external interface and communicate
+with ``AP_BL1`` to authenticate those images.
+
+During firmware update, there are (potentially) multiple transitions between the
+secure and normal world. The "level" of the BL image is relative to the world
+it's in so it makes sense to encode "NS" in the normal world images. The absence
+of "NS" implies a secure world image.
+
+AP Firmware Update Config: ``AP_BL2U``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This image does the minimum necessary AP secure world configuration required to
+complete the firmware update operation. It is potentially a subset of ``AP_BL2``
+functionality.
+
+SCP Firmware Update Config: ``SCP_BL2U`` (previously ``BL2-U0``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This image does the minimum necessary SCP secure world configuration required to
+complete the firmware update operation. It is potentially a subset of
+``SCP_BL2`` functionality.
+
+AP Firmware Updater: ``AP_NS_BL2U`` (previously ``BL3-U``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is the 2nd stage AP normal world firmware updater. Its primary purpose is
+to load a new set of firmware images from an external interface and write them
+into non-volatile storage.
+
+Other Processor Firmware Images
+-------------------------------
+
+Some systems may have additional processors to the AP and SCP. For example, a
+Management Control Processor (MCP). Images for these processors should follow
+the same terminology, with the processor abbreviation prefix, followed by
+underscore and the level of the firmware image.
+
+For example,
+
+MCP Boot ROM: ``MCP_BL1``
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+MCP RAM Firmware: ``MCP_BL2``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst
new file mode 100644
index 0000000..8180a3f
--- /dev/null
+++ b/docs/getting_started/index.rst
@@ -0,0 +1,20 @@
+Getting Started
+===============
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents
+
+   prerequisites
+   docs-build
+   initial-build
+   tools-build
+   build-options
+   build-internals
+   image-terminology
+   psci-lib-integration-guide
+   rt-svc-writers-guide
+
+--------------
+
+*Copyright (c) 2019-2023, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/initial-build.rst b/docs/getting_started/initial-build.rst
new file mode 100644
index 0000000..4f41be4
--- /dev/null
+++ b/docs/getting_started/initial-build.rst
@@ -0,0 +1,118 @@
+Performing an Initial Build
+===========================
+
+-  Before building TF-A, the environment variable ``CROSS_COMPILE`` must point
+   to your cross compiler.
+
+   For AArch64:
+
+   .. code:: shell
+
+       export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf-
+
+   For AArch32:
+
+   .. code:: shell
+
+       export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-none-eabi-
+
+   It is possible to build TF-A using Clang or Arm Compiler 6. To do so
+   ``CC`` needs to point to the clang or armclang binary, which will
+   also select the clang or armclang assembler. Arm Compiler 6 will be selected
+   when the base name of the path assigned to ``CC`` matches the string
+   'armclang'. GNU binutils are required since the TF-A build system doesn't
+   currently support Arm Scatter files. Meaning the GNU linker is used by
+   default for Arm Compiler 6. Because of this dependency, ``CROSS_COMPILE``
+   should be set as described above.
+
+   For AArch64 using Arm Compiler 6:
+
+   .. code:: shell
+
+       export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf-
+       make CC=<path-to-armclang>/bin/armclang PLAT=<platform> all
+
+   On the other hand, Clang uses LLVM linker (LLD) and other LLVM binutils by
+   default instead of GNU utilities (LLVM linker (LLD) 14.0.0 is known to
+   work with TF-A). ``CROSS_COMPILE`` need not be set for Clang. Please note,
+   that the default linker may be manually overridden using the ``LD`` variable.
+
+   Clang will be selected when the base name of the path assigned to ``CC``
+   contains the string 'clang'. This is to allow both clang and clang-X.Y
+   to work.
+
+   For AArch64 using clang:
+
+   .. code:: shell
+
+       make CC=<path-to-clang>/bin/clang PLAT=<platform> all
+
+-  Change to the root directory of the TF-A source tree and build.
+
+   For AArch64:
+
+   .. code:: shell
+
+       make PLAT=<platform> all
+
+   For AArch32:
+
+   .. code:: shell
+
+       make PLAT=<platform> ARCH=aarch32 AARCH32_SP=sp_min all
+
+   Notes:
+
+   -  If ``PLAT`` is not specified, ``fvp`` is assumed by default. See the
+      :ref:`Build Options` document for more information on available build
+      options.
+
+   -  (AArch32 only) Currently only ``PLAT=fvp`` is supported.
+
+   -  (AArch32 only) ``AARCH32_SP`` is the AArch32 EL3 Runtime Software and it
+      corresponds to the BL32 image. A minimal ``AARCH32_SP``, sp_min, is
+      provided by TF-A to demonstrate how PSCI Library can be integrated with
+      an AArch32 EL3 Runtime Software. Some AArch32 EL3 Runtime Software may
+      include other runtime services, for example Trusted OS services. A guide
+      to integrate PSCI library with AArch32 EL3 Runtime Software can be found
+      at :ref:`PSCI Library Integration guide for Armv8-A AArch32 systems`.
+
+   -  (AArch64 only) The TSP (Test Secure Payload), corresponding to the BL32
+      image, is not compiled in by default. Refer to the
+      :ref:`Test Secure Payload (TSP) and Dispatcher (TSPD)` document for
+      details on building the TSP.
+
+   -  By default this produces a release version of the build. To produce a
+      debug version instead, refer to the "Debugging options" section below.
+
+   -  The build process creates products in a ``build`` directory tree, building
+      the objects and binaries for each boot loader stage in separate
+      sub-directories. The following boot loader binary files are created
+      from the corresponding ELF files:
+
+      -  ``build/<platform>/<build-type>/bl1.bin``
+      -  ``build/<platform>/<build-type>/bl2.bin``
+      -  ``build/<platform>/<build-type>/bl31.bin`` (AArch64 only)
+      -  ``build/<platform>/<build-type>/bl32.bin`` (mandatory for AArch32)
+
+      where ``<platform>`` is the name of the chosen platform and ``<build-type>``
+      is either ``debug`` or ``release``. The actual number of images might differ
+      depending on the platform.
+
+-  Build products for a specific build variant can be removed using:
+
+   .. code:: shell
+
+       make DEBUG=<D> PLAT=<platform> clean
+
+   ... where ``<D>`` is ``0`` or ``1``, as specified when building.
+
+   The build tree can be removed completely using:
+
+   .. code:: shell
+
+       make realclean
+
+--------------
+
+*Copyright (c) 2020-2022, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/prerequisites.rst b/docs/getting_started/prerequisites.rst
new file mode 100644
index 0000000..573abdf
--- /dev/null
+++ b/docs/getting_started/prerequisites.rst
@@ -0,0 +1,194 @@
+Prerequisites
+=============
+
+This document describes the software requirements for building |TF-A| for
+AArch32 and AArch64 target platforms.
+
+It may possible to build |TF-A| with combinations of software packages that are
+different from those listed below, however only the software described in this
+document can be officially supported.
+
+Build Host
+----------
+
+|TF-A| can be built using either a Linux or a Windows machine as the build host.
+
+A relatively recent Linux distribution is recommended for building |TF-A|. We
+have performed tests using Ubuntu 22.04 LTS (64-bit) but other distributions
+should also work fine as a base, provided that the necessary tools and libraries
+can be installed.
+
+.. _prerequisites_toolchain:
+
+Toolchain
+---------
+
+|TF-A| can be built with any of the following *cross-compiler* toolchains that
+target the Armv7-A or Armv8-A architectures:
+
+- TF-A has been tested with version 12.3.Rel1 (gcc 12.3) from the `Arm Developer website`_
+
+   You will need the targets ``arm-none-eabi`` and ``aarch64-none-elf`` for
+   AArch32 and AArch64 builds respectively.
+
+- Clang == 14.0.0
+- Arm Compiler == 6.18
+
+In addition, a native compiler is required to build the supporting tools.
+
+.. note::
+   Versions greater than the ones specified are likely but not guaranteed to
+   work. This is predominantly because TF-A carries its own copy of compiler-rt,
+   which may be older than the version expected by the compiler. Fixes and bug
+   reports are always welcome.
+
+.. note::
+   The software has also been built on Windows 7 Enterprise SP1, using CMD.EXE,
+   Cygwin, and Msys (MinGW) shells, using version 5.3.1 of the GNU toolchain.
+
+.. note::
+   For instructions on how to select the cross compiler refer to
+   :ref:`Performing an Initial Build`.
+
+.. _prerequisites_software_and_libraries:
+
+Software and Libraries
+----------------------
+
+The following tools are required to obtain and build |TF-A|:
+
+- An appropriate toolchain (see :ref:`prerequisites_toolchain`)
+- GNU Make
+- Git
+
+The following libraries must be available to build one or more components or
+supporting tools:
+
+- OpenSSL >= 1.1.1 (v3.0.0 to v3.0.6 highly discouraged due to security issues)
+
+   Required to build the cert_create, encrypt_fw, and fiptool tools.
+
+   .. note::
+
+    If using OpenSSL 3, older Linux versions may require it to be built from
+    source code, as it may not be available in the default package repositories.
+    Please refer to the OpenSSL project documentation for more information.
+
+The following libraries are required for Trusted Board Boot and Measured Boot
+support:
+
+- mbed TLS == 3.4.1 (tag: ``mbedtls-3.4.1``)
+
+These tools are optional:
+
+- Device Tree Compiler (DTC) >= 1.4.7
+
+   Needed if you want to rebuild the provided Flattened Device Tree (FDT)
+   source files (``.dts`` files). DTC is available for Linux through the package
+   repositories of most distributions.
+
+- Arm `Development Studio (Arm-DS)`_
+
+   The standard software package used for debugging software on Arm development
+   platforms and |FVP| models.
+
+- Node.js >= 16
+
+   Highly recommended, and necessary in order to install and use the packaged
+   Git hooks and helper tools. Without these tools you will need to rely on the
+   CI for feedback on commit message conformance.
+
+- Poetry >= 1.3.2
+
+   Required for managing Python dependencies, this will allow you to reliably
+   reproduce a Python environment to build documentation and run analysis tools.
+   Most importantly, it ensures your system environment will not be affected by
+   dependencies in the Python scripts.
+
+Package Installation (Linux)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you are using the recommended Ubuntu distribution then you can install the
+required packages with the following command:
+
+.. code:: shell
+
+    sudo apt install build-essential git
+
+The optional packages can be installed using:
+
+.. code:: shell
+
+    sudo apt install device-tree-compiler
+
+Additionally, to install a version of Node.js compatible with TF-A's repository
+scripts, you can use the `Node Version Manager`_. To install both NVM and an
+appropriate version of Node.js, run the following **from the root directory of
+the repository**:
+
+.. code:: shell
+
+    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
+    exec "$SHELL" -ic "nvm install; exec $SHELL"
+
+.. _Node Version Manager: https://github.com/nvm-sh/nvm#install--update-script
+
+Supporting Files
+----------------
+
+TF-A has been tested with pre-built binaries and file systems from `Linaro
+Release 20.01`_. Alternatively, you can build the binaries from source using
+instructions in :ref:`Performing an Initial Build`.
+
+.. _prerequisites_get_source:
+
+Getting the TF-A Source
+-----------------------
+
+Source code for |TF-A| is maintained in a Git repository hosted on
+TrustedFirmware.org. To clone this repository from the server, run the following
+in your shell:
+
+.. code:: shell
+
+    git clone "https://review.trustedfirmware.org/TF-A/trusted-firmware-a"
+
+Additional Steps for Contributors
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you are planning on contributing back to TF-A, there are some things you'll
+want to know.
+
+TF-A is hosted by a `Gerrit Code Review`_ server. Gerrit requires that all
+commits include a ``Change-Id`` footer, and this footer is typically
+automatically generated by a Git hook installed by you, the developer.
+
+If you have Node.js installed already, you can automatically install this hook,
+along with any additional hooks and Javascript-based tooling that we use, by
+running from within your newly-cloned repository:
+
+.. code:: shell
+
+    npm install --no-save
+
+If you have opted **not** to install Node.js, you can install the Gerrit hook
+manually by running:
+
+.. code:: shell
+
+    curl -Lo $(git rev-parse --git-dir)/hooks/commit-msg https://review.trustedfirmware.org/tools/hooks/commit-msg
+    chmod +x $(git rev-parse --git-dir)/hooks/commit-msg
+
+You can read more about Git hooks in the *githooks* page of the Git
+documentation, available `here <https://git-scm.com/docs/githooks>`_.
+
+--------------
+
+*Copyright (c) 2021-2023, Arm Limited. All rights reserved.*
+
+.. _Arm Developer website: https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/downloads
+.. _Gerrit Code Review: https://www.gerritcodereview.com/
+.. _Linaro Release Notes: https://community.arm.com/dev-platforms/w/docs/226/old-release-notes
+.. _Linaro instructions: https://community.arm.com/dev-platforms/w/docs/304/arm-reference-platforms-deliverables
+.. _Development Studio (Arm-DS): https://developer.arm.com/Tools%20and%20Software/Arm%20Development%20Studio
+.. _Linaro Release 20.01: http://releases.linaro.org/members/arm/platforms/20.01
diff --git a/docs/getting_started/psci-lib-integration-guide.rst b/docs/getting_started/psci-lib-integration-guide.rst
new file mode 100644
index 0000000..7e4b0db
--- /dev/null
+++ b/docs/getting_started/psci-lib-integration-guide.rst
@@ -0,0 +1,534 @@
+PSCI Library Integration guide for Armv8-A AArch32 systems
+==========================================================
+
+This document describes the PSCI library interface with a focus on how to
+integrate with a suitable Trusted OS for an Armv8-A AArch32 system. The PSCI
+Library implements the PSCI Standard as described in `PSCI`_ and is meant
+to be integrated with EL3 Runtime Software which invokes the PSCI Library
+interface appropriately. **EL3 Runtime Software** refers to software executing
+at the highest secure privileged mode, which is EL3 in AArch64 or Secure SVC/
+Monitor mode in AArch32, and provides runtime services to the non-secure world.
+The runtime service request is made via SMC (Secure Monitor Call) and the call
+must adhere to `SMCCC`_. In AArch32, EL3 Runtime Software may additionally
+include Trusted OS functionality. A minimal AArch32 Secure Payload, SP-MIN, is
+provided in Trusted Firmware-A (TF-A) to illustrate the usage and integration
+of the PSCI library. The description of PSCI library interface and its
+integration with EL3 Runtime Software in this document is targeted towards
+AArch32 systems.
+
+Generic call sequence for PSCI Library interface (AArch32)
+----------------------------------------------------------
+
+The generic call sequence of PSCI Library interfaces (see
+`PSCI Library Interface`_) during cold boot in AArch32
+system is described below:
+
+#. After cold reset, the EL3 Runtime Software performs its cold boot
+   initialization including the PSCI library pre-requisites mentioned in
+   `PSCI Library Interface`_, and also the necessary platform
+   setup.
+
+#. Call ``psci_setup()`` in Monitor mode.
+
+#. Optionally call ``psci_register_spd_pm_hook()`` to register callbacks to
+   do bookkeeping for the EL3 Runtime Software during power management.
+
+#. Call ``psci_prepare_next_non_secure_ctx()`` to initialize the non-secure CPU
+   context.
+
+#. Get the non-secure ``cpu_context_t`` for the current CPU by calling
+   ``cm_get_context()`` , then programming the registers in the non-secure
+   context and exiting to non-secure world. If the EL3 Runtime Software needs
+   additional configuration to be set for non-secure context, like routing
+   FIQs to the secure world, the values of the registers can be modified prior
+   to programming. See `PSCI CPU context management`_ for more
+   details on CPU context management.
+
+The generic call sequence of PSCI library interfaces during warm boot in
+AArch32 systems is described below:
+
+#. After warm reset, the EL3 Runtime Software performs the necessary warm
+   boot initialization including the PSCI library pre-requisites mentioned in
+   `PSCI Library Interface`_ (Note that the Data cache
+   **must not** be enabled).
+
+#. Call ``psci_warmboot_entrypoint()`` in Monitor mode. This interface
+   initializes/restores the non-secure CPU context as well.
+
+#. Do step 5 of the cold boot call sequence described above.
+
+The generic call sequence of PSCI library interfaces on receipt of a PSCI SMC
+on an AArch32 system is described below:
+
+#. On receipt of an SMC, save the register context as per `SMCCC`_.
+
+#. If the SMC function identifier corresponds to a SMC32 PSCI API, construct
+   the appropriate arguments and call the ``psci_smc_handler()`` interface.
+   The invocation may or may not return back to the caller depending on
+   whether the PSCI API resulted in power down of the CPU.
+
+#. If ``psci_smc_handler()`` returns, populate the return value in R0 (AArch32)/
+   X0 (AArch64) and restore other registers as per `SMCCC`_.
+
+PSCI CPU context management
+---------------------------
+
+PSCI library is in charge of initializing/restoring the non-secure CPU system
+registers according to `PSCI`_ during cold/warm boot.
+This is referred to as ``PSCI CPU Context Management``. Registers that need to
+be preserved across CPU power down/power up cycles are maintained in
+``cpu_context_t`` data structure. The initialization of other non-secure CPU
+system registers which do not require coordination with the EL3 Runtime
+Software is done directly by the PSCI library (see ``cm_prepare_el3_exit()``).
+
+The EL3 Runtime Software is responsible for managing register context
+during switch between Normal and Secure worlds. The register context to be
+saved and restored depends on the mechanism used to trigger the world switch.
+For example, if the world switch was triggered by an SMC call, then the
+registers need to be saved and restored according to `SMCCC`_. In AArch64,
+due to the tight integration with BL31, both BL31 and PSCI library
+use the same ``cpu_context_t`` data structure for PSCI CPU context management
+and register context management during world switch. This cannot be assumed
+for AArch32 EL3 Runtime Software since most AArch32 Trusted OSes already implement
+a mechanism for register context management during world switch. Hence, when
+the PSCI library is integrated with a AArch32 EL3 Runtime Software, the
+``cpu_context_t`` is stripped down for just PSCI CPU context management.
+
+During cold/warm boot, after invoking appropriate PSCI library interfaces, it
+is expected that the EL3 Runtime Software will query the ``cpu_context_t`` and
+write appropriate values to the corresponding system registers. This mechanism
+resolves 2 additional problems for AArch32 EL3 Runtime Software:
+
+#. Values for certain system registers like SCR and SCTLR cannot be
+   unilaterally determined by PSCI library and need inputs from the EL3
+   Runtime Software. Using ``cpu_context_t`` as an intermediary data store
+   allows EL3 Runtime Software to modify the register values appropriately
+   before programming them.
+
+#. The PSCI library provides appropriate LR and SPSR values (entrypoint
+   information) for exit into non-secure world. Using ``cpu_context_t`` as an
+   intermediary data store allows the EL3 Runtime Software to store these
+   values safely until it is ready for exit to non-secure world.
+
+Currently the ``cpu_context_t`` data structure for AArch32 stores the following
+registers: R0 - R3, LR (R14), SCR, SPSR, SCTLR.
+
+The EL3 Runtime Software must implement accessors to get/set pointers
+to CPU context ``cpu_context_t`` data and these are described in
+`CPU Context management API`_.
+
+PSCI Library Interface
+----------------------
+
+The PSCI library implements the `PSCI`_. The interfaces to this library are
+declared in ``psci_lib.h`` and are as listed below:
+
+.. code:: c
+
+        u_register_t psci_smc_handler(uint32_t smc_fid, u_register_t x1,
+                                      u_register_t x2, u_register_t x3,
+                                      u_register_t x4, void *cookie,
+                                      void *handle, u_register_t flags);
+        int psci_setup(const psci_lib_args_t *lib_args);
+        void psci_warmboot_entrypoint(void);
+        void psci_register_spd_pm_hook(const spd_pm_ops_t *pm);
+        void psci_prepare_next_non_secure_ctx(entry_point_info_t *next_image_info);
+
+The CPU context data 'cpu_context_t' is programmed to the registers differently
+when PSCI is integrated with an AArch32 EL3 Runtime Software compared to
+when the PSCI is integrated with an AArch64 EL3 Runtime Software (BL31). For
+example, in the case of AArch64, there is no need to retrieve ``cpu_context_t``
+data and program the registers as it will done implicitly as part of
+``el3_exit``. The description below of the PSCI interfaces is targeted at
+integration with an AArch32 EL3 Runtime Software.
+
+The PSCI library is responsible for initializing/restoring the non-secure world
+to an appropriate state after boot and may choose to directly program the
+non-secure system registers. The PSCI generic code takes care not to directly
+modify any of the system registers affecting the secure world and instead
+returns the values to be programmed to these registers via ``cpu_context_t``.
+The EL3 Runtime Software is responsible for programming those registers and
+can use the proposed values provided in the ``cpu_context_t``, modifying the
+values if required.
+
+PSCI library needs the flexibility to access both secure and non-secure
+copies of banked registers. Hence it needs to be invoked in Monitor mode
+for AArch32 and in EL3 for AArch64. The NS bit in SCR (in AArch32) or SCR_EL3
+(in AArch64) must be set to 0. Additional requirements for the PSCI library
+interfaces are:
+
+-  Instruction cache must be enabled
+-  Both IRQ and FIQ must be masked for the current CPU
+-  The page tables must be setup and the MMU enabled
+-  The C runtime environment must be setup and stack initialized
+-  The Data cache must be enabled prior to invoking any of the PSCI library
+   interfaces except for ``psci_warmboot_entrypoint()``. For
+   ``psci_warmboot_entrypoint()``, if the build option ``HW_ASSISTED_COHERENCY``
+   is enabled however, data caches are expected to be enabled.
+
+Further requirements for each interface can be found in the interface
+description.
+
+Interface : psci_setup()
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    Argument : const psci_lib_args_t *lib_args
+    Return   : void
+
+This function is to be called by the primary CPU during cold boot before
+any other interface to the PSCI library. It takes ``lib_args``, a const pointer
+to ``psci_lib_args_t``, as the argument. The ``psci_lib_args_t`` is a versioned
+structure and is declared in ``psci_lib.h`` header as follows:
+
+.. code:: c
+
+        typedef struct psci_lib_args {
+            /* The version information of PSCI Library Interface */
+            param_header_t        h;
+            /* The warm boot entrypoint function */
+            mailbox_entrypoint_t  mailbox_ep;
+        } psci_lib_args_t;
+
+The first field ``h``, of ``param_header_t`` type, provides the version
+information. The second field ``mailbox_ep`` is the warm boot entrypoint address
+and is used to configure the platform mailbox. Helper macros are provided in
+``psci_lib.h`` to construct the ``lib_args`` argument statically or during
+runtime. Prior to calling the ``psci_setup()`` interface, the platform setup for
+cold boot must have completed. Major actions performed by this interface are:
+
+-  Initializes architecture.
+-  Initializes PSCI power domain and state coordination data structures.
+-  Calls ``plat_setup_psci_ops()`` with warm boot entrypoint ``mailbox_ep`` as
+   argument.
+-  Calls ``cm_set_context_by_index()`` (see
+   `CPU Context management API`_) for all the CPUs in the
+   platform
+
+Interface : psci_prepare_next_non_secure_ctx()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    Argument : entry_point_info_t *next_image_info
+    Return   : void
+
+After ``psci_setup()`` and prior to exit to the non-secure world, this function
+must be called by the EL3 Runtime Software to initialize the non-secure world
+context. The non-secure world entrypoint information ``next_image_info`` (first
+argument) will be used to determine the non-secure context. After this function
+returns, the EL3 Runtime Software must retrieve the ``cpu_context_t`` (using
+cm_get_context()) for the current CPU and program the registers prior to exit
+to the non-secure world.
+
+Interface : psci_register_spd_pm_hook()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    Argument : const spd_pm_ops_t *
+    Return   : void
+
+As explained in `Secure payload power management callback`_,
+the EL3 Runtime Software may want to perform some bookkeeping during power
+management operations. This function is used to register the ``spd_pm_ops_t``
+(first argument) callbacks with the PSCI library which will be called
+appropriately during power management. Calling this function is optional and
+need to be called by the primary CPU during the cold boot sequence after
+``psci_setup()`` has completed.
+
+Interface : psci_smc_handler()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    Argument : uint32_t smc_fid, u_register_t x1,
+               u_register_t x2, u_register_t x3,
+               u_register_t x4, void *cookie,
+               void *handle, u_register_t flags
+    Return   : u_register_t
+
+This function is the top level handler for SMCs which fall within the
+PSCI service range specified in `SMCCC`_. The function ID ``smc_fid`` (first
+argument) determines the PSCI API to be called. The ``x1`` to ``x4`` (2nd to 5th
+arguments), are the values of the registers r1 - r4 (in AArch32) or x1 - x4
+(in AArch64) when the SMC is received. These are the arguments to PSCI API as
+described in `PSCI`_. The 'flags' (8th argument) is a bit field parameter
+and is detailed in 'smccc.h' header. It includes whether the call is from the
+secure or non-secure world. The ``cookie`` (6th argument) and the ``handle``
+(7th argument) are not used and are reserved for future use.
+
+The return value from this interface is the return value from the underlying
+PSCI API corresponding to ``smc_fid``. This function may not return back to the
+caller if PSCI API causes power down of the CPU. In this case, when the CPU
+wakes up, it will start execution from the warm reset address.
+
+Interface : psci_warmboot_entrypoint()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    Argument : void
+    Return   : void
+
+This function performs the warm boot initialization/restoration as mandated by
+`PSCI`_. For AArch32, on wakeup from power down the CPU resets to secure SVC
+mode and the EL3 Runtime Software must perform the prerequisite initializations
+mentioned at top of this section. This function must be called with Data cache
+disabled (unless build option ``HW_ASSISTED_COHERENCY`` is enabled) but with MMU
+initialized and enabled. The major actions performed by this function are:
+
+-  Invalidates the stack and enables the data cache.
+-  Initializes architecture and PSCI state coordination.
+-  Restores/Initializes the peripheral drivers to the required state via
+   appropriate ``plat_psci_ops_t`` hooks
+-  Restores the EL3 Runtime Software context via appropriate ``spd_pm_ops_t``
+   callbacks.
+-  Restores/Initializes the non-secure context and populates the
+   ``cpu_context_t`` for the current CPU.
+
+Upon the return of this function, the EL3 Runtime Software must retrieve the
+non-secure ``cpu_context_t`` using ``cm_get_context()`` and program the registers
+prior to exit to the non-secure world.
+
+EL3 Runtime Software dependencies
+---------------------------------
+
+The PSCI Library includes supporting frameworks like context management,
+cpu operations (cpu_ops) and per-cpu data framework. Other helper library
+functions like bakery locks and spin locks are also included in the library.
+The dependencies which must be fulfilled by the EL3 Runtime Software
+for integration with PSCI library are described below.
+
+General dependencies
+~~~~~~~~~~~~~~~~~~~~
+
+The PSCI library being a Multiprocessor (MP) implementation, EL3 Runtime
+Software must provide an SMC handling framework capable of MP adhering to
+`SMCCC`_ specification.
+
+The EL3 Runtime Software must also export cache maintenance primitives
+and some helper utilities for assert, print and memory operations as listed
+below. The TF-A source tree provides implementations for all
+these functions but the EL3 Runtime Software may use its own implementation.
+
+**Functions : assert(), memcpy(), memset(), printf()**
+
+These must be implemented as described in ISO C Standard.
+
+**Function : flush_dcache_range()**
+
+::
+
+    Argument : uintptr_t addr, size_t size
+    Return   : void
+
+This function cleans and invalidates (flushes) the data cache for memory
+at address ``addr`` (first argument) address and of size ``size`` (second argument).
+
+**Function : inv_dcache_range()**
+
+::
+
+    Argument : uintptr_t addr, size_t size
+    Return   : void
+
+This function invalidates (flushes) the data cache for memory at address
+``addr`` (first argument) address and of size ``size`` (second argument).
+
+CPU Context management API
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The CPU context management data memory is statically allocated by PSCI library
+in BSS section. The PSCI library requires the EL3 Runtime Software to implement
+APIs to store and retrieve pointers to this CPU context data. SP-MIN
+demonstrates how these APIs can be implemented but the EL3 Runtime Software can
+choose a more optimal implementation (like dedicating the secure TPIDRPRW
+system register (in AArch32) for storing these pointers).
+
+**Function : cm_set_context_by_index()**
+
+::
+
+    Argument : unsigned int cpu_idx, void *context, unsigned int security_state
+    Return   : void
+
+This function is called during cold boot when the ``psci_setup()`` PSCI library
+interface is called.
+
+This function must store the pointer to the CPU context data, ``context`` (2nd
+argument), for the specified ``security_state`` (3rd argument) and CPU identified
+by ``cpu_idx`` (first argument). The ``security_state`` will always be non-secure
+when called by PSCI library and this argument is retained for compatibility
+with BL31. The ``cpu_idx`` will correspond to the index returned by the
+``plat_core_pos_by_mpidr()`` for ``mpidr`` of the CPU.
+
+The actual method of storing the ``context`` pointers is implementation specific.
+For example, SP-MIN stores the pointers in the array ``sp_min_cpu_ctx_ptr``
+declared in ``sp_min_main.c``.
+
+**Function : cm_get_context()**
+
+::
+
+    Argument : uint32_t security_state
+    Return   : void *
+
+This function must return the pointer to the ``cpu_context_t`` structure for
+the specified ``security_state`` (first argument) for the current CPU. The caller
+must ensure that ``cm_set_context_by_index`` is called first and the appropriate
+context pointers are stored prior to invoking this API. The ``security_state``
+will always be non-secure when called by PSCI library and this argument
+is retained for compatibility with BL31.
+
+**Function : cm_get_context_by_index()**
+
+::
+
+    Argument : unsigned int cpu_idx, unsigned int security_state
+    Return   : void *
+
+This function must return the pointer to the ``cpu_context_t`` structure for
+the specified ``security_state`` (second argument) for the CPU identified by
+``cpu_idx`` (first argument). The caller must ensure that
+``cm_set_context_by_index`` is called first and the appropriate context
+pointers are stored prior to invoking this API. The ``security_state`` will
+always be non-secure when called by PSCI library and this argument is
+retained for compatibility with BL31. The ``cpu_idx`` will correspond to the
+index returned by the ``plat_core_pos_by_mpidr()`` for ``mpidr`` of the CPU.
+
+Platform API
+~~~~~~~~~~~~
+
+The platform layer abstracts the platform-specific details from the generic
+PSCI library. The following platform APIs/macros must be defined by the EL3
+Runtime Software for integration with the PSCI library.
+
+The mandatory platform APIs are:
+
+-  plat_my_core_pos
+-  plat_core_pos_by_mpidr
+-  plat_get_syscnt_freq2
+-  plat_get_power_domain_tree_desc
+-  plat_setup_psci_ops
+-  plat_reset_handler
+-  plat_panic_handler
+-  plat_get_my_stack
+
+The mandatory platform macros are:
+
+-  PLATFORM_CORE_COUNT
+-  PLAT_MAX_PWR_LVL
+-  PLAT_NUM_PWR_DOMAINS
+-  CACHE_WRITEBACK_GRANULE
+-  PLAT_MAX_OFF_STATE
+-  PLAT_MAX_RET_STATE
+-  PLAT_MAX_PWR_LVL_STATES (optional)
+-  PLAT_PCPU_DATA_SIZE (optional)
+
+The details of these APIs/macros can be found in the :ref:`Porting Guide`.
+
+All platform specific operations for power management are done via
+``plat_psci_ops_t`` callbacks registered by the platform when
+``plat_setup_psci_ops()`` API is called. The description of each of
+the callbacks in ``plat_psci_ops_t`` can be found in PSCI section of the
+:ref:`Porting Guide`. If any these callbacks are not registered, then the
+PSCI API associated with that callback will not be supported by PSCI
+library.
+
+Secure payload power management callback
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+During PSCI power management operations, the EL3 Runtime Software may
+need to perform some bookkeeping, and PSCI library provides
+``spd_pm_ops_t`` callbacks for this purpose. These hooks must be
+populated and registered by using ``psci_register_spd_pm_hook()`` PSCI
+library interface.
+
+Typical bookkeeping during PSCI power management calls include save/restore
+of the EL3 Runtime Software context. Also if the EL3 Runtime Software makes
+use of secure interrupts, then these interrupts must also be managed
+appropriately during CPU power down/power up. Any secure interrupt targeted
+to the current CPU must be disabled or re-targeted to other running CPU prior
+to power down of the current CPU. During power up, these interrupt can be
+enabled/re-targeted back to the current CPU.
+
+.. code:: c
+
+        typedef struct spd_pm_ops {
+                void (*svc_on)(u_register_t target_cpu);
+                int32_t (*svc_off)(u_register_t __unused);
+                void (*svc_suspend)(u_register_t max_off_pwrlvl);
+                void (*svc_on_finish)(u_register_t __unused);
+                void (*svc_suspend_finish)(u_register_t max_off_pwrlvl);
+                int32_t (*svc_migrate)(u_register_t from_cpu, u_register_t to_cpu);
+                int32_t (*svc_migrate_info)(u_register_t *resident_cpu);
+                void (*svc_system_off)(void);
+                void (*svc_system_reset)(void);
+        } spd_pm_ops_t;
+
+A brief description of each callback is given below:
+
+-  svc_on, svc_off, svc_on_finish
+
+   The ``svc_on``, ``svc_off`` callbacks are called during PSCI_CPU_ON,
+   PSCI_CPU_OFF APIs respectively. The ``svc_on_finish`` is called when the
+   target CPU of PSCI_CPU_ON API powers up and executes the
+   ``psci_warmboot_entrypoint()`` PSCI library interface.
+
+-  svc_suspend, svc_suspend_finish
+
+   The ``svc_suspend`` callback is called during power down bu either
+   PSCI_SUSPEND or PSCI_SYSTEM_SUSPEND APIs. The ``svc_suspend_finish`` is
+   called when the CPU wakes up from suspend and executes the
+   ``psci_warmboot_entrypoint()`` PSCI library interface. The ``max_off_pwrlvl``
+   (first parameter) denotes the highest power domain level being powered down
+   to or woken up from suspend.
+
+-  svc_system_off, svc_system_reset
+
+   These callbacks are called during PSCI_SYSTEM_OFF and PSCI_SYSTEM_RESET
+   PSCI APIs respectively.
+
+-  svc_migrate_info
+
+   This callback is called in response to PSCI_MIGRATE_INFO_TYPE or
+   PSCI_MIGRATE_INFO_UP_CPU APIs. The return value of this callback must
+   correspond to the return value of PSCI_MIGRATE_INFO_TYPE API as described
+   in `PSCI`_. If the secure payload is a Uniprocessor (UP)
+   implementation, then it must update the mpidr of the CPU it is resident in
+   via ``resident_cpu`` (first argument). The updates to ``resident_cpu`` is
+   ignored if the secure payload is a multiprocessor (MP) implementation.
+
+-  svc_migrate
+
+   This callback is only relevant if the secure payload in EL3 Runtime
+   Software is a Uniprocessor (UP) implementation and supports migration from
+   the current CPU ``from_cpu`` (first argument) to another CPU ``to_cpu``
+   (second argument). This callback is called in response to PSCI_MIGRATE
+   API. This callback is never called if the secure payload is a
+   Multiprocessor (MP) implementation.
+
+CPU operations
+~~~~~~~~~~~~~~
+
+The CPU operations (cpu_ops) framework implement power down sequence specific
+to the CPU and the details of which can be found at
+:ref:`firmware_design_cpu_ops_fwk`. The TF-A tree implements the ``cpu_ops``
+for various supported CPUs and the EL3 Runtime Software needs to include the
+required ``cpu_ops`` in its build. The start and end of the ``cpu_ops``
+descriptors must be exported by the EL3 Runtime Software via the
+``__CPU_OPS_START__`` and ``__CPU_OPS_END__`` linker symbols.
+
+The ``cpu_ops`` descriptors also include reset sequences and may include errata
+workarounds for the CPU. The EL3 Runtime Software can choose to call this
+during cold/warm reset if it does not implement its own reset sequence/errata
+workarounds.
+
+--------------
+
+*Copyright (c) 2016-2023, Arm Limited and Contributors. All rights reserved.*
+
+.. _PSCI: https://developer.arm.com/documentation/den0022/latest/
+.. _SMCCC: https://developer.arm.com/docs/den0028/latest
diff --git a/docs/getting_started/rt-svc-writers-guide.rst b/docs/getting_started/rt-svc-writers-guide.rst
new file mode 100644
index 0000000..fe64558
--- /dev/null
+++ b/docs/getting_started/rt-svc-writers-guide.rst
@@ -0,0 +1,320 @@
+EL3 Runtime Service Writer's Guide
+=====================================================
+
+Introduction
+------------
+
+This document describes how to add a runtime service to the EL3 Runtime
+Firmware component of Trusted Firmware-A (TF-A), BL31.
+
+Software executing in the normal world and in the trusted world at exception
+levels lower than EL3 will request runtime services using the Secure Monitor
+Call (SMC) instruction. These requests will follow the convention described in
+the SMC Calling Convention PDD (`SMCCC`_). The `SMCCC`_ assigns function
+identifiers to each SMC request and describes how arguments are passed and
+results are returned.
+
+SMC Functions are grouped together based on the implementor of the service, for
+example a subset of the Function IDs are designated as "OEM Calls" (see `SMCCC`_
+for full details). The EL3 runtime services framework in BL31 enables the
+independent implementation of services for each group, which are then compiled
+into the BL31 image. This simplifies the integration of common software from
+Arm to support `PSCI`_, Secure Monitor for a Trusted OS and SoC specific
+software. The common runtime services framework ensures that SMC Functions are
+dispatched to their respective service implementation - the
+:ref:`Firmware Design` document provides details of how this is achieved.
+
+The interface and operation of the runtime services depends heavily on the
+concepts and definitions described in the `SMCCC`_, in particular SMC Function
+IDs, Owning Entity Numbers (OEN), Fast and Standard calls, and the SMC32 and
+SMC64 calling conventions. Please refer to that document for a full explanation
+of these terms.
+
+Owning Entities, Call Types and Function IDs
+--------------------------------------------
+
+The SMC Function Identifier includes a OEN field. These values and their
+meaning are described in `SMCCC`_ and summarized in table 1 below. Some entities
+are allocated a range of of OENs. The OEN must be interpreted in conjunction
+with the SMC call type, which is either *Fast* or *Yielding*. Fast calls are
+uninterruptible whereas Yielding calls can be pre-empted. The majority of
+Owning Entities only have allocated ranges for Fast calls: Yielding calls are
+reserved exclusively for Trusted OS providers or for interoperability with
+legacy 32-bit software that predates the `SMCCC`_.
+
+::
+
+    Type       OEN     Service
+    Fast        0      Arm Architecture calls
+    Fast        1      CPU Service calls
+    Fast        2      SiP Service calls
+    Fast        3      OEM Service calls
+    Fast        4      Standard Service calls
+    Fast       5-47    Reserved for future use
+    Fast      48-49    Trusted Application calls
+    Fast      50-63    Trusted OS calls
+
+    Yielding   0- 1    Reserved for existing Armv7-A calls
+    Yielding   2-63    Trusted OS Standard Calls
+
+*Table 1: Service types and their corresponding Owning Entity Numbers*
+
+Each individual entity can allocate the valid identifiers within the entity
+range as they need - it is not necessary to coordinate with other entities of
+the same type. For example, two SoC providers can use the same Function ID
+within the SiP Service calls OEN range to mean different things - as these
+calls should be specific to the SoC. The Standard Runtime Calls OEN is used for
+services defined by Arm standards, such as `PSCI`_.
+
+The SMC Function ID also indicates whether the call has followed the SMC32
+calling convention, where all parameters are 32-bit, or the SMC64 calling
+convention, where the parameters are 64-bit. The framework identifies and
+rejects invalid calls that use the SMC64 calling convention but that originate
+from an AArch32 caller.
+
+The EL3 runtime services framework uses the call type and OEN to identify a
+specific handler for each SMC call, but it is expected that an individual
+handler will be responsible for all SMC Functions within a given service type.
+
+Getting started
+---------------
+
+TF-A has a ``services`` directory in the source tree under which
+each owning entity can place the implementation of its runtime service. The
+`PSCI`_ implementation is located here in the ``lib/psci`` directory.
+
+Runtime service sources will need to include the ``runtime_svc.h`` header file.
+
+Registering a runtime service
+-----------------------------
+
+A runtime service is registered using the ``DECLARE_RT_SVC()`` macro, specifying
+the name of the service, the range of OENs covered, the type of service and
+initialization and call handler functions.
+
+.. code:: c
+
+    #define DECLARE_RT_SVC(_name, _start, _end, _type, _setup, _smch)
+
+-  ``_name`` is used to identify the data structure declared by this macro, and
+   is also used for diagnostic purposes
+
+-  ``_start`` and ``_end`` values must be based on the ``OEN_*`` values defined in
+   ``smccc.h``
+
+-  ``_type`` must be one of ``SMC_TYPE_FAST`` or ``SMC_TYPE_YIELD``
+
+-  ``_setup`` is the initialization function with the ``rt_svc_init`` signature:
+
+   .. code:: c
+
+       typedef int32_t (*rt_svc_init)(void);
+
+-  ``_smch`` is the SMC handler function with the ``rt_svc_handle`` signature:
+
+   .. code:: c
+
+       typedef uintptr_t (*rt_svc_handle_t)(uint32_t smc_fid,
+                                         u_register_t x1, u_register_t x2,
+                                         u_register_t x3, u_register_t x4,
+                                         void *cookie,
+                                         void *handle,
+                                         u_register_t flags);
+
+Details of the requirements and behavior of the two callbacks is provided in
+the following sections.
+
+During initialization the services framework validates each declared service
+to ensure that the following conditions are met:
+
+#. The ``_start`` OEN is not greater than the ``_end`` OEN
+#. The ``_end`` OEN does not exceed the maximum OEN value (63)
+#. The ``_type`` is one of ``SMC_TYPE_FAST`` or ``SMC_TYPE_YIELD``
+#. ``_setup`` and ``_smch`` routines have been specified
+
+``std_svc_setup.c`` provides an example of registering a runtime service:
+
+.. code:: c
+
+    /* Register Standard Service Calls as runtime service */
+    DECLARE_RT_SVC(
+            std_svc,
+            OEN_STD_START,
+            OEN_STD_END,
+            SMC_TYPE_FAST,
+            std_svc_setup,
+            std_svc_smc_handler
+    );
+
+Initializing a runtime service
+------------------------------
+
+Runtime services are initialized once, during cold boot, by the primary CPU
+after platform and architectural initialization is complete. The framework
+performs basic validation of the declared service before calling
+the service initialization function (``_setup`` in the declaration). This
+function must carry out any essential EL3 initialization prior to receiving a
+SMC Function call via the handler function.
+
+On success, the initialization function must return ``0``. Any other return value
+will cause the framework to issue a diagnostic:
+
+::
+
+    Error initializing runtime service <name of the service>
+
+and then ignore the service - the system will continue to boot but SMC calls
+will not be passed to the service handler and instead return the *Unknown SMC
+Function ID* result ``0xFFFFFFFF``.
+
+If the system must not be allowed to proceed without the service, the
+initialization function must itself cause the firmware boot to be halted.
+
+If the service uses per-CPU data this must either be initialized for all CPUs
+during this call, or be done lazily when a CPU first issues an SMC call to that
+service.
+
+Handling runtime service requests
+---------------------------------
+
+SMC calls for a service are forwarded by the framework to the service's SMC
+handler function (``_smch`` in the service declaration). This function must have
+the following signature:
+
+.. code:: c
+
+    typedef uintptr_t (*rt_svc_handle_t)(uint32_t smc_fid,
+                                       u_register_t x1, u_register_t x2,
+                                       u_register_t x3, u_register_t x4,
+                                       void *cookie,
+                                       void *handle,
+                                       u_register_t flags);
+
+The handler is responsible for:
+
+#. Determining that ``smc_fid`` is a valid and supported SMC Function ID,
+   otherwise completing the request with the *Unknown SMC Function ID*:
+
+   .. code:: c
+
+       SMC_RET1(handle, SMC_UNK);
+
+#. Determining if the requested function is valid for the calling security
+   state. SMC Calls can be made from Non-secure, Secure or Realm worlds and
+   the framework will forward all calls to the service handler.
+
+   The ``flags`` parameter to this function indicates the caller security state
+   in bits 0 and 5. The ``is_caller_secure(flags)``, ``is_caller_non_secure(flags)``
+   and ``is_caller_realm(flags)`` helper functions can be used to determine whether
+   the caller's security state is Secure, Non-secure or Realm respectively.
+
+   If invalid, the request should be completed with:
+
+   .. code:: c
+
+       SMC_RET1(handle, SMC_UNK);
+
+#. Truncating parameters for calls made using the SMC32 calling convention.
+   Such calls can be determined by checking the CC field in bit[30] of the
+   ``smc_fid`` parameter, for example by using:
+
+   ::
+
+       if (GET_SMC_CC(smc_fid) == SMC_32) ...
+
+   For such calls, the upper bits of the parameters x1-x4 and the saved
+   parameters X5-X7 are UNDEFINED and must be explicitly ignored by the
+   handler. This can be done by truncating the values to a suitable 32-bit
+   integer type before use, for example by ensuring that functions defined
+   to handle individual SMC Functions use appropriate 32-bit parameters.
+
+#. Providing the service requested by the SMC Function, utilizing the
+   immediate parameters x1-x4 and/or the additional saved parameters X5-X7.
+   The latter can be retrieved using the ``SMC_GET_GP(handle, ref)`` function,
+   supplying the appropriate ``CTX_GPREG_Xn`` reference, e.g.
+
+   .. code:: c
+
+       uint64_t x6 = SMC_GET_GP(handle, CTX_GPREG_X6);
+
+#. Implementing the standard SMC32 Functions that provide information about
+   the implementation of the service. These are the Call Count, Implementor
+   UID and Revision Details for each service documented in section 6 of the
+   `SMCCC`_.
+
+   TF-A expects owning entities to follow this recommendation.
+
+#. Returning the result to the caller. Based on `SMCCC`_ spec, results are
+   returned in W0-W7(X0-X7) registers for SMC32(SMC64) calls from AArch64
+   state. Results are returned in R0-R7 registers for SMC32 calls from AArch32
+   state. The framework provides a family of macros to set the multi-register
+   return value and complete the handler:
+
+   .. code:: c
+
+       AArch64 state:
+
+       SMC_RET1(handle, x0);
+       SMC_RET2(handle, x0, x1);
+       SMC_RET3(handle, x0, x1, x2);
+       SMC_RET4(handle, x0, x1, x2, x3);
+       SMC_RET5(handle, x0, x1, x2, x3, x4);
+       SMC_RET6(handle, x0, x1, x2, x3, x4, x5);
+       SMC_RET7(handle, x0, x1, x2, x3, x4, x5, x6);
+       SMC_RET8(handle, x0, x1, x2, x3, x4, x5, x6, x7);
+
+       AArch32 state:
+
+       SMC_RET1(handle, r0);
+       SMC_RET2(handle, r0, r1);
+       SMC_RET3(handle, r0, r1, r2);
+       SMC_RET4(handle, r0, r1, r2, r3);
+       SMC_RET5(handle, r0, r1, r2, r3, r4);
+       SMC_RET6(handle, r0, r1, r2, r3, r4, r5);
+       SMC_RET7(handle, r0, r1, r2, r3, r4, r5, r6);
+       SMC_RET8(handle, r0, r1, r2, r3, r4, r5, r6, r7);
+
+The ``cookie`` parameter to the handler is reserved for future use and can be
+ignored. The ``handle`` is returned by the SMC handler - completion of the
+handler function must always be via one of the ``SMC_RETn()`` macros.
+
+.. note::
+   The PSCI and Test Secure-EL1 Payload Dispatcher services do not follow
+   all of the above requirements yet.
+
+Services that contain multiple sub-services
+-------------------------------------------
+
+It is possible that a single owning entity implements multiple sub-services. For
+example, the Standard calls service handles ``0x84000000``-``0x8400FFFF`` and
+``0xC4000000``-``0xC400FFFF`` functions. Within that range, the `PSCI`_ service
+handles the ``0x84000000``-``0x8400001F`` and ``0xC4000000``-``0xC400001F`` functions.
+In that respect, `PSCI`_ is a 'sub-service' of the Standard calls service. In
+future, there could be additional such sub-services in the Standard calls
+service which perform independent functions.
+
+In this situation it may be valuable to introduce a second level framework to
+enable independent implementation of sub-services. Such a framework might look
+very similar to the current runtime services framework, but using a different
+part of the SMC Function ID to identify the sub-service. TF-A does not provide
+such a framework at present.
+
+Secure-EL1 Payload Dispatcher service (SPD)
+-------------------------------------------
+
+Services that handle SMC Functions targeting a Trusted OS, Trusted Application,
+or other Secure-EL1 Payload are special. These services need to manage the
+Secure-EL1 context, provide the *Secure Monitor* functionality of switching
+between the normal and secure worlds, deliver SMC Calls through to Secure-EL1
+and generally manage the Secure-EL1 Payload through CPU power-state transitions.
+
+TODO: Provide details of the additional work required to implement a SPD and
+the BL31 support for these services. Or a reference to the document that will
+provide this information....
+
+--------------
+
+*Copyright (c) 2014-2023, Arm Limited and Contributors. All rights reserved.*
+
+.. _SMCCC: https://developer.arm.com/docs/den0028/latest
+.. _PSCI: https://developer.arm.com/documentation/den0022/latest/
diff --git a/docs/getting_started/tools-build.rst b/docs/getting_started/tools-build.rst
new file mode 100644
index 0000000..166b527
--- /dev/null
+++ b/docs/getting_started/tools-build.rst
@@ -0,0 +1,179 @@
+Building Supporting Tools
+=========================
+
+.. note::
+
+    OpenSSL 3.0 is needed in order to build the tools. A custom installation
+    can be used if not updating the OpenSSL version on the OS. In order to do
+    this, use the ``OPENSSL_DIR`` variable after the ``make`` command to
+    indicate the location of the custom OpenSSL build. Then, to run the tools,
+    use the ``LD_LIBRARY_PATH`` to indicate the location of the built
+    libraries. More info about ``OPENSSL_DIR`` can be found at
+    :ref:`Build Options`.
+
+Building and using the FIP tool
+-------------------------------
+
+The following snippets build a :ref:`FIP<Image Terminology>` for the FVP
+platform. While it is not an intrinsic part of the FIP format, a BL33 image is
+required for these examples. For the purposes of experimentation, `Trusted
+Firmware-A Tests`_ (`tftf.bin``) may be used. Refer to to the `TFTF
+documentation`_ for instructions on building a TFTF binary.
+
+The TF-A build system provides the make target ``fip`` to create a FIP file
+for the specified platform using the FIP creation tool included in the TF-A
+project. Examples below show how to build a FIP file for FVP, packaging TF-A
+and BL33 images.
+
+For AArch64:
+
+.. code:: shell
+
+    make PLAT=fvp BL33=<path-to>/bl33.bin fip
+
+For AArch32:
+
+.. code:: shell
+
+    make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=<path-to>/bl33.bin fip
+
+The resulting FIP may be found in:
+
+::
+
+    build/fvp/<build-type>/fip.bin
+
+For advanced operations on FIP files, it is also possible to independently build
+the tool and create or modify FIPs using this tool. To do this, follow these
+steps:
+
+It is recommended to remove old artifacts before building the tool:
+
+.. code:: shell
+
+    make -C tools/fiptool clean
+
+Build the tool:
+
+.. code:: shell
+
+    make [DEBUG=1] [V=1] fiptool
+
+The tool binary can be located in:
+
+::
+
+    ./tools/fiptool/fiptool
+
+Invoking the tool with ``help`` will print a help message with all available
+options.
+
+Example 1: create a new Firmware package ``fip.bin`` that contains BL2 and BL31:
+
+.. code:: shell
+
+    ./tools/fiptool/fiptool create \
+        --tb-fw build/<platform>/<build-type>/bl2.bin \
+        --soc-fw build/<platform>/<build-type>/bl31.bin \
+        fip.bin
+
+Example 2: view the contents of an existing Firmware package:
+
+.. code:: shell
+
+    ./tools/fiptool/fiptool info <path-to>/fip.bin
+
+Example 3: update the entries of an existing Firmware package:
+
+.. code:: shell
+
+    # Change the BL2 from Debug to Release version
+    ./tools/fiptool/fiptool update \
+        --tb-fw build/<platform>/release/bl2.bin \
+        build/<platform>/debug/fip.bin
+
+Example 4: unpack all entries from an existing Firmware package:
+
+.. code:: shell
+
+    # Images will be unpacked to the working directory
+    ./tools/fiptool/fiptool unpack <path-to>/fip.bin
+
+Example 5: remove an entry from an existing Firmware package:
+
+.. code:: shell
+
+    ./tools/fiptool/fiptool remove \
+        --tb-fw build/<platform>/debug/fip.bin
+
+Note that if the destination FIP file exists, the create, update and
+remove operations will automatically overwrite it.
+
+The unpack operation will fail if the images already exist at the
+destination. In that case, use -f or --force to continue.
+
+More information about FIP can be found in the :ref:`Firmware Design` document.
+
+.. _tools_build_cert_create:
+
+Building the Certificate Generation Tool
+----------------------------------------
+
+The ``cert_create`` tool is built as part of the TF-A build process when the
+``fip`` make target is specified and TBB is enabled (as described in the
+previous section), but it can also be built separately with the following
+command:
+
+.. code:: shell
+
+    make PLAT=<platform> [DEBUG=1] [V=1] certtool
+
+For platforms that require their own IDs in certificate files, the generic
+'cert_create' tool can be built with the following command. Note that the target
+platform must define its IDs within a ``platform_oid.h`` header file for the
+build to succeed.
+
+.. code:: shell
+
+    make PLAT=<platform> USE_TBBR_DEFS=0 [DEBUG=1] [V=1] certtool
+
+``DEBUG=1`` builds the tool in debug mode. ``V=1`` makes the build process more
+verbose. The following command should be used to obtain help about the tool:
+
+.. code:: shell
+
+    ./tools/cert_create/cert_create -h
+
+.. _tools_build_enctool:
+
+Building the Firmware Encryption Tool
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``encrypt_fw`` tool is built as part of the TF-A build process when the
+``fip`` make target is specified, DECRYPTION_SUPPORT and TBB are enabled, but
+it can also be built separately with the following command:
+
+.. code:: shell
+
+    make PLAT=<platform> [DEBUG=1] [V=1] enctool
+
+``DEBUG=1`` builds the tool in debug mode. ``V=1`` makes the build process more
+verbose. The following command should be used to obtain help about the tool:
+
+.. code:: shell
+
+    ./tools/encrypt_fw/encrypt_fw -h
+
+Note that the enctool in its current implementation only supports encryption
+key to be provided in plain format. A typical implementation can very well
+extend this tool to support custom techniques to protect encryption key.
+
+Also, a user may choose to provide encryption key or nonce as an input file
+via using ``cat <filename>`` instead of a hex string.
+
+--------------
+
+*Copyright (c) 2019-2022, Arm Limited. All rights reserved.*
+
+.. _Trusted Firmware-A Tests: https://git.trustedfirmware.org/TF-A/tf-a-tests.git/
+.. _TFTF documentation: https://trustedfirmware-a-tests.readthedocs.io/en/latest/