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
__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
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(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.