xnvme

Header

/**
 * Cross-platform I/O library for NVMe devices
 *
 * Copyright (C) Simon A. F. Lund <simon.lund@samsung.com>
 * Copyright (C) Klaus B. A. Jensen <k.jensen@samsung.com>
 * SPDX-License-Identifier: Apache-2.0
 *
 * @file libxnvme.h
 */
#ifndef __LIBXNVME_H
#define __LIBXNVME_H

#ifdef __cplusplus
extern "C" {
#endif

#include <inttypes.h>
#include <stdint.h>
#include <stdlib.h>
#include <stdbool.h>
#include <sys/types.h>
#include <sys/uio.h>
#include <libxnvme_be.h>
#include <libxnvme_dev.h>
#include <libxnvme_buf.h>
#include <libxnvme_geo.h>
#include <libxnvme_ident.h>
#include <libxnvme_spec.h>
#include <libxnvme_util.h>

/**
 * xNVMe options
 *
 * @see xnvme_dev_open()
 *
 * @struct xnvme_opts
 */
struct xnvme_opts {
	const char *be;    ///< Backend/system interface to use
	const char *dev;   ///< Device manager/enumerator
	const char *mem;   ///< Memory allocator to use for buffers
	const char *sync;  ///< Synchronous Command-interface
	const char *async; ///> Asynchronous Command-interface
	const char *admin; ///< Administrative Command-interface
	uint32_t nsid;     ///< Namespace identifier
	union {
		struct {
			uint32_t rdonly   : 1; ///< OS open; read-only
			uint32_t wronly   : 1; ///< OS open; write-only
			uint32_t rdwr     : 1; ///< OS open; for read and only
			uint32_t create   : 1; ///< OS open; create if it does not exist
			uint32_t truncate : 1; ///< OS open; truncate content
			uint32_t direct   : 1; ///< OS open; attempt bypass OS-caching
			uint32_t _rsvd    : 26;
		};
		uint32_t oflags;
	};
	uint32_t create_mode;     ///< OS file creation-mode
	uint8_t poll_io;          ///< io_uring: enable io-polling
	uint8_t poll_sq;          ///< io_uring: enable sqthread-polling
	uint8_t register_files;   ///< io_uring: enable file-regirations
	uint8_t register_buffers; ///< io_uring: enable buffer-registration
	struct {
		uint32_t value : 31;
		uint32_t given : 1;
	} css;                 ///< SPDK controller-setup: do command-set-selection
	uint32_t use_cmb_sqs;  ///< SPDK controller-setup: use controller-memory-buffer for sq
	uint32_t shm_id;       ///< SPDK multi-processing: shared-memory-id
	uint32_t main_core;    ///< SPDK multi-processing: main-core
	const char *core_mask; ///< SPDK multi-processing: core-mask
	const char *adrfam;    ///< SPDK fabrics: address-family, IPv4/IPv6
	const char *subnqn;    ///< SPDK fabrics: Subsystem NQN
	const char *hostnqn;   ///< SPDK fabrics: Host NQN
	uint32_t spdk_fabrics; ///< Is assigned a value by backend if SPDK uses fabrics
};

/**
 * Returns an initialized option-struct with default values
 *
 * @return Zero-initialized and with default values where applicable
 */
struct xnvme_opts
xnvme_opts_default(void);

/**
 * Opaque device handle.
 *
 * @see xnvme_dev_open()
 *
 * @struct xnvme_dev
 */
struct xnvme_dev;

enum xnvme_enumerate_action {
	XNVME_ENUMERATE_DEV_KEEP_OPEN = 0x0, ///< Keep device-handle open after callback returns
	XNVME_ENUMERATE_DEV_CLOSE     = 0x1  ///< Close device-handle when callback returns
};

/**
 * Signature of callback function used with 'xnvme_enumerate' invoked for each discoved device
 *
 * The callback function signals whether the device-handle it receives should by closed, that is,
 * backend with invoke 'xnvme_dev_close(), after the callback returns or kept open. In the latter
 * case then it is up to the user to invoke 'xnvme_dev_close()' on the device-handle.
 *
 * Each signal is represented by the enum #xnvme_enumerate_action, and the values
 * XNVME_ENUMERATE_DEV_KEEP_OPEN or XNVME_ENUMERATE_DEV_CLOSE.
 */
typedef int (*xnvme_enumerate_cb)(struct xnvme_dev *dev, void *cb_args);

/**
 * enumerate devices
 *
 * @param sys_uri URI of the system to enumerate, when NULL, localhost/PCIe
 * @param opts Options for instrumenting the runtime during enumeration
 * @param cb_func Callback function to invoke for each yielded device
 * @param cb_args Arguments passed to the callback function
 *
 * @return On success, 0 is returned. On error, negative `errno` is returned.
 */
int
xnvme_enumerate(const char *sys_uri, struct xnvme_opts *opts, xnvme_enumerate_cb cb_func,
		void *cb_args);

/**
 * Creates a device handle (::xnvme_dev) based on the given device-uri
 *
 * @param dev_uri File path "/dev/nvme0n1" or "0000:04.01"
 * @param opts Options for library backend and system-interfaces
 *
 * @return On success, a handle to the device. On error, NULL is returned and `errno` set to
 * indicate the error.
 */
struct xnvme_dev *
xnvme_dev_open(const char *dev_uri, struct xnvme_opts *opts);

/**
 * Destroy the given device handle (::xnvme_dev)
 *
 * @param dev Device handle obtained with xnvme_dev_open()
 */
void
xnvme_dev_close(struct xnvme_dev *dev);

/**
 * Allocate a buffer for IO with the given device
 *
 * The buffer will be aligned to device geometry and DMA allocated if required by the backend for
 * command payloads
 *
 * @note
 * nbytes must be greater than zero and a multiple of minimal granularity
 * @note
 * De-allocate the buffer using xnvme_buf_free()
 *
 * @param dev Device handle obtained with xnvme_dev_open()
 * @param nbytes The size of the allocated buffer in bytes
 *
 * @return On success, a pointer to the allocated memory is returned. On error, NULL is returned
 * and `errno` set to indicate the error.
 */
void *
xnvme_buf_alloc(const struct xnvme_dev *dev, size_t nbytes);

/**
 * Reallocate a buffer for IO with the given device
 *
 * The buffer will be aligned to device geometry and DMA allocated if required by the backend for
 * IO
 *
 * @note
 * nbytes must be greater than zero and a multiple of minimal granularity
 * @note
 * De-allocate the buffer using xnvme_buf_free()
 *
 * @param dev Device handle obtained with xnvme_dev_open()
 * @param buf The buffer to reallocate
 * @param nbytes The size of the allocated buffer in bytes
 *
 * @return On success, a pointer to the allocated memory is returned. On error, NULL is returned
 * and `errno` set to indicate the error.
 */
void *
xnvme_buf_realloc(const struct xnvme_dev *dev, void *buf, size_t nbytes);

/**
 * Free the given IO buffer allocated with xnvme_buf_alloc()
 *
 * @param dev Device handle obtained with xnvme_dev_open()
 * @param buf Pointer to a buffer allocated with xnvme_buf_alloc()
 */
void
xnvme_buf_free(const struct xnvme_dev *dev, void *buf);

/**
 * Opaque Command Queue Handle to be initialized by xnvme_queue_init()
 *
 * @see xnvme_queue_init
 * @see xnvme_queue_term
 *
 * @struct xnvme_queue
 */
struct xnvme_queue;

/**
 * Command Queue initialization options
 *
 * @enum xnvme_queue_opts
 */
enum xnvme_queue_opts {
	XNVME_QUEUE_IOPOLL = 0x1,      ///< XNVME_QUEUE_IOPOLL: queue. is polled for completions
	XNVME_QUEUE_SQPOLL = 0x1 << 1, ///< XNVME_QUEUE_SQPOLL: queue. is polled for submissions
};

/**
 * Allocate a Command Queue for asynchronous command submission and completion
 *
 * @param dev Device handle (::xnvme_dev) obtained with xnvme_dev_open()
 * @param capacity Maximum number of outstanding commands on the initialized queue, note that it
 * must be a power of 2 within the range [1,4096]
 * @param opts Queue options
 * @param queue Pointer-pointer to the ::xnvme_queue to initialize
 *
 * @return On success, 0 is returned. On error, negative `errno` is returned.
 */
int
xnvme_queue_init(struct xnvme_dev *dev, uint16_t capacity, int opts, struct xnvme_queue **queue);

/**
 * Get the capacity of the given ::xnvme_queue
 *
 * @param queue Pointer to the ::xnvme_queue to query for capacity
 *
 * @return On success, capacity of given ::xnvme_queue text is returned. On error, 0 is returned
 * e.g. errors are silent
 */
uint32_t
xnvme_queue_get_capacity(struct xnvme_queue *queue);

/**
 * Get the number of outstanding commands on the given ::xnvme_queue
 *
 * @param queue Pointer to the ::xnvme_queue to query for outstanding commands
 *
 * @return On success, number of outstanding commands are returned. On error, 0 is returned e.g.
 * errors are silent
 */
uint32_t
xnvme_queue_get_outstanding(struct xnvme_queue *queue);

/**
 * Tear down the given ::xnvme_queue
 *
 * @param queue Pointer to the ::xnvme_queue to tear down
 *
 * @return On success, 0 is returned. On error, negative `errno` is returned.
 */
int
xnvme_queue_term(struct xnvme_queue *queue);

/**
 * Process completions of commands on the given ::xnvme_queue
 *
 * Set process 'max' to limit number of completions, 0 means no max.
 *
 * @param queue Pointer to the ::xnvme_queue to poke for completions
 * @param max The max number of completions to complete
 *
 * @return On success, number of completions processed, may be 0. On error, negative `errno` is
 * returned.
 */
int
xnvme_queue_poke(struct xnvme_queue *queue, uint32_t max);

/**
 * Process outstanding commands on the given ::xnvme_queue until it is empty
 *
 * @param queue Pointer to the ::xnvme_queue to wait/process commands on
 *
 * @return On success, number of commands processed, may be 0. On error, negative `errno` is
 * returned.
 */
int
xnvme_queue_drain(struct xnvme_queue *queue);

/**
 * DEPRECATED: expect that this function will be removed in an upcoming release
 *
 * @param queue Pointer to the ::xnvme_queue to wait/process commands on
 *
 * @return On success, number of commands processed, may be 0. On error, negative `errno` is
 * returned.
 */
int
xnvme_queue_wait(struct xnvme_queue *queue);

/**
 * Retrieve a command-context from the given queue for async. command execution with the queue
 *
 * @note The command-context is managed by the queue, thus, return it to the queue via
 * ::xnvme_queue_put_cmd_ctx
 *
 * @note This is not thread-safe
 *
 * @param queue Pointer to the ::xnvme_queue to retrieve a command-context for
 *
 * @return On success, a command-context is returned. On error, NULL is returned and `errno` is set
 * to indicate the error.
 */
struct xnvme_cmd_ctx *
xnvme_queue_get_cmd_ctx(struct xnvme_queue *queue);

/**
 * Hand back a command-context previously retrieve using ::xnvme_queue_get_cmd_ctx
 *
 * @note This function is not thread-safe
 *
 * @param queue Pointer to the ::xnvme_queue to hand back the command-context to
 * @param ctx Pointer to command context (::xnvme_cmd_ctx)
 *
 * @return On success, 0 is returned. On error, negative `errno` is returned.
 */
int
xnvme_queue_put_cmd_ctx(struct xnvme_queue *queue, struct xnvme_cmd_ctx *ctx);

/**
 * Signature of function used with Command Queues for async. callback upon command-completion
 */
typedef void (*xnvme_queue_cb)(struct xnvme_cmd_ctx *ctx, void *opaque);

/**
 * The xNVMe Command Context
 *
 * @struct xnvme_cmd_ctx
 */
struct xnvme_cmd_ctx {
	struct xnvme_spec_cmd cmd; ///< Command to be processed
	struct xnvme_spec_cpl cpl; ///< Completion result from processing

	struct xnvme_dev *dev; ///< Device associated with the command

	///< Fields for command option: XNVME_CMD_ASYNC
	struct {
		struct xnvme_queue *queue; ///< Queue used for command processing
		xnvme_queue_cb cb;         ///< User defined callback function
		void *cb_arg;              ///< User defined callback function arguments
	} async;

	///< Field containing command-options, the field is initialized by helper-functions
	uint32_t opts;

	uint8_t be_rsvd[12]; ///< Fields reserved for use by library internals
};
XNVME_STATIC_ASSERT(sizeof(struct xnvme_cmd_ctx) == 128, "Incorrect size")

/**
 * Assign a callback-function and argument to be used with the given command-context
 *
 * @param ctx Pointer to the ::xnvme_cmd_ctx to setup callback for
 * @param cb The callback function to use
 * @param cb_arg The callback argument to use
 */
static inline void
xnvme_cmd_ctx_set_cb(struct xnvme_cmd_ctx *ctx, xnvme_queue_cb cb, void *cb_arg)
{
	ctx->async.cb     = cb;
	ctx->async.cb_arg = cb_arg;
}

/**
 * Assign a callback-function and argument to be used with the ::xnvme_cmd_ctx of the queue
 *
 * @param queue The ::xnvme_queue to assign default callback function for
 * @param cb The callback function to use
 * @param cb_arg The callback argument to use
 *
 * @return On success, 0 is returned. On error, negative `errno` is returned.
 */
int
xnvme_queue_set_cb(struct xnvme_queue *queue, xnvme_queue_cb cb, void *cb_arg);

/**
 * Retrieve a command-context for issuing commands to the given device
 *
 * @param dev Device handle (::xnvme_dev) obtained with xnvme_dev_open()
 *
 * @return A ::xnvme_cmd_ctx initialized synchronous command on the given device
 */
struct xnvme_cmd_ctx
xnvme_cmd_ctx_from_dev(struct xnvme_dev *dev);

/**
 * Retrieve a command-text for issuing commands via the given queue
 *
 * @param queue Pointer to the ::xnvme_queue to retrieve a command-context for
 *
 * @return On success, a pointer to a ::xnvme_cmd_ctx is returned. On error, NULL is returned and
 * `errno` set to indicate the error.
 */
struct xnvme_cmd_ctx *
xnvme_cmd_ctx_from_queue(struct xnvme_queue *queue);

/**
 * Clears/resets the given ::xnvme_cmd_ctx
 *
 * @param ctx Pointer to the ::xnvme_cmd_ctx to clear
 */
void
xnvme_cmd_ctx_clear(struct xnvme_cmd_ctx *ctx);

/**
 * Encapsulate completion-error checking here for now.
 *
 * @param ctx Pointer to the ::xnvme_cmd_ctx to check status on
 *
 * @return On success, 0 is return. On error, a non-zero value is returned.
 */
static inline int
xnvme_cmd_ctx_cpl_status(struct xnvme_cmd_ctx *ctx)
{
	return ctx->cpl.status.sc || ctx->cpl.status.sct;
}

/**
 * Pass an NVMe IO Command through to the device via the given ::xnvme_cmd_ctx
 *
 * @param ctx Pointer to command context (::xnvme_cmd_ctx)
 * @param dbuf pointer to data-payload
 * @param dbuf_nbytes size of data-payload in bytes
 * @param mbuf pointer to meta-payload
 * @param mbuf_nbytes size of the meta-payload in bytes
 *
 * @return On success, 0 is returned. On error, negative `errno` is returned.
 */
int
xnvme_cmd_pass(struct xnvme_cmd_ctx *ctx, void *dbuf, size_t dbuf_nbytes, void *mbuf,
	       size_t mbuf_nbytes);

/**
 * Pass a vectored NVMe IO Command through to the device via the given ::xnvme_cmd_ctx
 *
 * @param ctx Pointer to command context (::xnvme_cmd_ctx)
 * @param dvec array of data iovecs
 * @param dvec_cnt number of elements in dvec
 * @param dvec_nbytes size of the meta-payload in bytes
 * @param mvec array of metadata iovecs
 * @param mvec_cnt number of elements in mvec
 * @param mvec_nbytes size of the meta-payload in bytes
 *
 * @return On success, 0 is returned. On error, negative `errno` is returned.
 */
int
xnvme_cmd_passv(struct xnvme_cmd_ctx *ctx, struct iovec *dvec, size_t dvec_cnt, size_t dvec_nbytes,
		struct iovec *mvec, size_t mvec_cnt, size_t mvec_nbytes);

/**
 * Pass a NVMe Admin Command through to the device with minimal intervention
 *
 * @param ctx Pointer to command context (::xnvme_cmd_ctx)
 * @param dbuf pointer to data-payload
 * @param dbuf_nbytes size of data-payload in bytes
 * @param mbuf pointer to meta-payload
 * @param mbuf_nbytes size of the meta-payload in bytes
 *
 * @return On success, 0 is returned. On error, negative `errno` is returned.
 */
int
xnvme_cmd_pass_admin(struct xnvme_cmd_ctx *ctx, void *dbuf, size_t dbuf_nbytes, void *mbuf,
		     size_t mbuf_nbytes);

#ifdef __cplusplus
}
#endif

