diff --git a/docs/about/contact.rst b/docs/about/contact.rst
index b45fd4f..0f3821e 100644
--- a/docs/about/contact.rst
+++ b/docs/about/contact.rst
@@ -10,3 +10,6 @@
 --------------
 
 *Copyright (c) 2019, Arm Limited. All rights reserved.*
+
+.. _issue tracker: https://developer.trustedfirmware.org/project/board/9/
+.. _mailing list: https://lists.trustedfirmware.org/mailman/listinfo/tf-a-tests
diff --git a/docs/about/platforms.rst b/docs/about/platforms.rst
index 32d6da7..e57cbc9 100644
--- a/docs/about/platforms.rst
+++ b/docs/about/platforms.rst
@@ -44,3 +44,5 @@
 --------------
 
 *Copyright (c) 2019, Arm Limited. All rights reserved.*
+
+.. _FVP: https://developer.arm.com/products/system-design/fixed-virtual-platforms
diff --git a/docs/design.rst b/docs/design.rst
index 4df620c..5e85d6a 100644
--- a/docs/design.rst
+++ b/docs/design.rst
@@ -1,5 +1,5 @@
-Design
-======
+Framework Design
+================
 
 This document provides some details about the internals of the TF-A Tests
 design. It is incomplete at the moment.
@@ -242,5 +242,4 @@
 
 *Copyright (c) 2018-2019, Arm Limited. All rights reserved.*
 
-.. _Summary of build options: user-guide.rst#summary-of-build-options
 .. _Firmware Update: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/firmware-update.rst
