[ofa-general] [PATCH] libibverbs-manpages updates
Dotan Barak
dotanb at dev.mellanox.co.il
Tue Mar 27 09:39:31 PDT 2007
Spelling mistakes were fixed.
All PKey / QKey instances were replaced with P_Key / Q_Key.
Added non-blocking mode examples to ibv_get_async_event and ibv_get_cq_event.
Name of variables were fixed in ibv_get_cq_event first example.
Signed-off-by: Dotan Barak <dotanb at mellanox.co.il>
---
diff --git a/man/ibv_get_async_event.3 b/man/ibv_get_async_event.3
index bb6d068..bbddf7c 100644
--- a/man/ibv_get_async_event.3
+++ b/man/ibv_get_async_event.3
@@ -110,6 +110,46 @@ 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
+2. Poll the queue until it has an async event
+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;
+}
+/* Wait for 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..c0c346a 100644
--- a/man/ibv_get_cq_event.3
+++ b/man/ibv_get_cq_event.3
@@ -15,9 +15,9 @@ 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
+wait for the next completion event in the completion event channel
.I channel\fR.
-Fill the arguemnt
+Fill the argument
.I cq
with the CQ that got the event, and its context in
.I cq_context\fR.
@@ -39,18 +39,21 @@ 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
+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()
+is expensive and it is advised to minimize the number of calls to this verb by acking several completion events in one time.
.SH "EXAMPLES"
-The following code example demonstrates one possible way to work with completion events. It performs the following steps:
+1) The following code example demonstrates one possible way to work with completion events. It performs the following steps:
.PP
Stage I: Preparation
1. Creates a CQ
2. Requests for notification upon a new (first) completion event
.PP
Stage II: Completion Handling Routine
-3. Wait for the completion event
+3. Wait for the completion event and ack it
4. Request for notification upon the next completion event
5. Empty the CQ
.PP
@@ -74,13 +77,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,6 +106,47 @@ do {
} while (ne);
.fi
+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
+2. Poll the channel until there it has a completion event
+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 "CONFORMING TO"
InfiniBand Architecture Specification, Release 1.2.
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) */
More information about the general
mailing list