Man page updates

- Fix spelling mistakes
- Convert "PKey"/"QKey" to "P_Key"/"Q_Key"
- Fix variable names in ibv_get_cq_event() example
- Add non-blocking examples for ibv_get_cq_event() and ibv_get_async_event()

Signed-off-by: Dotan Barak <dotanb@mellanox.co.il>.
Signed-off-by: Roland Dreier <rolandd@cisco.com>

6 files changed, 137 insertions, 26 deletions

diff --git a/man/ibv_get_async_event.3 b/man/ibv_get_async_event.3
index bb6d068..77e8be8 100644
--- a/man/ibv_get_async_event.3
+++ b/man/ibv_get_async_event.3
@@ -110,6 +110,51 @@ is a blocking function.  If multiple threads call this function
 simultaneously, then when an async event occurs, only one thread will
 receive it, and it is not possible to predict which thread will
 receive it.
+.SH "EXAMPLES"
+The following code example demonstrates one possible way to work with async events in non-blocking mode.
+It performs the following steps:
+.PP
+1. Set the async events queue work mode to be non-blocked
+.br
+2. Poll the queue until it has an async event
+.br
+3. Get the async event and ack it
+.PP
+.nf
+/* change the blocking mode of the async event queue */
+flags = fcntl(ctx->async_fd, F_GETFL);
+rc = fcntl(ctx->async_fd, F_SETFL, flags | O_NONBLOCK);
+if (rc < 0) {
+        fprintf(stderr, "Failed to change file descriptor of async event queue\en");
+        return 1;
+}
+
+/*
+ * poll the queue until it has an event and sleep ms_timeout
+ * milliseconds between any iteration
+ */
+my_pollfd.fd      = ctx->async_fd;
+my_pollfd.events  = POLLIN;
+my_pollfd.revents = 0;
+
+do {
+        rc = poll(&my_pollfd, 1, ms_timeout);
+} while (rc == 0);
+if (rc < 0) {
+        fprintf(stderr, "poll failed\en");
+        return 1;
+}
+
+/* Get the async event */
+if (ibv_get_async_event(ctx, &async_event)) {
+        fprintf(stderr, "Failed to get async_event\en");
+        return 1;
+}
+
+/* Ack the event */
+ibv_ack_async_event(&async_event);
+
+.fi
 .SH "SEE ALSO"
 .BR ibv_open_device (3)
 .SH "AUTHORS"
diff --git a/man/ibv_get_cq_event.3 b/man/ibv_get_cq_event.3
index c48f2a1..695734b 100644
--- a/man/ibv_get_cq_event.3
+++ b/man/ibv_get_cq_event.3
@@ -1,5 +1,6 @@
-.TH IBV_GET_CQ_EVENT 3  "2006-10-31" "OpenIB" "OpenIB Programmer's Manual"
-
+.\" -*- nroff -*-
+.\"
+.TH IBV_GET_CQ_EVENT 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual"
 .SH "NAME"
 ibv_get_cq_event, ibv_ack_cq_events \- get and acknowledge completion queue (CQ) events
 
@@ -15,15 +16,16 @@ ibv_get_cq_event, ibv_ack_cq_events \- get and acknowledge completion queue (CQ)
 
 .SH "DESCRIPTION"
 .B ibv_get_cq_event()
-get the next event from the completion event channel
+waits for the next completion event in the completion event channel
 .I channel\fR.
-Fill the arguemnt
+The argument
 .I cq
-with the CQ that got the event, and its context in
-.I cq_context\fR.
+is used to return the CQ that caused the event and
+.I cq_context
+is used to return the CQ's context.
 .PP
 .B ibv_ack_cq_events()
-acknowledge
+acknowledges
 .I nevents
 events on the CQ
 .I cq\fR.
@@ -39,22 +41,39 @@ All completion events that
 .B ibv_get_cq_event()
 returns must be acknowledged using
 .B ibv_ack_cq_events()\fR.
-To avoid races, destroying a CQ will wait for all completion events to be acknowledged; this guarntees a one-to-one 
-correspondence between acks and successful gets.
-
+To avoid races, destroying a CQ will wait for all completion events to
+be acknowledged; this guarantees a one-to-one correspondence between
+acks and successful gets.
+.PP
+Calling
+.B ibv_ack_cq_events()
+may be relatively expensive in the datapath, since it must take a
+mutex.  Therefore it may be better to amortize this cost by
+keeping a count of the number of events needing acknowledgement and
+acking several completion events in one call to
+.B ibv_ack_cq_events()\fR.
 .SH "EXAMPLES"
-The following code example demonstrates one possible way to work with completion events. It performs the following steps:
+The following code example demonstrates one possible way to work with
+completion events. It performs the following steps:
 .PP
 Stage I: Preparation
