usr/src/lib/udapl/libdat/include/dat/udat.h

   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_ */