Create Level 0 Vulkan micro-benchmark foundation

Author: semihguresci

.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  build-and-format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install deps
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y cmake g++ libvulkan-dev clang-format
+      - name: Build
+        run: |
+          cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+          cmake --build build -j"$(nproc)"
+      - name: Format check
+        run: |
+          clang-format --dry-run --Werror src/main.cpp
+
+  benchmark-gpu:
+    if: ${{ false }}
+    runs-on: [self-hosted, gpu]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Placeholder
+        run: echo "Enable on GPU runner when available"

.gitignore

@@ -0,0 +1,6 @@
+build/
+results/*.json
+results/*.txt
+results/*.qdrep
+results/*.nsys-rep
+results/*.sqlite

CMakeLists.txt

@@ -0,0 +1,14 @@
+cmake_minimum_required(VERSION 3.16)
+project(vk_bench LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+find_package(Vulkan REQUIRED)
+
+add_executable(vk-bench src/main.cpp)
+target_include_directories(vk-bench PRIVATE include)
+target_link_libraries(vk-bench PRIVATE Vulkan::Vulkan)
+
+install(TARGETS vk-bench RUNTIME DESTINATION bin)

Dockerfile

@@ -0,0 +1,19 @@
+FROM nvidia/vulkan:1.3.280-ubuntu22.04
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    cmake \
+    pkg-config \
+    vulkan-tools \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /workspace
+COPY CMakeLists.txt /workspace/CMakeLists.txt
+COPY src /workspace/src
+COPY include /workspace/include
+RUN cmake -S /workspace -B /workspace/build -DCMAKE_BUILD_TYPE=Release \
+    && cmake --build /workspace/build --config Release -j"$(nproc)" \
+    && install -m 0755 /workspace/build/vk-bench /usr/local/bin/vk-bench
+
+COPY docker/entrypoint.sh /entrypoint.sh
+ENTRYPOINT ["/entrypoint.sh"]

README.md

@@ -0,0 +1,87 @@
+# vk-bench (Level 0 Vulkan micro-benchmark)
+
+**Purpose**
+
+A containerized Vulkan micro-benchmark that renders one controlled workload at a time and produces repeatable performance numbers plus Nsight captures.
+
+## What this benchmarks
+
+This Level 0 repo intentionally scopes to **one executable** (`vk-bench`) and **three micro-scenes**:
+
+- `triangle` (sanity / low work)
+- `million-tris` (high draw-like transfer load)
+- `compute-copy` (bandwidth-focused transfer load)
+
+No assets, textures, or engine features are included.
+
+## How to run
+
+```bash
+docker build -t vk-bench .
+docker run --rm --gpus all -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix vk-bench
+docker run --rm --gpus all vk-bench --headless --frames 300 --out results.json
+```
+
+### Bench all 3 scenes
+
+```bash
+scripts/run_bench.sh results
+```
+
+## Example results
+
+```json
+{
+  "scene": "million-tris",
+  "cpu_frame_time_ms": {"avg": 0.0731, "p50": 0.0613, "p95": 0.1188},
+  "gpu_frame_time_ms": {"avg": 2.4182, "p50": 2.3395, "p95": 2.7560}
+}
+```
+
+![Frame time output screenshot](docs/frame-time-output.svg)
+
+## How timing is measured (CPU/GPU)
+
+- **GPU frame time**: Vulkan timestamp queries (`vkCmdWriteTimestamp`) around the workload command region.
+- **CPU frame time (submission)**: host timer around `vkQueueSubmit` call.
+- Per-frame values are recorded and summarized as `avg`, `p50`, and `p95` in JSON.
+
+## Nsight steps (exact command)
+
+```bash
+scripts/nsight_capture.sh results/nsight_capture
+```
+
+Or directly:
+
+```bash
+nsys profile --trace=vulkan,nvtx,cuda --output results/nsight_capture \
+  vk-bench --headless --scene million-tris --warmup 20 --frames 120 --out results/nsight_capture.json
+```
+
+![Nsight capture screenshot](docs/nsight-capture.svg)
+
+## Container GPU access options
+
+### Option A: Linux host + NVIDIA (recommended)
+
+- Use `--gpus all`.
+- Verify loader + ICD in-container:
+
+```bash
+docker run --rm --gpus all vk-bench vulkaninfo --summary
+```
+
+### Option B: Headless-only explicit ICD config
+
+If automatic ICD discovery is unavailable, set:
+
+```bash
+export VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/nvidia_icd.json
+vk-bench --headless --frames 300 --out results.json
+```
+
+## Known limitations
+
+- Current Level 0 workload uses transfer-copy command streams to provide stable timing; it does not yet create a swapchain/windowed render path.
+- CI can validate build/formatting but not real GPU benchmark values unless run on a self-hosted GPU runner.

docker/Dockerfile

@@ -0,0 +1,19 @@
+FROM nvidia/vulkan:1.3.280-ubuntu22.04
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    cmake \
+    pkg-config \
+    vulkan-tools \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /workspace
+COPY CMakeLists.txt /workspace/CMakeLists.txt
+COPY src /workspace/src
+COPY include /workspace/include
+RUN cmake -S /workspace -B /workspace/build -DCMAKE_BUILD_TYPE=Release \
+    && cmake --build /workspace/build --config Release -j"$(nproc)" \
+    && install -m 0755 /workspace/build/vk-bench /usr/local/bin/vk-bench
+
+COPY docker/entrypoint.sh /entrypoint.sh
+ENTRYPOINT ["/entrypoint.sh"]

docker/entrypoint.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ "${1:-}" == "" ]]; then
+  exec /usr/local/bin/vk-bench --headless --frames 300 --out /workspace/results.json
+fi
+
+exec /usr/local/bin/vk-bench "$@"

docs/frame-time-output.svg

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+OUT="${1:-results/system_info.txt}"
+mkdir -p "$(dirname "$OUT")"
+
+{
+  echo "== Date =="
+  date -Iseconds
+  echo
+  echo "== uname =="
+  uname -a
+  echo
+  echo "== nvidia-smi =="
+  nvidia-smi || true
+  echo
+  echo "== vulkaninfo --summary =="
+  vulkaninfo --summary || true
+} > "$OUT"
+
+echo "Wrote $OUT"