/** 

* @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

*/