1dat_ep_create_with_sDriqr(e3cDtATA)ccess Transport LibrarydFautn_cetpi_ocnrseate_with_srq(3DAT)
2
3
4

NAME

6       dat_ep_create_with_srq  -  create  an instance of End Point with Shared
7       Receive Queue
8

SYNOPSIS

10       cc [ flag... ] file... -ldat [ library... ]
11       #include <dat/udat.h>
12
13       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
25

PARAMETERS

27       ia_handle             Handle for an open instance of the  IA  to  which
28                             the created Endpoint belongs.
29
30
31       pz_handle             Handle for an instance of the Protection Zone.
32
33
34       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
40
41       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
47
48       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
53
54       srq_handle            Handle for an  instance  of  the  Shared  Receive
55                             Queue.
56
57
58       ep_attributes         Pointer  to  a  structure that contains Consumer-
59                             requested Endpoint attributes. Cannot be NULL.
60
61
62       ep_handle             Handle for the created instance of an Endpoint.
63
64

DESCRIPTION

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
71
72       The Endpoint is created in the Unconnected state.
73
74
75       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
84
85       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
93
94       All Connection events for the connected Endpoint are  reported  to  the
95       Consumer through connect_evd_handle Event Dispatcher.
96
97
98       Shared  Receive  Queue  srq_handle  specifies where the EP will dequeue
99       Recv DTO buffers.
100
101
102       The created EP can be reset. The relationship between SRQ and EP is not
103       effected by dat_ep_reset(3DAT).
104
105
106       SRQ  can not be disassociated or replaced from created EP. The only way
107       to disassociate SRQ from EP is to destroy EP.
108
109
110       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
113
114       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
119
120       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

RETURN VALUES

131       DAT_SUCCESS                   The operation was successful.
132
133
134       DAT_INSUFFICIENT_RESOURCES    The operation failed due to resource lim‐
135                                     itations.
136
137
138       DAT_INVALID_HANDLE            Invalid DAT handle.
139
140
141       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
149
150       DAT_MODEL_NOT_SUPPORTED       The requested Provider Model was not sup‐
151                                     ported.
152
153

USAGE

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
159           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
163           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
168           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
174
175       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
196
197       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
207
208       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
212
213       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
218
219       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
225           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
232           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
244           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
258
259       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
263
264       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
273
274       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
285
286       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

ATTRIBUTES

294       See attributes(5) for descriptions of the following attributes:
295
296
297
298
299       ┌─────────────────────────────┬─────────────────────────────┐
300       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
301       ├─────────────────────────────┼─────────────────────────────┤
302       │Interface Stability          │Standard: uDAPL, 1.2         │
303       ├─────────────────────────────┼─────────────────────────────┤
304       │MT-Level                     │Safe                         │
305       └─────────────────────────────┴─────────────────────────────┘
306

SEE ALSO

308       dat_ep_create(3DAT),      dat_srq_create(3DAT),     dat_srq_free(3DAT),
309       dat_srq_query(3DAT), libdat(3LIB), attributes(5)
310
311
312
313SunOS 5.11                        16 Jul 2004     dat_ep_create_with_srq(3DAT)
Impressum