1dat_ep_create(3DAT)Direct Access Transport Library Functionsdat_ep_create(3DAT)
2
6 dat_ep_create - create an instance of an Endpoint
7
9 cc [ flag... ] file... -ldat [ library... ]
10 #include <dat/udat.h>
11 DAT_RETURN
13 dat_ep_create (
14 IN DAT_IA_HANDLE ia_handle,
15 IN DAT_PZ_HANDLE pz_handle,
16 IN DAT_EVD_HANDLE recv_evd_handle,
17 IN DAT_EVD_HANDLE request_evd_handle,
18 IN DAT_EVD_HANDLE connect_evd_handle,
19 IN DAT_EP_ATTR *ep_attributes,
20 OUT DAT_EP_HANDLE *ep_handle
21 )
22
25 ia_handle Handle for an open instance of the IA to which
26 the created Endpoint belongs.
27 pz_handle Handle for an instance of the Protection Zone.
30 recv_evd_handle Handle for the Event Dispatcher where events for
33 completions of incoming (receive) DTOs are
34 reported. DAT_HANDLE_NULL specifies that the Con‐
35 sumer is not interested in events for completions
36 of receives.
37 request_evd_handle Handle for the Event Dispatcher where events for
40 completions of outgoing (Send, RDMA Write, RDMA
41 Read, and RMR Bind) DTOs are reported. DAT_HAN‐
42 DLE_NULL specifies that the Consumer is not
43 interested in events for completions of requests.
44 connect_evd_handle Handle for the Event Dispatcher where Connection
47 events are reported. DAT_HANDLE_NULL specifies
48 that the Consumer is not interested in connection
49 events for now.
50 ep_attributes Pointer to a structure that contains Consumer-
53 requested Endpoint attributes. Can be NULL.
54 ep_handle Handle for the created instance of an Endpoint.
57
60 The dat_ep_create() function creates an instance of an Endpoint that is
61 provided to the Consumer as ep_handle. The value of ep_handle is not
62 defined if the DAT_RETURN is not DAT_SUCCESS.
63 The Endpoint is created in the Unconnected state.
66 Protection Zone pz_handle allows Consumers to control what local memory
69 the Endpoint can access for DTOs and what memory remote RDMA operations
70 can access over the connection of a created Endpoint. Only memory
71 referred to by LMRs and RMRs that match the Endpoint Protection Zone
72 can be accessed by the Endpoint.
73 The recv_evd_handle and request_evd_handle parameters are Event Dis‐
76 patcher instances where the Consumer collects completion notifications
77 of DTOs. Completions of Receive DTOs are reported in recv_evd_handle
78 Event Dispatcher, and completions of Send, RDMA Read, and RDMA Write
79 DTOs are reported in request_evd_handle Event Dispatcher. All comple‐
80 tion notifications of RMR bindings are reported to a Consumer in
81 request_evd_handle Event Dispatcher.
82 All Connection events for the connected Endpoint are reported to the
85 Consumer through connect_evd_handle Event Dispatcher.
86 The ep_attributes parameter specifies the initial attributes of the
89 created Endpoint. If the Consumer specifies NULL, the Provider fills it
90 with its default Endpoint attributes. The Consumer might not be able to
91 do any posts to the Endpoint or use the Endpoint in connection estab‐
92 lishment until certain Endpoint attributes are set. Maximum Message
93 Size and Maximum Recv DTOs are examples of such attributes.
94
96 DAT_SUCCESS The operation was successful.
97 DAT_INSUFFICIENT_RESOURCES The operation failed due to resource lim‐
100 itations.
101 DAT_INVALID_HANDLE Invalid DAT handle.
104 DAT_INVALID_PARAMETER Invalid parameter. One of the requested
107 EP parameters or attributes was invalid
108 or a combination of attributes or parame‐
109 ters is invalid.
110 DAT_MODEL_NOT_SUPPORTED The requested Provider Model was not sup‐
113 ported.
114
117 The Consumer creates an Endpoint prior to the establishment of a con‐
118 nection. The created Endpoint is in DAT_EP_STATE_UNCONNECTED. Consumers
119 can do the following:
120 1. Request a connection on the Endpoint through dat_ep_con‐
122 nect(3DAT) or dat_ep_dup_connect(3DAT) for the active side
123 of the connection model.
124 2. Associate the Endpoint with the Pending Connection Request
126 that does not have an associated local Endpoint for accept‐
127 ing the Pending Connection Request for the passive/server
128 side of the connection model.
129 3. Create a Reserved Service Point with the Endpoint for the
131 passive/server side of the connection model. Upon arrival of
132 a Connection Request on the Service Point, the Consumer
133 accepts the Pending Connection Request that has the Endpoint
134 associated with it
135 The Consumer cannot specify a request_evd_handle (recv_evd_handle) with
138 Request Completion Flags (Recv Completion Flags) that do not match the
139 other Endpoint Completion Flags for the DTO/RMR completion streams that
140 use the same EVD. If request_evd_handle (recv_evd_handle) is used for
141 an EVD that is fed by any event stream other than DTO or RMR completion
142 event streams, only DAT_COMPLETION_THRESHOLD is valid for Request/Recv
143 Completion Flags for the Endpoint completion streams that use that EVD.
144 If request_evd_handle (recv_evd_handle) is used for request (recv) com‐
145 pletions of an Endpoint whose associated Request (Recv) Completion Flag
146 attribute is DAT_COMPLETION_UNSIGNALLED_FLAG, the Request Completion
147 Flags and Recv Completion Flags for all Endpoint completion streams
148 that use the EVD must specify the same. Analogously, if recv_evd_handle
149 is used for recv completions of an Endpoint whose associated Recv Com‐
150 pletion Flags attribute is DAT_COMPLETION_SOLICITED_WAIT, the Recv Com‐
151 pletion Flags for all Endpoint Recv completion streams that use the
152 same EVD must specify the same Recv Completion Flags attribute value
153 and the EVD cannot be used for any other event stream types.
154 If EP is created with NULL attributes, Provider can fill them with its
157 own default values. The Consumer should not rely on the Provider-filled
158 attribute defaults, especially for portable applications. The Consumer
159 cannot do any operations on the created Endpoint except for
160 dat_ep_query(3DAT), dat_ep_get_status(3DAT), dat_ep_modify(3DAT), and
161 dat_ep_free(3DAT), depending on the values that the Provider picks.
162 The Provider is encouraged to pick up reasonable defaults because
165 unreasonable values might restrict Consumers to the dat_ep_query(),
166 dat_ep_get_status(), dat_ep_modify(), and dat_ep_free() operations. The
167 Consumer should check what values the Provider picked up for the
168 attributes. It is especially important to make sure that the number of
169 posted operations is not too large to avoid EVD overflow. Depending on
170 the values picked up by the Provider, the Consumer might not be able to
171 do any RDMA operations; it might only be able to send or receive mes‐
172 sages of very small sizes, or it might not be able to have more than
173 one segment in a buffer. Before doing any operations, except the ones
174 listed above, the Consumer can configure the Endpoint using dat_ep_mod‐
175 ify() to the attributes they want.
176 One reason the Consumer might still want to create an Endpoint with
179 Null attributes is for the Passive side of the connection establish‐
180 ment, where the Consumer sets up Endpoint attributes based on the con‐
181 nection request of the remote side.
182 Consumers might want to create Endpoints with NULL attributes if End‐
185 point properties are negotiated as part the Consumer connection estab‐
186 lishment protocol.
187 Consumers that create Endpoints with Provider default attributes should
190 always verify that the Provider default attributes meet their applica‐
191 tion's requirements with regard to the number of request/receive DTOs
192 that can be posted, maximum message sizes, maximum request/receive IOV
193 sizes, and maximum RDMA sizes.
194
196 See attributes(5) for descriptions of the following attributes:
197 ┌─────────────────────────────┬─────────────────────────────┐
202 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
203 ├─────────────────────────────┼─────────────────────────────┤
204 │Interface Stability │Standard: uDAPL, 1.1, 1.2 │
205 ├─────────────────────────────┼─────────────────────────────┤
206 │MT-Level │Safe │
207 └─────────────────────────────┴─────────────────────────────┘
208
210 dat_ep_connect(3DAT), dat_ep_dup_connect(3DAT), dat_ep_free(3DAT),
211 dat_ep_get_status(3DAT), dat_ep_modify(3DAT), dat_ep_query(3DAT), lib‐
212 dat(3LIB), attributes(5)
213SunOS 5.11 16 Jul 2004 dat_ep_create(3DAT)