rdma_get_cm_event

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, the call is blocked until an event is received.

Notes:
  • You can change the file descriptor that is associated with the channel and change the default synchronous behavior of the rdma_get_cm_event operation.
  • All events that are reported must be acknowledged by running the rdma_ack_cm_event operation.
  • The rdma_cm_id identifier is not destroyed until the related events are acknowledged.

Parameters

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

Return Values

Item Description
0 On success.
-1 Error, see errno. If an error occurs, the errno indicates the reason for failure.

Event Data

The details of the communication event are returned to the rdma_cm_event function. This structure is allocated by the rdma_cm identifier and released by the rdma_ack_cm_event operation. The rdma_cm_event function has the following parameters:
Item Description
id Specifies the rdma_cm identifier that is associated with the event. If RDMA_CM_EVENT_CONNECT_REQUEST is the event type, then for communication a new ID is referenced by the function.
listen_id Specifies the corresponding listening request identifier for the RDMA_CM_EVENT_CONNECT_REQUEST event type.
event Specifies the type of communication event that occurred.
status Returns 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. You must select the conn subfield based on the rdma_port_space function of the rdma_cm_id identifier that is associated with the event.

Connection Event Data

The event parameters are related to the connected queue pair (QP) services and the RDMA_PS_TCP event type. The connection related event data is valid for RDMA_CM_EVENT_CONNECT_REQUEST and RDMA_CM_EVENT_ESTABLISHED event types.
Item Description
private_data References any user-specified data that is associated with the event. The data referenced by this field matches the value specified by the remote side when running the rdma_connect or rdma_accept functions. If the event does not include any private data, the private_data field is NULL. The buffer referenced by this pointer is deallocated when running the rdma_ack_cm_event function.
private_data_len Specifies the size of the private data buffer.
Note: 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 that is requested by the recipient. The responder_resources field must match the initiator depth specified by the remote node when running the rdma_connect and rdma_accept functions.
initiator_dept Specifies the maximum number of outstanding RDMA read operations that the recipient holds. The initiator_dept field must match the responder resources specified by the remote node when running the rdma_connect and rdma_accept functions.
flow_control Indicates whether the hardware level flow control is provided by the sender. This value is specific to the InfiniBand architecture.
retry_count Indicates the number of times that the recipient must retry a send operation specific to the RDMA_CM_EVENT_CONNECT_REQUEST events. This value is specific to the InfiniBand architecture.
rnr_retry_count Indicates the number of times that the recipient must retry receiver not ready (RNR) NACK errors. This value is specific to the InfiniBand architecture.
srq Specifies whether 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 are reported.
Item Description
RDMA_CM_EVENT_ADDR_RESOLVED Indicates that 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 generated on rdma_cm_id identifiers without a QP associated with them.
RDMA_CM_EVENT_CONNECT_ERROR Indicates that an error has occurred trying to establish a connection. this event type can 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. This option is 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 contains 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 contains the transport specific reject reason if available. For InfiniBand, this event carries the reason for rejection in the IB CM REJ message.
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 identifier is removed. When you receive this event, you must destroy the associatedrdma_cm_id identifier.
RDMA_CM_EVENT_TIMEWAIT_EXIT Indicates that the QP associated with a connection has exited its timewait state and is 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 identifier reports this event.