[WIP][DNM] Add s2idle docs #562

DhruvaG2000 · 2025-12-08T12:05:27Z

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

github-actions · 2025-12-08T12:06:27Z

New warnings found with rstcheck:

source/linux/Foundational_Components/Power_Management/pm_psci_s2idle.rst:25: (ERROR/3) Unexpected indentation.

cshilwant · 2025-12-08T18:54:26Z

source/linux/Foundational_Components/Power_Management/pm_psci_s2idle.rst

+    *   **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).
+
+*************************************


The section identifier line should be of equal length to the section name.

cshilwant · 2025-12-08T18:56:02Z

source/linux/Foundational_Components/Power_Management/pm_psci_s2idle.rst

+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.
+
+**********************


The section identifier line should be of equal length to the section name.

cshilwant · 2025-12-08T18:56:52Z

source/linux/Foundational_Components/Power_Management/pm_psci_s2idle.rst

+
+**************************
+OS Initiated (OSI) Mode
+**************************


The section identifier line should be of equal length to the section name.

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>

DhruvaG2000 · 2025-12-09T12:24:11Z

@cshilwant , and rest I'll mark the PR ready for review once it has undergone LPM team internal review. Till then requesting you to hold off reviews.
This is going to be a major documentation update for AM62L PM story hence might take some time to get reviews and complete.

Thanks!

kwillis01 · 2025-12-09T14:44:22Z

source/linux/Foundational_Components/Power_Management/pm_psci_s2idle.rst

+S2Idle vs Deep Sleep (mem)
+**********************************
+
+On ARM64 platforms, both ``s2idle`` and ``deep`` states can achieve similar power savings (e.g., suspending to RAM / DDR Self-Refresh).


Suggested change

On ARM64 platforms, both ``s2idle`` and ``deep`` states can achieve similar power savings (e.g., suspending to RAM / DDR Self-Refresh).

On ARM64 platforms, ``deep`` states (suspend-to-RAM) and ``idle`` states can achieve similar power savings.

The eg here could be confusing since it is at the end of the sentence so it is not clear that you're referring to the deep states. Either it could be removed or the suggestion could be implemented.

ack, willfix

kwillis01 · 2025-12-09T14:50:31Z

source/linux/Foundational_Components/Power_Management/pm_psci_s2idle.rst

+On ARM64 platforms, both ``s2idle`` and ``deep`` states can achieve similar power savings (e.g., suspending to RAM / DDR Self-Refresh).
+The primary differences lie in the software execution flow, specifically how CPUs are managed and which PSCI APIs are invoked.
+
+.. list-table:: S2Idle vs Deep Sleep (ARM64)


Is it necessary to specify ARM64 platforms since you already specified ARM64 previously and this page will (presumably) only be used in ARM64 platforms?

ack, willfix

kwillis01 · 2025-12-09T14:54:13Z

source/linux/Foundational_Components/Power_Management/pm_psci_s2idle.rst

+     - **Offlined**: Non-boot CPUs are hot-unplugged (removed) from the system via ``CPU_OFF``.
+
+   * - **Entry Path**
+     - **cpuidle**: Uses the standard CPU idle framework and governance. It runtime suspends each driver to make sure it's idle.


Suggested change

- **cpuidle**: Uses the standard CPU idle framework and governance. It runtime suspends each driver to make sure it's idle.

- **cpuidle**: Uses the standard CPU idle framework and governance. Each driver is put into an idle state by runtime suspend.

ack, willfix

kwillis01 · 2025-12-09T14:56:15Z

source/linux/Foundational_Components/Power_Management/pm_psci_s2idle.rst

+     - **Kept Online**: Non-boot CPUs are put into a deep idle state but remain logically online.
+     - **Offlined**: Non-boot CPUs are hot-unplugged (removed) from the system via ``CPU_OFF``.


Suggested change

- **Kept Online**: Non-boot CPUs are put into a deep idle state but remain logically online.

- **Offlined**: Non-boot CPUs are hot-unplugged (removed) from the system via ``CPU_OFF``.

- **Online**: Non-boot CPUs are put into a deep idle state but remain logically online.

- **Offline**: Non-boot CPUs are hot-unplugged (removed) from the system via ``CPU_OFF``.

Changing it to be this way looks nicer and its easier to compare the differences imo. The explanations are good and get across the differences so the headings can become simpler

kwillis01 · 2025-12-09T15:00:50Z

