feat(linux): Add standby mode docs for AM62L

configs/AM62LX/AM62LX_linux_toc.txt

@@ -75,6 +75,7 @@ linux/Foundational_Components/Kernel/Kernel_Drivers/Watchdog
 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_am62l_standby
 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

source/linux/Foundational_Components/Power_Management/pm_am62l_standby.rst

@@ -0,0 +1,354 @@
+.. _am62l_standby_mode:
+
+########################
+AM62L Standby Mode
+########################
+
+**Overview**
+
+The AM62L family of SoCs supports a **Standby Mode** through the Linux CPUIdle framework's support for hierarchical
+idle states. While CPUIdle commonly provides per-CPU idle states using WFI (Wait For Interrupt), it also supports deeper
+states that operate at the CPU **cluster level**. The AM62L platform enables and utilizes these deeper cluster idle states
+to achieve improved standby power savings through reduced PLL frequencies, non-critical power domain disabling, and DDR
+auto-self-refresh when system conditions allow.
+
+*****************************
+Standby Mode: Opportunistic
+*****************************
+
+Unlike scheduled suspend modes that require explicit user intervention, Standby Mode operates transparently
+during normal system operation. The system continuously evaluates the idle state of processor clusters and
+automatically adjusts clock frequencies, disables non-critical power domains, and enables DDR auto-self-refresh
+when all cores are idle, then quickly restores full operational state when needed.
+
+Key characteristics of this opportunistic approach:
+
+* **Automatic Operation**: No user configuration required; the system makes power decisions in real-time
+* **Transparent**: Happens silently in the background during normal idle periods
+* **Fast Response**: Minimal latency to wake up from idle state upon interrupt
+* **Hierarchical Power Management**: Extends from individual CPU idle states to cluster-level standby
+
+*****************************
+Idle States Supported
+*****************************
+
+The AM62L Standby Mode configuration includes the following idle states:
+
+.. list-table:: AM62L Idle States
+   :widths: 20 50 30
+   :header-rows: 1
+
+   * - Idle State
+     - Description
+     - Latency
+
+   * - **cpu_sleep_0** (CPU Level)
+     - Individual CPU WFI (Wait For Interrupt) state
+     - Very Low (microseconds)
+
+   * - **cluster_sleep_0** (Low Latency Cluster standby)
+     - Cluster low-latency standby mode when all cores are idle, with reduced clock frequencies and non-critical power domains disabled
+     - Low (milliseconds)
+
+The configuration is loaded from the device tree overlay :file:`k3-am62l3-evm-idle-states.dtso`, which defines
+these states and their power management characteristics.
+
+**Power Domain Hierarchy**
+
+In addition to idle states, the device tree defines the power domain hierarchy which allows CPUIdle to understand
+how different power domains relate to each other:
+
+* **CPU_PD** (CPU Power Domain): Per-CPU power domain
+* **CLUSTER_PD** (Cluster Power Domain): Cluster-level power domain that groups multiple CPUs
+
+These power domains inform CPUIdle about which non-critical domains can be disabled when all cores within them are idle.
+
+.. note::
+
+   The device tree overlay also includes additional idle states for Suspend-to-Idle (S2Idle) functionality
+   can be referred from :ref:`pm_s2idle_psci`.
+   The Standby Mode uses the **cpu_sleep_0** and **cluster_sleep_0** idle states, coordinated through the
+   **CPU_PD** and **CLUSTER_PD** power domain hierarchy.
+
+****************************
+Critical Prerequisites
+****************************
+
+The AM62L Standby Mode implementation has important prerequisites that must be met for correct operation.
+
+**CPSW (Gigabit Ethernet) Driver Suspension**
+
+The entry into Cluster level standby is conditioned on CPSW driver being suspended, since hardware CRC errors
+occur when CPSW continues operation during cluster standby. The CPSW is an Always-On IP in the AM62L SoC.
+For cluster standby mode to be entered safely, the CPSW driver must be suspended/disabled. This is handled
+in the device tree overlay by disabling CPSW during standby transitions.
+
+**Display Driver Suspension**
+
+Similarly, the display driver must be in a suspended state for cluster standby to function correctly. Ensure
+display is not actively driving output when testing or relying on Standby Mode for power savings.
+
+.. warning::
+
+   Standby Mode only functions correctly when the DISPLAY and CPSW drivers are suspended. The device tree
+   overlay :file:`k3-am62l3-evm-idle-states.dtso` disables the CPSW driver to ensure this
+   condition is met. Do not override this configuration without understanding the implications for cluster
+   idle transitions and hardware stability.
+
+****************************
+Device Tree Configuration
+****************************
+
+The AM62L Standby Mode is defined in the device tree overlay. Key configuration elements include:
+
+1. **CPU Idle States** (cpu_sleep_0):
+      * Definition of per-CPU WFI idle state
+      * Entry and exit latencies
+      * Minimum residency duration
+
+2. **Domain Idle States** (cluster_sleep_0):
+      * Definition of low-latency cluster standby state
+      * Entry and exit latencies
+      * Minimum residency duration
+
+3. **Power Domain Hierarchy** (CPU_PD, CLUSTER_PD):
+      * Definition of CPU and cluster power domains
+      * Domain dependencies and relationships
+      * Coordination of which domains can enter standby together
+
+Example structure from :file:`k3-am62l3-evm-idle-states.dtso`:
+
+.. code-block:: dts
+
+   	idle-states {
+         entry-method = "psci";
+
+         cpu_sleep_0: stby {
+            compatible = "arm,idle-state";
+            idle-state-name = "Standby";
+            arm,psci-suspend-param = <0x00000001>;
+            entry-latency-us = <25>;
+            exit-latency-us = <100>;
+            min-residency-us = <1000>;
+         };
+      };
+
+      domain-idle-states {
+         cluster_sleep_0: low-latency-stby {
+            compatible = "domain-idle-state";
+            arm,psci-suspend-param = <0x01000021>;
+            entry-latency-us = <200>;
+            exit-latency-us = <300>;
+            min-residency-us = <10000>;
+         };
+      };
+
+      /* Power domain hierarchy for cluster standby coordination */
+      &psci {
+         CPU_PD: power-controller-cpu {
+            #power-domain-cells = <0>;
+            power-domains = <&CLUSTER_PD>;
+            domain-idle-states = <&cpu_sleep_0>;
+         };
+
+         CLUSTER_PD: power-controller-cluster {
+            #power-domain-cells = <0>;
+            domain-idle-states = <&cluster_sleep_0>;
+         };
+      };
+
+****************************
+Power Sequencing and Cluster Standby Entry/Exit
+****************************
+
+When the AM62L system enters Standby Mode and all cores in a cluster become idle:
+
+1. **Detection Phase**:
+      - CPUIdle monitors per-CPU idle state transitions
+      - Domain idle state manager tracks core idle status
+      - When all cores in a cluster are idle, cluster standby opportunity is identified
+
+2. **Coordination Phase**:
+      - Linux CPUIdle framework signals cluster idle state via PSCI ``CPU_SUSPEND`` call
+      - PSCI parameter encodes cluster standby request with standby state type (not power-down)
+      - TF-A receives request in secure monitor
+
+3. **Validation Phase**:
+      - TF-A validates the PSCI request parameter sent for cluster standby
+      - Checks all cores in cluster are idle
+
+4. **Standby Entry Phase**:
+      - TF-A executes cluster standby entry sequence
+      - Reduces PLL clock frequencies for non-critical subsystems
+      - Disables non-critical power domains
+      - Puts DDR into auto-self-refresh mode
+      - System enters low-power standby state with reduced power consumption
+
+5. **Wake-Up Phase**:
+      - Incoming interrupt triggers wake-up
+      - TF-A restores normal PLL frequencies and power domains
+      - DDR exits auto-self-refresh mode
+      - Cores resume execution with minimal latency
+      - System returns to active operation
+
+****************************
+Monitoring Standby Activity
+****************************
+Once Standby Mode is enabled, you can monitor idle state activity through the PM generic power domain (genpd)
+sysfs interface. The power domain names are derived from the PSCI power domain hierarchy defined in the device
+tree overlay.
+
+**CPU Idle Activity**
+
+To monitor per-CPU idle state usage:
+
+.. code-block:: console
+
+   # View CPU idle state statistics
+   $ cat /sys/kernel/debug/pm_genpd/power-controller-cpu/idle_states
+
+   State  Time(ms)       Usage      Rejected   Above      Below      S2idle
+   S0     1052189         34224       0        0       0          0
+
+**Cluster Standby Activity (Recommended)**
+
+To monitor cluster-level standby mode usage, which is the most useful metric for verifying that the system
+is successfully entering the low-latency standby mode when all cores are idle:
+
+.. code-block:: console
+
+   # View cluster standby state statistics
+   $ cat /sys/kernel/debug/pm_genpd/power-controller-cluster/idle_states
+
+   State  Time(ms)       Usage      Rejected   Above      Below      S2idle
+   S0     263595         5415       647        2854       0          0
+
+The ``Usage`` counter shows how many times the cluster entered the standby state, while ``Time(ms)`` shows
+the total milliseconds spent in that state. A non-zero Usage count indicates that the cluster standby mode
+is being actively used during idle periods.
+
+****************************
+Power Consumption Expectations
+****************************
+The AM62L Standby Mode delivers significant power savings when idle states are enabled. The following measurements
+show the power consumption differences:
+
+**Idle Power Consumption without Standby Idle States**
+
+When standby idle states are not enabled, the system maintains full operational clocking:
+
+.. list-table:: Power Consumption Without Idle States
+   :widths: 25 20
+   :header-rows: 1
+
+   * - Rail
+     - Average Power (mW)
+
+   * - vdd_core
+     - 302.65
+   * - soc_dvdd_1v8
+     - 27.03
+   * - soc_dvdd_3v3
+     - 3.74
+   * - vdda_1v8
+     - 29.89
+   * - vdd_lpddr4_pmic2
+     - 55.44
+   * - vdd_rtc
+     - 0.045
+   * - vdd_rtc_1v8
+     - 0.016
+   * - **Total System Power**
+     - **418.84 mW**
+
+**Idle Power Consumption with Cluster Standby Enabled**
+
+When cluster standby idle states are enabled and the system enters standby during idle periods:
+
+.. list-table:: Power Consumption With Cluster Standby
+   :widths: 25 20
+   :header-rows: 1
+
+   * - Rail
+     - Average Power (mW)
+
+   * - vdd_core
+     - 145.47
+   * - soc_dvdd_1v8
+     - 21.70
+   * - soc_dvdd_3v3
+     - 3.54
+   * - vdda_1v8
+     - 29.85
+   * - vdd_lpddr4_pmic2
+     - 21.25
+   * - vdd_rtc
+     - 0.038
+   * - vdd_rtc_1v8
+     - 0.017
+   * - **Total System Power**
+     - **221.88 mW**
+
+**Power Savings Summary**
+
+The AM62L Standby Mode achieves approximately **47% reduction in total system power consumption** during idle periods:
+
+* **Total Power without Idle States**: ~418.84 mW
+* **Total Power with Cluster Standby**: ~221.88 mW
+* **Power Savings**: ~196.96 mW (47%)
+
+****************************
+Difference from System Sleep Modes
+****************************
+Standby Mode is distinct from deeper system sleep modes like Deep Sleep or RTC-Only+DDR:
+
+.. list-table:: Standby vs Deep Sleep Modes
+   :widths: 25 35 40
+   :header-rows: 1
+
+   * - Feature
+     - Standby Mode
+     - Deep Sleep (mem)
+
+   * - **Entry**
+     - Automatic, opportunistic
+     - Explicit user request
+
+   * - **CPU State**
+     - Idle in standby state, context preserved
+     - Offline via hotplug
+
+   * - **Wakeup Latency**
+     - Microseconds
+     - Milliseconds
+
+   * - **PLL/Clock State**
+     - Reduced frequencies for non-critical subsystems
+     - Full frequency restoration required
+
+   * - **DDR State**
+     - Auto-self-refresh during cluster standby
+     - Self-refresh
+
+   * - **Use Case**
+     - Normal idle periods with fast wakeup
+     - Extended inactivity periods
+
+****************************
+Platform-Specific Implementation Details
+****************************
+The AM62L Standby Mode implementation uses platform-specific handlers in TF-A:
+
+* :file:`plat/ti/k3low/common/am62l_psci.c` - AM62L PSCI implementation
+* :file:`plat/ti/k3low/board/am62lx/lpm/standby.c` - Cluster standby handler and power sequencing logic
+
+These files implement the ``validate_power_state()`` and ``am62l_entry/exit_standby()`` PSCI platform operations that
+coordinate the idle state requests and manage the actual hardware sequencing for cluster standby entry/exit,
+including clock frequency adjustments and power domain transitions.
+
+**References**
+
+* :ref:`cpuidle-guide` - General CPUIdle framework documentation
+* :ref:`pm_s2idle_psci` - To understand PSCI and OSI mode
+* :ref:`lpm_modes` - Low power modes overview
+* Device Tree Overlay Documentation: :ref:`howto_dt_overlays`