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 The default synchronous behavior of this routine can be changed by mod‐
25 ifying the file descriptor associated with the given channel. All
26 events that are reported must be acknowledged by calling
27 rdma_ack_cm_event. Destruction of an rdma_cm_id will block until
28 related events have been acknowledged.
29
31 Communication event details are returned in the rdma_cm_event struc‐
32 ture. This structure is allocated by the rdma_cm and released by the
33 rdma_ack_cm_event routine. Details of the rdma_cm_event structure are
34 given below.
35 id The rdma_cm identifier associated with the event. If the
37 event type is RDMA_CM_EVENT_CONNECT_REQUEST, then this ref‐
38 erences a new id for that communication.
39 listen_id For RDMA_CM_EVENT_CONNECT_REQUEST event types, this refer‐
41 ences the corresponding listening request identifier.
42 event Specifies the type of communication event which occurred.
44 See EVENT TYPES below.
45 status Returns any asynchronous error information associated with
47 an event. The status is zero unless the corresponding
48 operation failed.
49 param Provides additional details based on the type of event.
51 Users should select the conn or ud subfields based on the
52 rdma_port_space of the rdma_cm_id associated with the
53 event. See UD EVENT DATA and CONN EVENT DATA below.
54
56 Event parameters related to unreliable datagram (UD) services:
57 RDMA_PS_UDP and RDMA_PS_IPOIB. The UD event data is valid for
58 RDMA_CM_EVENT_ESTABLISHED and RDMA_CM_EVENT_MULTICAST_JOIN events,
59 unless stated otherwise.
60 private_data
62 References any user-specified data associated with
63 RDMA_CM_EVENT_CONNECT_REQUEST or RDMA_CM_EVENT_ESTABLISHED
64 events. The data referenced by this field matches that
65 specified by the remote side when calling rdma_connect or
66 rdma_accept. This field is NULL if the event does not
67 include private data. The buffer referenced by this
68 pointer is deallocated when calling rdma_ack_cm_event.
69 private_data_len
71 The size of the private data buffer. Users should note
72 that the size of the private data buffer may be larger than
73 the amount of private data sent by the remote side. Any
74 additional space in the buffer will be zeroed out.
75 ah_attr Address information needed to send data to the remote end‐
77 point(s). Users should use this structure when allocating
78 their address handle.
79 qp_num QP number of the remote endpoint or multicast group.
81 qkey QKey needed to send data to the remote endpoint(s).
83
85 Event parameters related to connected QP services: RDMA_PS_TCP. The
86 connection related event data is valid for RDMA_CM_EVENT_CON‐
87 NECT_REQUEST and RDMA_CM_EVENT_ESTABLISHED events, unless stated other‐
88 wise.
89 private_data
91 References any user-specified data associated with the
92 event. The data referenced by this field matches that
93 specified by the remote side when calling rdma_connect or
94 rdma_accept. This field is NULL if the event does not
95 include private data. The buffer referenced by this
96 pointer is deallocated when calling rdma_ack_cm_event.
97 private_data_len
99 The size of the private data buffer. Users should note
100 that the size of the private data buffer may be larger than
101 the amount of private data sent by the remote side. Any
102 additional space in the buffer will be zeroed out.
103 responder_resources
105 The number of responder resources requested of the recipi‐
106 ent. This field matches the initiator depth specified by
107 the remote node when calling rdma_connect and rdma_accept.
108 initiator_depth
110 The maximum number of outstanding RDMA read/atomic opera‐
111 tions that the recipient may have outstanding. This field
112 matches the responder resources specified by the remote
113 node when calling rdma_connect and rdma_accept.
114 flow_control
116 Indicates if hardware level flow control is provided by the
117 sender.
118 retry_count For RDMA_CM_EVENT_CONNECT_REQUEST events only, indicates
120 the number of times that the recipient should retry send
121 operations.
122 rnr_retry_count
124 The number of times that the recipient should retry
125 receiver not ready (RNR) NACK errors.
126 srq Specifies if the sender is using a shared-receive queue.
128 qp_num Indicates the remote QP number for the connection.
130
132 The following types of communication events may be reported.
133 RDMA_CM_EVENT_ADDR_RESOLVED
135 Address resolution (rdma_resolve_addr) completed successfully.
136 RDMA_CM_EVENT_ADDR_ERROR
138 Address resolution (rdma_resolve_addr) failed.
139 RDMA_CM_EVENT_ROUTE_RESOLVED
141 Route resolution (rdma_resolve_route) completed successfully.
142 RDMA_CM_EVENT_ROUTE_ERROR
144 Route resolution (rdma_resolve_route) failed.
145 RDMA_CM_EVENT_CONNECT_REQUEST
147 Generated on the passive side to notify the user of a new con‐
148 nection request.
149 RDMA_CM_EVENT_CONNECT_RESPONSE
151 Generated on the active side to notify the user of a successful
152 response to a connection request. It is only generated on
153 rdma_cm_id's that do not have a QP associated with them.
154 RDMA_CM_EVENT_CONNECT_ERROR
156 Indicates that an error has occurred trying to establish or a
157 connection. May be generated on the active or passive side of a
158 connection.
159 RDMA_CM_EVENT_UNREACHABLE
161 Generated on the active side to notify the user that the remote
162 server is not reachable or unable to respond to a connection
163 request.
164 RDMA_CM_EVENT_REJECTED
166 Indicates that a connection request or response was rejected by
167 the remote end point.
168 RDMA_CM_EVENT_ESTABLISHED
170 Indicates that a connection has been established with the remote
171 end point.
172 RDMA_CM_EVENT_DISCONNECTED
174 The connection has been disconnected.
175 RDMA_CM_EVENT_DEVICE_REMOVAL
177 The local RDMA device associated with the rdma_cm_id has been
178 removed. Upon receiving this event, the user must destroy the
179 related rdma_cm_id.
180 RDMA_CM_EVENT_MULTICAST_JOIN
182 The multicast join operation (rdma_join_multicast) completed
183 successfully.
184 RDMA_CM_EVENT_MULTICAST_ERROR
186 An error either occurred joining a multicast group, or, if the
187 group had already been joined, on an existing group. The speci‐
188 fied multicast group is no longer accessible and should be
189 rejoined, if desired.
190 RDMA_CM_EVENT_ADDR_CHANGE
192 The network device associated with this ID through address reso‐
193 lution changed its HW address, eg following of bonding failover.
194 This event can serve as a hint for applications who want the
195 links used for their RDMA sessions to align with the network
196 stack.
197 RDMA_CM_EVENT_TIMEWAIT_EXIT
199 The QP associated with a connection has exited its timewait
200 state and is now ready to be re-used. After a QP has been dis‐
201 connected, it is maintained in a timewait state to allow any in
202 flight packets to exit the network. After the timewait state
203 has completed, the rdma_cm will report this event.
204
206 rdma_ack_cm_event(3), rdma_create_event_channel(3),
207 rdma_resolve_addr(3), rdma_resolve_route(3), rdma_connect(3), rdma_lis‐
208 ten(3), rdma_join_multicast(3), rdma_destroy_id(3), rdma_event_str(3)
209librdmacm 2007-10-31 RDMA_GET_CM_EVENT(3)