diff --git a/docs/getting_started/build-options.rst b/docs/getting_started/build-options.rst
new file mode 100644
index 0000000..70ae546
--- /dev/null
+++ b/docs/getting_started/build-options.rst
@@ -0,0 +1,106 @@
+Summary of build options
+========================
+
+As much as possible, TF-A Tests dynamically detect the platform hardware
+components and available features. There are a few build options to select
+specific features where the dynamic detection falls short. This section lists
+them.
+
+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 dependencies for build options.
+Therefore, if any of the build options are changed from a previous build, a
+clean build must be performed.
+
+Build options shared across test images
+'''''''''''''''''''''''''''''''''''''''
+
+Most of the build options listed in this section apply to TFTF, the FWU test
+images and Cactus, unless otherwise specified. These do not influence the EL3
+payload, whose simplistic build system is mostly independent.
+
+-  ``ARCH``: Choose the target build architecture for TF-A Tests. It can take
+   either ``aarch64`` or ``aarch32`` as values. By default, it is defined to
+   ``aarch64``. Not all test images support this build option.
+
+-  ``ARM_ARCH_MAJOR``: The major version of Arm Architecture to target when
+   compiling TF-A Tests. Its value must be numeric, and defaults to 8.
+
+-  ``ARM_ARCH_MINOR``: The minor version of Arm Architecture to target when
+   compiling TF-A Tests. Its value must be a numeric, and defaults to 0.
+
+-  ``DEBUG``: Chooses between a debug and a release build. A debug build
+   typically embeds assertions checking the validity of some assumptions and its
+   output is more verbose. The option can take either 0 (release) or 1 (debug)
+   as values. 0 is the default.
+
+-  ``ENABLE_ASSERTIONS``: This option controls whether calls to ``assert()`` are
+   compiled out.
+
+   -  For debug builds, this option defaults to 1, and calls to ``assert()`` are
+      compiled in.
+   -  For release builds, this option defaults to 0 and calls to ``assert()``
+      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.
+
+-  ``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.
+
+-  ``PLAT``: Choose a platform to build TF-A Tests for. The chosen platform name
+   must be a subdirectory of any depth under ``plat/``, and must contain a
+   platform makefile named ``platform.mk``. For example, to build TF-A Tests for
+   the Arm Juno board, select ``PLAT=juno``.
+
+-  ``V``: Verbose build. If assigned anything other than 0, the build commands
+   are printed. Default is 0.
+
+TFTF build options
+''''''''''''''''''
+
+-  ``ENABLE_PAUTH``: Boolean option to enable ARMv8.3 Pointer Authentication
+   (``ARMv8.3-PAuth``) support in the Trusted Firmware-A Test Framework itself.
+   If enabled, it is needed to use a compiler that supports the option
+   ``-mbranch-protection`` (GCC 9 and later). It defaults to 0.
+
+-  ``NEW_TEST_SESSION``: Choose whether a new test session should be started
+   every time or whether the framework should determine whether a previous
+   session was interrupted and resume it. It can take either 1 (always
+   start new session) or 0 (resume session as appropriate). 1 is the default.
+
+-  ``TESTS``: Set of tests to run. Use the following command to list all
+   possible sets of tests:
+
+   ::
+
+     make help_tests
+
+   If no set of tests is specified, the standard tests will be selected (see
+   ``tftf/tests/tests-standard.xml``).
+
+-  ``USE_NVM``: Used to select the location of test results. It can take either 0
+   (RAM) or 1 (non-volatile memory like flash) as test results storage. Default
+   value is 0, as writing to the flash significantly slows tests down.
+
+FWU test images build options
+'''''''''''''''''''''''''''''
+
+-  ``FIRMWARE_UPDATE``: Whether the Firmware Update test images (i.e.
+   ``NS_BL1U`` and ``NS_BL2U``) should be built. The default value is 0.  The
+   platform makefile is free to override this value if Firmware Update is
+   supported on this platform.
diff --git a/docs/getting_started/build.rst b/docs/getting_started/build.rst
new file mode 100644
index 0000000..cb8d358
--- /dev/null
+++ b/docs/getting_started/build.rst
@@ -0,0 +1,294 @@
+Building TF-A Tests
+===================
+
+-  Before building TF-A Tests, the environment variable ``CROSS_COMPILE`` must
+   point to the cross compiler.
+
+   For AArch64:
+
+   ::
+
+       export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf-
+
+   For AArch32:
+
+   ::
+
+       export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-eabi-
+
+-  Change to the root directory of the TF-A Tests source tree and build.
+
+   For AArch64:
+
+   ::
+
+       make PLAT=<platform>
+
+   For AArch32:
+
+   ::
+
+       make PLAT=<platform> ARCH=aarch32
+
+   Notes:
+
+   -  If ``PLAT`` is not specified, ``fvp`` is assumed by default. See the
+      `Summary of build options`_ for more information on available build
+      options.
+
+   -  By default this produces a release version of the build. To produce a
+      debug version instead, build the code with ``DEBUG=1``.
+
+   -  The build process creates products in a ``build/`` directory tree,
+      building the objects and binaries for each test image in separate
+      sub-directories. The following binary files are created from the
+      corresponding ELF files:
+
+      -  ``build/<platform>/<build-type>/tftf.bin``
+      -  ``build/<platform>/<build-type>/ns_bl1u.bin``
+      -  ``build/<platform>/<build-type>/ns_bl2u.bin``
+      -  ``build/<platform>/<build-type>/el3_payload.bin``
+      -  ``build/<platform>/<build-type>/cactus_mm.bin``
+      -  ``build/<platform>/<build-type>/cactus.bin``
+      -  ``build/<platform>/<build-type>/ivy.bin``
+      -  ``build/<platform>/<build-type>/quark.bin``
+
+      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.
+
+      Refer to the sections below for more information about each image.
+
+-  Build products for a specific build variant can be removed using:
+
+   ::
+
+       make DEBUG=<D> PLAT=<platform> clean
+
+   ... where ``<D>`` is ``0`` or ``1``, as specified when building.
+
+   The build tree can be removed completely using:
+
+   ::
+
+       make realclean
+
+-  Use the following command to list all supported build commands:
+
+   ::
+
+       make help
+
+TFTF test image
+```````````````
+
+``tftf.bin`` is the main test image to exercise the TF-A features. The other
+test images provided in this repository are optional dependencies that TFTF
+needs to test some specific features.
+
+``tftf.bin`` may be built independently of the other test images using the
+following command:
+
+::
+
+   make PLAT=<platform> tftf
+
+In TF-A boot flow, ``tftf.bin`` replaces the ``BL33`` image and should be
+injected in the FIP image. This might be achieved by running the following
+command from the TF-A root directory:
+
+::
+
+    BL33=tftf.bin make PLAT=<platform> fip
+
+Please refer to the `TF-A User guide`_ for further details.
+
+NS_BL1U and NS_BL2U test images
+```````````````````````````````
+
+``ns_bl1u.bin`` and ``ns_bl2u.bin`` are test images that exercise the `Firmware
+Update`_ (FWU) feature of TF-A [#]_. Throughout this document, they will be
+referred as the `FWU test images`.
+
+In addition to updating the firmware, the FWU test images also embed some tests
+that exercise the `FWU state machine`_ implemented in the TF-A. They send valid
+and invalid SMC requests to the TF-A BL1 image in order to test its robustness.
+
+NS_BL1U test image
+''''''''''''''''''
+
+The ``NS_BL1U`` image acts as the `Application Processor (AP) Firmware Update
+Boot ROM`. This typically is the first software agent executing on the AP in the
+Normal World during a firmware update operation. Its primary purpose is to load
+subsequent firmware update images from an external interface, such as NOR Flash,
+and communicate with ``BL1`` to authenticate those images.
+
+The ``NS_BL1U`` test image provided in this repository performs the following
+tasks:
+
+-  Load FWU images from external non-volatile storage (typically flash memory)
+   to Non-Secure RAM.
+
+-  Request TF-A BL1 to copy these images in Secure RAM and authenticate them.
+
+-  Jump to ``NS_BL2U`` which carries out the next steps in the firmware update
+   process.
+
+This image may be built independently of the other test images using the
+following command:
+
+::
+
+   make PLAT=<platform> ns_bl1u
+
+NS_BL2U test image
+''''''''''''''''''
+
+The ``NS_BL2U`` image acts as the `AP Firmware Updater`. Its primary
+responsibility is to load a new set of firmware images from an external
+interface and write them into non-volatile storage.
+
+The ``NS_BL2U`` test image provided in this repository overrides the original
+FIP image stored in flash with the backup FIP image (see below).
+
+This image may be built independently of the other test images using the
+following command:
+
+::
+
+   make PLAT=<platform> ns_bl2u
+
+Putting it all together
+'''''''''''''''''''''''
+
+The FWU test images should be used in conjunction with the TFTF image, as the
+latter initiates the FWU process by corrupting the FIP image and resetting the
+target. Once the FWU process is complete, TFTF takes over again and checks that
+the firmware was successfully updated.
+
+To sum up, 3 images must be built out of the TF-A Tests repository in order to
+test the TF-A Firmware Update feature:
+
+-  ``ns_bl1u.bin``
+-  ``ns_bl2u.bin``
+-  ``tftf.bin``
+
+Once that's done, they must be combined in the right way.
+
+-  ``ns_bl1u.bin`` is a standalone image and does not require any further
+   processing.
+
+-  ``ns_bl2u.bin`` must be injected into the ``FWU_FIP`` image. This might be
+   achieved by setting ``NS_BL2U=ns_bl2u.bin`` when building the ``FWU_FIP``
+   image out of the TF-A repository. Please refer to the section `Building FIP
+   images with support for Trusted Board Boot`_ in the TF-A User Guide.
+
+-  ``tftf.bin`` must be injected in the standard FIP image, as explained
+   in section `TFTF test image`_.
+
+Additionally, on Juno platform, the FWU FIP must contain a ``SCP_BL2U`` image.
+This image can simply be a copy of the standard ``SCP_BL2`` image if no specific
+firmware update operations need to be carried on the SCP side.
+
+Finally, the backup FIP image must be created. This can simply be a copy of the
+standard FIP image, which means that the Firmware Update process will restore
+the original, uncorrupted FIP image.
+
+EL3 test payload
+````````````````
+
+``el3_payload.bin`` is a test image exercising the alternative `EL3 payload boot
+flow`_ in TF-A. Refer to the `EL3 test payload README file`_ for more details
+about its behaviour and how to build and run it.
+
+SPM test images
+```````````````
+
+This repository contains 3 Secure Partitions that exercise the `Secure Partition
+Manager`_ (SPM) in TF-A [#]_. Cactus-MM is designed to test the SPM
+implementation based on the `ARM Management Mode Interface`_ (MM), while Cactus
+and Ivy can test the SPM implementation based on the SPCI and SPRT draft
+specifications. Note that it isn't possible to use both communication mechanisms
+at once: If Cactus-MM is used Cactus and Ivy can't be used.
+
+They run in Secure-EL0 and perform the following tasks:
+
+-  Test that TF-A has correctly setup the secure partition environment: They
+   should be allowed to perform cache maintenance operations, access floating
+   point registers, etc.
+
+-  Test that TF-A accepts to change data access permissions and instruction
+   permissions on behalf of the Secure Partitions for memory regions the latter
+   owns.
+
+-  Test communication with SPM through either MM, or both SPCI and SPRT.
+
+They are only supported on AArch64 FVP. They can be built independently of the
+other test images using the following command:
+
+::
+
+   make PLAT=fvp cactus ivy cactus_mm
+
+In the TF-A boot flow, the partitions replace the ``BL32`` image and should be
+injected in the FIP image. To test SPM-MM with Cactus-MM, it is enough to use
+``cactus_mm.bin`` as BL32 image. To test the SPM based on SPCI and SPRT, it is
+needed to use ``sp_tool`` to build a Secure Partition package that can be used
+as BL32 image.
+
+To run the full set of tests in the Secure Partitions, they should be used in
+conjunction with the TFTF image.
+
+For SPM-MM, build TF-A following the `TF-A SPM User Guide`_ and the following
+commands can be used to build the tests:
+
+::
+
+    # TF-A-Tests repository:
+
+    make PLAT=fvp TESTS=spm-mm tftf cactus_mm
+
+For SPM based on SPCI and SPRT, build TF-A following the `TF-A SPM User Guide`_
+and the following commands can be used to build the tests:
+
+::
+
+    # TF-A-Tests repository:
+
+    make PLAT=fvp TESTS=spm tftf cactus ivy
+
+    # TF-A repository:
+
+    make sptool
+
+    tools/sptool/sptool -o sp_package.bin \
+        -i path/to/cactus.bin:path/to/cactus.dtb \
+        -i path/to/ivy.bin:path/to/ivy.dtb
+
+Please refer to the `TF-A User guide`_ for further details.
+
+--------------
+
+.. [#] Therefore, the Trusted Board Boot feature must be enabled in TF-A for
+       the FWU test images to work. Please refer the `TF-A User guide`_ for
+       further details.
+
+.. [#] Therefore, the Secure Partition Manager must be enabled in TF-A for
+       any of the test Secure Partitions to work. Please refer to the `TF-A User
+       guide`_ for further details.
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
+
+.. _EL3 payload boot flow: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/user-guide.rst#el3-payloads-alternative-boot-flow
+.. _TF-A User Guide: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/user-guide.rst
+.. _TF-A SPM User Guide: https://trustedfirmware-a.readthedocs.io/en/latest/components/secure-partition-manager-design.html#building-tf-a-with-secure-partition-support
+.. _Firmware Update: FWU_
+.. _EL3 test payload README file: ../el3_payload/README
+.. _FWU: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/firmware-update.rst
+.. _FWU state machine: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/firmware-update.rst#fwu-state-machine
+.. _Summary of build options: user-guide.rst#summary-of-build-options
+.. _Building FIP images with support for Trusted Board Boot: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/user-guide.rst#building-fip-images-with-support-for-trusted-board-boot
+.. _Secure partition Manager: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/secure-partition-manager-design.rst
+.. _ARM Management Mode Interface: http://infocenter.arm.com/help/topic/com.arm.doc.den0060a/DEN0060A_ARM_MM_Interface_Specification.pdf
diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst
index 5da6747..25881dd 100644
--- a/docs/getting_started/index.rst
+++ b/docs/getting_started/index.rst
@@ -5,6 +5,10 @@
    :maxdepth: 1
 
    requirements
+   obtain
+   build
+   build-options
+   run
 
 This document describes how to build the Trusted Firmware-A Tests (TF-A Tests)
 and run them on a set of platforms. It assumes that the reader has previous
diff --git a/docs/getting_started/obtain.rst b/docs/getting_started/obtain.rst
new file mode 100644
index 0000000..1c4183d
--- /dev/null
+++ b/docs/getting_started/obtain.rst
@@ -0,0 +1,12 @@
+Getting the TF-A Tests source code
+==================================
+
+Download the TF-A Tests source code using the following command:
+
+::
+
+    git clone https://git.trustedfirmware.org/TF-A/tf-a-tests.git
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/run.rst b/docs/getting_started/run.rst
new file mode 100644
index 0000000..f9489e2
--- /dev/null
+++ b/docs/getting_started/run.rst
@@ -0,0 +1,115 @@
+Running the TF-A Tests
+======================
+
+Refer to the sections `Running the software on FVP`_ and `Running the software
+on Juno`_ in `TF-A User Guide`_. The same instructions mostly apply to run the
+TF-A Tests on those 2 platforms. The difference is that the following images are
+not needed here:
+
+-  Normal World bootloader. The TFTF replaces it in the boot flow;
+
+-  Linux Kernel;
+
+-  Device tree;
+
+-  Filesystem.
+
+In other words, only the following software images are needed:
+
+-  ``BL1`` firmware image;
+
+-  ``FIP`` image containing the following images:
+
+   -  ``BL2``;
+   -  ``SCP_BL2`` if required by the platform (e.g. Juno);
+   -  ``BL31``;
+   -  ``BL32`` (optional);
+   -  ``tftf.bin`` (standing as the BL33 image).
+
+Running the manual tests on FVP
+```````````````````````````````
+The manual tests rely on storing state in non-volatile memory (NVM) across
+reboot. On FVP the NVM is not persistent across reboots, so the following
+flag must be used to write the NVM to a file when the model exits.
+
+::
+
+        -C bp.flashloader0.fnameWrite=[filename]
+
+To ensure the model exits on shutdown the following flag must be used:
+
+::
+
+        -C bp.ve_sysregs.exit_on_shutdown=1
+
+After the model has been shutdown, this file must be fed back in to continue
+the test. Note this flash file includes the FIP image, so the original fip.bin
+does not need to be passed in. The following flag is used:
+
+::
+
+        -C bp.flashloader0.fname=[filename]
+
+Running the FWU tests
+`````````````````````
+
+As previously mentioned in section `Putting it all together`_, there are a
+couple of extra images involved when running the FWU tests. They need to be
+loaded at the right addresses, which depend on the platform.
+
+FVP
+'''
+
+In addition to the usual BL1 and FIP images, the following extra images must be
+loaded:
+
+-  ``NS_BL1U`` image at address ``0x0BEB8000`` (i.e. NS_BL1U_BASE macro in TF-A)
+-  ``FWU_FIP`` image at address ``0x08400000`` (i.e. NS_BL2U_BASE macro in TF-A)
+-  ``Backup FIP`` image at address ``0x09000000`` (i.e. FIP_BKP_ADDRESS macro in
+   TF-A tests).
+
+An example script is provided in `scripts/run_fwu_fvp.sh`_.
+
+Juno
+''''
+
+The same set of extra images and load addresses apply for Juno as for FVP.
+
+The new images must be programmed in flash memory by adding some entries in the
+``SITE1/HBI0262x/images.txt`` configuration file on the Juno SD card (where
+``x`` depends on the revision of the Juno board). Refer to the `Juno Getting
+Started Guide`_, section 2.3 "Flash memory programming" for more
+information. Users should ensure these do not overlap with any other entries in
+the file.
+
+Addresses in this file are expressed as an offset from the base address of the
+flash (that is, ``0x08000000``).
+
+::
+
+    NOR10UPDATE: AUTO                       ; Image Update:NONE/AUTO/FORCE
+    NOR10ADDRESS: 0x00400000                ; Image Flash Address
+    NOR10FILE: \SOFTWARE\fwu_fip.bin        ; Image File Name
+    NOR10LOAD: 00000000                     ; Image Load Address
+    NOR10ENTRY: 00000000                    ; Image Entry Point
+
+    NOR11UPDATE: AUTO                       ; Image Update:NONE/AUTO/FORCE
+    NOR11ADDRESS: 0x03EB8000                ; Image Flash Address
+    NOR11FILE: \SOFTWARE\ns_bl1u.bin        ; Image File Name
+    NOR11LOAD: 00000000                     ; Image Load Address
+    NOR11ENTRY: 00000000                    ; Image Load Address
+
+    NOR12UPDATE: AUTO                       ; Image Update:NONE/AUTO/FORCE
+    NOR12ADDRESS: 0x01000000                ; Image Flash Address
+    NOR12FILE: \SOFTWARE\backup_fip.bin     ; Image File Name
+    NOR12LOAD: 00000000                     ; Image Load Address
+    NOR12ENTRY: 00000000                    ; Image Entry Point
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
+
+.. _scripts/run_fwu_fvp.sh: ../scripts/run_fwu_fvp.sh
+.. _Juno Getting Started Guide: http://infocenter.arm.com/help/topic/com.arm.doc.dui0928e/DUI0928E_juno_arm_development_platform_gsg.pdf
+.. _Running the software on FVP: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/user-guide.rst#running-the-software-on-fvp
+.. _Running the software on Juno: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/user-guide.rst#running-the-software-on-juno
diff --git a/docs/index.rst b/docs/index.rst
index e9006e7..1436767 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -8,7 +8,7 @@
    Home<self>
    about/index
    getting_started/index
-   user-guide
+   process/index
    porting-guide
    implementing-tests
    design
@@ -65,7 +65,6 @@
 
 *Copyright (c)2019, Arm Limited. All rights reserved.*
 
-.. _FVP: https://developer.arm.com/products/system-design/fixed-virtual-platforms
 .. _Juno Arm Development Platform: https://developer.arm.com/products/system-design/development-boards/juno-development-board
 
 .. _Power State Coordination Interface (PSCI): PSCI_
@@ -85,6 +84,3 @@
 .. _Firmware update: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/firmware-update.rst
 .. _EL3 payload: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/user-guide.rst#el3-payloads-alternative-boot-flow
 .. _Secure partition: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/secure-partition-manager-design.rst
-
-.. _issue tracker: https://developer.trustedfirmware.org/project/board/9/
-.. _mailing list: https://lists.trustedfirmware.org/mailman/listinfo/tf-a-tests
diff --git a/docs/process/index.rst b/docs/process/index.rst
new file mode 100644
index 0000000..0af417d
--- /dev/null
+++ b/docs/process/index.rst
@@ -0,0 +1,11 @@
+Processes & Policies
+====================
+
+.. toctree::
+   :maxdepth: 1
+
+   style
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/process/style.rst b/docs/process/style.rst
new file mode 100644
index 0000000..5a6c1c2
--- /dev/null
+++ b/docs/process/style.rst
@@ -0,0 +1,35 @@
+Checking source code style
+--------------------------
+
+When making changes to the source for submission to the project, the source must
+be in compliance with the Linux style guide. To assist with this, the project
+Makefile provides two targets, which both utilise the ``checkpatch.pl`` script
+that ships with the Linux source tree.
+
+To check the entire source tree, you must first download copies of
+``checkpatch.pl``, ``spelling.txt`` and ``const_structs.checkpatch`` available
+in the `Linux master tree`_ scripts directory, then set the ``CHECKPATCH``
+environment variable to point to ``checkpatch.pl`` (with the other 2 files in
+the same directory).
+
+Then use the following command:
+
+::
+
+    make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkcodebase
+
+To limit the coding style checks to your local changes, use:
+
+::
+
+    make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkpatch
+
+By default, this will check all patches between ``origin/master`` and your local
+branch. If you wish to use a different reference commit, this can be specified
+using the ``BASE_COMMIT`` variable.
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
+
+.. _Linux master tree: https://github.com/torvalds/linux/tree/master/
diff --git a/docs/user-guide.rst b/docs/user-guide.rst
deleted file mode 100644
index cb696e6..0000000
--- a/docs/user-guide.rst
+++ /dev/null
@@ -1,566 +0,0 @@
-User Guide
-==========
-
-Getting the TF-A Tests source code
-----------------------------------
-
-Download the TF-A Tests source code using the following command:
-
-::
-
-    git clone https://git.trustedfirmware.org/TF-A/tf-a-tests.git
-
-Building TF-A Tests
--------------------
-
--  Before building TF-A Tests, the environment variable ``CROSS_COMPILE`` must
-   point to the cross compiler.
-
-   For AArch64:
-
-   ::
-
-       export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf-
-
-   For AArch32:
-
-   ::
-
-       export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-none-eabi-
-
--  Change to the root directory of the TF-A Tests source tree and build.
-
-   For AArch64:
-
-   ::
-
-       make PLAT=<platform>
-
-   For AArch32:
-
-   ::
-
-       make PLAT=<platform> ARCH=aarch32
-
-   Notes:
-
-   -  If ``PLAT`` is not specified, ``fvp`` is assumed by default. See the
-      `Summary of build options`_ for more information on available build
-      options.
-
-   -  By default this produces a release version of the build. To produce a
-      debug version instead, build the code with ``DEBUG=1``.
-
-   -  The build process creates products in a ``build/`` directory tree,
-      building the objects and binaries for each test image in separate
-      sub-directories. The following binary files are created from the
-      corresponding ELF files:
-
-      -  ``build/<platform>/<build-type>/tftf.bin``
-      -  ``build/<platform>/<build-type>/ns_bl1u.bin``
-      -  ``build/<platform>/<build-type>/ns_bl2u.bin``
-      -  ``build/<platform>/<build-type>/el3_payload.bin``
-      -  ``build/<platform>/<build-type>/cactus_mm.bin``
-      -  ``build/<platform>/<build-type>/cactus.bin``
-      -  ``build/<platform>/<build-type>/ivy.bin``
-      -  ``build/<platform>/<build-type>/quark.bin``
-
-      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.
-
-      Refer to the sections below for more information about each image.
-
--  Build products for a specific build variant can be removed using:
-
-   ::
-
-       make DEBUG=<D> PLAT=<platform> clean
-
-   ... where ``<D>`` is ``0`` or ``1``, as specified when building.
-
-   The build tree can be removed completely using:
-
-   ::
-
-       make realclean
-
--  Use the following command to list all supported build commands:
-
-   ::
-
-       make help
-
-TFTF test image
-```````````````
-
-``tftf.bin`` is the main test image to exercise the TF-A features. The other
-test images provided in this repository are optional dependencies that TFTF
-needs to test some specific features.
-
-``tftf.bin`` may be built independently of the other test images using the
-following command:
-
-::
-
-   make PLAT=<platform> tftf
-
-In TF-A boot flow, ``tftf.bin`` replaces the ``BL33`` image and should be
-injected in the FIP image. This might be achieved by running the following
-command from the TF-A root directory:
-
-::
-
-    BL33=tftf.bin make PLAT=<platform> fip
-
-Please refer to the `TF-A User guide`_ for further details.
-
-NS_BL1U and NS_BL2U test images
-```````````````````````````````
-
-``ns_bl1u.bin`` and ``ns_bl2u.bin`` are test images that exercise the `Firmware
-Update`_ (FWU) feature of TF-A [#]_. Throughout this document, they will be
-referred as the `FWU test images`.
-
-In addition to updating the firmware, the FWU test images also embed some tests
-that exercise the `FWU state machine`_ implemented in the TF-A. They send valid
-and invalid SMC requests to the TF-A BL1 image in order to test its robustness.
-
-NS_BL1U test image
-''''''''''''''''''
-
-The ``NS_BL1U`` image acts as the `Application Processor (AP) Firmware Update
-Boot ROM`. This typically is the first software agent executing on the AP in the
-Normal World during a firmware update operation. Its primary purpose is to load
-subsequent firmware update images from an external interface, such as NOR Flash,
-and communicate with ``BL1`` to authenticate those images.
-
-The ``NS_BL1U`` test image provided in this repository performs the following
-tasks:
-
--  Load FWU images from external non-volatile storage (typically flash memory)
-   to Non-Secure RAM.
-
--  Request TF-A BL1 to copy these images in Secure RAM and authenticate them.
-
--  Jump to ``NS_BL2U`` which carries out the next steps in the firmware update
-   process.
-
-This image may be built independently of the other test images using the
-following command:
-
-::
-
-   make PLAT=<platform> ns_bl1u
-
-NS_BL2U test image
-''''''''''''''''''
-
-The ``NS_BL2U`` image acts as the `AP Firmware Updater`. Its primary
-responsibility is to load a new set of firmware images from an external
-interface and write them into non-volatile storage.
-
-The ``NS_BL2U`` test image provided in this repository overrides the original
-FIP image stored in flash with the backup FIP image (see below).
-
-This image may be built independently of the other test images using the
-following command:
-
-::
-
-   make PLAT=<platform> ns_bl2u
-
-Putting it all together
-'''''''''''''''''''''''
-
-The FWU test images should be used in conjunction with the TFTF image, as the
-latter initiates the FWU process by corrupting the FIP image and resetting the
-target. Once the FWU process is complete, TFTF takes over again and checks that
-the firmware was successfully updated.
-
-To sum up, 3 images must be built out of the TF-A Tests repository in order to
-test the TF-A Firmware Update feature:
-
--  ``ns_bl1u.bin``
--  ``ns_bl2u.bin``
--  ``tftf.bin``
-
-Once that's done, they must be combined in the right way.
-
--  ``ns_bl1u.bin`` is a standalone image and does not require any further
-   processing.
-
--  ``ns_bl2u.bin`` must be injected into the ``FWU_FIP`` image. This might be
-   achieved by setting ``NS_BL2U=ns_bl2u.bin`` when building the ``FWU_FIP``
-   image out of the TF-A repository. Please refer to the section `Building FIP
-   images with support for Trusted Board Boot`_ in the TF-A User Guide.
-
--  ``tftf.bin`` must be injected in the standard FIP image, as explained
-   in section `TFTF test image`_.
-
-Additionally, on Juno platform, the FWU FIP must contain a ``SCP_BL2U`` image.
-This image can simply be a copy of the standard ``SCP_BL2`` image if no specific
-firmware update operations need to be carried on the SCP side.
-
-Finally, the backup FIP image must be created. This can simply be a copy of the
-standard FIP image, which means that the Firmware Update process will restore
-the original, uncorrupted FIP image.
-
-EL3 test payload
-````````````````
-
-``el3_payload.bin`` is a test image exercising the alternative `EL3 payload boot
-flow`_ in TF-A. Refer to the `EL3 test payload README file`_ for more details
-about its behaviour and how to build and run it.
-
-SPM test images
-```````````````
-
-This repository contains 3 Secure Partitions that exercise the `Secure Partition
-Manager`_ (SPM) in TF-A [#]_. Cactus-MM is designed to test the SPM
-implementation based on the `ARM Management Mode Interface`_ (MM), while Cactus
-and Ivy can test the SPM implementation based on the SPCI and SPRT draft
-specifications. Note that it isn't possible to use both communication mechanisms
-at once: If Cactus-MM is used Cactus and Ivy can't be used.
-
-They run in Secure-EL0 and perform the following tasks:
-
--  Test that TF-A has correctly setup the secure partition environment: They
-   should be allowed to perform cache maintenance operations, access floating
-   point registers, etc.
-
--  Test that TF-A accepts to change data access permissions and instruction
-   permissions on behalf of the Secure Partitions for memory regions the latter
-   owns.
-
--  Test communication with SPM through either MM, or both SPCI and SPRT.
-
-They are only supported on AArch64 FVP. They can be built independently of the
-other test images using the following command:
-
-::
-
-   make PLAT=fvp cactus ivy cactus_mm
-
-In the TF-A boot flow, the partitions replace the ``BL32`` image and should be
-injected in the FIP image. To test SPM-MM with Cactus-MM, it is enough to use
-``cactus_mm.bin`` as BL32 image. To test the SPM based on SPCI and SPRT, it is
-needed to use ``sp_tool`` to build a Secure Partition package that can be used
-as BL32 image.
-
-To run the full set of tests in the Secure Partitions, they should be used in
-conjunction with the TFTF image.
-
-For SPM-MM, the following commands can be used to build the tests:
-
-::
-    # TF-A-Tests repository:
-
-    make PLAT=fvp TESTS=spm-mm tftf cactus_mm
-
-    # TF-A repository:
-
-    make BL33=path/to/tftf.bin BL32=path/to/cactus_mm.bin \
-    PLAT=fvp EL3_EXCEPTION_HANDLING=1 ENABLE_SPM=1 all fip
-
-For SPM based on SPCI and SPRT:
-
-::
-    # TF-A-Tests repository:
-
-    make PLAT=fvp TESTS=spm tftf cactus ivy
-
-    # TF-A repository:
-
-    make sptool
-
-    tools/sptool/sptool -o sp_package.bin \
-        -i path/to/cactus.bin:path/to/cactus.dtb \
-        -i path/to/ivy.bin:path/to/ivy.dtb
-
-    make BL33=path/to/tftf.bin BL32=path/to/sp_package.bin \
-    PLAT=fvp ENABLE_SPM=1 SPM_MM=0 ARM_BL31_IN_DRAM=1 all fip
-
-Please refer to the `TF-A User guide`_ for further details.
-
-Summary of build options
-````````````````````````
-
-As much as possible, TF-A Tests dynamically detect the platform hardware
-components and available features. There are a few build options to select
-specific features where the dynamic detection falls short. This section lists
-them.
-
-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 dependencies for build options.
-Therefore, if any of the build options are changed from a previous build, a
-clean build must be performed.
-
-Build options shared across test images
-'''''''''''''''''''''''''''''''''''''''
-
-Most of the build options listed in this section apply to TFTF, the FWU test
-images and Cactus, unless otherwise specified. These do not influence the EL3
-payload, whose simplistic build system is mostly independent.
-
--  ``ARCH``: Choose the target build architecture for TF-A Tests. It can take
-   either ``aarch64`` or ``aarch32`` as values. By default, it is defined to
-   ``aarch64``. Not all test images support this build option.
-
--  ``ARM_ARCH_MAJOR``: The major version of Arm Architecture to target when
-   compiling TF-A Tests. Its value must be numeric, and defaults to 8.
-
--  ``ARM_ARCH_MINOR``: The minor version of Arm Architecture to target when
-   compiling TF-A Tests. Its value must be a numeric, and defaults to 0.
-
--  ``DEBUG``: Chooses between a debug and a release build. A debug build
-   typically embeds assertions checking the validity of some assumptions and its
-   output is more verbose. The option can take either 0 (release) or 1 (debug)
-   as values. 0 is the default.
-
--  ``ENABLE_ASSERTIONS``: This option controls whether calls to ``assert()`` are
-   compiled out.
-
-   -  For debug builds, this option defaults to 1, and calls to ``assert()`` are
-      compiled in.
-   -  For release builds, this option defaults to 0 and calls to ``assert()``
-      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.
-
--  ``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.
-
--  ``PLAT``: Choose a platform to build TF-A Tests for. The chosen platform name
-   must be a subdirectory of any depth under ``plat/``, and must contain a
-   platform makefile named ``platform.mk``. For example, to build TF-A Tests for
-   the Arm Juno board, select ``PLAT=juno``.
-
--  ``V``: Verbose build. If assigned anything other than 0, the build commands
-   are printed. Default is 0.
-
-TFTF build options
-''''''''''''''''''
-
--  ``ENABLE_PAUTH``: Boolean option to enable ARMv8.3 Pointer Authentication
-   (``ARMv8.3-PAuth``) support in the Trusted Firmware-A Test Framework itself.
-   If enabled, it is needed to use a compiler that supports the option
-   ``-mbranch-protection`` (GCC 9 and later). It defaults to 0.
-
--  ``NEW_TEST_SESSION``: Choose whether a new test session should be started
-   every time or whether the framework should determine whether a previous
-   session was interrupted and resume it. It can take either 1 (always
-   start new session) or 0 (resume session as appropriate). 1 is the default.
-
--  ``TESTS``: Set of tests to run. Use the following command to list all
-   possible sets of tests:
-
-   ::
-
-     make help_tests
-
-   If no set of tests is specified, the standard tests will be selected (see
-   ``tftf/tests/tests-standard.xml``).
-
--  ``USE_NVM``: Used to select the location of test results. It can take either 0
-   (RAM) or 1 (non-volatile memory like flash) as test results storage. Default
-   value is 0, as writing to the flash significantly slows tests down.
-
-FWU test images build options
-'''''''''''''''''''''''''''''
-
--  ``FIRMWARE_UPDATE``: Whether the Firmware Update test images (i.e.
-   ``NS_BL1U`` and ``NS_BL2U``) should be built. The default value is 0.  The
-   platform makefile is free to override this value if Firmware Update is
-   supported on this platform.
-
-Arm FVP platform specific build options
-'''''''''''''''''''''''''''''''''''''''
-
--  ``FVP_MAX_PE_PER_CPU``: Sets the maximum number of PEs implemented on any CPU
-   in the system. It can take either 1 or 2 values. This option defaults to 1.
-
-Checking source code style
---------------------------
-
-When making changes to the source for submission to the project, the source must
-be in compliance with the Linux style guide. To assist with this, the project
-Makefile provides two targets, which both utilise the ``checkpatch.pl`` script
-that ships with the Linux source tree.
-
-To check the entire source tree, you must first download copies of
-``checkpatch.pl``, ``spelling.txt`` and ``const_structs.checkpatch`` available
-in the `Linux master tree`_ scripts directory, then set the ``CHECKPATCH``
-environment variable to point to ``checkpatch.pl`` (with the other 2 files in
-the same directory).
-
-Then use the following command:
-
-::
-
-    make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkcodebase
-
-To limit the coding style checks to your local changes, use:
-
-::
-
-    make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkpatch
-
-By default, this will check all patches between ``origin/master`` and your local
-branch. If you wish to use a different reference commit, this can be specified
-using the ``BASE_COMMIT`` variable.
-
-Running the TF-A Tests
-----------------------
-
-Refer to the sections `Running the software on FVP`_ and `Running the software
-on Juno`_ in `TF-A User Guide`_. The same instructions mostly apply to run the
-TF-A Tests on those 2 platforms. The difference is that the following images are
-not needed here:
-
--  Normal World bootloader. The TFTF replaces it in the boot flow;
-
--  Linux Kernel;
-
--  Device tree;
-
--  Filesystem.
-
-In other words, only the following software images are needed:
-
--  ``BL1`` firmware image;
-
--  ``FIP`` image containing the following images:
-
-   -  ``BL2``;
-   -  ``SCP_BL2`` if required by the platform (e.g. Juno);
-   -  ``BL31``;
-   -  ``BL32`` (optional);
-   -  ``tftf.bin`` (standing as the BL33 image).
-
-Running the manual tests on FVP
-```````````````````````````````
-The manual tests rely on storing state in non-volatile memory (NVM) across
-reboot. On FVP the NVM is not persistent across reboots, so the following
-flag must be used to write the NVM to a file when the model exits.
-
-::
-        -C bp.flashloader0.fnameWrite=[filename]
-
-To ensure the model exits on shutdown the following flag must be used:
-
-::
-        -C bp.ve_sysregs.exit_on_shutdown=1
-
-After the model has been shutdown, this file must be fed back in to continue
-the test. Note this flash file includes the FIP image, so the original fip.bin
-does not need to be passed in. The following flag is used:
-
-::
-
-        -C bp.flashloader0.fname=[filename]
-
-Running the FWU tests
-`````````````````````
-
-As previously mentioned in section `Putting it all together`_, there are a
-couple of extra images involved when running the FWU tests. They need to be
-loaded at the right addresses, which depend on the platform.
-
-FVP
-'''
-
-In addition to the usual BL1 and FIP images, the following extra images must be
-loaded:
-
--  ``NS_BL1U`` image at address ``0x0BEB8000`` (i.e. NS_BL1U_BASE macro in TF-A)
--  ``FWU_FIP`` image at address ``0x08400000`` (i.e. NS_BL2U_BASE macro in TF-A)
--  ``Backup FIP`` image at address ``0x09000000`` (i.e. FIP_BKP_ADDRESS macro in
-   TF-A tests).
-
-An example script is provided in `scripts/run_fwu_fvp.sh`_.
-
-Juno
-''''
-
-The same set of extra images and load addresses apply for Juno as for FVP.
-
-The new images must be programmed in flash memory by adding some entries in the
-``SITE1/HBI0262x/images.txt`` configuration file on the Juno SD card (where
-``x`` depends on the revision of the Juno board). Refer to the `Juno Getting
-Started Guide`_, section 2.3 "Flash memory programming" for more
-information. Users should ensure these do not overlap with any other entries in
-the file.
-
-Addresses in this file are expressed as an offset from the base address of the
-flash (that is, ``0x08000000``).
-
-::
-
-    NOR10UPDATE: AUTO                       ; Image Update:NONE/AUTO/FORCE
-    NOR10ADDRESS: 0x00400000                ; Image Flash Address
-    NOR10FILE: \SOFTWARE\fwu_fip.bin        ; Image File Name
-    NOR10LOAD: 00000000                     ; Image Load Address
-    NOR10ENTRY: 00000000                    ; Image Entry Point
-
-    NOR11UPDATE: AUTO                       ; Image Update:NONE/AUTO/FORCE
-    NOR11ADDRESS: 0x03EB8000                ; Image Flash Address
-    NOR11FILE: \SOFTWARE\ns_bl1u.bin        ; Image File Name
-    NOR11LOAD: 00000000                     ; Image Load Address
-    NOR11ENTRY: 00000000                    ; Image Load Address
-
-    NOR12UPDATE: AUTO                       ; Image Update:NONE/AUTO/FORCE
-    NOR12ADDRESS: 0x01000000                ; Image Flash Address
-    NOR12FILE: \SOFTWARE\backup_fip.bin     ; Image File Name
-    NOR12LOAD: 00000000                     ; Image Load Address
-    NOR12ENTRY: 00000000                    ; Image Entry Point
-
---------------
-
-.. [#] Therefore, the Trusted Board Boot feature must be enabled in TF-A for
-       the FWU test images to work. Please refer the `TF-A User guide`_ for
-       further details.
-
-.. [#] Therefore, the Secure Partition Manager must be enabled in TF-A for
-       any of the test Secure Partitions to work. Please refer to the `TF-A User
-       guide`_ for further details.
-
---------------
-
-*Copyright (c) 2018-2020, Arm Limited. All rights reserved.*
-
-.. _Linux master tree: https://github.com/torvalds/linux/tree/master/
-
-.. _TF-A: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about
-.. _Trusted Firmware-A (TF-A): TF-A_
-.. _EL3 payload boot flow: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/user-guide.rst#el3-payloads-alternative-boot-flow
-.. _TF-A User Guide: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/user-guide.rst
-.. _Firmware Update: FWU_
-.. _FWU: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/firmware-update.rst
-.. _FWU state machine: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/firmware-update.rst#fwu-state-machine
-.. _Running the software on FVP: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/user-guide.rst#running-the-software-on-fvp
-.. _Running the software on Juno: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/user-guide.rst#running-the-software-on-juno
-.. _Building FIP images with support for Trusted Board Boot: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/user-guide.rst#building-fip-images-with-support-for-trusted-board-boot
-.. _Secure partition Manager: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/secure-partition-manager-design.rst
-
-.. _EL3 test payload README file: ../el3_payload/README
-.. _scripts/run_fwu_fvp.sh: ../scripts/run_fwu_fvp.sh
-
-.. _ARM Management Mode Interface: http://infocenter.arm.com/help/topic/com.arm.doc.den0060a/DEN0060A_ARM_MM_Interface_Specification.pdf
-.. _Juno Getting Started Guide: http://infocenter.arm.com/help/topic/com.arm.doc.dui0928e/DUI0928E_juno_arm_development_platform_gsg.pdf