xnvme_dev¶

Header¶

#ifndef __LIBXNVME_DEV_H
#define __LIBXNVME_DEV_H
#include <libxnvme.h>

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

/**
 * Returns the geometry of the given device
 *
 * @param dev Device handle obtained with xnvme_dev_open()
 *
 * @return The geometry (struct xnvme_geo) of given device handle
 */
const struct xnvme_geo *
xnvme_dev_get_geo(const struct xnvme_dev *dev);

/**
 * Returns the NVMe identify controller structure associated with the given
 * device
 *
 * @param dev Device handle obtained with xnvme_dev_open()
 *
 * @return On success, pointer to namespace structure. On error, NULL is
 * returned and `errno` is set to indicate the error
 */
const struct xnvme_spec_idfy_ctrlr *
xnvme_dev_get_ctrlr(const struct xnvme_dev *dev);

/**
 * Returns the NVMe identify controller structure specific to the Command Set
 * and Namespace associated with the given device
 *
 * @param dev Device handle obtained with xnvme_dev_open()
 *
 * @return On success, pointer to namespace structure. On error, NULL is
 * returned and `errno` is set to indicate the error
 */
const struct xnvme_spec_idfy_ctrlr *
xnvme_dev_get_ctrlr_css(const struct xnvme_dev *dev);

/**
 * Returns the NVMe identify namespace structure associated with the given
 * device
 *
 * @param dev Device handle obtained with xnvme_dev_open()
 *
 * @return On success, pointer to namespace structure. On error, NULL is
 * returned and `errno` is set to indicate the error
 */
const struct xnvme_spec_idfy_ns *
xnvme_dev_get_ns(const struct xnvme_dev *dev);

/**
 * Returns the NVMe identify namespace structure specific to the Command Set and
 * Namespace associated with the given device
 *
 * @param dev Device handle obtained with xnvme_dev_open()
 *
 * @return On success, pointer to namespace structure. On error, NULL is
 * returned and `errno` is set to indicate the error
 */
const struct xnvme_spec_idfy_ns *
xnvme_dev_get_ns_css(const struct xnvme_dev *dev);

/**
 * Returns the NVMe namespace identifier associated with the given `dev`
 *
 * @param dev Device handle obtained with xnvme_dev_open()
 *
 * @return On success, NVMe namespace identifier is returned
 */
uint32_t
xnvme_dev_get_nsid(const struct xnvme_dev *dev);

/**
 * Returns the NVMe Command Set Identifier associated with the given `dev`
 *
 * @param dev Device handle obtained with xnvme_dev_open()
 *
 * @return On success, NVMe Command Set Identifier is returned
 */
uint8_t
xnvme_dev_get_csi(const struct xnvme_dev *dev);

/**
 * Returns the representation of device identifier once decoded from
 * text-representation for the given `dev`
 *
 * @param dev Device handle obtained with xnvme_dev_open() / xnvme_dev_openf()
 *
 * @return On success, device identifier is returned
 */
const struct xnvme_ident *
xnvme_dev_get_ident(const struct xnvme_dev *dev);

/**
 * Returns the opts struct for the given `dev`
 *
 * @param dev Device handle obtained with xnvme_dev_open() / xnvme_dev_openf()
 *
 * @return On success, device options are returned
 */
const struct xnvme_opts *
xnvme_dev_get_opts(const struct xnvme_dev *dev);

/**
 * Returns the internal backend state of the given `dev`
 *
 * @param dev Device handle obtained with xnvme_dev_open()
 *
 * @return On success, the internal backend state is returned.
 */
const void *
xnvme_dev_get_be_state(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
 *
 * @return On success, the ssw is returned.
 */
uint64_t
xnvme_dev_get_ssw(const struct xnvme_dev *dev);

#endif /* __LIBXNVME_NVM */

Enums¶

Structs¶

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_fpr¶

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

Prints the given xnvme_dev to the given output stream.

Return

On success, the number of characters printed is returned.

Parameters

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

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

Return

On success, the internal backend state is returned.

Parameters

dev: Device handle obtained with xnvme_dev_open()

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

Return

On success, NVMe Command Set Identifier is returned

Parameters

dev: Device handle obtained with xnvme_dev_open()

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.

Return

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

Parameters

dev: Device handle obtained with xnvme_dev_open()

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.

Return

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

Parameters

dev: Device handle obtained with xnvme_dev_open()

xnvme_dev_get_geo¶

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

Returns the geometry of the given device.

Return

The geometry (struct xnvme_geo) of given device handle

Parameters

dev: Device handle obtained with xnvme_dev_open()

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

Return

On success, device identifier is returned

Parameters

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

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.

Return

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

Parameters

dev: Device handle obtained with xnvme_dev_open()

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.

Return

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

Parameters

dev: Device handle obtained with xnvme_dev_open()

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

Return

On success, NVMe namespace identifier is returned

Parameters

dev: Device handle obtained with xnvme_dev_open()

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

Return

On success, device options are returned

Parameters

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

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

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

Return

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

Parameters

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

xnvme_dev_pr¶

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

Prints the given xnvme_dev to stdout.

Return

On success, the number of characters printed is returned.

Parameters

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