doc: Update link formats
Use docutils/Sphinx-type linking with the :ref: keyword where
possible, instead of direct links to files.
As part of this patch some external links have been updated too,
especially those that point to the TF-A docs. Some link targets
are no longer valid but can be restored after the TF-A User Guide
is split up.
Change-Id: I328d5141cf9b32471bf669bfc0191e8f6f883a48
Signed-off-by: Paul Beesley <paul.beesley@arm.com>
Signed-off-by: Jimmy Brisson <jimmy.brisson@arm.com>
diff --git a/docs/about/features.rst b/docs/about/features.rst
index 2b810ce..b6fc2d0 100644
--- a/docs/about/features.rst
+++ b/docs/about/features.rst
@@ -17,8 +17,8 @@
- `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
+- `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).
@@ -43,3 +43,15 @@
--------------
*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/design.rst b/docs/design.rst
index e78cb4c..e900efe 100644
--- a/docs/design.rst
+++ b/docs/design.rst
@@ -4,6 +4,8 @@
This document provides some details about the internals of the TF-A Tests
design. It is incomplete at the moment.
+.. _design_high_level_behaviour:
+
High-Level Behaviour
--------------------
@@ -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
@@ -242,4 +244,4 @@
*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*
-.. _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.rst b/docs/getting_started/build.rst
index cb8d358..f137afe 100644
--- a/docs/getting_started/build.rst
+++ b/docs/getting_started/build.rst
@@ -33,7 +33,7 @@
Notes:
- If ``PLAT`` is not specified, ``fvp`` is assumed by default. See the
- `Summary of build options`_ for more information on available build
+ `TF-A documentation`_ for more information on available build
options.
- By default this produces a release version of the build. To produce a
@@ -101,17 +101,17 @@
BL33=tftf.bin make PLAT=<platform> fip
-Please refer to the `TF-A User guide`_ for further details.
+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`.
+``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
+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
@@ -158,6 +158,8 @@
make PLAT=<platform> ns_bl2u
+.. _build_putting_together:
+
Putting it all together
'''''''''''''''''''''''
@@ -180,8 +182,8 @@
- ``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.
+ 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`_.
@@ -197,15 +199,15 @@
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
+``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
+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
@@ -265,30 +267,23 @@
-i path/to/cactus.bin:path/to/cactus.dtb \
-i path/to/ivy.bin:path/to/ivy.dtb
-Please refer to the `TF-A User guide`_ for further details.
+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 User guide`_ 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 User
- guide`_ for further details.
+ 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 payload boot flow: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/user-guide.rst#el3-payloads-alternative-boot-flow
-.. _TF-A User Guide: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/user-guide.rst
-.. _TF-A SPM User Guide: https://trustedfirmware-a.readthedocs.io/en/latest/components/secure-partition-manager-design.html#building-tf-a-with-secure-partition-support
-.. _Firmware Update: FWU_
-.. _EL3 test payload README file: ../el3_payload/README
-.. _FWU: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/firmware-update.rst
-.. _FWU state machine: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/firmware-update.rst#fwu-state-machine
-.. _Summary of build options: user-guide.rst#summary-of-build-options
-.. _Building FIP images with support for Trusted Board Boot: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/user-guide.rst#building-fip-images-with-support-for-trusted-board-boot
-.. _Secure partition Manager: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/secure-partition-manager-design.rst
+.. _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
index 25881dd..a956efb 100644
--- a/docs/getting_started/index.rst
+++ b/docs/getting_started/index.rst
@@ -12,8 +12,10 @@
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)`_.
+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/run.rst b/docs/getting_started/run.rst
index fcb0bb8..0fe27d8 100644
--- a/docs/getting_started/run.rst
+++ b/docs/getting_started/run.rst
@@ -1,10 +1,9 @@
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
-TF-A Tests on those 2 platforms. The difference is that the following images are
-not needed here:
+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;
@@ -54,7 +53,7 @@
Running Firmware Update (FWU) Tests
-----------------------------------
-As previously mentioned in section `Putting it all together`_, there are a
+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.
@@ -69,7 +68,7 @@
- ``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`_.
+An example script is provided in ``scripts/run_fwu_fvp.sh``.
On Juno
^^^^^^^
@@ -110,7 +109,6 @@
*Copyright (c) 2019, Arm Limited. All rights reserved.*
-.. _scripts/run_fwu_fvp.sh: ../scripts/run_fwu_fvp.sh
.. _Juno Getting Started Guide: http://infocenter.arm.com/help/topic/com.arm.doc.dui0928e/DUI0928E_juno_arm_development_platform_gsg.pdf
-.. _Running the software on FVP: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/user-guide.rst#running-the-software-on-fvp
-.. _Running the software on Juno: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/user-guide.rst#running-the-software-on-juno
+.. _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 decdc68..e72a277 100644
--- a/docs/implementing-tests.rst
+++ b/docs/implementing-tests.rst
@@ -19,15 +19,15 @@
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
@@ -41,17 +41,18 @@
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
^^^^^^^^
@@ -69,21 +70,21 @@
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.
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 b483671..4869af1 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -28,37 +28,22 @@
Get the TF-A Tests source code from `trustedfirmware.org`_.
-See the `User Guide`_ for instructions on how to install, build and use the TF-A
-Tests.
+See content under the *Getting Started* chapter for instructions on how to
+install, build and use the TF-A Tests.
-See the `Design Guide`_ for information on how the TF-A Tests internally work.
+See :ref:`Framework Design` for information on how the TF-A Tests work
+internally.
-See the `Porting Guide`_ for information about how to use this software on
-another Armv8-A platform.
+See content under the *Porting* chapter for information about how to use this
+software on another Armv8-A platform.
-See the `Contributing Guidelines`_ for information on how to contribute to this
-project.
+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
-
-.. _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
-.. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
-
.. _trustedfirmware.org: https://git.trustedfirmware.org/TF-A/tf-a-tests.git
-
-.. _Trusted Firmware-A (TF-A): TF-A_
-.. _TF-A: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about
-.. _Test Secure Payload (TSP): TSP_
-.. _TSP: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/tree/bl32/tsp
-.. _Performance Measurement Framework (PMF): PMF_
-.. _PMF: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/firmware-design.rst#performance-measurement-framework
-.. _Firmware update: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/firmware-update.rst
-.. _EL3 payload: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/user-guide.rst#el3-payloads-alternative-boot-flow
-.. _Secure partition: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/secure-partition-manager-design.rst
+.. _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/mandatory-mods.rst b/docs/porting/mandatory-mods.rst
index dd4242f..7b94568 100644
--- a/docs/porting/mandatory-mods.rst
+++ b/docs/porting/mandatory-mods.rst
@@ -201,8 +201,8 @@
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`_.
+details of its description can be found in the
+`Trusted Firmware-A documentation`_.
Function : tftf_plat_get_mpidr()
--------------------------------
@@ -301,4 +301,4 @@
*Copyright (c) 2019, Arm Limited. All rights reserved.*
.. _SP805: https://static.docs.arm.com/ddi0270/b/DDI0270.pdf
-.. _docs/psci-pd-tree.rst: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/psci-pd-tree.rst
+.. _Trusted Firmware-A documentation: https://trustedfirmware-a.readthedocs.io/en/latest/design/psci-pd-tree.html#psci-power-domain-tree-structure