perfect/README.md

perfect

Branch	Status
master

CPU/GPU performance control library for benchmarking

• x86
• POWER
• Nvidia

Features

• Disable CPU turbo (linux)
• Set OS CPU performance mode to maximum (linux)
• Set GPU clocks (nvidia)
• Disable GPU turbo (nvidia)
• Flush addresses from cache (amd64, POWER)
• CUDA not required (GPU functions will not be compiled)

Installing

CMake

Ensure you have CMake 3.13+.

Add the source tree to your project and then use add_subdirectory

git submodule add git@github.com:cwpearson/perfect.git thirdparty/perfect

CMakeLists.txt

...
add_subdirectory(thirdparty/perfect)
...
target_link_libraries(your-target perfect)

Without CMake

Download the source AND

• for compiling with a non-cuda compiler:
  • add the include directory to your includes
  • add nvidia-ml to your link flags
  • add -DPERFECT_HAS_CUDA to your compile definitions
• with a CUDA compiler, just compile normally (PERFECT_HAS_CUDA is defined for you)

g++ code_using_perfect.cpp -DPERFECT_HAS_CUDA -Iperfect/include -lnvidia-ml 
nvcc code_using_perfect.cu -Iperfect/include -lnvidia-ml

If you don't have CUDA, then you could just do

g++ code_using_perfect.cpp -I perfect/include

Usage

The perfect functions all return a perfect::Result, which is defined in [include/perfect/result.hpp]. When things are working, it will be perfect::Result::SUCCESS. A PERFECT macro is also defined, which will terminate with an error message unless the perfect::Result is perfect::Result::SUCCESS.

perfect::CpuTurboState state;
PERFECT(perfect::get_cpu_turbo_state(&state));

CPU Turbo

perfect can enable and disable CPU boost through the Intel p-state mechanism or the ACPI cpufreq mechanism.

See [examples/cpu_turbo.cpp].

#include "perfect/cpu_turbo.hpp"

• Result get_cpu_turbo_state(CpuTurboState *state): save the current CPU turbo state
• Result set_cpu_turbo_state(CpuTurboState *state): restore a saved CPU turbo state
• Result disable_cpu_turbo(): disable CPU turbo
• Result enable_cpu_turbo(): enable CPU turbo
• bool is_turbo_enabled(CpuTurboState state): check if turbo is enabled

OS Performance

perfect can control the OS governor on linux.

See [examples/os_perf.cpp].

#include "perfect/os_perf.hpp"

• Result get_os_perf_state(OsPerfState *state, const int cpu): Save the current OS governor mode for CPU cpu.
• Result os_perf_state_maximum(const int cpu): Set the OS governor to it's maximum performance mode.
• Result set_os_perf_state(const int cpu, OsPerfState state): Restore a previously-saved OS governor mode.

GPU Turbo

perfect can enable/disable GPU turbo boost.

See [examples/gpu_turbo.cu]

#include "perfect/gpu_turbo.hpp"

• Result get_gpu_turbo_state(GpuTurboState *state, unsigned int idx): Get the current turbo state for GPU idx, useful to restore later.
• bool is_turbo_enabled(GpuTurboState state): Check if turbo is enabled.
• Result set_gpu_turbo_state(GpuTurboState state, unsigned int idx): Set a previously saved turbo state.
• Result disable_gpu_turbo(unsigned int idx): Disable GPU idx turbo.
• Result enable_gpu_turbo(unsigned int idx): Enable GPU idx turbo.

GPU Clocks

perfect can lock GPU clocks to their maximum values.

See [examples/gpu_clocks.cu]

#include "perfect/gpu_clocks.hpp`

• Result set_max_gpu_clocks(unsigned int idx): Set GPU idx clocks to their maximum reported values.
• Result reset_gpu_clocks(unsigned int idx): Unset GPU idx clocks.

CPU Cache

perfect can flush data from CPU caches. Unlike the other APIs, these do not return a Result because they do not fail.

See [examples/cpu_cache.cpp].

#include "perfect/cpu_cache.hpp`

• void flush_all(void *p, const size_t n): Flush all cache lines starting at p for n bytes.

Wish List

• Nvidia GPU power monitoring
• Nivida GPU utilization monitoring