usr/src/man/man3dat/dat_lmr_sync_rdma_read.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_READ 3DAT "Jul 16, 2004"
   8 .SH NAME
   9 dat_lmr_sync_rdma_read \- synchronize local memory with RDMA read 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_read (
  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_read()\fR function makes memory changes visible to an
  57 incoming RDMA Read operation. This operation guarantees consistency by locally
  58 flushing the non-coherent cache prior to it being retrieved by remote peer RDMA
  59 read operations.
  60 .sp
  61 .LP
  62 The \fBdat_lmr_sync_rdma_read()\fR function is needed if and only if the
  63 Provider attribute specifies that this operation is needed prior to an incoming
  64 RDMA Read operation. The Consumer must call \fBdat_lmr_sync_rdma_read()\fR
  65 after modifying data in a memory range in this region that will be the target
  66 of an incoming RDMA Read operation. The \fBdat_lmr_sync_rdma_read()\fR function
  67 must be called after the Consumer has modified the memory range but before the
  68 RDMA Read operation begins. The memory range that will be accessed by the RDMA
  69 read operation must be supplied by the caller in the \fIlocal_segments\fR
  70 array. After this call returns, the RDMA Read operation can safely see the
  71 modified contents of the memory range. It is permissible to batch
  72 synchronizations for multiple RDMA Read operations in a single call by passing
  73 a \fIlocal_segments\fR array that includes all modified memory ranges. The
  74 \fIlocal_segments\fR entries need not contain the same LMR and need not be in
  75 the same Protection Zone.
  76 .sp
  77 .LP
  78 If the Provider attribute specifying that this operation is required attempts
  79 to read from a memory range that is not properly synchronized using
  80 \fBdat_lmr_sync_rdma_read()\fR, the returned contents are undefined.
  81 .SH RETURN VALUES
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fBDAT_SUCCESS\fR\fR
  86 .ad
  87 .RS 25n
  88 The operation was successful.
  89 .RE
  90
  91 .sp
  92 .ne 2
  93 .na
  94 \fB\fBDAT_INVALID_HANDLE\fR\fR
  95 .ad
  96 .RS 25n
  97 The DAT handle is invalid.
  98 .RE
  99
 100 .sp
 101 .ne 2
 102 .na
 103 \fB\fBDAT_INVALID_PARAMETER\fR\fR
 104 .ad
 105 .RS 25n
 106 One of the parameters is invalid. For example, the address range for a local
 107 segment fell outside the boundaries of the corresponding Local Memory Region or
 108 the LMR handle was invalid.
 109 .RE
 110
 111 .SH USAGE
 112 .sp
 113 .LP
 114 Determining when an RDMA Read will start and what memory range it will read is
 115 the Consumer's responsibility. One possibility is to have the Consumer that is
 116 modifying memory call \fBdat_lmr_sync_rdma_read()\fR and then post a Send DTO
 117 message that identifies the range in the body of the Send. The Consumer wanting
 118 to perform the RDMA Read can receive this message and know when it is safe to
 119 initiate the RDMA Read operation.
 120 .sp
 121 .LP
 122 This call ensures that the Provider receives a coherent view of the buffer
 123 contents upon a subsequent remote RDMA Read operation. After the call
 124 completes, the Consumer can be assured that all platform-specific buffer and
 125 cache updates have been performed, and that the LMR range has consistency with
 126 the Provider hardware. Any subsequent write by the Consumer can void this
 127 consistency. The Provider is not required to detect such access.
 128 .sp
 129 .LP
 130 The action performed on the cache before the RDMA Read depends on the cache
 131 type:
 132 .RS +4
 133 .TP
 134 .ie t \(bu
 135 .el o
 136 I/O noncoherent cache will be invalidated.
 137 .RE
 138 .RS +4
 139 .TP
 140 .ie t \(bu
 141 .el o
 142 CPU noncoherent cache will be flushed.
 143 .RE
 144 .SH ATTRIBUTES
 145 .sp
 146 .LP
 147 See \fBattributes\fR(5) for descriptions of the following attributes:
 148 .sp
 149
 150 .sp
 151 .TS
 152 box;
 153 c | c
 154 l | l .
 155 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 156 _
 157 Interface Stability     Standard: uDAPL, 1.2
 158 _
 159 MT-Level        Unsafe
 160 .TE
 161
 162 .SH SEE ALSO
 163 .sp
 164 .LP
 165 \fBdat_lmr_sync_rdma_write\fR(3DAT), \fBlibdat\fR(3LIB), \fBattributes\fR(5)