|
Packit |
577717 |
/**
|
|
Packit |
577717 |
* @file: README
|
|
Packit |
577717 |
* CVS: $Id$
|
|
Packit |
577717 |
* @author: Asim YarKhan
|
|
Packit |
577717 |
* yarkhan@icl.utk.edu
|
|
Packit |
577717 |
* @defgroup papi_components Components
|
|
Packit |
577717 |
* @brief Component Specific Readme file: libmsr
|
|
Packit |
577717 |
*/
|
|
Packit |
577717 |
|
|
Packit |
577717 |
/** @page component_readme Component Readme
|
|
Packit |
577717 |
|
|
Packit |
577717 |
@section Component Specific Information
|
|
Packit |
577717 |
|
|
Packit |
577717 |
libmsr/
|
|
Packit |
577717 |
|
|
Packit |
577717 |
NOTE: This libmsr component is an initial version, and has been tested
|
|
Packit |
577717 |
with libmsr (v0.1.17 11/2015) and the msr_safe kernel module (19/2015
|
|
Packit |
577717 |
version).
|
|
Packit |
577717 |
https://github.com/scalability-llnl/libmsr
|
|
Packit |
577717 |
https://github.com/scalability-llnl/msr-safe
|
|
Packit |
577717 |
|
|
Packit |
577717 |
|
|
Packit |
577717 |
The PAPI libmsr component supports measuring and capping power usage
|
|
Packit |
577717 |
on recent Intel architectures using the RAPL interface exposed through
|
|
Packit |
577717 |
MSRs (model-specific registers).
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Lawrence Livermore National Laboratory has released a library (libmsr)
|
|
Packit |
577717 |
designed to provide a simple, safe, consistent interface to several of
|
|
Packit |
577717 |
the model-specific registers (MSRs) in Intel processors. The problem
|
|
Packit |
577717 |
is that permitting open access to the MSRs on a machine can be a
|
|
Packit |
577717 |
safety hazard, so access to MSRs is usually limited. In order to
|
|
Packit |
577717 |
encourage system administrators to give wider access to the MSRs on a
|
|
Packit |
577717 |
machine, LLNL has released a Linux kernel module (msr_safe) which
|
|
Packit |
577717 |
provides safer, white-listed access to the MSRs.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
PAPI has created a libmsr component that can provide read and write
|
|
Packit |
577717 |
access to the information and controls exposed via the libmsr library.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
This PAPI component introduces a new ability for PAPI; it is the first
|
|
Packit |
577717 |
case where PAPI is writing information to a counter as well as reading
|
|
Packit |
577717 |
the data from the counter.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
|
|
Packit |
577717 |
--------------------------------------------------
|
|
Packit |
577717 |
ENABLE ACCESS TO THE MSRS (MODEL SPECIFIC REGISTERS)
|
|
Packit |
577717 |
|
|
Packit |
577717 |
https://github.com/scalability-llnl/msr-safe
|
|
Packit |
577717 |
|
|
Packit |
577717 |
To use this component, the system will need to provide access to Model
|
|
Packit |
577717 |
Specific Registers (MSRs) from user space. The actions described
|
|
Packit |
577717 |
below will generally require superuser ability. Note, these actions
|
|
Packit |
577717 |
may have security and performance consequences, so please make sure
|
|
Packit |
577717 |
you know what you are doing.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
OPTION 1: EITHER: Enable MSR access using msr-safe
|
|
Packit |
577717 |
Install the msr-safe module from LLNL,
|
|
Packit |
577717 |
lsmod | grep msr (should show msr_safe)
|
|
Packit |
577717 |
Use chmod to set site-appropriate access permissions (e.g. 766) for
|
|
Packit |
577717 |
/dev/cpu/*/msr_safe /dev/cpu/msr_batch /dev/cpu/msr_whitelist
|
|
Packit |
577717 |
Load a whitelist appropriate for your machine
|
|
Packit |
577717 |
e.g. for SandyBridge:
|
|
Packit |
577717 |
cat msr-safe/whitelists/wl_062D > /dev/cpu/msr_whitelist
|
|
Packit |
577717 |
|
|
Packit |
577717 |
OPTION 2: OR: Enable MSR access via the filesystem and elevated permissions.
|
|
Packit |
577717 |
Or, enable access to the standard MSRs filesystem
|
|
Packit |
577717 |
|
|
Packit |
577717 |
For Linux kernel version < 3.7, using only file system checks
|
|
Packit |
577717 |
chmod 666 /dev/cpu/*/msr
|
|
Packit |
577717 |
|
|
Packit |
577717 |
For Linux kernel version >= 3.7, using capabilities
|
|
Packit |
577717 |
chmod 666 /dev/cpu/*/msr
|
|
Packit |
577717 |
The final executable needs CAP_SYS_RWIO to open MSR device files [1]
|
|
Packit |
577717 |
setcap cap_sys_rawio=ep <user_executable>
|
|
Packit |
577717 |
The final executable cannot be on a shared network partition.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
The dynamic linker on most operating systems will remove variables
|
|
Packit |
577717 |
that control dynamic linking from the environment of executables
|
|
Packit |
577717 |
with extended rights, such as setuid executables or executables
|
|
Packit |
577717 |
with raised capabilities. One such variable is
|
|
Packit |
577717 |
LD_LIBRARY_PATH. Therefore, executables that have the RAWIO
|
|
Packit |
577717 |
capability can only load shared libraries from default system
|
|
Packit |
577717 |
directories.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
One can work around this restriction by either installing the
|
|
Packit |
577717 |
shared libraries in system directories, linking statically against
|
|
Packit |
577717 |
those libraries, or using the -rpath linker option to specify the
|
|
Packit |
577717 |
full path to the shared libraries during the linking step.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
|
|
Packit |
577717 |
--------------------------------------------------
|
|
Packit |
577717 |
COMPILE THE LIBMSR LIBRARY TO ACCESS THE MSRS
|
|
Packit |
577717 |
|
|
Packit |
577717 |
https://github.com/scalability-llnl/libmsr
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Get the library and follow the instructions to build using CMake.
|
|
Packit |
577717 |
This library contains a subdirectory, test, which will exercise the
|
|
Packit |
577717 |
functionality.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
--------------------------------------------------
|
|
Packit |
577717 |
CONFIGURING THE PAPI LIBMSR COMPONENT
|
|
Packit |
577717 |
|
|
Packit |
577717 |
Set libmsr library and header files by configuring within the component.
|
|
Packit |
577717 |
% cd <papi_dir>/src/components/libmsr
|
|
Packit |
577717 |
% ./configure --with-libmsr-incdir=<PATH> --with-libmsr-libdir=<PATH>
|
|
Packit |
577717 |
Then, at the higher src dirctory, configure with this component
|
|
Packit |
577717 |
% cd <papi_dir>/src
|
|
Packit |
577717 |
% ./configure --with-components="libmsr"
|
|
Packit |
577717 |
or if you want to specify the compilers and enable debug.
|
|
Packit |
577717 |
% ./configure CC=gcc F77=gfortran --with-debug --with-components="libmsr"
|
|
Packit |
577717 |
Finally, follow the standard PAPI build (make) instructions
|
|
Packit |
577717 |
% make
|
|
Packit |
577717 |
To use the module, make sure that the libraries are accessible.
|
|
Packit |
577717 |
% export LD_LIBRARY_PATH=${PAPIDIR}/src:${PAPIDIR}/src/libpfm4/lib:${LIBMSRDIR}/lib:${LD_LIBRARY_PATH}
|
|
Packit |
577717 |
To check the installation, the following should show some available counters
|
|
Packit |
577717 |
% ./utils/papi_native_avail | grep libmsr
|
|
Packit |
577717 |
To check the installation, the following should some counter values
|
|
Packit |
577717 |
% ./utils/papi_native_avail -e "libmsr:::PKG_WATTS:PACKAGE0"
|
|
Packit |
577717 |
% ./utils/papi_command_line "libmsr:::PKG_WATTS:PACKAGE0"
|
|
Packit |
577717 |
% ./utils/papi_command_line "libmsr:::PKG_DELTA_ENERGY:PACKAGE0"
|
|
Packit |
577717 |
|
|
Packit |
577717 |
|
|
Packit |
577717 |
--------------------------------------------------
|
|
Packit |
577717 |
USE THE PAPI LIBMSR COMPONENT
|
|
Packit |
577717 |
|
|
Packit |
577717 |
See the components/libmsr/utils/README file for instructions. This
|
|
Packit |
577717 |
test demonstrates how to write power constraints, and gives an
|
|
Packit |
577717 |
estimate of the overheads for reading and writing information to the
|
|
Packit |
577717 |
RAPL MSRs.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
|
|
Packit |
577717 |
[1] http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=c903f0456bc69176912dee6dd25c6a66ee1aed00
|
|
Packit |
577717 |
|
|
Packit |
577717 |
*/
|