1 .TH "RDMA_CM" 7 "2008-01-02" "librdmacm" "Librdmacm Programmer's Manual" librdmacm
3 rdma_cm \- RDMA communication manager.
5 .B "#include <rdma/rdma_cma.h>"
7 Used to establish communication over RDMA transports.
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.
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
25 allocate an rdma_cm_id, this is conceptually similar to a socket
27 obtain a local RDMA device to reach the remote address
29 wait for RDMA_CM_EVENT_ADDR_RESOLVED event
33 allocate a QP for the communication
34 .IP rdma_resolve_route
35 determine the route to the remote address
37 wait for RDMA_CM_EVENT_ROUTE_RESOLVED event
41 connect to the remote server
43 wait for RDMA_CM_EVENT_ESTABLISHED event
47 Perform data transfers over connection
51 wait for RDMA_CM_EVENT_DISCONNECTED event
57 release the rdma_cm_id
58 .IP rdma_destroy_event_channel
59 release the event channel
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.
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
73 allocate an rdma_cm_id, this is conceptually similar to a socket
75 set the local port number to listen on
77 begin listening for connection requests
79 wait for RDMA_CM_EVENT_CONNECT_REQUEST event with a new rdma_cm_id
81 allocate a QP for the communication on the new rdma_cm_id
83 accept the connection request
87 wait for RDMA_CM_EVENT_ESTABLISHED event
91 Perform data transfers over connection
93 wait for RDMA_CM_EVENT_DISCONNECTED event
101 release the connected rdma_cm_id
103 release the listening rdma_cm_id
104 .IP rdma_destroy_event_channel
105 release the event channel
110 error - see errno for more details
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.
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.
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)