Direct Access Transport Library Functions
datepcreatewithsrq(3DAT)
NAME
datepcreatewithsrq - create an instance of End Point
with Shared Receive Queue
SYNOPSIS
cc [ flag... ] file... -ldat [ library... ]
#include
DATRETURN
datepcreatewithsrq (
IN DATIAHANDLE iahandle,
IN DATPZHANDLE pzhandle,
IN DATEVDHANDLE recvevdhandle,
IN DATEVDHANDLE requestevdhandle,
IN DATEVDHANDLE connectevdhandle,
IN DATSRQHANDLE srqhandle,
IN DATEPATR *epattributes,
OUT DATEPHANDLE *ephandle
)
PARAMETERS
iahandle Handle for an open instance of the IA
to which the created Endpoint belongs.
pzhandle Handle for an instance of the Protec-
tion Zone.
recvevdhandle Handle for the Event Dispatcher where
events for completions of incoming
(receive) DTOs are reported.
DATHANDLENUL specifies that the
Consumer is not interested in events
for completions of receives.
requestevdhandle Handle for the Event Dispatcher where
events for completions of outgoing
(Send, RDMA Write, RDMA Read, and RMR
Bind) DTOs are reported.
DATHANDLENUL specifies that the
Consumer is not interested in events
for completions of requests.
connectevdhandle Handle for the Event Dispatcher where
Connection events are reported.
DATHANDLENUL specifies that the
Consumer is not interested in
SunOS 5.11 Last change: 16 Jul 2004 1
Direct Access Transport Library Functions
datepcreatewithsrq(3DAT)
connection events for now.
srqhandle Handle for an instance of the Shared
Receive Queue.
epattributes Pointer to a structure that contains
Consumer-requested Endpoint attri-
butes. Cannot be NUL.
ephandle Handle for the created instance of an
Endpoint.
DESCRIPTION
The datepcreatewithsrq() function creates an instance of
an Endpoint that is using SRQ for Recv buffers is provided
to the Consumer as ephandle. The value of ephandle is not
defined if the DATRETURN is not DATSUCES.
The Endpoint is created in the Unconnected state.
Protection Zone pzhandle allows Consumers to control what
local memory the Endpoint can access for DTOs except Recv
and what memory remote RDMA operations can access over the
connection of a created Endpoint. Only memory referred to by
LMRs and RMRs that match the Endpoint Protection Zone can be
accessed by the Endpoint. The Recv DTO buffers PZ must match
the SRQ PZ. The SRQ PZ might or might not be the same as the
EP one. Check Provider attribute for the support of dif-
ferent PZs between SRQ and its EPs.
The recvevdhandle and requestevdhandle arguments are
Event Dispatcher instances where the Consumer collects com-
pletion notifications of DTOs. Completions of Receive DTOs
are reported in recvevdhandle Event Dispatcher, and com-
pletions of Send, RDMA Read, and RDMA Write DTOs are
reported in requestevdhandle Event Dispatcher. All comple-
tion notifications of RMR bindings are reported to a Consu-
mer in requestevdhandle Event Dispatcher.
All Connection events for the connected Endpoint are
reported to the Consumer through connectevdhandle Event
Dispatcher.
SunOS 5.11 Last change: 16 Jul 2004 2
Direct Access Transport Library Functions
datepcreatewithsrq(3DAT)
Shared Receive Queue srqhandle specifies where the EP will
dequeue Recv DTO buffers.
The created EP can be reset. The relationship between SRQ
and EP is not effected by datepreset(3DAT).
SRQ can not be disassociated or replaced from created EP.
The only way to disassociate SRQ from EP is to destroy EP.
Receive buffers cannot be posted to the created Endpoint.
Receive buffers must be posted to the SRQ to be used for the
created Endpoint.
The epattributes parameter specifies the initial attributes
of the created Endpoint. Consumer can not specify NUL for
epattributes but can specify values only for the parameters
needed and default for the rest.
For maxrequestdtos and maxrequestiov, the created End-
point will have at least the Consumer requested values but
might have larger values. Consumer can query the created
Endpoint to find out the actual values for these attributes.
Created Endpoint has the exact Consumer requested values for
maxrecvdtos, maxmessagesize, maxrdmasize, max
rdmareadin, and maxrdmareadout. For all other attri-
butes, except maxrecviov that is ignored, the created End-
point has the exact values requested by Consumer. If Pro-
vider cannot satisfy the Consumer requested attribute values
the operation fails.
RETURN VALUES
DATSUCES The operation was successful.
DATINSUFICIENTRESOURCES The operation failed due to
resource limitations.
DATINVALIDHANDLE Invalid DAT handle.
DATINVALIDPARAMETER Invalid parameter. One of the
requested EP parameters or
attributes was invalid or a
combination of attributes or
parameters is invalid. For
SunOS 5.11 Last change: 16 Jul 2004 3
Direct Access Transport Library Functions
datepcreatewithsrq(3DAT)
example, pzhandle specified
does not match the one for SRQ
or the requested maximum RDMA
Read IOV exceeds IA capabili-
ties..
DATMODELNOTSUPORTED The requested Provider Model
was not supported.
USAGE
The Consumer creates an Endpoint prior to the establishment
of a connection. The created Endpoint is in
DATEPSTATEUNCONECTED. Consumers can do the following:
1. Request a connection on the Endpoint through
datepconnect(3DAT) or datepdupconnect(3DAT)
for the active side of the connection model.
2. Associate the Endpoint with the Pending Connection
Request that does not have an associated local End-
point for accepting the Pending Connection Request
for the passive/server side of the con-nection
model.
3. Create a Reserved Service Point with the Endpoint
for the passive/server side of the connection
model. Upon arrival of a Connection Request on the
Service Point, the Consumer accepts the Pending
Connection Request that has the Endpoint associated
with it.
The Consumer cannot specify a requestevdhandle
(recvevdhandle) with Request Completion Flags (Recv Com-
pletion Flags) that do not match the other Endpoint Comple-
tion Flags for the DTO/RMR completion streams that use the
same EVD. If requestevdhandle (recvevd handle) is used
for request (recv) completions of an Endpoint whose associ-
ated Request (Recv) Completion Flag attribute is
DATCOMPLETIONUNSIGNALEDFLAG, the Request Completion
Flags and Recv Completion Flags for all Endpoint completion
streams that use the EVD must specify the same. By defini-
tion, completions of all Recv DTO posted to SRQ complete
with Signal. Analogously, if recvevdhandle is used for
recv completions of an Endpoint whose associated Recv Com-
pletion Flag attribute is DATCOMPLETIONSOLICITEDWAIT, the
Recv Completion Flags for all Endpoint Recv completion
streams that use the same EVD must specify the same Recv
Completion Flags attribute value and the EVD cannot be used
SunOS 5.11 Last change: 16 Jul 2004 4
Direct Access Transport Library Functions
datepcreatewithsrq(3DAT)
for any other event stream types. If recvevdhandle is used
for Recv completions of an Endpoint that uses SRQ and whose
Recv Completion Flag attribute is
DATCOMPLETIONEVDTHRESHOLD then all Endpoint DTO comple-
tion streams (request and/or recv completion streams) that
use that recvevdhandle must specify
DATCOMPLETIONEVDTHRESHOLD. Other event stream types can
also use the same EVD.
Consumers might want to use DATCOMPLETIONUNSIGNALEDFLAG
for Request and/or Recv completions when they control
locally with posted DTO/RMR completion flag (not needed for
Recv posted to SRQ) whether posted DTO/RMR completes with
Signal or not. Consumers might want to use
DATCOMPLETIONSOLICITEDWAIT for Recv completions when the
remote sender side control whether posted Recv competes with
Signal or not or not. uDAPL Consumers might want to use
DATCOMPLETIONEVDTHRESHOLD for Request and/or Recv comple-
tions when they control waiter unblocking with the threshold
parameter of the datevdwait(3DAT).
Some Providers might restrict whether multiple EPs that
share a SRQ can have different Protection Zones. Check the
srqeppzdifferencesupport Provider attribute for it.
Consumers might want to have a different PZ between EP and
SRQ. This allows incoming RDMA operations to be specific to
this EP PZ and not the same for all EPs that share SRQ. This
is critical for servers that supports multiple independent
clients.
The Provider is strongly encouraged to create an EP that is
ready to be connected. Any effects of previous connections
or connection establishment attempts on the underlying
Transport-specific Endpoint to which the DAT Endpoint is
mapped to should be hidden from the Consumer. The methods
described below are examples:
o The Provider does not create an underlying Tran-
sport Endpoint until the Consumer is connecting the
Endpoint or accepting a connection request on it.
This allows the Provider to accumulate Consumer
requests for attribute settings even for attributes
that the underlying transport does not allow to
change after the Transport Endpoint is created.
o The Provider creates the underlying Transport
SunOS 5.11 Last change: 16 Jul 2004 5
Direct Access Transport Library Functions
datepcreatewithsrq(3DAT)
Endpoint or chooses one from a pool of Provider-
controlled Transport Endpoints when the Consumer
creates the Endpoint. The Provider chooses the
Transport Endpoint that is free from any underlying
internal attributes that might prevent the Endpoint
from being connected. For IB and IP, that means
that the Endpoint is not in the TimeWait state.
Changing of some of the Endpoint attributes becomes
hard and might potentially require mapping the End-
point to another underlying Transport Endpoint that
might not be feasible for all transports.
o The Provider allocates a Transport-specific End-
point without worrying about impact on it from pre-
vious connections or connection establishment
attempts. Hide the Transport-specific TimeWait
state or CM timeout of the underlying transport
Endpoint within datepconnect(3DAT),
datepdupconnect(3DAT), or datcraccept(3DAT).
On the Active side of the connection establishment,
if the remnants of a previous connection for
Transport-specific Endpoint can be hidden within
the Timeout parameter, do so. If not, generating
DATCONECTION EVENTNONPEREJECTED is an
option. For the Passive side, generating a
DATCONECTIONCOMPLETIONEROR event locally,
while sending a non-peer-reject message to the
active side, is a way of handling it.
Any transitions of an Endpoint into an Unconnected state can
be handled similarly. One transition from a Disconnected to
an Unconnected state is a special case.
For datepreset(3DAT), the Provider can hide any remnants
of the previous connection or failed connection establish-
ment in the operation itself. Because the operation is syn-
chronous, the Provider can block in it until the TimeWait
state effect of the previous connection or connection setup
is expired, or until the Connection Manager timeout of an
unsuccessful connection establishment attempt is expired.
Alternatively, the Provider can create a new Endpoint for
the Consumer that uses the same handle.
DAT Providers are required not to change any Consumer-
specified Endpoint attributes during connection establish-
ment. If the Consumer does not specify an attribute, the
Provider can set it to its own default. Some EP attributes,
like outstanding RDMA Read incoming or outgoing, if not set
SunOS 5.11 Last change: 16 Jul 2004 6
Direct Access Transport Library Functions
datepcreatewithsrq(3DAT)
up by the Consumer, can be changed by Providers to establish
connection. It is recommended that the Provider pick the
default for outstanding RDMA Read attributes as 0 if the
Consumer has not specified them. This ensures that connec-
tion establishment does not fail due to insufficient out-
standing RDMA Read resources, which is a requirement for the
Provider.
The Provider is not required to check for a mismatch between
the maximum RDMA Read IOV and maximum RDMA Read outgoing
attributes, but is allowed to do so. In the later case it is
allowed to return DATINVALID PARAMETER when a mismatch is
detected. Provider must allocate resources to satisfy the
combination of these two EP attributes for local RDMA Read
DTOs.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Standard: uDAPL, 1.2
MT-Level Safe
SEE ALSO
datepcreate(3DAT), datsrqcreate(3DAT),
datsrqfree(3DAT), datsrqquery(3DAT), libdat(3LIB),
attributes(5)
SunOS 5.11 Last change: 16 Jul 2004 7
Direct Access Transport Library Functions
datepcreatewithsrq(3DAT)
SunOS 5.11 Last change: 16 Jul 2004 8
|
