/** 
* @file:   README
* CVS:     $Id$
* @author: Asim YarKhan
*          yarkhan@icl.utk.edu
* @defgroup papi_components Components
* @brief Component Specific Readme file: libmsr
*/

/** @page component_readme Component Readme

@section Component Specific Information

libmsr/

NOTE: This libmsr component is an initial version, and has been tested
with libmsr (v0.1.17 11/2015) and the msr_safe kernel module (19/2015
version).
  https://github.com/scalability-llnl/libmsr
  https://github.com/scalability-llnl/msr-safe


The PAPI libmsr component supports measuring and capping power usage
on recent Intel architectures using the RAPL interface exposed through
MSRs (model-specific registers).  

Lawrence Livermore National Laboratory has released a library (libmsr)
designed to provide a simple, safe, consistent interface to several of
the model-specific registers (MSRs) in Intel processors.  The problem
is that permitting open access to the MSRs on a machine can be a
safety hazard, so access to MSRs is usually limited.  In order to
encourage system administrators to give wider access to the MSRs on a
machine, LLNL has released a Linux kernel module (msr_safe) which
provides safer, white-listed access to the MSRs.

PAPI has created a libmsr component that can provide read and write
access to the information and controls exposed via the libmsr library.

This PAPI component introduces a new ability for PAPI; it is the first
case where PAPI is writing information to a counter as well as reading
the data from the counter.


--------------------------------------------------
ENABLE ACCESS TO THE MSRS (MODEL SPECIFIC REGISTERS)

https://github.com/scalability-llnl/msr-safe

To use this component, the system will need to provide access to Model
Specific Registers (MSRs) from user space.  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.

  OPTION 1: EITHER: Enable MSR access using msr-safe
    Install the msr-safe module from LLNL, 
       lsmod | grep msr        (should show msr_safe)
    Use chmod to set site-appropriate access permissions (e.g. 766) for 
       /dev/cpu/*/msr_safe /dev/cpu/msr_batch /dev/cpu/msr_whitelist
    Load a whitelist appropriate for your machine
       e.g. for SandyBridge: 
         cat msr-safe/whitelists/wl_062D > /dev/cpu/msr_whitelist
    
  OPTION 2: OR: Enable MSR access via the filesystem and elevated permissions.
    Or, enable access to the standard MSRs filesystem
    
    For Linux kernel version < 3.7, using only file system checks
         chmod 666 /dev/cpu/*/msr
    
    For Linux kernel version >= 3.7, using capabilities
         chmod 666 /dev/cpu/*/msr
         The final executable needs CAP_SYS_RWIO to open MSR device files [1]
         setcap cap_sys_rawio=ep <user_executable>
         The final executable cannot be on a shared network partition.
    
    The dynamic linker on most operating systems will remove variables
    that control dynamic linking from the environment of executables
    with extended rights, such as setuid executables or executables
    with raised capabilities. One such variable is
    LD_LIBRARY_PATH. Therefore, executables that have the RAWIO
    capability can only load shared libraries from default system
    directories.
    
    One can work around this restriction by either installing the
    shared libraries in system directories, linking statically against
    those libraries, or using the -rpath linker option to specify the
    full path to the shared libraries during the linking step.


--------------------------------------------------
COMPILE THE LIBMSR LIBRARY TO ACCESS THE MSRS

https://github.com/scalability-llnl/libmsr

Get the library and follow the instructions to build using CMake.
This library contains a subdirectory, test, which will exercise the
functionality.

--------------------------------------------------
CONFIGURING THE PAPI LIBMSR COMPONENT

Set libmsr library and header files by configuring within the component.
    % cd <papi_dir>/src/components/libmsr
    % ./configure --with-libmsr-incdir=<PATH> --with-libmsr-libdir=<PATH> 
Then, at the higher src dirctory, configure with this component
    % cd <papi_dir>/src
    % ./configure --with-components="libmsr"
    or if you want to specify the compilers and enable debug.
    % ./configure CC=gcc F77=gfortran --with-debug --with-components="libmsr"
Finally, 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:${LIBMSRDIR}/lib:${LD_LIBRARY_PATH}
To check the installation, the following should show some available counters 
    % ./utils/papi_native_avail | grep libmsr
To check the installation, the following should some counter values
    % ./utils/papi_native_avail -e "libmsr:::PKG_WATTS:PACKAGE0"
    % ./utils/papi_command_line  "libmsr:::PKG_WATTS:PACKAGE0"
    % ./utils/papi_command_line  "libmsr:::PKG_DELTA_ENERGY:PACKAGE0"


--------------------------------------------------
USE THE PAPI LIBMSR COMPONENT 

See the components/libmsr/utils/README file for instructions.  This
test demonstrates how to write power constraints, and gives an
estimate of the overheads for reading and writing information to the
RAPL MSRs.


[1] http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=c903f0456bc69176912dee6dd25c6a66ee1aed00

*/