Quick Start

Retrieve the xNVMe repository from GitHUB:

# Clone the xNVMe repos
git clone https://github.com/OpenMPDK/xNVMe.git --recursive
cd xnvme

# make: auto-configure xNVMe, build third-party libraries, and xNVMe itself
make

# make install: install via the apt package manager
sudo make install-deb

# make install: install in the "usual" manner
sudo make install

Note

The repository uses git-submodules, so make sure you are cloning with --recursive, if you overlooked that, then invoke git submodule update --init --recursive

If the above causes any issues, then have a look at Building xNVMe from source. Or, you can grab a binary release of xNVMe from the GitHUB release page.

API: Hello NVMe Device

This “hello-world” example prints out device information of the NVMe device at /dev/nvme0n1.

To use xNVMe include the libxnvme.h header in your C/C++ source:

#include <stdio.h>
#include <libxnvme.h>

int main(int argc, char **argv)
{
	struct xnvme_dev *dev = xnvme_dev_open("/dev/nvme0n1");
	if (!dev) {
		perror("xnvme_dev_open");
		return 1;
	}
	xnvme_dev_pr(dev, XNVME_PR_DEF);
	xnvme_dev_close(dev);

	return 0;
}

Run!

chmod +x hello
./hello
xnvme_dev:
  xnvme_ident:
    trgt: '/dev/nvme0n1'
    schm: 'file'
    opts: ''
    uri: 'file:/dev/nvme0n1'
  xnvme_cmd_opts:
    mask: '00000000000000000000000000000001'
    iomd: 'SYNC'
    payload_data: 'DRV'
    payload_meta: 'DRV'
    csi: 0x0
    nsid: 0x1
    ssw: 12
  xnvme_geo:
    type: XNVME_GEO_CONVENTIONAL
    npugrp: 1
    npunit: 1
    nzone: 1
    nsect: 2097152
    nbytes: 4096
    nbytes_oob: 0
    tbytes: 8589934592
    mdts_nbytes: 520192
    lba_nbytes: 4096
    lba_extended: 0

CLI: Hello Device

Most of the C API is wrapped in a suite of command-line interface (CLI) tools. The equivalent of the above example is readily available from the xnvme command:

xnvme info /dev/nvme0n1

Which should output information similar to:

xnvme_dev:
  xnvme_ident:
    trgt: '/dev/nvme0n1'
    schm: 'file'
    opts: ''
    uri: 'file:/dev/nvme0n1'
  xnvme_cmd_opts:
    mask: '00000000000000000000000000000001'
    iomd: 'SYNC'
    payload_data: 'DRV'
    payload_meta: 'DRV'
    csi: 0x0
    nsid: 0x1
    ssw: 12
  xnvme_geo:
    type: XNVME_GEO_CONVENTIONAL
    npugrp: 1
    npunit: 1
    nzone: 1
    nsect: 2097152
    nbytes: 4096
    nbytes_oob: 0
    tbytes: 8589934592
    mdts_nbytes: 520192
    lba_nbytes: 4096
    lba_extended: 0

With the basics in place, have a look at the C APIs: Examples, follow the Tutorials, and dive deeper into the C APIs and experiment with the Tools.