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]
dat_ep_create_with_srq - create an instance of End Point with Shared Receive Queue

cc [ flag.\|.\|. ] file.\|.\|. -ldat [ library.\|.\|. ]
#include <dat/udat.h>

DAT_RETURN
 dat_ep_create_with_srq (
 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_SRQ_HANDLE srq_handle,
 IN DAT_EP_ATTR *ep_attributes,
 OUT DAT_EP_HANDLE *ep_handle
 )

ia_handle pz_handle recv_evd_handle request_evd_handle connect_evd_handle srq_handle ep_attributes ep_handle

The dat_ep_create_with_srq() function creates an instance of an Endpoint that is using SRQ for Recv buffers is provided to the Consumer as ep_handle. The value of ep_handle is not defined if the DAT_RETURN is not DAT_SUCCESS.

The Endpoint is created in the Unconnected state.

Protection Zone pz_handle 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 different PZs between SRQ and its EPs.

The recv_evd_handle and request_evd_handle arguments are Event Dispatcher instances where the Consumer collects completion notifications of DTOs. Completions of Receive DTOs are reported in recv_evd_handle Event Dispatcher, and completions of Send, RDMA Read, and RDMA Write DTOs are reported in request_evd_handle Event Dispatcher. All completion notifications of RMR bindings are reported to a Consumer in request_evd_handle Event Dispatcher.

All Connection events for the connected Endpoint are reported to the Consumer through connect_evd_handle Event Dispatcher.

Shared Receive Queue srq_handle 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 dat_ep_reset(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 ep_attributes parameter specifies the initial attributes of the created Endpoint. Consumer can not specify NULL for ep_attributes but can specify values only for the parameters needed and default for the rest.

For max_request_dtos and max_request_iov, the created Endpoint 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 max_recv_dtos, max_message_size, max_rdma_size, max_ rdma_read_in, and max_rdma_read_out. For all other attributes, except max_recv_iov that is ignored, the created Endpoint has the exact values requested by Consumer. If Provider cannot satisfy the Consumer requested attribute values the operation fails.

DAT_SUCCESS DAT_INSUFFICIENT_RESOURCES DAT_INVALID_HANDLE DAT_INVALID_PARAMETER DAT_MODEL_NOT_SUPPORTED

The Consumer creates an Endpoint prior to the establishment of a connection. The created Endpoint is in DAT_EP_STATE_UNCONNECTED. Consumers can do the following:

The Consumer cannot specify a request_evd_handle (recv_evd_handle) 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 request_evd_handle (recv_evd_ handle) is used for request (recv) completions of an Endpoint whose associated Request (Recv) Completion Flag attribute is DAT_COMPLETION_UNSIGNALLED_FLAG, the Request Completion Flags and Recv Completion Flags for all Endpoint completion streams that use the EVD must specify the same. By definition, completions of all Recv DTO posted to SRQ complete with Signal. Analogously, if recv_evd_handle is used for recv completions of an Endpoint whose associated Recv Completion Flag attribute is DAT_COMPLETION_SOLICITED_WAIT, 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. If recv_evd_handle is used for Recv completions of an Endpoint that uses SRQ and whose Recv Completion Flag attribute is DAT_COMPLETION_EVD_THRESHOLD then all Endpoint DTO completion streams (request and/or recv completion streams) that use that recv_evd_handle must specify DAT_COMPLETION_EVD_THRESHOLD. Other event stream types can also use the same EVD.

Consumers might want to use DAT_COMPLETION_UNSIGNALLED_FLAG 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 DAT_COMPLETION_SOLICITED_WAIT 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 DAT_COMPLETION_EVD_THRESHOLD for Request and/or Recv completions when they control waiter unblocking with the threshold parameter of the dat_evd_wait(3DAT).

Some Providers might restrict whether multiple EPs that share a SRQ can have different Protection Zones. Check the srq_ep_pz_difference_support 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:

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 dat_ep_reset(3DAT), the Provider can hide any remnants of the previous connection or failed connection establishment in the operation itself. Because the operation is synchronous, 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 establishment. 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 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 connection establishment does not fail due to insufficient outstanding 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 DAT_INVALID_ PARAMETER when a mismatch is detected. Provider must allocate resources to satisfy the combination of these two EP attributes for local RDMA Read DTOs.

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Interface Stability Standard: uDAPL, 1.2

MT-Level Safe

dat_ep_create(3DAT), dat_srq_create(3DAT), dat_srq_free(3DAT), dat_srq_query(3DAT), libdat(3LIB), attributes(5)