Direct Access Transport Library Functions
dateppostrdmaread(3DAT)
NAME
dateppostrdmaread - transfer all data to the local data
buffer
SYNOPSIS
cc [ flag... ] file... -ldat [ library... ]
#include
DATRETURN
dateppostrdmaread (
IN DATEPHANDLE ephandle,
IN DATCOUNT numsegments,
IN DATLMRTRIPLET *localiov,
IN DATDTOCOKIE usercookie,
IN DATRMRTRIPLET *remotebuffer,
IN DATCOMPLETIONFLAGS completionflags
)
PARAMETERS
ephandle Handle for an instance of the Endpoint.
numsegments Number of lmrtriplets in localiov.
localiov I/O Vector that specifies the local
buffer to fill.
usercookie User-provided cookie that is returned to
the Consumer at the completion of the
RDMA Read. Can be NUL.
remotebuffer A pointer to an RMR Triplet that speci-
fies the remote buffer from which the
data is read.
completionflags Flags for posted RDMA Read. The default
DATCOMPLETIONDEFAULTFLAG is 0x00.
Other values are as follows:
Completion Suppression DATCOMPLETIONSUPRESFLAG
0x01 Suppress
suc-
cess-
ful
Completion.
SunOS 5.11 Last change: 16 Jul 2004 1
Direct Access Transport Library Functions
dateppostrdmaread(3DAT)
Notification of Completion DATCOMPLETIONUNSIGNALEDFLAG
0x04 Non-
notification
com-
ple-
tion.
Local
End-
point
must
be
con-
fig-
ured
for
Notif-
i-
ca-
tion
Suppres-
sion.
Barrier Fence DATCOMPLETIONBARIERFENCEFLAG
0x08 Request
for
Bar-
rier
Fence.
DESCRIPTION
The dateppostrdmaread() function requests the transfer
of all the data specified by the remotebuffer over the con-
nection of the ephandle Endpoint into the localiov.
The numsegments parameter specifies the number of segments
in the localiov. The localiov segments are filled in the
I/O Vector order until the whole message is received. This
ensures that all the "front" segments of the localiov I/O
Vector are completely filled, only one segment is partially
filled, if needed, and all segments that follow it are not
filled at all.
SunOS 5.11 Last change: 16 Jul 2004 2
Direct Access Transport Library Functions
dateppostrdmaread(3DAT)
The usercookie allows Consumers to have unique identifiers
for each DTO. These identifiers are completely under user
control and are opaque to the Provider. There is no require-
ment on the Consumer that the value usercookie should be
unique for each DTO. The usercookie is returned to the Con-
sumer in the Completion event for the posted RDMA Read.
A Consumer must not modify the localiov or its content
until the DTO is completed. When a Consumer does not adhere
to this rule, the behavior of the Provider and the underly-
ing Transport is not defined. Providers that allow Consumers
to get ownership of the localiov but not the memory it
specifies back after the dateppostrdmaread() returns
should document this behavior and also specify its support
in Provider attributes. This behavior allows Consumers full
control of the localiov after dateppostrdmaread()
returns. Because this behavior is not guaranteed by all Pro-
viders, portable Consumers should not rely on this behavior.
Consumers should not rely on the Provider copying localiov
information.
The completion of the posted RDMA Read is reported to the
Consumer asynchronously through a DTO Completion event based
on the specified completionflags value. The value of
DATCOMPLETIONUNSIGNALEDFLAG is only valid if the End-
point Request Completion Flags
DATCOMPLETIONUNSIGNALEDFLAG. Otherwise,
DATINVALIDPARAMETER is returned.
The DATSUCES return of the dateppostrdmaread() is at
least the equivalent of posting an RDMA Read operation
directly by native Transport. Providers should avoid
resource allocation as part of dateppostrdmaread() to
ensure that this operation is nonblocking and thread safe
for an UpCall.
The operation is valid for the Endpoint in the
DATEPSTATECONECTED and DATEPSTATEDISCONECTED states.
If the operation returns successfully for the Endpoint in
the DATEPSTATEDISCONECTED state, the posted RDMA Read is
immediately flushed to requestevdhandle.
RETURN VALUES
DATSUCES The operation was successful.
SunOS 5.11 Last change: 16 Jul 2004 3
Direct Access Transport Library Functions
dateppostrdmaread(3DAT)
DATINSUFICIENTRESOURCES The operation failed due to
resource limitations.
DATINVALIDPARAMETER Invalid parameter. For exam-
ple, one of the IOV segments
pointed to a memory outside
its LMR.
DATINVALIDHANDLE The ephandle parameter is
invalid.
DATINVALIDSTATE A parameter is in an invalid
state. Endpoint was not in the
DATEPSTATECONECTED or
DATEPSTATEDISCONECTED
state.
DATLENGTHEROR The size of the receiving
buffer is too small for send-
ing buffer data. The size of
the local buffer is too small
for the data of the remote
buffer.
DATPROTECTIONVIOLATION Protection violation for local
or remote memory access. Pro-
tection Zone mismatch between
either an LMR of one of the
localiov segments and the
local Endpoint or the
rmrcontext and the remote
Endpoint.
DATPRIVILEGESVIOLATION Privileges violation for local
or remote memory access.
Either one of the LMRs used in
localiov is invalid or does
not have the local write
privileges, or rmrcontext
does not have the remote read
privileges.
USAGE
SunOS 5.11 Last change: 16 Jul 2004 4
Direct Access Transport Library Functions
dateppostrdmaread(3DAT)
For best RDMA Read operation performance, the Consumer
should align each buffer segment of localiov to the Optimal
Buffer Alignment attribute of the Provider. For portable
applications, the Consumer should align each buffer segment
of localiov to the DATOPTIMALALIGNMENT.
If connection was established without outstanding RDMA Read
attributes matching on Endpoints on both sides (outstanding
RDMA Read outgoing on one end is larger than the outstanding
RDMA Read incoming on the other end), connection is broken
when the number of incoming RDMA Read exceeds the outstand-
ing RDMA Read incoming attribute of the Endpoint. The Consu-
mer can use its own flow control to ensure that it does not
post more RDMA Reads then the remote EP outstanding RDMA
Read incoming attribute is. Thus, they do not rely on the
underlying Transport enforcing it.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Standard: uDAPL, 1.1, 1.2
MT-Level Unsafe
SEE ALSO
libdat(3LIB), attributes(5)
SunOS 5.11 Last change: 16 Jul 2004 5
Direct Access Transport Library Functions
dateppostrdmaread(3DAT)
SunOS 5.11 Last change: 16 Jul 2004 6
|
