dat.h revision 7c478bd95313f5f23a4c958a745db2134aa03244
/*
* CDDL HEADER START
*
* The contents of this file are subject to the terms of the
* Common Development and Distribution License, Version 1.0 only
* (the "License"). You may not use this file except in compliance
* with the License.
*
* You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
* See the License for the specific language governing permissions
* and limitations under the License.
*
* When distributing Covered Code, include this CDDL HEADER in each
* file and include the License file at usr/src/OPENSOLARIS.LICENSE.
* If applicable, add the following below this CDDL HEADER, with the
* fields enclosed by brackets "[]" replaced with your own identifying
* information: Portions Copyright [yyyy] [name of copyright owner]
*
* CDDL HEADER END
*/
/*
* Copyright (c) 2002-2004, Network Appliance, Inc. All rights reserved.
*/
/*
* Copyright 2004 Sun Microsystems, Inc. All rights reserved.
* Use is subject to license terms.
*/
#ifndef _DAT_H_
#define _DAT_H_
#pragma ident "%Z%%M% %I% %E% SMI"
/*
*
* HEADER: dat.h
*
* PURPOSE: defines the common DAT API for uDAPL and kDAPL.
*
* Description: Header file for "uDAPL: User Direct Access Programming
* Library, Version: 1.2"
*
* Mapping rules:
* All global symbols are prepended with "DAT_" or "dat_"
* All DAT objects have an 'api' tag which, such as 'ep' or 'lmr'
* The method table is in the provider definition structure.
*
*
*/
#ifdef __cplusplus
extern "C" {
#endif
#include <dat/dat_error.h>
/* Generic DAT types */
typedef char *DAT_NAME_PTR; /* Format for ia_name and attributes */
#define DAT_NAME_MAX_LENGTH 256
/*
* Used for provider, vendor, transport, hardware specific attributes
* definitions.
*/
typedef struct dat_named_attr {
const char *name; /* Name of attribute */
const char *value; /* Value of attribute */
typedef enum dat_boolean {
DAT_FALSE = 0,
DAT_TRUE = 1
} DAT_BOOLEAN;
typedef union dat_context {
} DAT_CONTEXT;
typedef DAT_CONTEXT DAT_DTO_COOKIE;
typedef DAT_CONTEXT DAT_RMR_COOKIE;
typedef enum dat_completion_flags {
/* Completes with notification */
DAT_COMPLETION_DEFAULT_FLAG = 0x00,
/* Completions suppressed if successful */
DAT_COMPLETION_SUPPRESS_FLAG = 0x01,
/* Sender controlled notification for recv completion */
/* Completions with unsignaled notifications */
DAT_COMPLETION_UNSIGNALLED_FLAG = 0x04,
/* Do not start processing until all previous RDMA reads complete. */
/*
* Only valid for uDAPL as EP attribute for Recv Completion flags.
* Waiter unblocking is controlled by Threshold value of dat_evd_wait.
* UNSIGNALLED for RECV not allowed when EP has this attribute
*/
/* timeout = infinity */
#define DAT_TIMEOUT_INFINITE ((DAT_TIMEOUT) ~0)
/* dat handles */
typedef DAT_PVOID DAT_HANDLE;
typedef DAT_HANDLE DAT_CR_HANDLE;
typedef DAT_HANDLE DAT_EP_HANDLE;
typedef DAT_HANDLE DAT_EVD_HANDLE;
typedef DAT_HANDLE DAT_IA_HANDLE;
typedef DAT_HANDLE DAT_LMR_HANDLE;
typedef DAT_HANDLE DAT_PSP_HANDLE;
typedef DAT_HANDLE DAT_PZ_HANDLE;
typedef DAT_HANDLE DAT_RMR_HANDLE;
typedef DAT_HANDLE DAT_RSP_HANDLE;
typedef DAT_HANDLE DAT_SRQ_HANDLE;
/* dat NULL handles */
typedef DAT_SOCK_ADDR *DAT_IA_ADDRESS_PTR;
typedef DAT_UINT64 DAT_CONN_QUAL;
typedef DAT_UINT64 DAT_PORT_QUAL;
/* QOS definitions */
typedef enum dat_qos {
DAT_QOS_BEST_EFFORT = 0x00,
DAT_QOS_HIGH_THROUGHPUT = 0x01,
DAT_QOS_LOW_LATENCY = 0x02,
/* not low latency, nor high throughput */
DAT_QOS_ECONOMY = 0x04,
/* both low latency and high throughput */
DAT_QOS_PREMIUM = 0x08
} DAT_QOS;
/*
* FLAGS
*/
typedef enum dat_connect_flags {
DAT_CONNECT_DEFAULT_FLAG = 0x00,
DAT_CONNECT_MULTIPATH_FLAG = 0x01
typedef enum dat_close_flags {
DAT_CLOSE_ABRUPT_FLAG = 0x00,
DAT_CLOSE_GRACEFUL_FLAG = 0x01
typedef enum dat_evd_flags {
DAT_EVD_SOFTWARE_FLAG = 0x001,
DAT_EVD_CR_FLAG = 0x010,
DAT_EVD_DTO_FLAG = 0x020,
DAT_EVD_CONNECTION_FLAG = 0x040,
DAT_EVD_RMR_BIND_FLAG = 0x080,
DAT_EVD_ASYNC_FLAG = 0x100,
/* DAT events only, no software events */
DAT_EVD_DEFAULT_FLAG = 0x1F0
typedef enum dat_psp_flags {
/*
* Memory Buffers
*
* Both LMR and RMR triplets specify 64-bit addresses in the local host's byte
* order, even when that exceeds the size of a DAT_PVOID for the host
* architecture.
*/
/*
* Both LMR and RMR Triplets specify 64-bit addresses in the local host
* order, even when that exceeds the size of a void pointer for the host
* architecture. The DAT_VADDR type that represents addresses is in the
* native byte-order of the local host. Helper macros that allow Consumers
* to convert DAT_VADDR into various orders that might be useful for
* inclusion of RMR Triplets into a payload of a message follow.
*
* DAT defines the following macros to convert the fields on an RMR Triplet
* to defined byte orders to allow their export by the Consumer over wire
* protocols. DAT does not define how the two peers decide which byte should be
* used.
*
* DAT_LMRC_TO_LSB(lmrc) returns the supplied LMR Context in ls-byte
* order.
* DAT_LMRC_TO_MSB(lmrc) returns the supplied LMR Context in ms-byte
* order.
* DAT_RMRC_TO_LSB(rmrc) returns the supplied RMR Context in ls-byte
* order.
* DAT_RMRC_TO_MSB(rmrc) returns the supplied RMR Context in ms-byte
* order.
* DAT_VADDR_TO_LSB(vaddr) returns the supplied Virtual Address in ls-byte
* order.
* DAT_VADDR_TO_MSB(vaddr) returns the supplied Virtual Address in
* ms-byte order.
* DAT_VLEN_TO_LSB(vlen) returns the supplied length in ls-byte order.
* DAT_VLEN_TO_MSB(vlen) returns the supplied length in ms-byte order.
*
* Consumers are free to use 64-bit or 32-bit arithmetic for local or remote
* memory address and length manipulation in their preferred byte-order. Only
* the LMR and RMR Triplets passed to a Provider as part of a Posted DTO are
* required to be in 64-bit address and local host order formats. Providers
* shall convert RMR_Triplets to a Transport-required wire format.
*
* For the best performance, Consumers should align each buffer segment to
* the boundary specified by the dat_optimal_alignment.
*/
typedef DAT_UINT32 DAT_LMR_CONTEXT;
typedef DAT_UINT32 DAT_RMR_CONTEXT;
typedef DAT_UINT64 DAT_VLEN;
typedef DAT_UINT64 DAT_VADDR;
typedef struct dat_provider_attr DAT_PROVIDER_ATTR;
typedef struct dat_evd_param DAT_EVD_PARAM;
typedef struct dat_lmr_param DAT_LMR_PARAM;
/*
* It is legal for Consumer to specify zero for segment_length
* of the dat_lmr_triplet. When 0 is specified for the
* segment_length then the other two elements of the
* dat_lmr_triplet are irrelevant and can be invalid.
*/
typedef struct dat_lmr_triplet {
typedef struct dat_rmr_triplet {
/*
* The extra padding ensures that context, address, and length parameters are
* aligned on 64-bit boundaries.
*/
/* Memory privileges */
typedef enum dat_mem_priv_flags {
DAT_MEM_PRIV_NONE_FLAG = 0x00,
DAT_MEM_PRIV_LOCAL_READ_FLAG = 0x01,
DAT_MEM_PRIV_REMOTE_READ_FLAG = 0x02,
DAT_MEM_PRIV_LOCAL_WRITE_FLAG = 0x10,
DAT_MEM_PRIV_REMOTE_WRITE_FLAG = 0x20,
DAT_MEM_PRIV_ALL_FLAG = 0x33
/*
* For backwards compatibility with DAT-1.0 memory privileges values
* are supported
*/
#define DAT_MEM_PRIV_READ_FLAG (DAT_MEM_PRIV_LOCAL_READ_FLAG | \
#define DAT_MEM_PRIV_WRITE_FLAG (DAT_MEM_PRIV_LOCAL_WRITE_FLAG | \
/* LMR Arguments Mask */
typedef enum dat_lmr_param_mask {
DAT_LMR_FIELD_IA_HANDLE = 0x001,
DAT_LMR_FIELD_MEM_TYPE = 0x002,
DAT_LMR_FIELD_REGION_DESC = 0x004,
DAT_LMR_FIELD_LENGTH = 0x008,
DAT_LMR_FIELD_PZ_HANDLE = 0x010,
DAT_LMR_FIELD_MEM_PRIV = 0x020,
DAT_LMR_FIELD_LMR_CONTEXT = 0x040,
DAT_LMR_FIELD_RMR_CONTEXT = 0x080,
DAT_LMR_FIELD_REGISTERED_SIZE = 0x100,
DAT_LMR_FIELD_REGISTERED_ADDRESS = 0x200,
DAT_LMR_FIELD_ALL = 0x3FF
/* RMR Argumments & RMR Arguments Mask */
typedef struct dat_rmr_param {
typedef enum dat_rmr_param_mask {
DAT_RMR_FIELD_IA_HANDLE = 0x01,
DAT_RMR_FIELD_PZ_HANDLE = 0x02,
DAT_RMR_FIELD_LMR_TRIPLET = 0x04,
DAT_RMR_FIELD_MEM_PRIV = 0x08,
DAT_RMR_FIELD_RMR_CONTEXT = 0x10,
DAT_RMR_FIELD_ALL = 0x1F
/* Provider attributes */
typedef enum dat_iov_ownership {
/* Not modification by provider, consumer can use anytime. */
DAT_IOV_CONSUMER = 0x0,
/* Provider does not modify returned IOV DTO on completion. */
DAT_IOV_PROVIDER_NOMOD = 0x1,
/* Provider may modify IOV DTO on completion, can't trust it. */
DAT_IOV_PROVIDER_MOD = 0x2
typedef enum dat_ep_creator_for_psp {
DAT_PSP_CREATES_EP_NEVER, /* provider never creates endpoint */
DAT_PSP_CREATES_EP_IFASKED, /* provider creates endpoint if asked */
DAT_PSP_CREATES_EP_ALWAYS /* provider always creates endpoint */
/* General Interface Adapter attributes. These apply to both udat and kdat. */
/* To support backwards compatibility for DAPL-1.0 */
/* to support backwards compatibility for DAPL-1.0 & DAPL-1.1 */
#define max_mtu_size max_message_size
typedef struct dat_ia_attr
{
char adapter_name[DAT_NAME_MAX_LENGTH];
char vendor_name[DAT_NAME_MAX_LENGTH];
} DAT_IA_ATTR;
/* To support backwards compatibility for DAPL-1.0 & DAPL-1.1 */
typedef DAT_UINT64 DAT_IA_ATTR_MASK;
UINT64_C(0x020000000)
UINT64_C(0x040000000)
/* To support backwards compatibility for DAPL-1.0 & DAPL-1.1 */
#define DAT_IA_ALL DAT_IA_FIELD_ALL
/* Endpoint attributes */
typedef enum dat_service_type {
DAT_SERVICE_TYPE_RC /* reliable connections */
typedef struct dat_ep_attr {
} DAT_EP_ATTR;
/* Endpoint Parameters */
/* For backwards compatability */
typedef enum dat_ep_state {
DAT_EP_STATE_UNCONNECTED, /* quiescent state */
} DAT_EP_STATE;
typedef struct dat_ep_param {
} DAT_EP_PARAM;
typedef DAT_UINT64 DAT_EP_PARAM_MASK;
/* Remainder of values from EP_ATTR, 0x00001000 and up */
#define DAT_WATERMARK_INFINITE ((DAT_COUNT)~0)
#define DAT_HW_DEFAULT DAT_WATERMARK_INFINITE
#define DAT_SRQ_LW_DEFAULT 0x0
typedef enum dat_srq_state {
typedef struct dat_srq_attr {
} DAT_SRQ_ATTR;
typedef struct dat_srq_param {
typedef enum dat_srq_param_mask {
DAT_SRQ_FIELD_IA_HANDLE = 0x001,
DAT_SRQ_FIELD_SRQ_STATE = 0x002,
DAT_SRQ_FIELD_PZ_HANDLE = 0x004,
DAT_SRQ_FIELD_MAX_RECV_DTO = 0x008,
DAT_SRQ_FIELD_MAX_RECV_IOV = 0x010,
DAT_SRQ_FIELD_LOW_WATERMARK = 0x020,
DAT_SRQ_FIELD_AVAILABLE_DTO_COUNT = 0x040,
DAT_SRQ_FIELD_OUTSTANDING_DTO_COUNT = 0x080,
DAT_SRQ_FIELD_ALL = 0x0FF
/* PZ Parameters */
typedef struct dat_pz_param {
} DAT_PZ_PARAM;
typedef enum dat_pz_param_mask {
DAT_PZ_FIELD_IA_HANDLE = 0x01,
DAT_PZ_FIELD_ALL = 0x01
/* PSP Parameters */
typedef struct dat_psp_param {
typedef enum dat_psp_param_mask {
DAT_PSP_FIELD_IA_HANDLE = 0x01,
DAT_PSP_FIELD_CONN_QUAL = 0x02,
DAT_PSP_FIELD_EVD_HANDLE = 0x04,
DAT_PSP_FIELD_PSP_FLAGS = 0x08,
DAT_PSP_FIELD_ALL = 0x0F
/* RSP Parameters */
typedef struct dat_rsp_param {
typedef enum dat_rsp_param_mask {
DAT_RSP_FIELD_IA_HANDLE = 0x01,
DAT_RSP_FIELD_CONN_QUAL = 0x02,
DAT_RSP_FIELD_EVD_HANDLE = 0x04,
DAT_RSP_FIELD_EP_HANDLE = 0x08,
DAT_RSP_FIELD_ALL = 0x0F
/*
* Connection Request Parameters.
*
* The Connection Request does not provide Remote Endpoint attributes.
* If a local Consumer needs this information, the remote Consumer should
* encode it into Private Data.
*/
typedef struct dat_cr_param {
/* Remote IA whose Endpoint requested the connection. */
/* Port qualifier of the remote Endpoint of the requested connection. */
/* Size of the Private Data. */
/*
* Pointer to the Private Data passed by remote side in the Connection
* Request.
*/
/*
* The local Endpoint provided by the Service Point for the requested
* connection. It is the only Endpoint that can accept a Connection
* Request on this Service Point. The value DAT_HANDLE_NULL represents
* that there is no associated local Endpoint for the requested
* connection.
*/
} DAT_CR_PARAM;
typedef enum dat_cr_param_mask {
DAT_CR_FIELD_REMOTE_PORT_QUAL = 0x02,
DAT_CR_FIELD_PRIVATE_DATA_SIZE = 0x04,
DAT_CR_FIELD_PRIVATE_DATA = 0x08,
DAT_CR_FIELD_LOCAL_EP_HANDLE = 0x10,
DAT_CR_FIELD_ALL = 0x1F
/*
* *********************** Events *****************************************
*/
/* Completion status flags */
/* dto completion status */
/* For backwards compatability */
#define DAT_DTO_FAILURE DAT_DTO_ERR_FLUSHED
typedef enum dat_dto_completion_status {
DAT_DTO_SUCCESS = 0,
DAT_DTO_ERR_FLUSHED = 1,
DAT_DTO_ERR_LOCAL_EP = 3,
/* RMR completion status */
/* For backwards compatability */
#define DAT_RMR_BIND_SUCCESS DAT_DTO_SUCCESS
/* Completion group structs (six total) */
/* DTO completion event data */
/* transferred_length is not defined if status is not DAT_SUCCESS */
typedef struct dat_dto_completion_event_data {
/* RMR bind completion event data */
typedef struct dat_rmr_bind_completion_event_data {
typedef union dat_sp_handle {
/* Connection Request Arrival event data */
typedef struct dat_cr_arrival_event_data {
/*
* Handle to the Service Point that received the Connection Request
* from the remote side. If the Service Point was Reserved, sp is
* DAT_HANDLE_NULL because the reserved Service Point is automatically
* destroyed upon generating this event. Can be PSP or RSP.
*/
/* Address of the IA on which the Connection Request arrived. */
/*
* Connection Qualifier of the IA on which the Service Point received a
* Connection Request.
*/
/*
* The Connection Request instance created by a Provider for the
* arrived Connection Request. Consumers can find out private_data
* passed by a remote Consumer from cr_handle. It is up to a Consumer
* to dat_cr_accept or dat_cr_reject of the Connection Request.
*/
/* Connection event data */
typedef struct dat_connection_event_data {
/* Async Error event data */
/*
* For unaffiliated asynchronous event dat_handle is ia_handle. For Endpoint
* affiliated asynchronous event dat_handle is ep_handle. For EVD affiliated
* asynchronous event dat_handle is evd_handle. For SRQ affiliated asynchronous
* event dat_handle is srq_handle. For Memory affiliated asynchronous event
* dat_handle is either lmr_handle, rmr_handle or pz_handle.
*/
typedef struct dat_asynch_error_event_data {
/* LMR, RMR, or PZ handle */
/* The reason is object type specific and its values are defined below */
typedef enum ia_async_error_reason {
typedef enum ep_async_error_reason {
typedef enum ep_evd_error_reason {
typedef enum ep_srq_error_reason {
typedef enum lmr_async_error_reason {
typedef enum rmr_async_error_reason {
typedef enum pz_async_error_reason {
/* Software event data */
typedef struct dat_software_event_data {
typedef enum dat_event_number {
DAT_DTO_COMPLETION_EVENT = 0x00001,
DAT_RMR_BIND_COMPLETION_EVENT = 0x01001,
DAT_CONNECTION_REQUEST_EVENT = 0x02001,
DAT_CONNECTION_EVENT_ESTABLISHED = 0x04001,
DAT_CONNECTION_EVENT_PEER_REJECTED = 0x04002,
DAT_CONNECTION_EVENT_NON_PEER_REJECTED = 0x04003,
DAT_CONNECTION_EVENT_ACCEPT_COMPLETION_ERROR = 0x04004,
DAT_CONNECTION_EVENT_DISCONNECTED = 0x04005,
DAT_CONNECTION_EVENT_BROKEN = 0x04006,
DAT_CONNECTION_EVENT_TIMED_OUT = 0x04007,
DAT_CONNECTION_EVENT_UNREACHABLE = 0x04008,
DAT_ASYNC_ERROR_EVD_OVERFLOW = 0x08001,
DAT_ASYNC_ERROR_IA_CATASTROPHIC = 0x08002,
DAT_ASYNC_ERROR_EP_BROKEN = 0x08003,
DAT_ASYNC_ERROR_TIMED_OUT = 0x08004,
DAT_ASYNC_ERROR_PROVIDER_INTERNAL_ERROR = 0x08005,
DAT_SOFTWARE_EVENT = 0x10001
/* Union for event Data */
typedef union dat_event_data {
/* Event struct that holds all event information */
typedef struct dat_event {
} DAT_EVENT;
/* Provider/registration info */
typedef struct dat_provider_info {
char ia_name[DAT_NAME_MAX_LENGTH];
/*
* FUNCTION PROTOTYPES
*/
/*
* IA functions
*
* Note that there are actual 'dat_ia_open' and 'dat_ia_close'
* functions, it is not just a re-directing #define. That is
* because the functions may have to ensure that the provider
* library is loaded before it can call it, and may choose to
* unload the library after the last close.
*/
extern DAT_RETURN dat_ia_openv(
extern DAT_RETURN dat_ia_query(
extern DAT_RETURN dat_ia_close(
/* helper functions */
extern DAT_RETURN dat_set_consumer_context(
extern DAT_RETURN dat_get_consumer_context(
extern DAT_RETURN dat_get_handle_type(
/* CR Functions */
extern DAT_RETURN dat_cr_query(
extern DAT_RETURN dat_cr_accept(
extern DAT_RETURN dat_cr_reject(
/*
* For DAT-1.1 and above, this function is defined for both uDAPL and kDAPL.
* For DAT-1.0 it was only defined for uDAPL.
*/
extern DAT_RETURN dat_cr_handoff(
/* EVD Functions */
extern DAT_RETURN dat_evd_resize(
extern DAT_RETURN dat_evd_post_se(
extern DAT_RETURN dat_evd_dequeue(
extern DAT_RETURN dat_evd_query(
extern DAT_RETURN dat_evd_free(
/* EP functions */
extern DAT_RETURN dat_ep_create(
extern DAT_RETURN dat_ep_query(
extern DAT_RETURN dat_ep_modify(
extern DAT_RETURN dat_ep_connect(
extern DAT_RETURN dat_ep_dup_connect(
extern DAT_RETURN dat_ep_disconnect(
extern DAT_RETURN dat_ep_post_send(
extern DAT_RETURN dat_ep_post_recv(
extern DAT_RETURN dat_ep_post_rdma_read(
extern DAT_RETURN dat_ep_post_rdma_write(
extern DAT_RETURN dat_ep_get_status(
extern DAT_RETURN dat_ep_free(
extern DAT_RETURN dat_ep_reset(
/* LMR functions */
extern DAT_RETURN dat_lmr_query(
extern DAT_RETURN dat_lmr_free(
/* Non-coherent memory functions */
extern DAT_RETURN dat_lmr_sync_rdma_read(
extern DAT_RETURN dat_lmr_sync_rdma_write(
/* RMR Functions */
extern DAT_RETURN dat_rmr_create(
extern DAT_RETURN dat_rmr_query(
extern DAT_RETURN dat_rmr_bind(
extern DAT_RETURN dat_rmr_free(
/* PSP Functions */
extern DAT_RETURN dat_psp_create(
extern DAT_RETURN dat_psp_create_any(
extern DAT_RETURN dat_psp_query(
extern DAT_RETURN dat_psp_free(
/* RSP Functions */
extern DAT_RETURN dat_rsp_create(
extern DAT_RETURN dat_rsp_query(
extern DAT_RETURN dat_rsp_free(
/* PZ Functions */
extern DAT_RETURN dat_pz_create(
extern DAT_RETURN dat_pz_query(
extern DAT_RETURN dat_pz_free(
/*
* SRQ functions
*/
extern DAT_RETURN dat_ep_create_with_srq(
extern DAT_RETURN dat_ep_recv_query(
extern DAT_RETURN dat_ep_set_watermark(
extern DAT_RETURN dat_srq_create(
extern DAT_RETURN dat_srq_free(
extern DAT_RETURN dat_srq_post_recv(
extern DAT_RETURN dat_srq_query(
extern DAT_RETURN dat_srq_resize(
extern DAT_RETURN dat_srq_set_lw(
/*
* DAT registry functions.
*
* Note the dat_ia_open and dat_ia_close functions are linked to
* registration code which "redirects" to the appropriate provider.
*/
/* dat_provider_list */
/*
* DAT error functions.
*/
extern DAT_RETURN dat_strerror(
OUT const char **, /* major message string */
OUT const char **); /* minor message string */
#ifdef __cplusplus
}
#endif
#endif /* _DAT_H_ */