nvme/libnvme
1
0
Fork 0
Code Issues Activity

Merging upstream version 1.1~rc0.

Browse source 
Signed-off-by: Daniel Baumann <daniel@debian.org>
This commit is contained in:
Daniel Baumann 2025-02-16 10:03:28 +01:00
parent 537ee18b08
commit 73281abe5f
Signed by: daniel
GPG key ID: FBB4F0E80A80222F
764 changed files with 32602 additions and 5874 deletions
Download patch file Download diff file Expand all files Collapse all files

446
doc/rst/fabrics.rst Normal file
View file

@ -0,0 +1,446 @@
.. _fabrics.h:
**fabrics.h**
Fabrics-specific definitions.
.. c:struct:: nvme_fabrics_config
Defines all linux nvme fabrics initiator options
**Definition**
::
struct nvme_fabrics_config {
char *host_traddr;
char *host_iface;
int queue_size;
int nr_io_queues;
int reconnect_delay;
int ctrl_loss_tmo;
int fast_io_fail_tmo;
int keep_alive_tmo;
int nr_write_queues;
int nr_poll_queues;
int tos;
bool duplicate_connect;
bool disable_sqflow;
bool hdr_digest;
bool data_digest;
bool tls;
};
**Members**
``host_traddr``
Host transport address
``host_iface``
Host interface name
``queue_size``
Number of IO queue entries
``nr_io_queues``
Number of controller IO queues to establish
``reconnect_delay``
Time between two consecutive reconnect attempts.
``ctrl_loss_tmo``
Override the default controller reconnect attempt timeout in seconds
``fast_io_fail_tmo``
Set the fast I/O fail timeout in seconds.
``keep_alive_tmo``
Override the default keep-alive-timeout to this value in seconds
``nr_write_queues``
Number of queues to use for exclusively for writing
``nr_poll_queues``
Number of queues to reserve for polling completions
``tos``
Type of service
``duplicate_connect``
Allow multiple connections to the same target
``disable_sqflow``
Disable controller sq flow control
``hdr_digest``
Generate/verify header digest (TCP)
``data_digest``
Generate/verify data digest (TCP)
``tls``
Start TLS on the connection (TCP)
.. c:function:: const char * nvmf_trtype_str (__u8 trtype)
Decode TRTYPE field
**Parameters**
``__u8 trtype``
value to be decoded
**Description**
Decode the transport type field in the discovery
log page entry.
**Return**
decoded string
.. c:function:: const char * nvmf_adrfam_str (__u8 adrfam)
Decode ADRFAM field
**Parameters**
``__u8 adrfam``
value to be decoded
**Description**
Decode the address family field in the discovery
log page entry.
**Return**
decoded string
.. c:function:: const char * nvmf_subtype_str (__u8 subtype)
Decode SUBTYPE field
**Parameters**
``__u8 subtype``
value to be decoded
**Description**
Decode the subsystem type field in the discovery
log page entry.
**Return**
decoded string
.. c:function:: const char * nvmf_treq_str (__u8 treq)
Decode TREQ field
**Parameters**
``__u8 treq``
value to be decoded
**Description**
Decode the transport requirements field in the
discovery log page entry.
**Return**
decoded string
.. c:function:: const char * nvmf_eflags_str (__u16 eflags)
Decode EFLAGS field
**Parameters**
``__u16 eflags``
value to be decoded
**Description**
Decode the EFLAGS field in the discovery log page
entry.
**Return**
decoded string
.. c:function:: const char * nvmf_sectype_str (__u8 sectype)
Decode SECTYPE field
**Parameters**
``__u8 sectype``
value to be decoded
**Description**
Decode the SECTYPE field in the discovery log page
entry.
**Return**
decoded string
.. c:function:: const char * nvmf_prtype_str (__u8 prtype)
Decode RDMA Provider type field
**Parameters**
``__u8 prtype``
value to be decoded
**Description**
Decode the RDMA Provider type field in the discovery
log page entry.
**Return**
decoded string
.. c:function:: const char * nvmf_qptype_str (__u8 qptype)
Decode RDMA QP Service type field
**Parameters**
``__u8 qptype``
value to be decoded
**Description**
Decode the RDMA QP Service type field in the discovery log page
entry.
**Return**
decoded string
.. c:function:: const char * nvmf_cms_str (__u8 cms)
Decode RDMA connection management service field
**Parameters**
``__u8 cms``
value to be decoded
**Description**
Decode the RDMA connection management service field in the discovery
log page entry.
**Return**
decoded string
.. c:function:: void nvmf_default_config (struct nvme_fabrics_config *cfg)
Default values for fabrics configuration
**Parameters**
``struct nvme_fabrics_config *cfg``
config values to set
**Description**
Initializes **cfg** with default values.
.. c:function:: void nvmf_update_config (nvme_ctrl_t c, const struct nvme_fabrics_config *cfg)
Update fabrics configuration values
**Parameters**
``nvme_ctrl_t c``
Controller to be modified
``const struct nvme_fabrics_config *cfg``
Updated configuration values
**Description**
Updates the values from **c** with the configuration values from **cfg**;
all non-default values from **cfg** will overwrite the values in **c**.
.. c:function:: int nvmf_add_ctrl (nvme_host_t h, nvme_ctrl_t c, const struct nvme_fabrics_config *cfg)
Connect a controller and update topology
**Parameters**
``nvme_host_t h``
Host to which the controller should be attached
``nvme_ctrl_t c``
Controller to be connected
``const struct nvme_fabrics_config *cfg``
Default configuration for the controller
**Description**
Issues a 'connect' command to the NVMe-oF controller and inserts **c**
into the topology using **h** as parent.
**c** must be initialized and not connected to the topology.
**Return**
0 on success; on failure errno is set and -1 is returned.
.. c:function:: int nvmf_get_discovery_log (nvme_ctrl_t c, struct nvmf_discovery_log **logp, int max_retries)
Return the discovery log page
**Parameters**
``nvme_ctrl_t c``
Discover controller to use
``struct nvmf_discovery_log **logp``
Pointer to the log page to be returned
``int max_retries``
maximum number of log page entries to be returned
**Return**
0 on success; on failure -1 is returned and errno is set
.. c:function:: char * nvmf_hostnqn_generate ()
Generate a machine specific host nqn
**Parameters**
**Return**
An nvm namespace qualified name string based on the machine
identifier, or NULL if not successful.
.. c:function:: char * nvmf_hostnqn_from_file ()
Reads the host nvm qualified name from the config default location in /etc/nvme/
**Parameters**
**Return**
The host nqn, or NULL if unsuccessful. If found, the caller
is responsible to free the string.
.. c:function:: char * nvmf_hostid_from_file ()
Reads the host identifier from the config default location in /etc/nvme/.
**Parameters**
**Return**
The host identifier, or NULL if unsuccessful. If found, the caller
is responsible to free the string.
.. c:function:: nvme_ctrl_t nvmf_connect_disc_entry (nvme_host_t h, struct nvmf_disc_log_entry *e, const struct nvme_fabrics_config *defcfg, bool *discover)
Connect controller based on the discovery log page entry
**Parameters**
``nvme_host_t h``
Host to which the controller should be connected
``struct nvmf_disc_log_entry *e``
Discovery log page entry
``const struct nvme_fabrics_config *defcfg``
Default configuration to be used for the new controller
``bool *discover``
Set to 'true' if the new controller is a discovery controller
**Return**
Pointer to the new controller
.. c:function:: bool nvmf_is_registration_supported (nvme_ctrl_t c)
check whether registration can be performed.
**Parameters**
``nvme_ctrl_t c``
Controller instance
**Description**
Only discovery controllers (DC) that comply with TP8010 support
explicit registration with the DIM PDU. These can be identified by
looking at the value of a dctype in the Identify command
response. A value of 1 (DDC) or 2 (CDC) indicates that the DC
supports explicit registration.
**Return**
true if controller supports explicit registration. false
otherwise.
.. c:function:: int nvmf_register_ctrl (nvme_ctrl_t c, enum nvmf_dim_tas tas, __u32 *result)
Perform registration task with a DC
**Parameters**
``nvme_ctrl_t c``
Controller instance
``enum nvmf_dim_tas tas``
Task field of the Command Dword 10 (cdw10). Indicates whether to
perform a Registration, Deregistration, or Registration-update.
``__u32 *result``
The command-specific result returned by the DC upon command
completion.
**Description**
Perform registration task with a Discovery Controller (DC). Three
tasks are supported: register, deregister, and registration update.
**Return**
0 on success; on failure -1 is returned and errno is set

