feat(linux): Add s2idle docs

Document all about s2idle and PSCI and how the whole stack
helps us in selecting between low power modes on the TI AM62L

Signed-off-by: Dhruva Gole <d-gole@ti.com>

Author: DhruvaG2000

configs/AM62LX/AM62LX_linux_toc.txt

@@ -76,6 +76,7 @@ linux/Foundational_Components_Power_Management
 linux/Foundational_Components/Power_Management/pm_overview
 linux/Foundational_Components/Power_Management/pm_cpuidle
 linux/Foundational_Components/Power_Management/pm_am62lx_low_power_modes
+linux/Foundational_Components/Power_Management/pm_psci_s2idle
 linux/Foundational_Components/Power_Management/pm_wakeup_sources
 
 #linux/Foundational_Components/System_Security/SELinux

source/linux/Foundational_Components/Power_Management/pm_psci_s2idle.rst

@@ -0,0 +1,103 @@
+.. _pm_s2idle_psci:
+
+#############################################
+Suspend-to-Idle (S2Idle) and PSCI Integration
+#############################################
+
+**********************************
+Suspend-to-Idle (S2Idle) Overview
+**********************************
+
+Suspend-to-Idle (s2idle), also known as "freeze," is a generic, pure software, light-weight variant of system suspend.
+In this state, the Linux kernel freezes user space tasks, suspends devices, and then puts all CPUs into their deepest available idle state.
+
+**********************
+PSCI as the Enabler
+**********************
+
+The Power State Coordination Interface (PSCI) acts as the fundamental enabler for s2idle on ARM platforms. It provides the abstraction layer
+that allows the Operating System (OS) to request power states without needing intimate knowledge of the underlying power controller hardware.
+
+When the Linux kernel initiates s2idle:
+1. It freezes tasks and suspends devices.
+2. It invokes the `cpuidle` driver for each CPU.
+3. The `cpuidle` driver eventually calls the PSCI `CPU_SUSPEND` API to transition the CPU (and potentially higher-level topology nodes like clusters)
+   into a low-power state.
+
+The efficiency of s2idle depends heavily on the PSCI implementation's ability to coordinate these requests and enter the deepest possible hardware state.
+
+**************************
+OS Initiated (OSI) Mode
+**************************
+
+PSCI 1.0 introduced **OS Initiated (OSI)** mode, which shifts the responsibility of power state coordination from the platform firmware to the Operating System.
+
+In the default **Platform Coordinated (PC)** mode, the OS independently requests a state for each core. The firmware then aggregates these requests (voting) to
+determine if a cluster or the system can be powered down.
+
+In **OS Initiated (OSI)** mode, the OS explicitly manages the hierarchy. The OS determines when the last core in a power domain (e.g., a cluster) is going idle
+and explicitly requests the power-down of that domain.
+
+Why OSI?
+========
+
+OSI mode allows the OS to make better power decisions because it has visibility into:
+*   **Task Scheduling:** The OS knows when other cores will wake up.
+*   **Wakeup Latencies:** The OS can respect Quality of Service (QoS) latency constraints more accurately.
+*   **Usage Patterns:** The OS can predict idle duration better than firmware.
+
+OSI Sequence
+============
+
+The coordination in OSI mode follows a specific "Last Man Standing" sequence. The OS tracks the state of all cores in a topology node (e.g., a cluster).
+
+1.  **First Core(s) Idle:** When the first cores in a cluster go idle, the OS requests a local idle state for those cores (e.g., Core Power Down) but keeps the cluster running.
+2.  **Last Core Idle:** When the *last* active core in the cluster is ready to go idle, the OS recognizes that the entire cluster can now be powered down.
+3.  **Composite Request:** The last core issues a `CPU_SUSPEND` call that requests a **composite state**:
+    *   **Core State:** Power Down
+    *   **Cluster State:** Power Down
+    *   **System State:** (Optional) Power Down or Retention
+4.  **PSCI Enforcement:** The PSCI implementation verifies that all other cores in the requested node are indeed idle. If they are not, the request is denied (to prevent race conditions).
+
+*************************************
+Understanding the Suspend Parameter
+*************************************
+
+The `power_state` parameter passed to `CPU_SUSPEND` is the key to requesting these states. In OSI mode, this parameter must encode the intent for the entire hierarchy.
+
+Composite State Encoding
+========================
+
+The `power_state` is a 32-bit value that encodes the requested state for the Core and its parent nodes (Cluster, System).
+
+.. list-table:: Recommended StateID Encoding (Example)
+   :widths: 15 85
+   :header-rows: 1
+
+   * - Bit Field
+     - Description
+   * - **[31:28]**
+     - **Last Man Indicator**: Specifies the highest power level for which the calling core is the "last man".
+
+       * ``0``: Core only.
+       * ``1``: Last core in the Cluster.
+       * ``2``: Last core in the System.
+   * - **[27:16]**
+     - Reserved / Implementation Defined (often used for Extended StateID).
+   * - **[15:12]**
+     - Reserved.
+   * - **[11:8]**
+     - **System Level State**: e.g., 3 for Power Down, 2 for Retention.
+   * - **[7:4]**
+     - **Cluster Level State**: e.g., 3 for Power Down, 2 for Retention.
+   * - **[3:0]**
+     - **Core Level State**: e.g., 3 for Power Down, 1 for Retention, 0 for Run.
+
+**Example Scenario (OSI):**
+
+If the OS wants to put the last core of a cluster into power down, and also power down the cluster itself, it might construct a `power_state` where:
+*   **Core State [3:0]** = 3 (Power Down)
+*   **Cluster State [7:4]** = 3 (Power Down)
+*   **Last Man Indicator** = 1 (Cluster Level)
+
+The PSCI implementation reads this, confirms the other cores in the cluster are OFF, and then proceeds to power gate the entire cluster.

source/linux/Foundational_Components_Power_Management.rst

@@ -14,6 +14,7 @@ Power Management
    Foundational_Components/Power_Management/pm_rtc_ddr
    Foundational_Components/Power_Management/pm_low_power_modes
    Foundational_Components/Power_Management/pm_am62lx_low_power_modes
+   Foundational_Components/Power_Management/pm_psci_s2idle
    Foundational_Components/Power_Management/pm_wakeup_sources
    Foundational_Components/Power_Management/pm_sw_arch
    Foundational_Components/Power_Management/pm_debug