linux.h
linux-specific utility functions
-
int
nvme_fw_download_seq(int fd, __u32 size, __u32 xfer, __u32 offset, void *buf) Firmware download sequence
Parameters
int fdFile descriptor of nvme device
__u32 sizeTotal size of the firmware image to transfer
__u32 xferMaximum size to send with each partial transfer
__u32 offsetStarting offset to send with this firmware download
void *bufAddress of buffer containing all or part of the firmware image.
Return
The nvme command status if a response was received (see
enum nvme_status_field) or -1 with errno set otherwise.
-
enum
nvme_telemetry_da Telemetry Log Data Area
Constants
NVME_TELEMETRY_DA_1Data Area 1
NVME_TELEMETRY_DA_2Data Area 2
NVME_TELEMETRY_DA_3Data Area 3
NVME_TELEMETRY_DA_4Data Area 4
-
int
nvme_get_telemetry_max(int fd, enum nvme_telemetry_da *da, size_t *max_data_tx) Get telemetry limits
Parameters
int fdFile descriptor of nvme device
enum nvme_telemetry_da *daOn success return max supported data area
size_t *max_data_txOn success set to max transfer chunk supported by the controller
Return
The nvme command status if a response was received (see
enum nvme_status_field) or -1 with errno set otherwise.
-
int
nvme_get_telemetry_log(int fd, bool create, bool ctrl, bool rae, size_t max_data_tx, enum nvme_telemetry_da da, struct nvme_telemetry_log **log, size_t *size) Get specified telemetry log
Parameters
int fdFile descriptor of nvme device
bool createGenerate new host initated telemetry capture
bool ctrlGet controller Initiated log
bool raeRetain asynchronous events
size_t max_data_txSet the max data transfer size to be used retrieving telemetry.
enum nvme_telemetry_da daLog page data area, valid values:
enum nvme_telemetry_da.struct nvme_telemetry_log **logOn success, set to the value of the allocated and retrieved log.
size_t *sizePtr 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
enum nvme_status_field) or -1 with errno set otherwise.
-
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 fdFile descriptor of nvme device
bool raeRetain asynchronous events
struct nvme_telemetry_log **logOn success, set to the value of the allocated and retrieved log.
enum nvme_telemetry_da daLog page data area, valid values:
enum nvme_telemetry_dasize_t *sizePtr 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
enum nvme_status_field) or -1 with errno set otherwise.
-
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 fdFile descriptor of nvme device
struct nvme_telemetry_log **logOn success, set to the value of the allocated and retrieved log.
enum nvme_telemetry_da daLog page data area, valid values:
enum nvme_telemetry_dasize_t *sizePtr 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
enum nvme_status_field) or -1 with errno set otherwise.
-
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 fdFile descriptor of nvme device
struct nvme_telemetry_log **logOn success, set to the value of the allocated and retrieved log.
enum nvme_telemetry_da daLog page data area, valid values:
enum nvme_telemetry_dasize_t *sizePtr 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
enum nvme_status_field) or -1 with errno set otherwise.
-
int
nvme_get_ana_log_len(int fd, size_t *analen) Retrieve size of the current ANA log
Parameters
int fdFile descriptor of nvme device
size_t *analenPointer to where the length will be set on success
Return
The nvme command status if a response was received (see
enum nvme_status_field) or -1 with errno set otherwise.
-
int
nvme_get_logical_block_size(int fd, __u32 nsid, int *blksize) Retrieve block size
Parameters
int fdFile descriptor of nvme device
__u32 nsidNamespace id
int *blksizePointer to where the block size will be set on success
Return
The nvme command status if a response was received (see
enum nvme_status_field) or -1 with errno set otherwise.
-
int
nvme_get_lba_status_log(int fd, bool rae, struct nvme_lba_status_log **log) Retrieve the LBA Status log page
Parameters
int fdFile descriptor of the nvme device
bool raeRetain asynchronous events
struct nvme_lba_status_log **logOn success, set to the value of the allocated and retrieved log.
Return
The nvme command status if a response was received (see
enum nvme_status_field) or -1 with errno set otherwise.
-
int
nvme_namespace_attach_ctrls(int fd, __u32 nsid, __u16 num_ctrls, __u16 *ctrlist) Attach namespace to controller(s)
Parameters
int fdFile descriptor of nvme device
__u32 nsidNamespace ID to attach
__u16 num_ctrlsNumber of controllers in ctrlist
__u16 *ctrlistList of controller IDs to perform the attach action
Return
The nvme command status if a response was received (see
enum nvme_status_field) or -1 with errno set otherwise.
-
int
nvme_namespace_detach_ctrls(int fd, __u32 nsid, __u16 num_ctrls, __u16 *ctrlist) Detach namespace from controller(s)
Parameters
int fdFile descriptor of nvme device
__u32 nsidNamespace ID to detach
__u16 num_ctrlsNumber of controllers in ctrlist
__u16 *ctrlistList of controller IDs to perform the detach action
Return
The nvme command status if a response was received (see
enum nvme_status_field) or -1 with errno set otherwise.
-
int
nvme_open(const char *name) Open an nvme controller or namespace device
Parameters
const char *nameThe 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.
-
enum
nvme_hmac_alg HMAC algorithm
Constants
NVME_HMAC_ALG_NONENo HMAC algorithm
NVME_HMAC_ALG_SHA2_256SHA2-256
NVME_HMAC_ALG_SHA2_384SHA2-384
NVME_HMAC_ALG_SHA2_512SHA2-512
-
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 *hostnqnHost NVMe Qualified Name
enum nvme_hmac_alg hmacHMAC algorithm
unsigned int key_lenOutput key length
unsigned char *secretSecret to used for digest
unsigned char *keyGenerated DH-HMAC-CHAP key
Return
If key generation was successful the function returns 0 or -1 with errno set otherwise.
-
long
nvme_lookup_keyring(const char *keyring) Lookup keyring serial number
Parameters
const char *keyringKeyring name
Description
Looks up the serial number of the keyring keyring.
Return
The key serial number of the keyring or 0 with errno set otherwise.
-
char *
nvme_describe_key_serial(long key_id) Return key description
Parameters
long key_idKey serial number
Description
Fetches the description of the key or keyring identified by the serial number key_id.
Return
The description of key_id or NULL on failure. The returned string needs to be freed by the caller.
-
long
nvme_lookup_key(const char *type, const char *identity) Lookup key serial number
Parameters
const char *typeKey type
const char *identityKey description
Description
Looks up the serial number of the key identity
with type type in the current session keyring.
Return
The key serial number of the key or 0 with errno set otherwise.
-
int
nvme_set_keyring(long keyring_id) Link keyring for lookup
Parameters
long keyring_idKeyring id
Description
Links keyring_id into the session keyring such that its keys are available for further key lookups.
Return
0 on success, a negative number on error with errno set.
-
long
nvme_insert_tls_key(const char *keyring, const char *key_type, const char *hostnqn, const char *subsysnqn, int hmac, unsigned char *configured_key, int key_len) Derive and insert TLS key
Parameters
const char *keyringKeyring to use
const char *key_typeType of the resulting key
const char *hostnqnHost NVMe Qualified Name
const char *subsysnqnSubsystem NVMe Qualified Name
int hmacHMAC algorithm
unsigned char *configured_keyConfigured key data to derive the key from
int key_lenLength of configured_key
Description
Derives a ‘retained’ TLS key as specified in NVMe TCP 1.0a and stores it as type key_type in the keyring specified by keyring.
Return
The key serial number if the key could be inserted into the keyring or 0 with errno otherwise.