'\" 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_WRITE 3DAT "September 22, 2020" .SH NAME dat_lmr_sync_rdma_write \- synchronize local memory with RDMA write on non-coherent memory .SH SYNOPSIS .nf cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] #include <\fBdat/udat.h\fR> DAT_RETURN dat_lmr_sync_rdma_write ( IN DAT_IA_HANDLE ia_handle, IN const DAT_LMR_TRIPLET *local_segments, IN DAT_VLEN num_segments ) .fi .SH PARAMETERS .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 The \fBdat_lmr_sync_rdma_write()\fR function makes effects of an incoming RDMA Write operation visible to the Consumer. This operation guarantees consistency by locally invalidating the non-coherent cache whose buffer has been populated by remote peer RDMA write operations. .sp .LP The \fBdat_lmr_sync_rdma_write()\fR function is needed if and only if the Provider attribute specifies that this operation is needed after an incoming RDMA Write operation. The Consumer must call \fBdat_lmr_sync_rdma_write()\fR before reading data from a memory range in this region that was the target of an incoming RDMA Write operation. The \fBdat_lmr_sync_rdma_write()\fR function must be called after the RDMA Write operation completes, and the memory range that was modified by the RDMA Write must be supplied by the caller in the \fIlocal_segments\fR array. After this call returns, the Consumer may safely see the modified contents of the memory range. It is permissible to batch synchronizations of multiple RDMA Write 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 The Consumer must also use \fBdat_lmr_sync_rdma_write()\fR when performing local writes to a memory range that was or will be the target of incoming RDMA writes. After performing the local write, the Consumer must call \fBdat_lmr_sync_rdma_write()\fR before the RDMA Write is initiated. Conversely, after an RDMA Write completes, the Consumer must call \fBdat_lmr_sync_rdma_write()\fR before performing a local write to the same range. .sp .LP If the Provider attribute specifies that this operation is needed and the Consumer attempts to read from a memory range in an LMR without properly synchronizing using \fBdat_lmr_sync_rdma_write()\fR, the returned contents are undefined. If the Consumer attempts to write to a memory range without properly synchronizing, the contents of the memory range become undefined. .SH RETURN VALUES .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 Determining when an RDMA Write completes and determining which memory range was modified is the Consumer's responsibility. One possibility is for the RDMA Write initiator to post a Send DTO message after each RDMA Write that identifies the range in the body of the Send. The Consumer at the target of the RDMA Write can receive the message and know when and how to call \fBdat_lmr_sync_rdma_write()\fR. .sp .LP This call ensures that the Provider receives a coherent view of the buffer contents after a subsequent remote RDMA Write 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 read 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 Write depends on the cache type: .RS +4 .TP .ie t \(bu .el o I/O noncoherent cache will be flushed. .RE .RS +4 .TP .ie t \(bu .el o CPU noncoherent cache will be invalidated. .RE .SH ATTRIBUTES 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 \fBdat_lmr_sync_rdma_read\fR(3DAT), \fBlibdat\fR(3LIB), \fBattributes\fR(5)