1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
|
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!-- Fill in your name for FIRSTNAME and SURNAME. -->
<!ENTITY dhfirstname "Tim">
<!ENTITY dhsurname "Dijkstra">
<!-- dhusername could also be set to "&firstname; &surname;". -->
<!ENTITY dhusername "Tim Dijkstra">
<!ENTITY dhemail "tim@famdijkstra.org">
<!-- Please adjust the date whenever revising the manpage. -->
<!ENTITY dhdate "Apr 25, 2007">
<!-- SECTION should be 1-8, maybe w/ subsection other parameters are
allowed: see man(7), man(1) and
http://www.tldp.org/HOWTO/Man-Page/q2.html. -->
<!ENTITY dhsection "8">
<!-- TITLE should be something like "User commands" or similar (see
http://www.tldp.org/HOWTO/Man-Page/q2.html). -->
<!ENTITY dhtitle "pm-utils User Manual">
<!ENTITY dhucpackage "pm-action">
<!ENTITY dhpackage "pm-action">
<!ENTITY debian "<productname>Debian</productname>">
<!ENTITY gnu "<acronym>GNU</acronym>">
<!ENTITY gpl "&gnu; <acronym>GPL</acronym>">
]>
<refentry>
<refentryinfo>
<title>&dhtitle;</title>
<productname>&dhpackage;</productname>
<date>&dhdate;</date>
<authorgroup>
<author>
<firstname>&dhfirstname;</firstname>
<surname>&dhsurname;</surname>
<contrib>Manpage author.</contrib>
<address>
<email>&dhemail;</email>
</address>
</author>
</authorgroup>
<copyright>
<year>2007</year>
<holder>&dhusername;</holder>
</copyright>
<legalnotice>
<para>
This manual page was originally written for the &debian; system, and
has been adopted by the pm-utils project.
</para>
<para>
Permission is granted to copy, distribute and/or modify this
document under the terms of the &gnu; General Public License,
Version 2 or (at your option) any later version published by
the Free Software Foundation.
</para>
</legalnotice>
</refentryinfo>
<refmeta>
<refentrytitle>&dhucpackage;</refentrytitle>
<manvolnum>&dhsection;</manvolnum>
</refmeta>
<refnamediv>
<refname>&dhpackage;</refname>
<refpurpose>Suspend or Hibernate your computer</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>pm-hibernate</command>
<arg>--help</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>pm-suspend</command>
<arg>--quirk-*</arg>
<arg>--help</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>pm-suspend-hybrid</command>
<arg>--quirk-*</arg>
<arg>--help</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1 id="description">
<title>DESCRIPTION</title>
<para>
This manual page documents briefly the
<command>&dhpackage;</command>, <command>pm-hibernate</command>,
<command>pm-suspend</command> and <command>pm-suspend-hybrid</command>
commands. This manual page was originally written for the &debian;
distribution and has been adopted by the pm-utils project.
</para>
<para>
These commands can be used to put the machine in a sleep
state. The precise way how this is done can be
influenced by installing executables and configuration snippets.
For some options external programs are needed.
</para>
<para>
These commands will usually be called by <command>UPower</command>
or <command>hald</command> when triggered to do so by a program
in a desktop session such as <command>gnome-power-manager</command>.
Calling them from the command line is also possible, but it is not
guaranteed that all programs in your desktop session keep working
as expected.
</para>
<variablelist>
<!-- Use the variablelist.term.separator and the
variablelist.term.break.after parameters to
control the term elements. -->
<varlistentry>
<term><option>pm-suspend</option></term>
<listitem>
<para>
During suspend most devices are shutdown, and system state is
saved in RAM. The system still requires power in this state. Most
modern systems require 3 to 5 seconds to enter and leave suspend,
and most laptops can stay in suspend mode for 1 to 3 days before
exhausting their battery.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>pm-hibernate</option></term>
<listitem>
<para>
During hibernate the system is fully powered off, and system state
is saved to disk. The system does not require power, and can stay
in hibernate mode indefinitely. Most modern systems require 15 to 45
seconds to enter and leave hibernate, and entering and leaving
hibernate takes longer when you have more memory.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>pm-suspend-hybrid</option></term>
<listitem>
<para>
Hybrid-suspend is the process where the system does everything it
needs to hibernate, but suspends instead of shutting down. This means that
your computer can wake up quicker than for normal hibernation
if you do not run out of power, and you can resume even if you run out of power.
s2both(8) is an hybrid-suspend implementation.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="options">
<title>OPTIONS</title>
<para>
On some hardware putting the video card in the suspend state and
recovering from it needs some special quirk handling.
With the --quirk-* options of the <command>pm-suspend</command> and
<command>pm-suspend-hybrid</command> commands you can select which
quirks should be used.
</para>
<para>
If <command>pm-suspend</command>, <command>pm-hibernate</command>,
or <command>pm-suspend-hybrid</command> are invoked without any
commandline parameters, they will try to grab the correct quirks
from the internal quirk database.
</para>
<variablelist>
<!-- Use the variablelist.term.separator and the
variablelist.term.break.after parameters to
control the term elements. -->
<varlistentry>
<term><option>--quirk-dpms-on</option></term>
<listitem>
<para>
This option forces the video hardware to turn on the screen during
resume. Most video adapters turn on the screen themselves, but if
you get a blank screen on resume that can be turned back on by
moving the mouse or typing then this option may be useful.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--quirk-dpms-suspend</option></term>
<listitem>
<para>
This option forces the video hardware to turn off the screen when suspending.
Most video adapters seem to do this correctly, but some do not, which
wastes lots of power. If your screen is still on after successfully suspending
you may need to use this option.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--quirk-radeon-off</option></term>
<listitem>
<para>
This option forces Radeon hardware to turn off the display
during suspend and turn it back on during resume. You only need to
do this on some old ThinkPads of the '30 series
(T30, X31, R32,... ) with Radeon video hardware.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--quirk-s3-bios</option></term>
<listitem>
<para>
This option calls the video BIOS during S3 resume. Unfortunately,
it is not always allowed to call the video BIOS at this point, so
sometimes adding this option can actually break resume on some
systems.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--quirk-s3-mode</option></term>
<listitem>
<para>
This option initializes the video card into a VGA text mode, and
then uses the BIOS to set the video mode. On some systems S3 BIOS
only initializes the video BIOS to text mode, and so both S3 BIOS
and S3 MODE are needed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--quirk-vbe-post</option></term>
<listitem>
<para>
This option will attempt to reinitialize the video card when
resuming from suspend, using the same code the system BIOS uses
at boot in order to initialize the video hardware.
Not all video cards need this, and using this option on systems
where it is not needed can cause a system to lock up when resuming.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--quirk-vbemode-restore</option></term>
<listitem>
<para>
This option will save and restore the current VESA mode which may
be necessary to avoid X screen corruption. Using this feature on
Intel graphics hardware is probably a bad idea.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--quirk-vbestate-restore</option></term>
<listitem>
<para>
This option saves and restores some low level hardware state
which may be invalid after suspend.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--quirk-vga-mode-3</option></term>
<listitem>
<para>
This option will try to force the video card into a standard
text mode on resume.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--quirk-save-pci</option></term>
<listitem>
<para>
Save the PCI config space for the VGA card.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--store-quirks-as-lkw</option></term>
<listitem>
<para>
Save the quirks the video adaptor required by
<command>pm-suspend</command> or
<command>pm-suspend-hybrid</command> as an .quirkdb file that
is specific to this system. The file will be saved in
<filename>/var/cache/pm-utils/last_known_working.quirkdb</filename>.
This parameter will only save the actual quirks that were
used to successfully suspend/resume a system, and will be
specific to the exact configuration of that system, including
the video hardware, video driver, and whether or not kernel
modesetting was used. If the system configuration changes, like after
a kernel upgrade, this file will be overwritten.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="files">
<title>FILES</title>
<variablelist>
<varlistentry>
<term><filename>/etc/pm/config.d</filename></term>
<listitem>
<para>
The files in this directory are evaluated in C sort order.
These files can be provided by individual packages outside
of pm-utils. If a global configuration variable is set, the
value set to will be appended to the previous value.
If any other variable is set, it will be ignored.
The syntax is simply: VAR_NAME=value.
See the
CONFIGURATION VARIABLES section for valid variables defined
by pm-utils. External packages can define others, see
their respective documentation for more information.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>/etc/pm/sleep.d</filename></term>
<term><filename>/usr/lib/pm-utils/sleep.d</filename></term>
<listitem>
<para>
Programs in these directories (called hooks) are
combined and executed in C sort order before suspend and
hibernate with as argument 'suspend' or 'hibernate'.
Afterwards they are called in reverse order with
argument 'resume' and 'thaw' respectively.
If both directories contain a similar named file,
the one in <filename>/etc/pm/sleep.d</filename> will get preference. It
is possible to disable a hook in the distribution
directory by putting a non-executable file in
<filename>/etc/pm/sleep.d</filename>, or by adding it to the HOOK_BLACKLIST
configuration variable.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>/var/log/pm-suspend.log</filename></term>
<listitem>
<para>
The log file shows what was done on the last suspend/hibernate
and resume/thaw.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="sleep_hook_ordering_convention">
<title>SLEEP HOOK ORDERING CONVENTION</title>
<variablelist>
<varlistentry>
<term>00 - 49</term>
<listitem>
<para>User and most package supplied hooks. If a hook assumes
that all of the usual services and userspace
infrastructure is still running, it should be here.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>50 - 74</term>
<listitem>
<para> Service handling hooks. Hooks that start or stop a
service belong in this range. At or before 50, hooks
can assume that all services are still enabled.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>75 - 89</term>
<listitem>
<para> Module and non-core hardware handling. If a hook
needs to load/unload a module, or if it needs to
place non-video hardware that would otherwise break
suspend or hibernate into a safe state, it belongs in
this range. At or before 75, hooks can assume all
modules are still loaded.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>90 - 99</term>
<listitem>
<para> Reserved for critical suspend hooks. </para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="config_vars">
<title>CONFIGURATION VARIABLES</title>
<para>
Configuration variables defined by pm-utils. These can be set
in any file in <filename>/etc/pm/config.d/</filename>.
</para>
<variablelist>
<varlistentry>
<term><envar>SLEEP_MODULE [=kernel]</envar></term>
<listitem>
<para>
The default suspend backend to use. Valid values are:
<variablelist>
<varlistentry>
<term><parameter>kernel</parameter></term>
<listitem>
<para>
The built-in kernel suspend/resume support.
Use this if nothing else is supported on your system.
The kernel backend is always used if nothing else is available.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>uswsusp</parameter></term>
<listitem>
<para>
If your system has support for the userspace
suspend programs (s2ram/s2disk/s2both), then use this.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>tuxonice</parameter></term>
<listitem>
<para>
If your system has support for tuxonice/suspend2, use this.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><envar>HIBERNATE_RESUME_POST_VIDEO [=no]</envar></term>
<listitem>
<para>
If video should be posted after hibernate, just like
after suspend. You should not normally need to set this.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><envar>SUSPEND_MODULES</envar></term>
<listitem>
<para>
Space separated list of modules to unload before suspend.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><envar>HOOK_BLACKLIST</envar></term>
<listitem>
<para>
Space separated list of hooks that should be disabled.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><envar>ADD_PARAMETERS</envar></term>
<listitem>
<para>
Space separated list of command line parameters that should be added.
If special quirks are needed for your system, you can add them here.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><envar>DROP_PARAMETERS</envar></term>
<listitem>
<para>
Space separated list of command line parameters that should be ignored.
If particular quirks are causing problems for your system, you can add them
here. If you want to remove all parameters use <parameter>all</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><envar>HIBERNATE_MODE</envar></term>
<listitem>
<para>
Default method to power down the system when hibernating.
If not set, the system will use the kernel default as a
default value.
Check /sys/power/disk for valid values. The default value
will be surrounded by [square brackets].
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><envar>NEED_CLOCK_SYNC</envar></term>
<listitem>
<para>
If your system clock drifts across a suspend/resume or
hibernate/thaw cycle, you should set this to true.
This will cause pm-utils to synchronize the system clock
whenever going through a sleep/wake cycle at the expense of
making suspend/resume take longer.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><envar>PM_HIBERNATE_DELAY [=900]</envar></term>
<listitem><para>
If you are using kernel suspend/resume and invoke
<command>pm-suspend-hybrid</command>, this environment variable
controls how many seconds the system will wait after going into
suspend before waking back up and hibernating. By default, this
is set to 900 seconds (15 minutes).
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="return_values">
<title>RETURN VALUES</title>
<para>
Return values less than 128 mean that pm-action failed before trying to
put the system in the requested power saving state. A return value
of 128 means that pm-action tried to put the machine in the requested power state
but failed. A return value greater than 128 means pm-action encountered an error
and also failed to enter the requested power saving state.
</para>
</refsect1>
<refsect1 id="debugging">
<title>DEBUGGING</title>
<para>
Debugging suspend/resume can be a tricky process, and is covered in
more detail in <filename>/usr/share/doc/pm-utils/README.debugging</filename>.
</para>
</refsect1>
<refsect1 id="bugs">
<title>BUGS</title>
<para>
The upstream <acronym>BTS</acronym> can be found
at <ulink url="https://bugs.freedesktop.org/"/>.
Select 'pm-utils' as product.
</para>
</refsect1>
<refsect1 id="see_also">
<title>SEE ALSO</title>
<!-- In alpabetical order. -->
<para>
<citerefentry>
<refentrytitle>s2ram</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>s2disk</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>s2both</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pm-is-supported</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pm-powersave</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>vbetool</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>radeontool</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>
|
