fix(pm_psci_s2idle): Update and enhance s2idle docs by ti-scaria · Pull Request #750 · TexasInstruments/processor-sdk-doc

ti-scaria · 2026-07-20T07:43:05Z

Update the s2idle docs with the correct AM62L power domain hierarchy and idle states derived from the latest release.

Rewrite the mode selection explanation for clarity.

akashdeep-ti · 2026-07-20T10:11:57Z

       };
   };

-**Why Domain Grouping is Needed:**


why is this removed?

The points were not very accurate. Explained the power-domain component here and how its used in a different section below

akashdeep-ti · 2026-07-20T10:15:45Z

+   their deepest idle state?
+2. **Which idle state can be entered?** — Of the states available for this domain,
+   which is the deepest one whose total latency (entry + exit) fits within the
+   current QoS constraint?


can we add some note about wakeup source also?

Yes, I'll add a note on how enabling/disabling wakeup sources can affect the selection

akashdeep-ti · 2026-07-20T10:17:32Z

+``WKUP_PD`` is a sibling of ``MAIN_PD`` (not a child), ``MAIN_PD`` can still
+enter DeepSleep. This is why the RTC+DDR section in :ref:`lpm_modes` requires
+disabling USB wakeup sources — DeepSleep works regardless, but RTC+DDR requires
+``WKUP_PD`` to be idle too.


Something for no console suspend

Where should we keep the warning regarding the no_console_suspend parameter. Should we only keep it here or mention in the main LPM page as well

i think here is good enough as it is totally linked to mode selection

StaticRocket

There are other places where active voice should be used

StaticRocket · 2026-07-20T18:49:29Z

 * **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.
+These power domains tell CPUIdle which non-critical domains to disable when all cores within them are idle.


Suggested change

These power domains tell CPUIdle which non-critical domains to disable when all cores within them are idle.

These power domains tell CPUIdle what non-critical domains to disable when all cores within them are idle.

StaticRocket · 2026-07-20T18:52:02Z

+
+
+The idle state associated with each domain is the state that domain enters when all
+of its children are powered off. This determines the deepest low power mode the


Suggested change

of its children are powered off. This determines the deepest low power mode the

of its children are off. This determines the deepest low power mode the

StaticRocket · 2026-07-20T18:53:52Z

+This mapping is what the kernel uses at runtime to determine whether a power domain
+can be powered off. If any device assigned to a domain is still active, that domain


Suggested change

This mapping is what the kernel uses at runtime to determine whether a power domain

can be powered off. If any device assigned to a domain is still active, that domain

This mapping lets the kernel determine at runtime when to turn off a power domain.

If any device assigned to a domain is still active, that domain

akashdeep-ti · 2026-07-21T08:43:19Z

-======================
+The Linux kernel's PM QoS (Quality of Service) framework allows drivers and applications to
+specify maximum acceptable wakeup latency. These constraints directly influence what idle
+state are elligible for entry during s2idle.


Nitpick: eligible

akashdeep-ti · 2026-07-21T08:47:02Z

-Here's how it would look like: (The testqos.c program is shown further below, which helps set the
-`/dev/cpu_wakeup_latency` QoS constraint.)
+   When a wakeup source is enabled/disabled, and also depending on the wakeup source being in-band/out-of-band,
+   the genpd framework may choose to power off or keep on the the associated devices.


good update, can you add the exact behavior of genpd for these two cases (maybe add in 2 points) so that our documentation is complete on its own

akashdeep-ti · 2026-07-21T08:48:58Z

+500 ms constraint, so DeepSleep is the deepest permitted state.

-**Example: Deep Sleep Mode Selection:**
+**Example 2: Active USB blocks RTC+DDR but DeepSleep still possible**


For new changes, keep RTC + I/O + DDR (old ones are already taken care by kendall in her PR)

akashdeep-ti · 2026-07-21T08:50:51Z

+
+.. warning::
+
+   When disabling **serial UART** as a wakeup source, do not disable ``console_suspend`` in the kernel command line.


