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/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