Core#
This section describes the core xNVMe API, which includes functions (and headers) that will most likely be part of every program using the xNVMe library.
For the most part, xNVMe follows the NVMe specification (represented in C
in libxnvme_spec.h). However, there are a couple abstractions added on
top to make programming easier. The most essential of these are the structs:
xnvme_cmd_ctx and xnvme_queue.
The xnvme_cmd_ctx, referred to as command-context, encapsulates both the NVMe
command to be processed and the completion result once it is done.
The xnvme_queue, referred to as command-queue, is initialized with a number of
command-contexts equal to the capacity. When you want to submit a command, you
get a command-context from the command-queue. When you want to process completed
commands you poke the command-queue, and a callback function is called for every
command-context. At the end of the callback function, you should put the
command-context back into the command-queue.
The typical flow for doing asynchronous IO can be reduced to the following:
Open device with
xnvme_dev_open()Initialize command-queue with
xnvme_queue_init()Set queue callback with
xnvme_queue_set_cb()Get command-context from queue with
xnvme_queue_get_cmd_ctxSubmit an IO command, e.g., with
xnvme_nvm_read()(see libxnvme_nvm.h for more options)Get completion with
xnvme_queue_poke()Terminate command-queue with
xnvme_queue_term()
Examples of both asynchronous and synchronous IO in C can be seen here: C API Usage Examples.
The following gives a brief description of the header files in the core API:
libxnvme_adm.h includes functions for construction and submission of NVMe admin commands
libxnvme_buf.h includes functions for allocating and freeing memory with respect to the backend
libxnvme_cmd.h includes the command-context and functions related to it
libxnvme_dev.h includes functions for enumerating and opening devices
libxnvme_nvm.h includes functions for construction and submission of NVMe IO commands
libxnvme_queue.h includes the command-queue and functions related to it