/** 
* @file:   README
* CVS:     $Id$
* @author: Philip Vaccaro (ICL/UTK)
* @defgroup papi_components Components
* @brief Component Specific Readme file: powercap
*/

/** @page component_readme Component Readme

@section Component Specific Information

powercap/

The PAPI powercap component supports measuring and capping power usage
on recent Intel architectures (Sandybridge or later) using the powercap interface exposed
through the Linux kernel.

--------------------------------------------------
MEASURING AND CAPPING POWER

The powercap sysfs interface exposes energy counters and R/W regsiter-like
power settings. The counters and R/W settings apply to a power domain on a system.

For example, a single KNL chip exposes package power and DRAM power information. 
On KNL this component can be used to read package/DRAM energy counters and set package/DRAM power limits.
There are two limits in the package domain and a single limit in the DRAM domain. The two limits 
in the package domain correspond to long/short term limits. 

For all supported processors, each package/DRAM power limit has an associated
time window. The time window for each limit can also be changed, which changes the enforcement time window of
that limit.

These counters and settings are exposed though this PAPI component and can be accessed just like any normal PAPI
counter. Running the "powercap_basic" test in the test directory will list all the events on a system. There is also a 
"powercap_limit" test in the test directory that shows how a power limit is applied.
    
--------------------------------------------------
CONFIGURING THE PAPI POWERCAP COMPONENT

At the higher src dirctory, configure with this component
    % cd <papi_dir>/src
    % ./configure --with-components="powercap"
Follow the standard PAPI build (make) instructions
    % make 
To use the module, make sure that the libraries are accessible.  
    % export LD_LIBRARY_PATH=${PAPIDIR}/src:${PAPIDIR}/src/libpfm4/lib:${LD_LIBRARY_PATH}
To check the installation, the following should show some available counters 
    % ./utils/papi_native_avail | grep powercap
    
--------------------------------------------------
SYSTEM SETUP

The actions described below will generally require superuser ability.
Note, these actions may have security and performance consequences, so
please make sure you know what you are doing.

    Ensure the "CONFIG_POWERCAP" and "CONFIG_INTEL_RAPL" kernel
    modules are enabled.

    Use chmod to set site-appropriate access permissions (e.g. 766)
    for /sys/class/powercap/*

--------------------------------------------------