'\" 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_EP_CREATE 3DAT "Jul 16, 2004"
.SH NAME
dat_ep_create \- create an instance of an Endpoint
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <\fBdat/udat.h\fR>

DAT_RETURN
    dat_ep_create (
    IN    DAT_IA_HANDLE    ia_handle,
    IN    DAT_PZ_HANDLE    pz_handle,
    IN    DAT_EVD_HANDLE   recv_evd_handle,
    IN    DAT_EVD_HANDLE   request_evd_handle,
    IN    DAT_EVD_HANDLE   connect_evd_handle,
    IN    DAT_EP_ATTR      *ep_attributes,
    OUT   DAT_EP_HANDLE    *ep_handle
    )
.fi

.SH PARAMETERS
.sp
.ne 2
.na
\fB\fIia_handle\fR\fR
.ad
.RS 22n
Handle for an open instance of the IA to which the created Endpoint belongs.
.RE

.sp
.ne 2
.na
\fB\fIpz_handle\fR\fR
.ad
.RS 22n
Handle for an instance of the Protection Zone.
.RE

.sp
.ne 2
.na
\fB\fIrecv_evd_handle\fR\fR
.ad
.RS 22n
Handle for the Event Dispatcher where events for completions of incoming
(receive) DTOs are reported. \fBDAT_HANDLE_NULL\fR specifies that the Consumer
is not interested in events for completions of receives.
.RE

.sp
.ne 2
.na
\fB\fIrequest_evd_handle\fR\fR
.ad
.RS 22n
Handle for the Event Dispatcher where events for completions of outgoing (Send,
RDMA Write, RDMA Read, and RMR Bind) DTOs are reported. \fBDAT_HANDLE_NULL\fR
specifies that the Consumer is not interested in events for completions of
requests.
.RE

.sp
.ne 2
.na
\fB\fIconnect_evd_handle\fR\fR
.ad
.RS 22n
Handle for the Event Dispatcher where Connection events are reported.
\fBDAT_HANDLE_NULL\fR specifies that the Consumer is not interested in
connection events for now.
.RE

.sp
.ne 2
.na
\fB\fIep_attributes\fR\fR
.ad
.RS 22n
Pointer to a structure that contains Consumer-requested Endpoint attributes.
Can be \fINULL\fR.
.RE

.sp
.ne 2
.na
\fB\fIep_handle\fR\fR
.ad
.RS 22n
Handle for the created instance of an Endpoint.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBdat_ep_create()\fR function creates an instance of an Endpoint that is
provided to the Consumer as \fIep_handle\fR. The value of \fIep_handle\fR is
not defined if the \fBDAT_RETURN\fR is not \fBDAT_SUCCESS\fR.
.sp
.LP
The Endpoint is created in the Unconnected state.
.sp
.LP
Protection Zone \fIpz_handle\fR allows Consumers to control what local memory
the Endpoint can access for DTOs 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.
.sp
.LP
The \fIrecv_evd_handle\fR and \fIrequest_evd_handle\fR parameters are Event
Dispatcher instances where the Consumer collects completion notifications of
DTOs. Completions of Receive DTOs are reported in \fIrecv_evd_handle\fR Event
Dispatcher, and completions of Send, RDMA Read, and RDMA Write DTOs are
reported in \fIrequest_evd_handle\fR Event Dispatcher.  All completion
notifications of RMR bindings are reported to a Consumer in
\fIrequest_evd_handle\fR Event Dispatcher.
.sp
.LP
All Connection events for the connected Endpoint are reported to the Consumer
through \fIconnect_evd_handle\fR Event Dispatcher.
.sp
.LP
The \fIep_attributes\fR parameter specifies the initial attributes of the
created Endpoint. If the Consumer specifies \fINULL\fR, the Provider fills it
with its default Endpoint attributes. The Consumer might not be able to do any
posts to the Endpoint or use the Endpoint in connection establishment until
certain Endpoint attributes are set. Maximum Message Size and Maximum Recv DTOs
are examples of such attributes.
.SH RETURN VALUES
.sp
.ne 2
.na
\fB\fBDAT_SUCCESS\fR\fR
.ad
.RS 30n
The operation was successful.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR
.ad
.RS 30n
The operation failed due to resource limitations.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_HANDLE\fR\fR
.ad
.RS 30n
Invalid DAT handle.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_PARAMETER\fR\fR
.ad
.RS 30n
Invalid parameter. One of the requested EP parameters or attributes was invalid
or a combination of attributes or parameters is invalid.
.RE

