1RDMA_GET_CM_EVENT(3) Librdmacm Programmer's Manual RDMA_GET_CM_EVENT(3)
2
6 rdma_get_cm_event - Retrieves the next pending communication event.
7
9 #include <rdma/rdma_cma.h>
10 int rdma_get_cm_event (struct rdma_event_channel *channel, struct
12 rdma_cm_event **event);
13
15 channel Event channel to check for events.
16 event Allocated information about the next communication event.
18
20 Retrieves a communication event. If no events are pending, by default,
21 the call will block until an event is received.
22
24 Returns 0 on success, or -1 on error. If an error occurs, errno will
25 be set to indicate the failure reason.
26
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 re‐
32 lated events have been acknowledged.
33
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 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 listen_id For RDMA_CM_EVENT_CONNECT_REQUEST event types, this refer‐
45 ences the corresponding listening request identifier.
46 event Specifies the type of communication event which occurred.
48 See EVENT TYPES below.
49 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 a negative errno or a transport specific value. For
54 details on transport specific status values, see the event
55 type information below.
56 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
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, un‐
66 less stated otherwise.
67 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 in‐
74 clude private data. The buffer referenced by this pointer
75 is deallocated when calling rdma_ack_cm_event.
76 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 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 qp_num QP number of the remote endpoint or multicast group.
88 qkey QKey needed to send data to the remote endpoint(s).
90
92 Event parameters related to connected QP services: RDMA_PS_TCP. The
93 connection related event data is valid for RDMA_CM_EVENT_CONNECT_RE‐
94 QUEST and RDMA_CM_EVENT_ESTABLISHED events, unless stated otherwise.
95 private_data
97 References any user-specified data associated with the
98 event. The data referenced by this field matches that
99 specified by the remote side when calling rdma_connect or
100 rdma_accept. This field is NULL if the event does not in‐
101 clude private data. The buffer referenced by this pointer
102 is deallocated when calling rdma_ack_cm_event.
103 private_data_len
105 The size of the private data buffer. Users should note
106 that the size of the private data buffer may be larger than
107 the amount of private data sent by the remote side. Any
108 additional space in the buffer will be zeroed out.
109 responder_resources
111 The number of responder resources requested of the recipi‐
112 ent. This field matches the initiator depth specified by
113 the remote node when calling rdma_connect and rdma_accept.
114 initiator_depth
116 The maximum number of outstanding RDMA read/atomic opera‐
117 tions that the recipient may have outstanding. This field
118 matches the responder resources specified by the remote
119 node when calling rdma_connect and rdma_accept.
120 flow_control
122 Indicates if hardware level flow control is provided by the
123 sender.
124 retry_count For RDMA_CM_EVENT_CONNECT_REQUEST events only, indicates
126 the number of times that the recipient should retry send
127 operations.
128 rnr_retry_count
130 The number of times that the recipient should retry re‐
131 ceiver not ready (RNR) NACK errors.
132 srq Specifies if the sender is using a shared-receive queue.
134 qp_num Indicates the remote QP number for the connection.
136
138 The following types of communication events may be reported.
139 RDMA_CM_EVENT_ADDR_RESOLVED
141 Address resolution (rdma_resolve_addr) completed successfully.
142 RDMA_CM_EVENT_ADDR_ERROR
144 Address resolution (rdma_resolve_addr) failed.
145 RDMA_CM_EVENT_ROUTE_RESOLVED
147 Route resolution (rdma_resolve_route) completed successfully.
148 RDMA_CM_EVENT_ROUTE_ERROR
150 Route resolution (rdma_resolve_route) failed.
151 RDMA_CM_EVENT_CONNECT_REQUEST
153 Generated on the passive side to notify the user of a new con‐
154 nection request.
155 RDMA_CM_EVENT_CONNECT_RESPONSE
157 Generated on the active side to notify the user of a successful
158 response to a connection request. It is only generated on
159 rdma_cm_id's that do not have a QP associated with them.
160 RDMA_CM_EVENT_CONNECT_ERROR
162 Indicates that an error has occurred trying to establish or a
163 connection. May be generated on the active or passive side of a
164 connection.
165 RDMA_CM_EVENT_UNREACHABLE
167 Generated on the active side to notify the user that the remote
168 server is not reachable or unable to respond to a connection re‐
169 quest. If this event is generated in response to a UD QP reso‐
170 lution request over InfiniBand, the event status field will con‐
171 tain an errno, if negative, or the status result carried in the
172 IB CM SIDR REP message.
173 RDMA_CM_EVENT_REJECTED
175 Indicates that a connection request or response was rejected by
176 the remote end point. The event status field will contain the
177 transport specific reject reason if available. Under Infini‐
178 Band, this is the reject reason carried in the IB CM REJ mes‐
179 sage.
180 RDMA_CM_EVENT_ESTABLISHED
182 Indicates that a connection has been established with the remote
183 end point.
184 RDMA_CM_EVENT_DISCONNECTED
186 The connection has been disconnected.
187 RDMA_CM_EVENT_DEVICE_REMOVAL
189 The local RDMA device associated with the rdma_cm_id has been
190 removed. Upon receiving this event, the user must destroy the
191 related rdma_cm_id.
192 RDMA_CM_EVENT_MULTICAST_JOIN
194 The multicast join operation (rdma_join_multicast) completed
195 successfully.
196 RDMA_CM_EVENT_MULTICAST_ERROR
198 An error either occurred joining a multicast group, or, if the
199 group had already been joined, on an existing group. The speci‐
200 fied multicast group is no longer accessible and should be re‐
201 joined, if desired.
202 RDMA_CM_EVENT_ADDR_CHANGE
204 The network device associated with this ID through address reso‐
205 lution changed its HW address, eg following of bonding failover.
206 This event can serve as a hint for applications who want the
207 links used for their RDMA sessions to align with the network
208 stack.
209 RDMA_CM_EVENT_TIMEWAIT_EXIT
211 The QP associated with a connection has exited its timewait
212 state and is now ready to be re-used. After a QP has been dis‐
213 connected, it is maintained in a timewait state to allow any in
214 flight packets to exit the network. After the timewait state
215 has completed, the rdma_cm will report this event.
216
218 rdma_ack_cm_event(3), rdma_create_event_channel(3), rdma_re‐
219 solve_addr(3), rdma_resolve_route(3), rdma_connect(3), rdma_listen(3),
220 rdma_join_multicast(3), rdma_destroy_id(3), rdma_event_str(3)
221librdmacm 2007-10-31 RDMA_GET_CM_EVENT(3)