Mock NVIDIA telemetry stack

Mock nvidia gpus in Linux for monitoring software that reads NVIDIA telemetry through NVML or nvidia-smi. It does not emulate CUDA, PCI hardware, kernel ioctls, MIG provisioning, or GPU computation.

Build and test

make
make test

Requirements: Linux, gcc, make, Python 3.

Run

export MOCK_NVIDIA_STATE="$PWD/scenarios/loaded.json"
export LD_LIBRARY_PATH="$PWD/build${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
export PATH="$PWD/bin:$PATH"

nvidia-smi
nvidia-smi --query-gpu=uuid,name,utilization.gpu,memory.used,memory.total,temperature.gpu,power.draw,power.limit --format=csv,noheader,nounits
python3 examples/read_nvml.py

Run the loader diagnostic before testing a third-party program:

./bin/diagnose-loader

The build provides all common loader names: libnvidia-ml.so.1, libnvidia-ml.so, libnvml.so.1, and libnvml.so. NVTOP currently documents that it loads libnvml.so, rather than the canonical NVIDIA filename.

For an application linked to NVML:

LD_LIBRARY_PATH="$PWD/build" MOCK_NVIDIA_STATE="$PWD/scenarios/thermal.json" ./monitor

If the application loads an absolute path, mount build/libnvidia-ml.so.1 over that library inside an isolated test container. Never replace the host driver library.

LD_LIBRARY_PATH is commonly removed by sudo and ignored by confined Snap or setuid applications. A systemd service also needs both LD_LIBRARY_PATH and MOCK_NVIDIA_STATE in its unit environment. Run the tool directly as the same user while establishing basic compatibility.

Modes

Point MOCK_NVIDIA_STATE at a scenario file to render a different operating face through nvidia-smi or the NVML library. Each mode is independent and can be swapped at runtime.

Idle

scenarios/idle.json — a GPU at rest. Low GPU and memory utilization, an idle temperature, fans near their floor, and a minimal power draw. Clocks sit at their baseline speed.

Loaded

scenarios/loaded.json — a GPU running a busy compute workload. High GPU utilization, boosted graphics and memory clocks, and most of VRAM consumed.

Thermal

scenarios/thermal.json — a GPU at its thermal and power ceiling. Temperature approaches maximum, fans run at 100%, power draw is capped at the limit, the performance state sags, and ECC reports errors.

Multi-GPU

scenarios/4gpus.json — four GPUs under a mixed workload: two H100s in a busy state and two L40S blades, one loaded and one idle. GPU order in the array determines the NVML index.

State

The library reloads the JSON file when its modification time changes. Switch scenarios without restarting the monitored process:

cp scenarios/thermal.json /tmp/mock-gpu.json
export MOCK_NVIDIA_STATE=/tmp/mock-gpu.json
# edit or replace /tmp/mock-gpu.json while the collector runs

Supported state fields are demonstrated in scenarios/loaded.json. Memory is specified in MiB and power in watts. NVML returns bytes and milliwatts as the real API does.

For multiple GPUs, place one to eight device objects in gpus:

{
  "gpus": [
    {
      "name": "NVIDIA H100 80GB HBM3",
      "uuid": "GPU-FAKE-0001",
      "pci_bus_id": "00000000:01:00.0",
      "gpu_utilization_percent": 94,
      "vram_total_mib": 81559,
      "vram_used_mib": 74200,
      "temperature_c": 78,
      "power_draw_w": 610,
      "power_limit_w": 700
    },
    {
      "name": "NVIDIA L40S",
      "uuid": "GPU-FAKE-0002",
      "pci_bus_id": "00000000:02:00.0",
      "gpu_utilization_percent": 20,
      "vram_total_mib": 46068,
      "vram_used_mib": 9000,
      "temperature_c": 51,
      "power_draw_w": 160,
      "power_limit_w": 350
    }
  ]
}

See scenarios/4gpus.json for a complete mixed-load example. GPU order in the array determines the NVML index. UUID and PCI bus ID must be unique.

Implemented NVML subset

• initialization and shutdown
• device count and handles by index or UUID
• name, UUID, serial and PCI information
• utilization, memory, temperature and fan speed
• power draw and power limit
• graphics, SM and memory clocks
• performance state and compute mode
• ECC mode and aggregate error count
• running compute process count
• driver and NVML versions

Unsupported calls are absent. Add any required function to src/mock_nvml.c using the same state loader and NVIDIA NVML function signature.

Limitations

This package validates collectors, dashboards, alerts and recommendation logic. It cannot validate the NVIDIA kernel driver, CUDA workloads, PCI discovery, DCGM diagnostics, ECC hardware, throttling behavior or real process accounting.

Support and Donations

Support the project and other projects like this by supporting the creator, feel free to reach out for other ways to contribute.

• EVM: 0x6e8e3c2b31424266e7cff59e910df1587c317427 (ERC-20, BEP-20, TRC-20, AVAX-C, SPL, MATIC, POL, ARB, BASE, TON)
• BTC: bc1qzzvcguvqjc6qhwe2y5vy38w2zke7hksukjhm68
• LTC: MPfm5QLKH1r9XxgWmH75Gyps4LDfX5c53L
• SOL: GEaCMpnyM8tB5BU4RMuLm6tgMr3q9FgMHodxDxxAGby
• DOGE: DPkJheSBTTkFv9oxnEwGsfvrcCvEWDVhVY