1RDMA_GET_CM_EVENT(3)     Librdmacm Programmer's Manual    RDMA_GET_CM_EVENT(3)
2
3
4

NAME

6       rdma_get_cm_event - Retrieves the next pending communication event.
7

SYNOPSIS

9       #include <rdma/rdma_cma.h>
10
11       int   rdma_get_cm_event  (struct  rdma_event_channel  *channel,  struct
12       rdma_cm_event **event);
13

ARGUMENTS

15       channel     Event channel to check for events.
16
17       event       Allocated information about the next communication event.
18

DESCRIPTION

20       Retrieves a communication event.  If no events are pending, by default,
21       the call will block until an event is received.
22

RETURN VALUE

24       Returns  0  on success, or -1 on error.  If an error occurs, errno will
25       be set to indicate the failure reason.
26

NOTES

28       The default synchronous behavior of this routine can be changed by mod‐
29       ifying  the  file  descriptor  associated  with the given channel.  All
30       events  that   are   reported   must   be   acknowledged   by   calling
31       rdma_ack_cm_event.   Destruction  of  an  rdma_cm_id  will  block until
32       related events have been acknowledged.
33

EVENT DATA

35       Communication event details are returned in  the  rdma_cm_event  struc‐
36       ture.   This  structure is allocated by the rdma_cm and released by the
37       rdma_ack_cm_event routine.  Details of the rdma_cm_event structure  are
38       given below.
39
40       id          The  rdma_cm  identifier associated with the event.  If the
41                   event type is RDMA_CM_EVENT_CONNECT_REQUEST, then this ref‐
42                   erences a new id for that communication.
43
44       listen_id   For  RDMA_CM_EVENT_CONNECT_REQUEST event types, this refer‐
45                   ences the corresponding listening request identifier.
46
47       event       Specifies the type of communication event  which  occurred.
48                   See EVENT TYPES below.
49
50       status      Returns  any asynchronous error information associated with
51                   an event.  The status is zero if the operation was success‐
52                   ful,  otherwise  the status value is non-zero and is either
53                   set to an errno or a transport specific value.  For details
54                   on  transport  specific  status  values, see the event type
55                   information below.
56
57       param       Provides additional details based on  the  type  of  event.
58                   Users  should  select the conn or ud subfields based on the
59                   rdma_port_space  of  the  rdma_cm_id  associated  with  the
60                   event.  See UD EVENT DATA and CONN EVENT DATA below.
61

UD EVENT DATA

63       Event   parameters   related  to  unreliable  datagram  (UD)  services:
64       RDMA_PS_UDP  and  RDMA_PS_IPOIB.   The  UD  event  data  is  valid  for
65       RDMA_CM_EVENT_ESTABLISHED   and   RDMA_CM_EVENT_MULTICAST_JOIN  events,
66       unless stated otherwise.
67
68       private_data
69                   References  any   user-specified   data   associated   with
70                   RDMA_CM_EVENT_CONNECT_REQUEST  or RDMA_CM_EVENT_ESTABLISHED
71                   events.  The data referenced by  this  field  matches  that
72                   specified  by  the remote side when calling rdma_connect or
73                   rdma_accept.  This field is NULL  if  the  event  does  not
74                   include  private  data.   The  buffer  referenced  by  this
75                   pointer is deallocated when calling rdma_ack_cm_event.
76
77       private_data_len
78                   The size of the private data  buffer.   Users  should  note
79                   that the size of the private data buffer may be larger than
80                   the amount of private data sent by the  remote  side.   Any
81                   additional space in the buffer will be zeroed out.
82
83       ah_attr     Address  information needed to send data to the remote end‐
84                   point(s).  Users should use this structure when  allocating
85                   their address handle.
86
87       qp_num      QP number of the remote endpoint or multicast group.
88
89       qkey        QKey needed to send data to the remote endpoint(s).
90

CONN EVENT DATA

92       Event  parameters  related  to connected QP services: RDMA_PS_TCP.  The
93       connection  related  event  data  is   valid   for   RDMA_CM_EVENT_CON‐
94       NECT_REQUEST and RDMA_CM_EVENT_ESTABLISHED events, unless stated other‐
95       wise.
96
97       private_data
98                   References any  user-specified  data  associated  with  the
99                   event.   The  data  referenced  by  this field matches that
100                   specified by the remote side when calling  rdma_connect  or
101                   rdma_accept.   This  field  is  NULL  if the event does not
102                   include  private  data.   The  buffer  referenced  by  this
103                   pointer is deallocated when calling rdma_ack_cm_event.
104
105       private_data_len
106                   The  size  of  the  private data buffer.  Users should note
107                   that the size of the private data buffer may be larger than
108                   the  amount  of  private data sent by the remote side.  Any
109                   additional space in the buffer will be zeroed out.
110
111       responder_resources
112                   The number of responder resources requested of the  recipi‐
113                   ent.   This  field matches the initiator depth specified by
114                   the remote node when calling rdma_connect and rdma_accept.
115
116       initiator_depth
117                   The maximum number of outstanding RDMA  read/atomic  opera‐
118                   tions  that the recipient may have outstanding.  This field
119                   matches the responder resources  specified  by  the  remote
120                   node when calling rdma_connect and rdma_accept.
121
122       flow_control
123                   Indicates if hardware level flow control is provided by the
124                   sender.
125
126       retry_count For RDMA_CM_EVENT_CONNECT_REQUEST  events  only,  indicates
127                   the  number  of  times that the recipient should retry send
128                   operations.
129
130       rnr_retry_count
131                   The  number  of  times  that  the  recipient  should  retry
132                   receiver not ready (RNR) NACK errors.
133
134       srq         Specifies if the sender is using a shared-receive queue.
135
136       qp_num      Indicates the remote QP number for the connection.
137

