rdma_get_cm_event(3) — Linux manual page

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | RETURN VALUE | NOTES | EVENT DATA | UD EVENT DATA | CONN EVENT DATA | EVENT TYPES | SEE ALSO | COLOPHON

RDMA_GET_CM_EVENT(3)  Librdmacm Programmer's Manual RDMA_GET_CM_EVENT(3)

NAME         top

       rdma_get_cm_event - Retrieves the next pending communication
       event.

SYNOPSIS         top

       #include <rdma/rdma_cma.h>

       int rdma_get_cm_event (struct rdma_event_channel *channel, struct
       rdma_cm_event **event);

ARGUMENTS         top

       channel     Event channel to check for events.

       event       Allocated information about the next communication
                   event.

DESCRIPTION         top

       Retrieves a communication event.  If no events are pending, by
       default, the call will block until an event is received.

RETURN VALUE         top

       Returns 0 on success, or -1 on error.  If an error occurs, errno
       will be set to indicate the failure reason.

NOTES         top

       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         top

       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 a negative 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         top

       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         top

       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         top

       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         top

       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)

COLOPHON         top

       This page is part of the rdma-core (RDMA Core Userspace Libraries
       and Daemons) project.  Information about the project can be found
       at ⟨https://github.com/linux-rdma/rdma-core⟩.  If you have a bug
       report for this manual page, send it to
       [email protected].  This page was obtained from the
       project's upstream Git repository
       ⟨https://github.com/linux-rdma/rdma-core.git⟩ on 2024-06-14.  (At
       that time, the date of the most recent commit that was found in
       the repository was 2024-06-10.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       [email protected]

librdmacm                      2007-10-31           RDMA_GET_CM_EVENT(3)

Pages that refer to this page: rdma_accept(3)rdma_ack_cm_event(3)rdma_connect(3)rdma_create_event_channel(3)rdma_destroy_event_channel(3)rdma_disconnect(3)rdma_event_str(3)rdma_get_dst_port(3)rdma_get_request(3)rdma_join_multicast(3)rdma_join_multicast_ex(3)rdma_listen(3)rdma_migrate_id(3)rdma_reject(3)rdma_resolve_addr(3)rdma_resolve_route(3)rdma_cm(7)