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.