142
doc/rst/filters.rst Normal file
View file

@ -0,0 +1,142 @@
.. _filters.h:
**filters.h**
libnvme directory filter
.. c:function:: int nvme_namespace_filter (const struct dirent *d)
Filter for namespaces
**Parameters**
``const struct dirent *d``
dirent to check
**Return**
1 if **d** matches, 0 otherwise
.. c:function:: int nvme_paths_filter (const struct dirent *d)
Filter for paths
**Parameters**
``const struct dirent *d``
dirent to check
**Return**
1 if **d** matches, 0 otherwise
.. c:function:: int nvme_ctrls_filter (const struct dirent *d)
Filter for controllers
**Parameters**
``const struct dirent *d``
dirent to check
**Return**
1 if **d** matches, 0 otherwise
.. c:function:: int nvme_subsys_filter (const struct dirent *d)
Filter for subsystems
**Parameters**
``const struct dirent *d``
dirent to check
**Return**
1 if **d** matches, 0 otherwise
.. c:function:: int nvme_scan_subsystems (struct dirent ***subsys)
Scan for subsystems
**Parameters**
``struct dirent ***subsys``
Pointer to array of dirents
**Return**
number of entries in **subsys**
.. c:function:: int nvme_scan_subsystem_namespaces (nvme_subsystem_t s, struct dirent ***ns)
Scan for namespaces in a subsystem
**Parameters**
``nvme_subsystem_t s``
Subsystem to scan
``struct dirent ***ns``
Pointer to array of dirents
**Return**
number of entries in **ns**
.. c:function:: int nvme_scan_ctrls (struct dirent ***ctrls)
Scan for controllers
**Parameters**
``struct dirent ***ctrls``
Pointer to array of dirents
**Return**
number of entries in **ctrls**
.. c:function:: int nvme_scan_ctrl_namespace_paths (nvme_ctrl_t c, struct dirent ***paths)
Scan for namespace paths in a controller
**Parameters**
``nvme_ctrl_t c``
Controller to scan
``struct dirent ***paths``
Pointer to array of dirents
**Return**
number of entries in **paths**
.. c:function:: int nvme_scan_ctrl_namespaces (nvme_ctrl_t c, struct dirent ***ns)
Scan for namespaces in a controller
**Parameters**
``nvme_ctrl_t c``
Controller to scan
``struct dirent ***ns``
Pointer to array of dirents
**Return**
number of entries in **ns**

