Merge changes from topic "sphinx-doc"
* changes:
doc: Update link formats
doc: Update page content after re-arrangement
doc: Sync common content with TF-A
doc: Move content from Porting Guide
doc: Migrate content from User Guide and update it
doc: Move tools info to Getting Started chapter
doc: Move content to new About chapter
doc: Copy readme content to docs/index.rst
diff --git a/docs/about/contact.rst b/docs/about/contact.rst
new file mode 100644
index 0000000..a84dc52
--- /dev/null
+++ b/docs/about/contact.rst
@@ -0,0 +1,33 @@
+Support & Contact
+=================
+
+We welcome any feedback on TF-A Tests and there are several methods for
+providing it or for obtaining support.
+
+Mailing Lists
+^^^^^^^^^^^^^
+
+Public mailing lists for TF-A Tests and the wider Trusted Firmware project are
+hosted on TrustedFirmware.org. The mailing lists can be used for general
+enquiries, enhancement requests and issue reports, or to follow and participate
+in technical or organizational discussions around the project. These discussions
+include design proposals, advance notice of changes and upcoming events.
+
+The relevant list for the TF-A Tests project is `TF-A-Tests development`_
+
+You can see a `summary of all the lists`_ on the TrustedFirmware.org website.
+
+Issue Tracker
+^^^^^^^^^^^^^
+
+Specific issues may be raised using the `issue tracker`_ on the
+TrustedFirmware.org website. Using this tracker makes it easy for the
+maintainers to prioritise and respond to your ticket.
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
+
+.. _`issue tracker`: https://developer.trustedfirmware.org
+.. _`TF-A-Tests development`: https://lists.trustedfirmware.org/pipermail/tf-a-tests/
+.. _`summary of all the lists`: https://lists.trustedfirmware.org
diff --git a/docs/about/features.rst b/docs/about/features.rst
new file mode 100644
index 0000000..b6fc2d0
--- /dev/null
+++ b/docs/about/features.rst
@@ -0,0 +1,57 @@
+Feature Overview
+================
+
+This page provides an overview of the current TF-A Tests feature set. The
+:ref:`Change Log & Release Notes` document provides details of changes made
+since the last release.
+
+Current Features
+----------------
+
+The following TF-A features are currently tested to some extent (this list is
+not exhaustive):
+
+- `SMC Calling Convention`_
+- `Power State Coordination Interface (PSCI)`_
+- `Software Delegated Exception Interface (SDEI)`_
+- `Performance Measurement Framework (PMF)`_
+- Communication and interaction with the `Test Secure Payload (TSP)`_
+- `Firmware update`_ (or recovery mode)
+- `EL3 payload boot flow`_
+- Secure partition support
+
+These tests are not a compliance test suite for the Arm interface standards used
+in TF-A (such as PSCI).
+
+They do not cover 100% of the TF-A code. The fact that all tests pass does not
+mean that TF-A is free of bugs.
+
+They are not reference code. They should not be considered as the official way
+to test hardware/firmware features. Instead, they are provided as example code
+to experiment with and improve on.
+
+Still to come
+-------------
+
+- Additional tests
+- Support for new platforms
+- Design improvements
+- Stability improvements
+- Enhancements to the test framework to make it easier to implement tests
+- Fixes for known issues (detailed in :ref:`Change Log & Release Notes`)
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
+
+.. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
+.. _Power State Coordination Interface (PSCI): PSCI_
+.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
+.. _Software Delegated Exception Interface (SDEI): SDEI_
+.. _SDEI: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf
+.. _Performance Measurement framework (PMF): PMF_
+.. _PMF: https://trustedfirmware-a.readthedocs.io/en/latest/design/firmware-design.html#performance-measurement-framework
+.. _Test Secure Payload (TSP): TSP_
+.. _TSP: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/tree/bl32/tsp
+.. _Firmware update: https://trustedfirmware-a.readthedocs.io/en/latest/components/firmware-update.html
+.. _EL3 payload boot flow: https://trustedfirmware-a.readthedocs.io/en/latest/design/alt-boot-flows.html#el3-payloads-alternative-boot-flow
diff --git a/docs/about/index.rst b/docs/about/index.rst
new file mode 100644
index 0000000..21a9ac5
--- /dev/null
+++ b/docs/about/index.rst
@@ -0,0 +1,14 @@
+About
+=====
+
+.. toctree::
+ :maxdepth: 1
+
+ features
+ platforms
+ maintainers
+ contact
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/maintainers.rst b/docs/about/maintainers.rst
similarity index 64%
rename from maintainers.rst
rename to docs/about/maintainers.rst
index def3338..0f947ae 100644
--- a/maintainers.rst
+++ b/docs/about/maintainers.rst
@@ -1,5 +1,5 @@
-Trusted Firmware-A Tests maintainers
-====================================
+Maintainers
+===========
Trusted Firmware-A Tests (TF-A Tests) is a community maintained project. All
contributions are ultimately merged by the maintainers listed below.
@@ -7,15 +7,13 @@
Please note the maintainers' bandwidth is limited and contributions to this
project will be reviewed and handled on a best-effort basis.
-Maintainers
------------
+Maintainers List
+----------------
-- Dimitris Papastamos <dimitris.papastamos@arm.com>
- Joanna Farley <joanna.farley@arm.com>
-- Roberto Vargas <roberto.vargas@arm.com>
- Sandrine Bailleux <sandrine.bailleux@arm.com>
- Soby Mathew <soby.mathew@arm.com>
--------------
-*Copyright (c) 2018, Arm Limited. All rights reserved.*
+*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*
diff --git a/docs/about/platforms.rst b/docs/about/platforms.rst
new file mode 100644
index 0000000..a83e89b
--- /dev/null
+++ b/docs/about/platforms.rst
@@ -0,0 +1,48 @@
+Platform Support
+================
+
+Juno Arm Development Platform
+-----------------------------
+
+The AArch64 build of this release has been tested on variants r0, r1 and r2 of
+the `Juno Arm Development Platform`_. The AArch32 build has only been tested on
+variant r0.
+
+Armv8 Architecture Fixed Virtual Platforms
+------------------------------------------
+
+The AArch64 build has been tested on the following Armv8 Architecture Fixed
+Virtual Platforms (`FVP`_):
+
+- ``FVP_Base_AEMv8A-AEMv8A``
+- ``FVP_Base_Cortex-A35x4``
+- ``FVP_Base_Cortex-A57x4-A53x4``
+- ``FVP_Base_RevC-2xAEMv8A``
+- ``Foundation_Platform``
+
+The AArch32 build has been tested on the following `FVP`_\ s:
+
+- ``FVP_Base_Cortex-A32x4``
+- ``FVP_Base_RevC-2xAEMv8A``
+
+NOTE: Unless otherwise stated, the model version is version 11.6, build 45.
+
+System Guidance for Infrastructure (SGI) Fixed Virtual Platforms
+----------------------------------------------------------------
+
+The AArch64 build has been tested on the following Fixed Virtual Platforms
+(`FVP`_):
+
+- ``FVP_CSS_SGI-575``
+- ``FVP_RD_N1Edge``
+
+NOTE:
+
+- For ``FVP_CSS_SGI-575`` and ``FVP_RD_N1Edge``, internal version of the
+ models were used.
+
+--------------
+
+*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..e900efe 100644
--- a/docs/design.rst
+++ b/docs/design.rst
@@ -1,11 +1,13 @@
-Design
-======
+Framework Design
+================
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
--------------------------------------------
+.. _design_high_level_behaviour:
+
+High-Level 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.
@@ -165,8 +167,8 @@
-----------------------
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
+``tftf/framework/aarch64/entrypoint.S``). As explained in
+:ref:`design_high_level_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
@@ -221,8 +223,8 @@
Buffer holding the tests output. Tests output are concatenated.
-Interrupts management
----------------------
+Interrupt 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
@@ -242,5 +244,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
+.. _Firmware update: https://trustedfirmware-a.readthedocs.io/en/latest/components/firmware-update.html
diff --git a/docs/getting_started/build-options.rst b/docs/getting_started/build-options.rst
new file mode 100644
index 0000000..2e608e2
--- /dev/null
+++ b/docs/getting_started/build-options.rst
@@ -0,0 +1,110 @@
+Build Options Summary
+=====================
+
+As far as possible, TF-A Tests dynamically detects the platform hardware
+components and available features. There are a few build options to select
+specific features where the dynamic detection falls short.
+
+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::
+ 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.
+
+Common (Shared) Build Options
+-----------------------------
+
+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-specific 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-specific 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.
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/build.rst b/docs/getting_started/build.rst
new file mode 100644
index 0000000..f137afe
--- /dev/null
+++ b/docs/getting_started/build.rst
@@ -0,0 +1,289 @@
+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
+ `TF-A documentation`_ 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 documentation`_ 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
+
+.. _build_putting_together:
+
+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 documentation`_.
+
+- ``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 documentation`_ 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 documentation`_ 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 documentation`_ for further details.
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
+
+.. _EL3 test payload README file: https://git.trustedfirmware.org/TF-A/tf-a-tests.git/tree/el3_payload/README
+.. _ARM Management Mode Interface: http://infocenter.arm.com/help/topic/com.arm.doc.den0060a/DEN0060A_ARM_MM_Interface_Specification.pdf
+.. _TF-A documentation: https://trustedfirmware-a.readthedocs.org
+.. _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
diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst
new file mode 100644
index 0000000..a956efb
--- /dev/null
+++ b/docs/getting_started/index.rst
@@ -0,0 +1,21 @@
+Getting Started
+===============
+
+.. toctree::
+ :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
+experience building and running `Trusted Firmware-A (TF-A)`_.
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
+
+.. _Trusted Firmware-A (TF-A): https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
diff --git a/docs/getting_started/obtain.rst b/docs/getting_started/obtain.rst
new file mode 100644
index 0000000..cffab2d
--- /dev/null
+++ b/docs/getting_started/obtain.rst
@@ -0,0 +1,12 @@
+Obtaining 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/requirements.rst b/docs/getting_started/requirements.rst
new file mode 100644
index 0000000..3d06d98
--- /dev/null
+++ b/docs/getting_started/requirements.rst
@@ -0,0 +1,42 @@
+Prerequisites & Requirements
+============================
+
+This document describes the software and hardware requiremnts for building TF-A
+Tests for AArch32 and AArch64 target platforms.
+
+It may be possible to build TF-A Tests with combinations of software and
+hardware that are different from those listed below. The software and hardware
+described in this document are officially supported.
+
+Build Host
+----------
+
+TF-A Tests may be built using a Linux build host machine with a recent Linux
+distribution. We have performed tests using Ubuntu 16.04 LTS (64-bit), but other
+distributions should also work fine, provided that the tools and libraries
+can be installed.
+
+Toolchain
+---------
+
+Install the required packages to build TF-A Tests with the following command:
+
+::
+
+ sudo apt-get install device-tree-compiler 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 9.2-2019.12 (gcc 9.2):
+
+- `GCC cross-toolchain`_
+
+In addition, the following optional packages and tools may be needed:
+
+- For debugging, Arm `Development Studio 5 (DS-5)`_.
+
+.. _GCC cross-toolchain: https://developer.arm.com/open-source/gnu-toolchain/gnu-a/downloads
+.. _Development Studio 5 (DS-5): https://developer.arm.com/products/software-development-tools/ds-5-development-studio
+
+--------------
+
+*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..0fe27d8
--- /dev/null
+++ b/docs/getting_started/run.rst
@@ -0,0 +1,114 @@
+Running Tests
+=============
+
+Refer to the `Juno and FVP platform documentation`_ in the `TF-A documentation`.
+The same instructions mostly apply to running the TF-A Tests on those two
+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 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 Firmware Update (FWU) Tests
+-----------------------------------
+
+As previously mentioned in :ref:`build_putting_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.
+
+On 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``.
+
+On 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.*
+
+.. _Juno Getting Started Guide: http://infocenter.arm.com/help/topic/com.arm.doc.dui0928e/DUI0928E_juno_arm_development_platform_gsg.pdf
+.. _Juno and FVP platform documentation: https://trustedfirmware-a.readthedocs.io/en/latest/plat/
+.. _TF-A documentation: https://trustedfirmware-a.readthedocs.org
diff --git a/docs/implementing-tests.rst b/docs/implementing-tests.rst
index 3810c14..e72a277 100644
--- a/docs/implementing-tests.rst
+++ b/docs/implementing-tests.rst
@@ -4,14 +4,14 @@
This document aims at providing some pointers to help implementing new tests in
the TFTF image.
-Structure of a test
--------------------
+Test Structure
+--------------
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:
@@ -19,19 +19,19 @@
typedef test_result_t (*test_function_t)(void);
-See `tftf/framework/include/tftf.h`_.
+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
+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.
@@ -41,20 +41,21 @@
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'
+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.
+to do so will put the framework in an unrecoverable state, see the
+:ref:`Change Log & Release Notes` for details on this and other 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
@@ -66,24 +67,24 @@
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
+Template Test Code
------------------
-Some template test code is provided in `tftf/tests/template_tests`_. It can be
+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
----------------------------------------
+Build System Integration
+------------------------
-All test code is located under the `tftf/tests`_ directory. Tests are usually
+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`_.
+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
+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
@@ -105,7 +106,7 @@
<testsuite name="Bar test suite" description="An example test suite">
</testsuite>
-See the template test manifest for reference: `tftf/tests/tests-template.xml`_.
+See the template test manifest for reference: ``tftf/tests/tests-template.xml``.
--------------
@@ -113,11 +114,3 @@
.. _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/index.rst b/docs/index.rst
index 29b25d5..4869af1 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -6,13 +6,44 @@
:hidden:
Home<self>
- user-guide
- porting-guide
- implementing-tests
+ about/index
+ getting_started/index
+ process/index
design
+ implementing-tests
+ porting/index
change-log
license
+The Trusted Firmware-A Tests (TF-A-Tests) is a suite of baremetal tests to
+exercise the `Trusted Firmware-A (TF-A)`_ features from the Normal World. It
+enables strong TF-A functional testing without dependency on a Rich OS. It
+mainly interacts with TF-A through its SMC interface.
+
+It provides a basis for TF-A developers to validate their own platform ports and
+add their own test cases.
+
+Getting started
+---------------
+
+Get the TF-A Tests source code from `trustedfirmware.org`_.
+
+See content under the *Getting Started* chapter for instructions on how to
+install, build and use the TF-A Tests.
+
+See :ref:`Framework Design` for information on how the TF-A Tests work
+internally.
+
+See content under the *Porting* chapter for information about how to use this
+software on another Armv8-A platform.
+
+See content under the *Process* chapter for information on how to contribute to
+this project.
+
--------------
*Copyright (c)2019, Arm Limited. All rights reserved.*
+
+.. _Juno Arm Development Platform: https://developer.arm.com/products/system-design/development-boards/juno-development-board
+.. _trustedfirmware.org: https://git.trustedfirmware.org/TF-A/tf-a-tests.git
+.. _Trusted Firmware-A (TF-A): https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
diff --git a/docs/license.rst b/docs/license.rst
index 46124fc..3e940c8 100644
--- a/docs/license.rst
+++ b/docs/license.rst
@@ -1,9 +1,7 @@
License
=======
-The software is provided under a BSD-3-Clause `license`_. Contributions to this
-project are accepted under the same license with developer sign-off as
-described in the `Contributing Guidelines`_.
+The software is provided under a BSD-3-Clause license.
::
diff --git a/docs/porting-guide.rst b/docs/porting-guide.rst
deleted file mode 100644
index ba9b9aa..0000000
--- a/docs/porting-guide.rst
+++ /dev/null
@@ -1,432 +0,0 @@
-Porting Guide
-=============
-
-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).
-
-Function : platform_get_core_pos() [mandatory]
-``````````````````````````````````````````````
-
-::
-
- Argument : u_register_t
- Return : unsigned int
-
-This function returns a linear core ID from a MPID.
-
-Function : plat_crash_console_init() [mandatory]
-````````````````````````````````````````````````
-
-::
-
- Argument : void
- Return : int
-
-This function initializes a platform-specific console for crash reporting.
-
-Function : plat_crash_console_putc() [mandatory]
-````````````````````````````````````````````````
-
-::
-
- Argument : int
- Return : int
-
-This function prints a character on the platform-specific crash console.
-
-Function : plat_crash_console_flush() [mandatory]
-`````````````````````````````````````````````````
-
-::
-
- Argument : void
- Return : int
-
-This function waits until all the characters of the platform-specific crash
-console have been actually printed.
-
-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.
-
-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-2019, Arm Limited. All rights reserved.*
-
-.. _docs/psci-pd-tree.rst: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/psci-pd-tree.rst
-.. _SP805: https://static.docs.arm.com/ddi0270/b/DDI0270.pdf
diff --git a/docs/porting/build-flags.rst b/docs/porting/build-flags.rst
new file mode 100644
index 0000000..7f9854d
--- /dev/null
+++ b/docs/porting/build-flags.rst
@@ -0,0 +1,31 @@
+Build Flags
+===========
+
+The platform may define build flagsto to control inclusion or exclusion of
+certain tests. These flags must be defined in the platform makefile which
+is included by the build system.
+
+- **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) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/porting/index.rst b/docs/porting/index.rst
new file mode 100644
index 0000000..2f39ea2
--- /dev/null
+++ b/docs/porting/index.rst
@@ -0,0 +1,30 @@
+Porting
+=======
+
+.. toctree::
+ :maxdepth: 1
+
+ requirements
+ storage
+ build-flags
+ mandatory-mods
+ optional-mods
+
+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.
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/porting/mandatory-mods.rst b/docs/porting/mandatory-mods.rst
new file mode 100644
index 0000000..7b94568
--- /dev/null
+++ b/docs/porting/mandatory-mods.rst
@@ -0,0 +1,304 @@
+Mandatory Modifications
+=======================
+
+File : platform_def.h
+---------------------
+
+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()
+---------------------------------
+::
+
+ 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()
+--------------------------------------
+
+::
+
+ 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()
+--------------------------------
+
+::
+
+ 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()
+--------------------------------
+
+::
+
+ 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()
+-----------------------------------------------
+
+::
+
+ 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`_.
+
+Function : tftf_plat_get_mpidr()
+--------------------------------
+
+::
+
+ 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()
+--------------------------------
+
+::
+
+ 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()
+------------------------------
+
+::
+
+ Argument : void
+ Return : void
+
+This function initializes the IO system used by the firmware update.
+
+Function : plat_arm_gic_init()
+------------------------------
+
+::
+
+ Argument : void
+ Return : void
+
+This function initializes the ARM Generic Interrupt Controller (GIC).
+
+Function : platform_get_core_pos()
+----------------------------------
+
+::
+
+ Argument : u_register_t
+ Return : unsigned int
+
+This function returns a linear core ID from a MPID.
+
+Function : plat_crash_console_init()
+------------------------------------
+
+::
+
+ Argument : void
+ Return : int
+
+This function initializes a platform-specific console for crash reporting.
+
+Function : plat_crash_console_putc()
+------------------------------------
+
+::
+
+ Argument : int
+ Return : int
+
+This function prints a character on the platform-specific crash console.
+
+Function : plat_crash_console_flush()
+-------------------------------------
+
+::
+
+ Argument : void
+ Return : int
+
+This function waits until all the characters of the platform-specific crash
+console have been actually printed.
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
+
+.. _SP805: https://static.docs.arm.com/ddi0270/b/DDI0270.pdf
+.. _Trusted Firmware-A documentation: https://trustedfirmware-a.readthedocs.io/en/latest/design/psci-pd-tree.html#psci-power-domain-tree-structure
diff --git a/docs/porting/optional-mods.rst b/docs/porting/optional-mods.rst
new file mode 100644
index 0000000..a88d682
--- /dev/null
+++ b/docs/porting/optional-mods.rst
@@ -0,0 +1,57 @@
+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.
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
+
+.. _SP805: https://static.docs.arm.com/ddi0270/b/DDI0270.pdf
diff --git a/docs/porting/requirements.rst b/docs/porting/requirements.rst
new file mode 100644
index 0000000..0a00592
--- /dev/null
+++ b/docs/porting/requirements.rst
@@ -0,0 +1,16 @@
+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.
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/porting/storage.rst b/docs/porting/storage.rst
new file mode 100644
index 0000000..1317e7d
--- /dev/null
+++ b/docs/porting/storage.rst
@@ -0,0 +1,22 @@
+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 using the ``tftf_platform_setup()``
+function.
+
+.. warning::
+ 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/``.
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
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 8f67841..0000000
--- a/docs/user-guide.rst
+++ /dev/null
@@ -1,608 +0,0 @@
-User Guide
-==========
-
-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 device-tree-compiler build-essential make git perl libxml-libxml-perl
-
-Download and install the GNU cross-toolchain from developer.arm.com portal. The
-TF-A Tests have been tested with version 9.2-2019.12 (gcc 9.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/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.*
-
-.. _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: https://developer.arm.com/-/media/Files/downloads/gnu-a/9.2-2019.12/binrel/gcc-arm-9.2-2019.12-x86_64-arm-none-eabi.tar.xz
-.. _AArch64 GNU cross-toolchain: https://developer.arm.com/-/media/Files/downloads/gnu-a/9.2-2019.12/binrel/gcc-arm-9.2-2019.12-x86_64-aarch64-none-elf.tar.xz
-
-.. _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
diff --git a/readme.rst b/readme.rst
index 5d57910..cb2d564 100644
--- a/readme.rst
+++ b/readme.rst
@@ -131,13 +131,6 @@
See the `Contributing Guidelines`_ for information on how to contribute to this
project.
-
-Contact us
-----------
-
-We welcome any feedback on TF-A Tests. You can use either the `issue tracker`_
-or our `mailing list`_.
-
--------------
*Copyright (c) 2018-2020, Arm Limited. All rights reserved.*
@@ -148,14 +141,9 @@
.. _Design Guide: docs/design.rst
.. _Porting Guide: docs/porting-guide.rst
.. _User Guide: docs/user-guide.rst
-
.. _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
-.. _FreeBSD: http://www.freebsd.org
-.. _SCC: http://www.simple-cc.org/
-.. _LLVM compiler-rt: https://compiler-rt.llvm.org/
-
.. _Power State Coordination Interface (PSCI): PSCI_
.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
.. _Software Delegated Exception Interface (SDEI): SDEI_