diff --git a/docs/change-log.rst b/docs/change-log.rst index e075160..04f1644 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 cc2fe11..f50890b 100644 --- a/docs/firmware-design.rst +++ b/docs/firmware-design.rst @@ -8,22 +8,22 @@ .. 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 @@ 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 38eeb2f..5e788d1 100644 --- a/docs/psci-lib-integration-guide.rst +++ b/docs/psci-lib-integration-guide.rst @@ -25,12 +25,12 @@ ---------------------------------------------------------- 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 @@ 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 @@ #. 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 @@ #. 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 @@ 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 @@ - 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 @@ 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 @@ .. _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 6962cb6..b9ae92f 100644 --- a/docs/user-guide.rst +++ b/docs/user-guide.rst @@ -725,7 +725,7 @@ 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 @@ .. _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