Add small line saying that MAIN UART has out of band wakeup.

kwillis01

I really like the changes to the content, I think it will make it easier for users to read and implement in their system.

One big thing to note is I think we should go step by step in explaining how to set the CPU wakeup latency constraints. We should first explain what they are, the program needed to set them, and then how it is used.

kwillis01 · 2026-07-21T16:45:19Z


 On TI K3 platforms with OSI mode enabled, s2idle can dynamically enter deep power states
-(standby, Deep Sleep, RTC+DDR) that power down the MAIN domain. This creates a hybrid scenario:
+(standby, Deep Sleep, RTC+I/O+DDR) that power down the MAIN domain. This creates a hybrid scenario:


Suggested change

(standby, Deep Sleep, RTC+I/O+DDR) that power down the MAIN domain. This creates a hybrid scenario:

(standby, DeepSleep, RTC + I/O + DDR) that power down the MAIN domain. This creates a hybrid scenario:

kwillis01 · 2026-07-21T16:48:22Z

-            ├──> Timers
-            ├──> SDHCI controllers
-            └──> USB controllers
+   SOC_PD  [idle: RTC+I/O+DDR]


Suggested change

SOC_PD [idle: RTC+I/O+DDR]

SOC_PD [idle: RTC + I/O + DDR]

kwillis01 · 2026-07-21T19:07:17Z

+4. The deepest eligible state is selected

-* **cpu_sleep_1 (PowerDown)**: CPU is powered down with context loss
+Writing a latency value (in microseconds) to ``/dev/cpu_wakeup_latency`` does the following:


I think instead of diving right into writing to /dev/cpu_wakeup_latency, instead this part should start by explaining that to create a global CPU wakeup latency constraint the device file of /dev/cpu_wakeup_latency needs to be held open for the constraint to be “active”. Then show the example program of how to do that (test_qos.c). Then after those are explained, show and explain the example of using test_qos.c to determine the low power mode.

kwillis01 · 2026-07-21T19:07:41Z

