.TH POWERSAVE 8 "Oct 2003" "Version 0.1"

.SH NAME
powersave \- get/set power saving states of the machine, influence power management
.SH SYNOPSIS
.B powersave {-f|-l|-A} {-u|-U|-m} -[crbBsSaTFVtx] [-p percent] [-v
level] [-e scheme_name]
[ options ]
.SH DESCRIPTION
.BI powersave
provides a command line interface to various power saving related 
functionalities of your machine.
Powersave supports APM, ACPI and cpu-frequency scaling (speedstep, powernow, ...) features as well as
some ide disk power saving functionalities.
Take care that the appropriate modules for the features you want to use are loaded or compiled
into the kernel.
Some options may work correctly only with the latest kernels.
Some options are quite hardware dependent and you should be able to test their support
by using this tool.
For automatic global power management please install and start the
powersave daemon on your system.
Once you started the daemon you should only use the powersave daemon depending functions
or functions which just provide information about the system.
The cpufreq control functions like performance-, powersave-, dynamic-speed are used
by the powersave daemon. You may want to use them, but remember that
powersave policy should be configured in the configuration files and your settings
may be overridden by the daemon.

.SH OPTIONS THAT NEED A RUNNING POWERSAVE DAEMON

Be aware that the powersave system group exists and that 
users allowed to use these functions are part of the powersave group.

.TP
.I  --suspend-to-disk -U
Sets the machine into suspend (APM) or S4/"Suspend to Disk" (ACPI) mode
.TP
.I  --suspend-to-ram -u
Sets the machine into suspend (APM) or S3/"Suspend to RAM" (ACPI) mode
.TP
.I  --standby -m
Sets the machine into standby (APM) or S1/"Standby" (ACPI) mode
.TP
.I  --performance-speed   -f
Makes the daemon to set the machine fixed to the the highest supported frequency.
This option needs your hardware to support CPU frequency scaling (SpeedStep/PowerNow).
.TP
.I  --powersave-speed   -l
Makes the daemon to set the machine fixed to the lowest supported frequency.
.TP
.I  --dynamic-speed    -A
Makes the daemon to adjust the frequency of your machine dynamically.
This is always a good solution (for battery and AC plugged in).
It saves a lot of power and reduces the noise of your fan (if controlled).
You should not recognise any loss of performance.
.TP
.I  --ondemand-speed    -o
Gives cpufreq control to the kernel. The kernel will adjust the speed/frequency
instead of the daemon. This is known to have slightly better performance values,
but mostly worse power saving results (depending on the configs which also behave
slightly different). It's also known as not that field tested as the dynamic-speed
setting.
.TP
.I --cpufreq-state -c
Asks the daemon for the current cpufrequency scaling method:

.TP
.I battery-state  -s
Asks the daemon for the current battery state: NORMAL, WARNING, LOW or CRITICAL.

.SH OPTIONS THAT NEED ACPI WORKING AND THE APPROPRIATE KERNEL MODULES LOADED

.TP
.I --set-throttling-percent -p
Evaluates how much throttling states your machine supports and
sets the appropriate state according to your value.
Please specify the value in percent you want to throttle the CPU.
A value of 0 means no throttling, maximum CPU power.
Avoid values higher than 80%, because this could easily freeze your machine!
You need superuser rights for this option.
This funtion throttles all CPUs of your machine.

.TP
.I --get-throttling-info -t
Prints out the current and available throttling state of each
CPU in the system.

.TP
.I --apm-acpi -S
Evaluates whether your system supports APM or ACPI.

.TP
.I --battery-info       -b
Prints out remaining battery capacity in percent and 
remaining lifetime of battery. Remaining lifetime should
only give sensible values when working on battery power source.
It may happen that the remaining life time cannot be read 
immediately after switching to battery power, try it again 
after some seconds.
Depending whether your BIOS is buggy remaining lifetime 
or even remaining percent can not be calculated.
Multiple batteries will be sumerized to a total.

.TP
.I --extended-battery-info   -B
Prints out remaining battery capacity in percent and 
remaining lifetime for each battery. This only works if
your system supports ACPI

.TP
.I ac-status-info -a
Evaluate whether AC adapter is plugged in or if you are
currently working on battery power.

.TP
.I get-thermal-info   -T
iterates available thermal devices and prints current 
temperature and defined trippoints

