ACPI watch (acpiw) 0.75
(C) 2002 Oliver Diedrich (odi@heise.de)

This program may be redistributed under the terms of the
GNU Public License (GPL), see www.gnu.org


README
=======

1. What it does
----------------

'ACPI watch' displays the directory tree under /proc/acpi and the content of the
files in /proc/acpi and its subdirectories. It monitors the files for changes
and displays changed file entries. It should give you an idea not only which
information is presented in /proc/acpi, but also which part of this information
is static and which part changes dynamically.

Additionally, acpiw extracts and displays ACPI related messages from the syslog
as well as some basic information about your system. This information, together
with the data gathered from /proc/acpi, can be saved in a file.


2. Installation
----------------

- "make gui" to create a comfortable gtk2 GUI version (needs gtk2 libraries and
  header files)

- "make text" to create a console version that also displays most of the
  /proc/acpi information, but in a less clear format. Some (less important)
  functions of the GUI version are missing.

- For your convenience, the gtkacpiw and acpiw binaries are included. For the
  GUI version, the gtk+ libraries must be installed.

- In order to get the relevant ACPI information, you have to load the OSPM
  kernel modules. This is done by the acpi_on script and needs root privileges.

- To get all ACPI and system information, 'ACPI watch' should be started with
  root privileges.


3. Usage
---------

Console version:

acpiw [-u n] [-s filename]
-u n: set update interval to n seconds (default: 5 seconds)
-s filename: save ACPI data in filename

You'll first get a dump of the complete /proc/acpi tree. Each n seconds, the
/proc/acpi tree is rescanned, and changed entries are displayed. Stop the
program by pressing Ctrl-C. If '-s' was given on the command line, data are
saved.


GUI version:

gtkacpiw [-u n]
-u n: set update interval to n seconds (default: 5 seconds)

On the left side of the window, you'll see the /proc/acpi tree. Blue color
denotes files that can be written to, e.g. /proc/acpi/sleep to bring the system
to one of the S* states.

Three types of items displayed:

(1) directories, e.g. /proc/acpi/processor/
(2) files, e.g. /proc/acpi/processor/CPU0/info
(3) entries (lines) in the files at the end of each subtree, e.g.
    /proc/acpi/processor/CPU0/info -> "limit interface". Most of the entries
    consist of two parts, a label ("limit interface") and a value ("no"). In
    the tree, you always see the recent value of each entry.

gtkacpiw periodically rescans the /proc/acpi tree. If an entry changes, it is
printed in red color. Additionally, its subtree is painted red. For example,
if the "temperature" entry in /proc/acpi/thermal_zone/THR2/temperature changes,
the file temperature and the directories THR2 and thermal_zone in the tree are
painted red.

If you double click a directory or file, its subtree is expanded.
"View->Expand/collapse tree" in the menu expands or collapses the whole tree.

If you select (single click) a file entry, its value is displayed on the right
side. If the value has changed since the start of the program, all old values
are displayed together with a time stamp when each value has been recorded. You
can see, for example, how fast the battery of your laptop discharges, which
ACPI events happened within the last 15 minutes, or how the temperature has
increased since you started your kernel build.

"View->ACPI info" displays the ACPI related messages in the syslog.
"View->system info" displays some system information. You need root privileges
to read most of this information.

To save the ACPI data to a file, use the "File->save" dialog. When quitting
gtkacpi without saving the data, you won't be warned; so take care if you want
to permanently collect your ACPI data.


4. Bugs
--------

- ACPI watch does not run run forever because it eats up your memory.
  I observed that gtkacpiw tends to stop updating or to throw lots of error
  messages 20 to 30 hours after having been started (but it never damaged the
  system). Maybe using a slower update interval than the default 5 seconds
  increases this time.

- X11 arguments (-display, -geometry, and so on) are not honored.

- ACPI watch ignores /proc/acpi entries that appear after the programm had been
  started, e.g. by loading OSPM modules after starting ACPI watch.