contrib/ofed/librdmacm/man/rdma_cm.7

   1 .TH "RDMA_CM" 7 "2008-01-02" "librdmacm" "Librdmacm Programmer's Manual" librdmacm
   2 .SH NAME
   3 rdma_cm \- RDMA communication manager.
   4 .SH SYNOPSIS
   5 .B "#include <rdma/rdma_cma.h>"
   6 .SH "DESCRIPTION"
   7 Used to establish communication over RDMA transports.
   8 .SH "NOTES"
   9 The RDMA CM is a communication manager used to setup reliable, connected
  10 and unreliable datagram data transfers.  It provides an RDMA transport
  11 neutral interface for establishing connections.  The API is based on sockets,
  12 but adapted for queue pair (QP) based semantics: communication must be
  13 over a specific RDMA device, and data transfers are message based.
  14 .P
  15 The RDMA CM only provides the communication management (connection setup /
  16 teardown) portion of an RDMA API.  It works in conjunction with the verbs
  17 API defined by the libibverbs library.  The libibverbs library provides the
  18 interfaces needed to send and receive data.
  19 .SH "CLIENT OPERATION"
  20 This section provides a general overview of the basic operation for the active,
  21 or client, side of communication.  A general connection flow would be:
  22 .IP rdma_create_event_channel
  23 create channel to receive events
  24 .IP rdma_create_id
  25 allocate an rdma_cm_id, this is conceptually similar to a socket
  26 .IP rdma_resolve_addr
  27 obtain a local RDMA device to reach the remote address
  28 .IP rdma_get_cm_event
  29 wait for RDMA_CM_EVENT_ADDR_RESOLVED event
  30 .IP rdma_ack_cm_event
  31 ack event
  32 .IP rdma_create_qp
  33 allocate a QP for the communication
  34 .IP rdma_resolve_route
  35 determine the route to the remote address
  36 .IP rdma_get_cm_event
  37 wait for RDMA_CM_EVENT_ROUTE_RESOLVED event
  38 .IP rdma_ack_cm_event
  39 ack event
  40 .IP rdma_connect
  41 connect to the remote server
  42 .IP rdma_get_cm_event
  43 wait for RDMA_CM_EVENT_ESTABLISHED event
  44 .IP rdma_ack_cm_event
  45 ack event
  46 .P
  47 Perform data transfers over connection
  48 .IP rdma_disconnect
  49 tear-down connection
  50 .IP rdma_get_cm_event
  51 wait for RDMA_CM_EVENT_DISCONNECTED event
  52 .IP rdma_ack_cm_event
  53 ack event
  54 .IP rdma_destroy_qp
  55 destroy the QP
  56 .IP rdma_destroy_id
  57 release the rdma_cm_id
  58 .IP rdma_destroy_event_channel
  59 release the event channel
  60 .P
  61 An almost identical process is used to setup unreliable datagram (UD)
  62 communication between nodes.  No actual connection is formed between QPs
  63 however, so disconnection is not needed.
  64 .P
  65 Although this example shows the client initiating the disconnect, either side
  66 of a connection may initiate the disconnect.
  67 .SH "SERVER OPERATION"
  68 This section provides a general overview of the basic operation for the passive,
  69 or server, side of communication.  A general connection flow would be:
  70 .IP rdma_create_event_channel
  71 create channel to receive events
  72 .IP rdma_create_id
  73 allocate an rdma_cm_id, this is conceptually similar to a socket
  74 .IP rdma_bind_addr
  75 set the local port number to listen on
  76 .IP rdma_listen
  77 begin listening for connection requests
  78 .IP rdma_get_cm_event
  79 wait for RDMA_CM_EVENT_CONNECT_REQUEST event with a new rdma_cm_id
  80 .IP rdma_create_qp
  81 allocate a QP for the communication on the new rdma_cm_id
  82 .IP rdma_accept
  83 accept the connection request
  84 .IP rdma_ack_cm_event
  85 ack event
  86 .IP rdma_get_cm_event
  87 wait for RDMA_CM_EVENT_ESTABLISHED event
  88 .IP rdma_ack_cm_event
  89 ack event
  90 .P
  91 Perform data transfers over connection
  92 .IP rdma_get_cm_event
  93 wait for RDMA_CM_EVENT_DISCONNECTED event
  94 .IP rdma_ack_cm_event
  95 ack event
  96 .IP rdma_disconnect
  97 tear-down connection
  98 .IP rdma_destroy_qp
  99 destroy the QP
 100 .IP rdma_destroy_id
 101 release the connected rdma_cm_id
 102 .IP rdma_destroy_id
 103 release the listening rdma_cm_id
 104 .IP rdma_destroy_event_channel
 105 release the event channel
 106 .SH "RETURN CODES"
 107 .IP "=  0"
 108 success
 109 .IP "= -1"
 110 error - see errno for more details
 111 .P
 112 Librdmacm functions return 0 to indicate success, and a -1 return value
 113 to indicate failure.  If a function operates asynchronously, a return value of 0
 114 means that the operation was successfully started.  The operation could still
 115 complete in error; users should check the status of the related event.  If the
 116 return value is -1, then errno will contain additional information
 117 regarding the reason for the failure.
 118 .P
 119 Prior versions of the library would return -errno and not set errno for some cases
 120 related to ENOMEM, ENODEV, ENODATA, EINVAL, and EADDRNOTAVAIL codes. Applications
 121 that want to check these codes and have compatability with prior library versions
 122 must manually set errno to the negative of the return code if it is < -1.
 123 .SH "SEE ALSO"
 124 rdma_create_event_channel(3), rdma_get_cm_event(3), rdma_create_id(3),
 125 rdma_resolve_addr(3), rdma_bind_addr(3), rdma_create_qp(3),
 126 rdma_resolve_route(3), rdma_connect(3), rdma_listen(3), rdma_accept(3),
 127 rdma_reject(3), rdma_join_multicast(3), rdma_leave_multicast(3), rdma_notify(3),
 128 rdma_ack_cm_event(3), rdma_disconnect(3), rdma_destroy_qp(3), rdma_destroy_id(3),
 129 rdma_destroy_event_channel(3), rdma_get_devices(3), rdma_free_devices(3),
 130 rdma_get_peer_addr(3), rdma_get_local_addr(3),
 131 rdma_get_dst_port(3), rdma_get_src_port(3), rdma_set_option(3)
 132 ucmatose(1), udaddy(1), mckey(1), rping(1)