rdma_get_cm

Retrieves the next pending communication event.

Syntax

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

Description

The rdma_get_cm_event function retrieves a communication event. If no events are pending, by default, the call blocks until an event is received.

Notes:

You can modify the file descriptor associated with the given channel and change the default synchronous behavior of the rdma_get_cm_event routine.
All events that are reported must be acknowledged by calling rdma_ack_cm_event.
Destruction of an rdma_cm_id is blocked until related events are acknowledged.

Parameters

channel	Specifies the event channel to check for events.
event	Specifies the allocated information about the next communication event.

Return Values

0	On success.
-1	Error, see errno.
-EINVAL	The error occurs if channel or event is NULL.
-ENODATA	The write operation on channel->fd failed.
-ENOMEM	There is not enough space to allocate by malloc.
-ENODEV	Unable to get RDMA device

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	Specifies the rdma_cm identifier associated with the event. If the event type is RDMA_CM_EVENT_CONNECT_REQUEST, then the id references a new id for that communication.
listen_id	Specifies the corresponding listening request identifier for the RDMA_CM_EVENT_CONNECT_REQUEST event types.
event	Specifies the type of communication event that occurred. See Event Types.
status	Returns any asynchronous error information associated with an event. The status is zero unless the corresponding operation fails.
param	Provides additional details based on the type of event. You must select the conn subfield based on the rdma_port_space of the rdma_cm_id associated with the event. See Conn Event Data.

Conn Event Data

Event parameters are related to the 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.

private_data	References any user-specified data associated with the event. The data referenced by this field matches the value specified by the remote side when calling rdma_connect or rdma_accept. The private_data 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	Specifies the size of the private data buffer. You must note that the size of the private data buffer might be larger than the amount of private data sent by the remote side. Any additional space in the buffer is zeroed out.
responder_resources	Specifies the number of responder resources requested of the recipient. The responder_resources field matches the initiator depth specified by the remote node when calling rdma_connect and rdma_accept.
initiator_dept	Specifies the maximum number of outstanding RDMA read operations that the recipient might have. The initiator_dept field matches the responder resources specified by the remote node when calling rdma_connect and rdma_accept.
flow_control	Indicates if the hardware level flow control is provided by the sender (specific to the InfiniBand architecture).
retry_count	Indicates the number of times that the recipient must retry a send operation that is specific to RDMA_CM_EVENT_CONNECT_REQUEST events (specific to the InfiniBand architecture).
rnr_retry_count	Indicates the number of times that the recipient must retry receiver not ready (RNR) NACK errors (specific to the InfiniBand architecture).
srq	Specifies if the sender is using a shared-receive queue. Currently the field is not supported.
qp_num	Indicates the remote QP number for the connection.

Event Types

The following types of communication events might be reported.

RDMA_CM_EVENT_ADDR_RESOLVED	Indicates the address resolution (rdma_resolve_addr) completed successfully.
RDMA_CM_EVENT_ADDR_ERROR	Indicates that the address resolution (rdma_resolve_addr) failed.
RDMA_CM_EVENT_ROUTE_RESOLVED	Indicates that the route resolution (rdma_resolve_route) completed successfully.
RDMA_CM_EVENT_ROUTE_ERROR	Indicates that the route resolution (rdma_resolve_route) failed.
RDMA_CM_EVENT_CONNECT_REQUEST	Indicates that there is a new connection request on the passive side.
RDMA_CM_EVENT_CONNECT_RESPONSE	Indicates that the there is a successful response to a connection request on the active side. It is only generated on rdma_cm_ids that do not have a QP associated with them.
RDMA_CM_EVENT_CONNECT_ERROR	Indicates that an error has occurred trying to establish a connection. Might be generated on the active or passive side of a connection.
RDMA_CM_EVENT_UNREACHABLE	Indicates that the remote server is not reachable or unable to respond to a connection request on the active side.
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 is established with the remote end point.
RDMA_CM_EVENT_DISCONNECTED	Indicates that the connection is disconnected.
RDMA_CM_EVENT_DEVICE_REMOVAL	Indicates that the local RDMA device associated with the rdma_cm_id is removed. Upon receiving this event, you must destroy the related rdma_cm_id.
RDMA_CM_EVENT_TIMEWAIT_EXIT	Indicates that the QP associated with a connection has exited its timewait state and is now ready to be reused. After a QP is disconnected, it is maintained in a timewait state to allow any in flight packets to exit the network. After the timewait state is complete, the rdma_cm reports this event.