#endif /* __LIBXNVME_H */

Enums

xnvme_enumerate_action

enum xnvme_enumerate_action

Values:

enumerator XNVME_ENUMERATE_DEV_KEEP_OPEN

Keep device-handle open after callback returns.

enumerator XNVME_ENUMERATE_DEV_CLOSE

Close device-handle when callback returns.

xnvme_pr

enum xnvme_pr

Options for pretty-printer (*_pr, *_fpr) functions.

See

libxnvme_pp.h

Values:

enumerator XNVME_PR_DEF

XNVME_PR_DEF: Default options.

enumerator XNVME_PR_YAML

XNVME_PR_YAML: Print formatted as YAML.

enumerator XNVME_PR_TERSE

XNVME_PR_TERSE: Print without formatting.

xnvme_queue_opts

enum xnvme_queue_opts

Command Queue initialization options.

Values:

enumerator XNVME_QUEUE_IOPOLL

XNVME_QUEUE_IOPOLL: queue. is polled for completions.

enumerator XNVME_QUEUE_SQPOLL

XNVME_QUEUE_SQPOLL: queue. is polled for submissions.

Structs

xnvme_be_attr

struct xnvme_be_attr

Public Members

const char *name

Backend name.

uint8_t enabled

Whether the backend is ‘enabled’.