+.br
 1. Creates a CQ
+.br
 2. Requests for notification upon a new (first) completion event
 .PP
 Stage II: Completion Handling Routine
-3. Wait for the completion event
+.br
+3. Wait for the completion event and ack it
+.br
 4. Request for notification upon the next completion event
+.br
 5. Empty the CQ
 .PP
-Note that an extra event may be triggered without having a corresponding completion entry in the CQ. This occurs if a completion entry is added to the CQ between Step 4 and Step 5, and is then emptied (polled).
+Note that an extra event may be triggered without having a
+corresponding completion entry in the CQ.  This occurs if a completion
+entry is added to the CQ between Step 4 and Step 5, and the CQ is then
+emptied (polled) in Step 5.
 .PP
 .nf
 cq = ibv_create_cq(ctx, 1, ev_ctx, channel, 0);
@@ -74,13 +93,16 @@ if (ibv_req_notify_cq(cq, 0)) {
 \&.
 .PP
 /* Wait for the completion event */
-if (ibv_get_cq_event(ctx->channel, &ev_cq, &ev_ctx)) {
+if (ibv_get_cq_event(channel, &ev_cq, &ev_ctx)) {
         fprintf(stderr, "Failed to get cq_event\en");
         return 1;
 }
+
+/* Ack the event */
+ibv_ack_cq_events(ev_cq, 1);
 .PP
 /* Request notification upon the next completion event */
-if (ibv_req_notify_cq(ctx->cq, 0)) {
+if (ibv_req_notify_cq(cq, 0)) {
         fprintf(stderr, "Couldn't request CQ notification\en");
         return 1;
 }
@@ -100,9 +122,53 @@ do {
 } while (ne);
 .fi
 
-.SH "CONFORMING TO"
-InfiniBand Architecture Specification, Release 1.2.
+The following code example demonstrates one possible way to work with
+completion events in non-blocking mode.  It performs the following
+steps:
+.PP
+1. Set the completion event channel to be non-blocked
+.br
+2. Poll the channel until there it has a completion event
+.br
+3. Get the completion event and ack it
+.PP
+.nf
+/* change the blocking mode of the completion channel */
+flags = fcntl(channel->fd, F_GETFL);
+rc = fcntl(channel->fd, F_SETFL, flags | O_NONBLOCK);
+if (rc < 0) {
+	fprintf(stderr, "Failed to change file descriptor of completion event channel\en");
+	return 1;
+}
+
 
+/*
+ * poll the channel until it has an event and sleep ms_timeout
+ * milliseconds between any iteration
+ */
+my_pollfd.fd      = channel->fd;
+my_pollfd.events  = POLLIN;
+my_pollfd.revents = 0;
+
+do {
+	rc = poll(&my_pollfd, 1, ms_timeout);
+} while (rc == 0);
+if (rc < 0) {
+	fprintf(stderr, "poll failed\en");
+	return 1;
+}
+ev_cq = cq;
+
+/* Wait for the completion event */
+if (ibv_get_cq_event(channel, &ev_cq, &ev_ctx)) {
+        fprintf(stderr, "Failed to get cq_event\en");
+        return 1;
+}
+
+/* Ack the event */
+ibv_ack_cq_events(ev_cq, 1);
+
+.fi
 .SH "SEE ALSO"
 .BR ibv_create_comp_channel (3),
 .BR ibv_create_cq (3),
diff --git a/man/ibv_modify_qp.3 b/man/ibv_modify_qp.3
index 264baf3..a870744 100644
--- a/man/ibv_modify_qp.3
+++ b/man/ibv_modify_qp.3
@@ -27,7 +27,7 @@ enum ibv_qp_state       qp_state;               /* Move the QP to this state */
 enum ibv_qp_state       cur_qp_state;           /* Assume this is the current QP state */
 enum ibv_mtu            path_mtu;               /* Path MTU (valid only for RC/UC QPs) */
 enum ibv_mig_state      path_mig_state;         /* Path migration state (valid if HCA supports APM) */
-uint32_t                qkey;                   /* QKey for the QP (valid only for UD QPs) */
+uint32_t                qkey;                   /* Q_Key for the QP (valid only for UD QPs) */
 uint32_t                rq_psn;                 /* PSN for receive queue (valid only for RC/UC QPs) */
 uint32_t                sq_psn;                 /* PSN for send queue (valid only for RC/UC QPs) */
 uint32_t                dest_qp_num;            /* Destination QP number (valid only for RC/UC QPs) */
@@ -35,8 +35,8 @@ int                     qp_access_flags;        /* Mask of enabled remote access
 struct ibv_qp_cap       cap;                    /* QP capabilities (valid if HCA supports QP resizing) */
 struct ibv_ah_attr      ah_attr;                /* Primary path address vector (valid only for RC/UC QPs) */
 struct ibv_ah_attr      alt_ah_attr;            /* Alternate path address vector (valid only for RC/UC QPs) */
-uint16_t                pkey_index;             /* Primary PKey index */
-uint16_t                alt_pkey_index;         /* Alternate PKey index */
+uint16_t                pkey_index;             /* Primary P_Key index */
+uint16_t                alt_pkey_index;         /* Alternate P_Key index */
 uint8_t                 en_sqd_async_notify;    /* Enable SQD.drained async notification (Valid only if qp_state is SQD) */
 uint8_t                 sq_draining;            /* Is the QP draining? Irrelevant for ibv_modify_qp() */
 uint8_t                 max_rd_atomic;          /* Number of outstanding RDMA reads & atomic operations on the destination QP (valid only for RC QPs) */
diff --git a/man/ibv_modify_srq.3 b/man/ibv_modify_srq.3
index 9118994..01375c9 100644
--- a/man/ibv_modify_srq.3
+++ b/man/ibv_modify_srq.3
@@ -48,7 +48,7 @@ If any of the modify attributes is invalid, none of the attributes will be modif
 .PP
 Not all devices support resizing SRQs.  To check if a device supports it, check if the
 .B IBV_DEVICE_SRQ_RESIZE
-bit is set in the device capabilties flags.
+bit is set in the device capabilities flags.
 .PP
 Modifying the srq_limit arms the SRQ to produce an
 .B IBV_EVENT_SRQ_LIMIT_REACHED
diff --git a/man/ibv_query_port.3 b/man/ibv_query_port.3
index a04ebb7..fd61eb9 100644
--- a/man/ibv_query_port.3
+++ b/man/ibv_query_port.3
@@ -31,8 +31,8 @@ enum ibv_mtu            active_mtu;     /* Actual MTU */
 int                     gid_tbl_len;    /* Length of source GID table */
 uint32_t                port_cap_flags; /* Port capabilities */
 uint32_t                max_msg_sz;     /* Maximum message size */
-uint32_t                bad_pkey_cntr;  /* Bad PKey counter */
-uint32_t                qkey_viol_cntr; /* QKey violation counter */
+uint32_t                bad_pkey_cntr;  /* Bad P_Key counter */
+uint32_t                qkey_viol_cntr; /* Q_Key violation counter */
 uint16_t                pkey_tbl_len;   /* Length of partition table */
 uint16_t                lid;            /* Base port LID */
 uint16_t                sm_lid;         /* SM LID */
diff --git a/man/ibv_query_qp.3 b/man/ibv_query_qp.3
index 43f9767..fd1f41d 100644
--- a/man/ibv_query_qp.3
+++ b/man/ibv_query_qp.3
@@ -32,7 +32,7 @@ enum ibv_qp_state       qp_state;            /* Current QP state */
 enum ibv_qp_state       cur_qp_state;        /* Current QP state - irrelevant for ibv_query_qp */
 enum ibv_mtu            path_mtu;            /* Path MTU (valid only for RC/UC QPs) */
 enum ibv_mig_state      path_mig_state;      /* Path migration state (valid if HCA supports APM) */
-uint32_t                qkey;                /* QKey of the QP (valid only for UD QPs) */
+uint32_t                qkey;                /* Q_Key of the QP (valid only for UD QPs) */
 uint32_t                rq_psn;              /* PSN for receive queue (valid only for RC/UC QPs) */
 uint32_t                sq_psn;              /* PSN for send queue (valid only for RC/UC QPs) */
 uint32_t                dest_qp_num;         /* Destination QP number (valid only for RC/UC QPs) */
@@ -40,8 +40,8 @@ int                     qp_access_flags;     /* Mask of enabled remote access op
 struct ibv_qp_cap       cap;                 /* QP capabilities */
 struct ibv_ah_attr      ah_attr;             /* Primary path address vector (valid only for RC/UC QPs) */
 struct ibv_ah_attr      alt_ah_attr;         /* Alternate path address vector (valid only for RC/UC QPs) */
-uint16_t                pkey_index;          /* Primary PKey index */
-uint16_t                alt_pkey_index;      /* Alternate PKey index */
+uint16_t                pkey_index;          /* Primary P_Key index */
+uint16_t                alt_pkey_index;      /* Alternate P_Key index */
 uint8_t                 en_sqd_async_notify; /* Enable SQD.drained async notification - irrelevant for ibv_query_qp */
 uint8_t                 sq_draining;         /* Is the QP draining? (Valid only if qp_state is SQD) */
 uint8_t                 max_rd_atomic;       /* Number of outstanding RDMA reads & atomic operations on the destination QP (valid only for RC QPs) */