Adding upstream version 1.1~rc0.upstream/1.1_rc0

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

1 files changed, 1590 insertions, 0 deletions

diff --git a/doc/rst/mi.rst b/doc/rst/mi.rst
new file mode 100644
index 0000000..b9f2f84
--- /dev/null
+++ b/doc/rst/mi.rst
@@ -0,0 +1,1590 @@
+.. _mi.h - NVMe Management Interface library (libnvme-mi) definitions.:
+
+**mi.h - NVMe Management Interface library (libnvme-mi) definitions.**
+
+
+These provide an abstraction for the MI messaging between controllers
+and a host, typically over an MCTP-over-i2c link to a NVMe device, used
+as part of the out-of-band management of a system.
+
+We have a few data structures define here to reflect the topology
+of a MI connection with an NVMe subsystem:
+
+ - :c:type:`nvme_mi_ep_t`: an MI endpoint - our mechanism of communication with a
+   NVMe subsystem. For MCTP, an endpoint will be the component that
+   holds the MCTP address (EID), and receives our request message.
+
+   endpoints are defined in the NVMe-MI spec, and are specific to the MI
+   interface.
+
+   Each endpoint will provide access to one or more of:
+
+ - :c:type:`nvme_mi_ctrl_t`: a NVMe controller, as defined by the NVMe base spec.
+   The controllers are responsible for processing any NVMe standard
+   commands (eg, the Admin command set). An endpoint (:c:type:`nvme_mi_ep_t`)
+   may provide access to multiple controllers - so each of the controller-
+   type commands will require a :c:type:`nvme_mi_ctrl_t` to be specified, rather than
+   an endpoint
+
+A couple of conventions with the libnvme-mi API:
+
+ - All types and functions have the nvme_mi prefix, to distinguish from
+   the libnvme core.
+
+ - We currently support either MI commands and Admin commands. The
+   former adds a _mi prefix, the latter an _admin prefix. [This does
+   result in the MI functions having a double _mi, like
+   :c:type:`nvme_mi_mi_subsystem_health_status_poll`, which is apparently amusing
+   for our German-speaking readers]
+
+For return values: unless specified in the per-function documentation,
+all functions:
+
+ - return 0 on success
+
+ - return -1, with errno set, for errors communicating with the MI device,
+   either in request or response data
+
+ - return >1 on MI status errors. This value is the 8-bit MI status
+   value, represented by :c:type:`enum nvme_mi_resp_status <nvme_mi_resp_status>`. Note that the
+   status values may be vendor-defined above 0xe0.
+
+For the second case, we have a few conventions for errno values:
+
+ - EPROTO: response data violated the MI protocol, and libnvme cannot
+   validly interpret the response
+
+ - EIO: Other I/O error communicating with device (eg., valid but
+   unexpected response data)
+
+ - EINVAL: invalid input arguments for a command
+
+In line with the core NVMe API, the Admin command functions take an
+`_args` structure to provide the command-specific parameters. However,
+for the MI interface, the fd and timeout members of these _args structs
+are ignored.
+
+References to the specifications here will either to be the NVM Express
+Management Interface ("NVMe-MI") or the NVM Express Base specification
+("NVMe"). At the time of writing, the versions we're referencing here
+are:
+ - NVMe-MI 1.2b
+ - NVMe 2.0b
+with a couple of accommodations for older spec types, particularly NVMe-MI
+1.1, where possible.
+
+.. c:macro:: NVME_MI_MSGTYPE_NVME
+
+``NVME_MI_MSGTYPE_NVME ()``
+
+   MCTP message type for NVMe-MI messages.
+
+**Parameters**
+
+**Description**
+
+
+This is defined by MCTP, but is referenced as part of the NVMe-MI message
+spec. This is the MCTP NVMe message type (0x4), with the message-integrity
+bit (0x80) set.
+
+
+
+
+.. c:enum:: nvme_mi_message_type
+
+   NVMe-MI message type field.
+
+**Constants**
+
+``NVME_MI_MT_CONTROL``
+  NVME-MI Control Primitive
+
+``NVME_MI_MT_MI``
+  NVMe-MI command
+
+``NVME_MI_MT_ADMIN``
+  NVMe Admin command
+
+``NVME_MI_MT_PCIE``
+  PCIe command
+
+**Description**
+
+Used as byte 1 of both request and response messages (NMIMT bits of NMP
+byte). Not to be confused with the MCTP message type in byte 0.
+
+
+
+
+.. c:enum:: nvme_mi_ror
+
+   Request or response field.
+
+**Constants**
+
+``NVME_MI_ROR_REQ``
+  request message
+
+``NVME_MI_ROR_RSP``
+  response message
+
+
+
+
+.. c:enum:: nvme_mi_resp_status
+
+   values for the response status field
+
+**Constants**
+
+``NVME_MI_RESP_SUCCESS``
+  success
+
+``NVME_MI_RESP_MPR``
+  More Processing Required
+
+``NVME_MI_RESP_INTERNAL_ERR``
+  Internal Error
+
+``NVME_MI_RESP_INVALID_OPCODE``
+  Invalid command opcode
+
+``NVME_MI_RESP_INVALID_PARAM``
+  Invalid command parameter
+
+``NVME_MI_RESP_INVALID_CMD_SIZE``
+  Invalid command size
+
+``NVME_MI_RESP_INVALID_INPUT_SIZE``
+  Invalid command input data size
+
+``NVME_MI_RESP_ACCESS_DENIED``
+  Access Denied
+
+``NVME_MI_RESP_VPD_UPDATES_EXCEEDED``
+  More VPD updates than allowed
+
+``NVME_MI_RESP_PCIE_INACCESSIBLE``
+  PCIe functionality currently unavailable
+
+``NVME_MI_RESP_MEB_SANITIZED``
+  MEB has been cleared due to sanitize
+
+``NVME_MI_RESP_ENC_SERV_FAILURE``
+  Enclosure services process failed
+
+``NVME_MI_RESP_ENC_SERV_XFER_FAILURE``
+  Transfer with enclosure services failed
+
+``NVME_MI_RESP_ENC_FAILURE``
+  Unreoverable enclosure failure
+
+``NVME_MI_RESP_ENC_XFER_REFUSED``
+  Enclosure services transfer refused
+
+``NVME_MI_RESP_ENC_FUNC_UNSUP``
+  Unsupported enclosure services function
+
+``NVME_MI_RESP_ENC_SERV_UNAVAIL``
+  Enclosure services unavailable
+
+``NVME_MI_RESP_ENC_DEGRADED``
+  Noncritical failure detected by enc. services
+
+``NVME_MI_RESP_SANITIZE_IN_PROGRESS``
+  Command prohibited during sanitize
+
+
+
+
+.. c:struct:: nvme_mi_msg_hdr
+
+   General MI message header.
+
+**Definition**
+
+::
+
+  struct nvme_mi_msg_hdr {
+    __u8 type;
+    __u8 nmp;
+    __u8 meb;
+    __u8 rsvd0;
+  };
+
+**Members**
+
+``type``
+  MCTP message type, will always be NVME_MI_MSGTYPE_NVME
+
+``nmp``
+  NVMe-MI message parameters (including MI message type)
+
+``meb``
+  Management Endpoint Buffer flag; unused for libnvme-mi implementation
+
+``rsvd0``
+  currently reserved
+
+
+**Description**
+
+Wire format shared by both request and response messages, per NVMe-MI
+section 3.1. This is used for all message types, MI and Admin.
+
+
+
+
+.. c:struct:: nvme_mi_msg_resp
+
+   Generic response type.
+
+**Definition**
+
+::
+
+  struct nvme_mi_msg_resp {
+    struct nvme_mi_msg_hdr hdr;
+    __u8 status;
+    __u8 rsvd0[3];
+  };
+
+**Members**
+
+``hdr``
+  the general request/response message header
+
+``status``
+  response status value (see :c:type:`enum nvme_mi_resp_status <nvme_mi_resp_status>`)
+
+``rsvd0``
+  reserved data, may be defined by specific response
+
+
+**Description**
+
+Every response will start with one of these; command-specific responses
+will define parts of the reserved data, and may add further fields.
+
+
+
+
+.. c:enum:: nvme_mi_mi_opcode
+
+   Operation code for supported NVMe-MI commands.
+
+**Constants**
+
+``nvme_mi_mi_opcode_mi_data_read``
+  Read NVMe-MI Data Structure
+
+``nvme_mi_mi_opcode_subsys_health_status_poll``
+  Subsystem Health Status Poll
+
+``nvme_mi_mi_opcode_configuration_set``
+  MI Configuration Set
+
+``nvme_mi_mi_opcode_configuration_get``
+  MI Configuration Get
+
+
+
+
+.. c:struct:: nvme_mi_mi_req_hdr
+
+   MI request message header.
+
+**Definition**
+
+::
+
+  struct nvme_mi_mi_req_hdr {
+    struct nvme_mi_msg_hdr hdr;
+    __u8 opcode;
+    __u8 rsvd0[3];
+    __le32 cdw0, cdw1;
+  };
+
+**Members**
+
+``hdr``
+  generic MI message header
+
+``opcode``
+  opcode (OPC) for the specific MI command
+
+``rsvd0``
+  reserved bytes
+
+``cdw0``
+  Management Request Doubleword 0 - command specific usage
+
+``cdw1``
+  Management Request Doubleword 1 - command specific usage
+
+
+**Description**
+
+Wire format for MI request message headers, defined in section 5 of NVMe-MI.
+
+
+
+
+.. c:struct:: nvme_mi_mi_resp_hdr
+
+   MI response message header.
+
+**Definition**
+
+::
+
+  struct nvme_mi_mi_resp_hdr {
+    struct nvme_mi_msg_hdr hdr;
+    __u8 status;
+    __u8 nmresp[3];
+  };
+
+**Members**
+
+``hdr``
+  generic MI message header
+
+``status``
+  generic response status from command; non-zero on failure.
+
+``nmresp``
+  NVMe Management Response: command-type-specific response data
+
+
+**Description**
+
+Wire format for MI response message header, defined in section 5 of NVMe-MI.
+
+
+
+
+.. c:enum:: nvme_mi_dtyp
+
+   Data Structure Type field.
+
+**Constants**
+
+``nvme_mi_dtyp_subsys_info``
+  NVM Subsystem Information
+
+``nvme_mi_dtyp_port_info``
+  Port information
+
+``nvme_mi_dtyp_ctrl_list``
+  Controller List
+
+``nvme_mi_dtyp_ctrl_info``
+  Controller Information
+
+``nvme_mi_dtyp_opt_cmd_support``
+  Optionally Supported Command List
+
+``nvme_mi_dtyp_meb_support``
+  Management Endpoint Buffer Command Support List
+
+**Description**
+
+Data Structure Type field for Read NVMe-MI Data Structure command, used to
+indicate the particular structure to query from the endpoint.
+
+
+
+
+.. c:enum:: nvme_mi_config_id
+
+   NVMe-MI Configuration identifier.
+
+**Constants**
+
+``NVME_MI_CONFIG_SMBUS_FREQ``
+  Current SMBus/I2C frequency
+
+``NVME_MI_CONFIG_HEALTH_STATUS_CHANGE``
+  Health Status change - used to clear
+  health status bits in CCS bits of
+  status poll. Only for Set ops.
+
+``NVME_MI_CONFIG_MCTP_MTU``
+  MCTP maximum transmission unit size of port
+  specified in dw 0
+
+**Description**
+
+Configuration parameters for the MI Get/Set Configuration commands.
+
+See :c:type:`nvme_mi_mi_config_get`() and :c:type:`nvme_mi_config_set`().
+
+
+
+
+.. c:enum:: nvme_mi_config_smbus_freq
+
+   SMBus/I2C frequency values
+
+**Constants**
+
+``NVME_MI_CONFIG_SMBUS_FREQ_100kHz``
+  100kHz
+
+``NVME_MI_CONFIG_SMBUS_FREQ_400kHz``
+  400kHz
+
+``NVME_MI_CONFIG_SMBUS_FREQ_1MHz``
+  1MHz
+
+**Description**
+
+Values used in the SMBus Frequency device configuration. See
+:c:type:`nvme_mi_mi_config_get_smbus_freq`() and :c:type:`nvme_mi_mi_config_set_smbus_freq`().
+
+
+
+
+.. c:struct:: nvme_mi_admin_req_hdr
+
+   Admin command request header.
+
+**Definition**
+
+::
+
+  struct nvme_mi_admin_req_hdr {
+    struct nvme_mi_msg_hdr hdr;
+    __u8 opcode;
+    __u8 flags;
+    __le16 ctrl_id;
+    __le32 cdw1, cdw2, cdw3, cdw4, cdw5;
+    __le32 doff;
+    __le32 dlen;
+    __le32 rsvd0, rsvd1;
+    __le32 cdw10, cdw11, cdw12, cdw13, cdw14, cdw15;
+  };
+
+**Members**
+
+``hdr``
+  Generic MI message header
+
+``opcode``
+  Admin command opcode (using enum nvme_admin_opcode)
+
+``flags``
+  Command Flags, indicating dlen and doff validity; Only defined in
+  NVMe-MI version 1.1, no fields defined in 1.2 (where the dlen/doff
+  are always considered valid).
+
+``ctrl_id``
+  Controller ID target of command
+
+``cdw1``
+  Submission Queue Entry doubleword 1
+
+``cdw2``
+  Submission Queue Entry doubleword 2
+
+``cdw3``
+  Submission Queue Entry doubleword 3
+
+``cdw4``
+  Submission Queue Entry doubleword 4
+
+``cdw5``
+  Submission Queue Entry doubleword 5
+
+``doff``
+  Offset of data to return from command
+
+``dlen``
+  Length of sent/returned data
+
+``rsvd0``
+  Reserved
+
+``rsvd1``
+  Reserved
+
+``cdw10``
+  Submission Queue Entry doubleword 10
+
+``cdw11``
+  Submission Queue Entry doubleword 11
+
+``cdw12``
+  Submission Queue Entry doubleword 12
+
+``cdw13``
+  Submission Queue Entry doubleword 13
+
+``cdw14``
+  Submission Queue Entry doubleword 14
+
+``cdw15``
+  Submission Queue Entry doubleword 15
+
+
+**Description**
+
+Wire format for Admin command message headers, defined in section 6 of
+NVMe-MI.
+
+
+
+
+.. c:struct:: nvme_mi_admin_resp_hdr
+
+   Admin command response header.
+
+**Definition**
+
+::
+
+  struct nvme_mi_admin_resp_hdr {
+    struct nvme_mi_msg_hdr hdr;
+    __u8 status;
+    __u8 rsvd0[3];
+    __le32 cdw0, cdw1, cdw3;
+  };
+
+**Members**
+
+``hdr``
+  Generic MI message header
+
+``status``
+  Generic response code, non-zero on failure
+
+``rsvd0``
+  Reserved
+
+``cdw0``
+  Completion Queue Entry doubleword 0
+
+``cdw1``
+  Completion Queue Entry doubleword 1
+
+``cdw3``
+  Completion Queue Entry doubleword 3
+
+
+**Description**
+
+This is the generic response format with the three doublewords of completion
+queue data, plus optional response data.
+
+
+.. c:function:: nvme_root_t nvme_mi_create_root (FILE *fp, int log_level)
+
+   Create top-level MI (root) handle.
+
+**Parameters**
+
+``FILE *fp``
+  File descriptor for logging messages
+
+``int log_level``
+  Logging level to use
+
+**Description**
+
+Create the top-level (library) handle for creating subsequent endpoint
+objects. Similar to nvme_create_root(), but we provide this to allow linking
+without the core libnvme.
+
+See :c:type:`nvme_create_root`.
+
+**Return**
+
+new root object, or NULL on failure.
+
+
+.. c:function:: void nvme_mi_free_root (nvme_root_t root)
+
+   Free root object.
+
+**Parameters**
+
+``nvme_root_t root``
+  root to free
+
+
+
+
+.. c:type:: nvme_mi_ep_t
+
+   MI Endpoint object.
+
+**Description**
+
+
+Represents our communication endpoint on the remote MI-capable device.
+To be used for direct MI commands for the endpoint (through the
+nvme_mi_mi_* functions(), or to communicate with individual controllers
+(see :c:type:`nvme_mi_init_ctrl`).
+
+Endpoints are created through a transport-specific constructor; currently
+only MCTP-connected endpoints are supported, through :c:type:`nvme_mi_open_mctp`.
+Subsequent operations on the endpoint (and related controllers) are
+transport-independent.
+
+
+.. c:function:: nvme_mi_ep_t nvme_mi_first_endpoint (nvme_root_t m)
+
+   Start endpoint iterator
+
+**Parameters**
+
+``nvme_root_t m``
+  :c:type:`nvme_root_t` object
+
+**Return**
+
+first MI endpoint object under this root, or NULL if no endpoints
+        are present.
+
+**Description**
+
+See: :c:type:`nvme_mi_next_endpoint`, :c:type:`nvme_mi_for_each_endpoint`
+
+
+.. c:function:: nvme_mi_ep_t nvme_mi_next_endpoint (nvme_root_t m, nvme_mi_ep_t e)
+
+   Continue endpoint iterator
+
+**Parameters**
+
+``nvme_root_t m``
+  :c:type:`nvme_root_t` object
+
+``nvme_mi_ep_t e``
+  :c:type:`nvme_mi_ep_t` current position of iterator
+
+**Return**
+
+next endpoint MI endpoint object after **e** under this root, or NULL
+        if no further endpoints are present.
+
+**Description**
+
+See: :c:type:`nvme_mi_first_endpoint`, :c:type:`nvme_mi_for_each_endpoint`
+
+
+.. c:macro:: nvme_mi_for_each_endpoint
+
+``nvme_mi_for_each_endpoint (m, e)``
+
+   Iterator for NVMe-MI endpoints.
+
+**Parameters**
+
+``m``
+  :c:type:`nvme_root_t` containing endpoints
+
+``e``
+  :c:type:`nvme_mi_ep_t` object, set on each iteration
+
+
+.. c:macro:: nvme_mi_for_each_endpoint_safe
+
+``nvme_mi_for_each_endpoint_safe (m, e, _e)``
+
+   Iterator for NVMe-MI endpoints, allowing deletion during traversal
+
+**Parameters**
+
+``m``
+  :c:type:`nvme_root_t` containing endpoints
+
+``e``
+  :c:type:`nvme_mi_ep_t` object, set on each iteration
+
+``_e``
+  :c:type:`nvme_mi_ep_t` object used as temporary storage
+
+
+
+
+.. c:type:: nvme_mi_ctrl_t
+
+   NVMe-MI Controller object.
+
+**Description**
+
+
+Provides NVMe command functionality, through the MI interface.
+
+
+.. c:function:: nvme_mi_ctrl_t nvme_mi_first_ctrl (nvme_mi_ep_t ep)
+
+   Start controller iterator
+
+**Parameters**
+
+``nvme_mi_ep_t ep``
+  :c:type:`nvme_mi_ep_t` object
+
+**Return**
+
+first MI controller object under this root, or NULL if no controllers
+        are present.
+
+**Description**
+
+See: :c:type:`nvme_mi_next_ctrl`, :c:type:`nvme_mi_for_each_ctrl`
+
+
+.. c:function:: nvme_mi_ctrl_t nvme_mi_next_ctrl (nvme_mi_ep_t ep, nvme_mi_ctrl_t c)
+
+   Continue ctrl iterator
+
+**Parameters**
+
+``nvme_mi_ep_t ep``
+  :c:type:`nvme_mi_ep_t` object
+
+``nvme_mi_ctrl_t c``
+  :c:type:`nvme_mi_ctrl_t` current position of iterator
+
+**Return**
+
+next MI controller object after **c** under this endpoint, or NULL
+        if no further controllers are present.
+
+**Description**
+
+See: :c:type:`nvme_mi_first_ctrl`, :c:type:`nvme_mi_for_each_ctrl`
+
+
+.. c:macro:: nvme_mi_for_each_ctrl
+
+``nvme_mi_for_each_ctrl (ep, c)``
+
+   Iterator for NVMe-MI controllers.
+
+**Parameters**
+
+``ep``
+  :c:type:`nvme_mi_ep_t` containing endpoints
+
+``c``
+  :c:type:`nvme_mi_ctrl_t` object, set on each iteration
+
+**Description**
+
+Allows iteration of the list of controllers behind an endpoint. Unless the
+controllers have already been created explicitly, you'll probably want to
+call :c:type:`nvme_mi_scan_ep`() to scan for the controllers first.
+
+See: :c:type:`nvme_mi_scan_ep`()
+
+
+.. c:macro:: nvme_mi_for_each_ctrl_safe
+
+``nvme_mi_for_each_ctrl_safe (ep, c, _c)``
+
+   Iterator for NVMe-MI controllers, allowing deletion during traversal
+
+**Parameters**
+
+``ep``
+  :c:type:`nvme_mi_ep_t` containing controllers
+
+``c``
+  :c:type:`nvme_mi_ctrl_t` object, set on each iteration
+
+``_c``
+  :c:type:`nvme_mi_ctrl_t` object used as temporary storage
+
+**Description**
+
+Allows iteration of the list of controllers behind an endpoint, safe against
+deletion during iteration. Unless the controllers have already been created
+explicitly (or you're just iterating to destroy controllers) you'll probably
+want to call :c:type:`nvme_mi_scan_ep`() to scan for the controllers first.
+
+See: :c:type:`nvme_mi_scan_ep`()
+
+
+.. c:function:: nvme_mi_ep_t nvme_mi_open_mctp (nvme_root_t root, unsigned int netid, uint8_t eid)
+
+   Create an endpoint using a MCTP connection.
+
+**Parameters**
+
+``nvme_root_t root``
+  root object to create under
+
+``unsigned int netid``
+  MCTP network ID on this system
+
+``uint8_t eid``
+  MCTP endpoint ID
+
+**Description**
+
+Transport-specific endpoint initialization for MI-connected endpoints. Once
+an endpoint is created, the rest of the API is transport-independent.
+
+See :c:type:`nvme_mi_close`
+
+**Return**
+
+New endpoint object for **netid** & **eid**, or NULL on failure.
+
+
+.. c:function:: void nvme_mi_close (nvme_mi_ep_t ep)
+
+   Close an endpoint connection and release resources, including controller objects.
+
+**Parameters**
+
+``nvme_mi_ep_t ep``
+  Endpoint object to close
+
+
+.. c:function:: nvme_root_t nvme_mi_scan_mctp (void)
+
+   look for MCTP-connected NVMe-MI endpoints.
+
+**Parameters**
+
+``void``
+  no arguments
+
+**Description**
+
+This function queries the system MCTP daemon ("mctpd") over
+D-Bus, to find MCTP endpoints that report support for NVMe-MI over MCTP.
+
+This requires libvnme-mi to be compiled with D-Bus support; if not, this
+will return NULL.
+
+**Return**
+
+A **nvme_root_t** populated with a set of MCTP-connected endpoints,
+        or NULL on failure
+
+
+.. c:function:: int nvme_mi_scan_ep (nvme_mi_ep_t ep, bool force_rescan)
+
+   query an endpoint for its NVMe controllers.
+
+**Parameters**
+
+``nvme_mi_ep_t ep``
+  Endpoint to scan
+
+``bool force_rescan``
+  close existing controllers and rescan
+
+**Description**
+
+This function queries an MI endpoint for the controllers available, by
+performing an MI Read MI Data Structure command (requesting the
+controller list). The controllers are stored in the endpoint's internal
+list, and can be iterated with nvme_mi_for_each_ctrl.
+
+This will only scan the endpoint once, unless **force_rescan** is set. If
+so, all existing controller objects will be freed - the caller must not
+hold a reference to those across this call.
+
+See: :c:type:`nvme_mi_for_each_ctrl`
+
+**Return**
+
+0 on success, non-zero on failure
+
+
+.. c:function:: nvme_mi_ctrl_t nvme_mi_init_ctrl (nvme_mi_ep_t ep, __u16 ctrl_id)
+
+   initialise a NVMe controller.
+
+**Parameters**
+
+``nvme_mi_ep_t ep``
+  Endpoint to create under
+
+``__u16 ctrl_id``
+  ID of controller to initialize.
+
+**Description**
+
+Create a connection to a controller behind the endpoint specified in **ep**.
+Controller IDs may be queried from the endpoint through
+:c:type:`nvme_mi_mi_read_mi_data_ctrl_list`.
+
+See :c:type:`nvme_mi_close_ctrl`
+
+**Return**
+
+New controller object, or NULL on failure.
+
+
+.. c:function:: void nvme_mi_close_ctrl (nvme_mi_ctrl_t ctrl)
+
+   free a controller
+
+**Parameters**
+
+``nvme_mi_ctrl_t ctrl``
+  controller to free
+
+
+.. c:function:: char * nvme_mi_endpoint_desc (nvme_mi_ep_t ep)
+
+   Get a string describing a MI endpoint.
+
+**Parameters**
+
+``nvme_mi_ep_t ep``
+  endpoint to describe
+
+**Description**
+
+Generates a human-readable string describing the endpoint, with possibly
+transport-specific data. The string is allocated during the call, and the
+caller is responsible for free()-ing the string.
+
+**Return**
+
+a newly-allocated string containing the endpoint description, or
+        NULL on failure.
+
+
+.. c:function:: int nvme_mi_mi_read_mi_data_subsys (nvme_mi_ep_t ep, struct nvme_mi_read_nvm_ss_info *s)
+
+   Perform a Read MI Data Structure command, retrieving subsystem data.
+
+**Parameters**
+
+``nvme_mi_ep_t ep``
+  endpoint for MI communication
+
+``struct nvme_mi_read_nvm_ss_info *s``
+  subsystem information to populate
+
+**Description**
+
+Retrieves the Subsystem information - number of external ports and
+NVMe version information. See :c:type:`struct nvme_mi_read_nvm_ss_info <nvme_mi_read_nvm_ss_info>`.
+
+**Return**
+
+0 on success, non-zero on failure.
+
+
+.. c:function:: int nvme_mi_mi_read_mi_data_port (nvme_mi_ep_t ep, __u8 portid, struct nvme_mi_read_port_info *p)
+
+   Perform a Read MI Data Structure command, retrieving port data.
+
+**Parameters**
+
+``nvme_mi_ep_t ep``
+  endpoint for MI communication
+
+``__u8 portid``
+  id of port data to retrieve
+
+``struct nvme_mi_read_port_info *p``
+  port information to populate
+
+**Description**
+
+Retrieves the Port information, for the specified port ID. The subsystem
+data (from :c:type:`nvme_mi_mi_read_mi_data_subsys`) nmp field contains the allowed
+range of port IDs.
+
+See :c:type:`struct nvme_mi_read_port_info <nvme_mi_read_port_info>`.
+
+**Return**
+
+0 on success, non-zero on failure.
+
+
+.. c:function:: int nvme_mi_mi_read_mi_data_ctrl_list (nvme_mi_ep_t ep, __u8 start_ctrlid, struct nvme_ctrl_list *list)
+
+   Perform a Read MI Data Structure command, retrieving the list of attached controllers.
+
+**Parameters**
+
+``nvme_mi_ep_t ep``
+  endpoint for MI communication
+
+``__u8 start_ctrlid``
+  starting controller ID
+
+``struct nvme_ctrl_list *list``
+  controller list to populate
+
+**Description**
+
+Retrieves the list of attached controllers, with IDs greater than or
+equal to **start_ctrlid**.
+
+See :c:type:`struct nvme_ctrl_list <nvme_ctrl_list>`.
+
+**Return**
+
+0 on success, non-zero on failure.
+
+
+.. c:function:: int nvme_mi_mi_read_mi_data_ctrl (nvme_mi_ep_t ep, __u16 ctrl_id, struct nvme_mi_read_ctrl_info *ctrl)
+
+   Perform a Read MI Data Structure command, retrieving controller information
+
+**Parameters**
+
+``nvme_mi_ep_t ep``
+  endpoint for MI communication
+
+``__u16 ctrl_id``
+  ID of controller to query
+
+``struct nvme_mi_read_ctrl_info *ctrl``
+  controller data to populate
+
+**Description**
+
+Retrieves the Controller Information Data Structure for the attached
+controller with ID **ctrlid**.
+
+See :c:type:`struct nvme_mi_read_ctrl_info <nvme_mi_read_ctrl_info>`.
+
+**Return**
+
+0 on success, non-zero on failure.
+
+
+.. c:function:: int nvme_mi_mi_subsystem_health_status_poll (nvme_mi_ep_t ep, bool clear, struct nvme_mi_nvm_ss_health_status *nshds)
+
+   Read the Subsystem Health Data Structure from the NVM subsystem
+
+**Parameters**
+
+``nvme_mi_ep_t ep``
+  endpoint for MI communication
+
+``bool clear``
+  flag to clear the Composite Controller Status state
+
+``struct nvme_mi_nvm_ss_health_status *nshds``
+  subsystem health status data to populate
+
+**Description**
+
+Retrieves the Subsystem Health Data Structure into **nshds**. If **clear** is
+set, requests that the Composite Controller Status bits are cleared after
+the read. See NVMe-MI section 5.6 for details on the CCS bits.
+
+See :c:type:`struct nvme_mi_nvm_ss_health_status <nvme_mi_nvm_ss_health_status>`.
+
+**Return**
+
+0 on success, non-zero on failure.
+
+
+.. c:function:: int nvme_mi_mi_config_get (nvme_mi_ep_t ep, __u32 dw0, __u32 dw1, __u32 *nmresp)
+
+   query a configuration parameter
+
+**Parameters**
+
+``nvme_mi_ep_t ep``
+  endpoint for MI communication
+
+``__u32 dw0``
+  management doubleword 0, containing configuration identifier, plus
+  config-specific fields
+
+``__u32 dw1``
+  management doubleword 0, config-specific.
+
+``__u32 *nmresp``
+  set to queried configuration data in NMRESP field of response.
+
+**Description**
+
+Performs a MI Configuration Get command, with the configuration identifier
+as the LSB of **dw0**. Other **dw0** and **dw1** data is configuration-identifier
+specific.
+
+On a successful Configuration Get, the **nmresp** pointer will be populated with
+the bytes from the 3-byte NMRESP field, converted to native endian.
+
+See :c:type:`enum nvme_mi_config_id <nvme_mi_config_id>` for identifiers.
+
+**Return**
+
+0 on success, non-zero on failure.
+
+
+.. c:function:: int nvme_mi_mi_config_set (nvme_mi_ep_t ep, __u32 dw0, __u32 dw1)
+
+   set a configuration parameter
+
+**Parameters**
+
+``nvme_mi_ep_t ep``
+  endpoint for MI communication
+
+``__u32 dw0``
+  management doubleword 0, containing configuration identifier, plus
+  config-specific fields
+
+``__u32 dw1``
+  management doubleword 0, config-specific.
+
+**Description**
+
+Performs a MI Configuration Set command, with the command as the LSB of
+**dw0**. Other **dw0** and **dw1** data is configuration-identifier specific.
+
+See :c:type:`enum nvme_mi_config_id <nvme_mi_config_id>` for identifiers.
+
+**Return**
+
+0 on success, non-zero on failure.
+
+
+.. c:function:: int nvme_mi_mi_config_get_smbus_freq (nvme_mi_ep_t ep, __u8 port, enum nvme_mi_config_smbus_freq *freq)
+
+   get configuration: SMBus port frequency
+
+**Parameters**
+
+``nvme_mi_ep_t ep``
+  endpoint for MI communication
+
+``__u8 port``
+  port ID to query
+
+``enum nvme_mi_config_smbus_freq *freq``
+  output value for current frequency configuration
+
+**Description**
+
+Performs a MI Configuration Get, to query the current SMBus frequency of
+the port specified in **port**. On success, populates **freq** with the port
+frequency
+
+**Return**
+
+0 on success, non-zero on failure.
+
+
+.. c:function:: int nvme_mi_mi_config_set_smbus_freq (nvme_mi_ep_t ep, __u8 port, enum nvme_mi_config_smbus_freq freq)
+
+   set configuration: SMBus port frequency
+
+**Parameters**
+
+``nvme_mi_ep_t ep``
+  endpoint for MI communication
+
+``__u8 port``
+  port ID to set
+
+``enum nvme_mi_config_smbus_freq freq``
+  new frequency configuration
+
+**Description**
+
+Performs a MI Configuration Set, to update the current SMBus frequency of
+the port specified in **port**.
+
+See :c:type:`struct nvme_mi_read_port_info <nvme_mi_read_port_info>` for the maximum supported SMBus frequency
+for the port.
+
+**Return**
+
+0 on success, non-zero on failure.
+
+
+.. c:function:: int nvme_mi_mi_config_set_health_status_change (nvme_mi_ep_t ep, __u32 mask)
+
+   clear CCS bits in health status
+
+**Parameters**
+
+``nvme_mi_ep_t ep``
+  endpoint for MI communication
+
+``__u32 mask``
+  bitmask to clear
+
+**Description**
+
+Performs a MI Configuration Set, to update the current health status poll
+values of the Composite Controller Status bits. Bits set in **mask** will
+be cleared from future health status poll data, and may be re-triggered by
+a future health change event.
+
+See :c:type:`nvme_mi_mi_subsystem_health_status_poll`(), :c:type:`enum nvme_mi_ccs <nvme_mi_ccs>` for
+values in **mask**.
+
+**Return**
+
+0 on success, non-zero on failure.
+
+
+.. c:function:: int nvme_mi_mi_config_get_mctp_mtu (nvme_mi_ep_t ep, __u8 port, __u16 *mtu)
+
+   get configuration: MCTP MTU
+
+**Parameters**
+
+``nvme_mi_ep_t ep``
+  endpoint for MI communication
+
+``__u8 port``
+  port ID to query
+
+``__u16 *mtu``
+  output value for current MCTP MTU configuration
+
+**Description**
+
+Performs a MI Configuration Get, to query the current MCTP Maximum
+Transmission Unit size (MTU) of the port specified in **port**. On success,
+populates **mtu** with the MTU.
+
+The default reset value is 64, corresponding to the MCTP baseline MTU.
+
+Some controllers may also use this as the maximum receive unit size, and
+may not accept MCTP messages larger than the configured MTU.
+
+**Return**
+
+0 on success, non-zero on failure.
+
+
+.. c:function:: int nvme_mi_mi_config_set_mctp_mtu (nvme_mi_ep_t ep, __u8 port, __u16 mtu)
+
+   set configuration: MCTP MTU
+
+**Parameters**
+
+``nvme_mi_ep_t ep``
+  endpoint for MI communication
+
+``__u8 port``
+  port ID to set
+
+``__u16 mtu``
+  new MTU configuration
+
+**Description**
+
+Performs a MI Configuration Set, to update the current MCTP MTU value for
+the port specified in **port**.
+
+Some controllers may also use this as the maximum receive unit size, and
+may not accept MCTP messages larger than the configured MTU. When setting
+this value, you will likely need to change the MTU of the local MCTP
+interface(s) to match.
+
+**Return**
+
+0 on success, non-zero on failure.
+
+
+.. c:function:: int nvme_mi_admin_xfer (nvme_mi_ctrl_t ctrl, struct nvme_mi_admin_req_hdr *admin_req, size_t req_data_size, struct nvme_mi_admin_resp_hdr *admin_resp, off_t resp_data_offset, size_t *resp_data_size)
+
+   Raw admin transfer interface.
+
+**Parameters**
+
+``nvme_mi_ctrl_t ctrl``
+  controller to send the admin command to
+
+``struct nvme_mi_admin_req_hdr *admin_req``
+  request data
+
+``size_t req_data_size``
+  size of request data payload
+
+``struct nvme_mi_admin_resp_hdr *admin_resp``
+  buffer for response data
+
+``off_t resp_data_offset``
+  offset into request data to retrieve from controller
+
+``size_t *resp_data_size``
+  size of response data buffer, updated to received size
+
+**Description**
+
+Performs an arbitrary NVMe Admin command, using the provided request data,
+in **admin_req**. The size of the request data *payload* is specified in
+**req_data_size** - this does not include the standard header length (so a
+header-only request would have a size of 0).
+
+On success, response data is stored in **admin_resp**, which has an optional
+appended payload buffer of **resp_data_size** bytes. The actual payload
+transferred will be stored in **resp_data_size**. These sizes do not include
+the Admin request header, so 0 represents no payload.
+
+As with all Admin commands, we can request partial data from the Admin
+Response payload, offset by **resp_data_offset**.
+
+See: :c:type:`struct nvme_mi_admin_req_hdr <nvme_mi_admin_req_hdr>` and :c:type:`struct nvme_mi_admin_resp_hdr <nvme_mi_admin_resp_hdr>`.
+
+**Return**
+
+0 on success, non-zero on failure.
+
+
+.. c:function:: int nvme_mi_admin_identify_partial (nvme_mi_ctrl_t ctrl, struct nvme_identify_args *args, off_t offset, size_t size)
+
+   Perform an Admin identify command, and retrieve partial response data.
+
+**Parameters**
+
+``nvme_mi_ctrl_t ctrl``
+  Controller to process identify command
+
+``struct nvme_identify_args *args``
+  Identify command arguments
+
+``off_t offset``
+  offset of identify data to retrieve from response
+
+``size_t size``
+  size of identify data to return
+
+**Description**
+
+Perform an Identify command, using the Identify command parameters in **args**.
+The **offset** and **size** arguments allow the caller to retrieve part of
+the identify response. See NVMe-MI section 6.2 for the semantics (and some
+handy diagrams) of the offset & size parameters.
+
+Will return an error if the length of the response data (from the controller)
+did not match **size**.
+
+Unless you're performing a vendor-unique identify command, You'll probably
+want to use one of the identify helpers (nvme_mi_admin_identify,
+nvme_mi_admin_identify_cns_nsid, or nvme_mi_admin_identify_<type>) instead
+of this. If the type of your identify command is standardized but not
+yet supported by libnvme-mi, please contact the maintainers.
+
+See: :c:type:`struct nvme_identify_args <nvme_identify_args>`
+
+**Return**
+
+0 on success, non-zero on failure
+
+
+.. c:function:: int nvme_mi_admin_identify (nvme_mi_ctrl_t ctrl, struct nvme_identify_args *args)
+
+   Perform an Admin identify command.
+
+**Parameters**
+
+``nvme_mi_ctrl_t ctrl``
+  Controller to process identify command
+
+``struct nvme_identify_args *args``
+  Identify command arguments
+
+**Description**
+
+Perform an Identify command, using the Identify command parameters in **args**.
+Stores the identify data in ->data, and (if set) the result from cdw0
+into args->result.
+
+Will return an error if the length of the response data (from the
+controller) is not a full :c:type:`NVME_IDENTIFY_DATA_SIZE`.
+
+See: :c:type:`struct nvme_identify_args <nvme_identify_args>`
+
+**Return**
+
+0 on success, non-zero on failure
+
+
+.. c:function:: int nvme_mi_admin_identify_cns_nsid (nvme_mi_ctrl_t ctrl, enum nvme_identify_cns cns, __u32 nsid, void *data)
+
+   Perform an Admin identify command using specific CNS/NSID parameters.
+
+**Parameters**
+
+``nvme_mi_ctrl_t ctrl``
+  Controller to process identify command
+
+``enum nvme_identify_cns cns``
+  Controller or Namespace Structure, specifying identified object
+
+``__u32 nsid``
+  namespace ID
+
+``void *data``
+  buffer for identify data response
+
+**Description**
+
+Perform an Identify command, using the CNS specifier **cns**, and the
+namespace ID **nsid** if required by the CNS type.
+
+Stores the identify data in **data**, which is expected to be a buffer of
+:c:type:`NVME_IDENTIFY_DATA_SIZE` bytes.
+
+Will return an error if the length of the response data (from the
+controller) is not a full :c:type:`NVME_IDENTIFY_DATA_SIZE`.
+
+**Return**
+
+0 on success, non-zero on failure
+
+
+.. c:function:: int nvme_mi_admin_identify_ctrl (nvme_mi_ctrl_t ctrl, struct nvme_id_ctrl *id)
+
+   Perform an Admin identify for a controller
+
+**Parameters**
+
+``nvme_mi_ctrl_t ctrl``
+  Controller to process identify command
+
+``struct nvme_id_ctrl *id``
+  Controller identify data to populate
+
+**Description**
+
+Perform an Identify command, for the controller specified by **ctrl**,
+writing identify data to **id**.
+
+Will return an error if the length of the response data (from the
+controller) is not a full :c:type:`NVME_IDENTIFY_DATA_SIZE`, so **id** will be
+fully populated on success.
+
+See: :c:type:`struct nvme_id_ctrl <nvme_id_ctrl>`
+
+**Return**
+
+0 on success, non-zero on failure
+
+
+.. c:function:: int nvme_mi_admin_identify_ctrl_list (nvme_mi_ctrl_t ctrl, __u16 cntid, struct nvme_ctrl_list *list)
+
+   Perform an Admin identify for a controller list.
+
+**Parameters**
+
+``nvme_mi_ctrl_t ctrl``
+  Controller to process identify command
+
+``__u16 cntid``
+  Controller ID to specify list start
+
+``struct nvme_ctrl_list *list``
+  List data to populate
+
+**Description**
+
+Perform an Identify command, for the controller list starting with
+IDs greater than or equal to **cntid**.
+
+Will return an error if the length of the response data (from the
+controller) is not a full :c:type:`NVME_IDENTIFY_DATA_SIZE`, so **id** will be
+fully populated on success.
+
+See: :c:type:`struct nvme_ctrl_list <nvme_ctrl_list>`
+
+**Return**
+
+0 on success, non-zero on failure
+
+
+.. c:function:: int nvme_mi_admin_get_log_page (nvme_mi_ctrl_t ctrl, struct nvme_get_log_args *args)
+
+   Retrieve log page data from controller
+
+**Parameters**
+
+``nvme_mi_ctrl_t ctrl``
+  Controller to query
+
+``struct nvme_get_log_args *args``
+  Get Log Page command arguments
+
+**Description**
+
+Performs a Get Log Page Admin command as specified by **args**. Response data
+is stored in **args->data**, which should be a buffer of **args->data_len** bytes.
+Resulting data length is stored in **args->data_len** on successful
+command completion.
+
+This request may be implemented as multiple log page commands, in order
+to fit within MI message-size limits.
+
+See: :c:type:`struct nvme_get_log_args <nvme_get_log_args>`
+
+**Return**
+
+0 on success, non-zero on failure
+
+
+.. c:function:: int nvme_mi_admin_security_send (nvme_mi_ctrl_t ctrl, struct nvme_security_send_args *args)
+
+   Perform a Security Send command on a controller.
+
+**Parameters**
+
+``nvme_mi_ctrl_t ctrl``
+  Controller to send command to
+
+``struct nvme_security_send_args *args``
+  Security Send command arguments
+
+**Description**
+
+Performs a Security Send Admin command as specified by **args**. Response data
+is stored in **args->data**, which should be a buffer of **args->data_len** bytes.
+Resulting data length is stored in **args->data_len** on successful
+command completion.
+
+Security Send data length should not be greater than 4096 bytes to
+comply with specification limits.
+
+See: :c:type:`struct nvme_get_log_args <nvme_get_log_args>`
+
+**Return**
+
+0 on success, non-zero on failure
+
+
+.. c:function:: int nvme_mi_admin_security_recv (nvme_mi_ctrl_t ctrl, struct nvme_security_receive_args *args)
+
+   Perform a Security Receive command on a controller.
+
+**Parameters**
+
+``nvme_mi_ctrl_t ctrl``
+  Controller to send command to
+
+``struct nvme_security_receive_args *args``
+  Security Receive command arguments
+
+**Description**
+
+Performs a Security Receive Admin command as specified by **args**. Response
+data is stored in **args->data**, which should be a buffer of **args->data_len**
+bytes. Resulting data length is stored in **args->data_len** on successful
+command completion.
+
+Security Receive data length should not be greater than 4096 bytes to
+comply with specification limits.
+
+See: :c:type:`struct nvme_get_log_args <nvme_get_log_args>`
+
+**Return**
+
+0 on success, non-zero on failure
+
+