util.h

libnvme utility functions

enum nvme_connect_err

nvme connect error codes

Constants

ENVME_CONNECT_RESOLVE

failed to resolve host

ENVME_CONNECT_ADDRFAM

unrecognized address family

ENVME_CONNECT_TRADDR

failed to get traddr

ENVME_CONNECT_TARG

need a transport (-t) argument

ENVME_CONNECT_AARG

need a address (-a) argument

ENVME_CONNECT_OPEN

failed to open nvme-fabrics device

ENVME_CONNECT_WRITE

failed to write to nvme-fabrics device

ENVME_CONNECT_READ

failed to read from nvme-fabrics device

ENVME_CONNECT_PARSE

failed to parse ctrl info

ENVME_CONNECT_INVAL_TR

invalid transport type

ENVME_CONNECT_LOOKUP_SUBSYS_NAME

failed to lookup subsystem name

ENVME_CONNECT_LOOKUP_SUBSYS

failed to lookup subsystem

ENVME_CONNECT_ALREADY

the connect attempt failed, already connected

ENVME_CONNECT_INVAL

invalid arguments/configuration

ENVME_CONNECT_ADDRINUSE

hostnqn already in use

ENVME_CONNECT_NODEV

invalid interface

ENVME_CONNECT_OPNOTSUPP

not supported

ENVME_CONNECT_CONNREFUSED

connection refused

ENVME_CONNECT_ADDRNOTAVAIL

cannot assign requested address

ENVME_CONNECT_IGNORED

connect attempt is ignored due to configuration

__u8 nvme_status_to_errno(int status, bool fabrics)

Converts nvme return status to errno

Parameters

int status

Return status from an nvme passthrough command

bool fabrics

Set to true if status is to a fabrics target.

Return

An errno representing the nvme status if it is an nvme status field, or unchanged status is < 0 since errno is already set.

const char *nvme_status_to_string(int status, bool fabrics)

Returns string describing nvme return status.

Parameters

int status

Return status from an nvme passthrough command

bool fabrics

Set to true if status is to a fabrics target.

Return

String representation of the nvme status if it is an nvme status field, or a standard errno string if status is < 0.

const char *nvme_errno_to_string(int err)

Returns string describing nvme connect failures

Parameters

int err

Returned error code from nvme_add_ctrl()

Return

String representation of the nvme connect error codes

void nvme_init_ctrl_list(struct nvme_ctrl_list *cntlist, __u16 num_ctrls, __u16 *ctrlist)

Initialize an nvme_ctrl_list structure from an array.

Parameters

struct nvme_ctrl_list *cntlist

The controller list structure to initialize

__u16 num_ctrls

The number of controllers in the array, ctrlist.

__u16 *ctrlist

An array of controller identifiers in CPU native endian.

Description

This is intended to be used with any command that takes a controller list argument. See nvme_ns_attach_ctrls() and nvme_ns_detach().

void nvme_init_dsm_range(struct nvme_dsm_range *dsm, __u32 *ctx_attrs, __u32 *llbas, __u64 *slbas, __u16 nr_ranges)

Constructs a data set range structure

Parameters

struct nvme_dsm_range *dsm

DSM range array

__u32 *ctx_attrs

Array of context attributes

__u32 *llbas

Array of length in logical blocks

__u64 *slbas

Array of starting logical blocks

__u16 nr_ranges

The size of the dsm arrays

Description

Each array must be the same size of size ‘nr_ranges’. This is intended to be used with constructing a payload for nvme_dsm().

Return

The nvme command status if a response was received or -errno otherwise.

void nvme_init_copy_range(struct nvme_copy_range *copy, __u16 *nlbs, __u64 *slbas, __u32 *eilbrts, __u32 *elbatms, __u32 *elbats, __u16 nr)

Constructs a copy range structure

Parameters

struct nvme_copy_range *copy

Copy range array

__u16 *nlbs

Number of logical blocks

__u64 *slbas

Starting LBA

__u32 *eilbrts

Expected initial logical block reference tag

__u32 *elbatms

Expected logical block application tag mask

__u32 *elbats

Expected logical block application tag

__u16 nr

Number of descriptors to construct

void nvme_init_copy_range_f1(struct nvme_copy_range_f1 *copy, __u16 *nlbs, __u64 *slbas, __u64 *eilbrts, __u32 *elbatms, __u32 *elbats, __u16 nr)

Constructs a copy range f1 structure

Parameters

struct nvme_copy_range_f1 *copy

Copy range array

__u16 *nlbs

Number of logical blocks

__u64 *slbas

Starting LBA

__u64 *eilbrts

Expected initial logical block reference tag

__u32 *elbatms

Expected logical block application tag mask

__u32 *elbats

Expected logical block application tag

