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.
-L/usr/local/lib/x86_64-linux-gnu -lxnvme
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 librarylibxnvme.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
subnqn: ''
xnvme_be:
admin: {id: 'nvme'}
sync: {id: 'nvme'}
async: {id: 'emu'}
attr: {name: 'linux'}
xnvme_opts:
be: 'linux'
mem: 'posix'
dev: 'FIX-ID-VS-MIXIN-NAME'
admin: 'nvme'
sync: 'nvme'
async: 'emu'
xnvme_geo:
type: XNVME_GEO_UNKNOWN
npugrp: 0
npunit: 0
nzone: 0
nsect: 0
nbytes: 0
nbytes_oob: 0
tbytes: 0
mdts_nbytes: 0
lba_nbytes: 0
lba_extended: 0
ssw: 0
pi_type: 0
pi_loc: 0
pi_format: 0
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.