| 1 |
NVMe Management Interface (NVMe-MI) support |
| 2 |
=========================================== |
| 3 |
|
| 4 |
This libnvme project also includes support for the NVMe Management Interface |
| 5 |
(NVMe-MI), currently over a Management Component Transport (MCTP) |
| 6 |
protocol link. This MCTP link will typically use i2c/SMBus as the |
| 7 |
hardware transport, enabling out-of-band management and control over NVMe |
| 8 |
devices using a simple SMBus interface. |
| 9 |
|
| 10 |
The MI interface is compiled into a separate shared object, ``libnvme-mi.so``. |
| 11 |
|
| 12 |
Most of the MI API is transport-agnostic, except for the endpoint constructor |
| 13 |
functions. Once an endpoint object (``nvme_mi_ep_t``) is created, the generic |
| 14 |
functions can be used to manage it. |
| 15 |
|
| 16 |
When endpoints are created (through one of the transport-specific functions, |
| 17 |
like ``nvme_mi_open_mctp()``), the endpoint hardware will be probed to |
| 18 |
see if any device-specific workarounds ("quirks") are required. This is |
| 19 |
implemented as an Identify Controller command, requesting a small amount of |
| 20 |
data on controller ID 0. |
| 21 |
|
| 22 |
To suppress this probe, the ``LIBNVME_MI_PROBE_ENABLED`` environment var can be |
| 23 |
set. Values of ``0``, ``false`` and ``disabled`` will disable the probe, and no |
| 24 |
quirks will be applied. Other values, or an unset environment variable, will |
| 25 |
enable the probe. |
| 26 |
|
| 27 |
MCTP Transport |
| 28 |
-------------- |
| 29 |
|
| 30 |
The MI API is generally transport-agnostic, but the only currently-supported |
| 31 |
transport is MCTP, using the kernel ``AF_MCTP`` socket interface. |
| 32 |
|
| 33 |
MCTP endpoints are addressed by a (network-id, endpoint-id) pair. Endpoint |
| 34 |
IDs (EIDs) are defined by the MCTP standard as an 8-bit value. Since the |
| 35 |
address space is somewhat limited, the Linux `AF_MCTP` support allows for |
| 36 |
separate MCTP "networks", which provide separate address spaces. These networks |
| 37 |
each have a unique ``unsigned int`` as their ID. |
| 38 |
|
| 39 |
The default Network ID is 1; unless you have configured otherwise, MCTP |
| 40 |
endpoints will appear on this network. |
| 41 |
|
| 42 |
If compiled with D-Bus support, ``libnvme-mi`` can query the system MCTP daemon |
| 43 |
("``mctpd``") to find attached NVMe devices, via the ``nvme_mi_scan_mctp()`` |
| 44 |
function. Calling this will establish a ``nvme_root_t`` object, populated |
| 45 |
with the results of that scan. Use the ``nvme_mi_for_each_endpoint`` macro |
| 46 |
to iterate through the scanned endpoints. |
| 47 |
|
| 48 |
Note that the MCTP daemon is provided separately, as part of the MCTP userspace |
| 49 |
tools, at https://github.com/CodeConstruct/mctp . ``mctpd`` is responsible for |
| 50 |
discovery and enumeration for MCTP endpoints on the system, and will query |
| 51 |
each for its protocol capabilities during enumeration. Consequently, NVMe-MI |
| 52 |
endpoints will need to report support for NVMe-MI-over-MCTP (protocol 0x4) in |
| 53 |
their supported protocols list (ie., as returned by the MCTP Get Message Type |
| 54 |
Support command) in order to be discovered. |