xnvmeperf

xnvmeperf is a multi-threaded async I/O benchmark for NVMe devices. It runs a time-bounded async I/O loop and reports per-device and aggregate IOPS and throughput. A verify subcommand is also provided to check data integrity by writing a known per-LBA pattern and reading it back.

Usage: xnvmeperf <command> [<args>]

Where <command> is one of:

  run              | Run a benchmark against the given devices
  verify           | Verify data integrity by writing and reading back a known pattern

See 'xnvmeperf <command> --help' for the description of [<args>]

xnvmeperf - NVMe async IO benchmark -- ver: {major: 0, minor: 7, patch: 5}

run — Benchmark

Runs async I/O against one or more NVMe devices for a fixed duration. Devices are listed as trailing positional arguments. One thread is spawned per CPU in --cpumask, e.g. 0x3 spawns two threads on CPUs 0 and 1. If there are more devices than CPUs, devices are split evenly so each thread owns a slice and runs one async job per owned device. If there are more CPUs than devices, devices are assigned round-robin so multiple threads drive the same device concurrently.

Usage: xnvmeperf run [<uri>...] [<args>]

Run a time-bounded async IO benchmark against one or more NVMe devices.
Devices are distributed across CPU threads pinned by --cpumask.
  
Positional arguments:

  [uri ...]                     ; Device URI e.g. '/dev/nvme0n1', '0000:01:00.1', '10.9.8.1.8888', '\\.\PhysicalDrive1'
  
Where <args> include:

  --iopattern STRING            ; IO pattern (read, write, randread, randwrite)
  --qdepth NUM                  ; Use given 'NUM' as queue max capacity
  --iosize NUM                  ; Use given 'NUM' as bs/iosize
  --runtime NUM                 ; Run for 'NUM' seconds
  --cpumask STRING              ; Hex CPU bitmask for thread pinning (e.g. 0x3)
  
With <args> for backend:

  [ --be STRING ]               ; xNVMe backend, e.g. 'linux', 'spdk', 'fbsd', 'macos', 'posix', 'windows'
  [ --direct ]                  ; Bypass layers
  [ --poll_io NUM ]             ; For async=io_uring, enable hipri/io-compl.polling
  [ --poll_sq NUM ]             ; For async=io_uring, enable kernel-side sqthread-poll
  [ --help ]                    ; Show usage / help

See 'xnvmeperf --help' for other commands

xnvmeperf - NVMe async IO benchmark -- ver: {major: 0, minor: 7, patch: 5}

Example — sequential read on a single device:

xnvmeperf run --iopattern read --qdepth 32 --iosize 4096 \
    --runtime 10 --cpumask 0x1 /dev/nvme0n1

Example — random write across two devices on two CPUs:

xnvmeperf run --iopattern randwrite --qdepth 64 --iosize 4096 \
    --runtime 10 --cpumask 0x3 /dev/nvme0n1 /dev/nvme1n1

verify — Data integrity check

Writes --count sequential I/Os with a per-LBA stamp pattern, then reads them back and compares against the expected data. Reports the number of mismatches and I/O errors per device.

Usage: xnvmeperf verify [<uri>...] [<args>]

For each device: writes --count sequential IOs with a per-LBA pattern,
then reads them back and compares against the expected data.
  
Positional arguments:

  [uri ...]                     ; Device URI e.g. '/dev/nvme0n1', '0000:01:00.1', '10.9.8.1.8888', '\\.\PhysicalDrive1'
  
Where <args> include:

  --iosize NUM                  ; Use given 'NUM' as bs/iosize
  --count NUM                   ; Use given 'NUM' as count
  
With <args> for backend:

  [ --be STRING ]               ; xNVMe backend, e.g. 'linux', 'spdk', 'fbsd', 'macos', 'posix', 'windows'
  [ --direct ]                  ; Bypass layers
  [ --poll_io NUM ]             ; For async=io_uring, enable hipri/io-compl.polling
  [ --poll_sq NUM ]             ; For async=io_uring, enable kernel-side sqthread-poll
  [ --help ]                    ; Show usage / help

See 'xnvmeperf --help' for other commands

xnvmeperf - NVMe async IO benchmark -- ver: {major: 0, minor: 7, patch: 5}

Example:

xnvmeperf verify --iosize 4096 --count 256 /dev/nvme0n1