qublk#

qublk is a ublk server backed by xNVMe. It creates a /dev/ublkbN block device, receives READ / WRITE / FLUSH requests from the Linux ublk_drv over io_uring, and services them through the xNVMe asynchronous command interface. Thus, any xNVMe backend, such as uPCIe or io_uring, becomes usable as an ordinary block device.

REQ_FUA and REQ_PREFLUSH are supported, as are multiple ublk hardware queues via --nqueues.

Usage: qublk <command> [<args>]

Where <command> is one of:

  run              | Serve a ublk block-device backed by the given xNVMe device

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

qublk - ublk server backed by xNVMe -- ver: {major: 0, minor: 7, patch: 5}

Requirements#

qublk is Linux-only and is built only when liburing and <linux/ublk_cmd.h> are available. At runtime it requires:

root privileges
the ublk driver, loaded with modprobe ublk_drv
for user space backends such as uPCIe, a device bound to uio_pci_generic and hugepages configured; see uPCIe

`run` — Serve a block-device#

Opens the given device URI, adds a ublk device, and serves it until SIGINT / SIGTERM, upon which it performs a clean teardown (STOP_DEV followed by DEL_DEV).

When --dev-id is not given, the kernel assigns the device identifier. When --max-io-bytes is not given, the per-IO buffer size defaults to the smaller of 1MiB and the controller MDTS.

Usage: qublk run <uri> [<args>]

Serve a ublk block-device backed by the given xNVMe device
  
Positional arguments:

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

  [ --qdepth NUM ]              ; Use given 'NUM' as queue max capacity
  [ --nqueues NUM ]             ; Number of queues per device
  [ --dev-id NUM ]              ; Use given 'NUM' as device identifier
  [ --max-io-bytes NUM ]        ; Use given 'NUM' as per-IO buffer size in bytes
  
With <args> for backend:

  [ --be STRING ]               ; xNVMe backend, e.g. 'spdk', 'libvfn', 'upcie'
  [ --help ]                    ; Show usage / help

See 'qublk --help' for other commands

qublk - ublk server backed by xNVMe -- ver: {major: 0, minor: 7, patch: 5}

Example — NVMe block device via io_uring:

qublk run /dev/nvme0n1 --be io_uring --qdepth 64

Example — user space NVMe via uPCIe, with multiple hardware queues:

qublk run 0000:01:00.0 --be upcie --qdepth 64 --nqueues 4

While qublk is running, /dev/ublkb0 is the resulting block device.

qublk#

Requirements#

run — Serve a block-device#

`run` — Serve a block-device#