libxnvme_dev.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.

Functions#

xnvme_dev_close#

void xnvme_dev_close(struct xnvme_dev *dev)#

Destroy the given device handle (xnvme_dev)

Parameters:

dev – Device handle obtained with xnvme_dev_open()

xnvme_dev_derive_geo#

int xnvme_dev_derive_geo(struct xnvme_dev *dev)#

Derive the geometry of the given device.

This is done through a sequence of NVMe controller-register-reads, identify-controller/namespace commands, sysfs-probes, and ioctl()/stat()/ fstat() system calls. The system-interface and methods utilized are backend-specific.

Parameters:

dev – Device handle obtained with xnvme_dev_open()

Returns:

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

xnvme_dev_fpr#

int xnvme_dev_fpr(FILE *stream, const struct xnvme_dev *dev, int opts)#

Prints the given xnvme_dev to the given output stream.

Parameters:

stream – output stream used for printing
dev – pointer to structure to print
opts – printer options, see xnvme_pr

Returns:

On success, the number of characters printed is returned.

xnvme_dev_get_be_state#

const void *xnvme_dev_get_be_state(const struct xnvme_dev *dev)#

Returns the internal backend state of the given dev

Parameters:

dev – Device handle obtained with xnvme_dev_open()

Returns:

On success, the internal backend state is returned.

xnvme_dev_get_csi#

uint8_t xnvme_dev_get_csi(const struct xnvme_dev *dev)#

Returns the NVMe Command Set Identifier associated with the given dev

Parameters:

dev – Device handle obtained with xnvme_dev_open()

Returns:

On success, NVMe Command Set Identifier is returned

xnvme_dev_get_ctrlr#

const struct xnvme_spec_idfy_ctrlr *xnvme_dev_get_ctrlr(const struct xnvme_dev *dev)#

Returns the NVMe identify controller structure associated with the given device.

Parameters:

dev – Device handle obtained with xnvme_dev_open()

Returns:

On success, pointer to namespace structure. On error, NULL is returned and errno is set to indicate the error

xnvme_dev_get_ctrlr_css#

const struct xnvme_spec_idfy_ctrlr *xnvme_dev_get_ctrlr_css(const struct xnvme_dev *dev)#

Returns the NVMe identify controller structure specific to the Command Set and Namespace associated with the given device.

Parameters:

dev – Device handle obtained with xnvme_dev_open()

Returns:

On success, pointer to namespace structure. On error, NULL is returned and errno is set to indicate the error

xnvme_dev_get_geo#

const struct xnvme_geo *xnvme_dev_get_geo(const struct xnvme_dev *dev)#

Returns the geometry of the given device.

Parameters:

dev – Device handle obtained with xnvme_dev_open()

Returns:

The geometry (struct xnvme_geo) of given device handle

xnvme_dev_get_ident#

const struct xnvme_ident *xnvme_dev_get_ident(const struct xnvme_dev *dev)#

Returns the representation of device identifier once decoded from text-representation for the given dev

Parameters:

dev – Device handle obtained with xnvme_dev_open() / xnvme_dev_openf()

Returns:

On success, device identifier is returned

xnvme_dev_get_ns#

const struct xnvme_spec_idfy_ns *xnvme_dev_get_ns(const struct xnvme_dev *dev)#

Returns the NVMe identify namespace structure associated with the given device.

Parameters:

dev – Device handle obtained with xnvme_dev_open()

Returns:

On success, pointer to namespace structure. On error, NULL is returned and errno is set to indicate the error

xnvme_dev_get_ns_css#

const struct xnvme_spec_idfy_ns *xnvme_dev_get_ns_css(const struct xnvme_dev *dev)#

Returns the NVMe identify namespace structure specific to the Command Set and Namespace associated with the given device.

Parameters:

dev – Device handle obtained with xnvme_dev_open()

Returns:

On success, pointer to namespace structure. On error, NULL is returned and errno is set to indicate the error

xnvme_dev_get_nsid#

uint32_t xnvme_dev_get_nsid(const struct xnvme_dev *dev)#

Returns the NVMe namespace identifier associated with the given dev

Parameters:

dev – Device handle obtained with xnvme_dev_open()

Returns:

On success, NVMe namespace identifier is returned

xnvme_dev_get_opts#

const struct xnvme_opts *xnvme_dev_get_opts(const struct xnvme_dev *dev)#

Returns the opts struct for the given dev

Parameters:

dev – Device handle obtained with xnvme_dev_open() / xnvme_dev_openf()

Returns:

On success, device options are returned

xnvme_dev_get_ssw#

uint64_t xnvme_dev_get_ssw(const struct xnvme_dev *dev)#

Returns the sector-shift-width of the device, that is, the value used for converting block-device offset to lba, and vice-versa.

lba = ofz >> ssw ofz = lba << ssw

Returns:: On success, the ssw is returned.

xnvme_dev_open#

struct xnvme_dev *xnvme_dev_open(const char *dev_uri, struct xnvme_opts *opts)#

Creates a device handle (xnvme_dev) based on the given device-uri.

Parameters:

dev_uri – File path “/dev/nvme0n1” or “0000:04.01”
opts – Options for library backend and system-interfaces

Returns:

On success, a handle to the device. On error, NULL is returned and errno set to indicate the error.

xnvme_dev_pr#

int xnvme_dev_pr(const struct xnvme_dev *dev, int opts)#

Prints the given xnvme_dev to stdout.

Parameters:

dev – pointer to structure to print
opts – printer options, see xnvme_pr

Returns:

On success, the number of characters printed is returned.

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.