NAME
rdma_get_cm_event - Retrieves the next pending communication event.
SYNOPSIS
#include <rdma/rdma_cma.h>
int rdma_get_cm_event (struct rdma_event_channel *channel, struct
rdma_cm_event **event);
ARGUMENTS
channel Event channel to check for events.
event Allocated information about the next communication event.
DESCRIPTION
Retrieves a communication event. If no events are pending, by default,
the call will block until an event is received.
NOTES
The default synchronous behavior of this routine can be changed by
modifying the file descriptor associated with the given channel. All
events that are reported must be acknowledged by calling
rdma_ack_cm_event. Destruction of an rdma_cm_id will block until
related events have been acknowledged.
EVENT DATA
Communication event details are returned in the rdma_cm_event
structure. This structure is allocated by the rdma_cm and released by
the rdma_ack_cm_event routine. Details of the rdma_cm_event structure
are given below.
id The rdma_cm identifier associated with the event. If the
event type is RDMA_CM_EVENT_CONNECT_REQUEST, then this
references a new id for that communication.
listen_id For RDMA_CM_EVENT_CONNECT_REQUEST event types, this
references the corresponding listening request identifier.
event Specifies the type of communication event which occurred.
See EVENT TYPES below.
status Returns any asynchronous error information associated with
an event. The status is zero unless the corresponding
operation failed.
param Provides additional details based on the type of event.
Users should select the conn or ud subfields based on the
rdma_port_space of the rdma_cm_id associated with the
event. See UD EVENT DATA and CONN EVENT DATA below.
UD EVENT DATA
Event parameters related to unreliable datagram (UD) services:
RDMA_PS_UDP and RDMA_PS_IPOIB. The UD event data is valid for
RDMA_CM_EVENT_ESTABLISHED and RDMA_CM_EVENT_MULTICAST_JOIN events,
unless stated otherwise.
private_data
References any user-specified data associated with
RDMA_CM_EVENT_CONNECT_REQUEST or RDMA_CM_EVENT_ESTABLISHED
events. The data referenced by this field matches that
specified by the remote side when calling rdma_connect or
rdma_accept. This field is NULL if the event does not
include private data. The buffer referenced by this
pointer is deallocated when calling rdma_ack_cm_event.
private_data_len
The size of the private data buffer. Users should note
that the size of the private data buffer may be larger than
the amount of private data sent by the remote side. Any
additional space in the buffer will be zeroed out.
ah_attr Address information needed to send data to the remote
endpoint(s). Users should use this structure when
allocating their address handle.
qp_num QP number of the remote endpoint or multicast group.
qkey QKey needed to send data to the remote endpoint(s).
CONN EVENT DATA
Event parameters related to connected QP services: RDMA_PS_TCP. The
connection related event data is valid for
RDMA_CM_EVENT_CONNECT_REQUEST and RDMA_CM_EVENT_ESTABLISHED events,
unless stated otherwise.
private_data
References any user-specified data associated with the
event. The data referenced by this field matches that
specified by the remote side when calling rdma_connect or
rdma_accept. This field is NULL if the event does not
include private data. The buffer referenced by this
pointer is deallocated when calling rdma_ack_cm_event.
private_data_len
The size of the private data buffer. Users should note
that the size of the private data buffer may be larger than
the amount of private data sent by the remote side. Any
additional space in the buffer will be zeroed out.
responder_resources
The number of responder resources requested of the
recipient. This field matches the initiator depth
specified by the remote node when calling rdma_connect and
rdma_accept.
initiator_depth
The maximum number of outstanding RDMA read/atomic
operations that the recipient may have outstanding. This
field matches the responder resources specified by the
remote node when calling rdma_connect and rdma_accept.
flow_control
Indicates if hardware level flow control is provided by the
sender.
retry_count For RDMA_CM_EVENT_CONNECT_REQUEST events only, indicates
the number of times that the recipient should retry send
operations.
rnr_retry_count
The number of times that the recipient should retry
receiver not ready (RNR) NACK errors.
srq Specifies if the sender is using a shared-receive queue.
qp_num Indicates the remote QP number for the connection.
EVENT TYPES
The following types of communication events may be reported.
RDMA_CM_EVENT_ADDR_RESOLVED
Address resolution (rdma_resolve_addr) completed successfully.
RDMA_CM_EVENT_ADDR_ERROR
Address resolution (rdma_resolve_addr) failed.
RDMA_CM_EVENT_ROUTE_RESOLVED
Route resolution (rdma_resolve_route) completed successfully.
RDMA_CM_EVENT_ROUTE_ERROR
Route resolution (rdma_resolve_route) failed.
RDMA_CM_EVENT_CONNECT_REQUEST
Generated on the passive side to notify the user of a new
connection request.
RDMA_CM_EVENT_CONNECT_RESPONSE
Generated on the active side to notify the user of a successful
response to a connection request. It is only generated on
rdma_cm_id’s that do not have a QP associated with them.
RDMA_CM_EVENT_CONNECT_ERROR
Indicates that an error has occurred trying to establish or a
connection. May be generated on the active or passive side of a
connection.
RDMA_CM_EVENT_UNREACHABLE
Generated on the active side to notify the user that the remote
server is not reachable or unable to respond to a connection
request.
RDMA_CM_EVENT_REJECTED
Indicates that a connection request or response was rejected by
the remote end point.
RDMA_CM_EVENT_ESTABLISHED
Indicates that a connection has been established with the remote
end point.
RDMA_CM_EVENT_DISCONNECTED
The connection has been disconnected.
RDMA_CM_EVENT_DEVICE_REMOVAL
The local RDMA device associated with the rdma_cm_id has been
removed. Upon receiving this event, the user must destroy the
related rdma_cm_id.
RDMA_CM_EVENT_MULTICAST_JOIN
The multicast join operation (rdma_join_multicast) completed
successfully.
RDMA_CM_EVENT_MULTICAST_ERROR
An error either occurred joining a multicast group, or, if the
group had already been joined, on an existing group. The
specified multicast group is no longer accessible and should be
rejoined, if desired.
RDMA_CM_EVENT_ADDR_CHANGE
The network device associated with this ID through address
resolution changed its HW address, eg following of bonding
failover. This event can serve as a hint for applications who
want the links used for their RDMA sessions to align with the
network stack.
RDMA_CM_EVENT_TIMEWAIT_EXIT
The QP associated with a connection has exited its timewait
state and is now ready to be re-used. After a QP has been
disconnected, it is maintained in a timewait state to allow any
in flight packets to exit the network. After the timewait state
has completed, the rdma_cm will report this event.
SEE ALSO
rdma_ack_cm_event(3), rdma_create_event_channel(3),
rdma_resolve_addr(3), rdma_resolve_route(3), rdma_connect(3),
rdma_listen(3), rdma_join_multicast(3), rdma_destroy_id(3),
rdma_event_str(3)