Go to main content

man pages section 3: Library Interfaces and Headers

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

rdma_get_cm_event (3)

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);

Description

Librdmacm Programmer's Manual                             RDMA_GET_CM_EVENT(3)



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.


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+-----------------------+
       |ATTRIBUTE TYPE |   ATTRIBUTE VALUE     |
       +---------------+-----------------------+
       |Availability   | network/open-fabrics  |
       +---------------+-----------------------+
       |Stability      | Pass-through volatile |
       +---------------+-----------------------+

NOTES
       The default synchronous behavior of this routine can be changed by mod-
       ifying  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.

       Source code for open source software components in Oracle  Solaris  can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-
       code-downloads.html.

       This    software    was    built    from    source     available     at
       https://github.com/oracle/solaris-userland.    The  original  community
       source   was   downloaded   from    ['https://www.openfabrics.org/down-
       loads/ibutils/ibutils-1.5.7-0.2.gbd7e502.tar.gz', 'https://www.openfab-
       rics.org/downloads/libibverbs/libibverbs-1.1.8.tar.gz',
       'https://www.openfabrics.org/downloads/libmlx4/libmlx4-1.0.6.tar.gz',
       'https://www.openfabrics.org/downloads/libsdp/lib-
       sdp-1.1.108-0.15.gd7fdb72.tar.gz',   'https://www.openfabrics.org/down-
       loads/management/infiniband-diags-1.6.5.tar.gz',  'https://www.openfab-
       rics.org/downloads/management/libibmad-1.3.12.tar.gz',
       'https://www.openfabrics.org/downloads/management/libibu-
       mad-1.3.10.2.tar.gz',    'https://www.openfabrics.org/downloads/manage-
       ment/opensm-3.3.19.tar.gz',          'https://www.openfabrics.org/down-
       loads/perftest/perftest-1.3.0-0.42.gf350d3d.tar.gz', 'https://www.open-
       fabrics.org/downloads/qperf/qperf-0.4.9.tar.gz',  'https://www.openfab-
       rics.org/downloads/rdmacm/librdmacm-1.0.21.tar.gz',  'https://www.open-
       fabrics.org/downloads/rds-tools/rds-tools-2.0.4.tar.gz'].

       Further information about this software can be found on the open source
       community website at http://www.openfabrics.org/.

EVENT DATA
       Communication  event  details  are returned in the rdma_cm_event struc-
       ture.  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 ref-
                   erences a new id for that communication.

       listen_id   For RDMA_CM_EVENT_CONNECT_REQUEST event types, this  refer-
                   ences 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 success-
                   ful, 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  end-
                   point(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_CON-
       NECT_REQUEST and RDMA_CM_EVENT_ESTABLISHED events, unless stated other-
       wise.

       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 recipi-
                   ent.  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 opera-
                   tions 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  con-
              nection 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 res-
              olution 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  Infini-
              Band,  this  is  the reject reason carried in the IB CM REJ mes-
              sage.

       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 speci-
              fied 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 reso-
              lution 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  dis-
              connected,  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_lis-
       ten(3), rdma_join_multicast(3), rdma_destroy_id(3), rdma_event_str(3)




librdmacm                         2007-10-31              RDMA_GET_CM_EVENT(3)