uint8_t _rsvd[15]

xnvme_be_attr_list

struct xnvme_be_attr_list

Representation of xNVMe library backend attributes.

List of xNVMe library backend attributes.

Public Members

uint32_t capacity

Remaining unused entries.

int count

Number of used entries.

struct xnvme_be_attr item[]

Array of items.

xnvme_cmd_ctx

struct xnvme_cmd_ctx

The xNVMe Command Context.

Public Members

struct xnvme_spec_cmd cmd

Command to be processed.

struct xnvme_spec_cpl cpl

Completion result from processing.

struct xnvme_dev *dev

Device associated with the command.

Fields for command option: XNVME_CMD_ASYNC

struct xnvme_cmd_ctx.[anonymous] async

Field containing command-options, the field is initialized by helper-functions.

uint32_t opts

uint8_t be_rsvd[12]

Fields reserved for use by library internals.

xnvme_enumeration

struct xnvme_enumeration

List of devices found on the system usable with xNVMe.

Public Members

uint32_t capacity

Remaining unused entries.

uint32_t nentries

Used entries.

struct xnvme_ident entries[]

Device entries.

xnvme_lba_range

struct xnvme_lba_range

Representation of a range of logical-block-addresses aka LBAs.

Public Members

uint64_t slba

Range start-LBA; begins at and includes this address.

