Merge "docs: update PSCI reference" into integration

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

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

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/

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

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/

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