Manual fixes to reST documentations

Non-automated fixes to the converted documentation.

Change-Id: I61f3d37c7a8d6a56a7351048060b970c5b3751e4
Signed-off-by: Douglas Raillard <douglas.raillard@arm.com>

docs/change-log.rst

@@ -1,6 +1,13 @@
+
+.. section-numbering::
+    :suffix: .
+
+.. contents::
+
 ARM Trusted Firmware - version 1.3
 ==================================
 
+
 New features
 ------------
 

docs/firmware-design.rst

@@ -8,22 +8,22 @@ ARM Trusted Firmware Design
 .. contents::
 
 The ARM Trusted Firmware implements a subset of the Trusted Board Boot
-Requirements (TBBR) Platform Design Document (PDD) [1] for ARM reference
+Requirements (TBBR) Platform Design Document (PDD) [1]_ for ARM reference
 platforms. The TBB sequence starts when the platform is powered on and runs up
 to the stage where it hands-off control to firmware running in the normal
 world in DRAM. This is the cold boot path.
 
 The ARM Trusted Firmware also implements the Power State Coordination Interface
-PDD [2] as a runtime service. PSCI is the interface from normal world software
+PDD [2]_ as a runtime service. PSCI is the interface from normal world software
 to firmware implementing power management use-cases (for example, secondary CPU
 boot, hotplug and idle). Normal world software can access ARM Trusted Firmware
 runtime services via the ARM SMC (Secure Monitor Call) instruction. The SMC
-instruction must be used as mandated by the SMC Calling Convention [3].
+instruction must be used as mandated by the SMC Calling Convention [3]_.
 
 The ARM Trusted Firmware implements a framework for configuring and managing
 interrupts generated in either security state. The details of the interrupt
 management framework and its design can be found in ARM Trusted Firmware
-Interrupt Management Design guide [4].
+Interrupt Management Design guide [4]_.
 
 The ARM Trusted Firmware can be built to support either AArch64 or AArch32
 execution state.
@@ -2410,14 +2410,11 @@ kernel at boot time. These can be found in the ``fdts`` directory.
 References
 ----------
 
