]> git.openfabrics.org - ~shefty/libibverbs.git/commitdiff
Fixes for man pages
authorDotan Barak <dotanb@dev.mellanox.co.il>
Sun, 3 Feb 2008 15:55:04 +0000 (17:55 +0200)
committerRoland Dreier <rolandd@cisco.com>
Mon, 18 Feb 2008 21:58:57 +0000 (13:58 -0800)
Some fixes and updates to several man pages:
 * Correct formatting in a few places.
 * Add more "SEE ALSO" functions where appropriate.
 * Document byte order of GUID and P_Key fields.
 * Fix example code in ibv_get_cq_event.3
 * Document GRH handling on receive.

Signed-off-by: Dotan Barak <dotanb@dev.mellanox.co.il>
Signed-off-by: Roland Dreier <rolandd@cisco.com>
man/ibv_create_cq.3
man/ibv_create_qp.3
man/ibv_fork_init.3
man/ibv_get_cq_event.3
man/ibv_modify_qp.3
man/ibv_poll_cq.3
man/ibv_post_recv.3
man/ibv_post_srq_recv.3
man/ibv_query_device.3
man/ibv_query_pkey.3

index c39fe83ec8a828b40bcf81cfe5a4d4618cd1a346..bb256d546ef41a1746c8692d0e0bd30aef6a63a9 100644 (file)
@@ -51,6 +51,7 @@ fails if any queue pair is still associated with this CQ.
 .SH "SEE ALSO"
 .BR ibv_resize_cq (3),
 .BR ibv_req_notify_cq (3),
+.BR ibv_ack_cq_events (3),
 .BR ibv_create_qp (3)
 .SH "AUTHORS"
 .TP
index 68a08b0c4e5e528ec8fbd31adaf32aa71a2942b5..abd544961e168becba1ad62d044f874645bf0c19 100644 (file)
@@ -8,9 +8,9 @@ ibv_create_qp, ibv_destroy_qp \- create or destroy a queue pair (QP)
 .B #include <infiniband/verbs.h>
 .sp
 .BI "struct ibv_qp *ibv_create_qp(struct ibv_pd " "*pd" ,
-.BI "                             struct ibv_qp_init_attr " "*qp_init_attr)" ;
+.BI "                             struct ibv_qp_init_attr " "*qp_init_attr" );
 .nl
-.BI "int ibv_destroy_qp(struct ibv_qp " "*qp)" ;
+.BI "int ibv_destroy_qp(struct ibv_qp " "*qp" );
 .fi
 .SH "DESCRIPTION"
 .B ibv_create_qp()
index d911c3f98ec9e5cc6312421c5c2e8fecb21c9bb2..b34f71f19b17bdeaab927c910836ab1b1855cbbc 100644 (file)
@@ -49,7 +49,9 @@ regions.  The precise performance impact depends on the workload and
 usually will not be significant.
 .SH "SEE ALSO"
 .BR fork (2),
+.BR wait (2),
 .BR system (3),
+.BR exec (3),
 .BR ibv_get_device_list (3)
 .SH "AUTHORS"
 .TP
index 695734b1613a999368b0502dac8b5db6e4518a55..27dca6f15beb701407c68e018feb4ab0fb474abe 100644 (file)
@@ -18,11 +18,11 @@ ibv_get_cq_event, ibv_ack_cq_events \- get and acknowledge completion queue (CQ)
 .B ibv_get_cq_event()
 waits for the next completion event in the completion event channel
 .I channel\fR.
-The argument
+Fills the arguments
 .I cq
-is used to return the CQ that caused the event and
+with the CQ that got the event and
 .I cq_context
-is used to return the CQ's context.
+with the CQ's context\fR.
 .PP
 .B ibv_ack_cq_events()
 acknowledges