-  * Min residency: 500ms
-  * Use case: Short to moderate idle periods with faster resume requirements
+The value ``0x7a120`` (500,000 μs = 500ms) allows all CPU-level idle states. At the system domain
+level, Deep Sleep (350ms total: 250ms entry + 100ms exit) is allowed while RTC+I/O+DDR (900ms total:


Suggested change

level, Deep Sleep (350ms total: 250ms entry + 100ms exit) is allowed while RTC+I/O+DDR (900ms total:

level, DeepSleep (350ms total: 250ms entry + 100ms exit) is allowed while RTC + I/O + DDR (900ms total:

kwillis01 · 2026-07-21T19:07:57Z

-  * Exit latency: 600ms
-  * Min residency: 1000ms
-  * Use case: Long idle periods requiring maximum power savings
+The Device Tree defines multiple idle states at each level of the hierarchy, each with different


Suggested change

The Device Tree defines multiple idle states at each level of the hierarchy, each with different

The device tree defines multiple idle states at each level of the hierarchy, each with different

kwillis01 · 2026-07-21T19:22:16Z

+Examples
+========
+
+**Example 1: Latency constraint forces Deep Sleep instead of RTC+I/O+DDR**


Suggested change

**Example 1: Latency constraint forces Deep Sleep instead of RTC+I/O+DDR**

**Example 1: Latency constraint forces Deep Sleep instead of RTC + I/O + DDR**

kwillis01 · 2026-07-21T19:22:52Z

-  during long idle periods.
+   Result: System enters DeepSleep

+Even though RTC+I/O+DDR offers lower power, its 900 ms total latency exceeds the


Suggested change

Even though RTC+I/O+DDR offers lower power, its 900 ms total latency exceeds the

Even though RTC + I/O + DDR offers lower power, its 900 ms total latency exceeds the

kwillis01 · 2026-07-21T19:23:17Z

+500 ms constraint, so DeepSleep is the deepest permitted state.

-**Example: Deep Sleep Mode Selection:**
+**Example 2: Active USB blocks RTC+I/O+DDR but DeepSleep still possible**


Suggested change

**Example 2: Active USB blocks RTC+I/O+DDR but DeepSleep still possible**

**Example 2: Active USB blocks RTC + I/O + DDR but DeepSleep still possible**

kwillis01 · 2026-07-21T19:23:37Z

+   └─> main_sleep_deep (DeepSleep): SELECTED
+
+   SOC_PD: WKUP_PD cannot power off (USB0 active)
+   └─> main_sleep_rtcddr (RTC+I/O+DDR): REJECTED


Suggested change

└─> main_sleep_rtcddr (RTC+I/O+DDR): REJECTED

└─> main_sleep_rtcddr (RTC + I/O + DDR): REJECTED

kwillis01 · 2026-07-21T19:24:03Z

+
+The active USB device only blocks ``SOC_PD`` from powering off. Since
+``WKUP_PD`` is a sibling of ``MAIN_PD`` (not a child), ``MAIN_PD`` can still
+enter DeepSleep. This is why the RTC+I/O+DDR section in :ref:`lpm_modes` requires


Suggested change

enter DeepSleep. This is why the RTC+I/O+DDR section in :ref:`lpm_modes` requires

enter DeepSleep. This is why the RTC + I/O + DDR section in :ref:`lpm_modes` requires

akashdeep-ti · 2026-07-23T09:01:33Z

-  * Exit latency: 100ms
-  * Min residency: 500ms
-  * Use case: Short to moderate idle periods with faster resume requirements
+The value ``0x7a120`` (500,000 μs = 500ms) allows all CPU-level idle states. At the system domain


Is CPU level idle states/ System level idle states defined somewhere?

This is explained in '3.3.5.4.2. Standard Format' section made earlier.

github-actions · 2026-07-23T12:52:44Z

New warnings found with rstcheck:

source/devices/AM62LX/linux/Release_Specific_Release_Notes.rst:90: (WARNING/2) Block quote ends without a blank line; unexpected unindent.

kwillis01

There are still some vale warnings for passive voice that need to be fixed if possible

kwillis01 · 2026-07-23T18:17:54Z

   }

-Alternatively, you can also set it with this command:
+Alternatively, you can also set it with the following bash command:


Suggested change

Alternatively, you can also set it with the following bash command:

Alternatively, the CPU wakeup latency constraint can be set with the following bash command:

kwillis01 · 2026-07-23T18:18:11Z

  - Support for Wifi with M2 CC33xx cards - :ref:`How to Enable M.2-CC33xx in Linux <enable_m2cc3301>`
  - Out-of-Box experience based on LVGL (Light and Versatile Graphics Library) - :ref:`TI LVGL Demo - User Guide <TI-LVGL-Demo-User-Guide-label>`
  - Security: Post Quantum Cryptography using Module Lattice (ML) Key Encapsulation Mechanism (KEM) or ML-KEM, ML Digital Signature Algorithm (DSA) or ML-DSA, and Stateless Hash-Based (SLH) DSA or SLH-DSA - :ref:`Post Quantum Cryptography <post_quantum_cryptography>`
+  - Power Management: Runtime Low power mode selection using s2idle framework - :ref:`AM62L S2idle <pm_s2idle_psci>`


Suggested change

- Power Management: Runtime Low power mode selection using s2idle framework - :ref:`AM62L S2idle <pm_s2idle_psci>`

- Power Management: Runtime low power mode selection using s2idle framework - :ref:`AM62L S2idle <pm_s2idle_psci>`

kwillis01 · 2026-07-23T18:34:07Z


-**Cluster-Level Idle States:**
+Here's how it would look like: (The set_qos.c program is shown in :ref:`setting-cpu-wakeup-latency`, which helps set the
+`/dev/cpu_wakeup_latency` QoS constraint.)


Suggested change

`/dev/cpu_wakeup_latency` QoS constraint.)

