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                       int             port_num;       /* port number that got the event */
28               } element;
29               enum ibv_event_type     event_type;     /* type of the event */
30       };
31
32       One member of the  element  union  will  be  valid,  depending  on  the
33       event_type member of the structure.  event_type will be one of the fol‐
34       lowing events:
35
36       QP events:
37
38       IBV_EVENT_QP_FATAL  Error occurred on a QP and it transitioned to error
39       state
40
41       IBV_EVENT_QP_REQ_ERR  Invalid Request Local Work Queue Error
42
43       IBV_EVENT_QP_ACCESS_ERR  Local access violation error
44
45       IBV_EVENT_COMM_EST  Communication was established on a QP
46
47       IBV_EVENT_SQ_DRAINED  Send Queue was drained of outstanding messages in
48       progress
49
50       IBV_EVENT_PATH_MIG  A connection has migrated to the alternate path
51
52       IBV_EVENT_PATH_MIG_ERR  A connection failed to migrate to the alternate
53       path
54
55       IBV_EVENT_QP_LAST_WQE_REACHED  Last WQE Reached on a QP associated with
56       an SRQ
57
58       CQ events:
59
60       IBV_EVENT_CQ_ERR  CQ is in error (CQ overrun)
61
62       SRQ events:
63
64       IBV_EVENT_SRQ_ERR  Error occurred on an SRQ
65
66       IBV_EVENT_SRQ_LIMIT_REACHED  SRQ limit was reached
67
68       Port events:
69
70       IBV_EVENT_PORT_ACTIVE  Link became active on a port
71
72       IBV_EVENT_PORT_ERR  Link became unavailable on a port
73
74       IBV_EVENT_LID_CHANGE  LID was changed on a port
75
76       IBV_EVENT_PKEY_CHANGE  P_Key table was changed on a port
77
78       IBV_EVENT_SM_CHANGE  SM was changed on a port
79
80       IBV_EVENT_CLIENT_REREGISTER  SM sent a CLIENT_REREGISTER request  to  a
81       port
82
83       IBV_EVENT_GID_CHANGE  GID table was changed on a port
84
85       CA events:
86
87       IBV_EVENT_DEVICE_FATAL  CA is in FATAL state
88
89       ibv_ack_async_event() acknowledge the async event event.
90

RETURN VALUE

92       ibv_get_async_event() returns 0 on success, and -1 on error.
93
94       ibv_ack_async_event() returns no value.
95

NOTES

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

EXAMPLES

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

AUTHORS

155       Dotan Barak <dotanba@gmail.com>
156
157
158
159libibverbs                        2006-10-31            IBV_GET_ASYNC_EVENT(3)