.TP
.I get-fan-info       -F
detects which fan is on/off

.TP
.I list-schemes       -x
List all power schemes. Also shows which one is the current active one
and which are activated if power source changes to AC or battery power.
Configuration files for schemes are by default
located in @configdir@/scheme_*. A scheme
changes the power save policy of the powersave daemon. Changing the
power source (AC/Battery) normally switches the power policy/scheme. Use -e option
to switch between schemes manually.

.TP
.I get-scheme-description  -X
Show the description of a scheme.

.TP
.I set-active-scheme  -e
See above. Use -x to list all schemes you can switch to.

.TP
.I get-brightness       -K
Get the current brightness level of the display if supported. This works
at the moment with many toshiba, sony and asus notebooks.

.TP
.I get-brightness-levels   -L
Get number of supported brightness levels.

.TP
.I set-brightness   -k
Set the current brightness level. Get abailable brightness levels with -L
or give character 'u' for "brightness up" or character 'd' for "brightness
down"

.SH GENERAL OPTIONS - NEED NO KERNEL MODULS OR A RUNNING POWERSAVE DAEMON

.TP
.I --verbose -v
Set the debug level, allowed values: 0-31
Depending on how the binary was compiled
the output is written to stdout/stderr or directly
forwarded to the syslog daemon (default) or totally discarded.
So you normally should check /var/log/messages to check for
errors
1  Error
2  Warning
4  Diag
8  Info
16 Debug
e.g.  Error + Warning: 1 + 2 -> 3

.TP
.I --version -V
prints the current compiled version of the package

.TP
.I --calc-CPU-frequency -r
prints out the current CPU frequency of the machine using 
the time stamp counter (tsc) register
This should be a similar value as in /proc/cpuinfo, however
the value there could be wrong if you encounter a kernel bug.
If you are fiddling around with SpeedStep or PowerNow you should
rely on this value;
This currently only works on some single processor machines (i686, x86_64)

.SH RETURN VALUES
All options return 0 on success and any other value on failure.

Except:

--apm-acpi -S returns -1 if it fails, 2 for an APM machine and 1 for ACPI support!

--ac-status-info -a returns -1 if it fails, 2 for on AC and 1 for on battery power!

--cpufreq-state -c returns 1 if system is in maximum frequency (performance) mode, 
2 if system is in minimum frequency (powersave) mode and 3 if frequency is adjusted
depending on CPU usage (dynamic mode)

--battery-state,
returns 1 if battery is in normal state, 2 if in warning, 3 if in low
and 4 if battery is in critical state

--cpu-enable -E <x>
Enables a single CPU. CPUs start from 0, but 0 can't be disabled because
it runs the main timer.

--cpu-disable -D <x>
Disables a single CPU. CPUs start from 0, but 0 can't be disabled because
it runs the main timer.

This might change when using multiple options at once (see next).

.SH MULTIPLE OPTIONS
Several parameters can be passed at once.
The order of the output of each parameter complies to the order as
listed above.
If an error occurs, the return value will be EXIT_FAILURE(1),
or lower than zero.
If no error occured the return value will 0.
If a parameter with a special return value (see above) is used zero will be overridden
 with the meaning described above.
If several parameters with a special return value are passed, the last listed parameter with
a special return value will represent the return value.

.SH ACCESS TO DAEMON
This section affects parameters stated above under OPTIONS THAT NEED A RUNNING POWERSAVE DAEMON.
The connect is done by a UNIX socket.
Who is allowed to connect and query the daemon is passed to the daemon when the daemon is started.
This is in the /etc/init.d/powersaved script and is done with the -a parameter.
(see manpage of powersaved).

.SH BUGS
calculating frequency could be wrong if processor is in higher power save (C-)states 
(C3 and above normally). This is normal.
.SH AUTHOR
.B powersave
has been written by Thomas Renninger <mail@renninger.de>
.PP
Inspiration and code parts partly come from the acpid, apmd and cpufreqd 
packages. Many thanks to all developers who helped to create this software.
.SH SEE ALSO
.BR powersaved(8)
.PP 
ACPI kernel modules: ac, battery, button, thermal, processor, fan
.PP 
cpufreq kernel modules, see kernel sources /usr/src/linux/Documentation/cpu-freq