``/dev/cpu_wakeup_latency`` QoS constraint.)

kwillis01 · 2026-07-23T18:35:13Z

-**CPU-Level Idle States:**
+#. Each device or CPU can register a latency constraint (in nanoseconds)
+#. The cpuidle governor queries these constraints before selecting an idle state
+#. Only idle states with ``exit-latency-us + entry-latency-us`` ≤ constraint are considered


The code only around the exit and entry latency looked a little weird imo, this change makes it so the constraint is included but its in italics. I also think it would be fine if it all was considered code or bolded, as long as the constraint is included.

Suggested change

#. Only idle states with ``exit-latency-us + entry-latency-us`` ≤ constraint are considered

#. Only idle states with `exit-latency-us + entry-latency-us ≤ constraint` are considered

The use of double grave accent marks is correct here. We don't want this to be interpreted as an inline literal. That being said, I agree that the entire conditional expression should be in that block.

StaticRocket · 2026-07-23T19:00:52Z

#726

StaticRocket · 2026-07-23T21:50:58Z

   }

-Alternatively, you can also set it with this command:
+Alternatively, the CPU wakeup latency constraint can be set with the following bash command:


Passive voice

Update the s2idle docs with the correct AM62L power domain hierarchy and idle states derived from the latest release. Rewrite the mode selection logic by including the components involved and how they are used. Signed-off-by: Scaria Kochidanadu <s-kochidanadu@ti.com>

Add S2idle feature to Key Release References section. This is a method that enables selection of low power mode at runtime. Signed-off-by: Scaria Kochidanadu <s-kochidanadu@ti.com>

ti-scaria requested review from StaticRocket, VeeruPrudhvi, cshilwant, gehariprasath, jeevantelukula, praneethbajjuri and uditkumarti as code owners July 20, 2026 07:43

github-actions Bot assigned devarsht, gehariprasath, praneethbajjuri, r-vignesh, ti-scaria, uditkumarti and vishalmti Jul 20, 2026

akashdeep-ti reviewed Jul 20, 2026

View reviewed changes

akashdeep-ti suggested changes Jul 20, 2026

View reviewed changes

ti-scaria force-pushed the s2idle_update branch from 54ca588 to 96dc22a Compare July 20, 2026 12:02

StaticRocket requested changes Jul 20, 2026

View reviewed changes

ti-scaria force-pushed the s2idle_update branch from 96dc22a to b1ff2c0 Compare July 21, 2026 06:41

akashdeep-ti reviewed Jul 21, 2026

View reviewed changes

akashdeep-ti suggested changes Jul 21, 2026

View reviewed changes

ti-scaria force-pushed the s2idle_update branch from b1ff2c0 to 227fd48 Compare July 21, 2026 10:20

kwillis01 suggested changes Jul 21, 2026

View reviewed changes

ti-scaria force-pushed the s2idle_update branch from 227fd48 to 8a74108 Compare July 22, 2026 07:07

github-actions Bot requested review from devarsht and r-vignesh July 22, 2026 07:07

github-actions Bot requested a review from vishalmti July 22, 2026 07:07

ti-scaria requested review from StaticRocket, akashdeep-ti and kwillis01 July 23, 2026 05:44

ti-scaria force-pushed the s2idle_update branch from 8a74108 to b3424dc Compare July 23, 2026 09:01

akashdeep-ti reviewed Jul 23, 2026

View reviewed changes

github-actions Bot assigned bryanbrattlof and sskartheekadivi Jul 23, 2026

github-actions Bot requested review from bryanbrattlof and sskartheekadivi July 23, 2026 12:52

ti-scaria force-pushed the s2idle_update branch 2 times, most recently from e4e60a5 to f642481 Compare July 23, 2026 13:06

kwillis01 suggested changes Jul 23, 2026

View reviewed changes

ti-scaria force-pushed the s2idle_update branch from f642481 to 1926ca7 Compare July 23, 2026 20:11

kwillis01 approved these changes Jul 23, 2026

