contrib/ofed/librdmacm/man/rdma_cm.7

   1 .\" Licensed under the OpenIB.org BSD license (FreeBSD Variant) - See COPYING.md
   2 .TH "RDMA_CM" 7 "2010-07-19" "librdmacm" "Librdmacm Programmer's Manual" librdmacm
   3 .SH NAME
   4 rdma_cm \- RDMA communication manager.
   5 .SH SYNOPSIS
   6 .B "#include <rdma/rdma_cma.h>"
   7 .SH "DESCRIPTION"
   8 Used to establish communication over RDMA transports.
   9 .SH "NOTES"
  10 The RDMA CM is a communication manager used to setup reliable, connected
  11 and unreliable datagram data transfers.  It provides an RDMA transport
  12 neutral interface for establishing connections.  The API concepts are
  13 based on sockets, but adapted for queue pair (QP) based semantics:
  14 communication must be over a specific RDMA device, and data transfers
  15 are message based.
  16 .P
  17 The RDMA CM can control both the QP and communication management (connection setup /
  18 teardown) portions of an RDMA API, or only the communication management
  19 piece.  It works in conjunction with the verbs
  20 API defined by the libibverbs library.  The libibverbs library provides the
  21 underlying interfaces needed to send and receive data.
  22 .P
  23 The RDMA CM can operate asynchronously or synchronously.  The mode of
  24 operation is controlled by the user through the use of the rdma_cm event channel
  25 parameter in specific calls.  If an event channel is provided, an rdma_cm identifier
  26 will report its event data (results of connecting, for example), on that channel.
  27 If a channel is not provided, then all rdma_cm operations for the selected
  28 rdma_cm identifier will block until they complete.
  29 .SH "RDMA VERBS"
  30 The rdma_cm supports the full range of verbs available through the libibverbs
  31 library and interfaces.  However, it also provides wrapper functions for some
  32 of the more commonly used verbs funcationality.  The full set of abstracted
  33 verb calls are:
  34 .P
  35 rdma_reg_msgs  - register an array of buffers for sending and receiving
  36 .P
  37 rdma_reg_read  - registers a buffer for RDMA read operations
  38 .P
  39 rdma_reg_write - registers a buffer for RDMA write operations
  40 .P
  41 rdma_dereg_mr  - deregisters a memory region
  42 .P
  43 rdma_post_recv  - post a buffer to receive a message
  44 .P
  45 rdma_post_send  - post a buffer to send a message
  46 .P
  47 rdma_post_read  - post an RDMA to read data into a buffer
  48 .P
  49 rdma_post_write - post an RDMA to send data from a buffer
  50 .P
  51 rdma_post_recvv  - post a vector of buffers to receive a message
  52 .P
  53 rdma_post_sendv  - post a vector of buffers to send a message
  54 .P
  55 rdma_post_readv  - post a vector of buffers to receive an RDMA read
  56 .P
  57 rdma_post_writev - post a vector of buffers to send an RDMA write
  58 .P
  59 rdma_post_ud_send - post a buffer to send a message on a UD QP
  60 .P
  61 rdma_get_send_comp - get completion status for a send or RDMA operation
  62 .P
  63 rdma_get_recv_comp - get information about a completed receive
  64 .SH "CLIENT OPERATION"
  65 This section provides a general overview of the basic operation for the active,
  66 or client, side of communication.  This flow assume asynchronous operation with
  67 low level call details shown.  For
  68 synchronous operation, calls to rdma_create_event_channel, rdma_get_cm_event,
  69 rdma_ack_cm_event, and rdma_destroy_event_channel
  70 would be eliminated.  Abstracted calls, such as rdma_create_ep encapsulate
  71 several of these calls under a single API.
  72 Users may also refer to the example applications for
  73 code samples.  A general connection flow would be:
  74 .IP rdma_getaddrinfo
  75 retrieve address information of the destination
  76 .IP rdma_create_event_channel
  77 create channel to receive events
  78 .IP rdma_create_id
  79 allocate an rdma_cm_id, this is conceptually similar to a socket
  80 .IP rdma_resolve_addr
  81 obtain a local RDMA device to reach the remote address
  82 .IP rdma_get_cm_event
  83 wait for RDMA_CM_EVENT_ADDR_RESOLVED event
  84 .IP rdma_ack_cm_event
  85 ack event
  86 .IP rdma_create_qp
  87 allocate a QP for the communication
  88 .IP rdma_resolve_route
  89 determine the route to the remote address
  90 .IP rdma_get_cm_event
  91 wait for RDMA_CM_EVENT_ROUTE_RESOLVED event
  92 .IP rdma_ack_cm_event
  93 ack event
  94 .IP rdma_connect
  95 connect to the remote server
  96 .IP rdma_get_cm_event
  97 wait for RDMA_CM_EVENT_ESTABLISHED event
  98 .IP rdma_ack_cm_event
  99 ack event
 100 .P
 101 Perform data transfers over connection
 102 .IP rdma_disconnect
 103 tear-down connection
 104 .IP rdma_get_cm_event
 105 wait for RDMA_CM_EVENT_DISCONNECTED event
 106 .IP rdma_ack_cm_event
 107 ack event
 108 .IP rdma_destroy_qp
 109 destroy the QP
 110 .IP rdma_destroy_id
 111 release the rdma_cm_id
 112 .IP rdma_destroy_event_channel
 113 release the event channel
 114 .P
 115 An almost identical process is used to setup unreliable datagram (UD)
 116 communication between nodes.  No actual connection is formed between QPs
 117 however, so disconnection is not needed.
 118 .P
 119 Although this example shows the client initiating the disconnect, either side
 120 of a connection may initiate the disconnect.
 121 .SH "SERVER OPERATION"
 122 This section provides a general overview of the basic operation for the passive,
 123 or server, side of communication.  A general connection flow would be:
 124 .IP rdma_create_event_channel
 125 create channel to receive events
 126 .IP rdma_create_id
 127 allocate an rdma_cm_id, this is conceptually similar to a socket
 128 .IP rdma_bind_addr
 129 set the local port number to listen on
 130 .IP rdma_listen
 131 begin listening for connection requests
 132 .IP rdma_get_cm_event
 133 wait for RDMA_CM_EVENT_CONNECT_REQUEST event with a new rdma_cm_id
 134 .IP rdma_create_qp
 135 allocate a QP for the communication on the new rdma_cm_id
 136 .IP rdma_accept
 137 accept the connection request
 138 .IP rdma_ack_cm_event
 139 ack event
 140 .IP rdma_get_cm_event
 141 wait for RDMA_CM_EVENT_ESTABLISHED event
 142 .IP rdma_ack_cm_event
 143 ack event
 144 .P
 145 Perform data transfers over connection
 146 .IP rdma_get_cm_event
 147 wait for RDMA_CM_EVENT_DISCONNECTED event
 148 .IP rdma_ack_cm_event
 149 ack event
 150 .IP rdma_disconnect
 151 tear-down connection
 152 .IP rdma_destroy_qp
 153 destroy the QP
 154 .IP rdma_destroy_id
 155 release the connected rdma_cm_id
 156 .IP rdma_destroy_id
 157 release the listening rdma_cm_id
 158 .IP rdma_destroy_event_channel
 159 release the event channel
 160 .SH "RETURN CODES"
 161 .IP "=  0"
 162 success
 163 .IP "= -1"
 164 error - see errno for more details
 165 .P
 166 Most librdmacm functions return 0 to indicate success, and a -1 return value
 167 to indicate failure.  If a function operates asynchronously, a return value of 0
 168 means that the operation was successfully started.  The operation could still
 169 complete in error; users should check the status of the related event.  If the
 170 return value is -1, then errno will contain additional information
 171 regarding the reason for the failure.
 172 .P
 173 Prior versions of the library would return -errno and not set errno for some cases
 174 related to ENOMEM, ENODEV, ENODATA, EINVAL, and EADDRNOTAVAIL codes. Applications
 175 that want to check these codes and have compatibility with prior library versions
 176 must manually set errno to the negative of the return code if it is < -1.
 177 .SH "SEE ALSO"
 178 rdma_accept(3),
 179 rdma_ack_cm_event(3),
 180 rdma_bind_addr(3),
 181 rdma_connect(3),
 182 rdma_create_ep(3),
 183 rdma_create_event_channel(3),
 184 rdma_create_id(3),
 185 rdma_create_qp(3),
 186 rdma_dereg_mr(3),
 187 rdma_destroy_ep(3),
 188 rdma_destroy_event_channel(3),
 189 rdma_destroy_id(3),
 190 rdma_destroy_qp(3),
 191 rdma_disconnect(3),
 192 rdma_event_str(3),
 193 rdma_free_devices(3),
 194 rdma_getaddrinfo(3),
 195 rdma_get_cm_event(3),
 196 rdma_get_devices(3),
 197 rdma_get_dst_port(3),
 198 rdma_get_local_addr(3),
 199 rdma_get_peer_addr(3),
 200 rdma_get_recv_comp(3),
 201 rdma_get_request(3),
 202 rdma_get_send_comp(3),
 203 rdma_get_src_port(3),
 204 rdma_join_multicast(3),
 205 rdma_leave_multicast(3),
 206 rdma_listen(3),
 207 rdma_migrate_id(3),
 208 rdma_notify(3),
 209 rdma_post_read(3)
 210 rdma_post_readv(3),
 211 rdma_post_recv(3),
 212 rdma_post_recvv(3),
 213 rdma_post_send(3),
 214 rdma_post_sendv(3),
 215 rdma_post_ud_send(3),
 216 rdma_post_write(3),
 217 rdma_post_writev(3),
 218 rdma_reg_msgs(3),
 219 rdma_reg_read(3),
 220 rdma_reg_write(3),
 221 rdma_reject(3),
 222 rdma_resolve_addr(3),
 223 rdma_resolve_route(3),
 224 rdma_set_option(3)
 225 mckey(1),
 226 rdma_client(1),
 227 rdma_server(1),
 228 rping(1),
 229 ucmatose(1),
 230 udaddy(1)