__u16 nr

Number of descriptors to construct

void nvme_init_copy_range_f2(struct nvme_copy_range_f2 *copy, __u32 *snsids, __u16 *nlbs, __u64 *slbas, __u16 *sopts, __u32 *eilbrts, __u32 *elbatms, __u32 *elbats, __u16 nr)

Constructs a copy range f2 structure

Parameters

struct nvme_copy_range_f2 *copy

Copy range array

__u32 *snsids

Source namespace identifier

__u16 *nlbs

Number of logical blocks

__u64 *slbas

Starting LBA

__u16 *sopts

Source options

__u32 *eilbrts

Expected initial logical block reference tag

__u32 *elbatms

Expected logical block application tag mask

__u32 *elbats

Expected logical block application tag

__u16 nr

Number of descriptors to construct

void nvme_init_copy_range_f3(struct nvme_copy_range_f3 *copy, __u32 *snsids, __u16 *nlbs, __u64 *slbas, __u16 *sopts, __u64 *eilbrts, __u32 *elbatms, __u32 *elbats, __u16 nr)

Constructs a copy range f3 structure

Parameters

struct nvme_copy_range_f3 *copy

Copy range array

__u32 *snsids

Source namespace identifier

__u16 *nlbs

Number of logical blocks

__u64 *slbas

Starting LBA

__u16 *sopts

Source options

__u64 *eilbrts

Expected initial logical block reference tag

__u32 *elbatms

Expected logical block application tag mask

__u32 *elbats

Expected logical block application tag

__u16 nr

Number of descriptors to construct

int nvme_get_feature_length(int fid, __u32 cdw11, __u32 *len)

Retreive the command payload length for a specific feature identifier

Parameters

int fid

Feature identifier, see enum nvme_features_id.

__u32 cdw11

The cdw11 value may affect the transfer (only known fid is NVME_FEAT_FID_HOST_ID)

__u32 *len

On success, set to this features payload length in bytes.

Return

0 on success, -1 with errno set to EINVAL if the function did not recognize fid.

int nvme_get_feature_length2(int fid, __u32 cdw11, enum nvme_data_tfr dir, __u32 *len)

Retreive the command payload length for a specific feature identifier

Parameters

int fid

Feature identifier, see enum nvme_features_id.

__u32 cdw11

The cdw11 value may affect the transfer (only known fid is NVME_FEAT_FID_HOST_ID)

enum nvme_data_tfr dir

Data transfer direction: false - host to controller, true - controller to host may affect the transfer (only known fid is NVME_FEAT_FID_HOST_MEM_BUF).

__u32 *len

On success, set to this features payload length in bytes.

Return

0 on success, -1 with errno set to EINVAL if the function did not recognize fid.

int nvme_get_directive_receive_length(enum nvme_directive_dtype dtype, enum nvme_directive_receive_doper doper, __u32 *len)

Get directive receive length

Parameters

enum nvme_directive_dtype dtype

Directive type, see enum nvme_directive_dtype

enum nvme_directive_receive_doper doper

Directive receive operation, see enum nvme_directive_receive_doper

__u32 *len

On success, set to this directives payload length in bytes.

Return

0 on success, -1 with errno set to EINVAL if the function did not recognize dtype or doper.

size_t get_entity_name(char *buffer, size_t bufsz)

Get Entity Name (ENAME).

Parameters

char *buffer

The buffer where the ENAME will be saved as an ASCII string.

size_t bufsz

The size of buffer.

Description

Per TP8010, ENAME is defined as the name associated with the host (i.e. hostname).

Return

Number of characters copied to buffer.

size_t get_entity_version(char *buffer, size_t bufsz)

Get Entity Version (EVER).

Parameters

char *buffer

The buffer where the EVER will be saved as an ASCII string.

size_t bufsz

The size of buffer.

Description

EVER is defined as the operating system name and version as an ASCII string. This function reads different files from the file system and builds a string as follows: [os type] [os release] [distro release]

E.g. “Linux 5.17.0-rc1 SLES 15.4”

Return

Number of characters copied to buffer.

char *kv_strip(char *kv)

Strip blanks from key value string

Parameters

char *kv

The key-value string to strip

Description

Strip leading/trailing blanks as well as trailing comments from the Key=Value string pointed to by kv.

Return

A pointer to the stripped string. Note that the original string, kv, gets modified.

char *kv_keymatch(const char *kv, const char *key)

Look for key in key value string

Parameters

const char *kv

The key=value string to search for the presence of key

const char *key

The key to look for

Description

Look for key in the Key=Value pair pointed to by k and return a pointer to the Value if key is found.

Check if kv starts with key. If it does then make sure that we have a whole-word match on the key, and if we do, return a pointer to the first character of value (i.e. skip leading spaces, tabs, and equal sign)

