Core

Here are the main concept and mechanics with pointers to the relevant parts of the API.

Device Interaction

Device interaction spans multiple modules, starting with the device representation by the opaque type libxnvme_dev.h.

To query a system for devices, use the xnvme_enumerate function, which invokes callback functions for each discovered device, providing the opaque handle to the device. Another way to obtain device handles is through direct calls to xnvme_dev_open, where the essential structure is the option struct (xnvme_opts).

Once a handle is available, the device geometry module (libxnvme_geo.h) is quite useful for querying constraints and capabilities. For details, see xnvme_geo. Notably, the properties mdts_nbytes and lba_nbytes are essential for constructing and submitting valid commands, as they represent a useful controller property and a useful NVM namespace property, respectively.

Lastly, the xnvme_ident structure, retrievable via xnvme_dev_get_ident, contains, among other things, information such as the command-set-identifier, which tells you which NVMe command-set is available.

Commands

Commands are encapsulated in the libxnvme_cmd.h module and xnvme_cmd_ctx. The xnvme_cmd_ctx, referred to as command-context, encapsulates both the command to be processed and the completion result once it is done. The essential command submission functions include:

• xnvme_cmd_pass

• xnvme_cmd_pass_iov

• xnvme_cmd_pass_admin

A code example is provided using these primitives for Synchronous I/O and via the libxnvme_queue.h module for Asynchronous I/O.

Buffers

The libxnvme_buf.h module provides a malloc-like interface for allocating I/O capable buffers and virtual memory.

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.