share/man/man3dat/dat_rmr_bind.3dat

   1 '\" te
   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"
   8 .SH NAME
   9 dat_rmr_bind \- bind the RMR to the specified memory region within an LMR
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ]
  14 #include <\fBdat/udat.h\fR>
  15
  16 DAT_RETURN
  17     dat_rmr_bind(
  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
  25     )
  26 .fi
  27
  28 .SH PARAMETERS
  29 .sp
  30 .ne 2
  31 .na
  32 \fB\fIrmr_handle\fR\fR
  33 .ad
  34 .RS 20n
  35 Handle for an RMR instance.
  36 .RE
  37
  38 .sp
  39 .ne 2
  40 .na
  41 \fB\fIlmr_triplet\fR\fR
  42 .ad
  43 .RS 20n
  44 A pointer to an \fIlmr_triplet\fR that defines the memory region of the LMR.
  45 .RE
  46
  47 .sp
  48 .ne 2
  49 .na
  50 \fB\fImem_privileges\fR\fR
  51 .ad
  52 .RS 20n
  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:
  57 .sp
  58 .ne 2
  59 .na
  60 \fBRemote Read\fR
  61 .ad
  62 .RS 16n
  63 \fBDAT_MEM_PRIV_REMOTE_READ_FLAG\fR
  64 .sp
  65 .ne 2
  66 .na
  67 \fB0x02\fR
  68 .ad
  69 .RS 8n
  70 Remote read access requested.
  71 .RE
  72
  73 .RE
  74
  75 .sp
  76 .ne 2
  77 .na
  78 \fBRemote Write\fR
  79 .ad
  80 .RS 16n
  81 \fBDAT_MEM_PRIV_REMOTE_WRITE_FLAG\fR
  82 .sp
  83 .ne 2
  84 .na
  85 \fB0x20\fR
  86 .ad
  87 .RS 8n
  88 Remote write access requested.
  89 .RE
  90
  91 .RE
  92
  93 .RE
  94
  95 .sp
  96 .ne 2
  97 .na
  98 \fB\fIep_handle\fR\fR
  99 .ad
 100 .RS 20n
 101 Endpoint to which \fBdat_rmr_bind()\fR is posted.
 102 .RE
 103
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fIuser_cookie\fR\fR
 108 .ad
 109 .RS 20n
 110 User-provided cookie that is returned to a Consumer at the completion of the
 111 \fBdat_rmr_bind()\fR. Can be \fINULL\fR.
 112 .RE
 113
 114 .sp
 115 .ne 2
 116 .na
 117 \fB\fIcompletion_flags\fR\fR
 118 .ad
 119 .RS 20n
 120 Flags for RMR Bind. The default \fBDAT_COMPLETION_DEFAULT_FLAG\fR is 0. Flag
 121 definitions are as follows:
 122 .sp
 123 .ne 2
 124 .na
 125 \fBCompletion Suppression\fR
 126 .ad
 127 .RS 30n
 128 \fBDAT_COMPLETION_SUPPRESS_FLAG\fR
 129 .sp
 130 .ne 2
 131 .na
 132 \fB0x01\fR
 133 .ad
 134 .RS 8n
 135 Suppress successful Completion.
 136 .RE
 137
 138 .RE
 139
 140 .sp
 141 .ne 2
 142 .na
 143 \fBNotification of Completion\fR
 144 .ad
 145 .RS 30n
 146 \fB\fR\fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR
 147 .sp
 148 .ne 2
 149 .na
 150 \fB0x04\fR
 151 .ad
 152 .RS 8n
 153 Non-notification completion. Local Endpoint must be configured for Notification
 154 Suppression.
 155 .RE
 156
 157 .RE
 158
 159 .sp
 160 .ne 2
 161 .na
 162 \fBBarrier Fence\fR
 163 .ad
 164 .RS 30n
 165 \fB\fR\fBDAT_COMPLETION_BARRIER_FENCE_FLAG\fR
 166 .sp
 167 .ne 2
 168 .na
 169 \fB0x08\fR
 170 .ad
 171 .RS 8n
 172 Request for Barrier Fence.
 173 .RE
 174
 175 .RE
 176
 177 .RE
 178
 179 .sp
 180 .ne 2
 181 .na
 182 \fB\fIrmr_context\fR\fR
 183 .ad
 184 .RS 20n
 185 New \fIrmr_context\fR for the bound RMR suitable to be shared with a remote
 186 host.
 187 .RE
 188
 189 .SH DESCRIPTION
 190 .sp
 191 .LP
 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.
 198 .sp
 199 .LP
 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.
 212 .sp
 213 .LP
 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.
 218 .sp
 219 .LP
 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.
 224 .sp
 225 .LP
 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.
 232 .sp
 233 .LP
 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.
 236 .sp
 237 .LP
 238 By default, \fBdat_rmr_bind()\fR generates notification completions.
 239 .sp
 240 .LP
 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
 244 match, that is
 245 .RS +4
 246 .TP
 247 .ie t \(bu
 248 .el o
 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,
 251 .RE
 252 .RS +4
 253 .TP
 254 .ie t \(bu
 255 .el o
 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,
 258 .RE
 259 .sp
 260 .LP
 261 or the operation fails and returns \fBDAT_PRIVILEGES_VIOLATION\fR.
 262 .sp
 263 .LP
 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.
 267 .sp
 268 .LP
 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.
 275 .sp
 276 .LP
 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.
 282 .sp
 283 .LP
 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.
 288 .SH RETURN VALUES
 289 .sp
 290 .ne 2
 291 .na
 292 \fB\fBDAT_SUCCESS\fR\fR
 293 .ad
 294 .RS 30n
 295 The operation was successful.
 296 .RE
 297
 298 .sp
 299 .ne 2
 300 .na
 301 \fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR
 302 .ad
 303 .RS 30n
 304 The operation failed due to resource limitations.
 305 .RE
 306
 307 .sp
 308 .ne 2
 309 .na
 310 \fB\fBDAT_INVALID_PARAMETER\fR\fR
 311 .ad
 312 .RS 30n
 313 Invalid parameter. For example, the \fItarget_address\fR or
 314 \fIsegment_length\fR exceeded the limits of the existing LMR.
 315 .RE
 316
 317 .sp
 318 .ne 2
 319 .na
 320 \fB\fBDAT_INVALID_HANDLE\fR\fR
 321 .ad
 322 .RS 30n
 323 Invalid DAT handle.
 324 .RE
 325
 326 .sp
 327 .ne 2
 328 .na
 329 \fB\fBDAT_INVALID_STATE\fR\fR
 330 .ad
 331 .RS 30n
 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.
 334 .RE
 335
 336 .sp
 337 .ne 2
 338 .na
 339 \fB\fBDAT_MODEL_NOT_SUPPORTED\fR\fR
 340 .ad
 341 .RS 30n
 342 The requested Model was not supported by the Provider.
 343 .RE
 344
 345 .sp
 346 .ne 2
 347 .na
 348 \fB\fBDAT_PRIVILEGES_VIOLATION\fR\fR
 349 .ad
 350 .RS 30n
 351 Privileges violation for local or remote memory access.
 352 .RE
 353
 354 .sp
 355 .ne 2
 356 .na
 357 \fB\fBDAT_PROTECTION_VIOLATION\fR\fR
 358 .ad
 359 .RS 30n
 360 Protection violation for local or remote memory access.
 361 .RE
 362
 363 .SH ATTRIBUTES
 364 .sp
 365 .LP
 366 See \fBattributes\fR(5) for descriptions of the following attributes:
 367 .sp
 368
 369 .sp
 370 .TS
 371 box;
 372 c | c
 373 l | l .
 374 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 375 _
 376 Interface Stability     Standard: uDAPL, 1.1, 1.2
 377 _
 378 MT-Level        Unsafe
 379 .TE
 380
 381 .SH SEE ALSO
 382 .sp
 383 .LP
 384 \fBlibdat\fR(3LIB), \fBattributes\fR(5)