From 668c5022e5edf6edf36180d04e9ef271829c94b5 Mon Sep 17 00:00:00 2001 From: Douglas Raillard Date: Wed, 28 Jun 2017 16:14:55 +0100 Subject: [PATCH] Manual fixes to reST documentations Non-automated fixes to the converted documentation. Change-Id: I61f3d37c7a8d6a56a7351048060b970c5b3751e4 Signed-off-by: Douglas Raillard --- docs/change-log.rst | 7 +++++++ docs/firmware-design.rst | 21 +++++++++------------ docs/psci-lib-integration-guide.rst | 22 +++++++++------------- docs/user-guide.rst | 4 +--- 4 files changed, 26 insertions(+), 28 deletions(-) diff --git a/docs/change-log.rst b/docs/change-log.rst index e0751607..04f16445 100644 --- a/docs/change-log.rst +++ b/docs/change-log.rst @@ -1,6 +1,13 @@ + +.. section-numbering:: + :suffix: . + +.. contents:: + ARM Trusted Firmware - version 1.3 ================================== + New features ------------ diff --git a/docs/firmware-design.rst b/docs/firmware-design.rst index cc2fe118..f50890b1 100644 --- a/docs/firmware-design.rst +++ b/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`_. -------------- diff --git a/docs/psci-lib-integration-guide.rst b/docs/psci-lib-integration-guide.rst index 38eeb2fd..5e788d13 100644 --- a/docs/psci-lib-integration-guide.rst +++ b/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 diff --git a/docs/user-guide.rst b/docs/user-guide.rst index 6962cb67..b9ae92fc 100644 --- a/docs/user-guide.rst +++ b/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 -- 2.30.2