.sp
.ne 2
.na
\fB\fBDAT_MODEL_NOT_SUPPORTED\fR\fR
.ad
.RS 30n
The requested Provider Model was not supported.
.RE

.SH USAGE
.sp
.LP
The Consumer creates an Endpoint prior to the establishment of a connection.
The created Endpoint is in \fBDAT_EP_STATE_UNCONNECTED\fR. Consumers can do the
following:
.RS +4
.TP
1.
Request a connection on the Endpoint through \fBdat_ep_connect\fR(3DAT) or
\fBdat_ep_dup_connect\fR(3DAT) for the active side of the connection model.
.RE
.RS +4
.TP
2.
Associate the Endpoint with the Pending Connection Request that does not
have an associated local Endpoint for accepting the Pending Connection Request
for the passive/server side of the connection model.
.RE
.RS +4
.TP
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
.RE
.sp
.LP
The Consumer cannot specify a \fIrequest_evd_handle\fR (\fIrecv_evd_handle\fR)
with Request Completion Flags (Recv Completion Flags) that do not match the
other Endpoint Completion Flags for the DTO/RMR completion streams that use the
same EVD. If \fIrequest_evd_handle\fR (\fIrecv_evd_handle\fR) is used for an
EVD that is fed by any event stream other than DTO or RMR completion event
streams, only \fBDAT_COMPLETION_THRESHOLD\fR is valid for Request/Recv
Completion Flags for the Endpoint completion streams that use that EVD. If
\fIrequest_evd_handle\fR (\fIrecv_evd_handle\fR) is used for request (recv)
completions of an Endpoint whose associated Request (Recv) Completion Flag
attribute is \fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR, the Request Completion
Flags and Recv Completion Flags for all Endpoint completion streams that use
the EVD must specify the same. Analogously, if \fIrecv_evd_handle\fR is used
for recv completions of an Endpoint whose associated Recv Completion Flags
attribute is \fBDAT_COMPLETION_SOLICITED_WAIT\fR, 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 for any
other event stream types.
.sp
.LP
If EP is created with \fINULL\fR attributes, Provider can fill them with its
own default values. The Consumer should not rely on the Provider-filled
attribute defaults, especially for portable applications. The Consumer cannot
do any operations on the created Endpoint except for \fBdat_ep_query\fR(3DAT),
\fBdat_ep_get_status\fR(3DAT), \fBdat_ep_modify\fR(3DAT), and
\fBdat_ep_free\fR(3DAT), depending on the values that the Provider picks.
.sp
.LP
The Provider is encouraged to pick up reasonable defaults because unreasonable
values might restrict Consumers to the \fBdat_ep_query()\fR,
\fBdat_ep_get_status()\fR, \fBdat_ep_modify()\fR, and \fBdat_ep_free()\fR
operations. The Consumer should check what values the Provider picked up for
the attributes. It is especially important to make sure that the number of
posted operations is not too large to avoid EVD overflow. Depending on the
values picked up by the Provider, the Consumer might not be able to do any RDMA
operations; it might only be able to send or receive messages of very small
sizes, or it might not be able to have more than one segment in a buffer.
Before doing any operations, except the ones listed above, the Consumer can
configure the Endpoint using \fBdat_ep_modify()\fR to the attributes they want.
.sp
.LP
One reason the Consumer might still want to create an Endpoint with Null
attributes is for the Passive side of the connection establishment, where the
Consumer sets up Endpoint attributes based on the connection request of the
remote side.
.sp
.LP
Consumers might want to create Endpoints with \fINULL\fR attributes if Endpoint
properties are negotiated as part the Consumer connection establishment
protocol.
.sp
.LP
Consumers that create Endpoints with Provider default attributes should always
verify that the Provider default attributes meet their application's
requirements with regard to the number of request/receive DTOs that can be
posted, maximum message sizes, maximum request/receive IOV sizes, and maximum
RDMA sizes.
.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.1, 1.2
_
MT-Level	Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBdat_ep_connect\fR(3DAT), \fBdat_ep_dup_connect\fR(3DAT),
\fBdat_ep_free\fR(3DAT), \fBdat_ep_get_status\fR(3DAT),
\fBdat_ep_modify\fR(3DAT), \fBdat_ep_query\fR(3DAT), \fBlibdat\fR(3LIB),
\fBattributes\fR(5)