xref: /illumos-gate/usr/src/lib/udapl/libdat/include/dat/udat.h (revision 03494a9880d80f834bec10a1e8f0a2f8f7c97bf4)
1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License (the "License").
6  * You may not use this file except in compliance with the License.
7  *
8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9  * or http://www.opensolaris.org/os/licensing.
10  * See the License for the specific language governing permissions
11  * and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL HEADER in each
14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15  * If applicable, add the following below this CDDL HEADER, with the
16  * fields enclosed by brackets "[]" replaced with your own identifying
17  * information: Portions Copyright [yyyy] [name of copyright owner]
18  *
19  * CDDL HEADER END
20  */
21 /*
22  * Copyright (c) 2002-2004, Network Appliance, Inc. All rights reserved.
23  */
24 
25 /*
26  * Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
27  * Use is subject to license terms.
28  */
29 
30 
31 #ifndef _UDAT_H_
32 #define	_UDAT_H_
33 
34 /*
35  *
36  * HEADER: udat.h
37  *
38  * PURPOSE: defines the user DAT API
39  *
40  * Description: Header file for "uDAPL: User Direct Access Programming
41  *              Library, Version: 1.2"
42  *
43  * Mapping rules:
44  *      All global symbols are prepended with "DAT_" or "dat_"
45  *      All DAT objects have an 'api' tag which, such as 'ep' or 'lmr'
46  *      The method table is in the provider definition structure.
47  *
48  *
49  */
50 
51 #ifdef __cplusplus
52 extern "C" {
53 #endif
54 
55 #include <dat/udat_config.h>
56 
57 #include <dat/dat_platform_specific.h>
58 
59 typedef enum dat_mem_type
60 {
61 	/* Shared between udat and kdat */
62 	DAT_MEM_TYPE_VIRTUAL		= 0x00,
63 	DAT_MEM_TYPE_LMR		= 0x01,
64 	/* udat specific */
65 	DAT_MEM_TYPE_SHARED_VIRTUAL	= 0x02,
66 	DAT_MEM_TYPE_SO_VIRTUAL		= 0x03
67 } DAT_MEM_TYPE;
68 
69 /* dat handle types */
70 typedef enum dat_handle_type
71 {
72 	DAT_HANDLE_TYPE_CR,
73 	DAT_HANDLE_TYPE_EP,
74 	DAT_HANDLE_TYPE_EVD,
75 	DAT_HANDLE_TYPE_IA,
76 	DAT_HANDLE_TYPE_LMR,
77 	DAT_HANDLE_TYPE_PSP,
78 	DAT_HANDLE_TYPE_PZ,
79 	DAT_HANDLE_TYPE_RMR,
80 	DAT_HANDLE_TYPE_RSP,
81 	DAT_HANDLE_TYPE_CNO,
82 	DAT_HANDLE_TYPE_SRQ
83 } DAT_HANDLE_TYPE;
84 
85 /*
86  * EVD state consists of 3 orthogonal substates. One for
87  * enabled/disabled, one for waitable/unwaitable, and one
88  * for configuration. Within each substates the values are
89  * mutually exclusive.
90  */
91 typedef enum dat_evd_state
92 {
93 	DAT_EVD_STATE_ENABLED 		= 0x01,
94 	DAT_EVD_STATE_DISABLED 		= 0x02,
95 	DAT_EVD_STATE_WAITABLE 		= 0x04,
96 	DAT_EVD_STATE_UNWAITABLE 	= 0x08,
97 	DAT_EVD_STATE_CONFIG_NOTIFY 	= 0x10,
98 	DAT_EVD_STATE_CONFIG_SOLICITED 	= 0x20,
99 	DAT_EVD_STATE_CONFIG_THRESHOLD 	= 0x30
100 } DAT_EVD_STATE;
101 
102 typedef enum dat_evd_param_mask
103 {
104 	DAT_EVD_FIELD_IA_HANDLE    	= 0x01,
105 	DAT_EVD_FIELD_EVD_QLEN		= 0x02,
106 	DAT_EVD_FIELD_EVD_STATE    	= 0x04,
107 	DAT_EVD_FIELD_CNO		= 0x08,
108 	DAT_EVD_FIELD_EVD_FLAGS		= 0x10,
109 
110 	DAT_EVD_FIELD_ALL		= 0x1F
111 } DAT_EVD_PARAM_MASK;
112 
113 typedef DAT_UINT64 DAT_PROVIDER_ATTR_MASK;
114 
115 #include <dat/dat.h>
116 
117 typedef DAT_HANDLE	DAT_CNO_HANDLE;
118 
119 struct dat_evd_param
120 {
121 	DAT_IA_HANDLE		ia_handle;
122 	DAT_COUNT		evd_qlen;
123 	DAT_EVD_STATE		evd_state;
124 	DAT_CNO_HANDLE		cno_handle;
125 	DAT_EVD_FLAGS		evd_flags;
126 };
127 
128 #define	DAT_LMR_COOKIE_SIZE 40 /* size of DAT_LMR_COOKIE in bytes */
129 typedef char (* DAT_LMR_COOKIE)[DAT_LMR_COOKIE_SIZE];
130 
131 /* Format for OS wait proxy agent function */
132 
133 typedef void (*DAT_AGENT_FUNC)(
134 	DAT_PVOID,	/* instance data   */
135 	DAT_EVD_HANDLE  /* Event Dispatcher*/);
136 
137 /* Definition */
138 
139 typedef struct dat_os_wait_proxy_agent
140 {
141 	DAT_PVOID instance_data;
142 	DAT_AGENT_FUNC proxy_agent_func;
143 } DAT_OS_WAIT_PROXY_AGENT;
144 
145 /* Define NULL Proxy agent */
146 
147 #define	DAT_OS_WAIT_PROXY_AGENT_NULL \
148 	(DAT_OS_WAIT_PROXY_AGENT) { \
149 	(DAT_PVOID) NULL, \
150 	(DAT_AGENT_FUNC) NULL }
151 
152 
153 /* Flags */
154 
155 /*
156  * The value specified by the uDAPL Consumer for dat_ia_open to indicate
157  * that not async EVD should be created for the opening instance of an IA.
158  * The same IA have been open before that has the only async EVD to
159  * handle async errors for all open instances of the IA.
160  */
161 
162 #define	DAT_EVD_ASYNC_EXISTS (DAT_EVD_HANDLE) 0x1
163 
164 /*
165  * The value return by the dat_ia_query for the case when there is no
166  * async EVD for the IA instance. Consumer had specified the value of
167  * DAT_EVD_ASYNC_EXISTS for the async_evd_handle for dat_ia_open.
168  */
169 
170 #define	DAT_EVD_OUT_OF_SCOPE (DAT_EVD_HANDLE) 0x2
171 
172 /*
173  * Memory types
174  *
175  * Specifing memory type for LMR create. A consumer must use a single
176  * value when registering memory. The union of any of these
177  * flags is used in the provider parameters to indicate what memory
178  * type provider supports for LMR memory creation.
179  */
180 
181 
182 
183 /* For udapl only */
184 
185 typedef struct dat_shared_memory
186 {
187 	DAT_PVOID		virtual_address;
188 	DAT_LMR_COOKIE		shared_memory_id;
189 } DAT_SHARED_MEMORY;
190 
191 typedef union dat_region_description
192 {
193 	DAT_PVOID		for_va;
194 	DAT_LMR_HANDLE		for_lmr_handle;
195 	DAT_SHARED_MEMORY	for_shared_memory;	/* For udapl only */
196 } DAT_REGION_DESCRIPTION;
197 
198 /* LMR Arguments */
199 
200 struct dat_lmr_param
201 {
202 	DAT_IA_HANDLE		ia_handle;
203 	DAT_MEM_TYPE		mem_type;
204 	DAT_REGION_DESCRIPTION	region_desc;
205 	DAT_VLEN		length;
206 	DAT_PZ_HANDLE		pz_handle;
207 	DAT_MEM_PRIV_FLAGS	mem_priv;
208 	DAT_LMR_CONTEXT		lmr_context;
209 	DAT_RMR_CONTEXT		rmr_context;
210 	DAT_VLEN		registered_size;
211 	DAT_VADDR		registered_address;
212 };
213 
214 
215 typedef struct dat_cno_param
216 {
217 	DAT_IA_HANDLE		ia_handle;
218 	DAT_OS_WAIT_PROXY_AGENT	agent;
219 } DAT_CNO_PARAM;
220 
221 typedef enum dat_cno_param_mask
222 {
223 	DAT_CNO_FIELD_IA_HANDLE	= 0x1,
224 	DAT_CNO_FIELD_AGENT	= 0x2,
225 
226 	DAT_CNO_FIELD_ALL	= 0x3
227 } DAT_CNO_PARAM_MASK;
228 
229 
230 /* General Provider attributes. udat specific. */
231 typedef enum dat_pz_support
232 {
233 	DAT_PZ_UNIQUE,
234 	DAT_PZ_SAME,
235 	DAT_PZ_SHAREABLE
236 } DAT_PZ_SUPPORT;
237 
238 /*
239  * Provider should support merging of all event stream types. Provider
240  * attribute specify support for merging different event stream types.
241  * It is a 2D binary matrix where each row and column represents an event
242  * stream type. Each binary entry is 1 if the event streams of its raw
243  * and column can fed the same EVD, and 0 otherwise. The order of event
244  * streams in row and column is the same as in the definition of
245  * DAT_EVD_FLAGS: index 0 - Software Event, 1- Connection Request,
246  * 2 - DTO Completion, 3 - Connection event, 4 - RMR Bind Completion,
247  * 5 - Asynchronous event. By definition each diagonal entry is 1.
248  * Consumer allocates an array for it and passes it IN as a pointer
249  * for the array that Provider fills. Provider must fill the array
250  * that Consumer passes.
251  */
252 
253 struct dat_provider_attr
254 {
255 	char				provider_name[DAT_NAME_MAX_LENGTH];
256 	DAT_UINT32			provider_version_major;
257 	DAT_UINT32			provider_version_minor;
258 	DAT_UINT32			dapl_version_major;
259 	DAT_UINT32			dapl_version_minor;
260 	DAT_MEM_TYPE			lmr_mem_types_supported;
261 	DAT_IOV_OWNERSHIP		iov_ownership_on_return;
262 	DAT_QOS				dat_qos_supported;
263 	DAT_COMPLETION_FLAGS		completion_flags_supported;
264 	DAT_BOOLEAN			is_thread_safe;
265 	DAT_COUNT			max_private_data_size;
266 	DAT_BOOLEAN			supports_multipath;
267 	DAT_EP_CREATOR_FOR_PSP		ep_creator;
268 	DAT_PZ_SUPPORT			pz_support;
269 	DAT_UINT32			optimal_buffer_alignment;
270 	const DAT_BOOLEAN		evd_stream_merging_supported[6][6];
271 	DAT_BOOLEAN			srq_supported;
272 	DAT_COUNT			srq_watermarks_supported;
273 	DAT_BOOLEAN			srq_ep_pz_difference_supported;
274 	DAT_COUNT			srq_info_supported;
275 	DAT_COUNT			ep_recv_info_supported;
276 	DAT_BOOLEAN			lmr_sync_req;
277 	DAT_BOOLEAN			dto_async_return_guaranteed;
278 	DAT_BOOLEAN			rdma_write_for_rdma_read_req;
279 	DAT_COUNT			num_provider_specific_attr;
280 	DAT_NAMED_ATTR *		provider_specific_attr;
281 };
282 
283 #define	DAT_PROVIDER_FIELD_PROVIDER_NAME		UINT64_C(0x0000001)
284 #define	DAT_PROVIDER_FIELD_PROVIDER_VERSION_MAJOR	UINT64_C(0x0000002)
285 #define	DAT_PROVIDER_FIELD_PROVIDER_VERSION_MINOR	UINT64_C(0x0000004)
286 #define	DAT_PROVIDER_FIELD_DAPL_VERSION_MAJOR		UINT64_C(0x0000008)
287 #define	DAT_PROVIDER_FIELD_DAPL_VERSION_MINOR		UINT64_C(0x0000010)
288 #define	DAT_PROVIDER_FIELD_LMR_MEM_TYPE_SUPPORTED	UINT64_C(0x0000020)
289 #define	DAT_PROVIDER_FIELD_IOV_OWNERSHIP		UINT64_C(0x0000040)
290 #define	DAT_PROVIDER_FIELD_DAT_QOS_SUPPORTED		UINT64_C(0x0000080)
291 #define	DAT_PROVIDER_FIELD_COMPLETION_FLAGS_SUPPORTED	UINT64_C(0x0000100)
292 #define	DAT_PROVIDER_FIELD_IS_THREAD_SAFE		UINT64_C(0x0000200)
293 #define	DAT_PROVIDER_FIELD_MAX_PRIVATE_DATA_SIZE	UINT64_C(0x0000400)
294 #define	DAT_PROVIDER_FIELD_SUPPORTS_MULTIPATH		UINT64_C(0x0000800)
295 #define	DAT_PROVIDER_FIELD_EP_CREATOR			UINT64_C(0x0001000)
296 #define	DAT_PROVIDER_FIELD_PZ_SUPPORT			UINT64_C(0x0002000)
297 #define	DAT_PROVIDER_FIELD_OPTIMAL_BUFFER_ALIGNMENT	UINT64_C(0x0004000)
298 #define	DAT_PROVIDER_FIELD_EVD_STREAM_MERGING_SUPPORTED	UINT64_C(0x0008000)
299 #define	DAT_PROVIDER_FIELD_SRQ_SUPPORTED		UINT64_C(0x0010000)
300 #define	DAT_PROVIDER_FIELD_SRQ_WATERMARKS_SUPPORTED	UINT64_C(0x0020000)
301 #define	DAT_PROVIDER_FIELD_SRQ_EP_PZ_DIFFERENCE_SUPPORTED \
302 							UINT64_C(0x0040000)
303 #define	DAT_PROVIDER_FIELD_SRQ_INFO_SUPPORTED		UINT64_C(0x0080000)
304 #define	DAT_PROVIDER_FIELD_EP_RECV_INFO_SUPPORTED	UINT64_C(0x0100000)
305 #define	DAT_PROVIDER_FIELD_LMR_SYNC_REQ			UINT64_C(0x0200000)
306 #define	DAT_PROVIDER_FIELD_DTO_ASYNC_RETURN_GUARANTEED	UINT64_C(0x0400000)
307 #define	DAT_PROVIDER_FIELD_RDMA_WRITE_FOR_RDMA_READ_REQ	UINT64_C(0x0800000)
308 #define	DAT_PROVIDER_FIELD_NUM_PROVIDER_SPECIFIC_ATTR	UINT64_C(0x1000000)
309 #define	DAT_PROVIDER_FIELD_PROVIDER_SPECIFIC_ATTR	UINT64_C(0x2000000)
310 
311 #define	DAT_PROVIDER_FIELD_ALL				UINT64_C(0x3FFFFFF)
312 #define	DAT_PROVIDER_FIELD_NONE				UINT64_C(0x0)
313 
314 #include <dat/udat_vendor_specific.h>
315 
316 /* ************************************************************************ */
317 
318 /*
319  * User DAT functions definitions.
320  */
321 
322 
323 extern DAT_RETURN dat_lmr_create(
324 	IN	DAT_IA_HANDLE,		/* ia_handle		*/
325 	IN	DAT_MEM_TYPE,		/* mem_type		*/
326 	IN	DAT_REGION_DESCRIPTION,	/* region_description   */
327 	IN	DAT_VLEN,		/* length		*/
328 	IN	DAT_PZ_HANDLE,		/* pz_handle		*/
329 	IN	DAT_MEM_PRIV_FLAGS,	/* privileges		*/
330 	OUT	DAT_LMR_HANDLE *,	/* lmr_handle		*/
331 	OUT	DAT_LMR_CONTEXT *,	/* lmr_context		*/
332 	OUT	DAT_RMR_CONTEXT *,	/* rmr_context		*/
333 	OUT	DAT_VLEN *,		/* registered_length	*/
334 	OUT	DAT_VADDR *);		/* registered_address   */
335 
336 /* Event Functions */
337 
338 extern DAT_RETURN dat_evd_create(
339 	IN	DAT_IA_HANDLE,		/* ia_handle		*/
340 	IN	DAT_COUNT,		/* evd_min_qlen		*/
341 	IN	DAT_CNO_HANDLE,		/* cno_handle		*/
342 	IN	DAT_EVD_FLAGS,		/* evd_flags		*/
343 	OUT	DAT_EVD_HANDLE *);	/* evd_handle		*/
344 
345 extern DAT_RETURN dat_evd_modify_cno(
346 	IN	DAT_EVD_HANDLE,		/* evd_handle		*/
347 	IN	DAT_CNO_HANDLE);	/* cno_handle		*/
348 
349 extern DAT_RETURN dat_cno_create(
350 	IN	DAT_IA_HANDLE,		/* ia_handle		*/
351 	IN	DAT_OS_WAIT_PROXY_AGENT,	/* agent		*/
352 	OUT	DAT_CNO_HANDLE *);	/* cno_handle		*/
353 
354 extern DAT_RETURN dat_cno_modify_agent(
355 	IN	DAT_CNO_HANDLE,			/* cno_handle		*/
356 	IN	DAT_OS_WAIT_PROXY_AGENT);	/* agent		*/
357 
358 extern DAT_RETURN dat_cno_query(
359 	IN	DAT_CNO_HANDLE,		/* cno_handle		*/
360 	IN	DAT_CNO_PARAM_MASK,	/* cno_param_mask	*/
361 	OUT	DAT_CNO_PARAM *);	/* cno_param		*/
362 
363 extern DAT_RETURN dat_cno_free(
364 	IN DAT_CNO_HANDLE);		/* cno_handle		*/
365 
366 extern DAT_RETURN dat_cno_wait(
367 	IN	DAT_CNO_HANDLE,		/* cno_handle		*/
368 	IN	DAT_TIMEOUT,		/* timeout		*/
369 	OUT	DAT_EVD_HANDLE *);	/* evd_handle		*/
370 
371 extern DAT_RETURN dat_evd_enable(
372 	IN	DAT_EVD_HANDLE);	/* evd_handle		*/
373 
374 extern DAT_RETURN dat_evd_wait(
375 	IN	DAT_EVD_HANDLE,		/* evd_handle		*/
376 	IN	DAT_TIMEOUT,		/* Timeout		*/
377 	IN	DAT_COUNT,		/* Threshold		*/
378 	OUT	DAT_EVENT *,		/* event		*/
379 	OUT	DAT_COUNT *);		/* N more events	*/
380 
381 extern DAT_RETURN dat_evd_disable(
382 	IN	DAT_EVD_HANDLE);	/* evd_handle		*/
383 
384 extern DAT_RETURN dat_evd_set_unwaitable(
385 	IN DAT_EVD_HANDLE);		/* evd_handle */
386 
387 extern DAT_RETURN dat_evd_clear_unwaitable(
388 	IN DAT_EVD_HANDLE); /* evd_handle */
389 
390 #ifdef __cplusplus
391 }
392 #endif
393 
394 #endif /* _UDAT_H_ */
395