README

# VARIORUM

[![Build Status](https://travis-ci.com/LLNL/variorum.svg?branch=dev)](https://travis-ci.com/LLNL/variorum)
[![Read the Docs](https://readthedocs.org/projects/variorum/badge/?version=latest)](http://variorum.readthedocs.io)

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

version 0.4.1


Last Update
-----------
2 April 2021


Webpages
--------
https://variorum.readthedocs.io


## Overview

Variorum is an extensible vendor-neutral library for exposing power and
performance monitoring and control of low-level hardware knobs.


## Documentation
To get started building and using Variorum, check out the full documentation
here:

https://variorum.readthedocs.io


## Getting Started

Installation is simple. You will need [CMAKE](http://www.cmake.org) 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 and JANSSON. The build system will first
check for a specified local install of these dependencies, then it will check
if it has been pre-installed. If it can find neither, it will clone and build
the dependency 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 and Microarchitecture Support
Variorum has support for an increasing number of platforms and
microarchitectures:

Platforms supported: Intel, IBM, NVIDIA, ARM

Supported Intel Microarchitectures:

    0x2A (Sandy Bridge)
    0x2D (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 Microrchitectures:

    Power9

Supported Nvidia Microrchitectures:

    Volta (requires [CUDA Toolkit[(https://developer.nvidia.com/cuda-downloads))

Supported ARM Microrchitectures:

    Juno r2

## Testing

From within the build directory, unit tests can be executed as follows:
```
    $ make test
```
Please report any failed tests to the project team at
<variorum-maintainers@llnl.gov>.


## Examples

For sample code, see the `examples/` directory.


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


## System Environment Requirements
This software has certain system requirements depending on what hardware you
are running on.

Intel: Running this software on Intel platforms 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](https://github.com/LLNL/msr-safe) kernel module, but running as root
(or going through the bother of adding the capabilities to the binaries) is
another option.

IBM: Running this software on IBM platforms depends on the OPAL files being
present with R/W permissions.

Nvidia: Running this software on Nvidia platforms depends on CUDA being loaded.

ARM: Running this software on ARM platforms depends on the Linux Hardware
Monitoring (hwmon) subsystem for access to the monitoring and control
interfaces.


## Bug Tracker
Bugs and feature requests are being tracked on [GitHub
Issues](https://github.com/LLNL/variorum/issues).


## Mailing List
If you have questions about Variorum, identify a bug, or have ideas about
expanding the functionality of Variorum and are interested in contributing to
its development, please send an email to our open mailing list at
<variorum-users@llnl.gov>. We are very interested in improving Variorum and
exploring new use cases.

If you are interested in keeping up with Variorum or communicating with its
developers and users, please join our open mailing list by sending an email as
follows:

```
To: listserv@listserv.llnl.gov
Subject: (leave this field empty)

Subscribe variorum-users
```


## Contributing
We welcome all kinds of contributions: new features, bug fixes, documentation,
edits, etc.!

To contribute, make a pull request, with `dev` as the destination branch. We
use Travis to run CI tests, and your branch must pass these tests before being
merged.

See the [CONTRIBUTING](./CONTRIBUTING.md) for more information.


## Authors
Stephanie Brink, <brink2@llnl.gov> <br>
Aniruddha Marathe, <marathe1@llnl.gov> <br>
Tapasya Patki, <patki1@llnl.gov> <br>
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](./AUTHORS).


## License
Variorum is released under the MIT license. For more details, see the
[LICENSE](./LICENSE) and [NOTICE](./NOTICE) files.

SPDX-License-Identifier: MIT

`LLNL-CODE-789253`