uint64_t elba

Range end-LBA; ends at and includes this address.

uint32_t naddrs

Number of addresses in range [slba, elba].

uint64_t nbytes

Number of bytes covered by [slba, elba].

struct xnvme_lba_range.[anonymous] attr

xnvme_timer

struct xnvme_timer

Encapsulation of a basic wall-clock timer, start/stop clock.

Public Members

uint64_t start

uint64_t stop

Functions

XNVME_ILOG2

uint64_t XNVME_ILOG2(uint64_t x)

XNVME_MAX

int XNVME_MAX(int x, int y)

Calculate the maximum of the given x and y

Return

The maximum of x and y

Parameters

• x:

• y:

XNVME_MIN

int XNVME_MIN(int x, int y)

Calculate the minimum of the given x and y

Return

The maximum of x and y

Parameters

• x:

• y:

XNVME_MIN_S64

int64_t XNVME_MIN_S64(int64_t x, int64_t y)

Calculate the minimum of the given x and y

Return

The maximum of x and y

Parameters

• x:

• y:

XNVME_MIN_U64

uint64_t XNVME_MIN_U64(uint64_t x, uint64_t y)

Calculate the minimum of the given x and y

Return

The maximum of x and y

Parameters

• x:

• y:

xnvme_be_attr_fpr

int xnvme_be_attr_fpr(FILE *stream, const struct xnvme_be_attr *attr, int opts)

Prints the given backend attribute to the given output stream.

Return

On success, the number of characters printed is returned.

Parameters

• stream: output stream used for printing

• attr: Pointer to the xnvme_be_attr to print

• opts: printer options, see xnvme_pr

xnvme_be_attr_list_bundled

int xnvme_be_attr_list_bundled(struct xnvme_be_attr_list **list)

List backends bundled with the library.

Return

On success, 0 is returned. On error, negative errno is returned.

xnvme_be_attr_list_fpr

int xnvme_be_attr_list_fpr(FILE *stream, const struct xnvme_be_attr_list *list, int opts)

Prints the given backend attribute list to the given output stream.

Return

On success, the number of characters printed is returned.

Parameters

• stream: output stream used for printing

• list: Pointer to the backend attribute list to print

• opts: printer options, see xnvme_pr

xnvme_be_attr_list_pr

