summaryrefslogtreecommitdiffstats
path: root/doc/rst/linux.rst
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2022-07-26 05:25:28 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2022-07-26 05:34:52 +0000
commit9ecff41dd11e920286f9be670a0ec3a668371d1d (patch)
tree89c73ab6742847ca5f12056e6c0dd4ec6bbe79d0 /doc/rst/linux.rst
parentAdding debian version 1.0-1. (diff)
downloadlibnvme-9ecff41dd11e920286f9be670a0ec3a668371d1d.tar.xz
libnvme-9ecff41dd11e920286f9be670a0ec3a668371d1d.zip
Merging upstream version 1.1~rc0.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/rst/linux.rst')
-rw-r--r--doc/rst/linux.rst342
1 files changed, 342 insertions, 0 deletions
diff --git a/doc/rst/linux.rst b/doc/rst/linux.rst
new file mode 100644
index 0000000..83dbca9
--- /dev/null
+++ b/doc/rst/linux.rst
@@ -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.
+
+