README

This software is a reference implementation of the PowerAPI. The main purpose 
for the creation of the reference was to test the viability of API functions
during the design of the API specification. The reference is also being used
to test implementation details such as how to interface with different types
of hardware and communication between agents. The reference is a work in
progress and only a subset of the functions listed in the specification have
been implemented.

The main component of this software is libpwr (located in directory pwr). 
Any application that uses the PowerAPI must link against libpwr.so. 
It implements the API and is designed as a hardware neutral framework. The
framework accesses platform specific power measurement and control via plugins.
The plugins are implemented as dynamic libraries (located in directory plugins).
There are currently plugins for several platforms as well as a dummy plugin
used for development. The dummy plugin is trivial and a good place to look when
implementing a plugin for a new platform. 

libpwr is configured via an XML file describing the hardware it is interacting 
with. XML was chosen for expedient development not performance. libpwr has an
object that interfaces with the XML file via TinyXML-2. TinyXML-2 is 
included with this distribution and is already integrated into this
software package.  The original software can also be found at 
"https://github.com/leethomason/tinyxml2".

The reference also explores accessing the API via a scripting language such as
Python and remote PowerAPI calls. The Python binding is done via Swig and is
located in directory swig. The remote API calls are supported via a daemon and
ULXMLRPCPP. The daemon is located in directory daemon. ULXMLRPCPP was chosen
for expedient development and is not a good choice for large scale. The intent
is that ULXMLRPCPP could be easily replaced with another IPC  mechanism.
ULXMLRCPPP is not included with this distribution and can be found at
"http://ulxmlrpcpp.sourceforge.net". ULXMLRCPPP version 1.7.5 is currently
being used.

The examples directory contains simple “C” and Python programs that can be 
examined to get a feeling for how one would use the Power API. Note that the
execution of example programs rely on environment variables POWERAPI_CONFIG and
POWERAPI_ROOT. POWERAPI_CONFIG tells the PowerAPI library what system
configuration file to use. POWERAPI_ROOT tells the PowerAPI library its entry
point. Consult the run scripts in examples on how to set these variables.
Debug printouts are part of libpwr and can be enabled by 1) enabling DEBUG in
pwr/Makefile and setting _DbgFlag in pwr/cntxt.cc. 

This software has been compiled on:
	Mac OSX 10.9.5 / gcc version 4.6.4 (MacPorts gcc46 4.6.4_3)
	Linux 2.6.32 / gcc version 4.4.6 (Red Hat 4.4.6-3) 
    Linux 3.0.101 / gcc version 4.3.4 (SUSE Linux)

If you have questions or comments email contact-powerapi@sandia.gov.