int xnvme_be_attr_list_pr(const struct xnvme_be_attr_list *list, int opts)

Prints the given backend attribute list to standard out.

Return

On success, the number of characters printed is returned.

Parameters

• list: Pointer to the backend attribute list to print

• opts: printer options, see xnvme_pr

xnvme_be_attr_pr

int xnvme_be_attr_pr(const struct xnvme_be_attr *attr, int opts)

Prints the given backend attribute to stdout.

Return

On success, the number of characters printed is returned.

Parameters

• attr: Pointer to the xnvme_be_attr to print

• opts: printer options, see xnvme_pr

xnvme_buf_alloc

void *xnvme_buf_alloc(const struct xnvme_dev *dev, size_t nbytes)

Allocate a buffer for IO with the given device.

The buffer will be aligned to device geometry and DMA allocated if required by the backend for command payloads

Note

nbytes must be greater than zero and a multiple of minimal granularity

Note

De-allocate the buffer using xnvme_buf_free()

Return

On success, a pointer to the allocated memory is returned. On error, NULL is returned and errno set to indicate the error.

Parameters

• dev: Device handle obtained with xnvme_dev_open()

• nbytes: The size of the allocated buffer in bytes

xnvme_buf_free

void xnvme_buf_free(const struct xnvme_dev *dev, void *buf)

Free the given IO buffer allocated with xnvme_buf_alloc()

Parameters

• dev: Device handle obtained with xnvme_dev_open()

• buf: Pointer to a buffer allocated with xnvme_buf_alloc()

xnvme_buf_phys_alloc

void *xnvme_buf_phys_alloc(const struct xnvme_dev *dev, size_t nbytes, uint64_t *phys)

Allocate a buffer of physical memory, aligned for IO with the given device.

Note

nbytes must be greater than zero and a multiple of minimal granularity

Note

De-allocate the buffer using xnvme_buf_phys_free()

Return

On success, a pointer to the allocated memory is returned. On error, NULL is returned and errno set to indicate the error.

Parameters

• dev: Device handle obtained with xnvme_dev_open()

• nbytes: The size of the allocated buffer in bytes

• phys: A pointer to the variable to hold the physical address of the allocated buffer. If NULL, the physical address is not returned.

xnvme_buf_phys_free

void xnvme_buf_phys_free(const struct xnvme_dev *dev, void *buf)

Free the given buffer of physical memory allocated with xnvme_buf_phys_alloc()

Parameters

• dev: Device handle obtained with xnvme_dev_open()

• buf: Pointer to a buffer allocated with xnvme_buf_phys_alloc()

xnvme_buf_phys_realloc

void *xnvme_buf_phys_realloc(const struct xnvme_dev *dev, void *buf, size_t nbytes, uint64_t *phys)

Re-allocate a buffer of physical memory, aligned for IO with the given device.

Note

nbytes must be greater than zero and a multiple of minimal granularity

Note

De-allocate the buffer using xnvme_buf_phys_free()

Return

On success, a pointer to the allocated memory is returned. On error, NULL is returned and errno set to indicate the error.

Parameters

• dev: Device handle obtained with xnvme_dev_open()

• buf: The buffer to reallocate

• nbytes: The size of the allocated buffer in bytes

• phys: A pointer to the variable to hold the physical address of the allocated buffer. If NULL, the physical address is not returned.

xnvme_buf_realloc

void *xnvme_buf_realloc(const struct xnvme_dev *dev, void *buf, size_t nbytes)

Reallocate a buffer for IO with the given device.

The buffer will be aligned to device geometry and DMA allocated if required by the backend for IO

Note

nbytes must be greater than zero and a multiple of minimal granularity

Note

De-allocate the buffer using xnvme_buf_free()

Return

On success, a pointer to the allocated memory is returned. On error, NULL is returned and errno set to indicate the error.

Parameters

• dev: Device handle obtained with xnvme_dev_open()

• buf: The buffer to reallocate

• nbytes: The size of the allocated buffer in bytes

xnvme_buf_virt_alloc

void *xnvme_buf_virt_alloc(size_t alignment, size_t nbytes)

Allocate a buffer of virtual memory of the given alignment and nbytes

Note

You must use xnvme_buf_virt_free() to de-allocate the buffer

Return

On success, a pointer to the allocated memory is return. On error, NULL is returned and errno set to indicate the error

Parameters

• alignment: The alignment in bytes

• nbytes: The size of the buffer in bytes

xnvme_buf_virt_free

void xnvme_buf_virt_free(void *buf)

Free the given virtual memory buffer.

Parameters

• buf: Pointer to a buffer allocated with xnvme_buf_virt_alloc()

xnvme_buf_vtophys

int xnvme_buf_vtophys(const struct xnvme_dev *dev, void *buf, uint64_t *phys)

Retrieve the physical address of the given buffer.

The intended use for this function is to provide the physical-address of a buffer-allocation allocated with xnvme_buf_phys_alloc() or xnvme_buf_alloc(), where the ‘phys’ argument was either not provided.

Return

On success, 0 is returned. On error, negative errno is returned.

Parameters

• dev: Device handle obtained with xnvme_dev_open()

• buf: Pointer to a buffer allocated with xnvme_buf_alloc()

• phys: A pointer to the variable to hold the physical address of the given buffer.

xnvme_cmd_ctx_clear

void xnvme_cmd_ctx_clear(struct xnvme_cmd_ctx *ctx)

Clears/resets the given xnvme_cmd_ctx.

Parameters

• ctx: Pointer to the xnvme_cmd_ctx to clear

xnvme_cmd_ctx_cpl_status

