1dat_ep_create_with_sDriqr(e3cDtATA)ccess Transport LibrarydFautn_cetpi_ocnrseate_with_srq(3DAT)
2
6 dat_ep_create_with_srq - create an instance of End Point with Shared
7 Receive Queue
8
10 cc [ flag... ] file... -ldat [ library... ]
11 #include <dat/udat.h>
12 DAT_RETURN
14 dat_ep_create_with_srq (
15 IN DAT_IA_HANDLE ia_handle,
16 IN DAT_PZ_HANDLE pz_handle,
17 IN DAT_EVD_HANDLE recv_evd_handle,
18 IN DAT_EVD_HANDLE request_evd_handle,
19 IN DAT_EVD_HANDLE connect_evd_handle,
20 IN DAT_SRQ_HANDLE srq_handle,
21 IN DAT_EP_ATTR *ep_attributes,
22 OUT DAT_EP_HANDLE *ep_handle
23 )
24
27 ia_handle Handle for an open instance of the IA to which
28 the created Endpoint belongs.
29 pz_handle Handle for an instance of the Protection Zone.
32 recv_evd_handle Handle for the Event Dispatcher where events for
35 completions of incoming (receive) DTOs are
36 reported. DAT_HANDLE_NULL specifies that the Con‐
37 sumer is not interested in events for completions
38 of receives.
39 request_evd_handle Handle for the Event Dispatcher where events for
42 completions of outgoing (Send, RDMA Write, RDMA
43 Read, and RMR Bind) DTOs are reported. DAT_HAN‐
44 DLE_NULL specifies that the Consumer is not
45 interested in events for completions of requests.
46 connect_evd_handle Handle for the Event Dispatcher where Connection
49 events are reported. DAT_HANDLE_NULL specifies
50 that the Consumer is not interested in connection
51 events for now.
52 srq_handle Handle for an instance of the Shared Receive
55 Queue.
56 ep_attributes Pointer to a structure that contains Consumer-
59 requested Endpoint attributes. Cannot be NULL.
60 ep_handle Handle for the created instance of an Endpoint.
63
66 The dat_ep_create_with_srq() function creates an instance of an End‐
67 point that is using SRQ for Recv buffers is provided to the Consumer as
68 ep_handle. The value of ep_handle is not defined if the DAT_RETURN is
69 not DAT_SUCCESS.
70 The Endpoint is created in the Unconnected state.
73 Protection Zone pz_handle allows Consumers to control what local memory
76 the Endpoint can access for DTOs except Recv and what memory remote
77 RDMA operations can access over the connection of a created Endpoint.
78 Only memory referred to by LMRs and RMRs that match the Endpoint Pro‐
79 tection Zone can be accessed by the Endpoint. The Recv DTO buffers PZ
80 must match the SRQ PZ. The SRQ PZ might or might not be the same as the
81 EP one. Check Provider attribute for the support of different PZs
82 between SRQ and its EPs.
83 The recv_evd_handle and request_evd_handle arguments are Event Dis‐
86 patcher instances where the Consumer collects completion notifications
87 of DTOs. Completions of Receive DTOs are reported in recv_evd_handle
88 Event Dispatcher, and completions of Send, RDMA Read, and RDMA Write
89 DTOs are reported in request_evd_handle Event Dispatcher. All comple‐
90 tion notifications of RMR bindings are reported to a Consumer in
91 request_evd_handle Event Dispatcher.
92 All Connection events for the connected Endpoint are reported to the
95 Consumer through connect_evd_handle Event Dispatcher.
96 Shared Receive Queue srq_handle specifies where the EP will dequeue
99 Recv DTO buffers.
100 The created EP can be reset. The relationship between SRQ and EP is not
103 effected by dat_ep_reset(3DAT).
104 SRQ can not be disassociated or replaced from created EP. The only way
107 to disassociate SRQ from EP is to destroy EP.
108 Receive buffers cannot be posted to the created Endpoint. Receive buf‐
111 fers must be posted to the SRQ to be used for the created Endpoint.
112 The ep_attributes parameter specifies the initial attributes of the
115 created Endpoint. Consumer can not specify NULL for ep_attributes but
116 can specify values only for the parameters needed and default for the
117 rest.
118 For max_request_dtos and max_request_iov, the created Endpoint will
121 have at least the Consumer requested values but might have larger val‐
122 ues. Consumer can query the created Endpoint to find out the actual
123 values for these attributes. Created Endpoint has the exact Consumer
124 requested values for max_recv_dtos, max_message_size, max_rdma_size,
125 max_ rdma_read_in, and max_rdma_read_out. For all other attributes,
126 except max_recv_iov that is ignored, the created Endpoint has the exact
127 values requested by Consumer. If Provider cannot satisfy the Consumer
128 requested attribute values the operation fails.
129
131 DAT_SUCCESS The operation was successful.
132 DAT_INSUFFICIENT_RESOURCES The operation failed due to resource lim‐
135 itations.
136 DAT_INVALID_HANDLE Invalid DAT handle.
139 DAT_INVALID_PARAMETER Invalid parameter. One of the requested
142 EP parameters or attributes was invalid
143 or a combination of attributes or parame‐
144 ters is invalid. For example, pz_handle
145 specified does not match the one for SRQ
146 or the requested maximum RDMA Read IOV
147 exceeds IA capabilities..
148 DAT_MODEL_NOT_SUPPORTED The requested Provider Model was not sup‐
151 ported.
152
155 The Consumer creates an Endpoint prior to the establishment of a con‐
156 nection. The created Endpoint is in DAT_EP_STATE_UNCONNECTED. Consumers
157 can do the following:
158 1. Request a connection on the Endpoint through dat_ep_con‐
160 nect(3DAT) or dat_ep_dup_connect(3DAT) for the active side
161 of the connection model.
162 2. Associate the Endpoint with the Pending Connection Request
164 that does not have an associated local Endpoint for accept‐
165 ing the Pending Connection Request for the passive/server
166 side of the con-nection model.
167 3. Create a Reserved Service Point with the Endpoint for the
169 passive/server side of the connection model. Upon arrival of
170 a Connection Request on the Service Point, the Consumer
171 accepts the Pending Connection Request that has the Endpoint
172 associated with it.
173 The Consumer cannot specify a request_evd_handle (recv_evd_handle) with
176 Request Completion Flags (Recv Completion Flags) that do not match the
177 other Endpoint Completion Flags for the DTO/RMR completion streams that
178 use the same EVD. If request_evd_handle (recv_evd_ handle) is used for
179 request (recv) completions of an Endpoint whose associated Request
180 (Recv) Completion Flag attribute is DAT_COMPLETION_UNSIGNALLED_FLAG,
181 the Request Completion Flags and Recv Completion Flags for all Endpoint
182 completion streams that use the EVD must specify the same. By defini‐
183 tion, completions of all Recv DTO posted to SRQ complete with Signal.
184 Analogously, if recv_evd_handle is used for recv completions of an End‐
185 point whose associated Recv Completion Flag attribute is DAT_COMPLE‐
186 TION_SOLICITED_WAIT, the Recv Completion Flags for all Endpoint Recv
187 completion streams that use the same EVD must specify the same Recv
188 Completion Flags attribute value and the EVD cannot be used for any
189 other event stream types. If recv_evd_handle is used for Recv comple‐
190 tions of an Endpoint that uses SRQ and whose Recv Completion Flag
191 attribute is DAT_COMPLETION_EVD_THRESHOLD then all Endpoint DTO comple‐
192 tion streams (request and/or recv completion streams) that use that
193 recv_evd_handle must specify DAT_COMPLETION_EVD_THRESHOLD. Other event
194 stream types can also use the same EVD.
195 Consumers might want to use DAT_COMPLETION_UNSIGNALLED_FLAG for Request
198 and/or Recv completions when they control locally with posted DTO/RMR
199 completion flag (not needed for Recv posted to SRQ) whether posted
200 DTO/RMR completes with Signal or not. Consumers might want to use
201 DAT_COMPLETION_SOLICITED_WAIT for Recv completions when the remote
202 sender side control whether posted Recv competes with Signal or not or
203 not. uDAPL Consumers might want to use DAT_COMPLETION_EVD_THRESHOLD for
204 Request and/or Recv completions when they control waiter unblocking
205 with the threshold parameter of the dat_evd_wait(3DAT).
206 Some Providers might restrict whether multiple EPs that share a SRQ can
209 have different Protection Zones. Check the srq_ep_pz_difference_support
210 Provider attribute for it.
211 Consumers might want to have a different PZ between EP and SRQ. This
214 allows incoming RDMA operations to be specific to this EP PZ and not
215 the same for all EPs that share SRQ. This is critical for servers that
216 supports multiple independent clients.
217 The Provider is strongly encouraged to create an EP that is ready to be
220 connected. Any effects of previous connections or connection establish‐
221 ment attempts on the underlying Transport-specific Endpoint to which
222 the DAT Endpoint is mapped to should be hidden from the Consumer. The
223 methods described below are examples:
224 o The Provider does not create an underlying Transport End‐
226 point until the Consumer is connecting the Endpoint or
227 accepting a connection request on it. This allows the
228 Provider to accumulate Consumer requests for attribute set‐
229 tings even for attributes that the underlying transport does
230 not allow to change after the Transport Endpoint is created.
231 o The Provider creates the underlying Transport Endpoint or
233 chooses one from a pool of Provider-controlled Transport
234 Endpoints when the Consumer creates the Endpoint. The
235 Provider chooses the Transport Endpoint that is free from
236 any underlying internal attributes that might prevent the
237 Endpoint from being connected. For IB and IP, that means
238 that the Endpoint is not in the TimeWait state. Changing of
239 some of the Endpoint attributes becomes hard and might
240 potentially require mapping the Endpoint to another underly‐
241 ing Transport Endpoint that might not be feasible for all
242 transports.
243 o The Provider allocates a Transport-specific Endpoint without
245 worrying about impact on it from previous connections or
246 connection establishment attempts. Hide the Transport-spe‐
247 cific TimeWait state or CM timeout of the underlying trans‐
248 port Endpoint within dat_ep_connect(3DAT), dat_ep_dup_con‐
249 nect(3DAT), or dat_cr_accept(3DAT). On the Active side of
250 the connection establishment, if the remnants of a previous
251 connection for Transport-specific Endpoint can be hidden
252 within the Timeout parameter, do so. If not, generating
253 DAT_CONNECTION_ EVENT_NON_PEER_REJECTED is an option. For
254 the Passive side, generating a DAT_CONNECTION_COMPLE‐
255 TION_ERROR event locally, while sending a non-peer-reject
256 message to the active side, is a way of handling it.
257 Any transitions of an Endpoint into an Unconnected state can be handled
260 similarly. One transition from a Disconnected to an Unconnected state
261 is a special case.
262 For dat_ep_reset(3DAT), the Provider can hide any remnants of the pre‐
265 vious connection or failed connection establishment in the operation
266 itself. Because the operation is synchronous, the Provider can block
267 in it until the TimeWait state effect of the previous connection or
268 connection setup is expired, or until the Connection Manager timeout of
269 an unsuccessful connection establishment attempt is expired. Alterna‐
270 tively, the Provider can create a new Endpoint for the Consumer that
271 uses the same handle.
272 DAT Providers are required not to change any Consumer-specified End‐
275 point attributes during connection establishment. If the Consumer does
276 not specify an attribute, the Provider can set it to its own default.
277 Some EP attributes, like outstanding RDMA Read incoming or outgoing, if
278 not set up by the Consumer, can be changed by Providers to establish
279 connection. It is recommended that the Provider pick the default for
280 outstanding RDMA Read attributes as 0 if the Consumer has not specified
281 them. This ensures that connection establishment does not fail due to
282 insufficient outstanding RDMA Read resources, which is a requirement
283 for the Provider.
284 The Provider is not required to check for a mismatch between the maxi‐
287 mum RDMA Read IOV and maximum RDMA Read outgoing attributes, but is
288 allowed to do so. In the later case it is allowed to return
289 DAT_INVALID_ PARAMETER when a mismatch is detected. Provider must allo‐
290 cate resources to satisfy the combination of these two EP attributes
291 for local RDMA Read DTOs.
292
294 See attributes(5) for descriptions of the following attributes:
295 ┌─────────────────────────────┬─────────────────────────────┐
300 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
301 ├─────────────────────────────┼─────────────────────────────┤
302 │Interface Stability │Standard: uDAPL, 1.2 │
303 ├─────────────────────────────┼─────────────────────────────┤
304 │MT-Level │Safe │
305 └─────────────────────────────┴─────────────────────────────┘
306
308 dat_ep_create(3DAT), dat_srq_create(3DAT), dat_srq_free(3DAT),
309 dat_srq_query(3DAT), libdat(3LIB), attributes(5)
310SunOS 5.11 16 Jul 2004 dat_ep_create_with_srq(3DAT)