Return

A pointer to the first character of “value” if a match is found. NULL otherwise.

char *startswith(const char *s, const char *prefix)

Checks that a string starts with a given prefix.

Parameters

const char *s

The string to check

const char *prefix

A string that s could be starting with

Return

If s starts with prefix, then return a pointer within s at the first character after the matched prefix. NULL otherwise.

round_up

round_up (val, mult)

Round a value val to the next multiple specified by mult.

Parameters

val

Value to round

mult

Multiple to round to.

Description

usage: int x = round_up(13, sizeof(__u32)); // 13 -> 16

__u16 nvmf_exat_len(size_t val_len)

Return length rounded up by 4

Parameters

size_t val_len

Value length

Description

Return the size in bytes, rounded to a multiple of 4 (e.g., size of __u32), of the buffer needed to hold the exat value of size val_len.

Return

Length rounded up by 4

__u16 nvmf_exat_size(size_t val_len)

Return min aligned size to hold value

Parameters

size_t val_len

This is the length of the data to be copied to the “exatval” field of a “struct nvmf_ext_attr”.

Description

Return the size of the “struct nvmf_ext_attr” needed to hold a value of size val_len.

Return

The size in bytes, rounded to a multiple of 4 (i.e. size of __u32), of the “struct nvmf_ext_attr” required to hold a string of length val_len.

struct nvmf_ext_attr *nvmf_exat_ptr_next(struct nvmf_ext_attr *p)

Increment p to the next element in the array.

Parameters

struct nvmf_ext_attr *p

Pointer to an element of an array of “struct nvmf_ext_attr”.

Description

Extended attributes are saved to an array of “struct nvmf_ext_attr” where each element of the array is of variable size. In order to move to the next element in the array one must increment the pointer to the current element (p) by the size of the current element.

Return

Pointer to the next element in the array.

enum nvme_version

Selector for version to be returned by nvme_get_version

Constants

NVME_VERSION_PROJECT

Project release version

NVME_VERSION_GIT

Git reference

const char *nvme_get_version(enum nvme_version type)

Return version libnvme string

Parameters

enum nvme_version type

Selects which version type (see struct nvme_version)

Return

Returns version string for known types or else “n/a”

int nvme_uuid_to_string(unsigned char uuid[NVME_UUID_LEN], char *str)

Return string represenation of encoded UUID

Parameters

unsigned char uuid[NVME_UUID_LEN]

Binary encoded input UUID

char *str

Output string represenation of UUID

Return

Returns error code if type conversion fails.

int nvme_uuid_from_string(const char *str, unsigned char uuid[NVME_UUID_LEN])

Return encoded UUID represenation of string UUID

Parameters

const char *str

Output string represenation of UUID

unsigned char uuid[NVME_UUID_LEN]

Binary encoded input UUID

Return

Returns error code if type conversion fails.

int nvme_uuid_random(unsigned char uuid[NVME_UUID_LEN])

Generate random UUID

Parameters

unsigned char uuid[NVME_UUID_LEN]

Generated random UUID

Description

Generate random number according https://www.rfc-editor.org/rfc/rfc4122#section-4.4

Return

Returns error code if generating of random number fails.

int nvme_uuid_find(struct nvme_id_uuid_list *uuid_list, const unsigned char uuid[NVME_UUID_LEN])

Find UUID position on UUID list

Parameters

struct nvme_id_uuid_list *uuid_list

UUID list returned by identify UUID

const unsigned char uuid[NVME_UUID_LEN]

Binary encoded input UUID

Return

The array position where given UUID is present, or -1 on failure with errno set.

bool nvme_ipaddrs_eq(const char *addr1, const char *addr2)

Check if 2 IP addresses are equal.

Parameters

const char *addr1

IP address (can be IPv4 or IPv6)

const char *addr2

IP address (can be IPv4 or IPv6)

Return

true if addr1 == addr2. false otherwise.

const char *nvme_iface_matching_addr(const struct ifaddrs *iface_list, const char *addr)

Get interface matching addr

Parameters

const struct ifaddrs *iface_list

Interface list returned by getifaddrs()

const char *addr

Address to match

Description

Parse the interface list pointed to by iface_list looking for the interface that has addr as one of its assigned addresses.

Return

The name of the interface that owns addr or NULL.

bool nvme_iface_primary_addr_matches(const struct ifaddrs *iface_list, const char *iface, const char *addr)

Check that interface’s primary address matches

Parameters

const struct ifaddrs *iface_list

Interface list returned by getifaddrs()

const char *iface

Interface to match

const char *addr

Address to match

Description

Parse the interface list pointed to by iface_list and looking for interface iface. The get its primary address and check if it matches addr.

Return

true if a match is found, false otherwise.