/** 
* @file:   README
* CVS:     $Id$
* @author: Damien Genet (ICL/UTK)
* @defgroup papi_components Components
* @brief Component Specific Readme file: sensors_ppc
*/

/** @page component_readme Component Readme

@section Component Specific Information

sensors_ppc/

The PAPI sensors_ppc component supports reading system metrics
on recent IBM PowerPC architectures (Power9 and later) using the OCC memory exposed
through the Linux kernel.

--------------------------------------------------
MEASURING SYSTEM

The opal/exports sysfs interface exposes sensors and counters as read only
registers. The sensors and counters apply to the Power9.

These counters and settings are exposed though this PAPI component and can be
accessed just like any normal PAPI counter. Running the "sensors_ppc_basic"
test in the tests directory will report a very limited sub-set of information
on a system. For instance, voltage received by socket 0, and its extrema since
the last reboot.

Note: /sys/firmware/opal/exports/occ_inband_sensors is RDONLY for root. PAPI
library will need read permissions to access it.

--------------------------------------------------
CONFIGURING THE PAPI SENSORS_PPC COMPONENT

At the higher src dirctory, configure with this component
    % cd <papi_dir>/src
    % ./configure --with-components="sensors_ppc"
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 sensors_ppc

--------------------------------------------------
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.

    Use chmod to set site-appropriate access permissions (e.g. 440),
    use chown to set group ownership,
    for /sys/firmware/opal/exports/occ_inband_sensors

    And finally, have your user added to said group, granting you read access

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