@@ -102,7 +102,7 @@ if (ibv_get_cq_event(channel, &ev_cq, &ev_ctx)) {
 ibv_ack_cq_events(ev_cq, 1);
 .PP
 /* Request notification upon the next completion event */
-if (ibv_req_notify_cq(cq, 0)) {
+if (ibv_req_notify_cq(ev_cq, 0)) {
         fprintf(stderr, "Couldn't request CQ notification\en");
         return 1;
 }
@@ -114,6 +114,10 @@ do {
                 fprintf(stderr, "Failed to poll completions from the CQ\en");
                 return 1;
         }
+
+        /* there may be an extra event with no completion in the CQ */
+        if (ne == 0)
+                continue;
 .PP
         if (wc.status != IBV_WC_SUCCESS) {
                 fprintf(stderr, "Completion with status 0x%x was found\en", wc.status);
index a870744ded93465967d7f76d349c0f60e9728db0..f04590001c4f19d13beb20cbe1394cd4b78f77ca 100644 (file)
@@ -130,7 +130,7 @@ Next state     Required attributes
 \-\-\-\-\-\-\-\-\-\-     \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 Init \fB          IBV_QP_STATE, IBV_QP_PKEY_INDEX, IBV_QP_PORT, \fR
      \fB          IBV_QP_QKEY \fR
-RTR  \fB          None \fR
+RTR  \fB          IBV_QP_STATE \fR
 RTS  \fB          IBV_QP_STATE, IBV_QP_SQ_PSN \fR
 .fi
 .PP
index b634fc956d7cb67367182430d25fa34ea4eb9390..75e4d7ca044f811d95934ef46b5517cdf68058af 100644 (file)
@@ -32,7 +32,7 @@ uint32_t                vendor_err;     /* Vendor error syndrome */
 uint32_t                byte_len;       /* Number of bytes transferred */
 uint32_t                imm_data;       /* Immediate data (in network byte order) */
 uint32_t                qp_num;         /* Local QP number of completed WR */
-uint32_t                src_qp;         /* Source QP number (remote QP number) of completed WR */
+uint32_t                src_qp;         /* Source QP number (remote QP number) of completed WR (valid only for UD QPs) */
 enum ibv_wc_flags       wc_flags;       /* Flags of the completed WR */
 uint16_t                pkey_index;     /* P_Key index (valid only for GSI QPs) */
 uint16_t                slid;           /* Source LID */
@@ -47,7 +47,7 @@ The attribute wc_flags describes the properties of the work completion.
 It is either 0 or the bitwise OR of one or more of the following flags:
 .PP
 .TP
-.B IBV_WC_GRH \fR      GRH is present
+.B IBV_WC_GRH \fR      GRH is present (valid only for UD QPs)
 .TP
 .B IBV_WC_WITH_IMM \fR Immediate data value is valid
 .PP
index 478b67a66a18cdf90d821b603ad53c73a069c3c5..46a630bc652a7dc919c85c9c8507f2cfb6535711 100644 (file)
@@ -44,7 +44,6 @@ uint32_t                lkey;      /* Key of the local Memory Region */
 .in -8
 };
 .fi
-
 .SH "RETURN VALUE"
 .B ibv_post_recv()
 returns 0 on success, or the value of errno on failure (which indicates the failure reason).
@@ -60,6 +59,13 @@ is associated with a shared receive queue, you must use the function
 and not
 .B ibv_post_recv()\fR,
 since the QP's own receive queue will not be used.
+.PP
+If a WR is being posted to a UD QP, the Global Routing Header (GRH) of
+the incoming message will be placed in the first 40 bytes of the
+buffer(s) in the scatter list.  If no GRH is present in the incoming
+message, then the first bytes will be undefined.  This means that in
+all cases, the actual data of the incoming message will start at an
+offset of 40 bytes into the buffer(s) in the scatter list.
 .SH "SEE ALSO"
 .BR ibv_create_qp (3),
 .BR ibv_post_send (3),
index c7e2302652b4a8186d9e429cb9c7a7091e51b51a..65877cda63e149e570dd1f9da6c55f8a7b3a3eb2 100644 (file)
@@ -51,6 +51,13 @@ returns 0 on success, or the value of errno on failure (which indicates the fail
 The buffers used by a WR can only be safely reused after WR the
 request is fully executed and a work completion has been retrieved
 from the corresponding completion queue (CQ).
+.PP
+If a WR is being posted to a UD QP, the Global Routing Header (GRH) of
+the incoming message will be placed in the first 40 bytes of the
+buffer(s) in the scatter list.  If no GRH is present in the incoming
+message, then the first bytes will be undefined.  This means that in
+all cases, the actual data of the incoming message will start at an
+offset of 40 bytes into the buffer(s) in the scatter list.
 .SH "SEE ALSO"
 .BR ibv_create_qp (3),
 .BR ibv_post_send (3),
index 344f5b36cdd57a8ea4572c451321458d752b3496..f32776937e9cc9360650b4dd64b69be4f179d443 100644 (file)
@@ -22,8 +22,8 @@ is a pointer to an ibv_device_attr struct, as defined in <infiniband/verbs.h>.
 struct ibv_device_attr {
 .in +8
 char                    fw_ver[64];             /* FW version */
-uint64_t                node_guid;              /* Node GUID */
-uint64_t                sys_image_guid;         /* System image GUID */
+uint64_t                node_guid;              /* Node GUID (in network byte order) */
+uint64_t                sys_image_guid;         /* System image GUID (in network byte order) */
 uint64_t                max_mr_size;            /* Largest contiguous block that can be registered */
 uint64_t                page_size_cap;          /* Supported memory shift sizes */
 uint32_t                vendor_id;              /* Vendor ID, per IEEE */
index 489f1aca45e7890562c288c80015a546e6533f05..fcdfe6c6f529e3c023bf310df4c5889e755d795d 100644 (file)
@@ -12,7 +12,7 @@ ibv_query_pkey \- query an InfiniBand port's P_Key table
 .fi
 .SH "DESCRIPTION"
 .B ibv_query_pkey()
-returns the P_Key value in entry
+returns the P_Key value (in network byte order) in entry
 .I index
 of port
 .I port_num