ibv_get_async_event(3)

1IBV_GET_ASYNC_EVENT(3)  Libibverbs Programmer's Manual  IBV_GET_ASYNC_EVENT(3)
2
3
4

NAME

6       ibv_get_async_event, ibv_ack_async_event - get or acknowledge asynchro‐
7       nous events
8

SYNOPSIS

10       #include <infiniband/verbs.h>
11
12       int ibv_get_async_event(struct ibv_context *context,
13                               struct ibv_async_event *event);
14
15       void ibv_ack_async_event(struct ibv_async_event *event);
16

DESCRIPTION

18       ibv_get_async_event() waits for the next async event of the RDMA device
19       context  context  and returns it through the pointer event, which is an
20       ibv_async_event struct, as defined in <infiniband/verbs.h>.
21
22       struct ibv_async_event {
23               union {
24                       struct ibv_cq  *cq;             /* CQ that got the event */
25                       struct ibv_qp  *qp;             /* QP that got the event */
26                       struct ibv_srq *srq;            /* SRQ that got the event */
27                       struct ibv_wq  *wq;             /* WQ that got the event */
28                       int             port_num;       /* port number that got the event */
29               } element;
30               enum ibv_event_type     event_type;     /* type of the event */
31       };
32
33       One member of the  element  union  will  be  valid,  depending  on  the
34       event_type member of the structure.  event_type will be one of the fol‐
35       lowing events:
36
37       QP events:
38
39       IBV_EVENT_QP_FATAL  Error occurred on a QP and it transitioned to error
40       state
41
42       IBV_EVENT_QP_REQ_ERR  Invalid Request Local Work Queue Error
43
44       IBV_EVENT_QP_ACCESS_ERR  Local access violation error
45
46       IBV_EVENT_COMM_EST  Communication was established on a QP
47
48       IBV_EVENT_SQ_DRAINED  Send Queue was drained of outstanding messages in
49       progress
50
51       IBV_EVENT_PATH_MIG  A connection has migrated to the alternate path
52
53       IBV_EVENT_PATH_MIG_ERR  A connection failed to migrate to the alternate
54       path
55
56       IBV_EVENT_QP_LAST_WQE_REACHED  Last WQE Reached on a QP associated with
57       an SRQ
58
59       CQ events:
60
61       IBV_EVENT_CQ_ERR  CQ is in error (CQ overrun)
62
63       SRQ events:
64
65       IBV_EVENT_SRQ_ERR  Error occurred on an SRQ
66
67       IBV_EVENT_SRQ_LIMIT_REACHED  SRQ limit was reached
68
69       WQ events:
70
71       IBV_EVENT_WQ_FATAL  Error occurred on a WQ and it transitioned to error
72       state
73
74       Port events:
75
76       IBV_EVENT_PORT_ACTIVE  Link became active on a port
77
78       IBV_EVENT_PORT_ERR  Link became unavailable on a port
79
80       IBV_EVENT_LID_CHANGE  LID was changed on a port
81
82       IBV_EVENT_PKEY_CHANGE  P_Key table was changed on a port
83
84       IBV_EVENT_SM_CHANGE  SM was changed on a port
85
86       IBV_EVENT_CLIENT_REREGISTER   SM  sent a CLIENT_REREGISTER request to a
87       port
88
89       IBV_EVENT_GID_CHANGE  GID table was changed on a port
90
91       CA events:
92
93       IBV_EVENT_DEVICE_FATAL  CA is in FATAL state
94
95       ibv_ack_async_event() acknowledge the async event event.
96

RETURN VALUE

98       ibv_get_async_event() returns 0 on success, and -1 on error.
99
100       ibv_ack_async_event() returns no value.
101

NOTES

103       All async events that ibv_get_async_event() returns  must  be  acknowl‐
104       edged  using  ibv_ack_async_event().  To avoid races, destroying an ob‐
105       ject (CQ, SRQ or QP) will wait for all affiliated events for the object
106       to be acknowledged; this avoids an application retrieving an affiliated
107       event after the corresponding object has already been destroyed.
108
109       ibv_get_async_event() is a blocking function.  If multiple threads call
110       this function simultaneously, then when an async event occurs, only one
111       thread will receive it, and it is not possible to predict which  thread
112       will receive it.
113

EXAMPLES

115       The  following  code example demonstrates one possible way to work with
116       async events in non-blocking mode.  It performs the following steps:
117
118       1. Set the async events queue work mode to be non-blocked
119       2. Poll the queue until it has an async event
120       3. Get the async event and ack it
121
122       /* change the blocking mode of the async event queue */
123       flags = fcntl(ctx->async_fd, F_GETFL);
124       rc = fcntl(ctx->async_fd, F_SETFL, flags | O_NONBLOCK);
125       if (rc < 0) {
126               fprintf(stderr, "Failed to change file descriptor of async event queue\n");
127               return 1;
128       }
129
130       /*
131        * poll the queue until it has an event and sleep ms_timeout
132        * milliseconds between any iteration
133        */
134       my_pollfd.fd      = ctx->async_fd;
135       my_pollfd.events  = POLLIN;
136       my_pollfd.revents = 0;
137
138       do {
139               rc = poll(&my_pollfd, 1, ms_timeout);
140       } while (rc == 0);
141       if (rc < 0) {
142               fprintf(stderr, "poll failed\n");
143               return 1;
144       }
145
146       /* Get the async event */
147       if (ibv_get_async_event(ctx, &async_event)) {
148               fprintf(stderr, "Failed to get async_event\n");
149               return 1;
150       }
151
152       /* Ack the event */
153       ibv_ack_async_event(&async_event);
154
155

AUTHORS

160       Dotan Barak <dotanba@gmail.com>
161
162
163
164libibverbs                        2006-10-31            IBV_GET_ASYNC_EVENT(3)