Merging upstream version 1.1~rc0.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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.
+
+