EVENT TYPES

139       The following types of communication events may be reported.
140
141       RDMA_CM_EVENT_ADDR_RESOLVED
142              Address resolution (rdma_resolve_addr) completed successfully.
143
144       RDMA_CM_EVENT_ADDR_ERROR
145              Address resolution (rdma_resolve_addr) failed.
146
147       RDMA_CM_EVENT_ROUTE_RESOLVED
148              Route resolution (rdma_resolve_route) completed successfully.
149
150       RDMA_CM_EVENT_ROUTE_ERROR
151              Route resolution (rdma_resolve_route) failed.
152
153       RDMA_CM_EVENT_CONNECT_REQUEST
154              Generated  on  the passive side to notify the user of a new con‐
155              nection request.
156
157       RDMA_CM_EVENT_CONNECT_RESPONSE
158              Generated on the active side to notify the user of a  successful
159              response  to  a  connection  request.   It  is only generated on
160              rdma_cm_id's that do not have a QP associated with them.
161
162       RDMA_CM_EVENT_CONNECT_ERROR
163              Indicates that an error has occurred trying to  establish  or  a
164              connection.  May be generated on the active or passive side of a
165              connection.
166
167       RDMA_CM_EVENT_UNREACHABLE
168              Generated on the active side to notify the user that the  remote
169              server  is  not  reachable  or unable to respond to a connection
170              request.  If this event is generated in response to a UD QP res‐
171              olution  request  over  InfiniBand,  the event status field will
172              contain an errno, if negative, or the status result  carried  in
173              the IB CM SIDR REP message.
174
175       RDMA_CM_EVENT_REJECTED
176              Indicates  that a connection request or response was rejected by
177              the remote end point.  The event status field will  contain  the
178              transport  specific  reject  reason if available.  Under Infini‐
179              Band, this is the reject reason carried in the IB  CM  REJ  mes‐
180              sage.
181
182       RDMA_CM_EVENT_ESTABLISHED
183              Indicates that a connection has been established with the remote
184              end point.
185
186       RDMA_CM_EVENT_DISCONNECTED
187              The connection has been disconnected.
188
189       RDMA_CM_EVENT_DEVICE_REMOVAL
190              The local RDMA device associated with the  rdma_cm_id  has  been
191              removed.   Upon  receiving this event, the user must destroy the
192              related rdma_cm_id.
193
194       RDMA_CM_EVENT_MULTICAST_JOIN
195              The multicast  join  operation  (rdma_join_multicast)  completed
196              successfully.
197
198       RDMA_CM_EVENT_MULTICAST_ERROR
199              An  error  either occurred joining a multicast group, or, if the
200              group had already been joined, on an existing group.  The speci‐
201              fied  multicast  group  is  no  longer  accessible and should be
202              rejoined, if desired.
203
204       RDMA_CM_EVENT_ADDR_CHANGE
205              The network device associated with this ID through address reso‐
206              lution changed its HW address, eg following of bonding failover.
207              This event can serve as a hint for  applications  who  want  the
208              links  used  for  their  RDMA sessions to align with the network
209              stack.
210
211       RDMA_CM_EVENT_TIMEWAIT_EXIT
212              The QP associated with a  connection  has  exited  its  timewait
213              state  and is now ready to be re-used.  After a QP has been dis‐
214              connected, it is maintained in a timewait state to allow any  in
215              flight  packets  to  exit the network.  After the timewait state
216              has completed, the rdma_cm will report this event.
217

SEE ALSO

219       rdma_ack_cm_event(3),                     rdma_create_event_channel(3),
220       rdma_resolve_addr(3), rdma_resolve_route(3), rdma_connect(3), rdma_lis‐
221       ten(3), rdma_join_multicast(3), rdma_destroy_id(3), rdma_event_str(3)
222
223
224
225librdmacm                         2007-10-31              RDMA_GET_CM_EVENT(3)
Impressum