'\" te
.\" This manual page is derived from the DAT/uDAPL 1.2 specification.
.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" 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.
.\" 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.
.\" 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]
.TH DAT_LMR_SYNC_RDMA_READ 3DAT "Jul 16, 2004"
.SH NAME
dat_lmr_sync_rdma_read \- synchronize local memory with RDMA read on
non-coherent memory
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <\fBdat/udat.h\fR>

DAT_RETURN
    dat_lmr_sync_rdma_read (
    IN DAT_IA_HANDLE ia_handle,
    IN const DAT_LMR_TRIPLET *local_segments,
    IN DAT_VLEN num_segments
    )
.fi

.SH PARAMETERS
.sp
.ne 2
.na
\fB\fIia_handle\fR\fR
.ad
.RS 18n
A handle for an open instance of the IA.
.RE

.sp
.ne 2
.na
\fB\fIlocal_segments\fR\fR
.ad
.RS 18n
An array of buffer segments.
.RE

.sp
.ne 2
.na
\fB\fInum_segments\fR\fR
.ad
.RS 18n
The number of segments in the \fIlocal_segments\fR argument.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBdat_lmr_sync_rdma_read()\fR function makes memory changes visible to an
incoming RDMA Read operation. This operation guarantees consistency by locally
flushing the non-coherent cache prior to it being retrieved by remote peer RDMA
read operations.
.sp
.LP
The \fBdat_lmr_sync_rdma_read()\fR function is needed if and only if the
Provider attribute specifies that this operation is needed prior to an incoming
RDMA Read operation. The Consumer must call \fBdat_lmr_sync_rdma_read()\fR
after modifying data in a memory range in this region that will be the target
of an incoming RDMA Read operation. The \fBdat_lmr_sync_rdma_read()\fR function
must be called after the Consumer has modified the memory range but before the
RDMA Read operation begins. The memory range that will be accessed by the RDMA
read operation must be supplied by the caller in the \fIlocal_segments\fR
array. After this call returns, the RDMA Read operation can safely see the
modified contents of the memory range. It is permissible to batch
synchronizations for multiple RDMA Read operations in a single call by passing
a \fIlocal_segments\fR array that includes all modified memory ranges. The
\fIlocal_segments\fR entries need not contain the same LMR and need not be in
the same Protection Zone.
.sp
.LP
If the Provider attribute specifying that this operation is required attempts
to read from a memory range that is not properly synchronized using
\fBdat_lmr_sync_rdma_read()\fR, the returned contents are undefined.
.SH RETURN VALUES
.sp
.ne 2
.na
\fB\fBDAT_SUCCESS\fR\fR
.ad
.RS 25n
The operation was successful.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_HANDLE\fR\fR
.ad
.RS 25n
The DAT handle is invalid.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_PARAMETER\fR\fR
.ad
.RS 25n
One of the parameters is invalid. For example, the address range for a local
segment fell outside the boundaries of the corresponding Local Memory Region or
the LMR handle was invalid.
.RE

.SH USAGE
.sp
.LP
Determining when an RDMA Read will start and what memory range it will read is
the Consumer's responsibility. One possibility is to have the Consumer that is
modifying memory call \fBdat_lmr_sync_rdma_read()\fR and then post a Send DTO
message that identifies the range in the body of the Send. The Consumer wanting
to perform the RDMA Read can receive this message and know when it is safe to
initiate the RDMA Read operation.
.sp
.LP
This call ensures that the Provider receives a coherent view of the buffer
contents upon a subsequent remote RDMA Read operation. After the call
completes, the Consumer can be assured that all platform-specific buffer and
cache updates have been performed, and that the LMR range has consistency with
the Provider hardware. Any subsequent write by the Consumer can void this
consistency. The Provider is not required to detect such access.
.sp
.LP
The action performed on the cache before the RDMA Read depends on the cache
type:
.RS +4
.TP
.ie t \(bu
.el o
I/O noncoherent cache will be invalidated.
.RE
.RS +4
.TP
.ie t \(bu
.el o
CPU noncoherent cache will be flushed.
.RE
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Standard: uDAPL, 1.2
_
MT-Level	Unsafe
.TE

.SH SEE ALSO
.sp
.LP
\fBdat_lmr_sync_rdma_write\fR(3DAT), \fBlibdat\fR(3LIB), \fBattributes\fR(5)