share/man/man3dat/dat_lmr_sync_rdma_write.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_LMR_SYNC_RDMA_WRITE 3DAT "Jul 16, 2004"
   8 .SH NAME
   9 dat_lmr_sync_rdma_write \- synchronize local memory with RDMA write on
  10 non-coherent memory
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ]
  15 #include <\fBdat/udat.h\fR>
  16
  17 DAT_RETURN
  18     dat_lmr_sync_rdma_write (
  19     IN DAT_IA_HANDLE ia_handle,
  20     IN const DAT_LMR_TRIPLET *local_segments,
  21     IN DAT_VLEN num_segments
  22     )
  23 .fi
  24
  25 .SH PARAMETERS
  26 .sp
  27 .ne 2
  28 .na
  29 \fB\fIia_handle\fR\fR
  30 .ad
  31 .RS 18n
  32 A handle for an open instance of the IA.
  33 .RE
  34
  35 .sp
  36 .ne 2
  37 .na
  38 \fB\fIlocal_segments\fR\fR
  39 .ad
  40 .RS 18n
  41 An array of buffer segments.
  42 .RE
  43
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fInum_segments\fR\fR
  48 .ad
  49 .RS 18n
  50 The number of segments in the \fIlocal_segments\fR argument.
  51 .RE
  52
  53 .SH DESCRIPTION
  54 .sp
  55 .LP
  56 The \fBdat_lmr_sync_rdma_write()\fR function makes effects of an incoming RDMA
  57 Write operation visible to the Consumer. This operation guarantees consistency
  58 by locally invalidating the non-coherent cache whose buffer has been populated
  59 by remote peer RDMA write operations.
  60 .sp
  61 .LP
  62 The \fBdat_lmr_sync_rdma_write()\fR function is needed if and only if the
  63 Provider attribute specifies that this operation is needed after an incoming
  64 RDMA Write operation. The Consumer must call \fBdat_lmr_sync_rdma_write()\fR
  65 before reading data from a memory range in this region that was the target of
  66 an incoming RDMA Write operation. The \fBdat_lmr_sync_rdma_write()\fR function
  67 must be called after the RDMA Write operation completes, and the memory range
  68 that was modified by the RDMA Write must be supplied by the caller in the
  69 \fIlocal_ segments\fR array. After this call returns, the Consumer may safely
  70 see the modified contents of the memory range. It is permissible to batch
  71 synchronizations of multiple RDMA Write operations in a single call by passing
  72 a \fIlocal_segments\fR array that includes all modified memory ranges. The
  73 \fIlocal_segments\fR entries need not contain the same LMR and need not be in
  74 the same Protection Zone.
  75 .sp
  76 .LP
  77 The Consumer must also use \fBdat_lmr_sync_rdma_write()\fR when performing
  78 local writes to a memory range that was or will be the target of incoming RDMA
  79 writes. After performing the local write, the Consumer must call
  80 \fBdat_lmr_sync_rdma_write()\fR before the RDMA Write is initiated.
  81 Conversely, after an RDMA Write completes, the Consumer must call
  82 \fBdat_lmr_sync_rdma_write()\fR before performing a local write to the same
  83 range.
  84 .sp
  85 .LP
  86 If the Provider attribute specifies that this operation is needed and the
  87 Consumer attempts to read from a memory range in an LMR without properly
  88 synchronizing using \fBdat_lmr_sync_rdma_write()\fR, the returned contents are
  89 undefined. If the Consumer attempts to write to a memory range without properly
  90 synchronizing, the contents of the memory range become undefined.
  91 .SH RETURN VALUES
  92 .sp
  93 .ne 2
  94 .na
  95 \fB\fBDAT_SUCCESS\fR\fR
  96 .ad
  97 .RS 25n
  98 The operation was successful.
  99 .RE
 100
 101 .sp
 102 .ne 2
 103 .na
 104 \fB\fBDAT_INVALID_HANDLE\fR\fR
 105 .ad
 106 .RS 25n
 107 The DAT handle is invalid.
 108 .RE
 109
 110 .sp
 111 .ne 2
 112 .na
 113 \fB\fBDAT_INVALID_PARAMETER\fR\fR
 114 .ad
 115 .RS 25n
 116 One of the parameters is invalid. For example, the address range for a local
 117 segment fell outside the boundaries of the corresponding Local Memory Region or
 118 the LMR handle was invalid.
 119 .RE
 120
 121 .SH USAGE
 122 .sp
 123 .LP
 124 Determining when an RDMA Write completes and determining which memory range was
 125 modified is the Consumer's responsibility. One possibility is for the RDMA
 126 Write initiator to post a Send DTO message after each RDMA Write that
 127 identifies the range in the body of the Send. The Consumer at the target of the
 128 RDMA Write can receive the message and know when and how to call
 129 \fBdat_lmr_sync_rdma_write()\fR.
 130 .sp
 131 .LP
 132 This call ensures that the Provider receives a coherent view of the buffer
 133 contents after a subsequent remote RDMA Write operation. After the call
 134 completes, the Consumer can be assured that all platform-specific buffer and
 135 cache updates have been performed, and that the LMR range has consistency with
 136 the Provider hardware. Any subsequent read by the Consumer can void this
 137 consistency. The Provider is not required to detect such access.
 138 .sp
 139 .LP
 140 The action performed on the cache before the RDMA Write depends on the cache
 141 type:
 142 .RS +4
 143 .TP
 144 .ie t \(bu
 145 .el o
 146 I/O noncoherent cache will be flushed.
 147 .RE
 148 .RS +4
 149 .TP
 150 .ie t \(bu
 151 .el o
 152 CPU noncoherent cache will be invalidated.
 153 .RE
 154 .SH ATTRIBUTES
 155 .sp
 156 .LP
 157 See \fBattributes\fR(5) for descriptions of the following attributes:
 158 .sp
 159
 160 .sp
 161 .TS
 162 box;
 163 c | c
 164 l | l .
 165 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 166 _
 167 Interface Stability     Standard: uDAPL, 1.2
 168 _
 169 MT-Level        Unsafe
 170 .TE
 171
 172 .SH SEE ALSO
 173 .sp
 174 .LP
 175 \fBdat_lmr_sync_rdma_read\fR(3DAT), \fBlibdat\fR(3LIB), \fBattributes\fR(5)