
                 PowerManagement Control Scripts
    ----------------------------------------------------------
    Matthias Grimm <matthiasgrimm@users.sourceforge.net>, 2004

Introduction
------------
A powermanagement daemon can't be prepared for all aspects of power
management for a whole bunch of different systems. The hardware is
not always the same, used software needs some special care or the
user wants a special job done at a certain event. All this aspects
can't be handled in one single program without help. This help is
usually a highly adaptable shell script.

Most tasks that have to be done after a power management event are
common tasks needed from most people. For example someone with an
IDE hard disk may want to spin down the disk after some idle time.
Those scripts for common tasks useful for many people without change
are collected in the PowerManagement Control Scripts.

As mentioned this package contains a lot of common scripts to assist
the power management handling of the daemon. But on a certain computer
not all are needed. To control which scripts should be executed and
which not, the scripts are stored in different locations:

  ./scripts.d place for all scripts in package. Scripts in this
              directory are referenced to as 'slave scripts' later in
	      this document
  ./event.d   place for scripts to be executed

If following directories exist the containing scripts will be executed
just before suspend and after wakeup additionally to those in ./event.d:

  ./suspend.d contains scripts to be launched before suspend
  ./resume.d  contains scripts to be launched after wakeup

In avoidance of storing each script twice the directories ./event.d,
./suspend.d and ./resume.d should only contain symbolic links to the
real scripts in ./scripts.d.

The master script will not differentiate between suspend-to-ram and
suspend-to-disk. In both cases the scripts in suspend.d will be executed.
A third argument will help to distinguish the two cases. Each script now
may decide to handle the two cases seperately or not.

If the calling sequence matters, use link name with leading numbers.
For example:

   suspend.d/20nfs  -> ../scripts.d/nfs     umount filesystems first
   suspend.d/21eth0 -> ../scripts.d/eth0    then shut down eth0

   resume.d/20eth0 -> ../scripts.d/eth0     first bring up eth0 before
   resume.d/21nfs  -> ../scripts.d/nfs      mounting filesystems again


The Master Script
-----------------
The master script will be called by the powermanagement daemon and will
then launch all slave scripts in ./event.d. The main task of this script
is to translate the given arguments from the daemon into those the slave
scripts understand. In some cases it might be useful that the master
script itself complete a task directly without calling any slave script.

To adapt the PMCS (PowerManagement Control Scripts) to a new
powermanagement daemon, a new master script for this deamon have to be
provided. Nothing else have to be changed. The slave scripts can be used
without any change.

Master scripts for some common powermanagement daemons are already 
included:  pmcs-pbbuttonsd, pmcs-pmud and pmcs-apmd.

The Slave Scripts
-----------------
As already mentioned the slave scripts actual do the work. They are
stored in .scripts.d and the active ones are linked to ./event.d. Each
scripts except at least two arguments; some accept three:

  arg $1: contains the action code or the power policy that should be
          set. Possible keywords are:
	  'powersave'   power policy, minimum power consumption
	  'custom'      power policy, user defined, something in between
	  'performance' power policy, maximum performance
	  'suspend'     action, prepare for sleep
	  'resume'      action, wakeup from sleep
	  'cover-open'  action, cover has been opened
	  'cover-close' action, cover has been closed
	    
  arg $2: power source. following keywords are possible:
          'ac'          the computer runs on AC power
	  'battery'     the computer runs on battery power

  arg $3: argument for arg $1 depending on arg $1. Following arguments
          have been defined yet:
	  'ram'|'disk'  for 'suspend' and 'resume'
	  'open'        for 'cover-open'
	  'close'       for 'cover-close'
	  
The arguments 'cover-open' / 'cover-closed' and 'suspend' / 'resume' 
are mutually exclusive. The 'cover-*' scripts will only be called if
no suspend mode is chosen at all or the chosen suspend mode is not
supported on this machine.

The third argument of the 'cover-*' events will allow to combine those
two commands in the slave scripts. It might happen in future that the
two commands 'cover-open' and 'cover-close' will be replaced by one
single command called 'cover'. New scripts should take this into account.

The Configuration
-----------------
Most slave scripts allow some options to configure. In avoidance
of setting those options in each slave script all configuration
options are collected in the file 'pmcs-config' that will be sourced
by all slave scripts. This 'pmcs-config' contains shell variables 
containing the option. This variables will then be used in the
slave scripts.

To get the full option list of a slave script please refer the
scripts documentation or look into the script itself.

Each pmcs-config variable should be unique and carry a certain prefix:

  general_      if the variable defines a policy independent option
  powersave_    if the option belongs to 'powersave' policy
  custom_       if the option belongs to 'custom' policy
  performance_  if the option belongs to 'performance' policy

Licence
-------
All scripts and attached material are published under the terms of
the GNU Public Licence (GPL).

