pwrkap -- Energy Use Monitor and Power Cap Enforcement Tools
version 7.30 (2009-01-12)

Written by Darrick J. Wong.
(C) Copyright IBM Corp. 2008-2009

This software is covered under the GNU GPL v2; see COPYING for details.

Overview
--------
pwrkap is a set of utilities that attempt to enforce an upper limit on the
amount of power consumed by a set of devices at any given time.  The intent
of the program is ensure that *power* use does not go above a given level;
it is NOT to optimize the amount of *energy* consumed for a particular
workload, though it may or may not end up doing that too.  There are two
components to this program--a self-training daemon that manages power domains
and a GUI program (that can run from a separate monitoring station) that
plots the power cap and use over time to show the effects of the program.

Requirements
------------
Your computer needs to have at least one power meter and some devices with
power management capabilities.  Obviously, the power meter should measure the
devices' power consumption.  A few more specifications:

The systems that you want to run the scripts on...

...must have Python 2.4 or newer.

...must have python bindings for GTK+ and matplotlib installed if you want
   to use the GUI program.

The power meter...

...must be readable by a user-space app.  Currently, pwrkap supports the
   IPMI sensor interface via ipmitool and the IBM PowerExecutive sensors
   via the ibmpex/ibmaem hwmon drivers.  The software can also use discharging
   ACPI batteries as a makeshift power meter, though this has not been as well
   tested.  Support for more devices should not be too difficult to add, but
   the author does not have any such devices.

...must not be too terribly slow to read.  The software was written under the
   assumption that a power meter can be read in under 15 seconds.

Power managed devices...

...must be controllable from user-space.  At the moment, pwrkap only knows
   how to talk to CPUs that implement CPU frequency control.  There are more
   devices (network cards, displays, disks, PCI devices, etc) that could be
   supported.

...must export utilization data.  pwrkap's new power allocation algorithm
   takes device utilization into account when figuring out what to do to try
   to match the cap.

Specific Requirements
---------------------
 - Red Hat Enterprise Linux 5, SUSE Linux Enterprise Server 10, Ubuntu 8.04.
 - Linux kernel 2.6 or newer.
 - CPU that supports CPU frequency changing via sysfs.

Installation
------------
# tar -xzf pwrkap.tar.gz
# cd pwrkap
# make install

You may also want to start pwrkap whenever the system is booted.  The 

To run pwrkap when the system is started up, create an init script:

* Debian/Ubuntu:
  1. Copy debian/init-script from the source tarball to /etc/init.d/pwrkap
  2. Run update-rc.d pwrkap defaults to set up the init script 

* Red Hat/SUSE:
  1. Copy redhat/init-script from the source tarball to /etc/init.d/pwrkap
  2. Run chkconfig pwrkap on to set up the init script. 

Usage
-----
Upon starting up for the first time, pwrkap does not know what the power
use profiles of the devices in the system, and will attempt to train itself.
During operation, the pwrkap daemon runs in closed-loop mode, using system
state snapshots to supplement the profile seed data.

# <Start a load test on all power-managed devices>
# pwrkap_main [-d] [-w]

-d: Debug mode, i.e. don't run as a daemon
-w: Start the web server (runs on port 8036)
-f: Simulate a power-managed system

The database will be saved in /etc/pwrkap_$HOSTNAME.bin when the program
exits.  By default, the daemon listens for the pwrkap client on port 9410.

To watch and control pwrkap, there are two clients.  The first is a command
line client that started its life as a debugging tool.  As such, it dumps
power snapshot data directly to standard output whenever the daemon sends data;
its one command is "<domainname> cap <new_cap>".

If you have a lot of machines, you may want to use the aggregator to reduce
the load on the monitoring workstation.  The aggregator reads a configuration
file to determine how to assemble domains; the format of the config file is:

   domain $ip_to_listen_on $port_to_listen $name_of_aggregate_domain consists of:
   system $pwrkap_server $pwrkap_server_port $pwrkap_domain_name

Then start the aggregator by running this:

$ pwrkap_aggregate config_file

You can then connect to the aggregator with a client to monitor the aggregated
systems as if they were one system.

$ pwrkap_cli machine_name[:port]

Command format: $domain_name command args
$domain_name is the name of the domain to alter.
command = {dump, cap}
    dump:           Dump transition tables to daemon console.
    cap $new_cap:    Set a new power cap.

The preferred method of interacting with pwrkap, however, is the gtk client.
It can connect to a large number of systems and can plot power cap, power use,
and device utilization data.

$ pwrkap_gtk machine_name[:port] [machine_name[:port]...]

Be forewarned that the graph gets a bit slow if there are a lot of machines
connected (>200), so the display of it is disabled by default.  If enabled,
the graphs show you the last few minutes' worth of power cap, power use, and
device utilization.

Wrap-Up
-------
I hope you enjoy pwrkap!  Details about the design and innards are in the
file DESIGN.
