xnvme

Header

/**
 * Cross-platform I/O library for emerging storage devices
 *
 * Designed for the low-level control and performance offered by NVMe device
 * while maintaining the support for traditional storage devices and
 * interfaces.
 *
 * SPDX-FileCopyrightText: Samsung Electronics Co., Ltd
 *
 * SPDX-License-Identifier: BSD-3-Clause
 *
 * @file libxnvme.h
 */

#ifndef __LIBXNVME_H
#define __LIBXNVME_H

#ifdef __cplusplus
extern "C" {
#endif

#include <assert.h>
#include <inttypes.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <sys/uio.h>
#include <time.h>

#include "libxnvme_util.h"
#include "libxnvme_opts.h"
#include "libxnvme_dev.h"
#include "libxnvme_be.h"
#include "libxnvme_buf.h"
#include "libxnvme_mem.h"
#include "libxnvme_geo.h"
#include "libxnvme_ident.h"
#include "libxnvme_queue.h"
#include "libxnvme_spec.h"
#include "libxnvme_spec_fs.h"
#include "libxnvme_spec_pp.h"
#include "libxnvme_cmd.h"
#include "libxnvme_lba.h"
#include "libxnvme_ver.h"
#include "libxnvme_pp.h"
#include "libxnvme_file.h"
#include "libxnvme_adm.h"
#include "libxnvme_nvm.h"
#include "libxnvme_kvs.h"
#include "libxnvme_znd.h"
#include "libxnvme_topology.h"
#include "libxnvme_libconf.h"
#include "libxnvme_cli.h"
#include "libxnvme_pi.h"

#ifdef __cplusplus
}
#endif

#endif /* __LIBXNVME_H */

Enums

xnvme_enumerate_action

enum xnvme_enumerate_action

SPDX-FileCopyrightText: Samsung Electronics Co., Ltd.

SPDX-License-Identifier: BSD-3-Clause

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_pi_check_type

Warning

doxygenenum: Cannot find enum “xnvme_pi_check_type” in doxygen xml output for project “xNVMe” from directory: builddir/doxy/xml

xnvme_pi_type

Warning

doxygenenum: Cannot find enum “xnvme_pi_type” in doxygen xml output for project “xNVMe” from directory: builddir/doxy/xml

xnvme_pr

enum xnvme_pr

SPDX-FileCopyrightText: Samsung Electronics Co., Ltd.

SPDX-License-Identifier: BSD-3-Clause Options for pretty-printer (*_pr, *_fpr) functions

xnvme_retreive_opts

enum xnvme_retreive_opts

SPDX-FileCopyrightText: Samsung Electronics Co., Ltd.

SPDX-License-Identifier: BSD-3-Clause

Values:

enumerator XNVME_KVS_RETRIEVE_OPT_RETRIEVE_RAW

xnvme_store_opts

enum xnvme_store_opts

Values:

enumerator XNVME_KVS_STORE_OPT_DONT_STORE_IF_KEY_NOT_EXISTS

enumerator XNVME_KVS_STORE_OPT_DONT_STORE_IF_KEY_EXISTS

enumerator XNVME_KVS_STORE_OPT_COMPRESS

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

SPDX-FileCopyrightText: Samsung Electronics Co., Ltd.

List of xNVMe library backend attributes.

SPDX-License-Identifier: BSD-3-Clause Representation 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_controller

Warning

doxygenstruct: Cannot find class “xnvme_controller” in doxygen xml output for project “xNVMe” from directory: builddir/doxy/xml

xnvme_namespace

Warning

doxygenstruct: Cannot find class “xnvme_namespace” in doxygen xml output for project “xNVMe” from directory: builddir/doxy/xml

xnvme_pi_ctx

Warning

doxygenstruct: Cannot find class “xnvme_pi_ctx” in doxygen xml output for project “xNVMe” from directory: builddir/doxy/xml

xnvme_pif

struct xnvme_pif

Public Members

union xnvme_pif.[anonymous] [anonymous]

xnvme_subsystem

Warning

doxygenstruct: Cannot find class “xnvme_subsystem” in doxygen xml output for project “xNVMe” from directory: builddir/doxy/xml

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

static inline uint64_t XNVME_ILOG2(uint64_t x)

XNVME_MAX

static inline int XNVME_MAX(int x, int y)

Calculate the maximum of the given x and y

Parameters:

x –
y –

Returns:

The maximum of x and y

XNVME_MIN

static inline int XNVME_MIN(int x, int y)

Calculate the minimum of the given x and y

Parameters:

x –
y –

Returns:

The maximum of x and y

XNVME_MIN_S64

static inline int64_t XNVME_MIN_S64(int64_t x, int64_t y)

Calculate the minimum of the given x and y

Parameters:

x –
y –

Returns:

The maximum of x and y

XNVME_MIN_U64

static inline uint64_t XNVME_MIN_U64(uint64_t x, uint64_t y)

Calculate the minimum of the given x and y

Parameters:

x –
y –

Returns:

The maximum of x and y

XNVME_SIZEOF_MEMBER

Warning

doxygenfunction: Cannot find function “XNVME_SIZEOF_MEMBER” in doxygen xml output for project “xNVMe” from directory: builddir/doxy/xml

XNVME_SIZEOF_MEMBER

Warning

doxygenfunction: Cannot find function “XNVME_SIZEOF_MEMBER” in doxygen xml output for project “xNVMe” from directory: builddir/doxy/xml

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.

Parameters:

stream – output stream used for printing
attr – Pointer to the xnvme_be_attr to print
opts – printer options, see xnvme_pr

Returns:

On success, the number of characters printed is returned.

xnvme_be_attr_list_bundled