4712
doc/rst/ioctl.rst Normal file
View file

File diff suppressed because it is too large Load diff

342
doc/rst/linux.rst Normal file
View file

@ -0,0 +1,342 @@
.. _linux.h:
**linux.h**
linux-specific utility functions
.. c:function:: int nvme_fw_download_seq (int fd, __u32 size, __u32 xfer, __u32 offset, void *buf)
Firmware download sequence
**Parameters**
``int fd``
File descriptor of nvme device
``__u32 size``
Total size of the firmware image to transfer
``__u32 xfer``
Maximum size to send with each partial transfer
``__u32 offset``
Starting offset to send with this firmware download
``void *buf``
Address of buffer containing all or part of the firmware image.
**Return**
The nvme command status if a response was received (see
:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise.
.. c:enum:: nvme_telemetry_da
Telemetry Log Data Area
**Constants**
``NVME_TELEMETRY_DA_1``
Data Area 1
``NVME_TELEMETRY_DA_2``
Data Area 2
``NVME_TELEMETRY_DA_3``
Data Area 3
``NVME_TELEMETRY_DA_4``
Data Area 4
.. c:function:: int nvme_get_ctrl_telemetry (int fd, bool rae, struct nvme_telemetry_log **log, enum nvme_telemetry_da da, size_t *size)
Get controller telemetry log
**Parameters**
``int fd``
File descriptor of nvme device
``bool rae``
Retain asynchronous events
``struct nvme_telemetry_log **log``
On success, set to the value of the allocated and retrieved log.
``enum nvme_telemetry_da da``
Log page data area, valid values: :c:type:`enum nvme_telemetry_da <nvme_telemetry_da>`
``size_t *size``
Ptr to the telemetry log size, so it can be returned
**Description**
The total size allocated can be calculated as:
(nvme_telemetry_log da size + 1) * NVME_LOG_TELEM_BLOCK_SIZE.
**Return**
The nvme command status if a response was received (see
:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise.
.. c:function:: int nvme_get_host_telemetry (int fd, struct nvme_telemetry_log **log, enum nvme_telemetry_da da, size_t *size)
Get host telemetry log
**Parameters**
``int fd``
File descriptor of nvme device
``struct nvme_telemetry_log **log``
On success, set to the value of the allocated and retrieved log.
``enum nvme_telemetry_da da``
Log page data area, valid values: :c:type:`enum nvme_telemetry_da <nvme_telemetry_da>`
``size_t *size``
Ptr to the telemetry log size, so it can be returned
**Description**
The total size allocated can be calculated as:
(nvme_telemetry_log da size + 1) * NVME_LOG_TELEM_BLOCK_SIZE.
**Return**
The nvme command status if a response was received (see
:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise.
.. c:function:: int nvme_get_new_host_telemetry (int fd, struct nvme_telemetry_log **log, enum nvme_telemetry_da da, size_t *size)
Get new host telemetry log
**Parameters**
``int fd``
File descriptor of nvme device
``struct nvme_telemetry_log **log``
On success, set to the value of the allocated and retrieved log.
``enum nvme_telemetry_da da``
Log page data area, valid values: :c:type:`enum nvme_telemetry_da <nvme_telemetry_da>`
``size_t *size``
Ptr to the telemetry log size, so it can be returned
**Description**
The total size allocated can be calculated as:
(nvme_telemetry_log da size + 1) * NVME_LOG_TELEM_BLOCK_SIZE.
**Return**
The nvme command status if a response was received (see
:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise.
.. c:function:: int nvme_get_log_page (int fd, __u32 xfer_len, struct nvme_get_log_args *args)
Get log page data
**Parameters**
``int fd``
File descriptor of nvme device
``__u32 xfer_len``
Max log transfer size per request to split the total.
``struct nvme_get_log_args *args``
:c:type:`struct nvme_get_log_args <nvme_get_log_args>` argument structure
**Return**
The nvme command status if a response was received (see
:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise.
.. c:function:: int nvme_get_ana_log_len (int fd, size_t *analen)
Retrieve size of the current ANA log
**Parameters**
``int fd``
File descriptor of nvme device
``size_t *analen``
Pointer to where the length will be set on success
**Return**
The nvme command status if a response was received (see
:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise.
.. c:function:: int nvme_get_logical_block_size (int fd, __u32 nsid, int *blksize)
Retrieve block size
**Parameters**
``int fd``
File descriptor of nvme device
``__u32 nsid``
Namespace id
``int *blksize``
Pointer to where the block size will be set on success
**Return**
The nvme command status if a response was received (see
:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise.
.. c:function:: int nvme_get_lba_status_log (int fd, bool rae, struct nvme_lba_status_log **log)
Retrieve the LBA Status log page
**Parameters**
``int fd``
File descriptor of the nvme device
``bool rae``
Retain asynchronous events
``struct nvme_lba_status_log **log``
On success, set to the value of the allocated and retrieved log.
**Return**
The nvme command status if a response was received (see
:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise.
.. c:function:: int nvme_namespace_attach_ctrls (int fd, __u32 nsid, __u16 num_ctrls, __u16 *ctrlist)
Attach namespace to controller(s)
**Parameters**
``int fd``
File descriptor of nvme device
``__u32 nsid``
Namespace ID to attach
``__u16 num_ctrls``
Number of controllers in ctrlist
``__u16 *ctrlist``
List of controller IDs to perform the attach action
**Return**
The nvme command status if a response was received (see
:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise.
.. c:function:: int nvme_namespace_detach_ctrls (int fd, __u32 nsid, __u16 num_ctrls, __u16 *ctrlist)
Detach namespace from controller(s)
**Parameters**
``int fd``
File descriptor of nvme device
``__u32 nsid``
Namespace ID to detach
``__u16 num_ctrls``
Number of controllers in ctrlist
``__u16 *ctrlist``
List of controller IDs to perform the detach action
**Return**
The nvme command status if a response was received (see
:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise.
.. c:function:: int nvme_open (const char *name)
Open an nvme controller or namespace device
**Parameters**
``const char *name``
The basename of the device to open
**Description**
This will look for the handle in /dev/ and validate the name and filetype
match linux conventions.
**Return**
A file descriptor for the device on a successful open, or -1 with
errno set otherwise.
.. c:enum:: nvme_hmac_alg
HMAC algorithm
**Constants**
``NVME_HMAC_ALG_NONE``
No HMAC algorithm
``NVME_HMAC_ALG_SHA2_256``
SHA2-256
``NVME_HMAC_ALG_SHA2_384``
SHA2-384
``NVME_HMAC_ALG_SHA2_512``
SHA2-512
.. c:function:: int nvme_gen_dhchap_key (char *hostnqn, enum nvme_hmac_alg hmac, unsigned int key_len, unsigned char *secret, unsigned char *key)
DH-HMAC-CHAP key generation
**Parameters**
``char *hostnqn``
Host NVMe Qualified Name
``enum nvme_hmac_alg hmac``
HMAC algorithm
``unsigned int key_len``
Output key length
``unsigned char *secret``
Secret to used for digest
``unsigned char *key``
Generated DH-HMAC-CHAP key
**Return**
If key generation was successful the function returns 0 or
-1 with errno set otherwise.

30
doc/rst/log.rst Normal file
View file

@ -0,0 +1,30 @@
.. _log.h:
**log.h**
logging functions
.. c:function:: void nvme_init_logging (nvme_root_t r, int lvl, bool log_pid, bool log_tstamp)
Initialize logging
**Parameters**
``nvme_root_t r``
nvme_root_t context
``int lvl``
Logging level to set
``bool log_pid``
Boolean to enable logging of the PID
``bool log_tstamp``
Boolean to enable logging of the timestamp
**Description**
Sets the default logging variables for the library.

36
doc/rst/meson.build Normal file
View file

@ -0,0 +1,36 @@
want_docs = get_option('docs')
if want_docs != 'false'
want_docs_build = get_option('docs-build')
rstdir = get_option('rstdir')
if want_docs_build
kernel_doc = find_program('../kernel-doc')
conf = configuration_data()
conf.set('SYSCONFDIR', sysconfdir)
if want_docs == 'all' or want_docs == 'rst' or want_docs == 'html'
foreach apif : api_files
afile = files('../../src/nvme/' + apif)
subst = configure_file(
input: afile,
output: '@BASENAME@.subst',
configuration: conf)
rst = custom_target(
apif.underscorify() + '_rst',
input: subst,
output: '@BASENAME@.rst',
capture: true,
command: [kernel_doc,
'-rst',
'@INPUT@'],
install: true,
install_dir: rstdir)
endforeach
endif
else
if want_docs == 'all' or want_docs == 'rst'
install_subdir('rst', install_dir: rstdir)
endif
endif
endif

1590
doc/rst/mi.rst Normal file
View file

File diff suppressed because it is too large Load diff

2108
doc/rst/tree.rst Normal file
View file

File diff suppressed because it is too large Load diff

10936
doc/rst/types.rst Normal file
View file

File diff suppressed because it is too large Load diff

494
doc/rst/util.rst Normal file
View file

@ -0,0 +1,494 @@
.. _util.h:
**util.h**
libnvme utility functions
.. c: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
.. c:function:: __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 :c:type:`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.
.. c:function:: 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 :c:type:`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.
.. c:function:: 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
.. c:function:: 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, :c:type:`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().
.. c:function:: 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.
.. c:function:: 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
.. c:function:: 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
.. c:function:: 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 :c:type:`enum nvme_features_id <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 :c:type:`fid`.
.. c:function:: 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 :c:type:`enum nvme_directive_dtype <nvme_directive_dtype>`
``enum nvme_directive_receive_doper doper``
Directive receive operation, see :c:type:`enum nvme_directive_receive_doper <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 :c:type:`dtype` or :c:type:`doper`.
.. c:function:: 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**.
.. c:function:: 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**.
.. c:function:: 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.
.. c:function:: 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.
.. c:function:: 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.
.. c:macro:: 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
.. c:function:: __u16 nvmf_exat_len (size_t val_len)
Return length rounded up by 4
**Parameters**
``size_t val_len``
Value lenght
**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**
Lenght rounded up by 4
.. c:function:: __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**.
.. c:function:: 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.
.. c: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
.. c:function:: 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"