Direct Access Transport Library Functions datrmrbind(3DAT)
NAME
datrmrbind - bind the RMR to the specified memory region
within an LMR
SYNOPSIS
cc [ flag... ] file... -ldat [ library... ]
#include
DATRETURN
datrmrbind(
IN DATRMRHANDLE rmrhandle,
IN DATLMRTRIPLET *lmrtriplet,
IN DATMEMPRIVFLAGS memprivileges,
IN DATEPHANDLE ephandle,
IN DATRMRCOKIE usercookie,
IN DATCOMPLETIONFLAGS completionflags,
OUT DATRMRCONTEXT *rmrcontext
)
PARAMETERS
rmrhandle Handle for an RMR instance.
lmrtriplet A pointer to an lmrtriplet that defines
the memory region of the LMR.
memprivileges Consumer-requested memory access
privileges for the registered remote
memory region. The Default value is
DATMEMPRIVNONEFLAG. The constant
value DATMEMPRIVALFLAG = 0x33,
which specifies both Read and Write
privileges, is also defined. Memory
privilege definitions are as follows:
Remote Read DATMEMPRIVREMOTEREADFLAG
0x02 Remote read
access
requested.
Remote Write DATMEMPRIVREMOTEWRITEFLAG
0x20 Remote write
access
requested.
SunOS 5.11 Last change: 16 Jul 2004 1
Direct Access Transport Library Functions datrmrbind(3DAT)
ephandle Endpoint to which datrmrbind() is
posted.
usercookie User-provided cookie that is returned to
a Consumer at the completion of the
datrmrbind(). Can be NUL.
completionflags Flags for RMR Bind. The default
DATCOMPLETIONDEFAULTFLAG is 0. Flag
definitions are as follows:
Completion Suppression DATCOMPLETIONSUPRESFLAG
0x01 Suppress
suc-
cess-
ful
Com-
ple-
tion.
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
SunOS 5.11 Last change: 16 Jul 2004 2
Direct Access Transport Library Functions datrmrbind(3DAT)
0x08 Request
for
Bar-
rier
Fence.
rmrcontext New rmrcontext for the bound RMR suit-
able to be shared with a remote host.
DESCRIPTION
The datrmrbind() function binds the RMR to the specified
memory region within an LMR and provides the new rmrcontext
value. The datrmrbind() operation is a lightweight asyn-
chronous operation that generates a new rmrcontext. The
Consumer is notified of the completion of this operation
through a rmrbind Completion event on the
requestevdhandle of the specified Endpoint ephandle.
The return value of rmrcontext can be transferred by local
Consumer to a Consumer on a remote host to be used for an
RDMA DTO. The use of rmrcontext by a remote host for an
RDMA DTO prior to the completion of the datrmrbind() can
result in an error and a broken connection. The local Consu-
mer can ensure that the remote Consumer does not have
rmrcontext before datrmrbind() is completed. One way is
to "wait" for the completion datrmrbind() on the rmrbind
Event Dispatcher of the specified Endpoint ephandle.
Another way is to send rmrcontext in a Send DTO over the
connection of the Endpoint ephandle. The barrier-fencing
behavior of the datrmrbind() with respect to Send and RDMA
DTOs ensures that a Send DTO does not start until
datrmrbind() completed.
The datrmrbind() function automatically fences all Send,
RDMA Read, and RDMA Write DTOs and datrmrbind() operations
submitted on the Endpoint ephandle after the
datrmrbind(). Therefore, none of these operations starts
until datrmrbind() is completed.
If the RMR Bind fails after datrmrbind() returns, connec-
tion of ephandle is broken. The Endpoint transitions into a
DATEPSTATEDISCONECTED state and the
DATCONECTIONEVENTBROKEN event is delivered to the
connectevdhandle of the Endpoint.
SunOS 5.11 Last change: 16 Jul 2004 3
Direct Access Transport Library Functions datrmrbind(3DAT)
The datrmrbind() function employs fencing to ensure that
operations sending the RMR Context on the same Endpoint as
the bind specified cannot result in an error from the peer
side using the delivered RMR Context too soon. One method,
used by InfiniBand, is to ensure that none of these opera-
tions start on the Endpoint until after the bind is com-
pleted. Other transports can employ different methods to
achieve the same goal.
Any RDMA DTO that uses the previous value of rmrcontext
after the datrmrbind() is completed fail and report a pro-
tection violation.
By default, datrmrbind() generates notification comple-
tions.
The memprivileges parameter allows Consumers to restrict
the type of remote accesses to the registered RMR by RDMA
DTOs. Providers whose underlying Transports require that
privileges of the requested RMR and the associated LMR
match, that is
o Set RMR's DATMEMPRIVREMOTEREADFLAG requires
that LMR's DATMEMPRIVLOCALREADFLAG is also
set,
o Set RMR's DATMEMPRIVREMOTEWRITEFLAG requires
that LMR's DATMEMPRIVLOCALWRITEFLAG is also
set,
or the operation fails and returns DATPRIVILEGESVIOLATION.
In the lmrtriplet, the value of length of zero means that
the Consumer does not want to associate an RMR with any
memory region within the LMR and the return value of
rmrcontext for that case is undefined.
The completion of the posted RMR Bind 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.
SunOS 5.11 Last change: 16 Jul 2004 4
Direct Access Transport Library Functions datrmrbind(3DAT)
The usercookie parameter allows Consumers to have unique
identifiers for each datrmrbind(). These identifiers are
completely under user control and are opaque to the Pro-
vider. The Consumer is not required to ensure the uniqueness
of the usercookie value. The usercookie is returned to the
Consumer in the rmrbind Completion event for this opera-
tion.
The operation is valid for the Endpoint in the
DATEPSTATECONECTED and DATEPSTATEDISCONECTED states.
If the operation returns successfully for the Endpoint in
DATEPSTATEDISCONECTED state, the posted RMR Bind is
immediately flushed to requestevdhandle.
RETURN VALUES
DATSUCES The operation was successful.
DATINSUFICIENTRESOURCES The operation failed due to
resource limitations.
DATINVALIDPARAMETER Invalid parameter. For exam-
ple, the targetaddress or
segmentlength exceeded the
limits of the existing LMR.
DATINVALIDHANDLE Invalid DAT handle.
DATINVALIDSTATE Parameter in an invalid state.
Endpoint was not in the a
DATEPSTATECONECTED or
DATEPSTATEDISCONECTED
state.
DATMODELNOTSUPORTED The requested Model was not
supported by the Provider.
DATPRIVILEGESVIOLATION Privileges violation for local
or remote memory access.
DATPROTECTIONVIOLATION Protection violation for local
or remote memory access.
SunOS 5.11 Last change: 16 Jul 2004 5
Direct Access Transport Library Functions datrmrbind(3DAT)
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 6
|