int xnvme_cmd_ctx_cpl_status(struct xnvme_cmd_ctx *ctx)

Encapsulate completion-error checking here for now.

Return

On success, 0 is return. On error, a non-zero value is returned.

Parameters

• ctx: Pointer to the xnvme_cmd_ctx to check status on

xnvme_cmd_ctx_from_dev

struct xnvme_cmd_ctx xnvme_cmd_ctx_from_dev(struct xnvme_dev *dev)

Retrieve a command-context for issuing commands to the given device.

Return

A xnvme_cmd_ctx initialized synchronous command on the given device

Parameters

• dev: Device handle (xnvme_dev) obtained with xnvme_dev_open()

xnvme_cmd_ctx_from_queue

struct xnvme_cmd_ctx *xnvme_cmd_ctx_from_queue(struct xnvme_queue *queue)

Retrieve a command-text for issuing commands via the given queue.

Return

On success, a pointer to a xnvme_cmd_ctx is returned. On error, NULL is returned and errno set to indicate the error.

Parameters

• queue: Pointer to the xnvme_queue to retrieve a command-context for

xnvme_cmd_ctx_pr

void xnvme_cmd_ctx_pr(const struct xnvme_cmd_ctx *ctx, int UNUSED_opts)

Prints a humanly readable representation the given xnvme_cmd_ctx.

Parameters

• ctx: Pointer to the xnvme_cmd_ctx to print

• UNUSED_opts: Printer options

xnvme_cmd_ctx_set_cb

void xnvme_cmd_ctx_set_cb(struct xnvme_cmd_ctx *ctx, xnvme_queue_cb cb, void *cb_arg)

Assign a callback-function and argument to be used with the given command-context.

Parameters

• ctx: Pointer to the xnvme_cmd_ctx to setup callback for

• cb: The callback function to use

• cb_arg: The callback argument to use

xnvme_cmd_pass

int xnvme_cmd_pass(struct xnvme_cmd_ctx *ctx, void *dbuf, size_t dbuf_nbytes, void *mbuf, size_t mbuf_nbytes)

Pass an NVMe IO Command through to the device via the given xnvme_cmd_ctx.

Return

On success, 0 is returned. On error, negative errno is returned.

Parameters

• ctx: Pointer to command context (xnvme_cmd_ctx)

• dbuf: pointer to data-payload

• dbuf_nbytes: size of data-payload in bytes

• mbuf: pointer to meta-payload

• mbuf_nbytes: size of the meta-payload in bytes

xnvme_cmd_pass_admin

int xnvme_cmd_pass_admin(struct xnvme_cmd_ctx *ctx, void *dbuf, size_t dbuf_nbytes, void *mbuf, size_t mbuf_nbytes)

Pass a NVMe Admin Command through to the device with minimal intervention.

Return

On success, 0 is returned. On error, negative errno is returned.

Parameters

• ctx: Pointer to command context (xnvme_cmd_ctx)

• dbuf: pointer to data-payload

• dbuf_nbytes: size of data-payload in bytes

• mbuf: pointer to meta-payload

• mbuf_nbytes: size of the meta-payload in bytes

xnvme_cmd_passv

int xnvme_cmd_passv(struct xnvme_cmd_ctx *ctx, struct iovec *dvec, size_t dvec_cnt, size_t dvec_nbytes, struct iovec *mvec, size_t mvec_cnt, size_t mvec_nbytes)

Pass a vectored NVMe IO Command through to the device via the given xnvme_cmd_ctx.

Return

On success, 0 is returned. On error, negative errno is returned.

Parameters

• ctx: Pointer to command context (xnvme_cmd_ctx)

• dvec: array of data iovecs

• dvec_cnt: number of elements in dvec

• dvec_nbytes: size of the meta-payload in bytes

• mvec: array of metadata iovecs

• mvec_cnt: number of elements in mvec

• mvec_nbytes: size of the meta-payload in bytes

xnvme_enumerate

int xnvme_enumerate(const char *sys_uri, struct xnvme_opts *opts, xnvme_enumerate_cb cb_func, void *cb_args)

enumerate devices

Return

On success, 0 is returned. On error, negative errno is returned.

Parameters

• sys_uri: URI of the system to enumerate, when NULL, localhost/PCIe

• opts: Options for instrumenting the runtime during enumeration

• cb_func: Callback function to invoke for each yielded device

• cb_args: Arguments passed to the callback function

xnvme_enumeration_alloc

int xnvme_enumeration_alloc(struct xnvme_enumeration **list, uint32_t capacity)

xnvme_enumeration_append

int xnvme_enumeration_append(struct xnvme_enumeration *list, const struct xnvme_ident *entry)

xnvme_enumeration_fpp

int xnvme_enumeration_fpp(FILE *stream, struct xnvme_enumeration *list, int opts)

xnvme_enumeration_fpr

int xnvme_enumeration_fpr(FILE *stream, struct xnvme_enumeration *list, int opts)

Prints the given xnvme_enumeration to the given output stream.

Return

On success, the number of characters printed is returned.

Parameters

• stream: output stream used for printing

• list: pointer to structure to print

• opts: printer options, see xnvme_pr

xnvme_enumeration_free

void xnvme_enumeration_free(struct xnvme_enumeration *list)

xnvme_enumeration_pp

int xnvme_enumeration_pp(struct xnvme_enumeration *list, int opts)

xnvme_enumeration_pr

int xnvme_enumeration_pr(struct xnvme_enumeration *list, int opts)

Prints the given xnvme_enumeration to stdout.

Return

On success, the number of characters printed is returned.

Parameters

