doc: Update page content after re-arrangement
This patch modifies the content of existing documents now that
it has been moved around. Some of the content requires updating
to make sense in its new location, for example. Other content may
simply be out of date.
Change-Id: I8dfa527e1d1f1520cefd21066802451352b573d2
Signed-off-by: Paul Beesley <paul.beesley@arm.com>
Signed-off-by: Jimmy Brisson <jimmy.brisson@arm.com>
diff --git a/docs/about/maintainers.rst b/docs/about/maintainers.rst
index 7635383..0f947ae 100644
--- a/docs/about/maintainers.rst
+++ b/docs/about/maintainers.rst
@@ -7,8 +7,8 @@
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
+----------------
- Joanna Farley <joanna.farley@arm.com>
- Sandrine Bailleux <sandrine.bailleux@arm.com>
diff --git a/docs/about/platforms.rst b/docs/about/platforms.rst
index e57cbc9..a83e89b 100644
--- a/docs/about/platforms.rst
+++ b/docs/about/platforms.rst
@@ -1,5 +1,5 @@
-Platforms
-=========
+Platform Support
+================
Juno Arm Development Platform
-----------------------------
@@ -27,8 +27,8 @@
NOTE: Unless otherwise stated, the model version is version 11.6, build 45.
-System Guidance for Infrastructure Fixed Virtual Platforms
-----------------------------------------------------------
+System Guidance for Infrastructure (SGI) Fixed Virtual Platforms
+----------------------------------------------------------------
The AArch64 build has been tested on the following Fixed Virtual Platforms
(`FVP`_):
diff --git a/docs/design.rst b/docs/design.rst
index 5e85d6a..e78cb4c 100644
--- a/docs/design.rst
+++ b/docs/design.rst
@@ -4,8 +4,8 @@
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
--------------------------------------------
+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.
@@ -221,8 +221,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
diff --git a/docs/getting_started/build-options.rst b/docs/getting_started/build-options.rst
index 70ae546..2e608e2 100644
--- a/docs/getting_started/build-options.rst
+++ b/docs/getting_started/build-options.rst
@@ -1,20 +1,20 @@
-Summary of build options
-========================
+Build Options Summary
+=====================
-As much as possible, TF-A Tests dynamically detect the platform hardware
+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. This section lists
-them.
+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 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.
+.. 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.
-Build options shared across test images
-'''''''''''''''''''''''''''''''''''''''
+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
@@ -70,8 +70,8 @@
- ``V``: Verbose build. If assigned anything other than 0, the build commands
are printed. Default is 0.
-TFTF build options
-''''''''''''''''''
+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.
@@ -97,10 +97,14 @@
(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
-'''''''''''''''''''''''''''''
+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/obtain.rst b/docs/getting_started/obtain.rst
index 1c4183d..cffab2d 100644
--- a/docs/getting_started/obtain.rst
+++ b/docs/getting_started/obtain.rst
@@ -1,5 +1,5 @@
-Getting the TF-A Tests source code
-==================================
+Obtaining Source Code
+=====================
Download the TF-A Tests source code using the following command:
diff --git a/docs/getting_started/run.rst b/docs/getting_started/run.rst
index f9489e2..fcb0bb8 100644
--- a/docs/getting_started/run.rst
+++ b/docs/getting_started/run.rst
@@ -1,5 +1,5 @@
-Running the TF-A Tests
-======================
+Running 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
@@ -26,8 +26,9 @@
- ``BL32`` (optional);
- ``tftf.bin`` (standing as the BL33 image).
-Running the manual tests on FVP
-```````````````````````````````
+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.
@@ -50,15 +51,15 @@
-C bp.flashloader0.fname=[filename]
-Running the FWU tests
-`````````````````````
+Running Firmware Update (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
-'''
+On FVP
+^^^^^^
In addition to the usual BL1 and FIP images, the following extra images must be
loaded:
@@ -70,8 +71,8 @@
An example script is provided in `scripts/run_fwu_fvp.sh`_.
-Juno
-''''
+On Juno
+^^^^^^^
The same set of extra images and load addresses apply for Juno as for FVP.
diff --git a/docs/implementing-tests.rst b/docs/implementing-tests.rst
index 3810c14..decdc68 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:
@@ -31,7 +31,7 @@
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.
@@ -54,7 +54,7 @@
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,15 +66,15 @@
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
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
divided into categories represented as sub-directories under ``tftf/tests/``.
diff --git a/docs/porting/mandatory-mods.rst b/docs/porting/mandatory-mods.rst
index 4f11324..dd4242f 100644
--- a/docs/porting/mandatory-mods.rst
+++ b/docs/porting/mandatory-mods.rst
@@ -1,8 +1,8 @@
-Mandatory modifications
------------------------
+Mandatory Modifications
+=======================
-File : platform_def.h [mandatory]
-`````````````````````````````````
+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
@@ -123,8 +123,8 @@
Defines the largest block size as seen by the software while writing to NOR
flash.
-Function : tftf_plat_arch_setup() [mandatory]
-`````````````````````````````````````````````
+Function : tftf_plat_arch_setup()
+---------------------------------
::
Argument : void
@@ -136,8 +136,8 @@
In both the ARM FVP and Juno ports, this function configures and enables the
MMU.
-Function : tftf_early_platform_setup() [mandatory]
-``````````````````````````````````````````````````
+Function : tftf_early_platform_setup()
+--------------------------------------
::
@@ -150,8 +150,8 @@
In both the ARM FVP and Juno ports, this function configures the console.
-Function : tftf_platform_setup() [mandatory]
-````````````````````````````````````````````
+Function : tftf_platform_setup()
+--------------------------------
::
@@ -167,8 +167,8 @@
also initialises the GIC and detects the platform topology using
platform-specific means.
-Function : plat_get_nvm_handle() [mandatory]
-````````````````````````````````````````````
+Function : plat_get_nvm_handle()
+--------------------------------
::
@@ -179,8 +179,8 @@
responsible for getting the pointer to the initialised non-volatile memory
entity.
-Function : tftf_plat_get_pwr_domain_tree_desc() [mandatory]
-```````````````````````````````````````````````````````````
+Function : tftf_plat_get_pwr_domain_tree_desc()
+-----------------------------------------------
::
@@ -204,8 +204,8 @@
details of its description can be found in the Trusted Firmware-A documentation:
`docs/psci-pd-tree.rst`_.
-Function : tftf_plat_get_mpidr() [mandatory]
-````````````````````````````````````````````
+Function : tftf_plat_get_mpidr()
+--------------------------------
::
@@ -220,8 +220,8 @@
referred to by the `core_pos` is absent, then this function returns
``INVALID_MPID``.
-Function : plat_get_state_prop() [mandatory]
-````````````````````````````````````````````
+Function : plat_get_state_prop()
+--------------------------------
::
@@ -235,8 +235,8 @@
state parameter for use in ``PSCI_CPU_SUSPEND`` API or ``PSCI_STAT/RESIDENCY``
API.
-Function : plat_fwu_io_setup() [mandatory]
-``````````````````````````````````````````
+Function : plat_fwu_io_setup()
+------------------------------
::
@@ -245,8 +245,8 @@
This function initializes the IO system used by the firmware update.
-Function : plat_arm_gic_init() [mandatory]
-``````````````````````````````````````````
+Function : plat_arm_gic_init()
+------------------------------
::
@@ -255,8 +255,8 @@
This function initializes the ARM Generic Interrupt Controller (GIC).
-Function : platform_get_core_pos() [mandatory]
-``````````````````````````````````````````````
+Function : platform_get_core_pos()
+----------------------------------
::
@@ -265,8 +265,8 @@
This function returns a linear core ID from a MPID.
-Function : plat_crash_console_init() [mandatory]
-````````````````````````````````````````````````
+Function : plat_crash_console_init()
+------------------------------------
::
@@ -275,8 +275,8 @@
This function initializes a platform-specific console for crash reporting.
-Function : plat_crash_console_putc() [mandatory]
-````````````````````````````````````````````````
+Function : plat_crash_console_putc()
+------------------------------------
::
@@ -285,8 +285,8 @@
This function prints a character on the platform-specific crash console.
-Function : plat_crash_console_flush() [mandatory]
-`````````````````````````````````````````````````
+Function : plat_crash_console_flush()
+-------------------------------------
::
diff --git a/docs/porting/optional-mods.rst b/docs/porting/optional-mods.rst
index 8bee341..a88d682 100644
--- a/docs/porting/optional-mods.rst
+++ b/docs/porting/optional-mods.rst
@@ -1,4 +1,4 @@
-Optional modifications
+Optional Modifications
======================
The following are helper functions implemented by the test framework that
@@ -6,7 +6,7 @@
definitions.
Function : platform_get_stack()
-```````````````````````````````
+-------------------------------
::
@@ -21,7 +21,7 @@
``plat/common/aarch64/platform_mp_stack.S``.
Function : tftf_platform_end()
-``````````````````````````````
+------------------------------
::
@@ -37,7 +37,7 @@
this character and rebooting the platform for example.
Function : tftf_plat_reset()
-````````````````````````````
+----------------------------
::
diff --git a/docs/porting/requirements.rst b/docs/porting/requirements.rst
index 158b4b8..0a00592 100644
--- a/docs/porting/requirements.rst
+++ b/docs/porting/requirements.rst
@@ -1,4 +1,4 @@
-Platform requirements
+Platform Requirements
=====================
The TF-A Tests rely on the following features to be present on the platform and
diff --git a/docs/porting/storage.rst b/docs/porting/storage.rst
index 6074358..1317e7d 100644
--- a/docs/porting/storage.rst
+++ b/docs/porting/storage.rst
@@ -1,17 +1,21 @@
-Storage abstraction layer
+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.
+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.
-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/``.
+.. 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/``.
--------------