Ubuntu Manpage: rdma_get_cm_event - Retrieves the next pending communication event.

Provided by: librdmacm-dev_1.0.21-1_amd64

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.