3 .TH IBV_GET_ASYNC_EVENT 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual"
5 ibv_get_async_event, ibv_ack_async_event \- get or acknowledge asynchronous events
8 .B #include <infiniband/verbs.h>
10 .BI "int ibv_get_async_event(struct ibv_context " "*context" ,
11 .BI " struct ibv_async_event " "*event" );
13 .BI "void ibv_ack_async_event(struct ibv_async_event " "*event" );
16 .B ibv_get_async_event()
17 waits for the next async event of the RDMA device context
19 and returns it through the pointer
21 which is an ibv_async_event struct, as defined in <infiniband/verbs.h>.
24 struct ibv_async_event {
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 */
34 enum ibv_event_type event_type; /* type of the event */
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
45 .B IBV_EVENT_QP_FATAL \fR Error occurred on a QP and it transitioned to error state
47 .B IBV_EVENT_QP_REQ_ERR \fR Invalid Request Local Work Queue Error
49 .B IBV_EVENT_QP_ACCESS_ERR \fR Local access violation error
51 .B IBV_EVENT_COMM_EST \fR Communication was established on a QP
53 .B IBV_EVENT_SQ_DRAINED \fR Send Queue was drained of outstanding messages in progress
55 .B IBV_EVENT_PATH_MIG \fR A connection has migrated to the alternate path
57 .B IBV_EVENT_PATH_MIG_ERR \fR A connection failed to migrate to the alternate path
59 .B IBV_EVENT_QP_LAST_WQE_REACHED \fR Last WQE Reached on a QP associated with an SRQ
63 .B IBV_EVENT_CQ_ERR \fR CQ is in error (CQ overrun)
67 .B IBV_EVENT_SRQ_ERR \fR Error occurred on an SRQ
69 .B IBV_EVENT_SRQ_LIMIT_REACHED \fR SRQ limit was reached
73 .B IBV_EVENT_PORT_ACTIVE \fR Link became active on a port
75 .B IBV_EVENT_PORT_ERR \fR Link became unavailable on a port
77 .B IBV_EVENT_LID_CHANGE \fR LID was changed on a port
79 .B IBV_EVENT_PKEY_CHANGE \fR P_Key table was changed on a port
81 .B IBV_EVENT_SM_CHANGE \fR SM was changed on a port
83 .B IBV_EVENT_CLIENT_REREGISTER \fR SM sent a CLIENT_REREGISTER request to a port
87 .B IBV_EVENT_DEVICE_FATAL \fR CA is in FATAL state
89 .B ibv_ack_async_event()
90 acknowledge the async event
93 .B ibv_get_async_event()
94 returns 0 on success, and \-1 on error.
96 .B ibv_ack_async_event()
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.
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
114 The following code example demonstrates one possible way to work with async events in non-blocking mode.
115 It performs the following steps:
117 1. Set the async events queue work mode to be non-blocked
119 2. Poll the queue until it has an async event
121 3. Get the async event and ack it
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);
128 fprintf(stderr, "Failed to change file descriptor of async event queue\en");
133 * poll the queue until it has an event and sleep ms_timeout
134 * milliseconds between any iteration
136 my_pollfd.fd = ctx->async_fd;
137 my_pollfd.events = POLLIN;
138 my_pollfd.revents = 0;
141 rc = poll(&my_pollfd, 1, ms_timeout);
144 fprintf(stderr, "poll failed\en");
148 /* Get the async event */
149 if (ibv_get_async_event(ctx, &async_event)) {
150 fprintf(stderr, "Failed to get async_event\en");
155 ibv_ack_async_event(&async_event);
159 .BR ibv_open_device (3)
162 Dotan Barak <dotanb@mellanox.co.il>