-
Notifications
You must be signed in to change notification settings - Fork 26
/
README
199 lines (133 loc) · 5.54 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
# VARIORUM
[![Build Status](https://github.com/llnl/variorum/actions/workflows/github-actions.yml/badge.svg)](https://github.com/LLNL/variorum/actions)
[![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.8.0
Last Update
-----------
26 March 2024
Webpages
--------
https://variorum.readthedocs.io
## Overview
Variorum is an extensible vendor-neutral library for Linux that exposes
power and performance monitoring and control of low-level hardware dials.
## 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).
## 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: AMD, ARM, IBM, Intel, NVIDIA
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 AMD Microrchitectures:
Family 19h, Models 0~Fh and 30h ~ 3Fh (EPYC Milan and Genoa)
Supported AMD GPUs:
AMD Radeon Instinct, all models from MI50 onwards.
Supported ARM Microrchitectures:
Juno r2
Neoverse N1
Supported IBM Microrchitectures:
Power9
Supported Intel Microarchitectures:
0x2A (Sandy Bridge)
0x2D (Sandy Bridge)
0x3E (Ivy Bridge)
0x3E (Haswell)
0x4F (Broadwell)
0x9E (Kaby Lake)
0x55 (Skylake, Cascade Lake, Cooper Lake)
0x6A (Ice Lake)
0x8F (Sapphire Rapids)
Supported Intel GPUs:
Intel Arctic Sound, Intel Ponte Vecchio
Supported Nvidia Microrchitectures:
Volta
Ampere
## Testing
From within the build directory, unit tests can be executed as follows:
```
$ make test
```
Please report any failed tests to the project maintainers.
## Examples
For sample code, see the `examples/` directory.
## System Environment Requirements
This software has certain system requirements depending on what hardware you
are running on.
AMD: Running this software on AMD platforms depends on the AMD Energy Driver,
AMD HSMP driver, and AMD E-SMI library being available with the correct
permissions.
AMD GPU: Running this software on AMD GPU platforms depends on the ROCm-SMI library.
ARM: Running this software on ARM platforms depends on the Linux Hardware
Monitoring (hwmon) subsystem for access to the monitoring and control
interfaces.
IBM: Running this software on IBM platforms depends on the OPAL files being
present with R/W permissions.
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.
Nvidia: Running this software on Nvidia platforms depends on CUDA being loaded.
## Bug Tracker
Bugs and feature requests are being tracked on [GitHub
Issues](https://github.com/LLNL/variorum/issues).
## 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 GitHub Actions 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, <[email protected]> <br>
Aniruddha Marathe, <[email protected]> <br>
Tapasya Patki, <[email protected]> <br>
Barry Rountree, <[email protected]>
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
[Contributors](https://variorum.readthedocs.io/en/latest/Contributors.html).
## 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`
## Acknowledgments
This research was supported by the Exascale Computing Project (17-SC-20-SC), a
joint project of the U.S. Department of Energy's Office of Science and National
Nuclear Security Administration, responsible for delivering a capable exascale
ecosystem, including software, applications, and hardware technology, to
support the nation's exascale computing imperative.