contrib/ofed/libibverbs/man/ibv_get_cq_event.3

   1 .\" -*- nroff -*-
   2 .\"
   3 .TH IBV_GET_CQ_EVENT 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual"
   4 .SH "NAME"
   5 ibv_get_cq_event, ibv_ack_cq_events \- get and acknowledge completion queue (CQ) events
   6
   7 .SH "SYNOPSIS"
   8 .nf
   9 .B #include <infiniband/verbs.h>
  10 .sp
  11 .BI "int ibv_get_cq_event(struct ibv_comp_channel " "*channel" ,
  12 .BI "                     struct ibv_cq " "**cq" ", void " "**cq_context" );
  13 .sp
  14 .BI "void ibv_ack_cq_events(struct ibv_cq " "*cq" ", unsigned int " "nevents" );
  15 .fi
  16
  17 .SH "DESCRIPTION"
  18 .B ibv_get_cq_event()
  19 waits for the next completion event in the completion event channel
  20 .I channel\fR.
  21 Fills the arguments
  22 .I cq
  23 with the CQ that got the event and
  24 .I cq_context
  25 with the CQ's context\fR.
  26 .PP
  27 .B ibv_ack_cq_events()
  28 acknowledges
  29 .I nevents
  30 events on the CQ
  31 .I cq\fR.
  32
  33 .SH "RETURN VALUE"
  34 .B ibv_get_cq_event()
  35 returns 0 on success, and \-1 on error.
  36 .PP
  37 .B ibv_ack_cq_events()
  38 returns no value.
  39 .SH "NOTES"
  40 All completion events that
  41 .B ibv_get_cq_event()
  42 returns must be acknowledged using
  43 .B ibv_ack_cq_events()\fR.
  44 To avoid races, destroying a CQ will wait for all completion events to
  45 be acknowledged; this guarantees a one-to-one correspondence between
  46 acks and successful gets.
  47 .PP
  48 Calling
  49 .B ibv_ack_cq_events()
  50 may be relatively expensive in the datapath, since it must take a
  51 mutex.  Therefore it may be better to amortize this cost by
  52 keeping a count of the number of events needing acknowledgement and
  53 acking several completion events in one call to
  54 .B ibv_ack_cq_events()\fR.
  55 .SH "EXAMPLES"
  56 The following code example demonstrates one possible way to work with
  57 completion events. It performs the following steps:
  58 .PP
  59 Stage I: Preparation
  60 .br
  61 1. Creates a CQ
  62 .br
  63 2. Requests for notification upon a new (first) completion event
  64 .PP
  65 Stage II: Completion Handling Routine
  66 .br
  67 3. Wait for the completion event and ack it
  68 .br
  69 4. Request for notification upon the next completion event
  70 .br
  71 5. Empty the CQ
  72 .PP
  73 Note that an extra event may be triggered without having a
  74 corresponding completion entry in the CQ.  This occurs if a completion
  75 entry is added to the CQ between Step 4 and Step 5, and the CQ is then
  76 emptied (polled) in Step 5.
  77 .PP
  78 .nf
  79 cq = ibv_create_cq(ctx, 1, ev_ctx, channel, 0);
  80 if (!cq) {
  81         fprintf(stderr, "Failed to create CQ\en");
  82         return 1;
  83 }
  84 .PP
  85 /* Request notification before any completion can be created */
  86 if (ibv_req_notify_cq(cq, 0)) {
  87         fprintf(stderr, "Couldn't request CQ notification\en");
  88         return 1;
  89 }
  90 .PP
  91 \&.
  92 \&.
  93 \&.
  94 .PP
  95 /* Wait for the completion event */
  96 if (ibv_get_cq_event(channel, &ev_cq, &ev_ctx)) {
  97         fprintf(stderr, "Failed to get cq_event\en");
  98         return 1;
  99 }
 100
 101 /* Ack the event */
 102 ibv_ack_cq_events(ev_cq, 1);
 103 .PP
 104 /* Request notification upon the next completion event */
 105 if (ibv_req_notify_cq(ev_cq, 0)) {
 106         fprintf(stderr, "Couldn't request CQ notification\en");
 107         return 1;
 108 }
 109 .PP
 110 /* Empty the CQ: poll all of the completions from the CQ (if any exist) */
 111 do {
 112         ne = ibv_poll_cq(cq, 1, &wc);
 113         if (ne < 0) {
 114                 fprintf(stderr, "Failed to poll completions from the CQ\en");
 115                 return 1;
 116         }
 117
 118         /* there may be an extra event with no completion in the CQ */
 119         if (ne == 0)
 120                 continue;
 121 .PP
 122         if (wc.status != IBV_WC_SUCCESS) {
 123                 fprintf(stderr, "Completion with status 0x%x was found\en", wc.status);
 124                 return 1;
 125         }
 126 } while (ne);
 127 .fi
 128
 129 The following code example demonstrates one possible way to work with
 130 completion events in non-blocking mode.  It performs the following
 131 steps:
 132 .PP
 133 1. Set the completion event channel to be non-blocked
 134 .br
 135 2. Poll the channel until there it has a completion event
 136 .br
 137 3. Get the completion event and ack it
 138 .PP
 139 .nf
 140 /* change the blocking mode of the completion channel */
 141 flags = fcntl(channel->fd, F_GETFL);
 142 rc = fcntl(channel->fd, F_SETFL, flags | O_NONBLOCK);
 143 if (rc < 0) {
 144         fprintf(stderr, "Failed to change file descriptor of completion event channel\en");
 145         return 1;
 146 }
 147
 148
 149 /*
 150  * poll the channel until it has an event and sleep ms_timeout
 151  * milliseconds between any iteration
 152  */
 153 my_pollfd.fd      = channel->fd;
 154 my_pollfd.events  = POLLIN;
 155 my_pollfd.revents = 0;
 156
 157 do {
 158         rc = poll(&my_pollfd, 1, ms_timeout);
 159 } while (rc == 0);
 160 if (rc < 0) {
 161         fprintf(stderr, "poll failed\en");
 162         return 1;
 163 }
 164 ev_cq = cq;
 165
 166 /* Wait for the completion event */
 167 if (ibv_get_cq_event(channel, &ev_cq, &ev_ctx)) {
 168         fprintf(stderr, "Failed to get cq_event\en");
 169         return 1;
 170 }
 171
 172 /* Ack the event */
 173 ibv_ack_cq_events(ev_cq, 1);
 174
 175 .fi
 176 .SH "SEE ALSO"
 177 .BR ibv_create_comp_channel (3),
 178 .BR ibv_create_cq (3),
 179 .BR ibv_req_notify_cq (3),
 180 .BR ibv_poll_cq (3)
 181
 182 .SH "AUTHORS"
 183 .TP
 184 Dotan Barak
 185 .RI < dotanb@mellanox.co.il >