Low-level NVM Express Mastery Galore!
libvfn is zero-dependency library for interacting with PCIe-based NVMe devices
from user-space using the Linux kernel vfio-pci driver.
The core of the library is excessively low-level and aims to allow controller verification and testing teams to interact with the NVMe device at the register and queue level. However, it does also provide a range of utility functions to issue commands and polling for their completions along with helpers for mapping memory in the commands as well as managing allocation of I/O Virtual Address through VFIO.
Issuing a crafted command using the high-level API can be as simple as:
#include <vfn/nvme.h>
#include <nvme/types.h>
int main(void) {
struct nvme_ctrl ctrl;
union nvme_cmd cmd;
void *vaddr;
nvme_init(&ctrl, "0000:01:00.0", NULL);
pgmap(&vaddr, NVME_IDENTIFY_DATA_SIZE);
cmd.identify = (struct nvme_cmd_identify) {
.opcode = nvme_admin_identify,
.cns = NVME_IDENTIFY_CNS_CTRL,
};
nvme_admin(&ctrl, &cmd, vaddr, NVME_IDENTIFY_DATA_SIZE, NULL);
printf("vid 0x%"PRIx8"\n", ((struct nvme_id_ctrl *)vaddr)->vid);
return 0;
}The above example uses libnvme for NVM Express data structure and constant definitions.
However, the true power of the library is only evident when using the lower level interfaces. See the cmb and perf examples.
The core libvfn library has zero dependencies apart from the included CCAN
components in ccan/. However, the included (and separately licensed)
examples and device tests depend on libnvme for type definitions.
To build the documentation, Sphinx is required.
libvfn uses the meson build system.
meson setup build ninja -C build
Use the included vfntool to detach a device from the kernel nvme driver
and attach it to the vfio-pci driver.
./build/tools/vfntool/vfntool -d 0000:01:00.0
Verify that everything works as expected using one of the included examples.
./build/examples/identify -d 0000:01:00.0
Except where otherwise stated, all software contained within this repository is
dual licensed under the GNU Lesser General Public License version 2.1 or later
or the MIT license. See COPYING and LICENSE for more information.
However, note that libvfn uses a number of components from the Comprehensive C
Archive Network (CCAN) which are separately licensed. See ccan/licenses for
a list of included licenses and ccan/ccan/*/LICENSE for the license used by
an individual component.
All software in the examples, tools, scripts and tests
directories are licensed under the GNU General Public License version 2 or
later. See {examples,tools,scripts,tests}/COPYING.
Finally, all documentation in the docs directory is dual licensed under the
GNU General Public License version 2 or later or the Creative Commons
Attribution 4.0 International license. Note however, that this only applies to
the raw rst files, since files resulting from processing by the documentation
build system may contain content tanken from files with other licenses.