util.h
libnvme utility functions
-
enum
nvme_connect_err nvme connect error codes
Constants
ENVME_CONNECT_RESOLVEfailed to resolve host
ENVME_CONNECT_ADDRFAMunrecognized address family
ENVME_CONNECT_TRADDRfailed to get traddr
ENVME_CONNECT_TARGneed a transport (-t) argument
ENVME_CONNECT_AARGneed a address (-a) argument
ENVME_CONNECT_OPENfailed to open nvme-fabrics device
ENVME_CONNECT_WRITEfailed to write to nvme-fabrics device
ENVME_CONNECT_READfailed to read from nvme-fabrics device
ENVME_CONNECT_PARSEfailed to parse ctrl info
ENVME_CONNECT_INVAL_TRinvalid transport type
ENVME_CONNECT_LOOKUP_SUBSYS_NAMEfailed to lookup subsystem name
ENVME_CONNECT_LOOKUP_SUBSYSfailed to lookup subsystem
ENVME_CONNECT_ALREADYthe connect attempt failed, already connected
ENVME_CONNECT_INVALinvalid arguments/configuration
ENVME_CONNECT_ADDRINUSEhostnqn already in use
ENVME_CONNECT_NODEVinvalid interface
ENVME_CONNECT_OPNOTSUPPnot supported
ENVME_CONNECT_CONNREFUSEDconnection refused
ENVME_CONNECT_ADDRNOTAVAILcannot assign requested address
ENVME_CONNECT_IGNOREDconnect attempt is ignored due to configuration
-
__u8
nvme_status_to_errno(int status, bool fabrics) Converts nvme return status to errno
Parameters
int statusReturn status from an nvme passthrough command
bool fabricsSet to true if
statusis 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 statusReturn status from an nvme passthrough command
bool fabricsSet to true if
statusis 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 errReturned 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 *cntlistThe controller list structure to initialize
__u16 num_ctrlsThe number of controllers in the array,
ctrlist.__u16 *ctrlistAn 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 *dsmDSM range array
__u32 *ctx_attrsArray of context attributes
__u32 *llbasArray of length in logical blocks
__u64 *slbasArray of starting logical blocks
__u16 nr_rangesThe 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 *copyCopy range array
__u16 *nlbsNumber of logical blocks
__u64 *slbasStarting LBA
__u32 *eilbrtsExpected initial logical block reference tag
__u32 *elbatmsExpected logical block application tag mask
__u32 *elbatsExpected logical block application tag
__u16 nrNumber 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 *copyCopy range array
__u16 *nlbsNumber of logical blocks
__u64 *slbasStarting LBA
__u64 *eilbrtsExpected initial logical block reference tag
__u32 *elbatmsExpected logical block application tag mask
__u32 *elbatsExpected logical block application tag
__u16 nrNumber 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 fidFeature identifier, see
enum nvme_features_id.__u32 cdw11The cdw11 value may affect the transfer (only known fid is
NVME_FEAT_FID_HOST_ID)__u32 *lenOn 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 fidFeature identifier, see
enum nvme_features_id.__u32 cdw11The cdw11 value may affect the transfer (only known fid is
NVME_FEAT_FID_HOST_ID)enum nvme_data_tfr dirData 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 *lenOn 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 dtypeDirective type, see
enum nvme_directive_dtypeenum nvme_directive_receive_doper doperDirective receive operation, see
enum nvme_directive_receive_doper__u32 *lenOn 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 *bufferThe buffer where the ENAME will be saved as an ASCII string.
size_t bufszThe 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 *bufferThe buffer where the EVER will be saved as an ASCII string.
size_t bufszThe 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 *kvThe 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 *kvThe key=value string to search for the presence of key
const char *keyThe 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 *sThe string to check
const char *prefixA 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
valValue to round
multMultiple 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_lenValue 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_lenThis 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 *pPointer 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_PROJECTProject release version
NVME_VERSION_GITGit reference
-
const char *
nvme_get_version(enum nvme_version type) Return version libnvme string
Parameters
enum nvme_version typeSelects 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 *strOutput 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 *strOutput 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.
-
bool
nvme_ipaddrs_eq(const char *addr1, const char *addr2) Check if 2 IP addresses are equal.
Parameters
const char *addr1IP address (can be IPv4 or IPv6)
const char *addr2IP 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_listInterface list returned by getifaddrs()
const char *addrAddress 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_listInterface list returned by getifaddrs()
const char *ifaceInterface to match
const char *addrAddress 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.