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