-#. Trusted Board Boot Requirements CLIENT PDD (ARM DEN 0006B-5). Available
-   under NDA through your ARM account representative.
-
-#. `Power State Coordination Interface PDD`_
-
-#. `SMC Calling Convention PDD`_
-
-#. `ARM Trusted Firmware Interrupt Management Design guide`_.
+.. [#] Trusted Board Boot Requirements CLIENT PDD (ARM DEN 0006B-5). Available
+       under NDA through your ARM account representative.
+.. [#] `Power State Coordination Interface PDD`_
+.. [#] `SMC Calling Convention PDD`_
+.. [#] `ARM Trusted Firmware Interrupt Management Design guide`_.
 
 --------------
 

docs/psci-lib-integration-guide.rst

@@ -25,12 +25,12 @@ Generic call sequence for PSCI Library interface (AArch32)
 ----------------------------------------------------------
 
 The generic call sequence of PSCI Library interfaces (see
-`section 4`_) during cold boot in AArch32
+`PSCI Library Interface`_) during cold boot in AArch32
 system is described below:
 
 #. After cold reset, the EL3 Runtime Software performs its cold boot
    initialization including the PSCI library pre-requisites mentioned in
-   `section 4`_, and also the necessary platform
+   `PSCI Library Interface`_, and also the necessary platform
    setup.
 
 #. Call ``psci_setup()`` in Monitor mode.
@@ -46,7 +46,7 @@ system is described below:
    context and exiting to non-secure world. If the EL3 Runtime Software needs
    additional configuration to be set for non-secure context, like routing
    FIQs to the secure world, the values of the registers can be modified prior
-   to programming. See `section 3`_ for more
+   to programming. See `PSCI CPU context management`_ for more
    details on CPU context management.
 
 The generic call sequence of PSCI library interfaces during warm boot in
@@ -54,7 +54,7 @@ AArch32 systems is described below:
 
 #. After warm reset, the EL3 Runtime Software performs the necessary warm
    boot initialization including the PSCI library pre-requisites mentioned in
-   `section 4`_ (Note that the Data cache
+   `PSCI Library Interface`_ (Note that the Data cache
    **must not** be enabled).
 
 #. Call ``psci_warmboot_entrypoint()`` in Monitor mode. This interface
@@ -75,8 +75,8 @@ on an AArch32 system is described below:
 #. If ``psci_smc_handler()`` returns, populate the return value in R0 (AArch32)/
    X0 (AArch64) and restore other registers as per `SMCCC`_.
 
-#. .. rubric:: PSCI CPU context management
-      :name: psci-cpu-context-management
+PSCI CPU context management
+---------------------------
 
 PSCI library is in charge of initializing/restoring the non-secure CPU system
 registers according to `PSCI specification`_ during cold/warm boot.
@@ -120,7 +120,7 @@ registers: R0 - R3, LR (R14), SCR, SPSR, SCTLR.
 
 The EL3 Runtime Software must implement accessors to get/set pointers
 to CPU context ``cpu_context_t`` data and these are described in
-`section 5.2`_.
+`CPU Context management API`_.
 
 PSCI Library Interface
 ----------------------
@@ -208,7 +208,7 @@ must have completed. Major actions performed by this interface are:
 -  Calls ``plat_setup_psci_ops()`` with warm boot entrypoint ``mailbox_ep`` as
    argument.
 -  Calls ``cm_set_context_by_index()`` (see
-   `section 5.2`_) for all the CPUs in the
+   `CPU Context management API`_) for all the CPUs in the
    platform
 
 Interface : psci\_prepare\_next\_non\_secure\_ctx()
@@ -235,7 +235,7 @@ Interface : psci\_register\_spd\_pm\_hook()
     Argument : const spd_pm_ops_t *
     Return   : void
 
-As explained in `section 5.4`_,
+As explained in `Secure payload power management callback`_,
 the EL3 Runtime Software may want to perform some bookkeeping during power
 management operations. This function is used to register the ``spd_pm_ops_t``
 (first argument) callbacks with the PSCI library which will be called
@@ -554,11 +554,7 @@ workarounds.
 
 .. _PSCI spec: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
 .. _SMCCC: https://silver.arm.com/download/ARM_and_AMBA_Architecture/AR570-DA-80002-r0p0-00rel0/ARM_DEN0028A_SMC_Calling_Convention.pdf
-.. _section 4: #user-content-psci-library-interface
-.. _section 3: #user-content-psci-cpu-context-management
 .. _PSCI specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
-.. _section 5.2: #user-content-cpu-context-management-api
 .. _PSCI Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
-.. _section 5.4: #user-content-secure-payload-power-management-callback
 .. _Porting Guide: porting-guide.rst
 .. _Firmware Design: ./firmware-design.rst

docs/user-guide.rst

@@ -725,7 +725,7 @@ ignored as the linker is called directly.
 
 It is also possible to introduce an infinite loop to help in debugging the
 post-BL2 phase of the Trusted Firmware. This can be done by rebuilding BL1 with
-the ``SPIN_ON_BL1_EXIT=1`` build flag. Refer to the "Summary of build options"
+the ``SPIN_ON_BL1_EXIT=1`` build flag. Refer to the `Summary of build options`_
 section. In this case, the developer may take control of the target using a
 debugger when indicated by the console output. When using DS-5, the following
 commands can be used:
@@ -1721,9 +1721,7 @@ wakeup interrupt from RTC.
 .. _Linaro Release Notes: https://community.arm.com/tools/dev-platforms/b/documents/posts/linaro-release-notes-deprecated
 .. _Linaro instructions: https://community.arm.com/dev-platforms/b/documents/posts/instructions-for-using-the-linaro-software-deliverables
 .. _Development Studio 5 (DS-5): http://www.arm.com/products/tools/software-tools/ds-5/index.php
-.. _Summary of build options: #user-content-summary-of-build-options
 .. _here: ./psci-lib-integration-guide.rst
-.. _Building the Test Secure Payload: #user-content-building-the-test-secure-payload
 .. _Trusted Board Boot: trusted-board-boot.rst
 .. _Secure-EL1 Payloads and Dispatchers: firmware-design.rst#user-content-secure-el1-payloads-and-dispatchers
 .. _Firmware Update: ./firmware-update.rst