int xnvme_be_attr_list_bundled(struct xnvme_be_attr_list **list)

List backends bundled with the library.

Returns:: 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.

Parameters:

stream – output stream used for printing
list – Pointer to the backend attribute list to print
opts – printer options, see xnvme_pr

Returns:

On success, the number of characters printed is returned.

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.

Parameters:

list – Pointer to the backend attribute list to print
opts – printer options, see xnvme_pr

Returns:

On success, the number of characters printed is returned.

xnvme_be_attr_pr

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

Prints the given backend attribute to stdout.

Parameters:

attr – Pointer to the xnvme_be_attr to print
opts – printer options, see xnvme_pr

Returns:

On success, the number of characters printed is returned.

xnvme_controller_get_registers

Warning

doxygenfunction: Cannot find function “xnvme_controller_get_registers” in doxygen xml output for project “xNVMe” from directory: builddir/doxy/xml

xnvme_controller_reset

Warning

doxygenfunction: Cannot find function “xnvme_controller_reset” in doxygen xml output for project “xNVMe” from directory: builddir/doxy/xml

xnvme_enumerate

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

enumerate devices

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

Returns:

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

xnvme_is_pow2

static inline int xnvme_is_pow2(uint32_t val)

xnvme_namespace_rescan

Warning

doxygenfunction: Cannot find function “xnvme_namespace_rescan” in doxygen xml output for project “xNVMe” from directory: builddir/doxy/xml

xnvme_pi_ctx_init

Warning

doxygenfunction: Cannot find function “xnvme_pi_ctx_init” in doxygen xml output for project “xNVMe” from directory: builddir/doxy/xml

xnvme_pi_generate

Warning

doxygenfunction: Cannot find function “xnvme_pi_generate” in doxygen xml output for project “xNVMe” from directory: builddir/doxy/xml

xnvme_pi_size

Warning

doxygenfunction: Cannot find function “xnvme_pi_size” in doxygen xml output for project “xNVMe” from directory: builddir/doxy/xml

xnvme_pi_verify

Warning

doxygenfunction: Cannot find function “xnvme_pi_verify” in doxygen xml output for project “xNVMe” from directory: builddir/doxy/xml

xnvme_prep_adm_gfeat

void xnvme_prep_adm_gfeat(struct xnvme_cmd_ctx *ctx, uint32_t nsid, uint8_t fid, uint8_t sel)

Prepare NVMe Get Features (gfeat) command.

Parameters:

ctx – Pointer to xnvme_cmd_ctx
nsid – Namespace identifier
fid – Feature identifier
sel – Select which value of the feature to select, that is, one of current/default/saved/supported

xnvme_prep_adm_log

void xnvme_prep_adm_log(struct xnvme_cmd_ctx *ctx, uint8_t lid, uint8_t lsp, uint64_t lpo_nbytes, uint32_t nsid, uint8_t rae, uint32_t dbuf_nbytes)

Prepare NVMe Get Log Page command.

Parameters:

ctx – Pointer to xnvme_cmd_ctx
lid – Log Page Identifier for the log to retrieve entries for
lsp – Log Specific Field for the log to retrieve entries for
lpo_nbytes – Log page Offset in BYTES
nsid – Namespace Identifier
rae – Retain Asynchronous Event, 0=Clear, 1=Retain
dbuf_nbytes – Number of BYTES to write from log-page to buf

xnvme_prep_adm_sfeat

void xnvme_prep_adm_sfeat(struct xnvme_cmd_ctx *ctx, uint32_t nsid, uint8_t fid, uint32_t feat, uint8_t save)

Prepare NVMe Set Feature (sfeat) command.

Parameters:

ctx – Pointer to xnvme_cmd_ctx
nsid – Namespace identifier
fid – Feature identifier (see NVMe 1.3; Figure 84)
feat – Structure defining feature attributes
save – Specify that controller shall save the attribute

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.

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

Returns:

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

xnvme_subsystem_reset

Warning

doxygenfunction: Cannot find function “xnvme_subsystem_reset” in doxygen xml output for project “xNVMe” from directory: builddir/doxy/xml

xnvme_timer_bw_pr

static inline 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

static inline double xnvme_timer_elapsed(struct xnvme_timer *t)

Get the elapsed time in seconds.

Parameters:

t –

Returns:

elapsed time in seconds as a floating point number

xnvme_timer_elapsed_msecs

static inline double xnvme_timer_elapsed_msecs(struct xnvme_timer *t)

Get the elapsed time in milliseconds.

Parameters:

t –

Returns:

elapsed time in milliseconds as a floating point number

xnvme_timer_elapsed_nsecs

static inline uint64_t xnvme_timer_elapsed_nsecs(struct xnvme_timer *t)

Get the elapsed time in nanoseconds.

Parameters:

t –

Returns:

elapsed time in nanoseconds

xnvme_timer_elapsed_secs

static inline double xnvme_timer_elapsed_secs(struct xnvme_timer *t)

Get the elapsed time in seconds.

Parameters:

t –

Returns:

elapsed time in seconds as a floating point number

xnvme_timer_elapsed_usecs

static inline double xnvme_timer_elapsed_usecs(struct xnvme_timer *t)

Get the elapsed time in microseconds.

Parameters:

t –

Returns:

elapsed time in microseconds as a floating point number

xnvme_timer_pr

static inline 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

static inline uint64_t xnvme_timer_start(struct xnvme_timer *t)

Start the given timer.

Parameters:

t –

Returns:

clock sample in nano seconds

xnvme_timer_stop

static inline uint64_t xnvme_timer_stop(struct xnvme_timer *t)

Stop the given timer.

Parameters:

t –

Returns:

clock sample in nano seconds