Adding upstream version 1.7.1.upstream/1.7.1

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

1 files changed, 201 insertions, 1 deletions

diff --git a/doc/rst/tree.rst b/doc/rst/tree.rst
index f964ec6..b73ffae 100644
--- a/doc/rst/tree.rst
+++ b/doc/rst/tree.rst
@@ -53,6 +53,22 @@ Sets the managing application string for **r**.
 Returns the managing application string for **r** or NULL if not set.
 
 
+.. c:function:: void nvme_root_release_fds (nvme_root_t r)
+
+   Close all opened file descriptors in the tree
+
+**Parameters**
+
+``nvme_root_t r``
+  :c:type:`nvme_root_t` object
+
+**Description**
+
+Controller and Namespace objects cache the file descriptors
+of opened nvme devices. This API can be used to close and
+clear all cached fds in the tree.
+
+
 .. c:function:: void nvme_free_tree (nvme_root_t r)
 
    Free root object
@@ -469,6 +485,86 @@ will start at **p** instead of the first controller.
 Controller instance
 
 
+.. c:function:: nvme_ctrl_t nvme_ctrl_find (nvme_subsystem_t s, const char *transport, const char *traddr, const char *trsvcid, const char *subsysnqn, const char *host_traddr, const char *host_iface)
+
+   Locate an existing controller
+
+**Parameters**
+
+``nvme_subsystem_t s``
+  :c:type:`nvme_subsystem_t` object
+
+``const char *transport``
+  Transport name
+
+``const char *traddr``
+  Transport address
+
+``const char *trsvcid``
+  Transport service identifier
+
+``const char *subsysnqn``
+  Subsystem NQN
+
+``const char *host_traddr``
+  Host transport address
+
+``const char *host_iface``
+  Host interface name
+
+**Description**
+
+Lookup a controller in **s** based on **transport**, **traddr**, **trsvcid**,
+**subsysnqn**, **host_traddr**, and **host_iface**. **transport** must be specified,
+other fields may be required depending on the transport. Parameters set
+to NULL will be ignored.
+
+Unlike nvme_lookup_ctrl(), this function does not create a new object if
+an existing controller cannot be found.
+
+**Return**
+
+Controller instance on success, NULL otherwise.
+
+
+.. c:function:: bool nvme_ctrl_config_match (struct nvme_ctrl *c, const char *transport, const char *traddr, const char *trsvcid, const char *subsysnqn, const char *host_traddr, const char *host_iface)
+
+   Check if ctrl **c** matches config params
+
+**Parameters**
+
+``struct nvme_ctrl *c``
+  An existing controller instance
+
+``const char *transport``
+  Transport name
+
+``const char *traddr``
+  Transport address
+
+``const char *trsvcid``
+  Transport service identifier
+
+``const char *subsysnqn``
+  Subsystem NQN
+
+``const char *host_traddr``
+  Host transport address
+
+``const char *host_iface``
+  Host interface name
+
+**Description**
+
+Check that controller **c** matches parameters: **transport**, **traddr**,
+**trsvcid**, **subsysnqn**, **host_traddr**, and **host_iface**. Parameters set
+to NULL will be ignored.
+
+**Return**
+
+true if there's a match, false otherwise.
+
+
 .. c:function:: nvme_ctrl_t nvme_create_ctrl (nvme_root_t r, const char *subsysnqn, const char *transport, const char *traddr, const char *host_traddr, const char *host_iface, const char *trsvcid)
 
    Allocate an unconnected NVMe controller
@@ -776,11 +872,30 @@ Next :c:type:`nvme_ns_t` object of an **s** iterator
 ``nvme_ns_t n``
   Namespace instance
 
+**Description**
+
+libnvme will open() the file (if not already opened) and keep
+an internal copy of the file descriptor. Following calls to
+this API retrieve the internal cached copy of the file
+descriptor. The file will remain opened and the fd will
+remain cached until the ns object is deleted or
+nvme_ns_release_fd() is called.
+
 **Return**
 
 File descriptor associated with **n** or -1
 
 