View reviewed changes

StaticRocket reviewed Jul 23, 2026

View reviewed changes

ti-scaria force-pushed the s2idle_update branch from 1926ca7 to 48be659 Compare July 24, 2026 07:13

ti-scaria requested review from StaticRocket, akashdeep-ti and kwillis01 July 24, 2026 07:33

ti-scaria added 2 commits July 24, 2026 17:40

feat(linux): add S2idle feature to release notes

6162289

Add S2idle feature to Key Release References section. This is a method that enables selection of low power mode at runtime. Signed-off-by: Scaria Kochidanadu <s-kochidanadu@ti.com>

ti-scaria force-pushed the s2idle_update branch from 48be659 to 6162289 Compare July 24, 2026 12:10

	These power domains tell CPUIdle which non-critical domains to disable when all cores within them are idle.
	These power domains tell CPUIdle what non-critical domains to disable when all cores within them are idle.



		The idle state associated with each domain is the state that domain enters when all
		of its children are powered off. This determines the deepest low power mode the

	of its children are powered off. This determines the deepest low power mode the
	of its children are off. This determines the deepest low power mode the

		This mapping is what the kernel uses at runtime to determine whether a power domain
		can be powered off. If any device assigned to a domain is still active, that domain


		.. warning::

		When disabling serial UART as a wakeup source, do not disable ``console_suspend`` in the kernel command line.

	(standby, Deep Sleep, RTC+I/O+DDR) that power down the MAIN domain. This creates a hybrid scenario:
	(standby, DeepSleep, RTC + I/O + DDR) that power down the MAIN domain. This creates a hybrid scenario:

	level, Deep Sleep (350ms total: 250ms entry + 100ms exit) is allowed while RTC+I/O+DDR (900ms total:
	level, DeepSleep (350ms total: 250ms entry + 100ms exit) is allowed while RTC + I/O + DDR (900ms total:

	The Device Tree defines multiple idle states at each level of the hierarchy, each with different
	The device tree defines multiple idle states at each level of the hierarchy, each with different

	Example 1: Latency constraint forces Deep Sleep instead of RTC+I/O+DDR
	Example 1: Latency constraint forces Deep Sleep instead of RTC + I/O + DDR

	Even though RTC+I/O+DDR offers lower power, its 900 ms total latency exceeds the
	Even though RTC + I/O + DDR offers lower power, its 900 ms total latency exceeds the

	Example 2: Active USB blocks RTC+I/O+DDR but DeepSleep still possible
	Example 2: Active USB blocks RTC + I/O + DDR but DeepSleep still possible

	└─> main_sleep_rtcddr (RTC+I/O+DDR): REJECTED
	└─> main_sleep_rtcddr (RTC + I/O + DDR): REJECTED

	enter DeepSleep. This is why the RTC+I/O+DDR section in :ref:`lpm_modes` requires
	enter DeepSleep. This is why the RTC + I/O + DDR section in :ref:`lpm_modes` requires

	Alternatively, you can also set it with the following bash command:
	Alternatively, the CPU wakeup latency constraint can be set with the following bash command:

	- Power Management: Runtime Low power mode selection using s2idle framework - :ref:`AM62L S2idle <pm_s2idle_psci>`
	- Power Management: Runtime low power mode selection using s2idle framework - :ref:`AM62L S2idle <pm_s2idle_psci>`

	`/dev/cpu_wakeup_latency` QoS constraint.)
	``/dev/cpu_wakeup_latency`` QoS constraint.)

	#. Only idle states with ``exit-latency-us + entry-latency-us`` ≤ constraint are considered
	#. Only idle states with `exit-latency-us + entry-latency-us ≤ constraint` are considered

Uh oh!

Conversation

ti-scaria commented Jul 20, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

StaticRocket left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

akashdeep-ti Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kwillis01 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jul 23, 2026

Uh oh!

kwillis01 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

StaticRocket commented Jul 23, 2026

akashdeep-ti Jul 21, 2026 •

edited

Loading