2 .\" This manual page is derived from the DAT/uDAPL 1.2 specification.
3 .\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH DAT_RMR_BIND 3DAT "Jul 16, 2004"
9 dat_rmr_bind \- bind the RMR to the specified memory region within an LMR
13 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ]
14 #include <\fBdat/udat.h\fR>
18 IN DAT_RMR_HANDLE rmr_handle,
19 IN DAT_LMR_TRIPLET *lmr_triplet,
20 IN DAT_MEM_PRIV_FLAGS mem_privileges,
21 IN DAT_EP_HANDLE ep_handle,
22 IN DAT_RMR_COOKIE user_cookie,
23 IN DAT_COMPLETION_FLAGS completion_flags,
24 OUT DAT_RMR_CONTEXT *rmr_context
32 \fB\fIrmr_handle\fR\fR
35 Handle for an RMR instance.
41 \fB\fIlmr_triplet\fR\fR
44 A pointer to an \fIlmr_triplet\fR that defines the memory region of the LMR.
50 \fB\fImem_privileges\fR\fR
53 Consumer-requested memory access privileges for the registered remote memory
54 region. The Default value is \fBDAT_MEM_PRIV_NONE_FLAG\fR. The constant value
55 \fBDAT_MEM_PRIV_ALL_FLAG\fR = 0x33, which specifies both Read and Write
56 privileges, is also defined. Memory privilege definitions are as follows:
63 \fBDAT_MEM_PRIV_REMOTE_READ_FLAG\fR
70 Remote read access requested.
81 \fBDAT_MEM_PRIV_REMOTE_WRITE_FLAG\fR
88 Remote write access requested.
101 Endpoint to which \fBdat_rmr_bind()\fR is posted.
107 \fB\fIuser_cookie\fR\fR
110 User-provided cookie that is returned to a Consumer at the completion of the
111 \fBdat_rmr_bind()\fR. Can be \fINULL\fR.
117 \fB\fIcompletion_flags\fR\fR
120 Flags for RMR Bind. The default \fBDAT_COMPLETION_DEFAULT_FLAG\fR is 0. Flag
121 definitions are as follows:
125 \fBCompletion Suppression\fR
128 \fBDAT_COMPLETION_SUPPRESS_FLAG\fR
135 Suppress successful Completion.
143 \fBNotification of Completion\fR
146 \fB\fR\fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR
153 Non-notification completion. Local Endpoint must be configured for Notification
165 \fB\fR\fBDAT_COMPLETION_BARRIER_FENCE_FLAG\fR
172 Request for Barrier Fence.
182 \fB\fIrmr_context\fR\fR
185 New \fIrmr_context\fR for the bound RMR suitable to be shared with a remote
192 The \fBdat_rmr_bind()\fR function binds the RMR to the specified memory region
193 within an LMR and provides the new \fIrmr_context\fR value. The
194 \fBdat_rmr_bind()\fR operation is a lightweight asynchronous operation that
195 generates a new \fIrmr_context\fR. The Consumer is notified of the completion
196 of this operation through a \fIrmr_bind\fR Completion event on the
197 \fIrequest_evd_handle\fR of the specified Endpoint \fIep_handle\fR.
200 The return value of \fIrmr_context\fR can be transferred by local Consumer to a
201 Consumer on a remote host to be used for an RDMA DTO. The use of
202 \fIrmr_context\fR by a remote host for an RDMA DTO prior to the completion of
203 the \fBdat_rmr_bind()\fR can result in an error and a broken connection. The
204 local Consumer can ensure that the remote Consumer does not have
205 \fIrmr_context\fR before \fBdat_rmr_bind()\fR is completed. One way is to
206 "wait" for the completion \fBdat_rmr_bind()\fR on the \fIrmr_bind\fR Event
207 Dispatcher of the specified Endpoint \fIep_handle\fR. Another way is to send
208 \fIrmr_context\fR in a Send DTO over the connection of the Endpoint
209 \fIep_handle\fR. The barrier-fencing behavior of the \fBdat_rmr_bind()\fR with
210 respect to Send and RDMA DTOs ensures that a Send DTO does not start until
211 \fBdat_rmr_bind()\fR completed.
214 The \fBdat_rmr_bind()\fR function automatically fences all Send, RDMA Read, and
215 RDMA Write DTOs and \fBdat_rmr_bind()\fR operations submitted on the Endpoint
216 \fIep_handle\fR after the \fBdat_rmr_bind()\fR. Therefore, none of these
217 operations starts until \fBdat_rmr_bind()\fR is completed.
220 If the RMR Bind fails after \fBdat_rmr_bind()\fR returns, connection of
221 \fIep_handle\fR is broken. The Endpoint transitions into a
222 \fBDAT_EP_STATE_DISCONNECTED\fR state and the \fBDAT_CONNECTION_EVENT_BROKEN\fR
223 event is delivered to the \fIconnect_evd_handle\fR of the Endpoint.
226 The \fBdat_rmr_bind()\fR function employs fencing to ensure that operations
227 sending the RMR Context on the same Endpoint as the bind specified cannot
228 result in an error from the peer side using the delivered RMR Context too soon.
229 One method, used by InfiniBand, is to ensure that none of these operations
230 start on the Endpoint until after the bind is completed. Other transports can
231 employ different methods to achieve the same goal.
234 Any RDMA DTO that uses the previous value of \fIrmr_context\fR after the
235 \fBdat_rmr_bind()\fR is completed fail and report a protection violation.
238 By default, \fBdat_rmr_bind()\fR generates notification completions.
241 The \fImem_privileges\fR parameter allows Consumers to restrict the type of
242 remote accesses to the registered RMR by RDMA DTOs. Providers whose underlying
243 Transports require that privileges of the requested RMR and the associated LMR
249 Set RMR's \fBDAT_MEM_PRIV_REMOTE_READ_FLAG\fR requires that LMR's
250 \fBDAT_MEM_PRIV_LOCAL_READ_FLAG\fR is also set,
256 Set RMR's \fBDAT_MEM_PRIV_REMOTE_WRITE_FLAG\fR requires that LMR's
257 \fBDAT_MEM_PRIV_LOCAL_WRITE_FLAG\fR is also set,
261 or the operation fails and returns \fBDAT_PRIVILEGES_VIOLATION\fR.
264 In the \fIlmr_triplet\fR, the value of \fIlength\fR of zero means that the
265 Consumer does not want to associate an RMR with any memory region within the
266 LMR and the return value of \fIrmr_context\fR for that case is undefined.
269 The completion of the posted RMR Bind is reported to the Consumer
270 asynchronously through a DTO Completion event based on the specified
271 \fIcompletion_flags\fR value. The value of
272 \fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR is only valid if the Endpoint Request
273 Completion Flags \fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR. Otherwise,
274 \fBDAT_INVALID_PARAMETER\fR is returned.
277 The \fIuser_cookie\fR parameter allows Consumers to have unique identifiers for
278 each \fBdat_rmr_bind()\fR. These identifiers are completely under user control
279 and are opaque to the Provider. The Consumer is not required to ensure the
280 uniqueness of the \fIuser_cookie\fR value. The \fIuser_cookie\fR is returned to
281 the Consumer in the \fIrmr_bind\fR Completion event for this operation.
284 The operation is valid for the Endpoint in the \fBDAT_EP_STATE_CONNECTED\fR and
285 \fBDAT_EP_STATE_DISCONNECTED\fR states. If the operation returns successfully
286 for the Endpoint in \fBDAT_EP_STATE_DISCONNECTED\fR state, the posted RMR Bind
287 is immediately flushed to \fIrequest_evd_handle\fR.
292 \fB\fBDAT_SUCCESS\fR\fR
295 The operation was successful.
301 \fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR
304 The operation failed due to resource limitations.
310 \fB\fBDAT_INVALID_PARAMETER\fR\fR
313 Invalid parameter. For example, the \fItarget_address\fR or
314 \fIsegment_length\fR exceeded the limits of the existing LMR.
320 \fB\fBDAT_INVALID_HANDLE\fR\fR
329 \fB\fBDAT_INVALID_STATE\fR\fR
332 Parameter in an invalid state. Endpoint was not in the a
333 \fBDAT_EP_STATE_CONNECTED\fR or \fBDAT_EP_STATE_DISCONNECTED\fR state.
339 \fB\fBDAT_MODEL_NOT_SUPPORTED\fR\fR
342 The requested Model was not supported by the Provider.
348 \fB\fBDAT_PRIVILEGES_VIOLATION\fR\fR
351 Privileges violation for local or remote memory access.
357 \fB\fBDAT_PROTECTION_VIOLATION\fR\fR
360 Protection violation for local or remote memory access.
366 See \fBattributes\fR(5) for descriptions of the following attributes:
374 ATTRIBUTE TYPE ATTRIBUTE VALUE
376 Interface Stability Standard: uDAPL, 1.1, 1.2
384 \fBlibdat\fR(3LIB), \fBattributes\fR(5)