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.
RETURN VALUE¶
Returns 0 on success, or -1 on error. If an error occurs, errno will be set to
indicate the failure reason.
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 if the operation was successful, otherwise
the status value is non-zero and is either set to an errno or a transport
specific value. For details on transport specific status values, see the
event type information below.
- 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. If this event is generated in response to a UD QP resolution
request over InfiniBand, the event status field will contain an errno, if
negative, or the status result carried in the IB CM SIDR REP message.
- RDMA_CM_EVENT_REJECTED
- Indicates that a connection request or response was
rejected by the remote end point. The event status field will contain the
transport specific reject reason if available. Under InfiniBand, this is
the reject reason carried in the IB CM REJ message.
- 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)