[openib-general] [PATCH] added comments to ib_mad.h - minor update

[Sean Hefty]

Here's a patch that includes some additional comments for the APIs in ib_mad.h.  I've also added a new value to ib_wc_status that can be used to indicate that a send request timed-out.  (I originally wasn't going to do this, but it seemed like the best way to handle this case.)

Other changes were renaming fields to match those used in ib_verbs.h.  And a new field for an address handle was added to allow clients to cache and re-use address handles when sending MADs.  I was going to rename the ib_mad_reg_class to ib_mad_reg, but that's the name of the structure, so I'd have to change that name first...

These have not been committed yet.

While commenting the ib_mad_msg structure, I was wondering if it made sense to break the structure apart into multiple structures: ib_send_mad_wr, ib_mad_send_wc, ib_mad_recv_wc.  Thoughts?


Index: ib_verbs.h
===================================================================
--- ib_verbs.h	(revision 587)
+++ ib_verbs.h	(working copy)
@@ -515,7 +515,8 @@
 	IB_WC_REM_ABORT_ERR,
 	IB_WC_INV_EECN_ERR,
 	IB_WC_INV_EEC_STATE_ERR,
-	IB_WC_GENERAL_ERR
+	IB_WC_GENERAL_ERR,
+	IB_WC_RESP_TIMEOUT_ERR
 };
 
 enum ib_wc_opcode {
Index: ib_mad.h
===================================================================
--- ib_mad.h	(revision 587)
+++ ib_mad.h	(working copy)
@@ -42,27 +42,41 @@
 	u32			lo_tid;
 };
 
+/**
+ * ib_mad_msg - MAD information to send or was received.
+ * list - Allows chaining together multiple messages.
+ * @context - Set by user and returned for sent messages.  For a received
+ *    response message, set to the @context for the matching send.
+ * @buf - TBD
+ * @length - TBD
+ * @ah - Address handle used for send operation.
+ * @timeout_ms - Used for send operations.  Timeout value, in milliseconds,
+ *   to wait for a response message.  Set to 0 if no response is expected.
+ * @status - Completion status for a sent message.
+ * @remote_qp - Destination QP for a sent message.  Source QP for a received
+ *   message.
+ * @remote_qkey - Specifies the qkey used by remote QP for send operations.
+ * @remote_lid - LID of remote QP for a received message.
+ * @pkey_index - pkey index for a received message.
+ * @sl - service level of source for a received message.
+ * @path_bits - path bits of source for a received message.
+ * @grh_flag - Indicates if the GRH is valid.
+ */
 struct ib_mad_msg {
 	struct list_head	list;
-
-	/* See about zero-copy... */
 	void			*buf;
 	int			length;
-
-	/* send_context is set on a receive to context on matching send */
-	void			*send_context;
+	struct ib_ah		*ah;
 	void			*context;
 	int			timeout_ms;
-
 	enum ib_wc_status_t	status;
-
 	u32			remote_qp;
-	u32			remote_q_key;
+	u32			remote_qkey;
 	u16			remote_lid;
 	u16			pkey_index;
-	u8			service_level;
+	u8			sl;
 	u8			path_bits;
-	u8			grh_valid;
+	u8			grh_flag;
 };
 
 /**