• list: pointer to structure to print

• opts: printer options, see xnvme_pr

xnvme_is_pow2

int xnvme_is_pow2(uint32_t val)

xnvme_lba_fpr

int xnvme_lba_fpr(FILE *stream, uint64_t lba, enum xnvme_pr opts)

Prints the given LBA to the given output stream.

Return

On success, the number of characters printed is returned.

Parameters

• stream: output stream used for printing

• lba: the LBA to print

• opts: printer options, see xnvme_pr

xnvme_lba_fprn

int xnvme_lba_fprn(FILE *stream, const uint64_t *lba, uint16_t nlb, enum xnvme_pr opts)

Prints the given list of Logical Block Addresses (LBAs)to the given output stream.

Parameters

• stream: output stream used for printing

• lba: Pointer to an array of LBAs to print

• nlb: Number of LBAs to print from the given list

• opts: printer options, see xnvme_pr

xnvme_lba_pr

int xnvme_lba_pr(uint64_t lba, enum xnvme_pr opts)

Prints the given Logical Block Addresses (LBA) to stdout.

Return

On success, the number of characters printed is returned.

Parameters

• lba: the LBA to print

• opts: printer options, see xnvme_pr

xnvme_lba_prn

int xnvme_lba_prn(const uint64_t *lba, uint16_t nlb, enum xnvme_pr opts)

Print a list of Logical Block Addresses (LBAs)

Return

On success, the number of characters printed is returned.

Parameters

• lba: Pointer to an array of LBAs to print

• nlb: Length of the array in items

• opts: Printer options

xnvme_lba_range_fpr

int xnvme_lba_range_fpr(FILE *stream, struct xnvme_lba_range *range, int opts)

Prints the given backend attribute to the given output stream.

Return

On success, the number of characters printed is returned.

Parameters

• stream: output stream used for printing

• range: Pointer to the xnvme_lba_range to print

• opts: printer options, see xnvme_pr

xnvme_lba_range_from_offset_nbytes

struct xnvme_lba_range xnvme_lba_range_from_offset_nbytes(struct xnvme_dev *dev, uint64_t offset, uint64_t nbytes)

Initializes a range starting at the given byte-offset and spanning nbytes.

Return

On success, an initialized range is returned by value with attr.is_valid = 1. On error, a potential non, or partially, initialized struct is returned by value with attr.is_valid = 0.

Parameters

• dev: Device handle obtained with xnvme_dev_open()

• offset: Offset in bytes satisfying offset < capacity

• nbytes: Number of bytes, satisfying offset + nbytes < capacity

xnvme_lba_range_from_slba_elba

struct xnvme_lba_range xnvme_lba_range_from_slba_elba(struct xnvme_dev *dev, uint64_t slba, uint64_t elba)

Initializes a range starting at the given start-lba (slba) and spanning naddrs.

Return

On success, an initialized range is returned by value with attr.is_valid = 1. On error, a potential non, or partially, initialized struct is returned by value with attr.is_valid = 0.

Parameters

• dev: Device handle obtained with xnvme_dev_open()

• slba: A valid lba on the given dev

• elba: A valid lba on the given dev

xnvme_lba_range_from_slba_naddrs

struct xnvme_lba_range xnvme_lba_range_from_slba_naddrs(struct xnvme_dev *dev, uint64_t slba, uint64_t naddrs)

Initializes a range starting at the given start-lba (slba) and spanning naddrs.

Return

On success, an initialized range is returned by value with attr.is_valid = 1. On error, a potential non, or partially, initialized struct is returned by value with attr.is_valid = 0.

Parameters

• dev: Device handle obtained with xnvme_dev_open()

• slba: A valid lba on the given dev

• naddrs: A non-zero number of addresses, satisfying slba + naddrs < device capacity

xnvme_lba_range_from_zdescr

struct xnvme_lba_range xnvme_lba_range_from_zdescr(struct xnvme_dev *dev, struct xnvme_spec_znd_descr *zdescr)

Initializes a range starting at the given zone-start-LBA and spanning zone-capacity.

Return

On success, an initialized range is returned by value with attr.is_valid = 1. On error, a potential non, or partially, initialized struct is returned by value with attr.is_valid = 0.

Parameters

• dev: Device handle obtained with xnvme_dev_open()

• zdescr: Pointer to a zone-descriptor valid on the given dev

xnvme_lba_range_pr

int xnvme_lba_range_pr(struct xnvme_lba_range *range, int opts)

Prints the given backend attribute to stdout.

Return

On success, the number of characters printed is returned.

Parameters

• range: Pointer to the xnvme_lba_range to print

• opts: printer options, see xnvme_pr

xnvme_prep_nvm

void xnvme_prep_nvm(struct xnvme_cmd_ctx *ctx, uint8_t opcode, uint32_t nsid, uint64_t slba, uint16_t nlb)

Submit, and optionally wait for completion of, a NVMe Write.

Return

On success, 0 is returned. On error, negative errno is returned.

Parameters

• ctx: Pointer to command context (xnvme_cmd_ctx)

• opcode: Opcode for the NVMe command

• nsid: Namespace Identifier

• slba: The LBA to start the write at

• nlb: Number of LBAs to be written. NOTE: nlb is a zero-based value

xnvme_queue_drain

int xnvme_queue_drain(struct xnvme_queue *queue)

Process outstanding commands on the given xnvme_queue until it is empty.

Return

On success, number of commands processed, may be 0. On error, negative errno is returned.

Parameters

• queue: Pointer to the xnvme_queue to wait/process commands on

xnvme_queue_get_capacity

