Merge pull request #399 from CodeConstruct/mi-kdoc

MI: Add kernel-doc documentation for MI API

Author: dwsuse

.github/workflows/doc.yml

@@ -14,7 +14,7 @@ jobs:
         uses: actions/checkout@v3
       - name: Check documentation format
         run: |
-          API_FILES="fabrics.h filters.h ioctl.h linux.h tree.h types.h"
+          API_FILES="fabrics.h filters.h ioctl.h linux.h mi.h tree.h types.h"
           for file in $API_FILES; do
             ./doc/kernel-doc -v -none src/nvme/$file 2>&1 | sed -r 's/^([^:]+):([0-9]+): (warning|error):/::\3 file=\1,line=\2::/g'
           done

doc/api.rst

@@ -11,6 +11,7 @@ functions.
 .. include::   rst/ioctl.rst
 .. include::   rst/fabrics.rst
 .. include::   rst/linux.rst
+.. include::   rst/mi.rst
 .. include::   rst/tree.rst
 .. include::   rst/filters.rst
 .. include::   rst/util.rst

doc/api.rst.in

@@ -11,6 +11,7 @@ functions.
 .. include::   rst/ioctl.rst
 .. include::   rst/fabrics.rst
 .. include::   rst/linux.rst
+.. include::   rst/mi.rst
 .. include::   rst/tree.rst
 .. include::   rst/filters.rst
 .. include::   rst/util.rst

doc/index.rst

@@ -12,6 +12,7 @@ and utilities to connect, scan, and manage nvme devices on a Linux system.
 
    installation.rst
    quickstart.rst
+   mi.rst
    api.rst
 
 Indices and tables

doc/index.rst.in

@@ -12,6 +12,7 @@ and utilities to connect, scan, and manage nvme devices on a Linux system.
 
    installation.rst
    quickstart.rst
+   mi.rst
    api.rst
 
 Indices and tables

doc/meson.build

@@ -13,6 +13,7 @@ api_files = [
   'ioctl.h',
   'linux.h',
   'log.h',
+  'mi.h',
   'tree.h',
   'types.h',
   'fabrics.h',
@@ -25,6 +26,7 @@ sphinx_sources = [
     'index.rst',
     'quickstart.rst',
     'installation.rst',
+    'mi.rst',
     'config-schema.json'
 ]
 

doc/mi.rst.in

@@ -0,0 +1,29 @@
+NVMe Management Interface (NVMe-MI) support
+===========================================
+
+This libnvme project also includes support for the NVMe Management Interface
+(NVMe-MI), currently over a Management Component Transport (MCTP)
+protocol link. This MCTP link will typically use i2c/SMBus as the
+hardware transport, enabling out-of-band management and control over NVMe
+devices using a simple SMBus interface.
+
+The MI interface is compiled into a separate shared object, ``libnvme-mi.so``.
+
+Most of the MI API is transport-agnostic, except for the endpoint constructor
+functions. Once an endpoint object (``nvme_mi_ep_t``) is created, the generic
+functions can be used to manage it.
+
+MCTP Transport
+--------------
+
+The MI API is generally transport-agnostic, but the only currently-supported
+transport is MCTP, using the kernel ``AF_MCTP`` socket interface.
+
+MCTP endpoints are addressed by a (network-id, endpoint-id) pair. Endpoint
+IDs (EIDs) are defined by the MCTP standard as an 8-bit value. Since the
+address space is somewhat limited, the Linux `AF_MCTP` support allows for
+separate MCTP "networks", which provide separate address spaces. These networks
+each have a unique ``unsigned int`` as their ID.
+
+The default Network ID is 1; unless you have configured otherwise, MCTP
+endpoints will appear on this network.

src/nvme/mi.c

@@ -526,14 +526,14 @@ int nvme_mi_mi_read_mi_data_port(nvme_mi_ep_t ep, __u8 portid,
 	return 0;
 }
 
-int nvme_mi_mi_read_mi_data_ctrl_list(nvme_mi_ep_t ep, __u8 start_portid,
+int nvme_mi_mi_read_mi_data_ctrl_list(nvme_mi_ep_t ep, __u8 start_ctrlid,
 				       struct nvme_ctrl_list *list)
 {
 	size_t len;
 	__u32 cdw0;
 	int rc;
 
-	cdw0 = ((__u8)nvme_mi_dtyp_ctrl_list << 24) | (start_portid << 16);
+	cdw0 = ((__u8)nvme_mi_dtyp_ctrl_list << 24) | (start_ctrlid << 16);
 	len = sizeof(*list);
 
 	rc = nvme_mi_read_data(ep, cdw0, list, &len);