Merge pull request #502 from CodeConstruct/pr/mi-status

Add encoding for MI/NVMe status values

Author: dwsuse

src/libnvme-mi.map

@@ -8,6 +8,7 @@ LIBNVME_MI_1_2 {
 		nvme_mi_admin_sanitize_nvm;
 		nvme_mi_admin_fw_download;
 		nvme_mi_admin_fw_commit;
+		nvme_mi_status_to_string;
 };
 
 LIBNVME_MI_1_1 {

src/nvme/mi.c

@@ -11,6 +11,7 @@
 #include <stdlib.h>
 #include <stdio.h>
 
+#include <ccan/array_size/array_size.h>
 #include <ccan/endian/endian.h>
 
 #include "log.h"
@@ -315,13 +316,12 @@ static int nvme_mi_admin_parse_status(struct nvme_mi_resp *resp, __u32 *result)
 	resp_hdr = (struct nvme_mi_msg_resp *)resp->hdr;
 
 	/* If we have a MI error, we can't be sure there's an admin header
-	 * following; return just the MI status
-	 *
-	 * TODO: this may alias the cdw3 result values, see
-	 * https://github.com/linux-nvme/libnvme/issues/456
+	 * following; return just the MI status, with the status type
+	 * indicator of MI.
 	 */
 	if (resp_hdr->status)
-		return resp_hdr->status;
+		return resp_hdr->status |
+			(NVME_STATUS_TYPE_MI << NVME_STATUS_TYPE_SHIFT);
 
 	/* We shouldn't hit this, as we'd have an error reported earlier.
 	 * However, for pointer safety, ensure we have a full admin header
@@ -1283,3 +1283,37 @@ nvme_mi_ctrl_t nvme_mi_next_ctrl(nvme_mi_ep_t ep, nvme_mi_ctrl_t c)
 {
 	return c ? list_next(&ep->controllers, c, ep_entry) : NULL;
 }
+
+
+static const char *const mi_status[] = {
+        [NVME_MI_RESP_MPR]                   = "More Processing Required: The command message is in progress and requires more time to complete processing",
+        [NVME_MI_RESP_INTERNAL_ERR]          = "Internal Error: The request message could not be processed due to a vendor-specific error",
+        [NVME_MI_RESP_INVALID_OPCODE]        = "Invalid Command Opcode",
+        [NVME_MI_RESP_INVALID_PARAM]         = "Invalid Parameter",
+        [NVME_MI_RESP_INVALID_CMD_SIZE]      = "Invalid Command Size: The size of the message body of the request was different than expected",
+        [NVME_MI_RESP_INVALID_INPUT_SIZE]    = "Invalid Command Input Data Size: The command requires data and contains too much or too little data",
+        [NVME_MI_RESP_ACCESS_DENIED]         = "Access Denied. Processing prohibited due to a vendor-specific mechanism of the Command and Feature lockdown function",
+        [NVME_MI_RESP_VPD_UPDATES_EXCEEDED]  = "VPD Updates Exceeded",
+        [NVME_MI_RESP_PCIE_INACCESSIBLE]     = "PCIe Inaccessible. The PCIe functionality is not available at this time",
+        [NVME_MI_RESP_MEB_SANITIZED]         = "Management Endpoint Buffer Cleared Due to Sanitize",
+        [NVME_MI_RESP_ENC_SERV_FAILURE]      = "Enclosure Services Failure",
+        [NVME_MI_RESP_ENC_SERV_XFER_FAILURE] = "Enclosure Services Transfer Failure: Communication with the Enclosure Services Process has failed",
+        [NVME_MI_RESP_ENC_FAILURE]           = "An unrecoverable enclosure failure has been detected by the Enclosuer Services Process",
+        [NVME_MI_RESP_ENC_XFER_REFUSED]      = "Enclosure Services Transfer Refused: The NVM Subsystem or Enclosure Services Process indicated an error or an invalid format in communication",
+        [NVME_MI_RESP_ENC_FUNC_UNSUP]        = "Unsupported Enclosure Function: An SES Send command has been attempted to a simple Subenclosure",
+        [NVME_MI_RESP_ENC_SERV_UNAVAIL]      = "Enclosure Services Unavailable: The NVM Subsystem or Enclosure Services Process has encountered an error but may become available again",
+        [NVME_MI_RESP_ENC_DEGRADED]          = "Enclosure Degraded: A noncritical failure has been detected by the Enclosure Services Process",
+        [NVME_MI_RESP_SANITIZE_IN_PROGRESS]  = "Sanitize In Progress: The requested command is prohibited while a sanitize operation is in progress",
+};
+
+/* kept in mi.c while we have a split libnvme/libnvme-mi; consider moving
+ * to utils.c (with nvme_status_to_string) if we ever merge. */
+const char *nvme_mi_status_to_string(int status)
+{
+	const char *s = "Unknown status";
+
+	if (status < ARRAY_SIZE(mi_status) && mi_status[status])
+                s = mi_status[status];
+
+        return s;
+}

src/nvme/mi.h

@@ -367,6 +367,20 @@ struct nvme_mi_admin_resp_hdr {
 	__le32	cdw0, cdw1, cdw3;
 } __attribute__((packed));
 
+/**
+ * nvme_mi_status_to_string() - return a string representation of the MI
+ * status.
+ * @status: MI response status
+ *
+ * Gives a string description of @status, as per section 4.1.2 of the NVMe-MI
+ * spec. The status value should be of type NVME_STATUS_MI, and extracted
+ * from the return value using nvme_status_get_value().
+ *
+ * Returned string is const, and should not be free()ed.
+ *
+ * Returns: A string representing the status value
+ */
+const char *nvme_mi_status_to_string(int status);
 
 /**
  * nvme_mi_create_root() - Create top-level MI (root) handle.

src/nvme/types.h

@@ -6141,6 +6141,75 @@ static inline __u16 nvme_status_code(__u16 status_field)
 	return NVME_GET(status_field, SC);
 }
 
+/**
+ * enum nvme_status_type - type encoding for NVMe return values, when
+ * represented as an int.
+ *
+ * The nvme_* api returns an int, with negative values indicating an internal
+ * or syscall error, zero signifying success, positive values representing
+ * the NVMe status.
+ *
+ * That latter case (the NVMe status) may represent status values from
+ * different parts of the transport/controller/etc, and are at most 16 bits of
+ * data. So, we use the most-significant 3 bits of the signed int to indicate
+ * which type of status this is.
+ *
+ * @NVME_STATUS_TYPE_SHIFT: shift value for status bits
+ * @NVME_STATUS_TYPE_MASK:  mask value for status bits
+ *
+ * @NVME_STATUS_TYPE_NVME:  NVMe command status value, typically from CDW3
+ * @NVME_STATUS_TYPE_MI:    NVMe-MI header status
+ */
+enum nvme_status_type {
+	NVME_STATUS_TYPE_SHIFT		= 27,
+	NVME_STATUS_TYPE_MASK		= 0x7,
+
+	NVME_STATUS_TYPE_NVME		= 0,
+	NVME_STATUS_TYPE_MI		= 1,
+};
+
+/**
+ * nvme_status_get_type() - extract the type from a nvme_* return value
+ * @status: the (non-negative) return value from the NVMe API
+ *
+ * Returns: the type component of the status.
+ */
+static inline __u32 nvme_status_get_type(int status)
+{
+	return NVME_GET(status, STATUS_TYPE);
+}
+
+/**
+ * nvme_status_get_value() - extract the status value from a nvme_* return
+ * value
+ * @status: the (non-negative) return value from the NVMe API
+ *
+ * Returns: the value component of the status; the set of values will depend
+ * on the status type.
+ */
+static inline __u32 nvme_status_get_value(int status)
+{
+	return status & ~(NVME_STATUS_TYPE_MASK << NVME_STATUS_TYPE_SHIFT);
+}
+
+/**
+ * nvme_status_equals() - helper to check a status against a type and value
+ * @status: the (non-negative) return value from the NVMe API
+ * @type: the status type
+ * @value: the status value
+ *
+ * Returns: true if @status is of the specified type and value
+ */
+static inline __u32 nvme_status_equals(int status, enum nvme_status_type type,
+				       unsigned int value)
+{
+	if (status < 0)
+		return false;
+
+	return nvme_status_get_type(status) == type &&
+		nvme_status_get_value(status) == value;
+}
+
 /**
  * enum nvme_admin_opcode - Known NVMe admin opcodes
  * @nvme_admin_delete_sq:		Delete I/O Submission Queue

test/mi-mctp.c

@@ -308,7 +308,8 @@ static void test_admin_resp_err(nvme_mi_ep_t ep, struct test_peer *peer)
 	peer->tx_buf_len = 8;
 
 	rc = nvme_mi_admin_identify_ctrl(ctrl, &id);
-	assert(rc == 0x2);
+	assert(nvme_status_get_type(rc) == NVME_STATUS_TYPE_MI);
+	assert(nvme_status_get_value(rc) == NVME_MI_RESP_INTERNAL_ERR);
 }
 
 /* test: all 4-byte aligned response sizes - should be decoded into the
@@ -332,7 +333,8 @@ static void test_admin_resp_sizes(nvme_mi_ep_t ep, struct test_peer *peer)
 	for (i = 8; i <= 4096 + 8; i+=4) {
 		peer->tx_buf_len = i;
 		rc = nvme_mi_admin_identify_ctrl(ctrl, &id);
-		assert(rc == 2);
+		assert(nvme_status_get_type(rc) == NVME_STATUS_TYPE_MI);
+		assert(nvme_status_get_value(rc) == NVME_MI_RESP_INTERNAL_ERR);
 	}
 
 	nvme_mi_close_ctrl(ctrl);