hipBench

KO | EN

gitlite — search

#javascript #hacktoberfest #golang #go #machine-learning #rust #macos #windows #cli #kubernetes #vue #pytorch #security #mcp

(★ 10)

HIP Kernel Benchmarking Library

hipBench Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Overview

> [!NOTE]
> This README is derived from the original nvbench project's README. More care is necessary to remove/modify parts that are only applicable to the original version.

This project is a work-in-progress. Everything is subject to change.
hipBench is an open source project. It is derived from 
[NVBench](https://github.com/NVIDIA/nvbench).

hipBench is a C++17 library designed to simplify HIP kernel benchmarking. It
features:

* [Parameter sweeps](docs/benchmarks.md#parameter-axes): a powerful and
  flexible "axis" system explores a kernel's configuration space. Parameters may
  be dynamic numbers/strings or [static types](docs/benchmarks.md#type-axes).
* [Runtime customization](docs/cli_help.md): A rich command-line interface
  allows [redefinition of parameter axes](docs/cli_help_axis.md), CUDA/AMD device
  selection, locking GPU clocks, changing output formats, and more.
* [Throughput calculations](docs/benchmarks.md#throughput-measurements): Compute
  and report:
  * Item throughput (elements/second)
  * Global memory bandwidth usage (bytes/second and per-device %-of-peak-bw)
* Multiple output formats: Currently supports markdown (default) and CSV output.
* [Manual timer mode](docs/benchmarks.md#explicit-timer-mode-nvbenchexec_tagtimer):
  (optional) Explicitly start/stop timing in a benchmark implementation.
* Multiple measurement types:
  * Cold Measurements:
    * Each sample runs the benchmark once with a clean device L2 cache.
    * GPU and CPU times are reported.
  * Batch Measurements:
    * Executes the benchmark multiple times back-to-back and records total time.
    * Reports the average execution time (total time / number of executions).
  * [CPU-only Measurements](docs/benchmarks.md#cpu-only-benchmarks)
    * Measures the host-side execution time of a non-GPU benchmark.
    * Not suitable for microbenchmarking.

# Supported Compilers and Tools

- CMake > 3.30.4
- ROCm == 7.0.2
- g++: 7 -> 12
- clang++: 9 -> 20
- cl.exe: 2019 -> 2022 (19.29, 29.39)
- Headers are tested with C++17 -> C++20.

# Known limitations

Generally, we aim for feature parity with NVBench.
Currently, we do not support CUDA devices with HIP's CUDA backend.
If this feature is relevant to your project, please let us know by opening a feature request on Github.

# Getting Started

## Minimal Benchmark

A basic kernel benchmark can be created with just a few lines of HIP C++:

```cpp
void my_benchmark(nvbench::state& state) {
  state.exec([](nvbench::launch& launch) {
    my_kernel<<<num_blocks, 256, 0, launch.get_stream()>>>();
  });
}
NVBENCH_BENCH(my_benchmark);
```

See [Benchmarks](docs/benchmarks.md) for information on customizing benchmarks
and implementing parameter sweeps.

## Command Line Interface

Each benchmark executable produced by hipBench provides a rich set of
command-line options for configuring benchmark execution at runtime. See the
[CLI overview](docs/cli_help.md)
and [CLI axis specification](docs/cli_help_axis.md) for more information.

## Examples

This repository provides a number of [examples](examples/) that demonstrate
various hipBench features and usecases:

- [Runtime and compile-time parameter sweeps](examples/axes.cu)
- [CPU-only benchmarking](examples/cpu_only.cu)
- [Enums and compile-time-constant-integral parameter axes](examples/enums.cu)
- [Reporting item/sec and byte/sec throughput statistics](examples/throughput.cu)
- [Skipping benchmark configurations](examples/skip.cu)
- [Benchmarking on a specific stream](examples/stream.cu)
- [Adding / hiding columns (summaries) in markdown output](examples/summaries.cu)
- [Benchmarks that sync CUDA devices: `nvbench::exec_tag::sync`](examples/exec_tag_sync.cu)
- [Manual timing: `nvbench::exec_tag::timer`](examples/exec_tag_timer.cu)

### Building Examples

To build the examples:
```
mkdir -p build
cd build
cmake -DNVBench_ENABLE_EXAMPLES=ON -DCMAKE_HIP_ARCHITECTURES=gfx90a .. && make
```
Be sure to set `CMAKE_HIP_ARCHITECTURES` based on the GPU you are running on.

Examples are built by default into `build/bin` and are prefixed with `nvbench.example`.

<details>
  <summary>Example output from `nvbench.example.throughput`</summary>

```
# Devices

## [0] `AMD Instinct MI210`
* CU Architecture: AMD Instinct MI210
* Number of CUs: 104
* CU Max Clock Rate: 1700 MHz
* Global Memory: 65446 MiB Free / 65520 MiB Total
* Global Memory Bus Peak: 1638 GB/sec (4096-bit DDR @1600MHz)
* Max Shared Memory: 64 KiB/CU, 64 KiB/Block
* L2 Cache Size: 8192 KiB
* Maximum Active Blocks: 32/CU
* Maximum Active Threads: 2048/CU, 1024/Block
* Available Registers: 65536/CU, 65536/Block
* ECC Enabled: No

# Log

Run:  throughput_bench [Device=0]
Warn: Current measurement timed out (15.00s) while over noise threshold (1.26% > 0.50%)
Pass: Cold: 0.262392ms GPU, 0.267860ms CPU, 7.19s total GPU, 27393x
Pass: Batch: 0.261963ms GPU, 7.18s total GPU, 27394x

# Benchmark Results

## throughput_bench

### [0] AMD Instinct MI210

| NumElements |  DataSize  | Samples |  CPU Time  | Noise |  GPU Time  | Noise | Elem/s  | GlobalMem BW  | BWPeak | Batch GPU  | Batch  |
|-------------|------------|---------|------------|-------|------------|-------|---------|---------------|--------|------------|--------|
|    16777216 | 64.000 MiB |  27393x | 267.860 us | 1.25% | 262.392 us | 1.26% | 63.940G | 476.387 GiB/s | 58.77% | 261.963 us | 27394x |
```

</details>

## Demo Project

To get started using hipBench with your own kernels, consider trying out
the [NVBench Demo Project](https://github.com/allisonvacanti/nvbench_demo).

`nvbench_demo` provides a simple CMake project that uses hipBench to build an
example benchmark. It's a great way to experiment with the library without a lot
of investment.

# Contributing

Contributions are welcome!

## Tests

To build `nvbench` tests:
```
export CMAKE_PREFIX_PATH=/opt/rocm/lib/cmake
mkdir -p build
cd build
cmake -DNVBench_ENABLE_TESTING=ON .. && make
```

Tests are built by default into `build/bin` and prefixed with `nvbench.test`.

To run all tests:
```
make test
```
or
```
CMAKE_PREFIX_PATH=/opt/rocm/lib/cmake ctest .
```
# License

hipBench is an open source project. It is derived from [NVBench](https://github.com/NVIDIA/nvbench).
The original [NVBench](https://github.com/NVIDIA/nvbench) is released under the Apache 2.0 License with LLVM exceptions.
Any new files and modifications made to exisiting files by AMD are distributed under MIT.
See [LICENSE](./LICENSE).

# Scope and Related Projects

hipBench will measure the CPU and AMD GPU execution time of a ***single
host-side critical region*** per benchmark. It is intended for regression
testing and parameter tuning of individual kernels.

hipBench is focused on evaluating the performance of HIP kernels. It also provides
CPU-only benchmarking facilities intended for non-trivial CPU workloads, but is
not optimized for CPU microbenchmarks. This may change in the future, but for now,
consider using Google Benchmark for high resolution CPU benchmarks.

hipBench

hipBench Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

hipBench

hipBench Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README