source/linux/Foundational_Components/Power_Management/pm_psci_s2idle.rst

+
+   * - **Entry Path**
+     - **cpuidle**: Uses the standard CPU idle framework and governance. It runtime suspends each driver to make sure it's idle.
+     - **suspend_ops**: Uses platform-specific suspend operations like each driver's suspend ops. No governor involvement.


No governor involvement. kind of makes it sound like there is a governor but it is not being used.

kwillis01 · 2025-12-09T15:26:29Z

source/linux/Foundational_Components/Power_Management/pm_psci_s2idle.rst

+**********************
+
+The Power State Coordination Interface (PSCI) is an ARM-defined standard that acts as the fundamental
+enabler for s2idle on ARM platforms. PSCI defines a standardized firmware interface that allows the


Since we denote ARM64 platforms earlier in the doc, could this confuse readers to think that this only applies to ARM platforms but not ARM64 platforms?

kwillis01 · 2025-12-09T15:29:36Z

source/linux/Foundational_Components/Power_Management/pm_psci_s2idle.rst

+In this state, the Linux kernel freezes user space tasks, suspends devices, and then puts all CPUs into their deepest available idle state.
+
+**********************************
+S2Idle vs Deep Sleep (mem)


Wondering if this whole section should be moved to be the last / one of the last sections? I think explaining PSCI would be good to do before going into comparisons on how it operates differently than Deep Sleep

kwillis01 · 2025-12-09T15:31:17Z

source/linux/Foundational_Components/Power_Management/pm_psci_s2idle.rst

+   5. Thaw tasks
+
+The `cpuidle` driver calls the PSCI `CPU_SUSPEND` API to transition the CPU (and potentially
+higher-level topology nodes like clusters) into a low-power state. The effectiveness of s2idle


Assume the reader doesn't know what the topology nodes / clusters are. This should either be explained or the information in the parenthesis should be removed.

kwillis01 · 2025-12-09T15:31:45Z

source/linux/Foundational_Components/Power_Management/pm_psci_s2idle.rst

+   2. Suspend devices
+        |
+        v
+   3. cpuidle driver  -----------> CPU_SUSPEND (SMC/HVC)


What is SMC/HVC?

ok will add explanation for secure monitor call.

kwillis01 · 2025-12-09T15:33:44Z

source/linux/Foundational_Components/Power_Management/pm_psci_s2idle.rst

+        |                         Enter low-power
+        |                         hardware state


Suggested change

| Enter low-power

| hardware state

| CPU enters low-power

| hardware state

Only suggesting this because I think the cpuidle to PSCI firmware can be a little confusing.

github-actions bot assigned devarsht, DhruvaG2000, praneethbajjuri, r-vignesh, uditkumarti and vishalmti Dec 8, 2025

github-actions bot requested review from devarsht, praneethbajjuri, r-vignesh, uditkumarti and vishalmti December 8, 2025 12:05

DhruvaG2000 changed the title ~~feat(linux): Add s2idle docs~~ [WIP][DNM] Add s2idle docs Dec 8, 2025

cshilwant reviewed Dec 8, 2025

View reviewed changes

feat(linux): Add s2idle docs

ef4ad74

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>

DhruvaG2000 force-pushed the s2idle_doc branch from b935f77 to ef4ad74 Compare December 9, 2025 12:21

kwillis01 suggested changes Dec 9, 2025

View reviewed changes

	On ARM64 platforms, both ``s2idle`` and ``deep`` states can achieve similar power savings (e.g., suspending to RAM / DDR Self-Refresh).
	On ARM64 platforms, ``deep`` states (suspend-to-RAM) and ``idle`` states can achieve similar power savings.

	- cpuidle: Uses the standard CPU idle framework and governance. It runtime suspends each driver to make sure it's idle.
	- cpuidle: Uses the standard CPU idle framework and governance. Each driver is put into an idle state by runtime suspend.

		- Kept Online: Non-boot CPUs are put into a deep idle state but remain logically online.
		- Offlined: Non-boot CPUs are hot-unplugged (removed) from the system via ``CPU_OFF``.

[WIP][DNM] Add s2idle docs #562

Are you sure you want to change the base?

[WIP][DNM] Add s2idle docs #562

Uh oh!

Conversation

DhruvaG2000 commented Dec 8, 2025

Uh oh!

github-actions bot commented Dec 8, 2025

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!

DhruvaG2000 commented Dec 9, 2025

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!

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!

8 participants