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

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>

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 a review from devarsht July 22, 2026 07:07

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

	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

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

10 participants

akashdeep-ti Jul 21, 2026 •

edited

Loading