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_ctx

  • Submit 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