contrib/ofed/libibverbs/man/ibv_get_async_event.3

   1 .\" -*- nroff -*-
   2 .\"
   3 .TH IBV_GET_ASYNC_EVENT 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual"
   4 .SH "NAME"
   5 ibv_get_async_event, ibv_ack_async_event \- get or acknowledge asynchronous events
   6 .SH "SYNOPSIS"
   7 .nf
   8 .B #include <infiniband/verbs.h>
   9 .sp
  10 .BI "int ibv_get_async_event(struct ibv_context " "*context" ,
  11 .BI "                        struct ibv_async_event " "*event" );
  12 .sp
  13 .BI "void ibv_ack_async_event(struct ibv_async_event " "*event" );
  14 .fi
  15 .SH "DESCRIPTION"
  16 .B ibv_get_async_event()
  17 waits for the next async event of the RDMA device context
  18 .I context
  19 and returns it through the pointer
  20 .I event\fR,
  21 which is an ibv_async_event struct, as defined in <infiniband/verbs.h>.
  22 .PP
  23 .nf
  24 struct ibv_async_event {
  25 .in +8
  26 union {
  27 .in +8
  28 struct ibv_cq  *cq;             /* CQ that got the event */
  29 struct ibv_qp  *qp;             /* QP that got the event */
  30 struct ibv_srq *srq;            /* SRQ that got the event */
  31 int             port_num;       /* port number that got the event */
  32 .in -8
  33 } element;
  34 enum ibv_event_type     event_type;     /* type of the event */
  35 .in -8
  36 };
  37 .fi
  38 .PP
  39 One member of the element union will be valid, depending on the
  40 event_type member of the structure.  event_type will be one of the
  41 following events:
  42 .PP
  43 .I QP events:
  44 .TP
  45 .B IBV_EVENT_QP_FATAL \fR Error occurred on a QP and it transitioned to error state
  46 .TP
  47 .B IBV_EVENT_QP_REQ_ERR \fR Invalid Request Local Work Queue Error
  48 .TP
  49 .B IBV_EVENT_QP_ACCESS_ERR \fR Local access violation error
  50 .TP
  51 .B IBV_EVENT_COMM_EST \fR Communication was established on a QP
  52 .TP
  53 .B IBV_EVENT_SQ_DRAINED \fR Send Queue was drained of outstanding messages in progress
  54 .TP
  55 .B IBV_EVENT_PATH_MIG \fR A connection has migrated to the alternate path
  56 .TP
  57 .B IBV_EVENT_PATH_MIG_ERR \fR A connection failed to migrate to the alternate path
  58 .TP
  59 .B IBV_EVENT_QP_LAST_WQE_REACHED \fR Last WQE Reached on a QP associated with an SRQ
  60 .PP
  61 .I CQ events:
  62 .TP
  63 .B IBV_EVENT_CQ_ERR \fR CQ is in error (CQ overrun)
  64 .PP
  65 .I SRQ events:
  66 .TP
  67 .B IBV_EVENT_SRQ_ERR \fR Error occurred on an SRQ
  68 .TP
  69 .B IBV_EVENT_SRQ_LIMIT_REACHED \fR SRQ limit was reached
  70 .PP
  71 .I Port events:
  72 .TP
  73 .B IBV_EVENT_PORT_ACTIVE \fR Link became active on a port
  74 .TP
  75 .B IBV_EVENT_PORT_ERR \fR Link became unavailable on a port
  76 .TP
  77 .B IBV_EVENT_LID_CHANGE \fR LID was changed on a port
  78 .TP
  79 .B IBV_EVENT_PKEY_CHANGE \fR P_Key table was changed on a port
  80 .TP
  81 .B IBV_EVENT_SM_CHANGE \fR SM was changed on a port
  82 .TP
  83 .B IBV_EVENT_CLIENT_REREGISTER \fR SM sent a CLIENT_REREGISTER request to a port
  84 .PP
  85 .I CA events:
  86 .TP
  87 .B IBV_EVENT_DEVICE_FATAL \fR CA is in FATAL state
  88 .PP
  89 .B ibv_ack_async_event()
  90 acknowledge the async event
  91 .I event\fR.
  92 .SH "RETURN VALUE"
  93 .B ibv_get_async_event()
  94 returns 0 on success, and \-1 on error.
  95 .PP
  96 .B ibv_ack_async_event()
  97 returns no value.
  98 .SH "NOTES"
  99 All async events that
 100 .B ibv_get_async_event()
 101 returns must be acknowledged using
 102 .B ibv_ack_async_event()\fR.
 103 To avoid races, destroying an object (CQ, SRQ or QP) will wait for all
 104 affiliated events for the object to be acknowledged; this avoids an
 105 application retrieving an affiliated event after the corresponding
 106 object has already been destroyed.
 107 .PP
 108 .B ibv_get_async_event()
 109 is a blocking function.  If multiple threads call this function
 110 simultaneously, then when an async event occurs, only one thread will
 111 receive it, and it is not possible to predict which thread will
 112 receive it.
 113 .SH "EXAMPLES"
 114 The following code example demonstrates one possible way to work with async events in non-blocking mode.
 115 It performs the following steps:
 116 .PP
 117 1. Set the async events queue work mode to be non-blocked
 118 .br
 119 2. Poll the queue until it has an async event
 120 .br
 121 3. Get the async event and ack it
 122 .PP
 123 .nf
 124 /* change the blocking mode of the async event queue */
 125 flags = fcntl(ctx->async_fd, F_GETFL);
 126 rc = fcntl(ctx->async_fd, F_SETFL, flags | O_NONBLOCK);
 127 if (rc < 0) {
 128         fprintf(stderr, "Failed to change file descriptor of async event queue\en");
 129         return 1;
 130 }
 131
 132 /*
 133  * poll the queue until it has an event and sleep ms_timeout
 134  * milliseconds between any iteration
 135  */
 136 my_pollfd.fd      = ctx->async_fd;
 137 my_pollfd.events  = POLLIN;
 138 my_pollfd.revents = 0;
 139
 140 do {
 141         rc = poll(&my_pollfd, 1, ms_timeout);
 142 } while (rc == 0);
 143 if (rc < 0) {
 144         fprintf(stderr, "poll failed\en");
 145         return 1;
 146 }
 147
 148 /* Get the async event */
 149 if (ibv_get_async_event(ctx, &async_event)) {
 150         fprintf(stderr, "Failed to get async_event\en");
 151         return 1;
 152 }
 153
 154 /* Ack the event */
 155 ibv_ack_async_event(&async_event);
 156
 157 .fi
 158 .SH "SEE ALSO"
 159 .BR ibv_open_device (3)
 160 .SH "AUTHORS"
 161 .TP
 162 Dotan Barak <dotanb@mellanox.co.il>