Skip to content
Tool for hardware-level feature control
C++ C Python CMake HTML M4 Other
Branch: dev
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
host-configs
src
.gitignore
.readthedocs.yml
AUTHORS
CONTRIBUTING.md
ChangeLog
LICENSE
NOTICE
README
README.md
TODO
VERSION

README.md

VARIORUM

Build Status Read the Docs

Welcome to Variorum, a platform-agnostic library exposing monitor and control interfaces for several features in hardware architectures.

version 0.1.0

Last Update

6 November 2019

Webpages

https://variorum.readthedocs.io

Overview

Variorum provides general interfaces to provide privileged functionality for monitoring and controlling various hardware-level features of multiple hardware architectures.

Getting Started

Installation is simple. You will need CMAKE version 2.8 or higher and GCC. Variorum does not support in-source builds. In most cases, the installation is as follows:

    $ cd variorum/
    $ mkdir build && mkdir install
    $ cd build/
    $ cmake -DCMAKE_INSTALL_PREFIX=../install ../src
    $ make
    $ make install

Note that Variorum depends on hwloc. The build system will first check for a specified local hwloc install, then it will check for a pre-installed hwloc. If it can find neither, it will clone and build hwloc from source (will fail on machines without internet access).

By default BUILD_DOCS=ON, so the build system looks for Doxygen and Sphinx. If you do not want to include these dependencies, simply toggle BUILD_DOCS=OFF in CMakeCache.txt or run the CMake command as follows:

$ cmake -DCMAKE_INSTALL_PREFIX=../install -DBUILD_DOCS=OFF ../src

CMake Host Config Files

We provide configuration files for specific systems to pre-populate the cache. This configuration file will define various compilers, and paths to hwloc installs. These can be used as follows:

    $ cd variorum/
    $ mkdir build && mkdir install
    $ cd build/
    $ cmake -C ../host-configs/your-local-configuration-file.cmake ../src
    $ make

Platform Support

Currently supported architectures are Intel Xeons (server processors). The library technically supports all Intel processors based on these architectures, but some features may vary between platforms.

Supported Intel Architectures:

0x2A (Sandy Bridge)
0x3E (Ivy Bridge)
0x3E (Haswell)
0x4F (Broadwell)
0x9E (Kaby Lake)
0x55 (Skylake)

If you are unsure of your architecture number, check the "model" field in lscpu or /proc/cpuinfo (note that it will not be in hexadecimal).

Supported IBM Architectures:

Power9

Testing

From within the build directory, unit tests can be executed individually. Please report any failed tests to Stephanie Brink at brink2@llnl.gov.

Examples

For sample code, see the examples/ directory.

Documentation

From within the build directory, documentation can be built with the following target:

    $ make docs

Additionally, set BUILD_DOCS=ON in CMakeLists.txt.

Support Additional Intel Platforms

  1. Under Intel/ directory, create a .h and .c header and source file for the respective platform. This will contain features specific to that platform, which may or may not exist in previous generations.
  2. Modify Intel/config_intel.c to set the function pointers for the respective platform.
  3. Include the new header file in Intel/config_architecture.h.

Notes

This software depends on the files /dev/cpu/*/msr being present with R/W permissions. Recent kernels require additional capabilities. We have found it easier to use our own msr-safe kernel module, but running as root (or going through the bother of adding the capabilities to the binaries) is another option.

Bug Tracker

Bugs and feature requests are being tracked on GitHub Issues.

Contributing

Please submit any bugfixes or feature improvements as pull requests. See the CONTRIBUTING for more information.

Contact

Stephanie Brink, brink2@llnl.gov
Aniruddha Marathe, marathe1@llnl.gov
Tapasya Patki, patki1@llnl.gov
Barry Rountree, rountree@llnl.gov

Please feel free to contact the developers with any questions or feedback.

We collect names of those who have contributed to Variorum over the years. See the current list in AUTHORS.

License

Variorum is released under the MIT license. For more details, see the LICENSE and NOTICE files.

SPDX-License-Identifier: MIT

LLNL-CODE-789253

You can’t perform that action at this time.