=== pm-utils ===

What is pm-utils?

* Provides simple shell command line tools to suspend and hibernate computer
that can be used to run vendor or distro supplied scripts on suspend and resume.

Why do we need it?

* As all the main distros are re-implimenting the same thing, over and over, to
do something that's really quite trivial.
Having the common locations for stuff means that software and hardware vendors
can just install one file to do the clever stuff.

* Distros can easily add/remove functionality by installing/removing one
file into the hooks directory, for example:

- enabling and disabling standby LED's on laptop hardware 
- enabling suspend GUI's like suspend2 
- re-enabling video
- starting and stopping services that can't cope with suspending 
- re-syncing the time with ntp 
- removing and modprobing modules when needed 
- setting grub to be the default target for a hibernate-resume 
- other wacky things that need doing on specific systems

How does pm-utils work?

Pm-utils contains the following executables:

* on_ac_power - checks whether the system is on ac power 
                (see man 1 on_ac_power)
* pm-is-supported - checks whether the system is capables of suspend or resume
                    (see man 1 pm-is-supported)
* pm-powersave - This runs the power.d hooks, it takes true or false as first
                 argument, depending on whether power should be saved
* pm-suspend - This runs the sleep.d hooks with suspend as first argument
               (this is usually run by another tool, e.g. gnome-power-manager)
               and finally suspends the machine (suspend to ram)
* pm-hibernate - Thus runs the sleep.d hooks with hibernate as first argument
                 (this is usually run by another tool, e.g. gnome-power-manager)
                 and finally hibernates the machine (suspend to disk)
* pm-suspend-hybrid - not yet implemented


Pm-utils has the following directory structure in /usr/lib,
the contens of the power.d and sleep.d may vary.

/usr/lib/pm-utils/
|-- bin
|   |-- pm-action
|   |-- pm-pmu
|   `-- pm-reset-swap
|-- defaults
|-- functions
|-- power.d
|   `-- sched-powersave
`-- sleep.d
    |-- 00clear
    |-- 01grub
    |-- 05led
    |-- 10NetworkManager
    |-- 20video
    |-- 49bluetooth
    |-- 50modules
    |-- 55battery
    |-- 60sysfont
    |-- 65alsa
    |-- 90clock
    |-- 94cpufreq
    |-- 95led
    |-- 99hd-apm-restore.hook
    `-- 99video

Within the power.d and sleep.d directories, the default hooks are stored.
Adjustments can be done within /etc/pm:

/etc/pm
|-- config.d
|   |-- 02oldconfig.conf
|   `-- hd-apm-restore.conf
|-- power.d
`-- sleep.d
    `-- 95ac-power-indicator.hook

The config.d directory may contain bash scripts, that are sourced by
pm-suspend and pm-hibernate to change the beheaviour of pm-utils.
The power.d and sleep.d directories can be used to add your own hooks
to pm-utils or to overwrite the default hooks. To overwrite an hook simply
add a hook with the same name to the directory.


How do hooks work?

* You put a file in /etc/pm/sleep.d, which is executable.  When suspend or
  hibernate is called, several things happen:
  
  1) a new virtual terminal is alloced and switched to
  2) /etc/pm/config.d/* are sourced in bash filename expansion sort order.  
     These files can be provided by individual packages outside of pm-utils or
     provided by the user.
     To append to a global variable, please use BAR+=" foo", to append
     the value foo separated with a space to the variable BAR
  3) each of /etc/pm/sleep.d/* are executed in C sort order.  The first command
     line argument is "suspend" or "hibernate".  These files may source
     configuration files from /etc/pm/config.d/ on their own in order to pick
     up variables set there that aren't part of the global list. Note that
     hooks should take care to preserve any global configuration variable
     which _that_ hook will later need to use, as sourcing this config file
     will clobber any such variables.
  4) the system suspends or hibernates.
  5) some event happens to wake the machine up
  6) each of /etc/pm/sleep.d/* are executed in reverse C sort order.  The first
     command line argument is "resume" or "thaw".
  7) the system switches back to the original virtual terminal from step 1.

  That's it!

Which variables can be used to configure pm-utils?

SUSPEND_MODULES
  This is a space separted list of modules, that should be removed before sleep and
  reloaded afterwards.

HIBERNATE_MODE
  This can be used to change the mode for hibernate. Default is platform. In case you
  need to change it to shutdown, please file a bug report, because this usually is a
  bug. Other valid modes are listed with
  cat /sys/power/disk
  You can find more info about them in the kernel documentation in
  Documentation/power/*
