Building an xNVMe Program

At this point you should have xNVMe built and installed on your system and have the system correctly configured and you should by now also be familiar with how to instrument xNVMe to utilize different backends and backend options.

With all that in place, go ahead and compile your own xNVMe program.

Example code

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_opts opts = xnvme_opts_default();
	struct xnvme_dev *dev;

	dev = xnvme_dev_open("/dev/nvme0n1", &opts);
	if (!dev) {
		perror("xnvme_dev_open()");
		return 1;
	}

	xnvme_dev_pr(dev, XNVME_PR_DEF);
	xnvme_dev_close(dev);

	return 0;
}

Compile and link

A pkg-config is provided with xNVMe, you can use pkg-config to get the required linker flags:

pkg-config --libs xnvme

This will output something like the output below, it will vary depending on the features enabled/disabled.

-Wl,--whole-archive -Wl,--no-as-needed -lxnvme -Wl,--no-whole-archive -Wl,--as-needed -pthread -lrt -lm -lnuma -luuid -laio

You can pass the arguments above to your compiler, or using pkg-config like so:

gcc ../getting_started/hello.c  $(pkg-config --libs xnvme) -o hello

Note

You do not need to link with SPDK/DPDK, as these are bundled with xNVMe. However, do take note of the linker flags surrounding -lxnvme, these are required as SPDK makes use of __attribute__((constructor)). Without the linker flags, none of the SPDK transports will work, as ctors will be “linked-out”, and xNVMe will give you errors such as device not found.

Also, xNVMe provides two different libraries, a static, and a shared library as well. Here is what the different libraries are intended for:

• libxnvme.a, this is static library version of xNVMe except it does not come with batteries included, so you have to manually link with SPDK, liburing, etc.

• libxnvme.so, this is the shared library version of xNVMe and it comes with batteries included, that is, all the third-party libraries are bundled within the shared library libxnvme.so. Thus you only need to link with xNVMe, as described above, and need not worry about linking with SPDK, liburing etc.

Using libxnvme.so is the preferred way to consume xNVMe as it comes with the correct version of the various third-party libraries and provides for a simpler link-target.

Run!

chmod +x hello
./hello

xnvme_dev:
  xnvme_ident:
    uri: '/dev/nvme0n1'
    dtype: 0x2
    nsid: 0x1
    csi: 0x0
  xnvme_be:
    admin: {id: 'nvme'}
    sync: {id: 'nvme'}
    async: {id: 'emu'}
    attr: {name: 'linux'}
  xnvme_opts:
    be: 'linux'
    mem: 'FIX-ID-VS-MIXIN-NAME'
    dev: 'FIX-ID-VS-MIXIN-NAME'
    admin: 'nvme'
    sync: 'nvme'
    async: 'emu'
    oflags: 0x4
  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
    ssw: 12

This should conclude the getting started guide of xNVMe, go ahead and explore the Tools and API.

Should xNVMe or your system still be misbehaving, then take a look in the Troubleshooting section or reach out by raising an issue, start an asynchronous discussions, or go to Discord for synchronous interaction.