1dat_rmr_bind(3DAT) Direct Access Transport Library Functionsdat_rmr_bind(3DAT)
2
6 dat_rmr_bind - bind the RMR to the specified memory region within an
7 LMR
8
10 cc [ flag... ] file... -ldat [ library... ]
11 #include <dat/udat.h>
12 DAT_RETURN
14 dat_rmr_bind(
15 IN DAT_RMR_HANDLE rmr_handle,
16 IN DAT_LMR_TRIPLET *lmr_triplet,
17 IN DAT_MEM_PRIV_FLAGS mem_privileges,
18 IN DAT_EP_HANDLE ep_handle,
19 IN DAT_RMR_COOKIE user_cookie,
20 IN DAT_COMPLETION_FLAGS completion_flags,
21 OUT DAT_RMR_CONTEXT *rmr_context
22 )
23
26 rmr_handle Handle for an RMR instance.
27 lmr_triplet A pointer to an lmr_triplet that defines the memory
30 region of the LMR.
31 mem_privileges Consumer-requested memory access privileges for the
34 registered remote memory region. The Default value
35 is DAT_MEM_PRIV_NONE_FLAG. The constant value
36 DAT_MEM_PRIV_ALL_FLAG = 0x33, which specifies both
37 Read and Write privileges, is also defined. Memory
38 privilege definitions are as follows:
39 Remote Read DAT_MEM_PRIV_REMOTE_READ_FLAG
41 0x02 Remote read access
43 requested.
44 Remote Write DAT_MEM_PRIV_REMOTE_WRITE_FLAG
48 0x20 Remote write access
50 requested.
51 ep_handle Endpoint to which dat_rmr_bind() is posted.
56 user_cookie User-provided cookie that is returned to a Consumer
59 at the completion of the dat_rmr_bind(). Can be
60 NULL.
61 completion_flags Flags for RMR Bind. The default DAT_COMPLE‐
64 TION_DEFAULT_FLAG is 0. Flag definitions are as
65 follows:
66 Completion Suppression DAT_COMPLETION_SUP‐
68 PRESS_FLAG
69 0x01 Suppress suc‐
71 cessful Com‐
72 pletion.
73 Notification of Completion DAT_COMPLE‐
77 TION_UNSIGNALLED_FLAG
78 0x04 Non-notifica‐
80 tion comple‐
81 tion. Local
82 Endpoint must
83 be configured
84 for Notifica‐
85 tion Suppres‐
86 sion.
87 Barrier Fence DAT_COMPLETION_BAR‐
91 RIER_FENCE_FLAG
92 0x08 Request for
94 Barrier
95 Fence.
96 rmr_context New rmr_context for the bound RMR suitable to be
101 shared with a remote host.
102
105 The dat_rmr_bind() function binds the RMR to the specified memory
106 region within an LMR and provides the new rmr_context value. The
107 dat_rmr_bind() operation is a lightweight asynchronous operation that
108 generates a new rmr_context. The Consumer is notified of the completion
109 of this operation through a rmr_bind Completion event on the
110 request_evd_handle of the specified Endpoint ep_handle.
111 The return value of rmr_context can be transferred by local Consumer to
114 a Consumer on a remote host to be used for an RDMA DTO. The use of
115 rmr_context by a remote host for an RDMA DTO prior to the completion of
116 the dat_rmr_bind() can result in an error and a broken connection. The
117 local Consumer can ensure that the remote Consumer does not have
118 rmr_context before dat_rmr_bind() is completed. One way is to "wait"
119 for the completion dat_rmr_bind() on the rmr_bind Event Dispatcher of
120 the specified Endpoint ep_handle. Another way is to send rmr_context in
121 a Send DTO over the connection of the Endpoint ep_handle. The barrier-
122 fencing behavior of the dat_rmr_bind() with respect to Send and RDMA
123 DTOs ensures that a Send DTO does not start until dat_rmr_bind() com‐
124 pleted.
125 The dat_rmr_bind() function automatically fences all Send, RDMA Read,
128 and RDMA Write DTOs and dat_rmr_bind() operations submitted on the End‐
129 point ep_handle after the dat_rmr_bind(). Therefore, none of these
130 operations starts until dat_rmr_bind() is completed.
131 If the RMR Bind fails after dat_rmr_bind() returns, connection of
134 ep_handle is broken. The Endpoint transitions into a DAT_EP_STATE_DIS‐
135 CONNECTED state and the DAT_CONNECTION_EVENT_BROKEN event is delivered
136 to the connect_evd_handle of the Endpoint.
137 The dat_rmr_bind() function employs fencing to ensure that operations
140 sending the RMR Context on the same Endpoint as the bind specified can‐
141 not result in an error from the peer side using the delivered RMR Con‐
142 text too soon. One method, used by InfiniBand, is to ensure that none
143 of these operations start on the Endpoint until after the bind is com‐
144 pleted. Other transports can employ different methods to achieve the
145 same goal.
146 Any RDMA DTO that uses the previous value of rmr_context after the
149 dat_rmr_bind() is completed fail and report a protection violation.
150 By default, dat_rmr_bind() generates notification completions.
153 The mem_privileges parameter allows Consumers to restrict the type of
156 remote accesses to the registered RMR by RDMA DTOs. Providers whose
157 underlying Transports require that privileges of the requested RMR and
158 the associated LMR match, that is
159 o Set RMR's DAT_MEM_PRIV_REMOTE_READ_FLAG requires that LMR's
161 DAT_MEM_PRIV_LOCAL_READ_FLAG is also set,
162 o Set RMR's DAT_MEM_PRIV_REMOTE_WRITE_FLAG requires that LMR's
164 DAT_MEM_PRIV_LOCAL_WRITE_FLAG is also set,
165 or the operation fails and returns DAT_PRIVILEGES_VIOLATION.
168 In the lmr_triplet, the value of length of zero means that the Consumer
171 does not want to associate an RMR with any memory region within the LMR
172 and the return value of rmr_context for that case is undefined.
173 The completion of the posted RMR Bind is reported to the Consumer asyn‐
176 chronously through a DTO Completion event based on the specified com‐
177 pletion_flags value. The value of DAT_COMPLETION_UNSIGNALLED_FLAG is
178 only valid if the Endpoint Request Completion Flags DAT_COMPLE‐
179 TION_UNSIGNALLED_FLAG. Otherwise, DAT_INVALID_PARAMETER is returned.
180 The user_cookie parameter allows Consumers to have unique identifiers
183 for each dat_rmr_bind(). These identifiers are completely under user
184 control and are opaque to the Provider. The Consumer is not required to
185 ensure the uniqueness of the user_cookie value. The user_cookie is
186 returned to the Consumer in the rmr_bind Completion event for this
187 operation.
188 The operation is valid for the Endpoint in the DAT_EP_STATE_CONNECTED
191 and DAT_EP_STATE_DISCONNECTED states. If the operation returns success‐
192 fully for the Endpoint in DAT_EP_STATE_DISCONNECTED state, the posted
193 RMR Bind is immediately flushed to request_evd_handle.
194
196 DAT_SUCCESS The operation was successful.
197 DAT_INSUFFICIENT_RESOURCES The operation failed due to resource lim‐
200 itations.
201 DAT_INVALID_PARAMETER Invalid parameter. For example, the tar‐
204 get_address or segment_length exceeded
205 the limits of the existing LMR.
206 DAT_INVALID_HANDLE Invalid DAT handle.
209 DAT_INVALID_STATE Parameter in an invalid state. Endpoint
212 was not in the a DAT_EP_STATE_CONNECTED
213 or DAT_EP_STATE_DISCONNECTED state.
214 DAT_MODEL_NOT_SUPPORTED The requested Model was not supported by
217 the Provider.
218 DAT_PRIVILEGES_VIOLATION Privileges violation for local or remote
221 memory access.
222 DAT_PROTECTION_VIOLATION Protection violation for local or remote
225 memory access.
226
229 See attributes(5) for descriptions of the following attributes:
230 ┌─────────────────────────────┬─────────────────────────────┐
235 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
236 ├─────────────────────────────┼─────────────────────────────┤
237 │Interface Stability │Standard: uDAPL, 1.1, 1.2 │
238 ├─────────────────────────────┼─────────────────────────────┤
239 │MT-Level │Unsafe │
240 └─────────────────────────────┴─────────────────────────────┘
241
243 libdat(3LIB), attributes(5)
244SunOS 5.11 16 Jul 2004 dat_rmr_bind(3DAT)