+.. c:function:: void nvme_ns_release_fd (nvme_ns_t n)
+
+   Close fd and clear fd from ns object
+
+**Parameters**
+
+``nvme_ns_t n``
+  Namespace instance
+
+
 .. c:function:: int nvme_ns_get_nsid (nvme_ns_t n)
 
    NSID of a namespace
@@ -1302,11 +1417,30 @@ Parent namespace if present
 ``nvme_ctrl_t c``
   Controller instance
 
+**Description**
+
+libnvme will open() the file (if not already opened) and keep
+an internal copy of the file descriptor. Following calls to
+this API retrieve the internal cached copy of the file
+descriptor. The file will remain opened and the fd will
+remain cached until the controller object is deleted or
+nvme_ctrl_release_fd() is called.
+
 **Return**
 
 File descriptor associated with **c** or -1
 
 
+.. c:function:: void nvme_ctrl_release_fd (nvme_ctrl_t c)
+
+   Close fd and clear fd from controller object
+
+**Parameters**
+
+``nvme_ctrl_t c``
+  Controller instance
+
+
 .. c:function:: const char * nvme_ctrl_get_name (nvme_ctrl_t c)
 
    sysfs name of a controller
@@ -1350,6 +1484,26 @@ NVMe-over-Fabrics address string of **c** or empty string
 of no address is present.
 
 
+.. c:function:: char * nvme_ctrl_get_src_addr (nvme_ctrl_t c, char *src_addr, size_t src_addr_len)
+
+   Extract src_addr from the c->address string
+
+**Parameters**
+
+``nvme_ctrl_t c``
+  Controller instance
+
+``char *src_addr``
+  Where to copy the src_addr. Size must be at least INET6_ADDRSTRLEN.
+
+``size_t src_addr_len``
+  Length of the buffer **src_addr**.
+
+**Return**
+
+Pointer to **src_addr** on success. NULL on failure to extract the src_addr.
+
+
 .. c:function:: const char * nvme_ctrl_get_phy_slot (nvme_ctrl_t c)
 
    PCI physical slot number of a controller
@@ -1395,7 +1549,7 @@ Model string of **c**
 
 .. c:function:: const char * nvme_ctrl_get_state (nvme_ctrl_t c)
 
-   Running state of an controller
+   Running state of a controller
 
 **Parameters**
 
@@ -1962,6 +2116,20 @@ Managing application string or NULL if not set.
 Sets the managing application string for **s**.
 
 
+.. c:function:: const char * nvme_subsystem_get_iopolicy (nvme_subsystem_t s)
+
+   Return the IO policy of subsytem
+
+**Parameters**
+
+``nvme_subsystem_t s``
+  nvme_subsystem_t object
+
+**Return**
+
+IO policy used by current subsystem
+
+
 .. c:function:: int nvme_scan_topology (nvme_root_t r, nvme_scan_filter_t f, void *f_args)
 
    Scan NVMe topology and apply filter
@@ -2015,6 +2183,22 @@ Host NQN of **h**
 Host ID of **h**
 
 
+.. c:function:: void nvme_host_release_fds (struct nvme_host *h)
+
+   Close all opened file descriptors under host
+
+**Parameters**
+
+``struct nvme_host *h``
+  nvme_host_t object
+
+**Description**
+
+Controller and Namespace objects cache the file descriptors
+of opened nvme devices. This API can be used to close and
+clear all cached fds under this host.
+
+
 .. c:function:: void nvme_free_host (nvme_host_t h)
 
    Free nvme_host_t object
@@ -2220,6 +2404,22 @@ String with the contents of **attr** or ``NULL`` in case of an empty value
 nvme_ns_t of the namespace with id **nsid** in subsystem **s**
 
 
+.. c:function:: void nvme_subsystem_release_fds (struct nvme_subsystem *s)
+
+   Close all opened fds under subsystem
+
+**Parameters**
+
+``struct nvme_subsystem *s``
+  nvme_subsystem_t object
+
+**Description**
+
+Controller and Namespace objects cache the file descriptors
+of opened nvme devices. This API can be used to close and
+clear all cached fds under this subsystem.
+
+
 .. c:function:: char * nvme_get_path_attr (nvme_path_t p, const char *attr)
 
    Read path sysfs attribute