uint32_t xnvme_queue_get_capacity(struct xnvme_queue *queue)

Get the capacity of the given xnvme_queue.

Return

On success, capacity of given xnvme_queue text is returned. On error, 0 is returned e.g. errors are silent

Parameters

• queue: Pointer to the xnvme_queue to query for capacity

xnvme_queue_get_cmd_ctx

struct xnvme_cmd_ctx *xnvme_queue_get_cmd_ctx(struct xnvme_queue *queue)

Retrieve a command-context from the given queue for async.

command execution with the queue

Note

The command-context is managed by the queue, thus, return it to the queue via xnvme_queue_put_cmd_ctx

Note

This is not thread-safe

Return

On success, a command-context is returned. On error, NULL is returned and errno is set to indicate the error.

Parameters

• queue: Pointer to the xnvme_queue to retrieve a command-context for

xnvme_queue_get_outstanding

uint32_t xnvme_queue_get_outstanding(struct xnvme_queue *queue)

Get the number of outstanding commands on the given xnvme_queue.

Return

On success, number of outstanding commands are returned. On error, 0 is returned e.g. errors are silent

Parameters

• queue: Pointer to the xnvme_queue to query for outstanding commands

xnvme_queue_init

int xnvme_queue_init(struct xnvme_dev *dev, uint16_t capacity, int opts, struct xnvme_queue **queue)

Allocate a Command Queue for asynchronous command submission and completion.

Return

On success, 0 is returned. On error, negative errno is returned.

Parameters

• dev: Device handle (xnvme_dev) obtained with xnvme_dev_open()

• capacity: Maximum number of outstanding commands on the initialized queue, note that it must be a power of 2 within the range [1,4096]

• opts: Queue options

• queue: Pointer-pointer to the xnvme_queue to initialize

xnvme_queue_poke

int xnvme_queue_poke(struct xnvme_queue *queue, uint32_t max)

Process completions of commands on the given xnvme_queue.

Set process ‘max’ to limit number of completions, 0 means no max.

Return

On success, number of completions processed, may be 0. On error, negative errno is returned.

Parameters

• queue: Pointer to the xnvme_queue to poke for completions

• max: The max number of completions to complete

xnvme_queue_put_cmd_ctx

int xnvme_queue_put_cmd_ctx(struct xnvme_queue *queue, struct xnvme_cmd_ctx *ctx)

Hand back a command-context previously retrieve using xnvme_queue_get_cmd_ctx.

Note

This function is not thread-safe

Return

On success, 0 is returned. On error, negative errno is returned.

Parameters

• queue: Pointer to the xnvme_queue to hand back the command-context to

• ctx: Pointer to command context (xnvme_cmd_ctx)

xnvme_queue_set_cb

int xnvme_queue_set_cb(struct xnvme_queue *queue, xnvme_queue_cb cb, void *cb_arg)

Assign a callback-function and argument to be used with the xnvme_cmd_ctx of the queue.

Return

On success, 0 is returned. On error, negative errno is returned.

Parameters

• queue: The xnvme_queue to assign default callback function for

• cb: The callback function to use

• cb_arg: The callback argument to use

xnvme_queue_term

int xnvme_queue_term(struct xnvme_queue *queue)

Tear down the given xnvme_queue.

Return

On success, 0 is returned. On error, negative errno is returned.

Parameters

• queue: Pointer to the xnvme_queue to tear down

xnvme_queue_wait

int xnvme_queue_wait(struct xnvme_queue *queue)

DEPRECATED: expect that this function will be removed in an upcoming release.

Return

On success, number of commands processed, may be 0. On error, negative errno is returned.

Parameters

• queue: Pointer to the xnvme_queue to wait/process commands on

xnvme_timer_bw_pr

void xnvme_timer_bw_pr(struct xnvme_timer *t, const char *prefix, size_t nbytes)

Print the elapsed time in seconds and the associated data rate in MB/s.

Parameters

• t:

• prefix:

• nbytes:

xnvme_timer_elapsed

double xnvme_timer_elapsed(struct xnvme_timer *t)

Get the elapsed time in seconds.

Return

elapsed time in seconds as a floating point number

Parameters

• t:

xnvme_timer_elapsed_msecs

double xnvme_timer_elapsed_msecs(struct xnvme_timer *t)

Get the elapsed time in milliseconds.

Return

elapsed time in milliseconds as a floating point number

Parameters

• t:

xnvme_timer_elapsed_nsecs

uint64_t xnvme_timer_elapsed_nsecs(struct xnvme_timer *t)

Get the elapsed time in nanoseconds.

Return

elapsed time in nanoseconds

Parameters

• t:

xnvme_timer_elapsed_secs

double xnvme_timer_elapsed_secs(struct xnvme_timer *t)

Get the elapsed time in seconds.

Return

elapsed time in seconds as a floating point number

Parameters

• t:

xnvme_timer_elapsed_usecs

double xnvme_timer_elapsed_usecs(struct xnvme_timer *t)

Get the elapsed time in microseconds.

Return

elapsed time in microseconds as a floating point number

Parameters

• t:

xnvme_timer_pr

void xnvme_timer_pr(struct xnvme_timer *t, const char *prefix)

Print the elapsed time in seconds as a floating point number.

Parameters

• t:

• prefix:

xnvme_timer_start

uint64_t xnvme_timer_start(struct xnvme_timer *t)

Start the given timer.

Return

clock sample in nano seconds

Parameters

• t:

xnvme_timer_stop

uint64_t xnvme_timer_stop(struct xnvme_timer *t)

Stop the given timer.

Return

clock sample in nano seconds

Parameters

• t: