diff --git a/docs/change-log.rst b/docs/change-log.rst
new file mode 100644
index 0000000..912a35a
--- /dev/null
+++ b/docs/change-log.rst
@@ -0,0 +1,241 @@
+
+.. section-numbering::
+    :suffix: .
+
+.. contents::
+
+Please note that the Trusted Firmware-A Tests version follows the Trusted
+Firmware-A version for simplicity. At any point in time, TF-A Tests version
+`x.y` aims at testing TF-A version `x.y`. Different versions of TF-A and TF-A
+Tests are not guaranteed to be compatible. This also means that a version
+upgrade on the TF-A-Tests side might not necessarily introduce any new feature.
+
+Trusted Firmware-A Tests - version 2.0
+======================================
+
+New features
+------------
+
+This is the first public release of the Trusted Firmware-A Tests source code.
+
+TFTF
+````
+
+-  Provides a baremetal test framework to exercise TF-A features through its
+   ``SMC`` interface.
+
+-  Integrates easily with TF-A: the TFTF binary is packaged in the FIP image
+   as a ``BL33`` component.
+
+-  Standalone binary that runs on the target without human intervention (except
+   for some specific tests that require a manual target reset).
+
+-  Designed for multi-core testing. The various sub-frameworks allow maximum
+   parallelism in order to stress the firmware.
+
+-  Displays test results on the UART output. This may then be parsed by an
+   external tool and integrated in a continuous integration system.
+
+-  Supports running in AArch64 (NS-EL2 or NS-EL1) and AArch32 states.
+
+-  Supports parsing a tests manifest (XML file) listing the tests to include in
+   the binary.
+
+-  Detects most platform features at run time (e.g. topology, GIC version, ...).
+
+-  Provides a topology enumeration framework. Allows tests to easily go through
+   affinity levels and power domain nodes.
+
+-  Provides an event framework to synchronize CPU operations in a multi-core
+   context.
+
+-  Provides a timer framework. Relies on a single global timer to generate
+   interrupts for all CPUs in the system. This allows tests to easily program
+   interrupts on demand to use as a wake-up event source to come out of CPU
+   suspend state for example.
+
+-  Provides a power-state enumeration framework. Abstracts the valid power
+   states supported on the platform.
+
+-  Provides helper functions for power management operations (CPU hotplug,
+   CPU suspend, system suspend, ...) with proper saving of the hardware state.
+
+-  Supports rebooting the platform at the end of each test for greater
+   independence between tests.
+
+-  Supports interrupting and resuming a test session. This relies on storing
+   test results in non-volatile memory (e.g. flash).
+
+FWU images
+``````````
+
+-  Provides example code to exercise the Firmware Update feature of TF-A.
+
+-  Tests the robustness of the FWU state machine implemented in the TF-A by
+   sending valid and invalid authentication, copy and image execution requests
+   to the TF-A BL1 image.
+
+EL3 test payload
+````````````````
+
+-  Tests the ability of TF-A to load an EL3 payload.
+
+Cactus test secure partition
+````````````````````````````
+
+-  Tests that TF-A has correctly setup the secure partition environment: it
+   should be allowed to perform cache maintenance operations, access floating
+   point registers, etc.
+
+-  Tests the ability of a secure partition to request changing data access
+   permissions and instruction permissions of memory regions it owns.
+
+-  Tests the ability of a secure partition to handle StandaloneMM requests.
+
+Known issues and limitations
+----------------------------
+
+The sections below lists the known issues and limitations of each test image
+provided in this repository.
+
+TFTF
+````
+
+The TFTF test image might be conceptually sub-divided further in 2 parts: the
+tests themselves, and the test framework they are based upon.
+
+Test framework
+''''''''''''''
+
+-  Some stability issues.
+
+-  No mechanism to abort tests when they time out (e.g. this could be
+   implemented using a watchdog).
+
+-  No convenient way to include or exclude tests on a per-platform basis.
+
+-  Power domains and affinity levels are considered equivalent but they may
+   not necessarily be.
+
+-  Need to provide better support to alleviate duplication of test code. There
+   are some recurrent test patterns for which helper functions should be
+   provided. For example, bringing up all CPUs on the platform and executing the
+   same function on all of them, or programming an interrupt and waiting for it
+   to trigger.
+
+-  Every CPU that participates in a test must return from the test function. If
+   it does not - e.g. because it powered itself off for testing purposes - then
+   the test framework will wait forever for this CPU. This limitation is too
+   restrictive for some tests.
+
+-  No protection against interrupted flash operations. If the target is reset
+   while some data is written to flash, the test framework might behave
+   incorrectly on reset.
+
+-  When compiling the code, if the generation of the tests_list.c and/or
+   tests_list.h files fails, the build process is not aborted immediately and
+   will only fail later on.
+
+-  The directory layout is confusing. Most of the test framework code has been
+   moved under the ``tftf/`` directory to better isolate it but this effort is
+   not complete. As a result, there are still some TFTF files scattered around.
+
+Tests
+'''''
+
+-  Some tests are implemented for AArch64 only and are skipped on AArch32.
+
+-  Some tests are not robust enough:
+
+   -  Some tests might hang in some circumstances. For example, they might wait
+      forever for a condition to become true.
+
+   -  Some tests rely on arbitrary time delays instead of proper synchronization
+      when executing order-sensitive steps.
+
+   -  Some tests have been implemented in a practical manner: they seem to work
+      on actual hardware but they make assumptions that are not guaranteed by
+      the Arm architecture. Therefore, they might fail on some other platforms.
+
+-  PSCI stress tests are very unreliable and will often hang. The root cause is
+   not known for sure but this might be due to bad synchronization between CPUs.
+
+-  The GICv2 spurious IRQ test is Juno-specific. In reality, it should only be
+   GICv2-specific. It should be reworked to remove any platform-specific
+   assumption.
+
+-  The GICv2 spurious IRQ test sometimes fails with the following error message:
+
+   ``SMC @ lead CPU returned 0xFFFFFFFF 0x8 0xC``
+
+   The root cause is unknown.
+
+-  The manual tests in AArch32 mode do not work properly. They save some state
+   information into non-volatile memory in order to detect the reset reason but
+   this state does not appear to be retained. As a result, these tests keep
+   resetting infinitely.
+
+-  The FWU tests take a long time to complete. This is because they wait for the
+   watchdog to reset the system. On FVP, TF-A configures the watchdog period to
+   about 4 min. This is way too long in an automated testing context. Besides,
+   the user gets not feedback, which may let them think that the tests are not
+   working properly.
+
+-  The test "Target timer to a power down cpu" sometimes fails with the
+   following error message:
+
+   ``Expected timer switch: 4 Actual: 3``
+
+   The root cause is unknown.
+
+FWU images
+``````````
+
+-  NS-BL1U and NS-BL2U images reuse TFTF-specific code for legacy reasons. This
+   is not a clean design and may cause confusion.
+
+Cactus test secure partition
+````````````````````````````
+
+-  Cactus is experimental code. It's likely to change a lot as the secure
+   partition software architecture evolves.
+
+-  Fails to link with GNU toolchain 7.3.1.
+
+-  Cactus is supported on AArch64 FVP platform only.
+
+All test images
+```````````````
+
+-  TF-A Tests are derived from a fork of TF-A so:
+
+    -  they've got some code in common but lag behind on some features.
+
+    -  there might still be some irrelevant references to TF-A.
+
+-  Some design issues.
+   E.g. TF-A Tests inherited from the I/O layer of TF-A, which still needs a
+   major rework.
+
+-  Cannot build TF-A Tests with Clang. Only GCC is supported.
+
+-  The build system does not cope well with parallel building. The user should
+   not attempt to run multiple jobs in parallel with the ``-j`` option of `GNU
+   make`.
+
+-  The build system does not properly track build options. A clean build must be
+   performed every time a build option changes.
+
+-  SMCCC v2 is not properly supported.
+
+-  UUIDs are not compliant to RFC 4122.
+
+-  No floating point support. The code is compiled with GCC flag
+   ``-mgeneral-regs-only``, which prevents the compiler from generating code
+   that accesses floating point registers. This might limit some test scenarios.
+
+-  The documentation is too lightweight.
+
+--------------
+
+*Copyright (c) 2018, Arm Limited. All rights reserved.*
diff --git a/docs/design.rst b/docs/design.rst
new file mode 100644
index 0000000..a59c1d7
--- /dev/null
+++ b/docs/design.rst
@@ -0,0 +1,266 @@
+Trusted Firmware-A Tests - Design
+=================================
+
+.. section-numbering::
+    :suffix: .
+
+.. contents::
+
+This document provides some details about the internals of the TF-A Tests
+design. It is incomplete at the moment.
+
+Global overview of the TF-A tests behaviour
+-------------------------------------------
+
+The EL3 firmware is expected to hand over to the TF-A tests with all secondary
+cores powered down, i.e. only the primary core should enter the TF-A tests.
+
+The primary CPU initialises the platform and the TF-A tests internal data
+structures.
+
+Then the test session begins. The TF-A tests are executed one after the
+other. Tests results are saved in non-volatile memory as we go along.
+
+Once all tests have completed, a report is generated. The TF-A tests currently
+supports 2 report formats:
+
+-  Raw output, i.e. text messages over serial console.
+
+-  Junit output, i.e. XML file generated over semihosting. This is useful when a
+   post-processing tool needs to parse the test report, as it is more
+   machine-friendly than the raw output.
+
+The report format to use is chosen at build time. For more information,
+refer to the section `Summary of build options`_ in the User Guide.
+
+Global Code Structure
+---------------------
+
+The code is organised into the following categories (present as directories at
+the top level or under the ``tftf/`` directory):
+
+-  **Drivers.**
+
+   Some examples follow, this list might not be exhaustive.
+
+   -  Generic GIC driver.
+
+      ``arm_gic.h`` contains the public APIs that tests might use. Both GIC
+      architecture versions 2 and 3 are supported.
+
+   -  PL011 UART driver.
+
+   -  VExpress NOR flash driver.
+
+      Note that tests are not expected to use this driver in most
+      cases. Instead, they should use the ``tftf_nvm_read()`` and
+      ``tftf_nvm_write()`` wrapper APIs. See definitions in
+      ``tftf/framework/include/nvm.h``. See also the NVM validation test cases
+      (``tftf/tests/framework_validation_tests/test_validation_nvm.c``) for an
+      example of usage of these functions.
+
+   -  SP805 watchdog.
+
+      Used solely to generate an interrupt that will reset the system on purpose
+      (used in ``tftf_plat_reset()``).
+
+   -  SP804 timer.
+
+      This is used as the system timer on Juno. It is configured such that an
+      interrupt is generated when it reaches 0. It is programmed in one-shot
+      mode, i.e. it must be rearmed every time it reaches 0.
+
+-  **Framework.**
+
+   Core features of the test framework.
+
+-  **Library code.**
+
+   Some examples of APIs provided in ``include/lib/`` follow, this list might
+   not be exhaustive.
+
+   -  ``aarch64/``
+
+      Architecture helper functions for e.g. system registers access, cache
+      maintenance operations, MMU configuration, ...
+
+   -  ``events.h``
+
+      Events API. Used to create synchronisation points between CPUs in tests.
+
+   -  ``irq.h``
+
+      IRQ handling support. Used to configure IRQs and register/unregister
+      handlers called upon reception of a specific IRQ.
+
+   -  ``power_management.h``
+
+      Power management operations (CPU ON/OFF, CPU suspend, etc.).
+
+   -  ``sgi.h``
+
+      Software Generated Interrupt support. Used as an inter-CPU communication
+      mechanism.
+
+   -  ``spinlock.h``
+
+      Lightweight implementation of synchronisation locks. Used to prevent
+      concurrent accesses to shared data structures.
+
+   -  ``timer.h``
+
+      Support for programming the timer. Any timer which is in the `always-on`
+      power domain can be used to exit CPUs from suspend state.
+
+   -  ``tftf_lib.h``
+
+      Miscellaneous helper functions/macros: MP-safe ``printf()``, low-level
+      PSCI wrappers, insertion of delays, raw SMC interface, support for writing
+      a string in the test report, macros to skip tests on platforms that do not
+      meet topology requirements, etc.
+
+   -  ``semihosting.h``
+
+      Semihosting support.
+
+   -  ``io_storage.h``
+
+      Low-level IO operations. Tests are not expected to use these APIs
+      directly. They should use higher-level APIs like ``tftf_nvm_read()``
+      and ``tftf_nvm_write()``.
+
+  ``include/stdlib/`` provides standard C library functions (``memcpy()``,
+  ``printf()``, and so on).
+
+-  **Platform specific.**
+
+   Note that ``include/plat/common/plat_topology.h`` provides the interfaces
+   that a platform must implement to support topology discovery (i.e. how many
+   CPUs and clusters there are).
+
+-  **Tests.**
+
+The tests are divided into the following categories (present as directories in
+the ``tftf/tests/`` directory):
+
+-  **Framework validation tests.**
+
+   Tests that exercise the core features of the framework. Verify that the test
+   framework itself works properly.
+
+-  **Runtime services tests.**
+
+   Tests that exercise the runtime services offered by the EL3 Firmware to the
+   Normal World software. For example, this includes tests for the Standard
+   Service (to which PSCI belongs to), the Trusted OS service or the SiP
+   service.
+
+-  **CPU extensions tests.**
+
+   Tests some CPU extensions features. For example, the AMU tests ensure that
+   the counters provided by the Activity Monitor Unit are behaving correctly.
+
+-  **Firmware Update tests.**
+
+   Tests that exercise the `Firmware Update`_ feature of TF-A.
+
+-  **Template tests.**
+
+   Sample test code showing how to write tests in practice. Serves as
+   documentation.
+
+-  **Performance tests.**
+
+   Simple tests measuring the latency of an SMC call.
+
+-  **Miscellaneous tests.**
+
+   Tests for RAS support, correct system setup, ...
+
+All assembler files have the ``.S`` extension. The linker source file has the
+extension ``.ld.S``. This is processed by GCC to create the linker script which
+has the extension ``.ld``.
+
+Detailed Code Structure
+-----------------------
+
+The cold boot entry point is ``tftf_entrypoint`` (see
+``tftf/framework/aarch64/entrypoint.S``). As explained in section `Global
+overview of the TF-A tests behaviour`_, only the primary CPU is expected to
+execute this code.
+
+Tests can power on other CPUs using the function ``tftf_cpu_on()``. This uses
+the PSCI ``CPU_ON`` API of the EL3 Firmware. When entering the Normal World,
+execution starts at the warm boot entry point, which is ``tftf_hotplug_entry()``
+(see ``tftf/framework/aarch64/entrypoint.S``).
+
+Information about the progression of the test session and tests results are
+written into Non-Volatile Memory as we go along. This consists of the following
+data (see struct ``tftf_state_t`` typedef in ``tftf/framework/include/nvm.h``):
+
+-   ``test_to_run``
+
+    Reference to the test to run.
+
+-   ``test_progress``
+
+    Progress in the execution of ``test_to_run``. This is used to implement the
+    following state machine:
+
+::
+
+   +-> TEST_READY (initial state of the test)                  <--------------+
+   |        |                                                                 |
+   |        |  Test framework prepares the test environment.                  |
+   |        |                                                                 |
+   |        v                                                                 |
+   |   TEST_IN_PROGRESS                                                       |
+   |        |                                                                 |
+   |        |  Hand over to the test function.                                |
+   |        |  If the test wants to reboot the platform  ---> TEST_REBOOTING  |
+   |        |                                                       |         |
+   |        |  Test function returns into framework.                | Reboot  |
+   |        |                                                       |         |
+   |        |                                                       +---------+
+   |        v
+   |   TEST_COMPLETE
+   |        |
+   |        |  Do some framework management.
+   |        |  Move to next test.
+   +--------+
+
+-   ``testcase_buffer``
+
+    A buffer that the test can use as a scratch area for whatever it is doing.
+
+-   ``testcase_results``
+
+-   ``result_buffer_size``
+
+-   ``result_buffer``
+
+    Buffer holding the tests output. Tests output are concatenated.
+
+Interrupts management
+---------------------
+
+The TF-A tests expect SGIs #0 to #7 to be available for their own usage. In
+particular, this means that Trusted World software must configure them as
+non-secure interrupts.
+
+SGI #7 has a special status. It is the SGI that the timer management framework
+sends to all CPUs when the system timer fires off (see the definition of the
+constant ``IRQ_WAKE_SGI`` in the header file ``include/lib/irq.h``). Although
+test cases can use this specific SGI - e.g. they can register an IRQ handler for
+it and use it as an inter-CPU communication mechanism - they have to be aware of
+the underlying consequences. Some tests, like the PSCI ``CPU_SUSPEND`` tests,
+rely on this SGI to be enabled in order to wake up CPUs from their suspend
+state. If it is disabled, these tests will leave the system in an unresponsive
+state.
+
+--------------
+
+*Copyright (c) 2018, Arm Limited. All rights reserved.*
+
+.. _Summary of build options: user-guide.html#summary-of-build-options
+.. _Firmware Update: https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/firmware-update.rst
diff --git a/docs/implementing-tests.rst b/docs/implementing-tests.rst
new file mode 100644
index 0000000..f7be284
--- /dev/null
+++ b/docs/implementing-tests.rst
@@ -0,0 +1,128 @@
+How to implement tests
+======================
+
+.. section-numbering::
+    :suffix: .
+
+.. contents::
+
+This document aims at providing some pointers to help implementing new tests in
+the TFTF image.
+
+Structure of a test
+-------------------
+
+A test might be divided into 3 logical parts, detailed in the following
+sections.
+
+Prologue
+''''''''
+
+A test has a main entry point function, whose type is:
+
+::
+
+    typedef test_result_t (*test_function_t)(void);
+
+See `tftf/framework/include/tftf.h`_.
+
+Only the primary CPU enters this function, while other CPUs are powered down.
+
+First of all, the test function should check whether this test is applicable to
+this platform and environment. Some tests rely on specific hardware features or
+firmware capabilities to be present. If these are not available, the test should
+be skipped.  For example, a multi-core test requires at least 2 CPUs to
+run. Macros and functions are provided in `include/common/test_helpers.h`_ to
+help test code verify that their requirements are met.
+
+Core
+''''
+
+This is completely dependent on the purpose of the test. The paragraphs below
+just provide some useful, general information.
+
+The primary CPU may power on other CPUs by calling the function
+``tftf_cpu_on()``.  It provides an address to which secondary CPUs should jump
+to once they have been initialized by the test framework. This address should be
+different from the primary CPU test function.
+
+Synchronization primitives are provided in `include/lib/events.h`_ in case CPUs'
+execution threads need to be synchronized. Most multi-processing tests will need
+some synchronisation points that all/some CPUs need to reach before test
+execution may continue.
+
+Any CPU that is involved in a test must return from its test function. Failure
+to do so will put the framework in an unrecoverable state, see the `TFTF known
+limitations`_. The return code indicates the test result from the point of view
+of this CPU. At the end of the test, individual CPU results are aggregated and
+the overall test result is derived from that. A test is considered as passed if
+all involved CPUs reported a success status code.
+
+Epilogue
+''''''''
+
+Each test is responsible for releasing any allocated resources and putting the
+system back in a clean state when it finishes. Any change to the system
+configuration (e.g. MMU setup, GIC configuration, system registers, ...) must be
+undone and the original configuration must be restored. This guarantees that the
+next test is not affected by the actions of the previous one.
+
+One exception to this rule is that CPUs powered on as part of a test must not be
+powered down. As already stated above, as soon as a CPU enters the test, the
+framework expects it to return from the test.
+
+Template test code
+------------------
+
+Some template test code is provided in `tftf/tests/template_tests`_. It can be
+used as a starting point for developing new tests. Template code for both
+single-core and multi-core tests is provided.
+
+Plugging the test into the build system
+---------------------------------------
+
+All test code is located under the `tftf/tests`_ directory. Tests are usually
+divided into categories represented as sub-directories under ``tftf/tests/``.
+
+The source file implementing the new test code should be added to the
+appropriate tests makefile, see `.*mk` files under `tftf/tests`_.
+
+The new test code should also appear in a tests manifest, see ``*.xml`` files
+under `tftf/tests`_. A unique name and test function must be provided. An
+optional description may be provided as well.
+
+For example, to create a test case named "``Foo test case``", whose test
+function is ``foo()``, add the following line in the tests manifest:
+
+::
+
+    <testcase name="Foo test case" function="foo" />
+
+A testcase must be part of a testsuite. The ``testcase`` XML node above must be
+inside a ``testsuite`` XML node. A unique name and a description must be
+provided for the testsuite.
+
+For example, to create a test suite named "``Bar test suite``", whose
+description is: "``An example test suite``", add the following 2 lines:
+
+::
+
+    <testsuite name="Bar test suite" description="An example test suite">
+    </testsuite>
+
+See the template test manifest for reference: `tftf/tests/tests-template.xml`_.
+
+--------------
+
+*Copyright (c) 2018, Arm Limited. All rights reserved.*
+
+.. _SMC Calling Convention: SMCCC_
+.. _SMCCC: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
+
+.. _TFTF known limitations: change-log.rst#test-framework
+.. _tftf/framework/include/tftf.h: ../tftf/framework/include/tftf.h
+.. _tftf/tests: ../tftf/tests
+.. _tftf/tests/template_tests: ../tftf/tests/template_tests
+.. _tftf/tests/tests-template.xml: ../tftf/tests/tests-template.xml
+.. _include/common/test_helpers.h: ../include/common/test_helpers.h
+.. _include/lib/events.h: ../include/lib/events.h
diff --git a/docs/porting-guide.rst b/docs/porting-guide.rst
new file mode 100644
index 0000000..59d9dba
--- /dev/null
+++ b/docs/porting-guide.rst
@@ -0,0 +1,409 @@
+Trusted Firmware-A Tests - Porting Guide
+========================================
+
+.. section-numbering::
+    :suffix: .
+
+.. contents::
+
+--------------
+
+Introduction
+------------
+
+Please note that this document is incomplete.
+
+Porting the TF-A Tests to a new platform involves making some mandatory and
+optional modifications for both the cold and warm boot paths. Modifications
+consist of:
+
+*   Implementing a platform-specific function or variable,
+*   Setting up the execution context in a certain way, or
+*   Defining certain constants (for example #defines).
+
+The platform-specific functions and variables are all declared in
+``include/plat/common/platform.h``. The framework provides a default
+implementation of variables and functions to fulfill the optional requirements.
+These implementations are all weakly defined; they are provided to ease the
+porting effort. Each platform port can override them with its own implementation
+if the default implementation is inadequate.
+
+Platform requirements
+---------------------
+
+The TF-A Tests rely on the following features to be present on the platform and
+accessible from Normal World.
+
+-  Watchdog
+-  Non-Volatile Memory
+-  System Timer
+
+This also means that a platform port of the TF-A Tests must include software
+drivers for those features.
+
+Mandatory modifications
+-----------------------
+
+File : platform_def.h [mandatory]
+`````````````````````````````````
+
+Each platform must ensure that a header file of this name is in the system
+include path with the following constants defined. This may require updating the
+list of ``PLAT_INCLUDES`` in the ``platform.mk`` file. In the ARM FVP port, this
+file is found in ``plat/arm/board/fvp/include/platform_def.h``.
+
+-  **#define : PLATFORM_LINKER_FORMAT**
+
+   Defines the linker format used by the platform, for example
+   `elf64-littleaarch64` used by the FVP.
+
+-  **#define : PLATFORM_LINKER_ARCH**
+
+   Defines the processor architecture for the linker by the platform, for
+   example `aarch64` used by the FVP.
+
+-  **#define : PLATFORM_STACK_SIZE**
+
+   Defines the stack memory available to each CPU. This constant is used by
+   ``plat/common/aarch64/platform_mp_stack.S``.
+
+-  **#define : PLATFORM_CLUSTER_COUNT**
+
+   Defines the total number of clusters implemented by the platform in the
+   system.
+
+-  **#define : PLATFORM_CORE_COUNT**
+
+   Defines the total number of CPUs implemented by the platform across all
+   clusters in the system.
+
+-  **#define : PLATFORM_NUM_AFFS**
+
+   Defines the total number of nodes in the affinity hierarchy at all affinity
+   levels used by the platform.
+
+-  **#define : PLATFORM_MAX_AFFLVL**
+
+   Defines the maximum number of affinity levels in the system that the platform
+   implements.  ARMv8-A has support for 4 affinity levels. It is likely that
+   hardware will implement fewer affinity levels. For example, the Base AEM FVP
+   implements two clusters with a configurable number of CPUs.  It reports the
+   maximum affinity level as 1.
+
+-  **#define : PLAT_MAX_SPI_OFFSET_ID**
+
+   Defines the offset of the last Shared Peripheral Interrupt supported by the
+   TF-A Tests on this platform. SPI numbers are mapped onto GIC interrupt IDs,
+   starting from interrupt ID 32. In other words, this offset ID corresponds to
+   the last SPI number, to which 32 must be added to get the corresponding last
+   GIC IRQ ID.
+
+   E.g. If ``PLAT_MAX_SPI_OFFSET_ID`` is 10, this means that IRQ #42 is the last
+   SPI.
+
+-  **#define : PLAT_LOCAL_PSTATE_WIDTH**
+
+   Defines the bit-field width of the local state in State-ID field of the
+   power-state parameter. This macro will be used to compose the State-ID field
+   given the local power state at different affinity levels.
+
+-  **#define : PLAT_MAX_PWR_STATES_PER_LVL**
+
+   Defines the maximum number of power states at a power domain level for the
+   platform. This macro will be used by the ``PSCI_STAT_COUNT/RESIDENCY`` tests
+   to determine the size of the array to allocate for storing the statistics.
+
+-  **#define : TFTF_BASE**
+
+   Defines the base address of the TFTF binary in DRAM. Used by the linker
+   script to link the image at the right address. Must be aligned on a page-size
+   boundary.
+
+-  **#define : IRQ_PCPU_NS_TIMER**
+
+   Defines the IRQ ID of the per-CPU Non-Secure timer of the platform.
+
+-  **#define : IRQ_CNTPSIRQ1**
+
+   Defines the IRQ ID of the System timer of the platform.
+
+-  **#define : TFTF_NVM_OFFSET**
+
+   The TFTF needs some Non-Volatile Memory to store persistent data. This
+   defines the offset from the beginning of this memory that the TFTF can use.
+
+-  **#define : TFTF_NVM_SIZE**
+
+   Defines the size of the Non-Volatile Memory allocated for TFTF usage.
+
+If the platform port uses the ARM Watchdog Module (`SP805`_) peripheral, the
+following constant needs to be defined:
+
+-  **#define : SP805_WDOG_BASE**
+
+   Defines the base address of the `SP805`_ watchdog peripheral.
+
+If the platform port uses the IO storage framework, the following constants
+must also be defined:
+
+-  **#define : MAX_IO_DEVICES**
+
+   Defines the maximum number of registered IO devices. Attempting to register
+   more devices than this value using ``io_register_device()`` will fail with
+   ``IO_RESOURCES_EXHAUSTED``.
+
+-  **#define : MAX_IO_HANDLES**
+
+   Defines the maximum number of open IO handles. Attempting to open more IO
+   entities than this value using ``io_open()`` will fail with
+   ``IO_RESOURCES_EXHAUSTED``.
+
+If the platform port uses the VExpress NOR flash driver (see
+``drivers/io/vexpress_nor/``), the following constants must also be defined:
+
+-  **#define : NOR_FLASH_BLOCK_SIZE**
+
+   Defines the largest block size as seen by the software while writing to NOR
+   flash.
+
+Function : tftf_plat_arch_setup() [mandatory]
+`````````````````````````````````````````````
+::
+
+    Argument : void
+    Return   : void
+
+This function performs any platform-specific and architectural setup that the
+platform requires.
+
+In both the ARM FVP and Juno ports, this function configures and enables the
+MMU.
+
+Function : tftf_early_platform_setup() [mandatory]
+``````````````````````````````````````````````````
+
+::
+
+    Argument : void
+    Return   : void
+
+This function executes with the MMU and data caches disabled. It is only called
+by the primary CPU. It is used to perform platform-specific actions very early
+in the boot.
+
+In both the ARM FVP and Juno ports, this function configures the console.
+
+Function : tftf_platform_setup() [mandatory]
+````````````````````````````````````````````
+
+::
+
+    Argument : void
+    Return   : void
+
+This function executes with the MMU and data caches enabled. It is responsible
+for performing any remaining platform-specific setup that can occur after the
+MMU and data cache have been enabled.
+
+This function is also responsible for initializing the storage abstraction layer
+used to access non-volatile memory for permanent storage of test results. It
+also initialises the GIC and detects the platform topology using
+platform-specific means.
+
+Function : plat_get_nvm_handle() [mandatory]
+````````````````````````````````````````````
+
+::
+
+    Argument : uintptr_t *
+    Return   : void
+
+It is needed if the platform port uses IO storage framework. This function is
+responsible for getting the pointer to the initialised non-volatile memory
+entity.
+
+Function : tftf_plat_get_pwr_domain_tree_desc() [mandatory]
+```````````````````````````````````````````````````````````
+
+::
+
+    Argument : void
+    Return   : const unsigned char *
+
+This function returns the platform topology description array in a suitable
+format as expected by TFTF. The size of the array is expected to be
+``PLATFORM_NUM_AFFS - PLATFORM_CORE_COUNT + 1``. The format used to describe
+this array is :
+
+1.  The first entry in the array specifies the number of power domains at the
+    highest power level implemented in the platform. This caters for platforms
+    where the power domain tree does not have a single root node e.g. the FVP
+    which has two cluster power domains at the highest level (that is, 1).
+
+2.  Each subsequent entry corresponds to a power domain and contains the number
+    of power domains that are its direct children.
+
+The array format is the same as the one used by Trusted Firmware-A and more
+details of its description can be found in the Trusted Firmware-A documentation:
+`docs/psci-pd-tree.rst`_.
+
+Function : tftf_plat_get_mpidr() [mandatory]
+````````````````````````````````````````````
+
+::
+
+    Argument : unsigned int
+    Return   : uint64_t
+
+This function converts a given `core_pos` into a valid MPIDR if the CPU is
+present in the platform. The `core_pos` is a unique number less than the
+``PLATFORM_CORE_COUNT`` returned by ``platform_get_core_pos()`` for a given
+CPU. This API is used by the topology framework in TFTF to query the presence of
+a CPU and, if present, returns the corresponding MPIDR for it. If the CPU
+referred to by the `core_pos` is absent, then this function returns
+``INVALID_MPID``.
+
+Function : plat_get_state_prop() [mandatory]
+````````````````````````````````````````````
+
+::
+
+    Argument : unsigned int
+    Return   : const plat_state_prop_t *
+
+This functions returns the ``plat_state_prop_t`` array for all the valid low
+power states from platform for a specified affinity level and returns ``NULL``
+for an invalid affinity level. The array is expected to be NULL-terminated.
+This function is expected to be used by tests that need to compose the power
+state parameter for use in ``PSCI_CPU_SUSPEND`` API or ``PSCI_STAT/RESIDENCY``
+API.
+
+Function : plat_fwu_io_setup() [mandatory]
+``````````````````````````````````````````
+
+::
+
+    Argument : void
+    Return   : void
+
+This function initializes the IO system used by the firmware update.
+
+Function : plat_arm_gic_init() [mandatory]
+``````````````````````````````````````````
+
+::
+
+    Argument : void
+    Return   : void
+
+This function initializes the ARM Generic Interrupt Controller (GIC).
+
+Optional modifications
+----------------------
+
+The following are helper functions implemented by the test framework that
+perform common platform-specific tasks. A platform may choose to override these
+definitions.
+
+Function : platform_get_stack()
+```````````````````````````````
+
+::
+
+    Argument : unsigned long
+    Return   : unsigned long
+
+This function returns the base address of the memory stack that has been
+allocated for the CPU specified by MPIDR. The size of the stack allocated to
+each CPU is specified by the platform defined constant ``PLATFORM_STACK_SIZE``.
+
+Common implementation of this function is provided in
+``plat/common/aarch64/platform_mp_stack.S``.
+
+Function : tftf_platform_end()
+``````````````````````````````
+
+::
+
+    Argument : void
+    Return   : void
+
+This function performs any operation required by the platform to properly finish
+the test session.
+
+The default implementation sends an EOT (End Of Transmission) character on the
+UART. This can be used to automatically shutdown the FVP models. When running on
+real hardware, the UART output may be parsed by an external tool looking for
+this character and rebooting the platform for example.
+
+Function : tftf_plat_reset()
+````````````````````````````
+
+::
+
+    Argument : void
+    Return   : void
+
+This function resets the platform.
+
+The default implementation uses the ARM watchdog peripheral (`SP805`_) to
+generate a watchdog timeout interrupt. This interrupt remains deliberately
+unserviced, which eventually asserts the reset signal.
+
+Function : tftf_platform_setup()
+````````````````````````````````
+
+::
+
+    Argument : void
+    Return   : void
+
+Setup code for platform hardware. The default implementation initializes the IO
+and GIC.
+
+Storage abstraction layer
+-------------------------
+
+In order to improve platform independence and portability a storage abstraction
+layer is used to store test results to non-volatile platform storage.
+
+Each platform should register devices and their drivers via the Storage layer.
+These drivers then need to be initialized in ``tftf_platform_setup()`` function.
+
+It is mandatory to implement at least one storage driver. For the FVP and Juno
+platforms the NOR Flash driver is provided as the default means to store test
+results to storage. The storage layer is described in the header file
+``include/lib/io_storage.h``. The implementation of the common library is in
+``drivers/io/io_storage.c`` and the driver files are located in ``drivers/io/``.
+
+
+Build Flags
+-----------
+
+-  **PLAT_TESTS_SKIP_LIST**
+
+This build flag can be defined by the platform to control exclusion of some
+testcases from the default test plan for a platform. If used this needs to
+point to a text file which follows the following criteria:
+
+  -  Contain a list of tests to skip for this platform.
+
+  -  Specify 1 test per line, using the following format:
+
+     ::
+
+       testsuite_name/testcase_name
+
+     where ``testsuite_name`` and ``testcase_name`` are the names that appear in
+     the XML tests file.
+
+  -  Alternatively, it is possible to disable a test suite entirely, which will
+     disable all test cases part of this test suite. To do so, only specify the
+     test suite name, omitting the ``/testcase_name`` part.
+
+--------------
+
+*Copyright (c) 2018, Arm Limited. All rights reserved.*
+
+.. _docs/psci-pd-tree.rst: https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/psci-pd-tree.rst
+.. _SP805: https://static.docs.arm.com/ddi0270/b/DDI0270.pdf
diff --git a/docs/user-guide.rst b/docs/user-guide.rst
new file mode 100644
index 0000000..b638c68
--- /dev/null
+++ b/docs/user-guide.rst
@@ -0,0 +1,550 @@
+Trusted Firmware-A Tests - User Guide
+=====================================
+
+.. section-numbering::
+    :suffix: .
+
+.. contents::
+
+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
+experience building and running the `Trusted Firmware-A (TF-A)`_.
+
+Host machine requirements
+-------------------------
+
+The minimum recommended machine specification for building the software and
+running the `FVP models`_ is a dual-core processor running at 2GHz with 12GB of
+RAM. For best performance, use a machine with a quad-core processor running at
+2.6GHz with 16GB of RAM.
+
+The software has been tested on Ubuntu 16.04 LTS (64-bit). Packages used for
+building the software were installed from that distribution unless otherwise
+specified.
+
+Tools
+-----
+
+Install the required packages to build TF-A Tests with the following command:
+
+::
+
+    sudo apt-get install build-essential make git perl libxml-libxml-perl
+
+Download and install the GNU cross-toolchain from Linaro. The TF-A Tests have
+been tested with version 6.2-2016.11 (gcc 6.2):
+
+-  `AArch32 GNU cross-toolchain`_
+-  `AArch64 GNU cross-toolchain`_
+
+In addition, the following optional packages and tools may be needed:
+
+-   For debugging, Arm `Development Studio 5 (DS-5)`_.
+
+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-tests.git
+
+Building TF-A Tests
+-------------------
+
+-  Before building TF-A Tests, the environment variable ``CROSS_COMPILE`` must
+   point to the Linaro cross compiler.
+
+   For AArch64:
+
+   ::
+
+       export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
+
+   For AArch32:
+
+   ::
+
+       export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-linux-gnueabihf-
+
+-  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.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.
+
+Cactus test image
+`````````````````
+
+``cactus.bin`` is a test secure partition that exercises the `Secure Partition
+Manager`_ (SPM) in TF-A [#]_. It runs in Secure-EL0. It performs the following
+tasks:
+
+-  Test that TF-A has correctly setup the secure partition environment: Cactus
+   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 Cactus for memory regions the latter owns.
+
+-  Test communication with SPM through the `ARM Management Mode Interface`_.
+
+At the moment, Cactus is supported on AArch64 FVP only. It may be built
+independently of the other test images using the following command:
+
+::
+
+   make PLAT=fvp cactus
+
+In TF-A boot flow, Cactus replaces the ``BL32`` image and should be injected in
+the FIP image.  This might be achieved by running the following command from
+the TF-A root directory:
+
+::
+
+    BL32=cactus.bin make PLAT=fvp fip
+
+Please refer to the `TF-A User guide`_ for further details.
+
+To run the full set of tests in Cactus, it should be used in conjunction with
+the TFTF image, as the latter sends the Management Mode requests that Cactus
+services.
+
+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
+''''''''''''''''''
+
+-  ``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.
+
+-  ``SHELL_COLOR``: Choose whether text messages should use shell's color escape
+   sequences to ease identifying which CPU displays it. If enabled, this makes
+   each CPU write part of the message in a different color. It can take either
+   0 (disabled) or 1 (enabled) as values. 0 is the default.
+
+-  ``TEST_REPORTS``: List of desired test reports. Test reports are described by
+   a space-separated list of colon-separated pairs of report destination and
+   report type. Valid destinations are: 'uart' and 'semihosting'. Valid report
+   types are 'raw' (text output) or 'junit' (XML Junit format). The default is
+   'uart:raw', that is a text report printed on the UART. Here's an example of
+   multiple reports: 'uart:raw semihosting:junit'. The files stored on
+   semihosting are named 'tftf_report_junit.xml' and 'tftf_report_raw.txt'.
+
+-  ``TESTS_FILE``: Path to the XML file listing the tests to run. Default is
+   ``plat/<platform>/tests.xml`` if it exists, otherwise it falls back to
+   ``tftf/tests/tests-common.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.
+
+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 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
+       Cactus to work. Please refer to the `TF-A User guide`_ for further
+       details.
+
+--------------
+
+*Copyright (c) 2018, Arm Limited. All rights reserved.*
+
+.. _Development Studio 5 (DS-5): https://developer.arm.com/products/software-development-tools/ds-5-development-studio
+
+.. _FVP models: https://developer.arm.com/products/system-design/fixed-virtual-platforms
+
+.. _AArch32 GNU cross-toolchain: http://releases.linaro.org/components/toolchain/binaries/6.2-2016.11/arm-linux-gnueabihf/gcc-linaro-6.2.1-2016.11-x86_64_arm-linux-gnueabihf.tar.xz
+.. _AArch64 GNU cross-toolchain: http://releases.linaro.org/components/toolchain/binaries/6.2-2016.11/aarch64-linux-gnu/gcc-linaro-6.2.1-2016.11-x86_64_aarch64-linux-gnu.tar.xz
+
+.. _Linux master tree: https://github.com/torvalds/linux/tree/master/
+
+.. _TF-A: https://www.github.com/ARM-software/arm-trusted-firmware
+.. _Trusted Firmware-A (TF-A): TF-A_
+.. _EL3 payload boot flow: https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/user-guide.rst#el3-payloads-alternative-boot-flow
+.. _TF-A User Guide: https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/user-guide.rst
+.. _Firmware Update: FWU_
+.. _FWU: https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/firmware-update.rst
+.. _FWU state machine: https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/firmware-update.rst#fwu-state-machine
+.. _Running the software on FVP: https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/user-guide.rst#running-the-software-on-fvp
+.. _Running the software on Juno: https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/user-guide.rst#running-the-software-on-juno
+.. _Building FIP images with support for Trusted Board Boot: https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/user-guide.rst#building-fip-images-with-support-for-trusted-board-boot
+.. _Secure partition Manager: https://github.com/ARM-software/arm-trusted-firmware/blob/master/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