1 .. SPDX-License-Identifier: GPL-2.0
2 .. include:: <isonum.txt>
3
4 =========================
5 System Suspend Code Flows
6 =========================
7
8 :Copyright: |copy| 2020 Intel Corporation
9
10 :Author: Rafael J. Wysocki <rafael.j.wysocki@in
11
12 At least one global system-wide transition nee
13 system to get from the working state into one
14 :doc:`sleep states <sleep-states>`. Hibernati
15 transition to occur for this purpose, but the
16 referred to as *system-wide suspend* (or simpl
17 only one.
18
19 For those sleep states, the transition from th
20 the target sleep state is referred to as *syst
21 of cases, whether this means a transition or a
22 be clear from the context) and the transition
23 working state is referred to as *system resume
24
25 The kernel code flows associated with the susp
26 different sleep states of the system are quite
27 significant differences between the :ref:`susp
28 and the code flows related to the :ref:`suspen
29 :ref:`standby <standby>` sleep states.
30
31 The :ref:`suspend-to-RAM <s2ram>` and :ref:`st
32 cannot be implemented without platform support
33 boils down to the platform-specific actions ca
34 resume hooks that need to be provided by the p
35 available. Apart from that, the suspend and r
36 states are mostly identical, so they both toge
37 *platform-dependent suspend* states in what fo
38
39
40 .. _s2idle_suspend:
41
42 Suspend-to-idle Suspend Code Flow
43 =================================
44
45 The following steps are taken in order to tran
46 state to the :ref:`suspend-to-idle <s2idle>` s
47
48 1. Invoking system-wide suspend notifiers.
49
50 Kernel subsystems can register callbacks t
51 transition is about to occur and when the
52
53 That allows them to prepare for the change
54 up after getting back to the working state
55
56 2. Freezing tasks.
57
58 Tasks are frozen primarily in order to avo
59 from user space through MMIO regions or I/
60 it and to prevent user space from entering
61 of the transition is in progress (which mi
62 various reasons).
63
64 All user space tasks are intercepted as th
65 put into uninterruptible sleep until the e
66 transition.
67
68 The kernel threads that choose to be froze
69 specific reasons are frozen subsequently,
70 Instead, they are expected to periodically
71 to be frozen and to put themselves into un
72 however, that kernel threads can use locki
73 available in kernel space to synchronize t
74 resume, which can be much more precise tha
75 not a recommended option for kernel thread
76
77 3. Suspending devices and reconfiguring IRQs.
78
79 Devices are suspended in four phases calle
80 *late suspend* and *noirq suspend* (see :r
81 information on what exactly happens in eac
82
83 Every device is visited in each phase, but
84 accessed in more than two of them.
85
86 The runtime PM API is disabled for every d
87 phase and high-level ("action") interrupt
88 invoked before the *noirq* suspend phase.
89
90 Interrupts are still handled after that, b
91 interrupt controllers without performing a
92 would be triggered in the working state of
93 deferred till the subsequent system resume
94 `below <s2idle_resume_>`_).
95
96 IRQs associated with system wakeup devices
97 transition of the system is started when o
98
99 4. Freezing the scheduler tick and suspending
100
101 When all devices have been suspended, CPUs
102 into the deepest available idle state. Wh
103 "freezes" its own scheduler tick so that t
104 the tick do not occur until the CPU is wok
105
106 The last CPU to enter the idle state also
107 (among other things) prevents high resolut
108 forward until the first CPU that is woken
109 That allows the CPUs to stay in the deep i
110 go.
111
112 From this point on, the CPUs can only be w
113 interrupts. If that happens, they go back
114 interrupt that woke up one of them comes f
115 system wakeup, in which case the system re
116
117
118 .. _s2idle_resume:
119
120 Suspend-to-idle Resume Code Flow
121 ================================
122
123 The following steps are taken in order to tran
124 :ref:`suspend-to-idle <s2idle>` sleep state in
125
126 1. Resuming timekeeping and unfreezing the sc
127
128 When one of the CPUs is woken up (by a non
129 leaves the idle state entered in the last
130 transition, restarts the timekeeping (unle
131 by another CPU that woke up earlier) and t
132 unfrozen.
133
134 If the interrupt that has woken up the CPU
135 the system resume transition begins.
136
137 2. Resuming devices and restoring the working
138
139 Devices are resumed in four phases called
140 *resume* and *complete* (see :ref:`drivera
141 information on what exactly happens in eac
142
143 Every device is visited in each phase, but
144 accessed in more than two of them.
145
146 The working-state configuration of IRQs is
147 phase and the runtime PM API is re-enabled
148 supports it during the *early* resume phas
149
150 3. Thawing tasks.
151
152 Tasks frozen in step 2 of the preceding `s
153 transition are "thawed", which means that
154 uninterruptible sleep that they went into
155 are allowed to exit the kernel.
156
157 4. Invoking system-wide resume notifiers.
158
159 This is analogous to step 1 of the `suspen
160 and the same set of callbacks is invoked a
161 "notification type" parameter value is pas
162
163
164 Platform-dependent Suspend Code Flow
165 ====================================
166
167 The following steps are taken in order to tran
168 state to platform-dependent suspend state:
169
170 1. Invoking system-wide suspend notifiers.
171
172 This step is the same as step 1 of the sus
173 described `above <s2idle_suspend_>`_.
174
175 2. Freezing tasks.
176
177 This step is the same as step 2 of the sus
178 described `above <s2idle_suspend_>`_.
179
180 3. Suspending devices and reconfiguring IRQs.
181
182 This step is analogous to step 3 of the su
183 described `above <s2idle_suspend_>`_, but
184 wakeup generally does not have any effect
185
186 There are platforms that can go into a ver
187 when all CPUs in them are in sufficiently
188 devices have been put into low-power state
189 suspend-to-idle can reduce system power ve
190
191 On the other platforms, however, low-level
192 controllers) need to be turned off in a pl
193 in the hooks provided by the platform driv
194 reduction.
195
196 That usually prevents in-band hardware int
197 which must be done in a special platform-d
198 configuration of system wakeup sources usu
199 devices are suspended and is finalized by
200 on.
201
202 4. Disabling non-boot CPUs.
203
204 On some platforms the suspend hooks mentio
205 configuration of the system (in particular
206 by any code running in parallel with the p
207 and often do, trap into the platform firmw
208 suspend transition).
209
210 For this reason, the CPU offline/online (C
211 to take all of the CPUs in the system, exc
212 offline (typically, the CPUs that have bee
213 states).
214
215 This means that all tasks are migrated awa
216 rerouted to the only CPU that remains onli
217
218 5. Suspending core system components.
219
220 This prepares the core system components f
221 forward and suspends the timekeeping.
222
223 6. Platform-specific power removal.
224
225 This is expected to remove power from all
226 for the memory controller and RAM (in orde
227 latter) and some devices designated for sy
228
229 In many cases control is passed to the pla
230 to finalize the suspend transition as need
231
232
233 Platform-dependent Resume Code Flow
234 ===================================
235
236 The following steps are taken in order to tran
237 platform-dependent suspend state into the work
238
239 1. Platform-specific system wakeup.
240
241 The platform is woken up by a signal from
242 wakeup devices (which need not be an in-ba
243 control is passed back to the kernel (the
244 platform may need to be restored by the pl
245 kernel gets control again).
246
247 2. Resuming core system components.
248
249 The suspend-time configuration of the core
250 the timekeeping is resumed.
251
252 3. Re-enabling non-boot CPUs.
253
254 The CPUs disabled in step 4 of the precedi
255 back online and their suspend-time configu
256
257 4. Resuming devices and restoring the working
258
259 This step is the same as step 2 of the sus
260 described `above <s2idle_resume_>`_.
261
262 5. Thawing tasks.
263
264 This step is the same as step 3 of the sus
265 described `above <s2idle_resume_>`_.
266
267 6. Invoking system-wide resume notifiers.
268
269 This step is the same as step 4 of the sus
270 described `above <s2idle_resume_>`_.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.