diff --git a/docs/design/firmware-design.rst b/docs/design/firmware-design.rst index 56bedd47d..131cca135 100644 --- a/docs/design/firmware-design.rst +++ b/docs/design/firmware-design.rst @@ -9,12 +9,12 @@ 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. -TF-A also implements the `Power State Coordination Interface PDD`_ 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 TF-A runtime services via -the Arm SMC (Secure Monitor Call) instruction. The SMC instruction must be -used as mandated by the SMC Calling Convention (`SMCCC`_). +TF-A also implements the `PSCI`_ 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 TF-A runtime services via the Arm SMC (Secure Monitor Call) instruction. +The SMC instruction must be used as mandated by the SMC Calling Convention +(`SMCCC`_). TF-A implements a framework for configuring and managing interrupts generated in either security state. The details of the interrupt management framework @@ -400,8 +400,7 @@ initialization is complete. Hence, BL2 populates a platform-specific area of memory with the entrypoint and Saved Program Status Register (``SPSR``) of the normal world software image. The entrypoint is the load address of the BL33 image. The ``SPSR`` is determined as specified in Section 5.13 of the -`Power State Coordination Interface PDD`_. This information is passed to the -EL3 Runtime Software. +`PSCI`_. This information is passed to the EL3 Runtime Software. AArch64 BL31 (EL3 Runtime Software) execution ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -952,8 +951,8 @@ TODO: Provide design walkthrough of PSCI implementation. The PSCI v1.1 specification categorizes APIs as optional and mandatory. All the mandatory APIs in PSCI v1.1, PSCI v1.0 and in PSCI v0.2 draft specification -`Power State Coordination Interface PDD`_ are implemented. The table lists -the PSCI v1.1 APIs and their support in generic code. +`PSCI`_ are implemented. The table lists the PSCI v1.1 APIs and their support +in generic code. An API implementation might have a dependency on platform code e.g. CPU_SUSPEND requires the platform to export a part of the implementation. Hence the level @@ -2790,7 +2789,7 @@ kernel at boot time. These can be found in the ``fdts`` directory. - `Trusted Board Boot Requirements CLIENT (TBBR-CLIENT) Armv8-A (ARM DEN0006D)`_ -- `Power State Coordination Interface PDD`_ +- `PSCI`_ - `SMC Calling Convention`_ @@ -2800,10 +2799,8 @@ kernel at boot time. These can be found in the ``fdts`` directory. *Copyright (c) 2013-2023, Arm Limited and Contributors. All rights reserved.* -.. _Power State Coordination Interface PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf .. _SMCCC: https://developer.arm.com/docs/den0028/latest -.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf -.. _Power State Coordination Interface PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf +.. _PSCI: https://developer.arm.com/documentation/den0022/latest/ .. _Arm ARM: https://developer.arm.com/docs/ddi0487/latest .. _SMC Calling Convention: https://developer.arm.com/docs/den0028/latest .. _Trusted Board Boot Requirements CLIENT (TBBR-CLIENT) Armv8-A (ARM DEN0006D): https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a diff --git a/docs/getting_started/psci-lib-integration-guide.rst b/docs/getting_started/psci-lib-integration-guide.rst index 4d690a978..7e4b0db63 100644 --- a/docs/getting_started/psci-lib-integration-guide.rst +++ b/docs/getting_started/psci-lib-integration-guide.rst @@ -3,7 +3,7 @@ PSCI Library Integration guide for Armv8-A AArch32 systems This document describes the PSCI library interface with a focus on how to integrate with a suitable Trusted OS for an Armv8-A AArch32 system. The PSCI -Library implements the PSCI Standard as described in `PSCI spec`_ and is meant +Library implements the PSCI Standard as described in `PSCI`_ and is meant to be integrated with EL3 Runtime Software which invokes the PSCI Library interface appropriately. **EL3 Runtime Software** refers to software executing at the highest secure privileged mode, which is EL3 in AArch64 or Secure SVC/ @@ -74,7 +74,7 @@ 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. +registers according to `PSCI`_ during cold/warm boot. This is referred to as ``PSCI CPU Context Management``. Registers that need to be preserved across CPU power down/power up cycles are maintained in ``cpu_context_t`` data structure. The initialization of other non-secure CPU @@ -120,8 +120,8 @@ to CPU context ``cpu_context_t`` data and these are described in PSCI Library Interface ---------------------- -The PSCI library implements the `PSCI Specification`_. The interfaces -to this library are declared in ``psci_lib.h`` and are as listed below: +The PSCI library implements the `PSCI`_. The interfaces to this library are +declared in ``psci_lib.h`` and are as listed below: .. code:: c @@ -254,7 +254,7 @@ PSCI service range specified in `SMCCC`_. The function ID ``smc_fid`` (first argument) determines the PSCI API to be called. The ``x1`` to ``x4`` (2nd to 5th arguments), are the values of the registers r1 - r4 (in AArch32) or x1 - x4 (in AArch64) when the SMC is received. These are the arguments to PSCI API as -described in `PSCI spec`_. The 'flags' (8th argument) is a bit field parameter +described in `PSCI`_. The 'flags' (8th argument) is a bit field parameter and is detailed in 'smccc.h' header. It includes whether the call is from the secure or non-secure world. The ``cookie`` (6th argument) and the ``handle`` (7th argument) are not used and are reserved for future use. @@ -273,7 +273,7 @@ Interface : psci_warmboot_entrypoint() Return : void This function performs the warm boot initialization/restoration as mandated by -`PSCI spec`_. For AArch32, on wakeup from power down the CPU resets to secure SVC +`PSCI`_. For AArch32, on wakeup from power down the CPU resets to secure SVC mode and the EL3 Runtime Software must perform the prerequisite initializations mentioned at top of this section. This function must be called with Data cache disabled (unless build option ``HW_ASSISTED_COHERENCY`` is enabled) but with MMU @@ -496,7 +496,7 @@ A brief description of each callback is given below: This callback is called in response to PSCI_MIGRATE_INFO_TYPE or PSCI_MIGRATE_INFO_UP_CPU APIs. The return value of this callback must correspond to the return value of PSCI_MIGRATE_INFO_TYPE API as described - in `PSCI spec`_. If the secure payload is a Uniprocessor (UP) + in `PSCI`_. If the secure payload is a Uniprocessor (UP) implementation, then it must update the mpidr of the CPU it is resident in via ``resident_cpu`` (first argument). The updates to ``resident_cpu`` is ignored if the secure payload is a multiprocessor (MP) implementation. @@ -528,9 +528,7 @@ workarounds. -------------- -*Copyright (c) 2016-2020, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2016-2023, Arm Limited and Contributors. All rights reserved.* -.. _PSCI spec: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf +.. _PSCI: https://developer.arm.com/documentation/den0022/latest/ .. _SMCCC: https://developer.arm.com/docs/den0028/latest -.. _PSCI specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf -.. _PSCI Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf diff --git a/docs/getting_started/rt-svc-writers-guide.rst b/docs/getting_started/rt-svc-writers-guide.rst index 5a4be4d48..fe6455883 100644 --- a/docs/getting_started/rt-svc-writers-guide.rst +++ b/docs/getting_started/rt-svc-writers-guide.rst @@ -314,7 +314,7 @@ provide this information.... -------------- -*Copyright (c) 2014-2021, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2014-2023, Arm Limited and Contributors. All rights reserved.* .. _SMCCC: https://developer.arm.com/docs/den0028/latest -.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf +.. _PSCI: https://developer.arm.com/documentation/den0022/latest/ diff --git a/docs/index.rst b/docs/index.rst index bce9bb74e..a7a599356 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -90,7 +90,7 @@ have previously been raised against the software. .. _Armv7-A and Armv8-A: https://developer.arm.com/products/architecture/a-profile .. _Secure Monitor: http://www.arm.com/products/processors/technologies/trustzone/tee-smc.php -.. _Power State Coordination Interface (PSCI): http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf +.. _Power State Coordination Interface (PSCI): https://developer.arm.com/documentation/den0022/latest/ .. _Trusted Board Boot Requirements CLIENT (TBBR-CLIENT): https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a .. _System Control and Management Interface (SCMI): http://infocenter.arm.com/help/topic/com.arm.doc.den0056a/DEN0056A_System_Control_and_Management_Interface.pdf .. _Software Delegated Exception Interface (SDEI): http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf diff --git a/docs/plat/arm/juno/index.rst b/docs/plat/arm/juno/index.rst index ea7d11c0f..5320a3b36 100644 --- a/docs/plat/arm/juno/index.rst +++ b/docs/plat/arm/juno/index.rst @@ -249,4 +249,4 @@ configure it. .. _build the binaries from source: https://github.com/ARM-software/SCP-firmware/blob/master/user_guide.md#scp-firmware-user-guide .. _Arm Platforms Portal: https://community.arm.com/dev-platforms/ .. _Juno Getting Started Guide: https://developer.arm.com/documentation/den0928/f/?lang=en -.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf +.. _PSCI: https://developer.arm.com/documentation/den0022/latest/ diff --git a/docs/porting-guide.rst b/docs/porting-guide.rst index 8182f9140..b557a1695 100644 --- a/docs/porting-guide.rst +++ b/docs/porting-guide.rst @@ -3668,7 +3668,7 @@ amount of open resources per driver. *Copyright (c) 2013-2023, Arm Limited and Contributors. All rights reserved.* -.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf +.. _PSCI: https://developer.arm.com/documentation/den0022/latest/ .. _Arm Generic Interrupt Controller version 2.0 (GICv2): http://infocenter.arm.com/help/topic/com.arm.doc.ihi0048b/index.html .. _3.0 (GICv3): http://infocenter.arm.com/help/topic/com.arm.doc.ihi0069b/index.html .. _FreeBSD: https://www.freebsd.org