lnet/klnds/gnilnd/gni_pub.h

   1 /* SPDX-License-Identifier: GPL-2.0 */
   2
   3 /* Copyright 2007 Cray Inc. All Rights Reserved. */
   4
   5 /* Contains the user interface to the GNI. Kernel and User level.
   6  *
   7  * Author: Igor Gorodetsky <igorodet@cray.com>
   8  */
   9
  10 #ifndef _GNI_PUB_H_
  11 #define _GNI_PUB_H_
  12
  13 #ifdef __cplusplus
  14 extern "C"
  15 {
  16 #endif
  17
  18 #ifndef __KERNEL__
  19 #include <stdint.h>
  20 #endif
  21
  22 /* Common definitions for the kernel and the user level */
  23
  24 /**
  25  * GNI version control macros and values
  26  * Example: 0x00400080
  27  */
  28 /* Reflects major releases of GNI SW stack (e.g. support for new HW) */
  29 #define GNI_MAJOR_REV 0x00
  30 /* Reflects any uGNI API changes */
  31 #define GNI_MINOR_REV 0x5c
  32 /* Reflects any uGNI library code changes */
  33 #define GNI_CODE_REV  0x0000
  34
  35 #define GNI_GET_MAJOR(value) ((value >> 24) & 0xFF)
  36 #define GNI_GET_MINOR(value) ((value >> 16) & 0xFF)
  37 #define GNI_GET_REV(value) (value & 0xFFFF)
  38 #define GNI_VERSION ((GNI_MAJOR_REV << 24) | (GNI_MINOR_REV << 16) | GNI_CODE_REV)
  39 #define GNI_VERSION_CHECK(maj,min,code) (((maj) << 24) | ((min) << 16) | code)
  40
  41 /* Definitions of base versions where uGNI features are introduced */
  42 #define GNI_VERSION_FMA_SHARING  0x5b0000
  43
  44 /* Specifies input and output arguments to GNI functions */
  45 #define IN
  46 #define OUT
  47 #define INOUT
  48
  49 /* Reserved PTAGs.
  50    kernel apps: values  < GNI_PTAG_USER_START,
  51    user apps: GNI_PTAG_USER_START <= values <= GNI_PTAG_USER_END
  52    HSN boot: value = GNI_PTAG_MAX
  53
  54    GNI_PTAG_* values were designed for use on Gemini systems.  User
  55    applications run on an Aries system should always use a PTAG value of
  56    'GNI_FIND_ALLOC_PTAG' to allow the driver to automatically allocate a valid
  57    protection tag.
  58 */
  59 enum {
  60         GNI_PTAG_LND = 1,
  61         GNI_PTAG_OFED,
  62         GNI_PTAG_USER_START,
  63         GNI_PTAG_LND_KNC = 128,
  64         GNI_PTAG_USER_END = 253,
  65         GNI_PTAG_HSNBOOT = 254,
  66         GNI_PTAG_MAX = 254,
  67         GNI_PTAG_LB = 255
  68 };
  69
  70 #define GNI_FIND_ALLOC_PTAG GNI_PTAG_LB
  71
  72 /* Reserved PKEYs.
  73    kernel apps: values  < GNI_PKEY_USER_START,
  74    user apps: GNI_PTAG_USER_START <= values <= GNI_PKEY_USER_END
  75    HSN boot: value = GNI_PKEY_MAX */
  76 enum {
  77         GNI_PKEY_INVALID = 0,
  78         GNI_PKEY_LND = 1,
  79         GNI_PKEY_OFED,
  80         GNI_PKEY_USER_START = 128,
  81         GNI_PKEY_USER_END = 65407,
  82         GNI_PKEY_HSNBOOT = 65408,
  83         GNI_PKEY_MAX = 65534,
  84         GNI_PKEY_LB = 65535
  85 };
  86
  87
  88 #define GNI_COOKIE_PKEY_MASK           0xFFFF
  89 #define GNI_COOKIE_PKEY_SHIFT          16
  90 #define GNI_COOKIE_CBPS_MDD_MASK       0x7
  91 #define GNI_COOKIE_CBPS_MDD_SHIFT      3
  92 /* Macro to define COOKIE val (most useful to Aries).
  93  * cbps_mdd should be set at zero for now */
  94 #define GNI_JOB_CREATE_COOKIE(pkey, cbps_mdd) (((uint32_t)(pkey) << GNI_COOKIE_PKEY_SHIFT) | (((cbps_mdd) & GNI_COOKIE_CBPS_MDD_MASK) << GNI_COOKIE_CBPS_MDD_SHIFT))
  95
  96 /* Registered memory handle */
  97 typedef struct gni_mem_handle {
  98         uint64_t        qword1;
  99         uint64_t        qword2;
 100 } gni_mem_handle_t;
 101
 102 typedef enum gni_mem_handle_attr {
 103         GNI_MEMHNDL_ATTR_READONLY = 1,
 104         GNI_MEMHNDL_ATTR_VMDH,
 105         GNI_MEMHNDL_ATTR_MRT,
 106         GNI_MEMHNDL_ATTR_GART,
 107         GNI_MEMHNDL_ATTR_IOMMU,
 108         GNI_MEMHNDL_ATTR_PCI_IOMMU,
 109         GNI_MEMHNDL_ATTR_CLONE
 110 } gni_mem_handle_attr_t;
 111
 112 /* Opaque handles */
 113 typedef struct gni_nic  *gni_nic_handle_t;
 114 typedef struct gni_cdm  *gni_cdm_handle_t;
 115 typedef struct gni_ep   *gni_ep_handle_t;
 116 typedef struct gni_cq   *gni_cq_handle_t;
 117 typedef struct gni_err  *gni_err_handle_t;
 118 typedef struct gni_msgq *gni_msgq_handle_t;
 119 typedef struct gni_ce   *gni_ce_handle_t;
 120
 121 /* Short messaging types */
 122 typedef enum gni_smsg_type {
 123         GNI_SMSG_TYPE_INVALID = 0,
 124         GNI_SMSG_TYPE_MBOX,
 125         GNI_SMSG_TYPE_MBOX_AUTO_RETRANSMIT
 126 } gni_smsg_type_t;
 127
 128 #define GNI_SMSG_ANY_TAG 0xFF
 129
 130 /* Short messaging attributes */
 131 typedef struct gni_smsg_attr {
 132         gni_smsg_type_t         msg_type;
 133         void                    *msg_buffer;
 134         uint32_t                buff_size;
 135         gni_mem_handle_t        mem_hndl;
 136         uint32_t                mbox_offset;
 137         uint16_t                mbox_maxcredit;
 138         uint32_t                msg_maxsize;
 139 } gni_smsg_attr_t;
 140
 141 /* Maximum SMSG retransmit count default values */
 142
 143 #define FMA_SMSG_MAX_RETRANS_DEFAULT    10
 144
 145 /* Return codes */
 146 typedef enum gni_return {
 147         GNI_RC_SUCCESS = 0,
 148         GNI_RC_NOT_DONE,
 149         GNI_RC_INVALID_PARAM,
 150         GNI_RC_ERROR_RESOURCE,
 151         GNI_RC_TIMEOUT,
 152         GNI_RC_PERMISSION_ERROR,
 153         GNI_RC_DESCRIPTOR_ERROR,
 154         GNI_RC_ALIGNMENT_ERROR,
 155         GNI_RC_INVALID_STATE,
 156         GNI_RC_NO_MATCH,
 157         GNI_RC_SIZE_ERROR,
 158         GNI_RC_TRANSACTION_ERROR,
 159         GNI_RC_ILLEGAL_OP,
 160         GNI_RC_ERROR_NOMEM
 161 } gni_return_t;
 162
 163 /* Communication domain modes */
 164 #define GNI_CDM_MODE_FORK_NOCOPY        0x00000001
 165 #define GNI_CDM_MODE_FORK_FULLCOPY      0x00000002
 166 #define GNI_CDM_MODE_FORK_PARTCOPY      0x00000004 /* default */
 167 /* Do not kill the application for any type of error. For instance, when debugging. */
 168 #define GNI_CDM_MODE_ERR_NO_KILL        0x00000008
 169 /* Kill the application for any TRANSACTION errors. By default only a
 170  * subset will kill an application. The rest of the errors should be
 171  * reported through the CQ. Using this mode an application can request
 172  * being killed for all errors.
 173  */
 174 #define GNI_CDM_MODE_ERR_ALL_KILL       0x00000010
 175 /* Enable fast polling for GNI_EpPostDataTest,GNI_EpPostDataTestById
 176  * and GNI_PostDataProbe/GNI_PostDataProbeById.  Using this option may
 177  * result in loss of intermediate state information for datagram
 178  * transactions.
 179  */
 180 #define GNI_CDM_MODE_FAST_DATAGRAM_POLL 0x00000020
 181 /* Enable transmitting RDMA posts through one BTE channel, instead of
 182  * defaulting to using all three channels. This may be preferred for
 183  * some applications.
 184  */
 185 #define GNI_CDM_MODE_BTE_SINGLE_CHANNEL 0x00000040
 186 /* User space may specify PCI_IOMMU to be used for all memory
 187  * transactions. Setting this will always attempt to use the root
 188  * complex's address translation in the PCI bridge. If this can not be
 189  * enabled, but is requested, all memory registrations will error.
 190  */
 191 #define GNI_CDM_MODE_USE_PCI_IOMMU      0x00000080
 192 /* By default, newly created CDM's will allocate out of a shared MDD
 193  * pool. This pool is only shared within a protection domain. In an
 194  * IOMMU environment, there is more address space than MDDs available,
 195  * so this allows many more MDDs than normal. If the application
 196  * desires dedicated MDDs by default, then the CDM mode exists for
 197  * that. The shared mode flag is for convenience when the feature is
 198  * disabled during initial implementation stages.
 199  */
 200 #define GNI_CDM_MODE_MDD_DEDICATED      0x00000100
 201 #define GNI_CDM_MODE_MDD_SHARED         0x00000200
 202 /* By default, users may post transactions with either local or global completion
 203  * notification, not both.  If receipt of both local and global events is requested
 204  * users must set DUAL_EVENTS.  Performing a post operation with local and global
 205  * events enabled without DUAL_EVENTS set will yield an error GNI_RC_INVALID_PARAM.
 206  *
 207  * In addition, during an EpBind in default mode, transfer requests are allocated
 208  * equal in size to the number of events in the associated source CQ.  When
 209  * DUAL_EVENTS is set transfer requests are allocated 1 per 2 CQ event slots.
 210  * Therefore, a user is limited to posting half as many transactions as CQ events
 211  * when DUAL_EVENTS is set.  Exceeding this limit will yield an error
 212  * GNI_RC_ERROR_RESOURCE.
 213  */
 214 #define GNI_CDM_MODE_DUAL_EVENTS        0x00001000
 215
 216 /* This mode alters the FMA_SHARED behavior wrt. DLA */
 217 #define GNI_CDM_MODE_DLA_ENABLE_FORWARDING   0x00004000
 218 #define GNI_CDM_MODE_DLA_DISABLE_FORWARDING  0x00008000
 219 /* By default, newly created CDM's are assigned a dedicated FMA descriptor.  If
 220  * no FMA descriptors are available during the creation of a dedicated FMA CDM,
 221  * the operation will fail.  The FMA_SHARED CDM flag allows applications to
 222  * share FMA descriptors between (CDM's) within a protection domain.  This
 223  * enables a user to allocate more CDM's than there are FMA descriptors on a
 224  * node. */
 225 #define GNI_CDM_MODE_FMA_DEDICATED      0x00010000
 226 #define GNI_CDM_MODE_FMA_SHARED         0x00020000
 227 /* This mode enables the use of cached AMO operations */
 228 #define GNI_CDM_MODE_CACHED_AMO_ENABLED 0x00040000
 229 /* This CDM flag allows applications to request placing the CQs in
 230  * host memory closest to the NIC. This currently means on die0, but
 231  * could mean a different die in the future. This increases small
 232  * message injection rate for some applications.
 233  */
 234 #define GNI_CDM_MODE_CQ_NIC_LOCAL_PLACEMENT 0x00080000
 235 #define GNI_CDM_MODE_FLBTE_DISABLE          0x00100000
 236 /* Prevent mapping the entire FMA window into a process's address space.
 237  * Making the FMA window smaller reduces a process's memory footprint and
 238  * initialization overhead.  FMA throughput will be unnaffected while using
 239  * this mode with FMA transactions under the size configured in the file:
 240  * /sys/class/gni/kgni0/fma_sm_win_sz (32k by default, cache-aligned). */
 241 #define GNI_CDM_MODE_FMA_SMALL_WINDOW       0x00200000
 242
 243 #define GNI_CDM_MODE_MASK                   0x0FFFFFFF
 244
 245 /* Upper 4 CDM mode bits are reserved for internal ugni/dmapp usage. */
 246 #define GNI_CDM_MODE_PRIV_RESERVED_1        0x10000000
 247 #define GNI_CDM_MODE_PRIV_RESERVED_2        0x20000000
 248 #define GNI_CDM_MODE_PRIV_RESERVED_3        0x40000000
 249 #define GNI_CDM_MODE_PRIV_RESERVED_4        0x80000000
 250 #define GNI_CDM_MODE_PRIV_MASK              0xF0000000
 251
 252 /* Endpoint machine state */
 253 typedef enum gni_post_state{
 254         GNI_POST_PENDING,
 255         GNI_POST_COMPLETED,
 256         GNI_POST_ERROR,
 257         GNI_POST_TIMEOUT,
 258         GNI_POST_TERMINATED,
 259         GNI_POST_REMOTE_DATA
 260 } gni_post_state_t;
 261
 262 /* The memory attributes associated with the region.*/
 263 #define GNI_MEM_READWRITE               0x00000000
 264 #define GNI_MEM_READ_ONLY               0x00000001
 265 /* Directive to use Virtual MDH while registering this memory region. (user level)*/
 266 #define GNI_MEM_USE_VMDH                0x00000002
 267 /* Directive to use GART while registering the memory region */
 268 #define GNI_MEM_USE_GART                0x00000004
 269 /* Directive not to use GART or MRT as memory is physically contiguous */
 270 #define GNI_MEM_PHYS_CONT               0x00000008
 271 /* Valid only for gni_mem_register_segments(): segments are 4KB each, described by phys. addresses */
 272 #define GNI_MEM_PHYS_SEGMENTS           0x00000010
 273 /* Instruct NIC to enforce strict PI ordering.  On Gemini based platforms, this
 274    flag disables the HT "Non-Posted Pass Posted Writes" rule.  On Aries based
 275    platforms, this flag disables routing mode (GNI_DLVMODE_*) based ordering
 276    for received network requests and responses. */
 277 #define GNI_MEM_STRICT_PI_ORDERING      0x00000020
 278 /* Instruct NIC to issue PI (Processor Interface, e.g. HT) FLUSH command prior
 279    to sending network responses for the region */
 280 #define GNI_MEM_PI_FLUSH                0x00000040
 281 #define GNI_MEM_MDD_CLONE               0x00000080
 282 /* Instruct NIC to allow relaxed PI ordering.  On Gemini based platforms, this
 283    flag enables reordering of Non-Posted and Posted write requests into the
 284    processor by enabling both "Non-Posted Pass Posted Writes" and "Posted Pass
 285    Posted Writes" rules.  ("Non-Posted Pass Posted Writes" rule is enabled by
 286    default.)  On Aries based platforms, this flag enables reordering of
 287    requests not originated in the network.  Note: this flag is overridden by
 288    the GNI_MEM_STRICT_PI_ORDERING flag. */
 289 #define GNI_MEM_RELAXED_PI_ORDERING     0x00000100
 290 /* Only reserve the PTE range for this block of memory. */
 291 #define GNI_MEM_RESERVE_REGION          0x00000200
 292 /* Update the PTE range for the provided block of memory. The first
 293  * call with this flag will make MDH live. The application may receive
 294  * page faults if they don't call update region before sending to an
 295  * address. This will only fill in new pages, and compare old pages to
 296  * make sure there aren't any changes. */
 297 #define GNI_MEM_UPDATE_REGION           0x00000400
 298 /* Tell the driver to force this memory to be shared, despite default
 299  * CDM_MODE flag. If it is shared, then it will go into a pool of MDDs
 300  * shared with the same PTAGs. */
 301 #define GNI_MEM_MDD_SHARED              0x00000800
 302 /* Tell the driver to force this memory to be dedicated, despite
 303  * default CDM_MODE flag/kernel flags. If it is dedicated, then it
 304  * will operate like the old MDDs did, and be subject to the same
 305  * limits. */
 306 #define GNI_MEM_MDD_DEDICATED           0x00001000
 307 /* Directive that the memory region is GPU-resident memory. */
 308 #define GNI_MEM_CUDA                    0x01000000              /* Cuda device memory */
 309
 310 /* External memory, or resident memory in other PCI devices. These are
 311  * helper macros, as the different types of external memory have bits
 312  * assigned to them via the above memory flags */
 313 #define GNI_EXMEM_FLAGS(flag)           ((flag) >> 24)          /* Isolate exmem type */
 314 #define GNI_MEM_IS_EXTERNAL(flag)       (GNI_EXMEM_FLAGS(flag))
 315
 316 typedef struct gni_mem_segment {
 317         uint64_t        address; /* address of the segment */
 318         uint64_t        length;  /* size of the segment in bytes */
 319 } gni_mem_segment_t;
 320
 321 /* CQ modes/attributes of operation */
 322 typedef uint32_t gni_cq_mode_t;
 323
 324 /* The CQ will be created with blocking disabled. */
 325 #define GNI_CQ_NOBLOCK          0x00000000
 326 /* The CQ will be created with blocking enabled. */
 327 #define GNI_CQ_BLOCKING         0x00000001
 328 /* the EMULATED mode is reserved for internal uGNI use only. */
 329 #define GNI_CQ_EMULATED         0x00000002
 330 /* EMULATED mode cannot be created with blocking enabled. */
 331 #define GNI_CQ_EMULATED_INVALID (GNI_CQ_EMULATED | GNI_CQ_BLOCKING)
 332 /* use physical pages when creating the CQ, by default memory mapped space is used.  */
 333 #define GNI_CQ_PHYS_PAGES       0x00000004
 334 /* This is a "dummy CQ", as in, the CQ will never be checked for
 335  * events. It acts like a sink to avoid errors on the sender CQ for
 336  * instances where a remote event is needed. */
 337 #define GNI_CQ_UNMANAGED        0x00000008
 338
 339 #define GNI_CQ_IS_NON_BLOCKING(modes)     ((modes & GNI_CQ_BLOCKING) == GNI_CQ_NOBLOCK)
 340 #define GNI_CQ_IS_BLOCKING(modes)         ((modes & GNI_CQ_BLOCKING) == GNI_CQ_BLOCKING)
 341 #define GNI_CQ_IS_EMULATED(modes)         ((modes & GNI_CQ_EMULATED) == GNI_CQ_EMULATED)
 342 #define GNI_CQ_IS_NOT_EMULATED(modes)     ((modes & GNI_CQ_EMULATED) == 0)
 343 #define GNI_CQ_IS_INVALID_EMULATED(modes) ((modes & GNI_CQ_EMULATED_INVALID) == GNI_CQ_EMULATED_INVALID)
 344 #define GNI_CQ_USE_PHYS_PAGES(modes)      ((modes & GNI_CQ_PHYS_PAGES) == GNI_CQ_PHYS_PAGES)
 345
 346 /* Macros and enum for processing data component of CQEs associated with
 347    PostRDMA, PostFma, Short message transactions */
 348
 349 /* Completion queue entry (size of type field is 2 bits) */
 350 #define GNI_CQ_EVENT_TYPE_POST  0x0ULL
 351 #define GNI_CQ_EVENT_TYPE_SMSG  0x1ULL
 352 #define GNI_CQ_EVENT_TYPE_DMAPP 0x2ULL
 353 #define GNI_CQ_EVENT_TYPE_MSGQ  0x3ULL
 354 typedef uint64_t gni_cq_entry_t;
 355
 356 #ifndef GNI_INLINE_CQ_FUNCTIONS
 357 uint64_t gni_cq_get_data(gni_cq_entry_t);
 358 uint64_t gni_cq_get_source(gni_cq_entry_t);
 359 uint64_t gni_cq_get_status(gni_cq_entry_t);
 360 uint64_t gni_cq_get_info(gni_cq_entry_t);
 361 uint64_t gni_cq_overrun(gni_cq_entry_t);
 362 uint64_t gni_cq_rem_overrun(gni_cq_entry_t);
 363 uint64_t gni_cq_get_inst_id(gni_cq_entry_t);
 364 uint64_t gni_cq_get_rem_inst_id(gni_cq_entry_t);
 365 uint64_t gni_cq_get_tid(gni_cq_entry_t);
 366 uint64_t gni_cq_get_msg_id(gni_cq_entry_t);
 367 uint64_t gni_cq_get_type(gni_cq_entry_t);
 368 uint64_t gni_cq_get_block_id(gni_cq_entry_t);
 369 uint64_t gni_cq_get_unsuccessful_cnt(gni_cq_entry_t);
 370 uint64_t gni_cq_get_marker_id(gni_cq_entry_t);
 371 uint64_t gni_cq_get_failed_enqueue_cnt(gni_cq_entry_t);
 372 uint64_t gni_cq_get_ce_id(gni_cq_entry_t);
 373 uint64_t gni_cq_get_reductn_id(gni_cq_entry_t);
 374 uint64_t gni_cq_get_trans_type(gni_cq_entry_t);
 375 void     gni_cq_set_inst_id(gni_cq_entry_t *,uint64_t);
 376 void     gni_cq_set_rem_inst_id(gni_cq_entry_t *,uint64_t);
 377 void     gni_cq_set_tid(gni_cq_entry_t *,uint64_t);
 378 void     gni_cq_set_msg_id(gni_cq_entry_t *,uint64_t);
 379 void     gni_cq_set_type(gni_cq_entry_t *,uint64_t);
 380 void     gni_cq_clr_status(gni_cq_entry_t *);
 381 unsigned gni_cq_status_dla_overflow(gni_cq_entry_t);
 382 unsigned gni_cq_bte_enq_status(gni_cq_entry_t);
 383 #endif /* GNI_INLINE_CQ_FUNCTIONS */
 384
 385 #define GNI_CQ_GET_DATA    gni_cq_get_data
 386 #define GNI_CQ_GET_SOURCE  gni_cq_get_source
 387 #define GNI_CQ_GET_STATUS  gni_cq_get_status
 388 #define GNI_CQ_GET_INFO    gni_cq_get_info
 389 /*
 390  * GNI_CQ_GET_INST_ID will allow a user to query an event
 391  * to get the inst_id value associated with it.
 392  * On a Gemini interconnect, this will be a 32 bit value.
 393  * On an Aries interconnect, this will be a 24 bit value.
 394  */
 395 #define GNI_CQ_GET_INST_ID gni_cq_get_inst_id
 396 /*
 397  * GNI_CQ_GET_REM_INST_ID will allow a user to query a remote event
 398  * to get the 32 bit remote inst_id value associated with it.
 399  */
 400 #define GNI_CQ_GET_REM_INST_ID gni_cq_get_rem_inst_id
 401 #define GNI_CQ_GET_TID     gni_cq_get_tid
 402 #define GNI_CQ_GET_MSG_ID  gni_cq_get_msg_id
 403 #define GNI_CQ_GET_TYPE    gni_cq_get_type
 404 #define GNI_CQ_OVERRUN     gni_cq_overrun
 405 #define GNI_CQ_REM_OVERRUN gni_cq_rem_overrun
 406 #define GNI_CQ_GET_BLOCK_ID           gni_cq_get_block_id
 407 #define GNI_CQ_GET_UNSUCCESSFUL_CNT   gni_cq_get_unsuccessful_cnt
 408 #define GNI_CQ_GET_MARKER_ID          gni_cq_get_marker_id
 409 #define GNI_CQ_GET_FAILED_ENQUEUE_CNT gni_cq_get_failed_enqueue_cnt
 410 #define GNI_CQ_GET_CE_ID              gni_cq_get_ce_id
 411 #define GNI_CQ_GET_REDUCTN_ID         gni_cq_get_reductn_id
 412 #define GNI_CQ_GET_TRANS_TYPE         gni_cq_get_trans_type
 413 /*
 414  * GNI_CQ_SET_INST_ID will allow a user to set the inst_id
 415  * value for an event.
 416  * On a Gemini interconnect, this will be a 32 bit value.
 417  * On an Aries interconnect, this will be truncated to a 24 bit value.
 418  */
 419 #define GNI_CQ_SET_INST_ID(entry,val) gni_cq_set_inst_id(&(entry),val)
 420 /*
 421  * GNI_CQ_SET_REM_INST_ID will allow a user to set a 32 bit remote
 422  * inst_id value for an remote event.
 423  */
 424 #define GNI_CQ_SET_REM_INST_ID(entry,val) gni_cq_set_rem_inst_id(&(entry),val)
 425 #define GNI_CQ_SET_TID(entry,val)     gni_cq_set_tid(&(entry),val)
 426 #define GNI_CQ_SET_MSG_ID(entry,val)  gni_cq_set_msg_id(&(entry),val)
 427 #define GNI_CQ_SET_TYPE(entry,val)    gni_cq_set_type(&(entry),val)
 428 #define GNI_CQ_CLR_STATUS(entry)      gni_cq_clr_status(&(entry))
 429 #define GNI_CQ_STATUS_OK(entry)      (gni_cq_get_status(entry) == 0)
 430 #define GNI_CQ_STATUS_DLA_OVERFLOW(entry)   (gni_cq_status_dla_overflow(entry))
 431 #define GNI_CQ_BTE_ENQ_STATUS(entry)  gni_cq_bte_enq_status(entry)
 432
 433 /* Transaction types (for type field of post descriptor) */
 434 typedef enum gni_post_type {
 435         GNI_POST_RDMA_PUT = 1,
 436         GNI_POST_RDMA_GET,
 437         GNI_POST_FMA_PUT,
 438         GNI_POST_FMA_PUT_W_SYNCFLAG,
 439         GNI_POST_FMA_GET,
 440         GNI_POST_AMO,
 441         GNI_POST_CQWRITE,
 442         GNI_POST_CE,
 443         GNI_POST_FMA_GET_W_FLAG,
 444         GNI_POST_AMO_W_FLAG
 445 } gni_post_type_t;
 446
 447 /* FMA Get or Fetching AMO Flagged Response */
 448 #define GNI_FMA_FLAGGED_RESPONSE_SIZE   4     /* size in bytes */
 449
 450 /* FMA command types (for amo_cmd field of post descriptor) */
 451 typedef enum gni_fma_cmd_type {
 452         /************ AMOs with GET semantics **************/
 453         GNI_FMA_ATOMIC_FADD    = 0x008,    /* atomic FETCH and ADD */
 454         GNI_FMA_ATOMIC_FADD_C  = 0x018,    /* cached atomic FETCH and ADD */
 455         GNI_FMA_ATOMIC_FAND    = 0x009,    /* atomic FETCH and AND */
 456         GNI_FMA_ATOMIC_FAND_C  = 0x019,    /* cached atomic FETCH and AND */
 457         GNI_FMA_ATOMIC_FOR     = 0x00A,    /* atomic FETCH and OR */
 458         GNI_FMA_ATOMIC_FOR_C   = 0x01A,    /* cached atomic FETCH and OR */
 459         GNI_FMA_ATOMIC_FXOR    = 0x00B,    /* atomic FETCH and XOR */
 460         GNI_FMA_ATOMIC_FXOR_C  = 0x01B,    /* cached atomic FETCH and XOR */
 461         GNI_FMA_ATOMIC_FAX     = 0x00C,    /* atomic FETCH AND exclusive OR */
 462         GNI_FMA_ATOMIC_FAX_C   = 0x01C,    /* cached atomic FETCH AND exclusive OR */
 463         GNI_FMA_ATOMIC_CSWAP   = 0x00D,    /* atomic COMPARE and SWAP */
 464         GNI_FMA_ATOMIC_CSWAP_C = 0x01D,    /* cached atomic COMPARE and SWAP */
 465         /* Second generation commands ( GET semantics ) */
 466         GNI_FMA_ATOMIC2_FAND_S    = 0x240,    /* atomic fetching logical AND (32-bit operands) */
 467         GNI_FMA_ATOMIC2_FAND      = 0x041,    /* atomic FETCH and AND */
 468         GNI_FMA_ATOMIC2_FAND_SC   = 0x260,    /* cached atomic fetching logical AND (32-bit operands) */
 469         GNI_FMA_ATOMIC2_FAND_C    = 0x061,    /* cached atomic FETCH and AND */
 470         GNI_FMA_ATOMIC2_FOR_S     = 0x242,    /* atomic fetching logical OR (32-bit operands) */
 471         GNI_FMA_ATOMIC2_FOR       = 0x043,    /* atomic FETCH and OR */
 472         GNI_FMA_ATOMIC2_FOR_SC    = 0x262,    /* cached atomic fetching logical OR (32-bit operands) */
 473         GNI_FMA_ATOMIC2_FOR_C     = 0x063,    /* cached atomic FETCH and OR */
 474         GNI_FMA_ATOMIC2_FXOR_S    = 0x244,    /* atomic fetching logical Exclusive OR (32-bit operands) */
 475         GNI_FMA_ATOMIC2_FXOR      = 0x045,    /* atomic FETCH exclusive OR */
 476         GNI_FMA_ATOMIC2_FXOR_SC   = 0x264,    /* cached atomic fetching logical Exclusive OR (32-bit operands) */
 477         GNI_FMA_ATOMIC2_FXOR_C    = 0x065,    /* cached atomic FETCH exclusive OR */
 478         GNI_FMA_ATOMIC2_FSWAP_S   = 0x246,    /* atomic fetching Swap (32-bit operands) */
 479         GNI_FMA_ATOMIC2_FSWAP     = 0x047,    /* atomic FETCH and SWAP */
 480         GNI_FMA_ATOMIC2_FSWAP_SC  = 0x266,    /* cached atomic fetching Swap (32-bit operands) */
 481         GNI_FMA_ATOMIC2_FSWAP_C   = 0x067,    /* cached atomic FETCH and SWAP */
 482         GNI_FMA_ATOMIC2_FAX_S     = 0x248,    /* atomic fetching logical AND Exclusive OR (32-bit operands) */
 483         GNI_FMA_ATOMIC2_FAX       = 0x049,    /* atomic FETCH AND exclusive OR */
 484         GNI_FMA_ATOMIC2_FAX_SC    = 0x268,    /* cached atomic fetching logical AND Exclusive OR (32-bit operands) */
 485         GNI_FMA_ATOMIC2_FAX_C     = 0x069,    /* cached atomic FETCH AND exclusive OR */
 486         GNI_FMA_ATOMIC2_FCSWAP_S  = 0x24A,    /* atomic fetching Compare and Swap (32-bit operands) */
 487         GNI_FMA_ATOMIC2_FCSWAP    = 0x04B,    /* atomic Fetching COMPARE and SWAP */
 488         GNI_FMA_ATOMIC2_FCSWAP_SC = 0x26A,    /* cached atomic fetching Compare and Swap (32-bit operands) */
 489         GNI_FMA_ATOMIC2_FCSWAP_C  = 0x06B,    /* cached atomic Fetching COMPARE and SWAP */
 490         GNI_FMA_ATOMIC2_FIMIN_S   = 0x250,    /* atomic fetching integer signed two’s complement Minimum (32-bit operands) */
 491         GNI_FMA_ATOMIC2_FIMIN     = 0x051,    /* atomic Fetching integer signed two's complement Minimum */
 492         GNI_FMA_ATOMIC2_FIMIN_SC  = 0x270,    /* cached atomic fetching int signed two’s complement Minimum (32-bit operands) */
 493         GNI_FMA_ATOMIC2_FIMIN_C   = 0x071,    /* cached atomic Fetching integer signed two's complement Minimum */
 494         GNI_FMA_ATOMIC2_FIMAX_S   = 0x252,    /* atomic fetching integer signed two’s complement Maximum (32-bit operands) */
 495         GNI_FMA_ATOMIC2_FIMAX     = 0x053,    /* atomic Fetching integer signed two's complement Maximum */
 496         GNI_FMA_ATOMIC2_FIMAX_SC  = 0x272,    /* cached atomic fetching int signed two’s complement Maximum (32-bit operands) */
 497         GNI_FMA_ATOMIC2_FIMAX_C   = 0x073,    /* cached atomic Fetching integer signed two's complement Maximum */
 498         GNI_FMA_ATOMIC2_FIADD_S   = 0x254,    /* atomic fetching integer two’s complement Addition (32-bit operands) */
 499         GNI_FMA_ATOMIC2_FIADD     = 0x055,    /* atomic Fetching integer two's complement Addition */
 500         GNI_FMA_ATOMIC2_FIADD_SC  = 0x274,    /* cached atomic fetching integer two’s complement Addition (32-bit operands) */
 501         GNI_FMA_ATOMIC2_FIADD_C   = 0x075,    /* cached atomic Fetching integer two's complement Addition */
 502         GNI_FMA_ATOMIC2_FFPMIN_S  = 0x258,    /* atomic fetching floating point Minimum (single precision) (32-bit operands) */
 503         GNI_FMA_ATOMIC2_FFPMIN    = 0x059,    /* atomic Fetching floating point Minimum (double precision) */
 504         GNI_FMA_ATOMIC2_FFPMIN_SC = 0x278,    /* cached atomic fetching floating point Minimum (single precision) (32-bit operands) */
 505         GNI_FMA_ATOMIC2_FFPMIN_C  = 0x079,    /* cached atomic Fetching floating point Minimum (double precision) */
 506         GNI_FMA_ATOMIC2_FFPMAX_S  = 0x25A,    /* atomic fetching floating point Maximum (single precision) (32-bit operands) */
 507         GNI_FMA_ATOMIC2_FFPMAX    = 0x05B,    /* atomic Fetching floating point Maximum (double precision) */
 508         GNI_FMA_ATOMIC2_FFPMAX_SC = 0x27A,    /* cached atomic fetching floating point Maximum (single precision) (32-bit operands) */
 509         GNI_FMA_ATOMIC2_FFPMAX_C  = 0x07B,    /* cached atomic Fetching floating point Maximum (double precision) */
 510         GNI_FMA_ATOMIC2_FFPADD_S  = 0x25C,    /* atomic fetching floating point Addition (single precision) (32-bit operands) */
 511         GNI_FMA_ATOMIC2_FFPADD    = 0x05D,    /* atomic Fetching floating point Addition (double precision) */
 512         GNI_FMA_ATOMIC2_FFPADD_SC = 0x27C,    /* cached atomic fetching floating point Addition (single precision) (32-bit operands) */
 513         GNI_FMA_ATOMIC2_FFPADD_C  = 0x07D,    /* cached atomic Fetching floating point Addition (double precision) */
 514         /************ AMOs with PUT semantics ***************/
 515         GNI_FMA_ATOMIC_ADD     = 0x108,    /* atomic ADD */
 516         GNI_FMA_ATOMIC_ADD_C   = 0x118,    /* cached atomic ADD */
 517         GNI_FMA_ATOMIC_AND     = 0x109,    /* atomic AND */
 518         GNI_FMA_ATOMIC_AND_C   = 0x119,    /* cached atomic AND */
 519         GNI_FMA_ATOMIC_OR      = 0x10A,    /* atomic OR */
 520         GNI_FMA_ATOMIC_OR_C    = 0x11A,    /* cached atomic OR */
 521         GNI_FMA_ATOMIC_XOR     = 0x10B,    /* atomic exclusive OR */
 522         GNI_FMA_ATOMIC_XOR_C   = 0x11B,    /* cached atomic exclusive OR */
 523         GNI_FMA_ATOMIC_AX      = 0x10C,    /* atomic AND exclusive OR */
 524         GNI_FMA_ATOMIC_AX_C    = 0x11C,    /* cached atomic AND exclusive OR */
 525         /* Second generation commands ( PUT semantics ) */
 526         GNI_FMA_ATOMIC2_AND_S    = 0x340,    /* atomic AND (32-bit operands) */
 527         GNI_FMA_ATOMIC2_AND      = 0x141,    /* atomic AND */
 528         GNI_FMA_ATOMIC2_AND_SC   = 0x360,    /* cached atomic AND (32-bit operands) */
 529         GNI_FMA_ATOMIC2_AND_C    = 0x161,    /* cached atomic AND */
 530         GNI_FMA_ATOMIC2_OR_S     = 0x342,    /* atomic OR (32-bit operands) */
 531         GNI_FMA_ATOMIC2_OR       = 0x143,    /* atomic  OR */
 532         GNI_FMA_ATOMIC2_OR_SC    = 0x362,    /* cached atomic OR (32-bit operands) */
 533         GNI_FMA_ATOMIC2_OR_C     = 0x163,    /* cached atomic  OR */
 534         GNI_FMA_ATOMIC2_XOR_S    = 0x344,    /* atomic Exclusive OR (32-bit operands) */
 535         GNI_FMA_ATOMIC2_XOR      = 0x145,    /* atomic exclusive OR */
 536         GNI_FMA_ATOMIC2_XOR_SC   = 0x364,    /* cached atomic Exclusive OR (32-bit operands) */
 537         GNI_FMA_ATOMIC2_XOR_C    = 0x165,    /* cached atomic exclusive OR */
 538         GNI_FMA_ATOMIC2_SWAP_S   = 0x346,    /* atomic Swap (Store) (32-bit operands) */
 539         GNI_FMA_ATOMIC2_SWAP     = 0x147,    /* atomic SWAP */
 540         GNI_FMA_ATOMIC2_SWAP_SC  = 0x366,    /* cached atomic Swap (Store) (32-bit operands) */
 541         GNI_FMA_ATOMIC2_SWAP_C   = 0x167,    /* cached atomic SWAP */
 542         GNI_FMA_ATOMIC2_AX_S     = 0x348,    /* atomic AND Exclusive OR (32-bit operands), not valid for FMA_LAUNCH */
 543         GNI_FMA_ATOMIC2_AX       = 0x149,    /* atomic AND exclusive OR */
 544         GNI_FMA_ATOMIC2_AX_SC    = 0x368,    /* cached atomic AND Exclusive OR (32-bit operands), not valid for FMA_LAUNCH */
 545         GNI_FMA_ATOMIC2_AX_C     = 0x169,    /* cached atomic AND exclusive OR */
 546         GNI_FMA_ATOMIC2_CSWAP_S  = 0x34A,    /* atomic Compare and Swap (Conditional Store) (32-bit operands), not valid for FMA_LAUNCH */
 547         GNI_FMA_ATOMIC2_CSWAP    = 0x14B,    /* atomic COMPARE and SWAP */
 548         GNI_FMA_ATOMIC2_CSWAP_SC = 0x36A,    /* cached atomic Compare and Swap (Conditional Store) (32-bit operands), not valid for FMA_LAUNCH */
 549         GNI_FMA_ATOMIC2_CSWAP_C  = 0x16B,    /* cached atomic COMPARE and SWAP */
 550         GNI_FMA_ATOMIC2_IMIN_S   = 0x350,    /* atomic integer signed two’s complement Minimum (32-bit operands) */
 551         GNI_FMA_ATOMIC2_IMIN     = 0x151,    /* atomic integer signed two's complement Minimum */
 552         GNI_FMA_ATOMIC2_IMIN_SC  = 0x370,    /* cached atomic integer signed two’s complement Minimum (32-bit operands) */
 553         GNI_FMA_ATOMIC2_IMIN_C   = 0x171,    /* cached atomic integer signed two's complement Minimum */
 554         GNI_FMA_ATOMIC2_IMAX_S   = 0x352,    /* atomic integer signed two’s complement Maximum (32-bit operands) */
 555         GNI_FMA_ATOMIC2_IMAX     = 0x153,    /* atomic integer signed two's complement Maximum */
 556         GNI_FMA_ATOMIC2_IMAX_SC  = 0x372,    /* cached atomic integer signed two’s complement Maximum (32-bit operands) */
 557         GNI_FMA_ATOMIC2_IMAX_C   = 0x173,    /* cached atomic integer signed two's complement Maximum */
 558         GNI_FMA_ATOMIC2_IADD_S   = 0x354,    /* atomic integer two’s complement Addition (32-bit operands) */
 559         GNI_FMA_ATOMIC2_IADD     = 0x155,    /* atomic integer two's complement Addition */
 560         GNI_FMA_ATOMIC2_IADD_SC  = 0x374,    /* cached atomic integer two’s complement Addition (32-bit operands) */
 561         GNI_FMA_ATOMIC2_IADD_C   = 0x175,    /* cached atomic integer two's complement Addition */
 562         GNI_FMA_ATOMIC2_FPMIN_S  = 0x358,    /* atomic floating point Minimum (single precision) (32-bit operands) */
 563         GNI_FMA_ATOMIC2_FPMIN    = 0x159,    /* atomic floating point Minimum (double precision) */
 564         GNI_FMA_ATOMIC2_FPMIN_SC = 0x378,    /* cached atomic floating point Minimum (single precision) (32-bit operands) */
 565         GNI_FMA_ATOMIC2_FPMIN_C  = 0x179,    /* cached atomic floating point Minimum (double precision) */
 566         GNI_FMA_ATOMIC2_FPMAX_S  = 0x35A,    /* atomic floating point Maximum (single precision) (32-bit operands) */
 567         GNI_FMA_ATOMIC2_FPMAX    = 0x15B,    /* atomic floating point Maximum (double precision) */
 568         GNI_FMA_ATOMIC2_FPMAX_SC = 0x37A,    /* cached atomic floating point Maximum (single precision) (32-bit operands) */
 569         GNI_FMA_ATOMIC2_FPMAX_C  = 0x17B,    /* cached atomic floating point Maximum (double precision) */
 570         GNI_FMA_ATOMIC2_FPADD_S  = 0x35C,    /* atomic floating point Addition (single precision) (32-bit operands) */
 571         GNI_FMA_ATOMIC2_FPADD    = 0x15D,    /* atomic floating point Addition (double precision) */
 572         GNI_FMA_ATOMIC2_FPADD_SC = 0x37C,    /* cached atomic floating point Addition (single precision) (32-bit operands) */
 573         GNI_FMA_ATOMIC2_FPADD_C  = 0x17D,    /* cached atomic floating point Addition (double precision) */
 574 } gni_fma_cmd_type_t;
 575
 576 /* CE command types */
 577 typedef enum gni_ce_cmd_type {
 578         GNI_FMA_CE_AND_S        = 0x0ull,   /* Logical AND, short */
 579         GNI_FMA_CE_AND          = 0x1ull,   /* Logical AND */
 580         GNI_FMA_CE_OR_S         = 0x2ull,   /* Logical OR, short */
 581         GNI_FMA_CE_OR           = 0x3ull,   /* Logical OR */
 582         GNI_FMA_CE_XOR_S        = 0x4ull,   /* Logical XOR, short */
 583         GNI_FMA_CE_XOR          = 0x5ull,   /* Logical XOR */
 584         GNI_FMA_CE_IMIN_LIDX_S  = 0x10ull,  /* Integer signed two's complement minimum, short (lowest index returned) */
 585         GNI_FMA_CE_IMIN_LIDX    = 0x11ull,  /* Integer signed two's complement minimum (lowest index returned) */
 586         GNI_FMA_CE_IMAX_LIDX_S  = 0x12ull,  /* Integer signed two's complement maximum, short (lowest index returned) */
 587         GNI_FMA_CE_IMAX_LIDX    = 0x13ull,  /* Integer signed two's complement maximum (lowest index returned) */
 588         GNI_FMA_CE_IADD_S       = 0x14ull,  /* Integer two's complement ADD, short */
 589         GNI_FMA_CE_IADD         = 0x15ull,  /* Integer two's complement ADD */
 590         GNI_FMA_CE_FPMIN_LIDX_S = 0x18ull,  /* Floating point minimum, short (lowest index returned) */
 591         GNI_FMA_CE_FPMIN_LIDX   = 0x19ull,  /* Floating point minimum (lowest index returned) */
 592         GNI_FMA_CE_FPMAX_LIDX_S = 0x1aull,  /* Floating point maximum, short (lowest index returned) */
 593         GNI_FMA_CE_FPMAX_LIDX   = 0x1bull,  /* Floating point maximum (lowest index returned) */
 594         GNI_FMA_CE_FPADD_S      = 0x1cull,  /* Floating point ADD, short */
 595         GNI_FMA_CE_FPADD        = 0x1dull,  /* Floating point ADD */
 596         GNI_FMA_CE_IMIN_GIDX_S  = 0x30ull,  /* Integer signed two's complement minimum, short (greatest index returned) */
 597         GNI_FMA_CE_IMIN_GIDX    = 0x31ull,  /* Integer signed two's complement minimum (greatest index returned) */
 598         GNI_FMA_CE_IMAX_GIDX_S  = 0x32ull,  /* Integer signed two's complement maximum, short (greatest index returned) */
 599         GNI_FMA_CE_IMAX_GIDX    = 0x33ull,  /* Integer signed two's complement maximum (greatest index returned) */
 600         GNI_FMA_CE_FPMIN_GIDX_S = 0x38ull,  /* Floating point minimum, short (greatest index returned) */
 601         GNI_FMA_CE_FPMIN_GIDX   = 0x39ull,  /* Floating point minimum (greatest index returned) */
 602         GNI_FMA_CE_FPMAX_GIDX_S = 0x3aull,  /* Floating point maximum, short (greatest index returned) */
 603         GNI_FMA_CE_FPMAX_GIDX   = 0x3bull,  /* Floating point maximum (greatest index returned) */
 604 } gni_ce_cmd_type_t;
 605
 606 /* CE result structure */
 607 typedef struct gni_ce_result {
 608         uint64_t        control;
 609         uint64_t        result1;
 610         uint64_t        result2;
 611 } gni_ce_result_t;
 612
 613 /* CE result operations */
 614 uint64_t gni_ce_res_get_status(gni_ce_result_t *);
 615 uint64_t gni_ce_res_status_ok(gni_ce_result_t *);
 616 uint64_t gni_ce_res_get_fpe(gni_ce_result_t *);
 617 uint64_t gni_ce_res_get_red_id(gni_ce_result_t *);
 618
 619 #define GNI_CE_RES_GET_STATUS   gni_ce_res_get_status
 620 #define GNI_CE_RES_STATUS_OK    gni_ce_res_status_ok
 621 #define GNI_CE_RES_GET_FPE      gni_ce_res_get_fpe
 622 #define GNI_CE_RES_GET_RED_ID   gni_ce_res_get_red_id
 623
 624 /* CE floating point exceptions  */
 625 #define GNI_CE_FPE_OP_INVAL     0x1
 626 #define GNI_CE_FPE_OFLOW        0x2
 627 #define GNI_CE_FPE_UFLOW        0x4
 628 #define GNI_CE_FPE_PRECISION    0x8
 629
 630 /* CE child types */
 631 typedef enum {
 632         GNI_CE_CHILD_UNUSED,
 633         GNI_CE_CHILD_VCE,
 634         GNI_CE_CHILD_PE
 635 } gni_ce_child_t;
 636
 637 /* VCE channel modes, used during GNI_CeConfigure(...) */
 638 /* Rounding mode, specify 1 */
 639 #define GNI_CE_MODE_ROUND_UP            0x00000001
 640 #define GNI_CE_MODE_ROUND_DOWN          0x00000002
 641 #define GNI_CE_MODE_ROUND_NEAR          0x00000004
 642 #define GNI_CE_MODE_ROUND_ZERO          0x00000008
 643 /* CQE delivery mode, specify 1 */
 644 #define GNI_CE_MODE_CQE_ONCOMP          0x00000010
 645 #define GNI_CE_MODE_CQE_ONERR           0x00000040
 646 /* Routing mode, specify 1 */
 647 #define GNI_CE_MODE_RC_NMIN_HASH        0x00000080
 648 #define GNI_CE_MODE_RC_MIN_HASH         0x00000100
 649 #define GNI_CE_MODE_RC_MNON_HASH        0x00000200
 650 #define GNI_CE_MODE_RC_ADAPT            0x00000400
 651
 652 #define GNI_CE_MAX_CHILDREN             32
 653
 654 /* CQ event types */
 655 #define GNI_CQMODE_SILENT       0x0000
 656 #define GNI_CQMODE_LOCAL_EVENT  0x0001
 657 #define GNI_CQMODE_GLOBAL_EVENT 0x0002
 658 #define GNI_CQMODE_REMOTE_EVENT 0x0004
 659 #define GNI_CQMODE_DUAL_EVENTS  ( GNI_CQMODE_LOCAL_EVENT | GNI_CQMODE_GLOBAL_EVENT )
 660
 661 /* Delivery modes */
 662 #define GNI_DLVMODE_PERFORMANCE 0x0000
 663 #define GNI_DLVMODE_NO_ADAPT    0x0001
 664 #define GNI_DLVMODE_NO_HASH     0x0002
 665 #define GNI_DLVMODE_NO_RADAPT   0x0004
 666 #define GNI_DLVMODE_IN_ORDER    ( GNI_DLVMODE_NO_ADAPT | GNI_DLVMODE_NO_HASH )
 667
 668 /* Aries delivery modes */
 669 #define GNI_DLVMODE_MNON_HASH   GNI_DLVMODE_IN_ORDER
 670 #define GNI_DLVMODE_NMIN_HASH   0x0008
 671 #define GNI_DLVMODE_MIN_HASH    0x0010
 672 #define GNI_DLVMODE_ADAPTIVE0   GNI_DLVMODE_PERFORMANCE
 673 #define GNI_DLVMODE_ADAPTIVE1   0x0020
 674 #define GNI_DLVMODE_ADAPTIVE2   0x0040
 675 #define GNI_DLVMODE_ADAPTIVE3   0x0080
 676
 677 #define GNI_DLVMODE_ORDERED_TAIL 0x0100
 678
 679 /* Error Event Categories */
 680 /* WARNING: DO NOT CHANGE THESE UNLESS YOU CHANGE ghal_err_cat.h */
 681 #define GNI_ERRMASK_CORRECTABLE_MEMORY   BIT(0)
 682 #define GNI_ERRMASK_CRITICAL             BIT(1)
 683 #define GNI_ERRMASK_TRANSACTION          BIT(2)
 684 #define GNI_ERRMASK_ADDRESS_TRANSLATION  BIT(3)
 685 #define GNI_ERRMASK_TRANSIENT            BIT(4)
 686 #define GNI_ERRMASK_INFORMATIONAL        BIT(5)
 687 #define GNI_ERRMASK_DIAG_ONLY            BIT(6)
 688 #define GNI_ERRMASK_UNKNOWN_TRANSACTION  BIT(7)
 689
 690 /* RDMA mode */
 691 /* local_addr is a physical address (kernel only) */
 692 #define GNI_RDMAMODE_PHYS_ADDR  0x0001
 693 /* instruction to Gemini to wait for all responses from this post and all
 694  * previous posts before processing the next RDMA descriptor */
 695 #define GNI_RDMAMODE_FENCE      0x0002
 696 /* Disable Aries write combining of incoming GET data */
 697 #define GNI_RDMAMODE_GETWC_DIS  0x0004
 698
 699 /* Post CE modes, used during GNI_PostFma(...) */
 700 /* Use two operands (only meaningful for single operand collective operations).
 701  * Single operand CE operations are all variations of AND, OR, XOR and ADD.  */
 702 #define GNI_CEMODE_TWO_OP               BIT(0)
 703 /* The provided operands are an intermediate result that has experienced an
 704  * invalid operation floating point exception. */
 705 #define GNI_CEMODE_FPE_OP_INVAL         BIT(1)
 706 /* The provided operands are an intermediate result that has experienced an
 707  * overflow floating point exception */
 708 #define GNI_CEMODE_FPE_OFLOW            BIT(2)
 709 /* The provided operands are an intermediate result that has experienced an
 710  * underflow floating point exception. */
 711 #define GNI_CEMODE_FPE_UFLOW            BIT(3)
 712 /* The provided operands are an intermediate result that has experienced an
 713  * inexact result floating point exception. */
 714 #define GNI_CEMODE_FPE_PRECISION        BIT(4)
 715
 716 /* Maximum length in bytes of a datagram transaction */
 717 #define GNI_DATAGRAM_MAXSIZE    128
 718
 719 /*
 720  * Maximum length in bytes of a short message,
 721  * this includes the length of the header and data.
 722  */
 723 #define GNI_SMSG_MAX_SIZE       65535
 724
 725 /* Transaction descriptor */
 726 typedef struct gni_post_descriptor {
 727         /********************** Control **********************/
 728         /* points to the next descriptor in the link list */
 729         void *next_descr;
 730         /* points to the previous descriptor in the link list */
 731         void *prev_descr;
 732         /* holds an ID of the transaction assigned by the user */
 733         uint64_t post_id;
 734         /* error status of the transaction */
 735         uint64_t status;
 736         /* completion flag of the transaction */
 737         uint16_t cq_mode_complete;
 738         /********************** Common ***********************/
 739         /* type of the transaction */
 740         gni_post_type_t type;
 741         /* instruction to generate CQ events of the following types
 742            (see GNI_CQMODE_xxx)*/
 743         uint16_t cq_mode;
 744         /* delivery mode (see GNI_DLVMODE_xxx) */
 745         uint16_t dlvr_mode;
 746         /* address of region on the local node: source for Put, target for Get */
 747         uint64_t local_addr;
 748         /* local memory handle */
 749         gni_mem_handle_t local_mem_hndl;
 750         /* address of the remote region: target for Put, source for Get */
 751         uint64_t remote_addr;
 752         /* remote memory handle */
 753         gni_mem_handle_t remote_mem_hndl;
 754         /* number of bytes to move during the transaction */
 755         uint64_t length;
 756         /****************** RDMA specific ********************/
 757         /* see GNI_RDMAMODE_xxx */
 758         uint16_t rdma_mode;
 759         /* defines src. CQ for the transaction */
 760         gni_cq_handle_t src_cq_hndl;
 761         /************ FMA and AMO specific *******************/
 762         /* synchronization value */
 763         uint64_t sync_flag_value;
 764         /* location to deliver sync. value */
 765         uint64_t sync_flag_addr;
 766         /****************** AMO specific *********************/
 767         /* AMO command for the transaction */
 768         gni_fma_cmd_type_t amo_cmd;
 769         /* first operand required by the AMO command */
 770         uint64_t first_operand;
 771         /* second operand required by the AMO command */
 772         uint64_t second_operand;
 773         /****************** CQWrite specific *****************/
 774         /* cqwrite value - only 6 least significant bytes available to software */
 775         uint64_t cqwrite_value;
 776         /****************** CE specific **********************/
 777         /* CE command */
 778         gni_ce_cmd_type_t ce_cmd;
 779         /* CE modes, see GNI_CEMODE_* */
 780         uint32_t ce_mode;
 781         /* CE reduction ID */
 782         uint64_t ce_red_id;
 783 } gni_post_descriptor_t;
 784
 785 /* NTT configuration table entries */
 786 typedef struct gni_ntt_entry {
 787         uint32_t        blck_addr;
 788         uint32_t        rplc_addr;
 789         uint8_t         rplc_size;
 790 } gni_ntt_entry_t;
 791
 792 /* NTT configuration descriptor */
 793 typedef struct gni_ntt_descriptor {
 794         /* size of the NTT group to be configured */
 795         uint32_t        group_size;
 796         /* NTT granularity */
 797         uint8_t         granularity;
 798         /* pointer to the array of new NTT values */
 799         union {
 800                 uint32_t        *table;
 801                 gni_ntt_entry_t *table_v2;
 802         } u;
 803         /* configuration flags ( not used )*/
 804         uint8_t         flags;
 805 } gni_ntt_descriptor_t;
 806
 807 /* GNI Error Event */
 808 typedef struct gni_error_event {
 809         uint16_t error_code;
 810         uint8_t  error_category;
 811         uint8_t  ptag;
 812         uint32_t serial_number;
 813         uint64_t timestamp;
 814         uint64_t info_mmrs[4];
 815 } gni_error_event_t;
 816
 817 typedef uint8_t gni_error_mask_t;
 818
 819 /* Job parameters and limits */
 820 #define GNI_JOB_INVALID_LIMIT           (-1)
 821 /* Directive for the driver to cleanup NTT at the end of the job */
 822 #define GNI_JOB_CTRL_NTT_CLEANUP        (0x01)
 823 /* Job Control CE Channel Masks */
 824 #define GNI_JOB_CTRL_CE0_MASK           (1<<0)
 825 #define GNI_JOB_CTRL_CE1_MASK           (1<<1)
 826 #define GNI_JOB_CTRL_CE2_MASK           (1<<2)
 827 #define GNI_JOB_CTRL_CE3_MASK           (1<<3)
 828 #define GNI_JOB_CTRL_ALL_CE_MASK        (GNI_JOB_CTRL_CE0_MASK | \
 829                                          GNI_JOB_CTRL_CE1_MASK | \
 830                                          GNI_JOB_CTRL_CE2_MASK | \
 831                                          GNI_JOB_CTRL_CE3_MASK)
 832
 833 typedef struct gni_job_limits {
 834         int32_t  mdd_limit;      /* IN number of MDDs associated with the given ptag */
 835         union {
 836                 int32_t  mrt_limit;          /* Gemini: IN number of MRT entries used by MDDs with the given ptag */
 837                 struct {
 838                         uint8_t  ce_limit;    /* Aries: IN number of CE channels available with the given ptag */
 839                         uint8_t  iommu_limit; /* Aries: IN 2 ^ N * 1MB bytes of address space per ptag */
 840                         uint8_t  res_byte2;
 841                         uint8_t  res_byte3;
 842                 } m;
 843         } a;
 844         union {
 845                 int32_t  gart_limit;     /* Gemini: IN number of GART entries used by MDDs with the given ptag */
 846                 int32_t  dla_limit;      /* Aries: IN number of DLA entries available with the given ptag */
 847         } b;
 848         int32_t  fma_limit;      /* IN number of FMA descriptors associated with the given ptag */
 849         int32_t  bte_limit;      /* IN number of outstanding BTE descriptors with the given src. ptag */
 850         int32_t  cq_limit;       /* IN number of CQ descriptors associated with the given ptag */
 851         int32_t  ntt_ctrl;       /* IN NTT cotrol flag (see GNI_JOB_CTRL_NTT_xxx above)*/
 852         int32_t  ntt_base;       /* IN Base entry into NTT */
 853         int32_t  ntt_size;       /* IN size of the NTT */
 854 } gni_job_limits_t;
 855
 856 typedef enum gni_nic_device {
 857         GNI_DEVICE_GEMINI = 0,
 858         GNI_DEVICE_ARIES  = 1,
 859         GNI_DEVICE_PISCES = 2,
 860         GNI_DEVICE_LAST
 861 } gni_nic_device_t;
 862
 863 /* Resource info types */
 864 typedef enum gni_dev_res {
 865         GNI_DEV_RES_FIRST = 0,
 866         GNI_DEV_RES_MDD,
 867         GNI_DEV_RES_MRT,
 868         GNI_DEV_RES_CQ,
 869         GNI_DEV_RES_FMA,
 870         GNI_DEV_RES_CE,
 871         GNI_DEV_RES_DLA,
 872         GNI_DEV_RES_LAST
 873 } gni_dev_res_t;
 874
 875 typedef struct gni_dev_res_desc {
 876         uint64_t available;
 877         uint64_t reserved;
 878         uint64_t held;
 879         uint64_t total;
 880 } gni_dev_res_desc_t;
 881
 882 typedef enum gni_job_res {
 883         GNI_JOB_RES_FIRST = 0,
 884         GNI_JOB_RES_MDD,
 885         GNI_JOB_RES_MRT,
 886         GNI_JOB_RES_IOMMU,
 887         GNI_JOB_RES_GART,
 888         GNI_JOB_RES_CQ,
 889         GNI_JOB_RES_FMA,
 890         GNI_JOB_RES_RMDA,
 891         GNI_JOB_RES_CE,
 892         GNI_JOB_RES_DLA,
 893         GNI_JOB_RES_SFMA,
 894         GNI_JOB_RES_LAST
 895 } gni_job_res_t;
 896
 897 typedef struct gni_job_res_desc {
 898         uint64_t used;
 899         uint64_t limit;
 900 } gni_job_res_desc_t;
 901
 902 typedef enum gni_statistic {
 903         GNI_STAT_SMSG_BUFF_CREDITS_STALL = 0,
 904         GNI_STAT_SMSG_DLA_STALL,
 905         GNI_STAT_SMSG_MBOX_CREDITS_STALL,
 906         GNI_STAT_SMSG_REQ_STALL,
 907         GNI_STAT_SMSG_RETRANS_COUNT,
 908         GNI_STAT_SMSG_RETRANS_DLA_COUNT,
 909         GNI_STAT_SMSG_RETRANS_STALL,
 910 #if defined CRAY_CONFIG_GHAL_ARIES
 911         GNI_STAT_DLA_ALLOC_STATUS_STALL,
 912         GNI_STAT_DLA_ALLOC_STATUS_TIMEOUT,
 913         GNI_STAT_DLA_BLOCK_ORPHANED,
 914         GNI_STAT_DLA_BLOCK_RETRANS_COUNT,
 915         GNI_STAT_DLA_FREE_BLOCKS_STALL,
 916         GNI_STAT_DLA_FREE_FMAD_BLOCKS_STALL,
 917         GNI_STAT_DLA_HIGH_RETRANS_COUNT,
 918         GNI_STAT_DLA_OVERFLOW_RESEND,
 919         GNI_STAT_DLA_RETRANS_COUNT,
 920         GNI_STAT_DLA_TOTAL_RETRANS_COUNT,
 921         GNI_STAT_FLBTE_TXD_CORRUPT,
 922         GNI_STAT_FLBTE_TXD_NONE,
 923 #endif
 924         GNI_NUM_STATS
 925 } gni_statistic_t;
 926
 927 extern const char *gni_statistic_str[];
 928
 929 #ifdef __KERNEL__
 930
 931 #define GNI_ERRNO_FUNC_STR_LEN          100
 932
 933 typedef struct gni_errno {
 934         uint8_t         valid;
 935         char            func[GNI_ERRNO_FUNC_STR_LEN];
 936         int             lineno;
 937         int             errno;
 938         uint64_t        data1;
 939         uint64_t        data2;
 940         uint64_t        data3;
 941         uint64_t        data4;
 942 } gni_errno_t;
 943
 944 #endif
 945
 946 #ifndef __KERNEL__
 947
 948 /* User level definitions */
 949
 950 /* public MSGQ definitions */
 951
 952 /* shared message queue receive callback function */
 953 typedef int gni_msgq_rcv_cb_func(
 954                 uint32_t snd_id,
 955                 uint32_t snd_pe,
 956                 void     *msg,
 957                 uint8_t  msg_tag,
 958                 void     *cb_data
 959                 );
 960
 961 /* MSGQ limits */
 962 #define GNI_MSGQ_MSG_SZ_MAX             128
 963 #define GNI_MSGQ_NODE_INSTS_MAX         48
 964
 965 /* MSGQ mode flags */
 966 #define GNI_MSGQ_MODE_BLOCKING          (0x01)
 967
 968 /* MSGQ structures */
 969 typedef struct gni_msgq_attr {
 970         uint32_t         max_msg_sz;
 971         uint32_t         smsg_q_sz;
 972         uint32_t         rcv_pool_sz;
 973         uint32_t         num_msgq_eps;
 974         uint32_t         nloc_insts;
 975         uint8_t          modes;
 976         uint32_t         rcv_cq_sz;
 977 } gni_msgq_attr_t;
 978
 979 typedef struct gni_msgq_rem_inst {
 980         uint32_t         id;      /* instance ID */
 981         gni_mem_handle_t mdh;     /* MDH for the shmem region */
 982         uint64_t         mdh_off; /* offset into the MDH for the smsg mbox */
 983 } gni_msgq_rem_inst_t;
 984
 985 typedef struct gni_msgq_ep_attr {
 986         uint32_t         pe_addr;
 987         uint32_t         max_msg_sz;
 988         uint32_t         smsg_q_sz;
 989         uint32_t         num_insts;
 990         gni_msgq_rem_inst_t insts[GNI_MSGQ_NODE_INSTS_MAX];
 991 } gni_msgq_ep_attr_t;
 992
 993 #define MAX_BUILD_STRING_LENGTH 80
 994
 995 typedef struct gni_version_info {
 996         uint32_t         ugni_version;
 997         uint32_t         ugni_svn_revision;
 998         char             ugni_build_string[MAX_BUILD_STRING_LENGTH];
 999         uint32_t         kgni_version;
1000         uint32_t         kgni_svn_revision;
1001         char             kgni_build_string[MAX_BUILD_STRING_LENGTH];
1002 } gni_version_info_t;
1003
1004 /* If return codes are modified, need to modify
1005    gni_err_str */
1006
1007 extern const char *gni_err_str[];
1008
1009
1010 /**
1011  * GNI_CdmCreate - Create Communication Domain
1012  *
1013  * Parameters:
1014  * IN
1015  * inst_id  Instance of the cdm in the job (user level).
1016  *          Unique address of the instance within the upper layer
1017  *          protocol domain (kernel level).
1018  * ptag     Protection Tag.
1019  * cookie   Unique identifier generated by ALPS. Along with ptag
1020  *          helps to identify the Communication Domain.
1021  * modes    bit mask (see GNI_CDM_MODE_xxxxxx definitions)
1022  *
1023  * OUT
1024  * cdm_hndl     Handle returned. The handle is used with the other functions
1025  *      to specify a particular instance of the Communication Domain.
1026  *
1027  * Returns:
1028  * GNI_RC_SUCCESS - Operation completed successfully.
1029  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
1030  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
1031  *
1032  * Description:
1033  * This function creates an instance of the Communication Domain.
1034  **/
1035 gni_return_t
1036         GNI_CdmCreate(
1037                 IN  uint32_t            inst_id,
1038                 IN  uint8_t             ptag,
1039                 IN  uint32_t            cookie,
1040                 IN  uint32_t            modes,
1041                 OUT gni_cdm_handle_t    *cdm_hndl
1042                 );
1043
1044 /**
1045  * GNI_CdmDestroy - Destroys the instance of a Communication Domain
1046  *
1047  * Parameters:
1048  * IN
1049  * cdm_hndl   Communication Domain Handle
1050  *
1051  * Returns:
1052  * GNI_RC_SUCCESS - The operation completed successfully
1053  * GNI_RC_INVALID_PARAM - Caller specified an invalid Communication Domain Handle
1054  *
1055  * Description:
1056  * Destroys the instance of a Communication Domain.  Removes associations
1057  * between the calling process and the NIC devices that were established via
1058  * the corresponding Attach function.
1059  **/
1060 gni_return_t
1061         GNI_CdmDestroy(
1062                 IN gni_cdm_handle_t     cdm_hndl
1063                 );
1064
1065 /**
1066  * GNI_CdmGetNicAddress - Get the PE address of a GNI device.
1067  *
1068  * Parameters:
1069  * IN
1070  * device_id    The ID of the GNI device to query.
1071  *
1072  * OUT
1073  * address      The PE address of the GNI device queried.
1074  * cpu_id       The ID of the first CPU directly connected to the GNI device.
1075  *
1076  * Returns:
1077  * GNI_RC_SUCCESS - Operation completed successfully.
1078  * GNI_RC_NO_MATCH - Specified device_id does not exists.
1079  *
1080  * Description:
1081  *
1082  * Returns the PE address of the GNI device with ID device_id and the ID of
1083  * it's most closely connected CPU.
1084  **/
1085 gni_return_t
1086         GNI_CdmGetNicAddress(
1087                 IN  uint32_t    device_id,
1088                 OUT uint32_t    *address,
1089                 OUT uint32_t    *cpu_id
1090                 );
1091
1092 /**
1093  * GNI_CdmAttach - Attach Communication Domain to a NIC device
1094  *
1095  * Parameters:
1096  * IN
1097  * cdm_hndl     The Communication Domain Handle.
1098  * device_id    The device identifier , e.g. /dev/kgni1 has
1099  *              device_id = DEVICE_MINOR_NUMBER - GEMINI_BASE_MINOR_NUMBER = 1
1100  *              Setting device_id to (-1) will result in attaching to the nearest
1101  *              Gemini NIC.
1102  *
1103  * OUT
1104  * local_addr   PE address of the Gemini NIC attached
1105  * nic_hndl     Handle returned. The handle is used with the other functions to specify
1106  *              a particular instance of a Gemini NIC.
1107  * Returns:
1108  * GNI_RC_SUCCESS - Operation completed successfully.
1109  * GNI_RC_INVALID_PARAM - Caller specified an invalid CDM handle.
1110  * GNI_RC_NO_MATCH - Specified device_id does not exists
1111  * GNI_RC_ERROR_RESOURCE - The operation failed due to insufficient resources.
1112  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
1113  * GNI_RC_PERMISSION_ERROR - Insufficient permissions to perform operation.
1114  * GNI_RC_INVALID_STATE - Caller attempts to attach the same CDM instance to
1115  *                        the same Gemini NIC device more than once.
1116  *                        If returned while device_id= -1, means that there
1117  *                        are no more devices left for this CDM to attach to.
1118  * GNI_RC_NOT_DONE - The process was interrupted.
1119  *
1120  * Description:
1121  * Associates the Communication Domain with a Gemini NIC and provides a
1122  * NIC handle to the upper layer protocol. A process is not allowed
1123  * to attach the same CDM instance to the same Gemini NIC more than once,
1124  * but it is allowed to attach multiple CDMs to the same Gemini NIC.
1125  **/
1126 gni_return_t
1127         GNI_CdmAttach(
1128                 IN  gni_cdm_handle_t    cdm_hndl,
1129                 IN  uint32_t            device_id,
1130                 OUT uint32_t            *local_addr,
1131                 OUT gni_nic_handle_t    *nic_hndl
1132                 );
1133
1134 /**
1135  * GNI_CdmCheckpoint - Sets the checkpoint bit for each GNI nic handle
1136  *
1137  * Parameter:
1138  * IN
1139  * cdm_handle   Communication Domain Handle
1140  *
1141  * Returns:
1142  * GNI_RC_SUCCESS - The operation completed successfully
1143  * GNI_RC_INVALID_PARAM - Caller specified an invalid Communication Domain Handle
1144  *
1145  * Description:
1146  * This will set the checkpoint bit in each GNI NIC handle so that subsequent GNI library
1147  * calls made following a restart will not perform any system calls on the (now closed)
1148  * GNI device. This is needed so that it's safe to call GNI_CqDestroy and GNI_CdmDestroy
1149  * after a restart, as these now stale GNI resources have to be freed.
1150  **/
1151 gni_return_t
1152         GNI_CdmCheckpoint(
1153                 IN gni_cdm_handle_t     cdm_handle
1154                 );
1155
1156 /**
1157  * GNI_CdmResume- Unsets the checkpoint bit for each GNI nic handle
1158  *
1159  * Parameter:
1160  * IN
1161  * cdm_handle   Communication Domain Handle
1162  *
1163  * Returns:
1164  * GNI_RC_SUCCESS - The operation completed successfully
1165  * GNI_RC_INVALID_PARAM - Caller specified an invalid Communication Domain Handle
1166  *
1167  * Description:
1168  * Reverses the effects of GNI_CdmCheckpoint.
1169  **/
1170 gni_return_t
1171         GNI_CdmResume(
1172                 IN gni_cdm_handle_t     cdm_handle
1173                 );
1174
1175 /**
1176  * GNI_SuspendJob - Suspend GNI resources belonging to a job
1177  *
1178  * Parameter:
1179  * IN
1180  * device_id    The ID of the GNI device to use
1181  * job_id       The ID of the job using the communication domain to suspend
1182  * ptag         The PTAG of the communication domain to suspend
1183  * cookie       The cookie used by the communication domain to suspend
1184  * timeout      The Wait timeout in milliseconds
1185  *
1186  * Returns:
1187  * GNI_RC_SUCCESS - The job is suspended
1188  * GNI_RC_INVALID_PARAM - An invalid parameter was specified
1189  * GNI_RC_TIMEOUT - Timed out waiting for the operation to complete
1190  * GNI_RC_PERMISSION_ERROR - Caller is not a privileged user
1191  * GNI_RC_NOT_DONE - Job cannot be suspended at this point, try again
1192  * GNI_RC_INVALID_STATE - Job suspend is already pending
1193  * GNI_RC_ERROR_RESOURCE - Job does not support suspension
1194  *
1195  * Description:
1196  * GNI_SuspendJob notifies the GNI SW stack that the job identified by the
1197  * device ID and protection tag is going to be suspended.  This function can
1198  * block until SW stack is ready for the job to be suspended or until the
1199  * timeout expires.
1200  */
1201 gni_return_t
1202         GNI_SuspendJob(
1203                 IN uint32_t     device_id,
1204                 IN uint64_t     job_id,
1205                 IN uint8_t      ptag,
1206                 IN uint32_t     cookie,
1207                 IN uint32_t     timeout
1208                 );
1209
1210 /**
1211  * GNI_ResumeJob - Un-suspend GNI resources belonging to a job
1212  *
1213  * Parameter:
1214  * IN
1215  * device_id    The ID of the GNI device to use
1216  * job_id       The ID of the job using the communication domain to resume
1217  * ptag         The PTAG of the communication domain to resume
1218  * cookie       The cookie used by the communicatio domain to resume
1219  *
1220  * Returns:
1221  * GNI_RC_SUCCESS - The job is resumed
1222  * GNI_RC_INVALID_PARAM - An invalid parameter was specified
1223  * GNI_RC_PERMISSION_ERROR - Caller is not a privileged user
1224  * GNI_RC_INVALID_STATE - Job was not suspended
1225  *
1226  * Description:
1227  * GNI_ResumeJob notifies the GNI SW stack that the job identified by the
1228  * device ID and protection tag is going to resume its execution.
1229  */
1230 gni_return_t
1231         GNI_ResumeJob(
1232                 IN uint32_t     device_id,
1233                 IN uint64_t     job_id,
1234                 IN uint8_t      ptag,
1235                 IN uint32_t     cookie
1236                 );
1237
1238 /**
1239  * GNI_ConfigureNTT - Configure NTT entries for a Gemini device
1240  *
1241  * Parameters:
1242  * IN
1243  * device_id    The device identifier , e.g. /dev/kgni1 has
1244  *              device_id = DEVICE_MINOR_NUMBER - GEMINI_BASE_MINOR_NUMBER = 1.
1245  * ntt_desc     NTT configuration descriptor.
1246  * OUT
1247  * ntt_base     On return, is set to the base NTT
1248  *              entry allocated by the driver.
1249  *
1250  * Returns:
1251  * GNI_RC_SUCCESS - Operation completed successfully.
1252  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
1253  * GNI_RC_PERMISSION_ERROR - Process has insufficient permissions to set up
1254  *                           NTT resources.
1255  * GNI_RC_ERROR_RESOURCE - hardware resource limitation prevents NTT setup.
1256  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
1257  * GNI_RC_NO_MATCH - the specified device_id does not exist.
1258  *
1259  * Description:
1260  * This function sets up entries in the NTT associated with a particular
1261  * Gemini device.
1262  *
1263  * Notes:
1264  * If the table field of the input ntt_desc is set to NULL, the NTT
1265  * entries starting from ntt_base up to and including
1266  * ntt_base + ntt_desc->group_size - 1 will be reset to 0.
1267  *
1268  * If the ntt_base is -1 and ntt_desc->group_size is -1 and
1269  * the table field of ntt_desc is NULL all entries of NTT allocations not
1270  * currently in use will be reset to 0.
1271  *
1272  **/
1273 gni_return_t
1274         GNI_ConfigureNTT(
1275                 IN  int                         device_id,
1276                 IN  gni_ntt_descriptor_t        *ntt_desc,
1277                 OUT uint32_t                    *ntt_base
1278                 );
1279
1280 /**
1281  * GNI_ConfigureJob - Configure parameters of the job
1282  *
1283  * Parameters:
1284  * IN
1285  * device_id    The device identifier , e.g. /dev/kgni1 has
1286  *              device_id = DEVICE_MINOR_NUMBER - GEMINI_BASE_MINOR_NUMBER = 1.
1287  * job_id       Job container identifier.
1288  * ptag         Protection tag to be used by all applications in the given job container.
1289  * cookie       Unique identifier. Assigned to all applications within the
1290  *              job container along with ptag.
1291  * limits       Driver takes all the limit values,
1292  *              that are not set to GNI_JOB_INVALID_LIMIT, and stores them into the
1293  *              table indexed by the ptag. These limits will get imposed on all
1294  *              the applications running within the given job container.
1295  *              Setting limits for the same ptag will overwrite previously set limits.
1296  *
1297  * Return:
1298  *
1299  * GNI_RC_SUCCESS - Operation completed successfully.
1300  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
1301  * GNI_RC_PERMISSION_ERROR - Process has insufficient permissions to configure job
1302  * GNI_RC_NO_MATCH - the specified device_id does not exist or no NTT entries
1303  *                   exist for input ntt_base/ntt_size fields in the limits argument.
1304  * GNI_RC_INVALID_STATE - attempt to use the same ptag with different job_id or
1305  *                        different cookie.
1306  * GNI_RC_ILLEGAL_OP - the application is attempting to resize the NTT resources
1307  * GNI_RC_ERROR_RESOURCE - a resource allocation error was encountered while
1308  *                         trying to configure the job resources.
1309  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
1310  *
1311  * Description:
1312  *
1313  * The user(ALPS) can call this function multiple times for the same Gemini interface.
1314  * Driver looks up a triplet (job_id+ptag+cookie) and then adds a new entry into
1315  * the list it maintains per physical NIC, for every unique triplet.
1316  * Each entry may have non-unique job_id or ptag or cookie.
1317  * Using the same ptag with different job_ids's considered to be illegal
1318  * and such calls will fail.
1319  * This function must be called before GNI_CdmAttach() for the
1320  * CDM with the same ptag+cookie.
1321  * Calling GNI_ConfigureJob for the same triplet will have no effect,
1322  * unless limit argument is non-NULL.
1323  *
1324  * This function may also be used to associated NTT resources with a job.  The
1325  * NTT resources would have been previously allocated by a call to GNI_ConfigureNTT.
1326  * In this case, the application shall set the ntt_base and ntt_size fields
1327  * in the limits input.  If the application expects the driver to cluean up
1328  * the NTT resources upon termination of the job, the ntt_ctrl field in the
1329  * limits input must be set to GNI_JOB_CTRL_NTT_CLEANUP.  The application should
1330  * not attempt to change ntt_base or ntt_size by calling ConfigureJob a subsequent
1331  * time with different NTT parameters.
1332  *
1333  **/
1334 gni_return_t
1335         GNI_ConfigureJob(
1336                 IN uint32_t             device_id,
1337                 IN uint64_t             job_id,
1338                 IN uint8_t              ptag,
1339                 IN uint32_t             cookie,
1340                 IN gni_job_limits_t     *limits
1341                 );
1342
1343 /**
1344  * GNI_ConfigureNTTandJob - Configure NTT entries for a Gemini device and parameters of the job
1345  *
1346  * Parameters:
1347  * IN
1348  * device_id    The device identifier , e.g. /dev/gemini1 has
1349  *              device_id = DEVICE_MINOR_NUMBER - GEMINI_BASE_MINOR_NUMBER = 1.
1350  * job_id       Job container identifier.
1351  * ptag         Protection tag to be used by all applications in the given job container.
1352  * cookie       Unique identifier. Assigned to all applications within the
1353  *              job container along with ptag.
1354  * limits       Driver takes all the limit values,
1355  *              that are not set to GNI_JOB_INVALID_LIMIT, and stores them into the
1356  *              table indexed by the ptag. These limits will get imposed on all
1357  *              the applications running within the given job container.
1358  *              Setting limits for the same ptag will overwrite previously set limits.
1359  * ntt_desc     NTT configuration descriptor.
1360  * OUT
1361  * ntt_base     On return, is set to the base NTT
1362  *              entry allocated by the driver.
1363  *
1364  * Returns:
1365  * GNI_RC_SUCCESS - Operation completed successfully.
1366  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
1367  * GNI_RC_PERMISSION_ERROR - Process has insufficient permissions to set up
1368  *                           NTT resources.
1369  * GNI_RC_ERROR_RESOURCE - hardware resource limitation prevents NTT setup or
1370  *                         some other resource allocation error was encountered while
1371  *                         trying to configure the job resources
1372  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
1373  * GNI_RC_NO_MATCH - the specified device_id does not exist or no NTT entries
1374  *                   exist for input ntt_base/ntt_size fields in the limits argument.
1375  * GNI_RC_INVALID_STATE - attempt to use the same ptag with different job_id or
1376  *                        different cookie.
1377  * GNI_RC_ILLEGAL_OP - the application is attempting to resize the NTT resources
1378  *
1379  * Description:
1380  * This function sets up entries in the NTT associated with a particular
1381  * Gemini device and then configures parameters of the job in a single system call
1382  *
1383  * The user(ALPS) can call this function instead of calling GNI_ConfigureNTT and
1384  * GNI_ConfigureJob one after another. Setting ntt_desc to NULL will make this
1385  * function equivalent to GNI_ConfigureJob.
1386  * Driver looks up a triplet (job_id+ptag+cookie) and then adds a new entry into
1387  * the list it maintains per physical NIC, for every unique triplet.
1388  * Each entry may have non-unique job_id or ptag or cookie.
1389  * Using the same ptag with different job_ids's considered to be illegal
1390  * and such calls will fail.
1391  * This function or GNI_ConfigureJob must be called before GNI_CdmAttach() for the
1392  * CDM with the same ptag+cookie.
1393  *
1394  * This function can be used to associated NTT resources with a job.
1395  * If the application expects the driver to clean up the NTT resources
1396  * upon termination of the job, the ntt_ctrl field in the limits input must be set
1397  * to GNI_JOB_CTRL_NTT_CLEANUP.
1398  * The application should not attempt to change ntt_base or ntt_size by calling
1399  * ConfigureJob a subsequent time with different NTT parameters.
1400  *
1401  * Note:
1402  * This function can't be used to clear NTT table. GNI_ConfigureNTT should be used instead.
1403  **/
1404 gni_return_t
1405         GNI_ConfigureNTTandJob(
1406                 IN  int                         device_id,
1407                 IN  uint64_t                    job_id,
1408                 IN  uint8_t                     ptag,
1409                 IN  uint32_t                    cookie,
1410                 IN  gni_job_limits_t            *limits,
1411                 IN  gni_ntt_descriptor_t        *ntt_desc,
1412                 OUT uint32_t                    *ntt_base
1413                 );
1414
1415 /**
1416  * GNI_EpCreate - Create logical Endpoint
1417  *
1418  * Parameters:
1419  * IN
1420  * nic_hndl     Handle of the associated Gemini NIC.
1421  * src_cq_hndl  Handle of the CQ that will be used by default to deliver events
1422  *              related to the transactions initiated by the local node.
1423  *
1424  * OUT
1425  * ep_hndl      The handle of the newly created Endpoint instance.
1426  *
1427  * Returns:
1428  * GNI_RC_SUCCESS - Operation completed successfully.
1429  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
1430  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
1431  *
1432  * Description:
1433  * This function creates an instance of a Logical Endpoint.
1434  * A new instance is always created in a non-bound state.
1435  * A non-bound Endpoint is able to exchange posted data with
1436  * any bound remote Endpoint within the same Communication Domain.
1437  * An Endpoint cannot be used to post RDMA, FMA transactions or
1438  * send short messages while it is in non-bound state.
1439  **/
1440 gni_return_t
1441         GNI_EpCreate(
1442                 IN  gni_nic_handle_t    nic_hndl,
1443                 IN  gni_cq_handle_t     src_cq_hndl,
1444                 OUT gni_ep_handle_t     *ep_hndl
1445                 );
1446
1447 /**
1448  * GNI_EpSetEventData - Set event data for local and remote events
1449  *
1450  * Parameters:
1451  * IN
1452  * ep_hndl      The handle of the Endpoint instance.
1453  * local_event  Value to use when generating LOCAL CQ events
1454  * remote_event Value to use when generating GLOBAL & REMOTE CQ events
1455  *
1456  * Returns:
1457  * GNI_RC_SUCCESS - Operation completed successfully.
1458  * GNI_RC_INVALID_PARAM - Invalid EP handle.
1459  *
1460  * Description:
1461  * By default GNI uses local instance_id as an event data for GLOBAL and REMOTE CQ events,
1462  * and EP remote_id when generating LOCAL CQ events.
1463  * This function allows to re-assign these events to the user defined values.
1464  **/
1465 gni_return_t
1466         GNI_EpSetEventData(
1467                 IN gni_ep_handle_t      ep_hndl,
1468                 IN uint32_t             local_event,
1469                 IN uint32_t             remote_event
1470                 );
1471
1472 /**
1473  * GNI_EpBind - Bind logical Endpoint to a peer
1474  *
1475  * Parameters:
1476  * IN
1477  * ep_hndl      The handle of the Endpoint instance to be bound.
1478  * remote_addr  Physical address of the Gemini NIC at the remote peer or NTT index,
1479  *              when NTT is enabled for the given Communication Domain.
1480  * remote_id    User specified ID of the remote instance in the job or unique identifier of
1481  *              the remote instance within the upper layer protocol domain.
1482  *
1483  * Returns:
1484  * GNI_RC_SUCCESS - Operation completed successfully.
1485  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
1486  * GNI_RC_ERROR_RESOURCE - The operation failed due to insufficient resources.
1487  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
1488  *
1489  * Description:
1490  * This function binds a Logical Endpoint to the specific remote address
1491  * and remote instance in the Communication Domain.
1492  * Once bound the Endpoint can be used to post RDMA and FMA transactions.
1493  **/
1494 gni_return_t
1495         GNI_EpBind(
1496                 IN gni_ep_handle_t      ep_hndl,
1497                 IN uint32_t             remote_addr,
1498                 IN uint32_t             remote_id
1499                 );
1500
1501 /**
1502  * GNI_EpUnbind - Unbind logical Endpoint
1503  *
1504  * Parameters:
1505  * IN
1506  * ep_hndl      The handle of the Endpoint instance to be bound.
1507  *
1508  * Returns:
1509  * GNI_RC_SUCCESS - Operation completed successfully.
1510  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
1511  * GNI_RC_NOT_DONE - Operation is not permited
1512  *
1513  * Description:
1514  * This function unbinds a Logical Endpoint from the specific remote address
1515  * and remote instance and releases any internal short message resource.
1516  * A non-bound Endpoint is able to exchange posted data with
1517  * any bound remote Endpoint within the same Communication Domain.
1518  * An Endpoint cannot be used to post RDMA, FMA transactions or
1519  * send short messages while it is in non-bound state.
1520  **/
1521 gni_return_t
1522         GNI_EpUnbind(
1523                 IN gni_ep_handle_t      ep_hndl
1524                 );
1525
1526 /**
1527  * GNI_EpIdle - prepare the GNI endpoint for checkpoint
1528  *
1529  * Parameters:
1530  * IN
1531  * ep_hndl      The handle of the Endpoint instance to check
1532  *
1533  * Returns:
1534  * GNI_RC_SUCCESS - Operation completed successfully.
1535  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
1536  * GNI_RC_NOT_DONE - Operation is not permited
1537  *
1538  * Description:
1539  * Should be called prior to checkpoint for each GNI endpoint in use until
1540  * GNI_RC_SUCCESS is received. This will perform a subset of what is done in
1541  * GNI_EpUnbind to inspect if the GNI endpoint is idle and able to be safely
1542  * checkpointed. This function will not destroy any resources.
1543  **/
1544 gni_return_t
1545         GNI_EpIdle(
1546                 IN gni_ep_handle_t      ep_hndl
1547                 );
1548
1549 /**
1550  * GNI_EpDestroy - Destroy logical Endpoint
1551  *
1552  * Parameters:
1553  * IN
1554  * ep_hndl      The handle of the Endpoint instance to be destroyed.
1555  *
1556  * Returns:
1557  * GNI_RC_SUCCESS - Operation completed successfully.
1558  * GNI_RC_INVALID_PARAM - An invalid EP handle was specified.
1559  *
1560  * Description:
1561  * This function tears down an Endpoint.
1562  **/
1563 gni_return_t
1564         GNI_EpDestroy(
1565                 IN gni_ep_handle_t      ep_hndl
1566                 );
1567
1568 /**
1569  * GNI_EpPostData - Exchange datagram with a remote Endpoint
1570  *
1571  * Parameters:
1572  * IN
1573  * ep_hndl      Handle of the local Endpoint.
1574  * in_data      pointer to the data to be sent
1575  * data_len     size of the data to be sent
1576  * out_buf      buffer to receive incoming datagram
1577  * buf_size     size of the buffer for incoming datagram
1578  *
1579  * Returns:
1580  * GNI_RC_SUCCESS - Posted datagram was queued.
1581  * GNI_RC_INVALID_PARAM - An invalid EP handle was specified.
1582  * GNI_RC_ERROR_RESOURCE - Only one outstanding datagram transaction per
1583  *                         Endpoint is allowed.
1584  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
1585  * GNI_RC_SIZE_ERROR - Size of datagram is too big.
1586  *
1587  * Description:
1588  * This function posts a datagram to be exchanged with a remote Endpoint in the CDM.
1589  * If the EP is unbound a datagram can be exchanged with any bound Endpoint in the CDM.
1590  **/
1591 gni_return_t
1592         GNI_EpPostData(
1593                 IN gni_ep_handle_t      ep_hndl,
1594                 IN void                 *in_data,
1595                 IN uint16_t             data_len,
1596                 IN void                 *out_buf,
1597                 IN uint16_t             buf_size
1598                 );
1599
1600 /**
1601  * GNI_EpPostDataWId - Exchange datagram with a remote Endpoint, assigning an
1602  *                     id to the datagram.
1603  *
1604  * Parameters:
1605  * IN
1606  * ep_hndl      Handle of the local Endpoint.
1607  * in_data      pointer to the data to be sent
1608  * data_len     size of the data to be sent
1609  * out_buf      buffer to receive incoming datagram
1610  * buf_size     size of the buffer for incoming datagram
1611  * datagram_id  id associated with the datagram
1612  *
1613  * Returns:
1614  * GNI_RC_SUCCESS - Posted datagram was queued.
1615  * GNI_RC_INVALID_PARAM - An invalid EP handle was specified or an invalid
1616  *                        value (-1) for the datagram_id was specified.
1617  * GNI_RC_ERROR_RESOURCE - Only one outstanding datagram transaction per
1618  *                         Endpoint is allowed.
1619  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
1620  * GNI_RC_SIZE_ERROR - Size of datagram is too big.
1621  *
1622  * Description:
1623  * This function posts a datagram to be exchanged with a remote Endpoint in the CDM
1624  * and associated an Id with the datagram.
1625  * If the EP is unbound a datagram can be exchanged with any bound Endpoint in the CDM.
1626  *
1627  * Notes:
1628  * It may be useful to associated an Id with a datagram when intermixing usage of
1629  * bound and unbound EP's with datagrams.
1630  **/
1631 gni_return_t
1632         GNI_EpPostDataWId(
1633                 IN gni_ep_handle_t      ep_hndl,
1634                 IN void                 *in_data,
1635                 IN uint16_t             data_len,
1636                 IN void                 *out_buf,
1637                 IN uint16_t             buf_size,
1638                 IN uint64_t             datagram_id
1639                 );
1640
1641 /**
1642  * GNI_EpPostDataTest - Tests for completion of GNI_EpPostData operation
1643  *
1644  * Parameters:
1645  * IN
1646  * ep_hndl      Handle of the local Endpoint.
1647  *
1648  * OUT
1649  * post_state   State of the transaction is returned.
1650  * remote_addr  Physical address of the Gemini NIC at the remote peer.
1651  *              Valid only if post_state returned GNI_POST_COMPLETED.
1652  *              (This address is virtual if GNI_CDM_MODE_NTT_ENABLE).
1653  * remote_id    User specific ID of the remote instance in the job (user)
1654  *              Unique address of the remote instance within the upper layer
1655  *              protocol domain (kernel). Valid only if post_state returned
1656  *              GNI_POST_COMPLETED.
1657  *
1658  * Returns:
1659  * GNI_RC_SUCCESS - Post status is returned through the second function parameter.
1660  * GNI_RC_INVALID_PARAM - An invalid EP handle was specified.
1661  * GNI_RC_NO_MATCH - No matching datagram was found.
1662  * GNI_RC_SIZE_ERROR - Output buffer is too small for the size of the received
1663  *                     datagram.
1664  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
1665  *
1666  * Description:
1667  * This function returns the state of the PostData transaction.
1668  **/
1669 gni_return_t
1670         GNI_EpPostDataTest(
1671                 IN  gni_ep_handle_t     ep_hndl,
1672                 OUT gni_post_state_t    *post_state,
1673                 OUT uint32_t            *remote_addr,
1674                 OUT uint32_t            *remote_id
1675                 );
1676
1677 /**
1678  * GNI_EpPostDataTestById - Tests for completion of GNI_EpPostData operation for
1679  *                          a datagram using Id
1680  *
1681  * Parameters:
1682  * IN
1683  * ep_hndl      Handle of the local Endpoint.
1684  * datagram_id  Id of datagram to test for.
1685  *
1686  * OUT
1687  * post_state   State of the transaction is returned.
1688  * remote_addr  Physical address of the Gemini NIC at the remote peer.
1689  *              Valid only if post_state returned GNI_POST_COMPLETED.
1690  *              (This address is virtual if GNI_CDM_MODE_NTT_ENABLE).
1691  * remote_id    User specific ID of the remote instance in the job (user)
1692  *              Unique address of the remote instance within the upper layer
1693  *              protocol domain (kernel). Valid only if post_state returned
1694  *              GNI_POST_COMPLETED.
1695  *
1696  * Returns:
1697  * GNI_RC_SUCCESS - Post status is returned through the second function parameter.
1698  * GNI_RC_INVALID_PARAM - An invalid EP handle or an invalid datagram_id was specified.
1699  * GNI_RC_NO_MATCH - No matching datagram was found.
1700  * GNI_RC_SIZE_ERROR - Output buffer is too small for the size of the received
1701  *                     datagram.
1702  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
1703  *
1704  * Description:
1705  * This function returns the state of the PostData transaction.
1706  *
1707  * Notes:
1708  * The ep handle supplied as input must be the same as that
1709  * used when posting the datagram using GNI_EpPostDataWId.
1710  **/
1711 gni_return_t
1712         GNI_EpPostDataTestById(
1713                 IN  gni_ep_handle_t     ep_hndl,
1714                 IN  uint64_t            datagram_id,
1715                 OUT gni_post_state_t    *post_state,
1716                 OUT uint32_t            *remote_addr,
1717                 OUT uint32_t            *remote_id
1718                 );
1719
1720 /**
1721  * GNI_EpPostDataWait - Wait for the PostData transaction to complete
1722  *
1723  * Parameters:
1724  * IN
1725  * ep_hndl      Handle of the local Endpoint.
1726  * timeout      The count that this function waits, in milliseconds, for
1727  *              connection to complete.
1728  *              Set to (-1) if no timeout is desired. A timeout value of zero
1729  *              results in a GNI_RC_INVALID_PARAM error returned.
1730  *
1731  * OUT
1732  * post_state   State of the transaction is returned.
1733  * remote_addr  Physical address of the Gemini NIC at the remote peer.
1734  *              Valid only if post_state returned GNI_POST_COMPLETED.
1735  *              (This address is virtual if GNI_CDM_MODE_NTT_ENABLE).
1736  * remote_id    User specific ID of the remote instance in the job (user)
1737  *              Unique address of the remote instance within the upper layer
1738  *              protocol domain (kernel). Valid only if post_state returned
1739  *              GNI_POST_COMPLETED.
1740  *
1741  * Returns:
1742  * GNI_RC_SUCCESS - The transaction completed successfully.
1743  * GNI_RC_INVALID_PARAM - An invalid EP handle was specified or timeout was set to zero.
1744  * GNI_RC_TIMEOUT - The timeout expired before a datagram completion.
1745  * GNI_RC_SIZE_ERROR - Output buffer is too small for the size of the received datagram.
1746  * GNI_RC_NO_MATCH - No matching datagram was found.
1747  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
1748  *
1749  * Description:
1750  * This function is used to determine the result of a previously posted EpPostData
1751  * call on the specified Endpoint, blocking the calling thread until the completion
1752  * of the posted transaction or until the specified timeout expires.
1753  **/
1754 gni_return_t
1755         GNI_EpPostDataWait(
1756                 IN  gni_ep_handle_t     ep_hndl,
1757                 IN  uint32_t            timeout,
1758                 OUT gni_post_state_t    *post_state,
1759                 OUT uint32_t            *remote_addr,
1760                 OUT uint32_t            *remote_id
1761                 );
1762
1763 /**
1764  * GNI_EpPostDataWaitById - Wait for the PostData transaction with a given ID to complete
1765  *
1766  * Parameters:
1767  * IN
1768  * ep_hndl      Handle of the local Endpoint.
1769  * timeout      The count that this function waits, in milliseconds, for
1770  *              connection to complete.
1771  *              Set to (-1) if no timeout is desired. A timeout value of zero
1772  *              results in a GNI_RC_INVALID_PARAM error returned.
1773  * datagram_id  Id of datagram to wait for.
1774  *
1775  * OUT
1776  * post_state   State of the transaction is returned.
1777  * remote_addr  Physical address of the Gemini NIC at the remote peer.
1778  *              Valid only if post_state returned GNI_POST_COMPLETED.
1779  *              (This address is virtual if GNI_CDM_MODE_NTT_ENABLE).
1780  * remote_id    User specific ID of the remote instance in the job (user)
1781  *              Unique address of the remote instance within the upper layer
1782  *              protocol domain (kernel). Valid only if post_state returned
1783  *              GNI_POST_COMPLETED.
1784  *
1785  * Returns:
1786  * GNI_RC_SUCCESS - The transaction completed successfully.
1787  * GNI_RC_INVALID_PARAM - An invalid EP handle was specified or timeout was set to zero or
1788  *                        an invalid datagram id was specified.
1789  * GNI_RC_TIMEOUT - The timeout expired before a successful completion of the transaction.
1790  * GNI_RC_SIZE_ERROR - Output buffer is too small for the size of the received
1791  *                     datagram.
1792  * GNI_RC_NO_MATCH - No matching datagram was found.
1793  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
1794  *
1795  * Description:
1796  * This function is used to determine the result of a previously posted EpPostData
1797  * call on the specified Endpoint and datagram Id, blocking the calling thread until the completion
1798  * of the posted transaction or until the specified timeout expires.
1799  *
1800  * Notes:
1801  * The ep handle supplied as input must be the same as that
1802  * used when posting the datagram using GNI_EpPostDataWId.
1803  **/
1804 gni_return_t
1805         GNI_EpPostDataWaitById(
1806                 IN  gni_ep_handle_t     ep_hndl,
1807                 IN  uint64_t            datagram_id,
1808                 IN  uint32_t            timeout,
1809                 OUT gni_post_state_t    *post_state,
1810                 OUT uint32_t            *remote_addr,
1811                 OUT uint32_t            *remote_id
1812                 );
1813
1814 /**
1815  * GNI_PostDataProbe - Probe for datagrams associated with a cdm/nic which
1816  *                     are in completed, timed out, or cancelled state.
1817  *
1818  * Parameters:
1819  * IN
1820  * nic_hndl     Handle of a nic associated with the cdm for which datagrams
1821  *              status is being probed.
1822  *
1823  * OUT
1824  * remote_addr  Physical address of the Gemini NIC at the remote peer.
1825  *              Valid only if return value is GNI_RC_SUCCESS.
1826  *              (This address is virtual if GNI_CDM_MODE_NTT_ENABLE).
1827  * remote_id    User specific ID of the remote instance in the job (user)
1828  *              Unique address of the remote instance within the upper layer
1829  *              protocol domain (kernel). Valid only if return value is
1830  *              GNI_RC_SUCCESS.
1831  *
1832  * Returns:
1833  * GNI_RC_SUCCESS - A datagram in the completed, timed out or cancelled state was found.
1834  *                  The remote_addr and remote_id of the datagram are
1835  *                  in the remote_addr and remote_id arguments.
1836  * GNI_RC_INVALID_PARAM - An invalid NIC handle or invalid address for remote_addr or
1837  *                        remote_id was specified.
1838  * GNI_RC_NO_MATCH - No datagram in completed, timed out, or cancelled state was found.
1839  *
1840  * Description:
1841  * This function returns the remote_addr and remote_id of the first datagram found in
1842  * completed, timed out, or canceled state for the cdm associated with the
1843  * input nic handle.  This function must be used in conjunction
1844  * with GNI_EpPostDataTest or GNI_EpPostDataWait to obtain data exchanged
1845  * in the datagram transaction.
1846  **/
1847 gni_return_t
1848         GNI_PostDataProbe(
1849                 IN  gni_nic_handle_t    nic_hndl,
1850                 OUT uint32_t            *remote_addr,
1851                 OUT uint32_t            *remote_id
1852                 );
1853
1854 /**
1855  * GNI_PostDataProbeById - Probe by ID for datagrams associated with a cdm/nic which
1856  *                         are in completed, timed out, or cancelled state.
1857  *
1858  * Parameters:
1859  * IN
1860  * nic_hndl     Handle of a nic associated with the cdm for which datagrams
1861  *              status is being probed.
1862  *
1863  * OUT
1864  * datagram_id  Id of first datagram found to be in completed, timed out, or
1865  *              cancelled state.  Valid only if the return value is GNI_RC_SUCCESS.
1866  *
1867  * Returns:
1868  * GNI_RC_SUCCESS - A datagram previously posted with a datagram_id in the completed,
1869  *                  timed out or cancelled state was found.
1870  *                  The id of the datagram is returned in the datagram_id argument.
1871  * GNI_RC_INVALID_PARAM - An invalid NIC handle or an invalid datagram_id address was specified.
1872  * GNI_RC_NO_MATCH - No datagram in completed, timed out, or cancelled state was found.
1873  *
1874  * Description:
1875  * This function returns the postid of the first datagram posted with a datagram_id found in
1876  * completed, timed out, or canceled state for the cdm associated with the
1877  * input nic handle.  This function must be used in conjunction
1878  * with GNI_EpPostDataTestById or GNI_EpPostDataWaitById to obtain data exchanged
1879  * in the datagram transaction.
1880  *
1881  * Note:
1882  * This function should be used for probing for completion of datagrams that
1883  * were previously posted using the GNI_EpPostDataWId function.
1884  **/
1885 gni_return_t
1886         GNI_PostDataProbeById(
1887                 IN  gni_nic_handle_t    nic_hndl,
1888                 OUT uint64_t            *datagram_id
1889                 );
1890
1891 /**
1892  * GNI_PostdataProbeWaitById - Probe by ID for datagrams associated with a cdm/nic until
1893  *                             a datagram in completed, timed out, or cancelled state
1894  *                             is found or the timeout expires.
1895  *
1896  * Parameters:
1897  * IN
1898  * nic_hndl     Handle of a nic associated with the cdm for which datagrams
1899  *              status is being probed.
1900  * timeout      The number of milliseconds to block before returning
1901  *              to the caller, (-1) if no time-out is desired.
1902  *
1903  * OUT
1904  * datagram_id  Id of first datagram found to be in completed, timed out, or
1905  *              cancelled state.  Valid only if the return value is GNI_RC_SUCCESS.
1906  *
1907  * Returns:
1908  * GNI_RC_SUCCESS - A datagram previously posted with a datagram_id in the completed,
1909  *                  timed out or cancelled state was found.
1910  *                  The id of the datagram is returned in the datagram_id argument.
1911  * GNI_RC_INVALID_PARAM - An invalid NIC handle or an invalid datagram_id address was specified.
1912  * GNI_RC_TIMEOUT - No datagram in completed, timed out, or cancelled state was found before
1913  *                  the timeout expired.
1914  *
1915  * Description:
1916  * This function returns the postid of the first datagram posted with a datagram_id found in
1917  * completed, timed out, or canceled state for the cdm associated with the
1918  * input nic handle.  This function must be used in conjunction
1919  * with GNI_EpPostdataTestById or GNI_EpPostdataWaitById to obtain data exchanged
1920  * in the datagram transaction.
1921  *
1922  * Note:
1923  * This function should be used for probing for completion of datagrams that
1924  * were previously posted using the GNI_EpPostdataWId function.
1925  **/
1926 gni_return_t
1927         GNI_PostdataProbeWaitById(
1928                 IN  gni_nic_handle_t    nic_hndl,
1929                 IN  uint32_t            timeout,
1930                 OUT uint64_t            *datagram_id
1931                 );
1932
1933 /**
1934  * GNI_EpPostDataCancel - Cancels postdata transaction
1935  *
1936  * Parameters:
1937  * IN
1938  * ep_hndl      Handle of the local Endpoint.
1939  *
1940  * Returns:
1941  * GNI_RC_SUCCESS - Canceled successfully.
1942  * GNI_RC_INVALID_PARAM - An invalid EP handle was specified.
1943  * GNI_RC_NO_MATCH      - No active postdata transaction on the ep_hndl.
1944  *
1945  * Description:
1946  * This function is used to cancel a postdata transaction.
1947  **/
1948 gni_return_t
1949         GNI_EpPostDataCancel(
1950                 IN gni_ep_handle_t      ep_hndl
1951                 );
1952
1953 /**
1954  * GNI_EpPostDataCancelById - Cancels postdata datagram transaction with
1955  *                            a given Id
1956  *
1957  * Parameters:
1958  * IN
1959  * ep_hndl      Handle of the local Endpoint.
1960  * datagram_id  Id of datagram to cancel.
1961  *
1962  * Returns:
1963  * GNI_RC_SUCCESS - Canceled successfully.
1964  * GNI_RC_INVALID_PARAM - An invalid EP handle or datagram id was specified.
1965  * GNI_RC_NO_MATCH      - No active postdata transaction on the ep_hndl.
1966  *
1967  * Description:
1968  * This function is used to cancel a postdata transaction.
1969  **/
1970 gni_return_t
1971         GNI_EpPostDataCancelById(
1972                 IN gni_ep_handle_t      ep_hndl,
1973                 IN uint64_t             datagram_id
1974                 );
1975
1976 /**
1977  * GNI_MemRegister - Register memory with the NIC
1978  *
1979  * Parameters:
1980  * IN
1981  * nic_hndl     Handle of a currently open NIC.
1982  * address      Starting address of the memory region to be registered.
1983  * length       Length of the memory region to be registered, in bytes.
1984  * dst_cq_hndl  If not NULL, it will be used to notify the local process
1985  *              that a remote peer has delivered data from RDMA or FMA PUT
1986  *              into this memory region.
1987  * flags        Memory attributes associated with the region
1988  *              (see GNI_MEM_xxx in gni_puh.h)
1989  * vmdh_index   Specifies the index within the pre-allocated MDD block that
1990  *              must be used for the registration, e.g. when set to 0 will
1991  *              use the first entry of the MDD block. If set to (-1) relies
1992  *              on GNI library to allocate the next available entry from
1993  *              the MDD block.
1994  *
1995  * INOUT
1996  * mem_hndl     The new memory handle for the region.
1997  *
1998  * Returns:
1999  * GNI_RC_SUCCESS - The memory region was successfully registered.
2000  * GNI_RC_INVALID_PARAM - One on the parameters was invalid.
2001  * GNI_RC_ERROR_RESOURCE - The registration operation failed due to
2002  *                         insufficient resources.
2003  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
2004  * GNI_RC_PERMISSION_ERROR - The user's buffer R/W permissions conflict with
2005  *                           the flags argument.
2006  *
2007  * Description:
2008  * This function allows a process to register a region of memory with
2009  * the GNI NIC. The user may specify an arbitrary size region of memory,
2010  * with arbitrary alignment, but the actual area of memory registered will
2011  * be registered on MRT block granularity (or physical page granularity if
2012  * MRT is not enabled for this process).
2013  * A memory region must consist of a single segment.
2014  * Using a single segment to register a memory region allows an application
2015  * to use a virtual address in the future transactions in and out of the
2016  * registered region. A single segment memory registration should be a common
2017  * way in which an application registers its memory.
2018  * A new memory handle is generated for each region of memory that
2019  * is registered by a process.
2020  * A length parameter of zero will result in a GNI_RC_INVALID_PARAM error.
2021  * If GNI_MEM_USE_VMDH flag is set, this function will fail if
2022  * GNI_SetMddResources has not been called to specify the size of the
2023  * MDD block to be used. If GNI_MEM_USE_VMDH flag is set, this function
2024  * will fail with GNI_RC_ERROR_RESOURCE return code if the vMDH entry
2025  * specified by vmdh_index is already in use.
2026  * The contents of the memory region being registered are not altered.
2027  * The memory region must be previously allocated by an application.
2028  * If failure is returned, the contents of mem_hndl are untouched.
2029  **/
2030 gni_return_t
2031         GNI_MemRegister(
2032                 IN    gni_nic_handle_t  nic_hndl,
2033                 IN    uint64_t          address,
2034                 IN    uint64_t          length,
2035                 IN    gni_cq_handle_t   dst_cq_hndl,
2036                 IN    uint32_t          flags,
2037                 IN    uint32_t          vmdh_index,
2038                 INOUT gni_mem_handle_t  *mem_hndl
2039                 );
2040
2041 /**
2042  * GNI_MemRegisterSegments - Register memory segments with the NIC
2043  *
2044  * Parameters:
2045  * IN
2046  * nic_hndl     Handle of a currently open NIC.
2047  * mem_segments List of segments to be registered. Each element of the list consists
2048  *              of the starting address of the memory region and the length, in bytes.
2049  * segment_cnt  Number of segments in the mem_segments list.
2050  * dst_cq_hndl  If not NULL, specifies the CQ to receive events related to the
2051  *              transactions initiated by the remote node into this memory region.
2052  * flags        Memory attributes associated with the region
2053  *              (see GNI_MEM_xxx in gni_puh.h)
2054  * vmdh_index   Specifies the index within the pre-allocated MDD block that
2055  *              must be used for the registration, e.g. when set to 0 will
2056  *              use the first entry of the MDD block. If set to (-1) relies
2057  *              on GNI library to allocate the next available entry from
2058  *              the MDD block.
2059  *
2060  * INOUT
2061  * mem_hndl     The new memory handle for the region.
2062  *
2063  * Returns:
2064  * GNI_RC_SUCCESS - The memory region was successfully registered.
2065  * GNI_RC_INVALID_PARAM - One on the parameters was invalid.
2066  * GNI_RC_ERROR_RESOURCE - The registration operation failed due to
2067  *                         insufficient resources.
2068  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
2069  * GNI_RC_PERMISSION_ERROR - The user's buffer R/W permissions conflict with
2070  *                           the flags argument.
2071  *
2072  * Description:
2073  * This function allows a process to register a region of memory with
2074  * the Gemini NIC. The user may specify an arbitrary size region of memory,
2075  * with arbitrary alignment, but the actual area of memory registered will
2076  * be registered on MRT block granularity (or physical page granularity if
2077  * MRT is not enabled for this process).
2078  * To register a single segment GNI_MemRegister() function must be used.
2079  * Using multiple segments during the registration
2080  * imposes the requirement on an application to use an offset within
2081  * the registered memory region instead of a virtual address in all future
2082  * transactions where registered region is aligned to MRT block size (or page size
2083  * for non-MRT registrations).
2084  * A single segment memory registration should be a common way
2085  * an application registers its memory. A multiple segments registration
2086  * should be reserved for special cases.
2087  * A new memory handle is generated for each region of memory that
2088  * is registered by a process.
2089  * A length parameter of zero in any segment will result in a GNI_RC_INVALID_PARAM error.
2090  * If GNI_MEM_USE_VMDH flag is set, this function will fail if
2091  * GNI_SetMddResources has not been called to specify the size of the
2092  * MDD block to be used. If GNI_MEM_USE_VMDH flag is set, this function
2093  * will fail with GNI_RC_ERROR_RESOURCE return code if the vMDH entry
2094  * specified by vmdh_index is already in use.
2095  * The contents of the memory region being registered are not altered.
2096  * The memory region must be previously allocated by an application.
2097  * If failure is returned, the contents of mem_hndl are untouched.
2098  **/
2099 gni_return_t
2100         GNI_MemRegisterSegments(
2101                 IN    gni_nic_handle_t  nic_hndl,
2102                 IN    gni_mem_segment_t *mem_segments,
2103                 IN    uint32_t          segments_cnt,
2104                 IN    gni_cq_handle_t   dst_cq_hndl,
2105                 IN    uint32_t          flags,
2106                 IN    uint32_t          vmdh_index,
2107                 INOUT gni_mem_handle_t  *mem_hndl
2108                 );
2109
2110
2111 /**
2112  * GNI_SetMddResources - Set size of MDD block in NIC handle
2113  *
2114  * Parameters:
2115  * IN
2116  * nic_hndl     The handle for the NIC.
2117  * num_entries  Number of MDD entries in the block.
2118  *
2119  * Returns:
2120  * GNI_RC_SUCCESS - The block size was successfully specified
2121  * GNI_RC_INVALID_PARAM - One or more of the parameters was invalid
2122  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
2123  *
2124  * Description:
2125  * This function specifies the size of a contiguous block of MDD entries
2126  * that can be used for future memory registrations.
2127  **/
2128 gni_return_t
2129         GNI_SetMddResources(
2130                 IN gni_nic_handle_t     nic_hndl,
2131                 IN uint32_t             num_entries
2132                 );
2133
2134
2135 /**
2136  * GNI_MemDeregister - De-register memory
2137  *
2138  * Parameters:
2139  * IN
2140  * nic_hndl  The handle for the NIC that owns the memory region
2141  *           being de-registered.
2142  * mem_hndl  Memory handle for the region.
2143  *
2144  * Returns:
2145  * GNI_RC_SUCCESS - The memory region was successfully de-registered.
2146  * GNI_RC_INVALID_PARAM - One or more of the parameters was invalid.
2147  *
2148  * Description:
2149  * This function de-registers memory that was previously registered and unlocks
2150  * the associated pages from physical memory. The contents and attributes of the
2151  * region of memory being de-registered are not altered in any way.
2152  **/
2153 gni_return_t
2154         GNI_MemDeregister(
2155                 IN gni_nic_handle_t     nic_hndl,
2156                 IN gni_mem_handle_t     *mem_hndl
2157                 );
2158
2159 /**
2160  * GNI_MemHndlQueryAttr - Query for memory handle attributes
2161  *
2162  * Parameters:
2163  * IN
2164  * mem_hndl  Memory handle for a registered region.
2165  * attr      Attribute that is being queried
2166  *
2167  * OUT
2168  * yesno     A pointer to a boolean return val if the attr is set
2169  *
2170  * Returns:
2171  * GNI_RC_SUCCESS - The memory region was successfully queried.
2172  * GNI_RC_INVALID_PARAM - One or more of the parameters was invalid.
2173  *
2174  * Description:
2175  * This function returns a yes(1) or no(0) boolean value in the passed in
2176  * pointer. Only one attribute at a time may be tested, and uGNI will test the
2177  * memory handle for correctness. See gni_mem_handle_attr_t enum.
2178  **/
2179 gni_return_t
2180         GNI_MemHndlQueryAttr(
2181                 IN  gni_mem_handle_t            *mem_hndl,
2182                 IN  gni_mem_handle_attr_t       attr,
2183                 OUT int                         *yesno
2184                 );
2185
2186 /**
2187  * GNI_RebuildMemHndl - Given one mem_hndl, build a new one with a different VMDH
2188  *
2189  * Parameters:
2190  * IN
2191  * src_mem_hndl  Memory handle for a registered region.
2192  * vmdh_index    New VMDH Index to apply
2193  *
2194  * OUT
2195  * dst_mem_hndl  New memory handle for the region on a different node
2196  *
2197  * Returns:
2198  * GNI_RC_SUCCESS - The memory region was successfully queried.
2199  * GNI_RC_INVALID_PARAM - One or more of the parameters was invalid.
2200  * GNI_RC_INVALID_STATE - The mem_hndl wasn't updated at least once.
2201  *
2202  * Description:
2203  * This function returns a new memory handle that contains the same
2204  * address and length but with a new VMDH index. This way, the memory
2205  * handle exchange does not need to occur when an instance knows the
2206  * remote memory layout.
2207  **/
2208 gni_return_t
2209         GNI_RebuildMemHndl (
2210                 IN  gni_mem_handle_t    *src_mem_hndl,
2211                 IN  uint32_t            vmdh_index,
2212                 OUT gni_mem_handle_t    *dst_mem_hndl
2213                 );
2214
2215
2216 /**
2217  * GNI_MemQueryHndls - Get the next memory handle for either the nic handle or
2218  *                     file descriptor.  Only one of the nic_hndl or fd
2219  *                     parameters must be specified and valid.
2220  *
2221  * Parameters:
2222  * IN
2223  * nic_hndl      Handle of a currently open NIC.
2224  * fd            The file descriptor for a currently open NIC.
2225  *
2226  * IN/OUT
2227  * mem_hndl      If this parameter points to a valid memory handle,
2228  *               then return the next memory handle found.
2229  *
2230  * OUT
2231  * address       The address of the current memory location.
2232  * length        The length of the current memory location.
2233  *
2234  * Returns:
2235  * GNI_RC_SUCCESS - A memory handle was successfully found and returned.
2236  * GNI_RC_INVALID_PARAM - One or more of the parameters were invalid.
2237  * GNI_RC_NO_MATCH - A memory handle was not found for the supplied NIC or
2238  *                   a memory handle was not found after the supplied memory
2239  *                   handle.
2240  * GNI_RC_INVALID_STATE - The supplied memory handle was invalid or not found.
2241  *
2242  * Description:
2243  * This function returns the next available memory handle with its address
2244  * and length.  If an error occurs, the address and length will be zero.
2245  **/
2246 gni_return_t
2247         GNI_MemQueryHndls(
2248                 IN    gni_nic_handle_t  nic_hndl,
2249                 IN    int               fd,
2250                 INOUT gni_mem_handle_t *mem_hndl,
2251                 OUT   uint64_t         *address,
2252                 OUT   uint64_t         *length
2253                 );
2254
2255
2256 /**
2257  * GNI_CqCreate - Create Completion Queue
2258  *
2259  * Parameters:
2260  * IN
2261  * nic_hndl     The handle of the associated NIC.
2262  * entry_count  The minimum number of completion entries that this CQ will hold.
2263  * delay_count  The number of events the Gemini will allow to occur before
2264  *              generating an interrupt.
2265  *              Setting this to zero results in interrupt delivery with every event.
2266  *              For the user level this parameter is meaningful only when mode is
2267  *              set to GNI_CQ_BLOCKING
2268  * mode         The mode of operation of the new CQ: GNI_CQ_BLOCKING, GNI_CQ_NOBLOCK
2269  * handler      User supplied callback function to be run for each CQ entry received
2270  *              in the CQ.
2271  * context      User supplied pointer to be passed to the handler callback function.
2272  *
2273  * OUT
2274  * cq_hndl      The handle of the newly created Completion Queue.
2275  *
2276  * Returns:
2277  * GNI_RC_SUCCESS - A new Completion Queue was successfully created.
2278  * GNI_RC_INVALID_PARAM - One or more of the parameters was invalid.
2279  * GNI_RC_ERROR_RESOURCE - The Completion Queue could not be created due
2280  *                         to insufficient resources.
2281  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
2282  *
2283  * Description:
2284  * This function creates a new Completion Queue. The caller must specify
2285  * the minimum number of completion entries that the queue must contain.
2286  * To avoid dropped completion notifications, applications should make sure
2287  * that the number of operations posted on Endpoints attached to
2288  * a src_cq_hndl does not exceed the completion queue capacity at any time.
2289  *
2290  * Notes:
2291  * The handler, if specified, runs for each CQ entry that is received into
2292  * the CQ.  The handler is supplied with two arguments, a pointer to the
2293  * CQ entry, and a pointer to the context provided at CQ creation.
2294  * The handler is invoked at some time between when the CQ entry is deposited
2295  * into the CQ and the return of GNI_CqGetEvent or GNI_CqWaitEvent with
2296  * a status of either GNI_RC_SUCCESS or GNI_RC_TRANSACTION_ERROR.
2297  * Use of callback functions does not relieve the  user of the need to call
2298  * GNI_CqGetEvent or GNI_CqWaitEvent for each event deposited into the CQ.
2299  *
2300  * Completion Queues may be used for receipt of locally generated events
2301  * such as those arising from GNI_Post style transactions, etc. or
2302  * may be used for receipt of remote events, but not both.
2303  **/
2304 gni_return_t
2305         GNI_CqCreate(
2306                 IN  gni_nic_handle_t    nic_hndl,
2307                 IN  uint32_t            entry_count,
2308                 IN  uint32_t            delay_count,
2309                 IN  gni_cq_mode_t       mode,
2310                 IN  void                (*handler)(gni_cq_entry_t *,void *),
2311                 IN  void                *context,
2312                 OUT gni_cq_handle_t     *cq_hndl
2313                 );
2314
2315 /**
2316  * GNI_CqDestroy - Destroy Completion queue
2317  *
2318  * Parameters:
2319  * IN
2320  * cq_hndl    The handle for the Completion Queue to be destroyed.
2321  *
2322  * Returns:
2323  * GNI_RC_SUCCESS        - The CQ was successfully destroyed.
2324  * GNI_RC_INVALID_PARAM  - One or more of the parameters was invalid.
2325  * GNI_RC_ERROR_RESOURCE - The CQ could not be destroyed because one or
2326  *                         more Endpoint instances are still associated with it.
2327  *
2328  * Description:
2329  * This function destroys a specified Completion Queue.
2330  * If any Endpoints are associated with the CQ, the CQ is not destroyed and
2331  * an error is returned.
2332  **/
2333 gni_return_t
2334         GNI_CqDestroy(
2335                 IN gni_cq_handle_t      cq_hndl
2336                 );
2337
2338 /**
2339  * GNI_PostRdma - Post RDMA transaction
2340  *
2341  * Parameters:
2342  * IN
2343  * ep_hndl      Instance of a local Endpoint.
2344  * post_descr   Pointer to a descriptor to be posted.
2345  *
2346  * Returns:
2347  * GNI_RC_SUCCESS - The descriptor was successfully posted.
2348  * GNI_RC_INVALID_PARAM - The Endpoint handle was invalid.
2349  * GNI_RC_ALIGNMENT_ERROR - Posted source or destination data pointers or
2350  *                          data length are not properly aligned.
2351  * GNI_RC_ERROR_RESOURCE - The transaction request could not be posted due
2352  *                         to insufficient resources.
2353  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
2354  * GNI_RC_PERMISSION_ERROR - The user's buffer R/W permissions conflict with
2355  *                           the access type.
2356  *
2357  * Description:
2358  * This function adds a descriptor to the tail of the RDMA queue and
2359  * returns immediately.
2360  *
2361  **/
2362 gni_return_t
2363         GNI_PostRdma(
2364                 IN gni_ep_handle_t              ep_hndl,
2365                 IN gni_post_descriptor_t        *post_descr
2366                 );
2367
2368 /**
2369  * GNI_PostFma - Post FMA transaction
2370  *
2371  * Parameters:
2372  * IN
2373  * ep_hndl      Instance of a local Endpoint.
2374  * post_descr   Pointer to a descriptor to be posted.
2375  *
2376  * Returns:
2377  * GNI_RC_SUCCESS - The descriptor was successfully posted.
2378  * GNI_RC_INVALID_PARAM - The Endpoint handle was invalid.
2379  * GNI_RC_ALIGNMENT_ERROR - Posted source or destination data pointers or
2380  *                          data length are not properly aligned.
2381  * GNI_RC_ERROR_RESOURCE - The transaction request could not be posted due
2382  *                         to insufficient resources.
2383  *
2384  * Description:
2385  * This function executes a data transaction (Put, Get or AMO) by
2386  * storing into the directly mapped FMA Window to initiate a series of
2387  * FMA requests.
2388  * It returns before the transaction is confirmed by the remote NIC.
2389  * Zero-length FMA Put operations are supported. Zero-length FMA Get and
2390  * zero-length FMA AMO operations are not supported.
2391  *
2392  **/
2393
2394 gni_return_t
2395         GNI_PostFma(
2396                 IN gni_ep_handle_t              ep_hndl,
2397                 IN gni_post_descriptor_t        *post_descr
2398                 );
2399
2400 /**
2401  * GNI_PostCqWrite - Post a CQ Write transaction
2402  *
2403  * Parameters:
2404  * IN
2405  * ep_hndl      Instance of a local Endpoint.
2406  * post_descr   Pointer to a descriptor to be posted.
2407  *
2408  * Returns:
2409  * GNI_RC_SUCCESS - The descriptor was successfully posted.
2410  * GNI_RC_INVALID_PARAM - The Endpoint handle was invalid; .
2411  * GNI_RC_RESOUCE_ERROR - Insufficient resources were available to
2412  *                        initialize the endpoint.
2413  *
2414  * Description:
2415  * This function executes a cqwrite to a remote CQ.
2416  * It returns before the transaction is confirmed by the remote NIC.
2417  *
2418  **/
2419 gni_return_t
2420         GNI_PostCqWrite(
2421                 IN gni_ep_handle_t              ep_hndl,
2422                 IN gni_post_descriptor_t        *post_descr
2423                 );
2424
2425 /**
2426  * GNI_GetCompleted - Get next completed descriptor
2427  *
2428  * Parameters:
2429  * IN
2430  * cq_hndl      The handle for the Completion Queue.
2431  * event_data   The event returned by CqGetEvent function.
2432  *
2433  * OUT
2434  * post_desc    Address of the descriptor that has completed.
2435  *
2436  * Returns:
2437  * GNI_RC_SUCCESS - A completed descriptor was returned with a successful
2438  *                  completion status.
2439  * GNI_RC_DESCRIPTOR_ERROR - If the corresponding post queue (FMA, RDMA or AMO)
2440  *                           is empty, the descriptor pointer is set to NULL,
2441  *                           otherwise, a completed descriptor is returned with
2442  *                           an error completion status.
2443  * GNI_RC_INVALID_PARAM - The CQ handle was invalid.
2444  * GNI_RC_TRANSACTION_ERROR - A completed descriptor was returned with a
2445  *                            network error status.
2446  *
2447  * Description:
2448  * This function gets the descriptor from the corresponding post queue.
2449  * The descriptor is removed from the head of the queue and the address
2450  * of the descriptor is returned.
2451  *
2452  **/
2453 gni_return_t
2454         GNI_GetCompleted(
2455                 IN  gni_cq_handle_t             cq_hndl,
2456                 IN  gni_cq_entry_t              event_data,
2457                 OUT gni_post_descriptor_t       **post_descr
2458                 );
2459
2460 /**
2461  * GNI_CqGetEvent - Get next event
2462  *
2463  * Parameters:
2464  * IN
2465  * cq_hndl      The handle for the Completion Queue.
2466  *
2467  * OUT
2468  * event_data   A new event entry data, if the return status indicates success.
2469  *              Undefined otherwise.
2470  *
2471  * Returns:
2472  * GNI_RC_SUCCESS - A completion entry was found on the Completion Queue.
2473  * GNI_RC_NOT_DONE - No new completion entries are on the Completion Queue.
2474  * GNI_RC_INVALID_PARAM - The Completion Queue handle was invalid.
2475  * GNI_RC_ERROR_RESOURCE - CQ is in an overrun state and CQ events may
2476  *                         have been lost.
2477  * GNI_RC_TRANSACTION_ERROR - A network error was encountered in processing a transaction.
2478  *
2479  * Description:
2480  * This function polls the specified Completion Queue for a completion entry.
2481  * If a completion entry is found, it returns the event data stored in the entry.
2482  * CqGetEvent is a non-blocking call. It is up to the calling process to
2483  * subsequently invoke the appropriate function to de-queue the completed descriptor.
2484  * CqGetEvent only de-queues the completion entry from the Completion Queue.
2485  *
2486  **/
2487 gni_return_t
2488         GNI_CqGetEvent(
2489                 IN  gni_cq_handle_t     cq_hndl,
2490                 OUT gni_cq_entry_t      *event_data
2491                 );
2492
2493 /**
2494  * GNI_CqWaitEvent - Wait for the next event
2495  *
2496  * Parameters:
2497  * IN
2498  * cq_hndl      The handle for the Completion Queue.
2499  * timeout      The number of milliseconds to block before returning
2500  *              to the caller, (-1) if no time-out is desired.
2501  *
2502  * OUT
2503  * event_data   A new event entry data, if the return status indicates success.
2504  *              Undefined otherwise.
2505  *
2506  * Returns:
2507  * GNI_RC_SUCCESS - A completion entry was found on the Completion Queue.
2508  * GNI_RC_TIMEOUT - The request timed out and no completion entry was found.
2509  * GNI_RC_INVALID_PARAM - The Completion Queue handle was invalid.
2510  * GNI_RC_ERROR_RESOURCE - The Completion Queue was not created in
2511  *                         the GNI_CQ_BLOCKING mode.
2512  * GNI_RC_TRANSACTION_ERROR - A network error was encountered in processing a transaction.
2513  *
2514  * Description:
2515  * This function polls the specified Completion Queue for a completion entry.
2516  * If a completion entry was found, it immediately returns event data.
2517  * If no completion entry is found, the caller is blocked until a completion
2518  * entry is generated, or until the timeout value expires.
2519  * The Completion Queue must be created with the GNI_CQ_BLOCKING mode set
2520  * in order to be able to block on it.
2521  *
2522  **/
2523 gni_return_t
2524         GNI_CqWaitEvent(
2525                 IN  gni_cq_handle_t     cq_hndl,
2526                 IN  uint64_t            timeout,
2527                 OUT gni_cq_entry_t      *event_data
2528                 );
2529
2530 /**
2531  * GNI_CqVectorWaitEvent - Wait for the next event on multiple CQs
2532  *
2533  * Parameters:
2534  * IN
2535  * cq_hndl      Array of Completion Queue handles.
2536  * num_cqs      Number of Completion Queue handles.
2537  * timeout      The number of milliseconds to block before returning
2538  *              to the caller, (-1) if no time-out is desired.
2539  *
2540  * OUT
2541  * event_data   A new event entry data, if the return status indicates success.
2542  *              Undefined otherwise.
2543  * which        Array index for the CQ which returned an event (or error).
2544  *
2545  * Returns:
2546  * GNI_RC_SUCCESS - A completion entry was found on the Completion Queue.
2547  * GNI_RC_TIMEOUT - The request timed out and no completion entry was found.
2548  * GNI_RC_NOT_DONE - The Completion Queue handle had the interrupt mask set and
2549  *                   no event was processed.
2550  * GNI_RC_INVALID_PARAM - One of the Completion Queue handles was invalid.
2551  * GNI_RC_ERROR_RESOURCE - One of the Completion Queues was not created in
2552  *                         the GNI_CQ_BLOCKING mode.
2553  * GNI_RC_TRANSACTION_ERROR - A network error was encountered in processing a transaction.
2554  * GNI_RC_ERROR_NOMEM - No memory was available for the allocation of the cq
2555  *                      descriptor or event pointers.
2556  *
2557  * Description:
2558  * This function polls the specified Completion Queues for a completion entry.
2559  * If a completion entry was found, it immediately returns event data.
2560  * If no completion entry is found, the caller is blocked until a completion
2561  * entry is generated, or until the timeout value expires.
2562  * The Completion Queues must be created with the GNI_CQ_BLOCKING mode set
2563  * in order to be able to block on it.
2564  *
2565  **/
2566 gni_return_t
2567         GNI_CqVectorWaitEvent(
2568                 IN  gni_cq_handle_t     *cq_hndls,
2569                 IN  uint32_t            num_cqs,
2570                 IN  uint64_t            timeout,
2571                 OUT gni_cq_entry_t      *event_data,
2572                 OUT uint32_t            *which
2573                 );
2574
2575 /**
2576  * GNI_CqVectorMonitor - Monitor multiple CQs for the next event
2577  *
2578  * Parameters:
2579  * IN
2580  * cq_hndl      Array of Completion Queue handles.
2581  * num_cqs      Number of Completion Queue handles.
2582  * timeout      The number of milliseconds to block before returning
2583  *              to the caller, (-1) if no time-out is desired.
2584  *
2585  * OUT
2586  * which        Array index for the CQ which returned an event (or error).
2587  *
2588  * Returns:
2589  * GNI_RC_SUCCESS - A completion entry was found on the Completion Queue.
2590  * GNI_RC_TIMEOUT - The request timed out and no completion entry was found.
2591  * GNI_RC_NOT_DONE - The Completion Queue handle had the interrupt mask set and
2592  *                   no event was processed.
2593  * GNI_RC_INVALID_PARAM - One of the Completion Queue handles was invalid.
2594  * GNI_RC_ERROR_RESOURCE - One of the Completion Queues was not created in
2595  *                         the GNI_CQ_BLOCKING mode.
2596  * GNI_RC_ERROR_NOMEM - No memory was available for the allocation of the cq
2597  *                      descriptor or event pointers.
2598  *
2599  * Description:
2600  * This function polls the specified Completion Queues for a completion entry.
2601  * If a completion entry was found, it immediately returns the array index for the CQ.
2602  * If no completion entry is found, the caller is blocked until a completion
2603  * entry is generated, or until the timeout value expires.
2604  * The Completion Queues must be created with the GNI_CQ_BLOCKING mode set
2605  * in order to be able to block on it.
2606  *
2607  **/
2608 gni_return_t
2609         GNI_CqVectorMonitor(
2610                 IN  gni_cq_handle_t     *cq_hndls,
2611                 IN  uint32_t            num_cqs,
2612                 IN  uint64_t            timeout,
2613                 OUT uint32_t            *which
2614                 );
2615
2616 /**
2617  * GNI_CqInterruptMask - Increment the interrupt mask for the completion queue handle.
2618  *
2619  * Parameters:
2620  * IN
2621  * cq_hndl      The handle for the Completion Queue.
2622  *
2623  * Returns:
2624  * GNI_RC_SUCCESS - The interrupt mask was incremented successfully.
2625  * GNI_RC_ERROR_RESOURCE - The interrupt mask was not allocated for
2626  *                         the Completion Queue.
2627  * GNI_RC_NOT_DONE - The interrupt mask was not incremented.
2628  * GNI_RC_INVALID_PARAM - The Completion Queue handle was invalid or the
2629  *                        Completion Queue was not created in GNI_CQ_BLOCKING
2630  *                        mode.
2631  *
2632  * Description:
2633  * This function increments the interrupt mask for the specified Completion Queue.
2634  *
2635  **/
2636 gni_return_t
2637         GNI_CqInterruptMask(
2638                 IN gni_cq_handle_t cq_hndl
2639                 );
2640
2641 /**
2642  * GNI_CqInterruptUnmask - Decrement the interrupt mask for the completion queue handle.
2643  *
2644  * Parameters:
2645  * IN
2646  * cq_hndl      The handle for the Completion Queue.
2647  *
2648  * Returns:
2649  * GNI_RC_SUCCESS - The interrupt mask was decremented successfully.
2650  * GNI_RC_ERROR_RESOURCE - The interrupt mask was not allocated for
2651  *                         the Completion Queue.
2652  * GNI_RC_NOT_DONE - The interrupt mask was not decremented.
2653  * GNI_RC_INVALID_PARAM - The Completion Queue handle was invalid or the
2654  *                        Completion Queue was not created in GNI_CQ_BLOCKING
2655  *                        mode.
2656  *
2657  * Description:
2658  * This function decrements the interrupt mask for the specified Completion Queue.
2659  *
2660  **/
2661 gni_return_t
2662         GNI_CqInterruptUnmask(
2663                 IN gni_cq_handle_t cq_hndl
2664                 );
2665
2666 /**
2667  * GNI_CqTestEvent - Check if there is an event on a Completion Queue
2668  *
2669  * Parameters:
2670  * IN
2671  * cq_hndl      The handle for the Completion Queue.
2672  *
2673  *
2674  * Returns:
2675  * GNI_RC_SUCCESS - A completion entry was found on the Completion Queue.
2676  * GNI_RC_NOT_DONE - No new completion entries are on the Completion Queue.
2677  * GNI_RC_INVALID_PARAM - The Completion Queue handle was invalid.
2678  * GNI_RC_ERROR_RESOURCE - CQ is in an overrun state and CQ events may have been lost.
2679  *
2680  * Description:
2681  * This function polls the specified Completion Queue for a completion entry.
2682  * If a completion entry is found, it return GNI_RC_SUCCESS, unless the
2683  * CQ is overrun, in which case GNI_RC_ERROR_RESOURCE.  If no completion entry
2684  * is found GNI_RC_NOT_DONE is returned.
2685  *
2686  * No processing of new entries is performed by this function.
2687  *
2688  **/
2689 gni_return_t
2690         GNI_CqTestEvent(
2691                 IN gni_cq_handle_t      cq_hndl
2692                 );
2693
2694 /**
2695  * GNI_CqErrorStr - Decode error status into a string for a CQ Entry
2696  *
2697  * Parameters:
2698  * IN
2699  * entry           CQ entry with error status to be decoded
2700  * len             Length of the buffer in bytes
2701  *
2702  * OUT
2703  * buffer          Pointer to the buffer where the error code will be
2704  *                 returned.
2705  *
2706  * Returns:
2707  * GNI_RC_SUCCESS - The entry was successfully decoded.
2708  * GNI_RC_INVALID_PARAM - Invalid input parameter
2709  * GNI_RC_SIZE_ERROR - Supplied buffer is too small to contain the error
2710  *                     code
2711  *
2712  * Description:
2713  * This function decodes the error status encoded in a CQ Entry
2714  * by the hardware.
2715  *
2716  **/
2717 gni_return_t
2718         GNI_CqErrorStr(
2719                 IN  gni_cq_entry_t      entry,
2720                 OUT void                *buffer,
2721                 IN  uint32_t            len
2722                 );
2723
2724 /**
2725  * GNI_CqErrorRecoverable - Deduce error status as recoverable for a CQ Entry
2726  *
2727  * Parameters:
2728  * IN
2729  * entry           CQ entry with error status to be decoded
2730  *
2731  * OUT
2732  * recoverable     Pointer to the integer flag that will contain the result.
2733  *
2734  * Returns:
2735  * GNI_RC_SUCCESS - The entry was successfully decoded.
2736  * GNI_RC_INVALID_PARAM - Invalid input parameter
2737  * GNI_RC_INVALID_STATE - CQ entry translates to an undefined state
2738  *
2739  * Description:
2740  * This function translates any error status encoded in a CQ Entry by
2741  * the hardware into a recoverable/unrecoverable flag for application
2742  * usage.
2743  *
2744  **/
2745 gni_return_t
2746         GNI_CqErrorRecoverable(
2747                 IN  gni_cq_entry_t      entry,
2748                 OUT uint32_t            *recoverable
2749                 );
2750
2751 /**
2752  * GNI_SmsgBufferSizeNeeded - Return amount of memory required for short message
2753  *                            resources given parameters in an input short
2754  *                            message attributes structure
2755  * IN
2756  * smsg_attr            pointer to short message attributes structure
2757  *
2758  * OUT
2759  * size                 size in bytes required for the short message buffer
2760  *
2761  * Returns:
2762  * GNI_RC_SUCCESS - Operation completed successfully.
2763  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
2764  *
2765  * Description:
2766  * This utility function provides an application with a way to determine the
2767  * amount of memory needs to be allocated for short messaging resources.  The
2768  * msg_buffer, buff_size, mem_hndl, and mbox_offset fields in the input
2769  * smsg_attr structure do not need to be defined.
2770  **/
2771 gni_return_t
2772         GNI_SmsgBufferSizeNeeded(
2773                 IN  gni_smsg_attr_t     *smsg_attr,
2774                 OUT unsigned int        *size
2775                 );
2776
2777 /**
2778  * GNI_SmsgInit - Initialize short messaging resources
2779  * IN
2780  * ep_hndl              The handle of the Endpoint.
2781  * local_smsg_attr      Local parameters for short messaging
2782  * remote_smsg_attr     Remote parameters for short messaging provided by peer
2783  *
2784  * Returns:
2785  * GNI_RC_SUCCESS - Operation completed successfully.
2786  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
2787  * GNI_RC_INVALID_STATE - Endpoind is not bound
2788  * GNI_RC_ERROR_NOMEM - Insufficient memory to allocate short message
2789  *                      internal structures
2790  * Description:
2791  * This function configures the short messaging protocol on the given Endpoint.
2792  **/
2793 gni_return_t
2794         GNI_SmsgInit(
2795                 IN gni_ep_handle_t      ep_hndl,
2796                 IN gni_smsg_attr_t      *local_smsg_attr,
2797                 IN gni_smsg_attr_t      *remote_smsg_attr
2798                 );
2799
2800 /**
2801  * GNI_SmsgSetDeliveryMode - Configures SMSG delivery mode.
2802  *
2803  * IN
2804  * nic_handle           The NIC handle to alter.
2805  * dlvr_mode            The new SMSG delivery mode.
2806  *
2807  * Returns:
2808  * GNI_RC_SUCCESS - Operation completed successfully.
2809  * GNI_RC_INVALID_PARAM - Invalid NIC handle specified or
2810  *                        the delivery mode is invalid.
2811  *
2812  * Description:
2813  * This functions sets the SMSG delivery mode for SMSG transactions.
2814  **/
2815 gni_return_t
2816         GNI_SmsgSetDeliveryMode(
2817                 IN gni_nic_handle_t        nic_handle,
2818                 IN uint16_t                 dlvr_mode
2819                 );
2820
2821 /**
2822  * GNI_SmsgSend - Send short message
2823  *
2824  * Parameters:
2825  * IN
2826  * ep_hndl      Instance of an Endpoint.
2827  * header       Pointer to the header of a message.
2828  * header_length Length of the header in bytes.
2829  * data         Pointer to the payload of the message.
2830  * data_length  Length of the payload in byte.
2831  * msg_id       Identifier for application to track transaction.
2832  *              Only valid for short messaging using MBOX_PERSISTENT type,
2833  *              otherwise ignored.
2834  *
2835  * Returns:
2836  * GNI_RC_SUCCESS - The message was successfully sent.
2837  * GNI_RC_INVALID_PARAM - The Endpoint handle was invalid or
2838  *                        the Endpoint is not initialized for short messaging.
2839  * GNI_RC_NOT_DONE - No credits available to send the message
2840  * GNI_RC_ERROR_RESOURCE - The total size of the header plus data exceeds
2841  *                         the maximum short message size given in GNI_SmsgInit.
2842  *
2843  * Description:
2844  * This function sends a message to the remote peer, by copying it into the
2845  * pre-allocated remote buffer space using the FMA mechanism.  It returns
2846  * before the delivery is confirmed by the remote NIC.  With MBOX_PERSISTENT
2847  * type system attempts to re-transmit for certain transaction failures.  This
2848  * is a non-blocking call.  Completion events are delivered to local and remote
2849  * completion queues for each send.
2850  *
2851  * Note:
2852  * The SMSG interface uses the FMA mechanism with adaptive routing.  This
2853  * allows SMSG sends to arrive out of order at the target node.  Due to this,
2854  * it is possible for completion events to be delivered to the remote
2855  * completion queue while GNI_SmsgGetNext reports that no new messages are
2856  * available.  To handle this case when using remote events to detect the
2857  * arrival of SMSG sends, be sure to clear all messages from an endpoint using
2858  * GNI_SmsgGetNext after receiving each remote completion event.
2859  *
2860  **/
2861 gni_return_t
2862         GNI_SmsgSend(
2863                 IN gni_ep_handle_t      ep_hndl,
2864                 IN void                 *header,
2865                 IN uint32_t             header_length,
2866                 IN void                 *data,
2867                 IN uint32_t             data_length,
2868                 IN uint32_t             msg_id
2869                 );
2870
2871 /**
2872  * GNI_SmsgSendWTag - Send short message with a tag
2873  *
2874  * Parameters:
2875  * IN
2876  * ep_hndl      Instance of an Endpoint.
2877  * header       Pointer to the header of a message.
2878  * header_length Length of the header in bytes.
2879  * data         Pointer to the payload of the message.
2880  * data_length  Length of the payload in byte.
2881  * msg_id       Identifier for application to track transaction.
2882  *              Only valid for short messaging using MBOX_PERSISTENT type
2883  * tag          Tag associated with the short message.
2884  *
2885  * Returns:
2886  * GNI_RC_SUCCESS - The message was successfully sent.
2887  * GNI_RC_INVALID_PARAM - The Endpoint handle was invalid or
2888  *                        the Endpoint is not initialized for short messaging.
2889  * GNI_RC_NOT_DONE - No credits available to send the message
2890  * GNI_RC_ERROR_RESOURCE - The total size of the header plus data exceeds
2891  *                         the maximum short message size defined by GNI_SMSG_MAX_SIZE.
2892  *
2893  * Description:
2894  * This function sends a tagged message to the remote peer, by copying it into
2895  * the pre-allocated remote buffer space using the FMA mechanism.
2896  * It returns before the delivery is confirmed by the remote NIC.
2897  * With MBOX_PERSISTENT type system attempts to re-transmit
2898  * for certain transaction failures.
2899  * This is a non-blocking call.
2900  *
2901  **/
2902
2903 gni_return_t
2904         GNI_SmsgSendWTag(
2905                 IN gni_ep_handle_t      ep_hndl,
2906                 IN void                 *header,
2907                 IN uint32_t             header_length,
2908                 IN void                 *data,
2909                 IN uint32_t             data_length,
2910                 IN uint32_t             msg_id,
2911                 IN uint8_t              tag
2912                 );
2913
2914 /**
2915  * GNI_SmsgGetNext - Get next available short message
2916  *
2917  * Parameters:
2918  * IN
2919  * ep_hndl      Instance of an Endpoint.
2920  *
2921  * OUT
2922  * header       Pointer to the header of the newly arrived message.
2923  *
2924  * Returns:
2925  * GNI_RC_SUCCESS - The new message is successfully arrived.
2926  * GNI_RC_INVALID_PARAM - The Endpoint handle was invalid or the Endpoint
2927  *                        is not initialized for short messaging
2928  * GNI_RC_NOT_DONE - No new messages available.
2929  * GNI_RC_INVALID_STATE - The SMSG connection has entered an invalid state.
2930  *
2931  * Description:
2932  * This function returns a pointer to the header of the newly arrived message and
2933  * makes this message current. An application may decide to copy the message out
2934  * of the mailbox or process it immediately. This is a non-blocking call.
2935  *
2936  **/
2937 gni_return_t
2938         GNI_SmsgGetNext(
2939                 IN  gni_ep_handle_t     ep_hndl,
2940                 OUT void                **header
2941                 );
2942
2943 /**
2944  * GNI_SmsgGetNextWTag  -   Get next available short message if input tag
2945  *                          matches that of the short message.
2946  *
2947  * Parameters:
2948  * IN
2949  * ep_hndl       Instance of an Endpoint.
2950  *
2951  * OUT
2952  * header   Pointer to the header of the newly arrived message.
2953  *          event value.
2954  * tag      On input, pointer to value of remote event to be matched.
2955  *          A wildcard value of GNI_SMSG_ANY_TAG can be used to match any
2956  *          tag value of the incoming message.
2957  *          The value is set to that of the matching remote event
2958  *          on output.
2959  *
2960  * Returns:
2961  * GNI_RC_SUCCESS - The new message is successfully arrived.
2962  * GNI_RC_INVALID_PARAM - The Endpoint handle was invalid or the Endpoint is
2963  *            not in GNI_EP_STATE_CONNECTED state.
2964  * GNI_RC_NOT_DONE - No new messages available.
2965  * GNI_RC_NO_MATCH - Message available, but tag of message doesn't match
2966  *                   the value supplied in the tag argument.
2967  * GNI_RC_INVALID_STATE - The SMSG connection has entered an invalid state.
2968  *
2969  * Description:
2970  * This function returns a pointer to the header of the newly arrived message and
2971  * makes this message current if the input tag matches the tag of the newly
2972  * arrived message. An application may decide to copy the message header out
2973  * of the mailbox or process the header immediately. This is a non-blocking call.
2974  *
2975  **/
2976 gni_return_t
2977         GNI_SmsgGetNextWTag(
2978                 IN  gni_ep_handle_t     ep_hndl,
2979                 OUT void                **header,
2980                 OUT uint8_t             *tag
2981                 );
2982
2983
2984 /**
2985  * GNI_SmsgRelease - Release current message
2986  *
2987  * Parameters:
2988  * IN
2989  * ep_hndl      Instance of an Endpoint.
2990  *
2991  * Returns:
2992  * GNI_RC_SUCCESS - The current message is successfully released.
2993  * GNI_RC_INVALID_PARAM - The Endpoint handle was invalid or the Endpoint
2994  *                        is not initialized for short messaging
2995  * GNI_RC_NOT_DONE - There is no current message.
2996  *                   The GetNext function must return GNI_RC_SUCCESS before
2997  *                   calling this function.
2998  *
2999  * Description:
3000  * This function releases the current message buffer. It must be called only
3001  * after GetNext has returned GNI_RC_SUCCESS. This is a non-blocking call.
3002  * The message returned by the GetNext function must be copied out or processed
3003  * prior to making this call.
3004  *
3005  **/
3006 gni_return_t
3007         GNI_SmsgRelease(
3008                 IN gni_ep_handle_t      ep_hndl
3009                 );
3010
3011 /**
3012  * GNI_MsgqInit - Creates the resources required for the shared message queue.
3013  *
3014  * Parameters:
3015  * IN
3016  * nic_hndl     The handle of the attached NIC device to use in the message
3017  *              queue system.
3018  * rcv_cb       A callback function for handling received messages.
3019  * cb_data      User data to pass to the receive callback function.
3020  * snd_cq       A send CQ for use with the MSGQ.
3021  * attrs        The attributes for message queue system initialization.
3022  *
3023  * OUT
3024  * msgq_hndl    A handle for the created message queue resources.
3025  *
3026  * Returns:
3027  * GNI_RC_SUCCESS          Message Queue intialization succeeded.
3028  * GNI_RC_INVALID_PARAM    An invalid parameter was provided.
3029  * GNI_RC_ERROR_NOMEM      There was insufficient memory available to attach to
3030  *                         the shared memory region.
3031  * GNI_RC_INVALID_STATE    The attributes provided do not match the existing
3032  *                         message queue attributes or all instances were not
3033  *                         ready to attach the the shared memory area.
3034  * GNI_RC_PERMISSION_ERROR The hugetlbfs filesystem was not available.
3035  *
3036  * Description:
3037  *
3038  * GNI_MsgqInit uses the attributes provided to attach to a shared memory
3039  * region used for the message queue system.  The shared region is then
3040  * registered with a private receive completion queue and the provided message
3041  * queue attributes are stored as control information in the shared area.
3042  **/
3043 gni_return_t
3044         GNI_MsgqInit(
3045                 IN  gni_nic_handle_t            nic_hndl,
3046                 IN  gni_msgq_rcv_cb_func        *rcv_cb,
3047                 IN  void                        *cb_data,
3048                 IN  gni_cq_handle_t             snd_cq,
3049                 IN  gni_msgq_attr_t             *attrs,
3050                 OUT gni_msgq_handle_t           *msgq_hndl
3051                 );
3052
3053 /**
3054  * GNI_MsgqRelease - Frees all resources associated with a message queue handle.
3055  *
3056  * Parameters:
3057  * IN
3058  * msgq_hndl    The handle for the message queue to use for the operation.
3059  *
3060  * Returns:
3061  * GNI_RC_SUCCESS       All message queue resources were successfully freed.
3062  * GNI_RC_INVALID_PARAM An invalid parameter was provided.
3063  * GNI_RC_NOT_DONE      There are outstanding message queue transactions.
3064  *
3065  * Description:
3066  *
3067  * GNI_MsgqRelease frees all resources created during GNI_MsgqInit.  All
3068  * transactions must be completed (or all end-points destroyed) before calling
3069  * GNI_MsgqRelease.
3070  **/
3071 gni_return_t
3072         GNI_MsgqRelease(
3073                 IN gni_msgq_handle_t    msgq_hndl
3074                 );
3075
3076 /**
3077  * GNI_MsgqIdle - prepare the message queue for checkpoint
3078  *
3079  * Parameters:
3080  * IN
3081  * msgq_hndl    The handle for the message queue to use for the operation.
3082  *
3083  * Returns:
3084  * GNI_RC_SUCCESS       All message queue resources are idle.
3085  * GNI_RC_INVALID_PARAM An invalid parameter was provided.
3086  * GNI_RC_NOT_DONE      There are outstanding message queue transactions.
3087  *
3088  * Description:
3089  * If program has used GNI_MsgqInit, this function should be called prior to the
3090  * checkpoint until GNI_RC_SUCCESS is received. This will perform a subset of
3091  * what is done in GNI_MsgqRelease to inspect if the message queue is idle and
3092  * able to be safely checkpointed. This function will not destroy any resources.
3093  * Because the msgq is a shared resource, higher level libaries are expected to
3094  * prevent further sends by issuing a barrier prior to calling this function.
3095  **/
3096 gni_return_t
3097         GNI_MsgqIdle(
3098                 IN gni_msgq_handle_t    msgq_hndl
3099                 );
3100
3101 /**
3102  * GNI_MsgqGetConnAttrs - Assigns connection resources to a remote end-point
3103  *              address and returns attributes for completing the connection.
3104  *
3105  * Parameters:
3106  * IN
3107  * msgq_hndl    The handle for the message queue to use for the operation.
3108  * pe_addr      The PE address of the remote end-point to assign connection
3109  *              resources to (virtual if the NTT is enabled).
3110  *
3111  * OUT
3112  * attrs        The attributes needed to establish a message queue connection
3113  *              on the remote end-point.
3114  * attrs_size   (Optional) returns size of attrs that was written
3115  *
3116  * Returns:
3117  * GNI_RC_SUCCESS          Connection resources were assigned to the PE address.
3118  * GNI_RC_INVALID_PARAM    An invalid parameter was provided.
3119  * GNI_RC_INVALID_STATE    Connection resources have already been assigned to
3120  *                         the PE address provided.
3121  * GNI_RC_ERROR_RESOURCE   All connection resources have already been assigned.
3122  * GNI_RC_PERMISSION_ERROR Message queue Initialization has not completed
3123  *                         or teardown has been started.
3124  *
3125  * Description:
3126  *
3127  * The remote PE address provided is assigned to an SMSG control structure and
3128  * mailbox for use in an inter-node connection.  An attribute structure
3129  * describing the assigned resources is then returned.  The attributes must be
3130  * traded with the remote end-point to establish the connection.
3131  **/
3132 gni_return_t
3133         GNI_MsgqGetConnAttrs(
3134                 IN  gni_msgq_handle_t   msgq_hndl,
3135                 IN  uint32_t            pe_addr,
3136                 OUT gni_msgq_ep_attr_t  *attrs,
3137                 OUT uint32_t            *attrs_size
3138                 );
3139
3140 /**
3141  * GNI_MsgqConnect - Completes an inter-node message queue connection.
3142  *
3143  * Parameters:
3144  * IN
3145  * msgq_hndl    The handle for the message queue to use for the operation.
3146  * pe_addr      The PE address of the remote end-point to assign connection
3147  *              resources to (virtual if the NTT is enabled).
3148  * attrs        The connection attributes received from the remote node.
3149  *
3150  * Returns:
3151  * GNI_RC_SUCCESS          The connection was established.
3152  * GNI_RC_INVALID_PARAM    An invalid parameter was provided.
3153  * GNI_RC_NO_MATCH         The associated connection resources could not be
3154  *                         found.
3155  * GNI_RC_INVALID_STATE    A connection to the PE specfied by the attribute
3156  *                         structure has already been established.
3157  * GNI_RC_PERMISSION_ERROR Message queue Initialization has not completed
3158  *                         or teardown has been started.
3159  *
3160  * Description:
3161  *
3162  * The remote PE address provided is used to look up the shared connection
3163  * resources that were assigned during GNI_MsgqGetConnAttrs. The connection is
3164  * completed by adding the remote end-point attributes provided to the
3165  * connection resources.
3166  **/
3167 gni_return_t
3168         GNI_MsgqConnect(
3169                 IN gni_msgq_handle_t    msgq_hndl,
3170                 IN uint32_t             pe_addr,
3171                 IN gni_msgq_ep_attr_t   *attrs
3172                 );
3173
3174 /**
3175  * GNI_MsgqConnRelease - De-assign connection resources from a remote PE.
3176  *
3177  * Parameters:
3178  * IN
3179  * msgq_hndl    The handle for the message queue to use for the operation.
3180  * pe_addr      the remote PE address of the message queue connection to free.
3181  *
3182  * Returns:
3183  * GNI_RC_SUCCESS       Connection resources were freed from the PE address.
3184  * GNI_RC_INVALID_PARAM An invalid parameter was provided.
3185  * GNI_RC_NO_MATCH      No message queue connection for the PE address was
3186  *                      found.
3187  * GNI_RC_NOT_DONE      There are outstanding transactions on the connection.
3188  *
3189  * Description:
3190  *
3191  * GNI_MsgqConnRelease releases the connection resources assigned to a PE
3192  * address during GNI_MsgqGetConnAttrs.  All outstanding transactions on the
3193  * connection must be completed before calling GNI_MsgqConnRelease.  Connection
3194  * resources freed in this call may be re-assigned with a call to
3195  * GNI_MsgqGetConnAttrs.
3196  **/
3197 gni_return_t
3198         GNI_MsgqConnRelease(
3199                 IN gni_msgq_handle_t    msgq_hndl,
3200                 IN uint32_t             pe_addr
3201                 );
3202
3203 /**
3204  * GNI_MsgqSend - Sends a message using the message queue system.
3205  *
3206  * Parameters:
3207  * IN
3208  * msgq_hndl    The handle for the message queue to use for the operation.
3209  * ep_hndl      The end-point describing the target for the send.
3210  * hdr          The message header.
3211  * hdr_len      The message header length.
3212  * msg          The message data.
3213  * msg_len      The message data length.
3214  * msg_id       The message identifier (returned in a local completion event).
3215  * msg_tag      The message tag (sent with message data).
3216  *
3217  * Returns:
3218  * GNI_RC_SUCCESS       The send completed successfully.
3219  * GNI_RC_INVALID_PARAM An invalid parameter was provided.
3220  * GNI_RC_NO_MATCH      No message queue connection for the end-point was found.
3221  * GNI_RC_NOT_DONE      No credits are available to send the message.
3222  * GNI_RC_SIZE_ERROR    The message size exceeds the maximum message size.
3223  * GNI_RC_INVALID_STATE Connection resources exist but are inactive.
3224  *
3225  * Description:
3226  *
3227  * The end-point provided is used to look up a message queue connection and
3228  * target instance information to perform the send.  The completion queue in
3229  * the provided EP handle is also used for completion notification.
3230  **/
3231 gni_return_t
3232         GNI_MsgqSend(
3233                 IN gni_msgq_handle_t    msgq_hndl,
3234                 IN gni_ep_handle_t      ep_hndl,
3235                 IN void                 *hdr,
3236                 IN uint32_t             hdr_len,
3237                 IN void                 *msg,
3238                 IN uint32_t             msg_len,
3239                 IN uint32_t             msg_id,
3240                 IN uint8_t              msg_tag
3241                 );
3242
3243 /**
3244  * GNI_MsgqProgress - Processes received message queue messages.
3245  *
3246  * Parameters:
3247  * IN
3248  * msgq_hndl    The handle for the message queue to use for the operation.
3249  * timeout      The number of milliseconds to block waiting for each message.
3250  *
3251  * Returns:
3252  * GNI_RC_SUCCESS        All messages were processed.
3253  * GNI_RC_INVALID_PARAM  An invalid parameter was provided.
3254  * GNI_RC_NOT_DONE       Messages could still be available for processing.
3255  * GNI_RC_ERROR_RESOURCE The send CQ is full.
3256  * GNI_RC_INVALID_STATE  An unexpected CQ event was received.
3257  * GNI_RC_ERROR_NOMEM    Insufficient memory was available to complete the
3258  *                       operation.
3259  *
3260  * Description:
3261  *
3262  * The internal receive completion queue is polled for events.  When an event
3263  * is received the registered receive callback function is called with the
3264  * message data.  If the user provided callback function returns true,
3265  * GNI_MsgqProgress will attempt to process another message.  If the callback
3266  * returns false, GNI_MsgqProgress will return immediately.
3267  **/
3268 gni_return_t
3269         GNI_MsgqProgress(
3270                 IN gni_msgq_handle_t    msgq_hndl,
3271                 IN uint32_t             timeout
3272                 );
3273
3274 /**
3275  * GNI_MsgqSize - Returns the size of the MSGQ allocated shared buffer given a
3276  *                set of initialization parameters.
3277  *
3278  * Parameters:
3279  * IN
3280  * attrs        The attributes for message queue system initialization.
3281  *
3282  * OUT
3283  * size         The size, in bytes, required to create the Msgq with the given
3284  *              set of parameters.
3285  *
3286  * Returns:
3287  * GNI_RC_SUCCESS       The operation completed successfully.
3288  * GNI_RC_INVALID_PARAM An invalid parameter was provided.
3289  *
3290  * Description:
3291  *
3292  * Returns the size of the Msgq allocated shared buffer given a set of
3293  * initialization parameters.  The size is specified in bytes.  The size is
3294  * always a multiple of the configured hugetlbfs hugepage size.
3295  **/
3296 gni_return_t
3297         GNI_MsgqSize(
3298                 IN  gni_msgq_attr_t     *attrs,
3299                 OUT uint32_t            *size
3300                 );
3301
3302 /**
3303  * GNI_SmsgsSetMaxRetrans - Configures SMSG max retransmit count.
3304  *
3305  * IN
3306  * nic_handle           The NIC handle to alter.
3307  * max_retrans          The new SMSG max retransmit count.
3308  *
3309  * Returns:
3310  * GNI_RC_SUCCESS - Operation completed successfully.
3311  * GNI_RC_INVALID_PARAM - Invalid NIC handle specified.
3312  *
3313  * Description:
3314  * This functions sets the maximum retransmit counts for SMSG transactions.
3315  * EPs associated with the NIC handle provided will give up retransmitting SMSG
3316  * transactions and return GNI_RC_TRANSACTION_ERROR when the retransmit count
3317  * has been reached.
3318  **/
3319 gni_return_t
3320         GNI_SmsgSetMaxRetrans(
3321                 IN gni_nic_handle_t     nic_handle,
3322                 IN uint16_t             max_retrans
3323                 );
3324
3325 /**
3326  * GNI_SubscribeErrors - Subscribe to error events on associated NIC.
3327  *
3328  * Parameters:
3329  * IN
3330  * nic_handle           The handle of the associated NIC.
3331  * device_id            The device identifier, for privileged mode (when NULL is passed in for nic_handle).
3332  * mask                 The error mask with corresponding bits set for notification.
3333  * EEQ_size             Size of the EEQ. The queue size will be a default of 64 entries if 0 is passed in.
3334  *
3335  * OUT
3336  * err_handle           The handle of the subscribed error events.
3337  *
3338  * Returns:
3339  * GNI_RC_SUCCESS          - Operation completed successfully.
3340  * GNI_RC_INVALID_PARAM    - One of the input parameters was invalid.
3341  *                           Or, a non-privileged user is trying to subscribe without a communication domain.
3342  * GNI_RC_NO_MATCH         - Specified device_id does not exists.
3343  * GNI_RC_ERROR_RESOURCE   - The event queue could not be created due to insufficient resources.
3344  * GNI_RC_ERROR_NOMEM      - Insufficient memory to complete the operation.
3345  *
3346  * Description:
3347  * This function creates an error event queue. When this function
3348  * returns, events start reporting immediately. For privileged users,
3349  * IE: super-users, they can pass in NULL for nic_handle. This
3350  * signifies to use the passed in device_id instead. This allows
3351  * privileged users subscribe to errors without a CDM being attached.
3352  * By default, if no nic_handle is passed in, then errors will be
3353  * captured for all ptags.
3354  *
3355  * Also, the mask value can be a bitwise OR of the error categories as
3356  * defined by the GNI_ERRMASK_* flags found in gni_pub.h.
3357  *
3358  **/
3359 gni_return_t
3360         GNI_SubscribeErrors(
3361                 IN  gni_nic_handle_t    nic_handle,
3362                 IN  uint32_t            device_id,
3363                 IN  gni_error_mask_t    mask,
3364                 IN  uint32_t            EEQ_size,
3365                 OUT gni_err_handle_t    *err_handle
3366                 );
3367
3368 /**
3369  * GNI_ReleaseErrors - Release error event notification.
3370  *
3371  * Parameters:
3372  * IN
3373  * err_handle           The handle of the subscribed error events.
3374  *
3375  * Returns:
3376  * GNI_RC_SUCCESS       - Operation completed successfully.
3377  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
3378  * GNI_RC_NOT_DONE      - A thread is still waiting on the event queue.
3379  *
3380  * Description:
3381  * This function releases the error event notification and cleans up
3382  * the memory resources for the event queue.
3383  *
3384  **/
3385 gni_return_t
3386         GNI_ReleaseErrors(
3387                 IN gni_err_handle_t     err_handle
3388                 );
3389
3390 /**
3391  * GNI_GetErrorMask - Get the currently set error mask.
3392  *
3393  * Parameters:
3394  * IN
3395  * err_handle           The handle of the subscribed error events.
3396  *
3397  * OUT
3398  * mask                 The pointer to copy the mask value to.
3399  *
3400  * Returns:
3401  * GNI_RC_SUCCESS       - Operation completed successfully.
3402  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
3403  *
3404  * Description:
3405  * The error mask is used to match error events, and decide if the
3406  * subscriber wants an event delivered. This is a convenience
3407  * function.
3408  *
3409  **/
3410 gni_return_t
3411         GNI_GetErrorMask(
3412                 IN  gni_err_handle_t    err_handle,
3413                 OUT gni_error_mask_t    *mask
3414                 );
3415
3416 /**
3417  * GNI_SetErrorMask - Set a new error mask for matching events.
3418  *
3419  * Parameters:
3420  * IN
3421  * err_handle           The handle of the subscribed error events.
3422  * mask_in              The error mask with corresponding bits set for notification.
3423  * mask_out             The pointer to copy the pre-set mask value to.
3424  *
3425  * Returns:
3426  * GNI_RC_SUCCESS       - Operation completed successfully.
3427  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
3428  *
3429  * Description:
3430  * Set a new error mask used to match for error event delivery.
3431  *
3432  **/
3433 gni_return_t
3434         GNI_SetErrorMask(
3435                 IN gni_err_handle_t     err_handle,
3436                 IN gni_error_mask_t     mask_in,
3437                 IN gni_error_mask_t     *mask_out
3438                 );
3439
3440 /**
3441  * GNI_GetErrorEvent - Get an error event, if available.
3442  *
3443  * Parameters:
3444  * IN
3445  * err_handle           The handle of the subscribed error events.
3446  * event                The pointer to the buffer to copy the event into.
3447  *
3448  * Returns:
3449  * GNI_RC_SUCCESS          - Operation completed successfully.
3450  * GNI_RC_INVALID_PARAM    - One of the input parameters was invalid.
3451  * GNI_RC_NOT_DONE         - No event was found in the event queue.
3452  *
3453  * Description:
3454  * This function is non-blocking and when it is called it will return
3455  * any new events in the event pointer.
3456  *
3457  **/
3458 gni_return_t
3459         GNI_GetErrorEvent(
3460                 IN gni_err_handle_t     err_handle,
3461                 IN gni_error_event_t    *event
3462                 );
3463
3464 /**
3465  * GNI_WaitErrorEvents - Wait until an error event occurs.
3466  *
3467  * Parameters:
3468  * IN
3469  * err_handle           The handle of the subscribed error events.
3470  * events               The pointer to the buffer to copy the events into.
3471  * events_size          The number of events in the events pointer.
3472  * timeout              After first event is triggered, time to wait for subsequent events.
3473  *
3474  * OUT
3475  * num_events           The number of events copied into the events buffer.
3476  *
3477  * Returns:
3478  * GNI_RC_SUCCESS          - Operation completed successfully.
3479  * GNI_RC_INVALID_PARAM    - One of the input parameters was invalid.
3480  * GNI_RC_NOT_DONE         - No event was found in the event queue.
3481  * GNI_RC_TIMEOUT          - Timeout was triggered before any more events came.
3482  * GNI_RC_PERMISSION_ERROR - The events pointer can't be written into.
3483  *
3484  * Description:
3485  * This function will block waiting forever waiting for one event to
3486  * occur. When that one event is triggered, it will delay returning to
3487  * try and coalesce error events. The timeout value is specified in
3488  * number of milliseconds. The number of events copied are stored in
3489  * the num_events structure.
3490  *
3491  **/
3492 gni_return_t
3493         GNI_WaitErrorEvents(
3494                 IN  gni_err_handle_t    err_handle,
3495                 IN  gni_error_event_t   *events,
3496                 IN  uint32_t            events_size,
3497                 IN  uint32_t            timeout,
3498                 OUT uint32_t            *num_events
3499                 );
3500
3501 /**
3502  * GNI_SetErrorPtag - Set protection tag for an error handler.
3503  *
3504  * Parameters:
3505  * IN
3506  * err_handle           The handle of the subscribed error events.
3507  * ptag                 The protect tag to set for matching error events.
3508  *
3509  * Returns:
3510  * GNI_RC_SUCCESS          - Operation completed successfully.
3511  * GNI_RC_INVALID_PARAM    - One of the input parameters was invalid.
3512  * GNI_RC_PERMISSION_ERROR - Only super-user can set ptag to something other than the communication domain.
3513  *
3514  * Description:
3515  * This is a privileged operation only. This function allows error
3516  * event capturing on other ptags. It also can be set to 0 to specify
3517  * capturing all events.
3518  *
3519  **/
3520 gni_return_t
3521         GNI_SetErrorPtag(
3522                 IN gni_err_handle_t     err_handle,
3523                 IN uint8_t              ptag
3524                 );
3525
3526 /**
3527  * GNI_GetNumLocalDevices - Get the number of local NICs on this node.
3528  *
3529  * Parameters:
3530  * OUT
3531  * num_devices  Pointer to the number of devices.
3532  *
3533  * Returns:
3534  * GNI_RC_SUCCESS - Number of devices was returned successfully.
3535  * GNI_RC_INVALID_PARAM - One or more of the parameters was invalid.
3536  * GNI_RC_ERROR_RESOURCE - There are no GNI NICs on this node.
3537  *
3538  * Description:
3539  * Returns the number of local device (NIC) IDs.
3540  **/
3541 gni_return_t
3542         GNI_GetNumLocalDevices(
3543                 OUT int *num_devices
3544                 );
3545
3546 /**
3547  * GNI_GetLocalDeviceIds - Get the IDs for each local NIC on this node.
3548  *
3549  * Parameters:
3550  * IN
3551  * len          The number of entries in the device_ids array.
3552  *
3553  * OUT
3554  * device_ids   Pointer to an array of device IDs.
3555  *
3556  * Returns:
3557  * GNI_RC_SUCCESS - Device IDs were returned successfully.
3558  * GNI_RC_INVALID_PARAM - One or more of the parameters was invalid.
3559  * GNI_RC_ERROR_RESOURCE - There are no GNI NICs on this node.
3560  *
3561  * Description:
3562  * Returns an array of local device (NIC) IDs.
3563  **/
3564 gni_return_t
3565         GNI_GetLocalDeviceIds(
3566                 IN  int len,
3567                 OUT int *device_ids
3568                 );
3569
3570 /**
3571  * GNI_GetVersion - Get the GNI version number.
3572  *
3573  * Parameters:
3574  * OUT
3575  * version      Pointer to the GNI version number.
3576  *
3577  * Returns:
3578  * GNI_RC_SUCCESS - Operation completed successfully.
3579  * GNI_RC_INVALID_PARAM - Invalid parameter.
3580  *
3581  * Description:
3582  *
3583  * Returns the GNI version number of the uGNI library.
3584  **/
3585 gni_return_t
3586         GNI_GetVersion(
3587                 OUT uint32_t    *version
3588                 );
3589
3590 /**
3591  * GNI_GetVersionInformation - Get the version information of the uGNI
3592  *                             and kGNI libraries.
3593  *
3594  * Parameters:
3595  * OUT
3596  * version_info  Pointer to the structure containing the GNI version
3597  *               information.
3598  *
3599  * Returns:
3600  * GNI_RC_SUCCESS - Operation completed successfully.
3601  * GNI_RC_INVALID_PARAM - Invalid parameter.
3602  *
3603  * Description:
3604  *
3605  * Returns the version information of the uGNI and kGNI libraries.
3606  **/
3607 gni_return_t
3608         GNI_GetVersionInformation(
3609                 OUT gni_version_info_t  *version_info
3610                 );
3611
3612 /**
3613  * GNI_GetDeviceType - Get the NIC type of the GNI device on the running system.
3614  *
3615  * Parameters:
3616  * OUT
3617  * dev_type     The GNI NIC device type of the device on the running system.
3618  *
3619  * Returns:
3620  * GNI_RC_SUCCESS - Operation completed successfully.
3621  * GNI_RC_ERROR_RESOURCE - A GNI device does not exist on the running system.
3622  *
3623  * Description:
3624  *
3625  * Returns the GNI NIC device type of the GNI device on a running system.
3626  **/
3627 gni_return_t
3628         GNI_GetDeviceType(
3629                 OUT gni_nic_device_t    *dev_type
3630                 );
3631
3632 /**
3633  * GNI_GetDevResInfo - Get device resource information.
3634  *
3635  * Parameters:
3636  * IN
3637  * device_id    The ID of the device to query.
3638  * res_type     The resource to query.
3639  *
3640  * OUT
3641  * res_desc     A pointer to information about the queried device resource.
3642  *
3643  * Returns:
3644  * GNI_RC_SUCCESS - Operation completed successfully.
3645  * GNI_RC_INVALID_PARAM - An invalid parameter was provided.
3646  * GNI_RC_ERROR_RESOURCE - The resource queried is not supported by the device
3647  *                         with ID 'device_id'.
3648  *
3649  * Description:
3650  *
3651  * Returns information about the device resource 'res_type' for the GNI device
3652  * with ID 'device_id'.
3653  **/
3654 gni_return_t
3655         GNI_GetDevResInfo(
3656                 IN  uint32_t            device_id,
3657                 IN  gni_dev_res_t       res_type,
3658                 OUT gni_dev_res_desc_t  *res_desc
3659                 );
3660
3661 /**
3662  * GNI_GetJobResInfo - Get job resource information.
3663  *
3664  * Parameters:
3665  * IN
3666  * device_id    The ID of the device to query.
3667  * res_type     The resource to query.
3668  * ptag         The protection tag of the job to query.
3669  *
3670  * OUT
3671  * res_desc     A pointer to information about the queried job resource.
3672  *
3673  * Returns:
3674  * GNI_RC_SUCCESS - Operation completed successfully.
3675  * GNI_RC_INVALID_PARAM - An invalid parameter was provided.
3676  * GNI_RC_ERROR_RESOURCE - The resource queried is not supported by the device
3677  *                         with ID 'device_id'
3678  *
3679  * Description:
3680  *
3681  * Returns information about the job resource 'res_type' for the job with
3682  * protection tag 'ptag' on the GNI device with ID 'device_id'.
3683  **/
3684 gni_return_t
3685         GNI_GetJobResInfo(
3686                 IN  uint32_t            device_id,
3687                 IN  uint8_t             ptag,
3688                 IN  gni_job_res_t       res_type,
3689                 OUT gni_job_res_desc_t  *res_desc
3690                 );
3691
3692 /**
3693  * GNI_GetNttGran - Get the configured NTT granularity.
3694  *
3695  * Parameters:
3696  * IN
3697  * device_id    The ID of the GNI device to query.
3698  *
3699  * OUT
3700  * ntt_gran     The NTT granularity configured for the GNI device.
3701  *
3702  * Returns:
3703  * GNI_RC_SUCCESS - Operation completed successfully.
3704  * GNI_RC_INVALID_PARAM - Invalid parameter.
3705  *
3706  * Description:
3707  *
3708  * Returns the configured NTT granularity for the GNI device with ID
3709  * 'device_id'.
3710  **/
3711 gni_return_t
3712         GNI_GetNttGran(
3713                 IN  uint32_t    device_id,
3714                 OUT uint32_t    *ntt_gran
3715                 );
3716
3717 /**
3718  * GNI_GetPtag - Get the ptag associated with a cookie.
3719  *
3720  * Parameters:
3721  * IN
3722  * device_id    The ID of the GNI device to query.
3723  * cookie       The cookie associated with ptag.
3724  *
3725  * OUT
3726  * ptag         The ptag associated with the cookie.
3727  *
3728  * Returns:
3729  * GNI_RC_SUCCESS - Operation completed successfully.
3730  * GNI_RC_INVALID_PARAM - Invalid parameter.
3731  * GNI_RC_NO_MATCH - Could not find associated ptag or device_id is
3732  *                   invalid.
3733  * GNI_RC_ERROR_RESOURCE - a resource allocation error was encountered while
3734  *                         trying to configure the job resources.
3735  *
3736  * Description:
3737  *
3738  * Returns the ptag associated with cookie for the GNI device with ID
3739  * 'device_id'.
3740  **/
3741 gni_return_t
3742         GNI_GetPtag(
3743                 IN  uint32_t    device_id,
3744                 IN  uint32_t    cookie,
3745                 OUT uint8_t     *ptag
3746                 );
3747
3748 /**
3749  * GNI_CeCreate - Allocate a VCE channel.
3750  *
3751  * Parameters:
3752  * IN
3753  * nic_hndl     The NIC handle to associate with the VCE channel.
3754  *
3755  * OUT
3756  * ce_hndl      A handle for the new VCE channel.
3757  *
3758  * Returns:
3759  * GNI_RC_SUCCESS - Operation completed successfully.
3760  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
3761  * GNI_RC_ERROR_RESOURCE - A resource allocation error was encountered.
3762  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
3763  * GNI_RC_ILLEGAL_OP - The operation is not supported on this NIC type.
3764  *
3765  * Description:
3766  *
3767  * The GNI_CeCreate() interface attempts to allocate a hardware VCE channel
3768  * resource.  On success, a handle to the allocated resource is returned to the
3769  * user.
3770  **/
3771 gni_return_t
3772         GNI_CeCreate(
3773                 IN  gni_nic_handle_t    nic_hndl,
3774                 OUT gni_ce_handle_t     *ce_hndl
3775                 );
3776
3777 /**
3778  * GNI_CeGetId - Retrieve the ID of a VCE channel.
3779  *
3780  * Parameters:
3781  * IN
3782  * ce_hndl      The VCE channel to use.
3783  *
3784  * OUT
3785  * ce_id        The ID of the VCE channel.
3786  *
3787  * Returns:
3788  * GNI_RC_SUCCESS - Operation completed successfully.
3789  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
3790  * GNI_RC_ILLEGAL_OP - The operation is not supported on this NIC type.
3791  *
3792  * Description:
3793  *
3794  * The GNI_CeGetId() interface returns the hardware VCE channel identifier from
3795  * the provided CE handle.  This ID is used to associate an endpoint with the
3796  * VCE channel.  Endpoints are then used to configure the VCE channel.
3797  **/
3798 gni_return_t
3799         GNI_CeGetId(
3800                 IN  gni_ce_handle_t     ce_hndl,
3801                 OUT uint32_t            *ce_id
3802                 );
3803
3804 /**
3805  * GNI_EpSetCeAttr - Store CE tree attributes into an endpoint.
3806  *
3807  * Parameters:
3808  * IN
3809  * ep_hndl      The EP handle to use.
3810  * ce_id        The CE ID to store in the endpoint.
3811  * child_id     The child ID to store in the endpoint
3812  * child_type   The child type to store in the endpoint
3813  *
3814  * Returns:
3815  * GNI_RC_SUCCESS - Operation completed successfully.
3816  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
3817  * GNI_RC_ILLEGAL_OP - The operation is not supported on this NIC type.
3818  *
3819  * Description:
3820  *
3821  * The GNI_EpSetCeAttr() interface sets the CE specific attributes of an
3822  * endpoint.  A VCE channel is configured using a set of endpoints with CE
3823  * attributes set.  Each endpoint used for VCE channel configuration represents
3824  * a node directly connected to the channel.  Additionally, endpoints used to
3825  * initiate CE operations (leaf nodes in the collective tree) must have CE
3826  * attributes set.
3827  *
3828  * Notes:
3829  *
3830  * Endpoints used for CE channel configuration represent either a child PE,
3831  * child VCE or parent VCE.  Each of these endpoint types is configured using a
3832  * different set of EP CE attributes.
3833  *
3834  * An endpoint representing a child PE is configured with:
3835  * ce_id - unused.
3836  * child_id - set to the uniquely assigned index in [0,GNI_CE_MAX_CHILDREN)
3837  *            that the local VCE channel refers to this child with.
3838  * child_type - set to GNI_CE_CHILD_PE.
3839  *
3840  * An endpoint representing a child VCE is configured with:
3841  * ce_id - set to the CE ID of the child VCE channel.
3842  * child_id - set to the uniquely assigned index in [0,GNI_CE_MAX_CHILDREN)
3843  *            that the local VCE channel refers to this child with.
3844  * child_type - set to  GNI_CE_CHILD_VCE.
3845  *
3846  * An endpoint representing a parent VCE is configured with:
3847  * ce_id - set to the CE ID of the parent VCE channel.
3848  * child_id - set to the uniquely assigned index in [0,GNI_CE_MAX_CHILDREN)
3849  *            that the remote VCE channel refers to this child with.
3850  * child_type - set to  GNI_CE_CHILD_VCE.
3851  *
3852  * Endpoints used to initiate CE operations using GNI_PostFma() must also be
3853  * configured with CE attributes.  These leaf endpoints are configured with:
3854  *
3855  * ce_id - set to the CE ID of the parente VCE channel.
3856  * child_id - set to the uniquely assigned index in [0,GNI_CE_MAX_CHILDREN)
3857  *            that the remote VCE channel refers to this child with.
3858  * child_type - set to GNI_CE_CHILD_PE.
3859  *
3860  * Also note that endpoints used for CE operations (either configuration of a
3861  * VCE channel or as a leaf endpoint) must be bound using remote address and
3862  * instance ID information.
3863  **/
3864 gni_return_t
3865         GNI_EpSetCeAttr(
3866                 IN gni_ep_handle_t      ep_hndl,
3867                 IN uint32_t             ce_id,
3868                 IN uint32_t             child_id,
3869                 IN gni_ce_child_t       child_type
3870                 );
3871
3872 /**
3873  * GNI_CeConfigure - Configure a VCE channel.
3874  *
3875  * Parameters:
3876  * IN
3877  * ce_hndl      The VCE channel to configure.
3878  * child_eps    An array of endpoints representing VCE child connections.
3879  * num_child_eps The number of child connections.
3880  * parent_ep    An endpoint representing the VCE parent connection.
3881  * cq_hndl      The CQ to associate with VCE channel.
3882  * modes        VCE channel configuration modes.
3883  *
3884  * Returns:
3885  * GNI_RC_SUCCESS - Operation completed successfully.
3886  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
3887  * GNI_RC_ILLEGAL_OP - The operation is not supported on this NIC type.
3888  *
3889  * Description:
3890  *
3891  * The GNI_CeConfigure() interface configures a VCE channel given a set of
3892  * endpoints representing collective tree conections to the channel.
3893  **/
3894 gni_return_t
3895         GNI_CeConfigure(
3896                 IN gni_ce_handle_t      ce_hndl,
3897                 IN gni_ep_handle_t      *child_eps,
3898                 IN uint32_t             num_child_eps,
3899                 IN gni_ep_handle_t      parent_ep,
3900                 IN gni_cq_handle_t      cq_hndl,
3901                 IN uint32_t             modes
3902                 );
3903
3904 /**
3905  * GNI_CeCheckResult - Check the result of a CE operation.
3906  *
3907  * Parameters:
3908  * IN
3909  * result       A pointer to the CE result structure used for the operation.
3910  * length       The size of the result (unused in Aries).
3911  *
3912  * Returns:
3913  * GNI_RC_SUCCESS - Operation completed successfully.
3914  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
3915  * GNI_RC_NOT_DONE - Operation has not completed.
3916  * GNI_RC_TRANSACTION_ERROR - Operation completed with an error.
3917  * GNI_RC_ILLEGAL_OP - The operation is not supported on this NIC type.
3918  *
3919  * Description:
3920  *
3921  * The GNI_CeCheckResult() interface reads control information in the provided
3922  * CE result structure to determine the status of a pending CE operation.
3923  *
3924  * Notes:
3925  *
3926  * If GNI_RC_TRANSACTION_ERROR is returned, the result structure must be
3927  * further analyzed to determine if the result was delivered.  A user should
3928  * first check the status of the result structure using the
3929  * GNI_CE_RES_STATUS_OK() macro.  If this macro evaluates to false, the result
3930  * could not be delivered due to a network error.  Otherwise, the result is
3931  * available, but the an exception was generated by the operation.  A user
3932  * should use the GNI_CE_RES_GET_FPE() macro to determine what exception(s)
3933  * occurred.
3934  **/
3935 gni_return_t
3936         GNI_CeCheckResult(
3937                 IN gni_ce_result_t      *result,
3938                 IN uint32_t             length
3939                 );
3940
3941 /**
3942  * GNI_CeDestroy - Free a VCE channel.
3943  *
3944  * Parameters:
3945  * IN
3946  * ce_hndl      The VCE channel to free.
3947  *
3948  * Returns:
3949  * GNI_RC_SUCCESS - Operation completed successfully.
3950  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
3951  * GNI_RC_ILLEGAL_OP - The operation is not supported on this NIC type.
3952  *
3953  * Description:
3954  *
3955  * The GNI_CeDestroy() interface frees the VCE channel resources associated
3956  * with the provided CE handle.
3957  **/
3958 gni_return_t
3959         GNI_CeDestroy(
3960                 IN gni_ce_handle_t      ce_hndl
3961                 );
3962
3963 /* Balanced Injection modes */
3964 #define GNI_BI_FLAG_APPLY_NOW                   0x1
3965 #define GNI_BI_FLAG_APPLY_AFTER_THROTTLE        0x2
3966 #define GNI_BI_FLAG_USE_DEFAULT_SETTINGS        0x4
3967 #define GNI_BI_FLAG_VALUE_IS_NUM_ORB_ENTRIES    0x8
3968
3969 /* Balanced Injection limits */
3970 #define GNI_BI_INJECT_BW_MIN                    0
3971 #define GNI_BI_INJECT_BW_MAX                    100
3972 #define GNI_BI_INJECT_BW_ORB_MIN                0
3973 #define GNI_BI_INJECT_BW_ORB_MAX                992
3974
3975 typedef struct gni_bi_desc {
3976         uint16_t current_bw;
3977         uint16_t current_aot_bw;
3978         uint16_t current_norbs;
3979         uint16_t flags;
3980         uint16_t sys_def_bw;
3981         uint16_t sys_def_aot_bw;
3982         uint16_t cle_seqnum;
3983         uint16_t hss_seqnum;
3984 } gni_bi_desc_t;
3985
3986 /**
3987  * GNI_SetBIConfig - Sets the balanced injection configuration.
3988  *
3989  * Parameters:
3990  * IN
3991  * device_id    The ID of the GNI device to query.
3992  * bw           The new injection bandwidth value.
3993  * aot_bw       The new 'apply-on-throttle' injection bandwidth value.
3994  * modes        modes
3995  *
3996  * Returns:
3997  * GNI_RC_SUCCESS - Operation completed successfully.
3998  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
3999  * GNI_RC_PERMISSION_ERROR - The operation was attempted by an unpriviledged user.
4000  *
4001  * Description:
4002  *
4003  * The GNI_SetBIConfig() interface configures a node's balanced injection
4004  * settings.
4005  **/
4006 gni_return_t
4007         GNI_SetBIConfig(
4008                 IN uint32_t     device_id,
4009                 IN uint16_t     bw,
4010                 IN uint16_t     aot_bw,
4011                 IN uint16_t     modes
4012                 );
4013
4014 /**
4015  * GNI_GetBIConfig - Gets the balanced injection configuration.
4016  *
4017  * Parameters:
4018  * IN
4019  * device_id    The ID of the GNI device to query.
4020  *
4021  * OUT
4022  * desc         The current balanced injection configuration.
4023  *
4024  * Returns:
4025  * GNI_RC_SUCCESS - Operation completed successfully.
4026  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
4027  *
4028  * Description:
4029  *
4030  * The GNI_GetBIConfig() interface returns information about a node's balanced
4031  * injection configuration.
4032  **/
4033 gni_return_t
4034         GNI_GetBIConfig(
4035                 IN uint32_t             device_id,
4036                 OUT gni_bi_desc_t       *desc
4037                 );
4038
4039 /**
4040  * GNI_BISyncWait - Blocks until the most recent BI configuration update is
4041  *                  committed.
4042  *
4043  * Parameters:
4044  * IN
4045  * device_id    The ID of the GNI device to query.
4046  *
4047  * OUT
4048  * timeout      The maximum amount of time in milliseconds to wait.
4049  *
4050  * Returns:
4051  * GNI_RC_SUCCESS - Operation completed successfully.
4052  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
4053  * GNI_RC_TIMEOUT - The timeout expired.
4054  *
4055  * Description:
4056  *
4057  * The GNI_BISyncWait() interface blocks until the most recent BI configuration
4058  * update is committed or the timeout expires.
4059  **/
4060 gni_return_t
4061         GNI_BISyncWait(
4062                 IN uint32_t     device_id,
4063                 OUT uint32_t    timeout);
4064
4065 /**
4066  * GNI_GetNicStat - Get a NIC statistic
4067  *
4068  * Parameters:
4069  * IN
4070  * nic_hndl     Handle of the associated NIC.
4071  * stat         NIC statistic to get
4072  *
4073  * OUT
4074  * value         Value of the statistic counter
4075  *
4076  * Returns:
4077  * GNI_RC_SUCCESS - Operation completed successfully.
4078  * GNI_RC_INVALID_PARAM - One of the arguments is invalid.
4079  *
4080  * Description:
4081  * Read the value of the NIC statistic counter.
4082  **/
4083 gni_return_t
4084         GNI_GetNicStat(
4085                 IN gni_nic_handle_t nic_hndl,
4086                 IN gni_statistic_t stat,
4087                 OUT uint32_t *value);
4088
4089 /**
4090  * GNI_ResetNicStat - Reset a NIC statistic to zero
4091  *
4092  * Parameters:
4093  * IN
4094  * nic_hndl     Handle of the associated NIC.
4095  * stat         NIC statistic to clear
4096  *
4097  * Returns:
4098  * GNI_RC_SUCCESS - Operation completed successfully.
4099  * GNI_RC_INVALID_PARAM - One of the arguments is invalid.
4100  *
4101  * Description:
4102  * Reset a NIC statistic counter to zero.
4103  **/
4104 gni_return_t
4105         GNI_ResetNicStat(
4106                 IN gni_nic_handle_t nic_hndl,
4107                 IN gni_statistic_t stat);
4108
4109 #endif /*not __KERNEL__*/
4110
4111 #ifdef __KERNEL__
4112 /* Kernel level definitions */
4113
4114 /**
4115  * gni_cdm_create - Create Communication Domain
4116  *
4117  * Parameters:
4118  * IN
4119  * inst_id      Unique address of the instance within the upper layer
4120  *              protocol domain.
4121  * ptag         Protection Tag.
4122  * cookie       Unique identifier generated by ALPS. Along with ptag
4123  *              helps to identify the Communication Domain.
4124  * modes        bit mask (see GNI_CDM_MODE_xxxxxx definitions)
4125  *
4126  * OUT
4127  * cdm_hndl     Handle returned. The handle is used with the other functions
4128  *              to specify a particular instance of the Communication Domain.
4129  *
4130  * Returns:
4131  * GNI_RC_SUCCESS - Operation completed successfully.
4132  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
4133  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
4134  *
4135  * Description:
4136  * This function creates an instance of the Communication Domain.
4137  *
4138  **/
4139 gni_return_t
4140         gni_cdm_create(
4141                 IN  uint32_t            inst_id,
4142                 IN  uint8_t             ptag,
4143                 IN  uint32_t            cookie,
4144                 IN  uint32_t            modes,
4145                 OUT gni_cdm_handle_t    *cdm_hndl
4146                 );
4147
4148 /**
4149  * gni_cdm_destroy - Destroy Communication Domain
4150  *
4151  * Parameters:
4152  * IN
4153  * cdm_hndl     The Communication Domain Handle.
4154  *
4155  * Returns:
4156  * GNI_RC_SUCCESS - Operation completed successfully.
4157  * GNI_RC_INVALID_PARAM - Caller specified an invalid CDM handle.
4158  *
4159  * Description:
4160  * Destroys the instance of the Communication Domain.
4161  * Removes associations between the calling process and the NIC devices
4162  * that were established via the corresponding Attach function.
4163  **/
4164 gni_return_t
4165         gni_cdm_destroy(
4166                 IN gni_cdm_handle_t     cdm_hndl
4167                 );
4168
4169 /**
4170  * gni_cdm_attach - Attach Communication Domain to a NIC device
4171  *
4172  * Parameters:
4173  * IN
4174  * cdm_hndl     The Communication Domain Handle.
4175  * device_id    The device identifier , e.g. /dev/kgni1 has
4176  *              device_id = DEVICE_MINOR_NUMBER - GEMINI_BASE_MINOR_NUMBER = 1
4177  *              Setting device_id to (-1) will result in attaching to
4178  *              the nearest Gemini NIC.
4179  *
4180  * OUT
4181  * local_addr   PE address of the Gemini NIC attached
4182  * nic_hndl     Handle returned. The handle is used with the other functions to specify
4183  *              a particular instance of a Gemini NIC.
4184  * Returns:
4185  * GNI_RC_SUCCESS - Operation completed successfully.
4186  * GNI_RC_NOT_DONE - Operation can't succeed right now, try again.
4187  * GNI_RC_INVALID_PARAM - Caller specified an invalid CDM handle.
4188  * GNI_RC_NO_MATCH - Specified device_id does not exists
4189  * GNI_RC_ERROR_RESOURCE - The operation failed due to insufficient resources.
4190  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
4191  *
4192  * Description:
4193  * Associates the Communication Domain with a Gemini NIC and provides a NIC handle
4194  * to the upper layer protocol. A process is not allowed to attach the same CDM
4195  * instance to the same Gemini NIC more than once, but it is allowed to attach
4196  * multiple CDMs to the same Gemini NIC.
4197  **/
4198 gni_return_t
4199         gni_cdm_attach(
4200                 IN  gni_cdm_handle_t    cdm_hndl,
4201                 IN  uint32_t            device_id,
4202                 OUT uint32_t            *local_addr,
4203                 OUT gni_nic_handle_t    *nic_hndl
4204                 );
4205
4206 /**
4207  * gni_ep_create - Create logical Endpoint
4208  *
4209  * Parameters:
4210  * IN
4211  * nic_hndl     Handle of the associated Gemini NIC.
4212  * src_cq_hndl  Handle of the CQ that will be used by default to deliver events
4213  *              related to the transactions initiated by the local node.
4214  *
4215  * OUT
4216  * ep_hndl      The handle of the newly created Endpoint instance.
4217  *
4218  * Returns:
4219  * GNI_RC_SUCCESS - Operation completed successfully.
4220  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
4221  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
4222  *
4223  * Description:
4224  * This function creates an instance of a Logical Endpoint.
4225  * A new instance is always created in a non-bound state.
4226  * A non-bound Endpoint is able to exchange posted data with
4227  * any bound remote Endpoint within the same Communication Domain.
4228  * An Endpoint cannot be used to post RDMA, FMA transactions or
4229  * send short messages while it is in non-bound state.
4230  **/
4231 gni_return_t
4232         gni_ep_create(
4233                 IN  gni_nic_handle_t    nic_hndl,
4234                 IN  gni_cq_handle_t     src_cq_hndl,
4235                 OUT gni_ep_handle_t     *ep_hndl
4236                 );
4237 /**
4238  * gni_ep_set_eventdata - Set event data  for local and remote events
4239  *
4240  * Parameters:
4241  * IN
4242  * ep_hndl      The handle of the Endpoint instance.
4243  * local_event  Value to use when generating LOCAL CQ events
4244  * remote_event Value to use when generating GLOBAL & REMOTE CQ events
4245  *
4246  * Returns:
4247  * GNI_RC_SUCCESS - Operation completed successfully.
4248  * GNI_RC_INVALID_PARAM - Invalid EP handle.
4249  *
4250  * Description:
4251  * By default GNI uses local instance_id as an event data for GLOBAL and REMOTE CQ events,
4252  * and EP remote_id when generating LOCAL CQ events.
4253  * This function allows to re-assign these events to the user defined values.
4254  **/
4255 gni_return_t
4256         gni_ep_set_eventdata(
4257                 IN gni_ep_handle_t      ep_hndl,
4258                 IN uint32_t             local_event,
4259                 IN uint32_t             remote_event
4260                 );
4261 /**
4262  * gni_ep_bind - Bind logical Endpoint to a peer
4263  *
4264  * Parameters:
4265  * IN
4266  * ep_hndl      The handle of the Endpoint instance to be bound.
4267  * remote_addr  Physical address of the Gemini NIC at the remote peer or NTT index,
4268  *              when NTT is enabled for the given Communication Domain.
4269  * remote_id    User specified ID of the remote instance in the job or unique identifier of
4270  *              the remote instance within the upper layer protocol domain.
4271  *
4272  * Returns:
4273  * GNI_RC_SUCCESS - Operation completed successfully.
4274  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
4275  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
4276  *
4277  * Description:
4278  * This function binds a Logical Endpoint to the specific remote address
4279  * and remote instance in the Communication Domain.
4280  * Once bound the Endpoint can be used to post RDMA and FMA transactions.
4281  **/
4282 gni_return_t
4283         gni_ep_bind(
4284                 IN gni_ep_handle_t      ep_hndl,
4285                 IN uint32_t             remote_addr,
4286                 IN uint32_t             remote_id
4287                 );
4288 /**
4289  * gni_ep_unbind - Unbind logical Endpoint
4290  *
4291  * Parameters:
4292  * IN
4293  * ep_hndl      The handle of the Endpoint instance to be bound.
4294  *
4295  * Returns:
4296  * GNI_RC_SUCCESS - Operation completed successfully.
4297  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
4298  * GNI_RC_NOT_DONE - Operation is not permited
4299  *
4300  * Description:
4301  * This function unbinds a Logical Endpoint from the specific remote address
4302  * and remote instance and releases any internal short message resource.
4303  * A non-bound Endpoint is able to exchange posted data with
4304  * any bound remote Endpoint within the same Communication Domain.
4305  * An Endpoint cannot be used to post RDMA, FMA transactions or
4306  * send short messages while it is in non-bound state.
4307  **/
4308 gni_return_t
4309         gni_ep_unbind(
4310                 IN gni_ep_handle_t      ep_hndl
4311                 );
4312
4313 /**
4314  * gni_ep_destroy - Destroy logical Endpoint
4315  *
4316  * Parameters:
4317  * IN
4318  * ep_hndl      The handle of the Endpoint instance to be destroyed.
4319  *
4320  * Returns:
4321  * GNI_RC_SUCCESS - Operation completed successfully.
4322  * GNI_RC_INVALID_PARAM - An invalid EP handle was specified.
4323  *
4324  * Description:
4325  * This function tears down an Endpoint.
4326  **/
4327 gni_return_t
4328         gni_ep_destroy(
4329                 IN gni_ep_handle_t      ep_hndl
4330                 );
4331
4332 /**
4333  * gni_ep_postdata - Exchange datagram with a remote Endpoint
4334  *
4335  * Parameters:
4336  * IN
4337  * ep_hndl      Handle of the local Endpoint.
4338  * in_data      pointer to the data to be sent
4339  * data_len     size of the data to be sent
4340  * out_buf      buffer to receive incoming datagram
4341  * buf_size     size of the buffer for incoming datagram
4342  *
4343  * Returns:
4344  * GNI_RC_SUCCESS - Connection request was queued.
4345  * GNI_RC_INVALID_PARAM - An invalid EP handle was specified.
4346  * GNI_RC_ERROR_RESOURCE - Only one outstanding datagram transaction per Endpoint
4347  *                         is allowed.
4348  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
4349  * GNI_RC_SIZE_ERROR - Size of datagram is too big.
4350  *
4351  * Description:
4352  * This function posts a datagram to be exchanged with a remote Endpoint in the CDM.
4353  * If the EP is unbound a datagram can be exchanged with any bound Endpoint in the CDM.
4354  **/
4355 gni_return_t
4356         gni_ep_postdata(
4357                 IN gni_ep_handle_t      ep_hndl,
4358                 IN void                 *in_data,
4359                 IN uint16_t             data_len,
4360                 IN void                 *out_buf,
4361                 IN uint16_t             buf_size
4362                 );
4363
4364 /**
4365  * gni_ep_postdata_w_id - Exchange datagram with a remote Endpoint, assigning an
4366  *                        id to the datagram.
4367  *
4368  * Parameters:
4369  * IN
4370  * ep_hndl      Handle of the local Endpoint.
4371  * in_data      pointer to the data to be sent
4372  * data_len     size of the data to be sent
4373  * out_buf      buffer to receive incoming datagram
4374  * buf_size     size of the buffer for incoming datagram
4375  * datagram_id  id associated with the datagram
4376  *
4377  * Returns:
4378  * GNI_RC_SUCCESS - Posted datagram was queued.
4379  * GNI_RC_INVALID_PARAM - An invalid EP handle was specified or an invalid
4380  *                        value (-1) for the datagram_id was specified.
4381  * GNI_RC_ERROR_RESOURCE - Only one outstanding datagram transaction per
4382  *                         Endpoint is allowed.
4383  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
4384  * GNI_RC_SIZE_ERROR - Size of datagram is too big.
4385  *
4386  * Description:
4387  * This function posts a datagram to be exchanged with a remote Endpoint in the CDM
4388  * and associated an Id with the datagram.
4389  * If the EP is unbound a datagram can be exchanged with any bound Endpoint in the CDM.
4390  *
4391  * Notes:
4392  * It may be useful to associate an Id with a datagram when intermixing usage of
4393  * bound and unbound EP's with datagrams.  Unbound endpoints must post datagrams with
4394  * a datagram id.
4395  **/
4396 gni_return_t
4397         gni_ep_postdata_w_id(
4398                 IN gni_ep_handle_t      ep_hndl,
4399                 IN void                 *in_data,
4400                 IN uint16_t             data_len,
4401                 IN void                 *out_buf,
4402                 IN uint16_t             buf_size,
4403                 IN uint64_t             datagram_id
4404                 );
4405
4406 /**
4407  * gni_ep_postdata_test - Tests for completion of a gni_ep_postdata operation.
4408  *
4409  * Parameters:
4410  * IN
4411  * ep_hndl      Handle of the local Endpoint.
4412  *
4413  * OUT
4414  * post_state   State of the transaction is returned.
4415  * remote_addr  Physical address of the Gemini NIC at the remote peer.
4416  *              Valid only if post_state returned GNI_POST_COMPLETED.
4417  * remote_id    User specific ID of the remote instance in the job (user)
4418  *              Unique address of the remote instance within the upper layer
4419  *              protocol domain (kernel). Valid only if post_state returned
4420  *              GNI_POST_COMPLETED.
4421  *
4422  * Returns:
4423  * GNI_RC_SUCCESS - Connection status is returned through the second function parameter.
4424  * GNI_RC_INVALID_PARAM - An invalid EP handle was specified.
4425  * GNI_RC_NO_MATCH - No matching datagram was found.
4426  * GNI_RC_SIZE_ERROR - Output buffer is too small for the size of the received
4427  *                     datagram.
4428  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
4429  *
4430  * Description:
4431  * This function returns the state of the PostData transaction.
4432  **/
4433 gni_return_t
4434         gni_ep_postdata_test(
4435                 IN  gni_ep_handle_t     ep_hndl,
4436                 OUT gni_post_state_t    *post_state,
4437                 OUT uint32_t            *remote_addr,
4438                 OUT uint32_t            *remote_id
4439                 );
4440
4441 /**
4442  * gni_ep_postdata_test_by_id - Tests for completion of a gni_ep_postdata_w_id operation
4443  *                              with a specified post id.
4444  *
4445  * Parameters:
4446  * IN
4447  * ep_hndl      Handle of the local Endpoint.
4448  * datagram_id  Id of the datagram associated with the endpoint.
4449  *
4450  * OUT
4451  * post_state   State of the transaction is returned.
4452  * remote_addr  Physical address of the Gemini NIC at the remote peer.
4453  *              Valid only if post_state returned GNI_POST_COMPLETED.
4454  * remote_id    User specific ID of the remote instance in the job (user)
4455  *              Unique address of the remote instance within the upper layer
4456  *              protocol domain (kernel). Valid only if post_state returned
4457  *              GNI_POST_COMPLETED.
4458  *
4459  * Returns:
4460  * GNI_RC_SUCCESS - Connection status is returned through the second function parameter.
4461  * GNI_RC_INVALID_PARAM - An invalid EP handle was specified.
4462  * GNI_RC_NO_MATCH - No matching datagram was found.
4463  * GNI_RC_SIZE_ERROR - Output buffer is too small for the size of the received
4464  *                     datagram.
4465  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
4466  *
4467  * Description:
4468  * This function returns the state of the PostData transaction with an assigned
4469  * datagram id.
4470  *
4471  * Note:
4472  * Unbound endpoints must test for datagrams with the same datagram id used
4473  * when calling gni_ep_postdata_w_id.
4474  **/
4475 gni_return_t
4476         gni_ep_postdata_test_by_id(
4477                 IN  gni_ep_handle_t     ep_hndl,
4478                 IN  uint64_t            datagram_id,
4479                 OUT gni_post_state_t    *post_state,
4480                 OUT uint32_t            *remote_addr,
4481                 OUT uint32_t            *remote_id
4482                 );
4483
4484 /**
4485  * gni_ep_postdata_wait - Wait for the Endpoint to connect
4486  *
4487  * Parameters:
4488  * IN
4489  * ep_hndl      Handle of the local Endpoint.
4490  * timeout      The count that this function waits, in milliseconds, for
4491  *              connection to complete.
4492  *              Set to (-1) if no timeout is desired. A timeout value of zero results
4493  *              in a GNI_RC_INVALID_PARAM error returned.
4494  * post_state   State of the transaction is returned.
4495  * remote_addr  Physical address of the Gemini NIC at the remote peer.
4496  *              Valid only if post_state returned GNI_POST_COMPLETED.
4497  * remote_id    User specific ID of the remote instance in the job (user)
4498  *              Unique address of the remote instance within the upper layer
4499  *              protocol domain (kernel). Valid only if post_state returned
4500  *              GNI_POST_COMPLETED.
4501  *
4502  * Returns:
4503  * GNI_RC_SUCCESS - The connection completed successfully.
4504  * GNI_RC_INVALID_PARAM - An invalid EP handle was specified or timeout was set to zero.
4505  * GNI_RC_TIMEOUT - The timeout expired before a successful connection completion.
4506  * GNI_RC_SIZE_ERROR - Output buffer is too small for the size of the received
4507  *                     datagram.
4508  * GNI_RC_NO_MATCH - No matching datagram was found.
4509  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
4510  *
4511  * Description:
4512  * This function is used to determine the result of a previously posted EpPostData
4513  * call on the specified Endpoint, blocking the calling thread until the completion
4514  * of the posted transaction or until the specified timeout expires.
4515  **/
4516 gni_return_t
4517         gni_ep_postdata_wait(
4518                 IN  gni_ep_handle_t     ep_hndl,
4519                 IN  uint32_t            timeout,
4520                 OUT gni_post_state_t    *post_state,
4521                 OUT uint32_t            *remote_addr,
4522                 OUT uint32_t            *remote_id
4523                 );
4524
4525 /**
4526  * gni_postdata_probe - Probe for datagrams associated with a cdm/nic which
4527  *                      are in completed, timed out, or cancelled state.
4528  *
4529  * Parameters:
4530  * IN
4531  * nic_hndl     Handle of a nic associated with the cdm for which datagrams
4532  *              status is being probed.
4533  *
4534  * OUT
4535  * remote_addr  Physical address of the Gemini NIC at the remote peer.
4536  *              Valid only if return value is GNI_RC_SUCCESS.
4537  *              (This address is virtual if GNI_CDM_MODE_NTT_ENABLE).
4538  * remote_id    User specific ID of the remote instance in the job (user)
4539  *              Unique address of the remote instance within the upper layer
4540  *              protocol domain (kernel). Valid only if return value is
4541  *              GNI_RC_SUCCESS.
4542  *
4543  * Returns:
4544  * GNI_RC_SUCCESS - A datagram in the completed, timed out or cancelled state was found.
4545  *                  The remote_addr and remote_id of the datagram are
4546  *                  in the remote_addr and remote_id arguments.
4547  * GNI_RC_INVALID_PARAM - An invalid NIC handle or invalid address for remote_addr or
4548  *                        remote_id was specified.
4549  * GNI_RC_NO_MATCH - No datagram in completed, timed out, or cancelled state was found.
4550  *
4551  * Description:
4552  * This function returns the remote_addr and remote_id of the first datagram found in
4553  * completed, timed out, or canceled state for the cdm associated with the
4554  * input nic handle.  This function must be used in conjunction
4555  * with GNI_EpPostDataTest or GNI_EpPostDataWait to obtain data exchanged
4556  * in the datagram transaction.
4557  **/
4558 gni_return_t
4559         gni_postdata_probe(
4560                 IN  gni_nic_handle_t    nic_hndl,
4561                 OUT uint32_t            *remote_addr,
4562                 OUT uint32_t            *remote_id
4563                 );
4564
4565 /**
4566  * gni_postdata_probe_by_id - Probe by ID for datagrams associated with a cdm/nic which
4567  *                               are in completed, timed out, or cancelled state.
4568  *
4569  * Parameters:
4570  * IN
4571  * nic_hndl     Handle of a nic associated with the cdm for which datagrams
4572  *              status is being probed.
4573  *
4574  * OUT
4575  * datagram_id  Id of first datagram found to be in completed, timed out, or
4576  *              cancelled state.  Valid only if the return value is GNI_RC_SUCCESS.
4577  *
4578  * Returns:
4579  * GNI_RC_SUCCESS - A datagram previously posted with a datagram_id in the completed,
4580  *                  timed out or cancelled state was found.
4581  *                  The id of the datagram is returned in the datagram_id argument.
4582  * GNI_RC_INVALID_PARAM - An invalid NIC handle or an invalid datagram_id address was specified.
4583  * GNI_RC_NO_MATCH - No datagram in completed, timed out, or cancelled state was found.
4584  *
4585  * Description:
4586  * This function returns the postid of the first datagram posted with a datagram_id found in
4587  * completed, timed out, or canceled state for the cdm associated with the
4588  * input nic handle.  This function must be used in conjunction
4589  * with GNI_EpPostDataTestById or GNI_EpPostDataWaitById to obtain data exchanged
4590  * in the datagram transaction.
4591  *
4592  * Note:
4593  * This function should be used for probing for completion of datagrams that
4594  * were previously posted using the GNI_EpPostDataWId function.
4595  **/
4596 gni_return_t
4597         gni_postdata_probe_by_id(
4598                 IN  gni_nic_handle_t    nic_hndl,
4599                 OUT uint64_t            *datagram_id
4600                 );
4601
4602 /**
4603  * gni_postdata_probe_wait_by_id - Probe by ID for datagrams associated with a cdm/nic until
4604  *                                 a datagram in completed, timed out, or cancelled state is found
4605  *                                 or the timeout expires.
4606  *
4607  * Parameters:
4608  * IN
4609  * nic_hndl     Handle of a nic associated with the cdm for which datagrams
4610  *              status is being probed.
4611  * timeout      The number of milliseconds to block before returning
4612  *              to the caller, (-1) if no time-out is desired.
4613  *
4614  * OUT
4615  * datagram_id  Id of first datagram found to be in completed, timed out, or
4616  *              cancelled state.  Valid only if the return value is GNI_RC_SUCCESS.
4617  *
4618  * Returns:
4619  * GNI_RC_SUCCESS - A datagram previously posted with a datagram_id in the completed,
4620  *                  timed out or cancelled state was found.
4621  *                  The id of the datagram is returned in the datagram_id argument.
4622  * GNI_RC_INVALID_PARAM - An invalid NIC handle or an invalid datagram_id address was specified.
4623  * GNI_RC_TIMEOUT - No datagram in completed, timed out, or cancelled state was found before
4624  *                  the timeout expired.
4625  *
4626  * Description:
4627  * This function returns the postid of the first datagram posted with a datagram_id found in
4628  * completed, timed out, or canceled state for the cdm associated with the
4629  * input nic handle.  This function must be used in conjunction
4630  * with gni_ep_postdata_test_by_id or gni_ep_postdata_wait_by_id to obtain data exchanged
4631  * in the datagram transaction.
4632  *
4633  * Note:
4634  * This function should be used for probing for completion of datagrams that
4635  * were previously posted using the gni_ep_postdata_w_id function.
4636  **/
4637 gni_return_t
4638         gni_postdata_probe_wait_by_id(
4639                 IN  gni_nic_handle_t    nic_hndl,
4640                 IN  uint32_t            timeout,
4641                 OUT uint64_t            *datagram_id
4642                 );
4643
4644 /**
4645  * gni_ep_postdata_cancel - Cancels postdata transaction
4646  *
4647  * Parameters:
4648  * IN
4649  * ep_hndl      Handle of the local Endpoint.
4650  *
4651  * Returns:
4652  * GNI_RC_SUCCESS - Canceled successfully.
4653  * GNI_RC_INVALID_PARAM - The ep_hndl parameter was invalid
4654  * GNI_RC_NO_MATCH      - No active postdata transaction on the ep_hndl
4655  *
4656  * Description:
4657  * This function is used to cancel a postdata transaction.
4658  **/
4659 gni_return_t
4660         gni_ep_postdata_cancel(
4661                 IN gni_ep_handle_t      ep_hndl
4662                 );
4663
4664 /**
4665  * gni_ep_postdata_cancel_by_id - Cancels postdata transaction with a specified
4666  *                                post id.
4667  *
4668  * Parameters:
4669  * IN
4670  * ep_hndl      Handle of the local Endpoint.
4671  * datagram_id  Id of the datagram to cancel.
4672  *
4673  * Returns:
4674  * GNI_RC_SUCCESS - Canceled successfully.
4675  * GNI_RC_INVALID_PARAM - The ep_hndl parameter was invalid
4676  * GNI_RC_NO_MATCH      - No active postdata transaction on the ep_hndl
4677  *
4678  * Description:
4679  * This function is used to cancel a postdata transaction.
4680  *
4681  * Note:
4682  * Unbound endpoints must cancel datagrams with the same datagram id used
4683  * when calling gni_ep_postdata_w_id.
4684  **/
4685 gni_return_t
4686         gni_ep_postdata_cancel_by_id(
4687                 IN gni_ep_handle_t      ep_hndl,
4688                 IN uint64_t             datagram_id
4689                 );
4690
4691 /**
4692  * gni_mem_register - Register memory with the NIC
4693  *
4694  * Parameters:
4695  * IN
4696  * nic_hndl     Handle of a currently open NIC.
4697  * address      Starting address of the memory region to be registered.
4698  * length       Length of the memory region to be registered, in bytes.
4699  * dst_cq_hndl  If not NULL, specifies the CQ to receive events related to
4700  *              the transactions initiated by the remote node into this memory region.
4701  * flags        One of the following flags: GNI_MEM_READWRITE_ONLY, GNI_MEM_READ_ONLY
4702  *
4703  * OUT
4704  * mem_hndl     The new memory handle for the region.
4705  *
4706  * Returns:
4707  * GNI_RC_SUCCESS - The memory region was successfully registered.
4708  * GNI_RC_INVALID_PARAM - One on the parameters was invalid.
4709  * GNI_RC_ERROR_RESOURCE - The registration operation failed due
4710  *                         to insufficient resources.
4711  * GNI_RC_PERMISSION_ERROR - The user's buffer R/W permissions conflict with
4712  *                           the flags argument.
4713  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
4714  *
4715  * Description:
4716  * This function allows a process to register a region of memory with the Gemini NIC.
4717  * The user may specify an arbitrary size region of memory, with arbitrary alignment,
4718  * but the actual area of memory registered will be registered on MRT block granularity
4719  * (or physical page granularity if MRT is not enabled for this process).
4720  * A memory region must consist of a single segment.
4721  * Using a single segment to register a memory region allows an application to use a virtual
4722  * address in the future transactions in and out of the registered region.
4723  * A single segment memory registration should be a common way an application
4724  * registers its memory, with a multiple segments registration being reserved
4725  * for special cases. A new memory handle is generated for each region of memory
4726  * that is registered by a process.
4727  * A length parameter of zero will result in a GNI_RC_INVALID_PARAM error.
4728  * The contents of the memory region being registered are not altered.
4729  * The memory region must be previously allocated by an application.
4730  * If failure is returned, the contents of mem_hndl are untouched.
4731  **/
4732 gni_return_t
4733         gni_mem_register(
4734                 IN  gni_nic_handle_t    nic_hndl,
4735                 IN  uint64_t            address,
4736                 IN  uint64_t            length,
4737                 IN  gni_cq_handle_t     dst_cq_hndl,
4738                 IN  uint32_t            flags,
4739                 OUT gni_mem_handle_t    *mem_hndl
4740                 );
4741
4742 /**
4743  * gni_mem_register_segments - Register memory with the NIC
4744  *
4745  * Parameters:
4746  * IN
4747  * nic_hndl     Handle of a currently open NIC.
4748  * mem_segmets  List of segments to be registered. Each element of the list
4749  *              consists of the starting address of the memory region and
4750  *              the length, in bytes.
4751  * segment_cnt  Number of segments in the mem_segments list.
4752  * dst_cq_hndl  If not NULL, specifies the CQ to receive events related to
4753  *              the transactions initiated by the remote node into this memory region.
4754  * flags        One of the following flags: GNI_MEM_READWRITE_ONLY, GNI_MEM_READ_ONLY
4755  *
4756  * OUT
4757  * mem_hndl     The new memory handle for the region.
4758  *
4759  * Returns:
4760  * GNI_RC_SUCCESS - The memory region was successfully registered.
4761  * GNI_RC_INVALID_PARAM - One on the parameters was invalid.
4762  * GNI_RC_ERROR_RESOURCE - The registration operation failed due
4763  *                         to insufficient resources.
4764  * GNI_RC_PERMISSION_ERROR - The user's buffer R/W permissions conflict with
4765  *                           the flags argument.
4766  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
4767  *
4768  * Description:
4769  * This function allows a process to register a region of memory with the Gemini NIC.
4770  * The user may specify an arbitrary size region of memory, with arbitrary alignment,
4771  * but the actual area of memory registered will be registered on MRT block granularity
4772  * (or physical page granularity if MRT is not enabled for this process).
4773  * This function allows a process to register a region of memory with
4774  * the Gemini NIC. The user may specify an arbitrary size region of memory,
4775  * with arbitrary alignment, but the actual area of memory registered will
4776  * be registered on MRT block granularity (or physical page granularity if
4777  * MRT is not enabled for this process).
4778  * To register a single segment GNI_MemRegister() function must be used,
4779  * with an exception of physical page registration (when GNI_MEM_PHYS_SEGMENTS flag is set).
4780  * Using this function imposes the requirement on an application to use an offset within
4781  * the registered memory region instead of a virtual address in all future
4782  * transactions, where registered region is aligned to MRT block size (or page size
4783  * for non-MRT registrations).
4784  * A single segment memory registration should be a common way
4785  * an application registers its memory. A multiple segments registration
4786  * should be reserved for special cases.
4787  * A new memory handle is generated for each region of memory that
4788  * is registered by a process.
4789  * A length parameter of zero in any segment will result in a GNI_RC_INVALID_PARAM error.
4790  * The contents of the memory region being registered are not altered.
4791  * The memory region must be previously allocated by an application.
4792  * If failure is returned, the contents of mem_hndl are untouched.
4793  **/
4794 gni_return_t
4795         gni_mem_register_segments(
4796                 IN  gni_nic_handle_t    nic_hndl,
4797                 IN  gni_mem_segment_t   *mem_segments,
4798                 IN  uint32_t            segments_cnt,
4799                 IN  gni_cq_handle_t     dst_cq_hndl,
4800                 IN  uint32_t            flags,
4801                 OUT gni_mem_handle_t    *mem_hndl
4802                 );
4803
4804 /**
4805  * gni_mem_deregister - De-register memory
4806  *
4807  * Parameters:
4808  * IN
4809  * nic_hndl     The handle for the NIC that owns the memory region being
4810  *              de-registered.
4811  * mem_hndl     Memory handle for the region.
4812  * hold_timeout Specifies a hold period before releasing the MDD for reuse
4813  *              in milliseconds.
4814  *
4815  * Returns:
4816  * GNI_RC_SUCCESS - The memory region was successfully de-registered.
4817  * GNI_RC_INVALID_PARAM - One or more of the parameters was invalid.
4818  *
4819  * Description:
4820  * This function de-registers memory that was previously registered
4821  * and unlocks the associated pages from physical memory. The contents
4822  * and attributes of the region of memory being de-registered are not
4823  * altered in any way. When the hold_timeout is used, the MDD is
4824  * disabled, but not available for reuse until the specified time in
4825  * milliseconds has elapsed. This is considered a dead-man timer. IE:
4826  * The timeout is for the driver to maintain the resources, if the
4827  * upper layers expect to call gni_mem_mdd_release on this mem_hndl,
4828  * then it must be in less time than this hold_timeout.
4829  **/
4830 gni_return_t
4831         gni_mem_deregister(
4832                 IN gni_nic_handle_t     nic_hndl,
4833                 IN gni_mem_handle_t     *mem_hndl,
4834                 IN int                  hold_timeout
4835                 );
4836
4837 /**
4838  * gni_mem_mdd_release - Release an MDD which was on-hold.
4839  *
4840  * Parameters:
4841  * IN
4842  * nic_hndl     The handle for the NIC that owns the memory region being
4843  *              de-registered.
4844  * mem_hndl     Memory handle for the region.
4845  *
4846  * Returns:
4847  * GNI_RC_SUCCESS - The MDD was successfully released.
4848  * GNI_RC_NO_MATCH - The MDD was not found on the waiting list.
4849  *
4850  * Description:
4851  * After an MDD is deregistered with a holding period, it can be
4852  * manually released by upper layers if they know the state is
4853  * clean. When calling this function it releases the MDD for reuse. It
4854  * returns two codes. Success means the MDD was found on the timer
4855  * list and removed. No match means that the MDD wasn't found,
4856  * although, this could have been on the list and already triggered,
4857  * or it could be bad parameters. It's hard to say at that point since
4858  * it is now released and could even be reused. If this funtion
4859  * returns no match, it would be considered the upper layers fault,
4860  * since the driver would have released the mem_hndl only after the
4861  * deadman timer was triggered.
4862  **/
4863 gni_return_t
4864         gni_mem_mdd_release(
4865                 IN gni_nic_handle_t     nic_hndl,
4866                 IN gni_mem_handle_t     *mem_hndl
4867                 );
4868
4869 /**
4870  * gni_cq_create - Create Completion Queue
4871  *
4872  * Parameters:
4873  * IN
4874  * nic_hndl     The handle of the associated NIC.
4875  * entry_count  The number of completion entries that this CQ will hold.
4876  * delay_index  The number of events the Gemini will allow to occur before
4877  *              generating an interrupt. Setting this to zero results in
4878  *              interrupt delivery with every event.
4879  *              For the user level this parameter is meaningful only when
4880  *              mode is set to GNI_CQ_BLOCKING
4881  * event_hndl   Address of the user-defined function to be called when
4882  *              the number of events specified by the delay_count parameter
4883  *              occurs (kernel level).
4884  *
4885  * OUT
4886  * cq_hndl      The handle of the newly created Completion Queue.
4887  *
4888  * Returns:
4889  * GNI_RC_SUCCESS - A new Completion Queue was successfully created.
4890  * GNI_RC_INVALID_PARAM - One or more of the parameters was invalid.
4891  * GNI_RC_ERROR_RESOURCE - The Completion Queue could not be created due
4892  *                         to insufficient resources.
4893  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
4894  *
4895  * Description:
4896  * This function creates a new Completion Queue. The caller must specify
4897  * the minimum number of completion entries that the queue must contain.
4898  * To avoid dropped completion notifications, applications should make sure
4899  * that the number of operations posted on Endpoints attached to a src_cq_hndl
4900  * does not exceed the completion queue capacity at any time.
4901  **/
4902 typedef void (gni_cq_event_hndlr_f)(IN uint32_t device_id, IN uint64_t data);
4903
4904 gni_return_t
4905         gni_cq_create(
4906                 IN  gni_nic_handle_t            nic_hndl,
4907                 IN  uint32_t                    entry_count,
4908                 IN  uint32_t                    delay_index,
4909                 IN  gni_cq_event_hndlr_f        *event_handler,
4910                 IN  uint64_t                    usr_event_data,
4911                 OUT gni_cq_handle_t             *cq_hndl
4912                 );
4913
4914 /**
4915  * gni_cq_destroy - Destroy Completion queue
4916  *
4917  * Parameters:
4918  * IN
4919  * cq_hndl      The handle for the Completion Queue to be destroyed.
4920  *
4921  * Returns:
4922  * GNI_RC_SUCCESS - The CQ was successfully destroyed.
4923  * GNI_RC_INVALID_PARAM - One or more of the parameters was invalid.
4924  * GNI_RC_ERROR_RESOURCE - The CQ could not be destroyed because one or
4925  *                         more Endpoint instances are still associated with it.
4926  *
4927  * Description:
4928  * This function destroys a specified Completion Queue.
4929  * If any Endpoints are associated with the CQ, the CQ is not destroyed and
4930  * an error is returned.
4931  **/
4932 gni_return_t
4933         gni_cq_destroy(
4934                 IN gni_cq_handle_t      cq_hndl
4935                 );
4936
4937 /**
4938  * gni_post_rdma - Post RDMA transaction
4939  *
4940  * Parameters:
4941  * IN
4942  * ep_hndl      Instance of a local Endpoint.
4943  * post_descr   Pointer to a descriptor to be posted.
4944  *
4945  * Returns:
4946  * GNI_RC_SUCCESS - The descriptor was successfully posted.
4947  * GNI_RC_INVALID_PARAM - The Endpoint handle was invalid.
4948  * GNI_RC_ALIGNMENT_ERROR - Posted source or destination data pointers or
4949  *                          data length are not properly aligned.
4950  * GNI_RC_ERROR_RESOURCE - The transaction request could not be posted due
4951  *                         to insufficient resources.
4952  * GNI_RC_ERROR_NOMEM - Insufficient memory to complete the operation.
4953  * GNI_RC_PERMISSION_ERROR - The user's buffer R/W permissions conflict with
4954  *                           the access type.
4955  *
4956  * Description:
4957  * This function adds a descriptor to the tail of the RDMA queue
4958  * and returns immediately.
4959  *
4960  **/
4961 gni_return_t
4962         gni_post_rdma(
4963                 IN gni_ep_handle_t              ep_hndl,
4964                 IN gni_post_descriptor_t        *post_descr
4965                 );
4966
4967 /**
4968  * gni_post_fma - Post FMA transaction
4969  *
4970  * Parameters:
4971  * IN
4972  * ep_hndl      Instance of a local Endpoint.
4973  * post_descr   Pointer to a descriptor to be posted.
4974  *
4975  * Returns:
4976  * GNI_RC_SUCCESS - The descriptor was successfully posted.
4977  * GNI_RC_INVALID_PARAM - The Endpoint handle was invalid.
4978  * GNI_RC_ALIGNMENT_ERROR - Posted source or destination data pointers or
4979  *                          data length are not properly aligned.
4980  * GNI_RC_ERROR_RESOURCE - The transaction request could not be posted due
4981  *                         to insufficient resources.
4982  *
4983  * Description:
4984  * This function executes a data transaction (Put, Get, or AMO) by
4985  * storing into the directly mapped FMA Window to initiate a series
4986  * of FMA requests.
4987  * It returns before the transaction is confirmed by the remote NIC.
4988  * Zero-length FMA Put operations are supported. Zero-length FMA Get and
4989  * zero-length FMA AMO operations are not supported.
4990  *
4991  **/
4992 gni_return_t
4993         gni_post_fma(
4994                 IN gni_ep_handle_t              ep_hndl,
4995                 IN gni_post_descriptor_t        *post_descr
4996                 );
4997
4998 /**
4999  * gni_get_completed - Get next completed descriptor
5000  *
5001  * Parameters:
5002  * IN
5003  * cq_hndl      The handle for the Completion Queue.
5004  * event_data   The event returned by CqGetEvent function.
5005  *
5006  * OUT
5007  * post_desc    Address of the descriptor that has completed.
5008  *
5009  * Returns:
5010  * GNI_RC_SUCCESS - A completed descriptor was returned with a successful
5011  *                  completion status.
5012  * GNI_RC_DESCRIPTOR_ERROR - If the corresponding post queue (FMA, RDMA or AMO)
5013  *                           is empty, the descriptor pointer is set to NULL,
5014  *                           otherwise, a completed descriptor is returned with
5015  *                           an error completion status.
5016  * GNI_RC_INVALID_PARAM - The Endpoint handle was invalid.
5017  * GNI_RC_TRANSACTION_ERROR - A completed descriptor was returned with a
5018  *                            network error status.
5019  *
5020  * Description:
5021  * This function gets the descriptor from the corresponding post queue.
5022  * The post queue is identified by the transaction type the GetCompleted
5023  * function extracts from the event_data parameter. The descriptor is removed
5024  * from the head of the queue and the address of the descriptor is returned.
5025  *
5026  **/
5027 gni_return_t
5028         gni_get_completed(
5029                 IN  gni_cq_handle_t             cq_hndl,
5030                 IN  gni_cq_entry_t              event_data,
5031                 OUT gni_post_descriptor_t       **post_descr
5032                 );
5033
5034 /**
5035  * gni_cq_get_event - Get next event
5036  *
5037  * Parameters:
5038  * IN
5039  * cq_hndl      The handle for the Completion Queue.
5040  *
5041  * OUT
5042  * event_data   A new event entry data, if the return status indicates success.
5043  *              Undefined otherwise.
5044  *
5045  * Returns:
5046  * GNI_RC_SUCCESS - A completion entry was found on the Completion Queue.
5047  * GNI_RC_NOT_DONE - No new completion entries are on the Completion Queue.
5048  * GNI_RC_INVALID_PARAM - The Completion Queue handle was invalid.
5049  * GNI_RC_ERROR_RESOURCE - The Completion Queue was in an overrun state and
5050  *                         events may have been lost.
5051  * GNI_RC_TRANSACTION_ERROR - A completion entry in an error state was found on
5052  *                            the Completion Queue in an error state.
5053  *
5054  * Description:
5055  * This function polls the specified Completion Queue for a completion entry.
5056  * If a completion entry is found, it returns the event data stored in the entry.
5057  * CqGetEvent is a non-blocking call. It is up to the calling process
5058  * to subsequently invoke the appropriate function to de-queue the completed descriptor.
5059  * CqGetEvent only de-queues the completion entry from the Completion Queue.
5060  *
5061  **/
5062 gni_return_t
5063         gni_cq_get_event(
5064                 IN  gni_cq_handle_t     cq_hndl,
5065                 OUT gni_cq_entry_t      *event_data
5066                 );
5067
5068 /**
5069  * gni_cq_error_str - Decode error status into a string for a CQ Entry
5070  *
5071  * Parameters:
5072  * IN
5073  * entry           CQ entry with error status to be decoded
5074  * len             Length of the buffer in bytes
5075  *
5076  * OUT
5077  * buffer          Pointer to the buffer where the error code will be
5078  *                 returned.
5079  *
5080  * Returns:
5081  * GNI_RC_SUCCESS - The entry was successfully decoded.
5082  * GNI_RC_INVALID_PARAM - Invalid input parameter
5083  * GNI_RC_SIZE_ERROR - Supplied buffer is too small to contain the error
5084  *                     code
5085  *
5086  * Description:
5087  * This function decodes the error status encoded in a CQ Entry
5088  * by the hardware.
5089  *
5090  **/
5091 gni_return_t
5092         gni_cq_error_str(
5093                 IN  gni_cq_entry_t      entry,
5094                 OUT void                *buffer,
5095                 IN  uint32_t            len
5096                 );
5097
5098 /**
5099  * gni_cq_error_recoverable - Deduce error status as recoverable for a CQ Entry
5100  *
5101  * Parameters:
5102  * IN
5103  * entry           CQ entry with error status to be decoded
5104  *
5105  * OUT
5106  * recoverable     Pointer to the integer flag that will contain the result.
5107  *
5108  * Returns:
5109  * GNI_RC_SUCCESS - The entry was successfully decoded.
5110  * GNI_RC_INVALID_PARAM - Invalid input parameter
5111  * GNI_RC_INVALID_STATE - CQ entry translates to an undefined state
5112  *
5113  * Description:
5114  * This function translates any error status encoded in a CQ Entry by
5115  * the hardware into a recoverable/unrecoverable flag for application
5116  * usage.
5117  *
5118  **/
5119 gni_return_t
5120         gni_cq_error_recoverable(
5121                 IN  gni_cq_entry_t      entry,
5122                 OUT uint32_t            *recoverable
5123                 );
5124
5125 /**
5126  * gni_smsg_buff_size_needed - Return amount of memory required for short
5127  *                             message resources given parameters in an input
5128  *                             short message attributes structure
5129  * IN
5130  * local_smsg_attr      parameters for short messaging
5131  *
5132  * OUT
5133  * size                 size in bytes required for the short message buffer
5134  *
5135  * Returns:
5136  * GNI_RC_SUCCESS - Operation completed successfully.
5137  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
5138  *
5139  * Description:
5140  * This utility function provides an application with a way to determine the
5141  * amount of memory needs to be allocated for short messaging resources.  The
5142  * msg_buffer, buff_size, mem_hndl, and mbox_offset fields in the input
5143  * smsg_attr structure do not need to be defined.
5144  **/
5145 gni_return_t
5146         gni_smsg_buff_size_needed(
5147                 IN  gni_smsg_attr_t     *smsg_attr,
5148                 OUT unsigned int        *size
5149                 );
5150
5151 /**
5152  * gni_smsg_init - Initialize short messaging resources
5153  * IN
5154  * ep_hndl              The handle of the Endpoint.
5155  * local_smsg_attr      Local parameters for short messaging
5156  * remote_smsg_attr     Remote parameters for short messaging provided by peer
5157  *
5158  * Returns:
5159  * GNI_RC_SUCCESS - Operation completed successfully.
5160  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
5161  * GNI_RC_INVALID_STATE - Endpoind is not bound
5162  * GNI_RC_ERROR_NOMEM - Insufficient memory to allocate short message
5163  *                      internal structures
5164  *
5165  * Description:
5166  * This function configures the short messaging protocol on the given Endpoint.
5167  **/
5168 gni_return_t
5169         gni_smsg_init(
5170                 IN gni_ep_handle_t      ep_hndl,
5171                 IN gni_smsg_attr_t      *local_smsg_attr,
5172                 IN gni_smsg_attr_t      *remote_smsg_attr
5173                 );
5174
5175 /**
5176  * gni_smsg_set_delivery_mode - Configures SMSG delivery mode.
5177  *
5178  * IN
5179  * nic_handle           The NIC handle to alter.
5180  * dlvr_mode            The new SMSG delivery mode.
5181  *
5182  * Returns:
5183  * GNI_RC_SUCCESS - Operation completed successfully.
5184  * GNI_RC_INVALID_PARAM - Invalid NIC handle specified or
5185  *                        the delivery mode is invalid.
5186  *
5187  * Description:
5188  * This functions sets the SMSG delivery mode for SMSG transactions.
5189  **/
5190 gni_return_t
5191         gni_smsg_set_delivery_mode(
5192                 IN gni_nic_handle_t        nic_handle,
5193                 IN uint16_t                 dlvr_mode
5194                 );
5195
5196 /**
5197  * gni_smsg_send - Send short message
5198  *
5199  * Parameters:
5200  * IN
5201  * ep_hndl      Instance of an Endpoint.
5202  * header       Pointer to the header of a message.
5203  * header_length Length of the header in bytes.
5204  * data         Pointer to the payload of the message.
5205  * data_length Length of the payload in bytes.
5206  * msg_id       Identifier for application to track transaction.
5207  *              Only valid for short messaging using MBOX_PERSISTENT type,
5208  *              otherwise ignored.
5209  *
5210  * Returns:
5211  * GNI_RC_SUCCESS - The message was successfully sent.
5212  * GNI_RC_INVALID_PARAM - The Endpoint handle was invalid or
5213  *                        the Endpoint is not initialized for short messaging.
5214  * GNI_RC_NOT_DONE - No credits available to send the message
5215  * GNI_RC_ERROR_RESOURCE - The total size of the header plus data exceeds
5216  *                         the maximum short message size defined by GNI_SMSG_MAX_SIZE.
5217  *
5218  * Description:
5219  * This function sends a message to the remote peer, by copying it into
5220  * the pre-allocated remote buffer space using the FMA mechanism.
5221  * It returns before the delivery is confirmed by the remote NIC.
5222  * With MBOX_PERSISTENT type system attempts to re-transmit
5223  * for certain transaction failures.
5224  * This is a non-blocking call.
5225  *
5226  **/
5227 gni_return_t
5228         gni_smsg_send(
5229                 IN gni_ep_handle_t      ep_hndl,
5230                 IN void                 *header,
5231                 IN uint32_t             header_length,
5232                 IN void                 *data,
5233                 IN uint32_t             data_length,
5234                 IN uint32_t             msg_id
5235                 );
5236
5237 /**
5238  * gni_smsg_getnext - Get next available short message
5239  *
5240  * Parameters:
5241  * IN
5242  * ep_hndl      Instance of an Endpoint.
5243  *
5244  * OUT
5245  * header       Pointer to the header of the newly arrived message.
5246  *
5247  * Returns:
5248  * GNI_RC_SUCCESS - The new message is successfully arrived.
5249  * GNI_RC_INVALID_PARAM - The Endpoint handle was invalid or the Endpoint is
5250  *                        not initialized for short messaging.
5251  * GNI_RC_NOT_DONE - No new messages available.
5252  * GNI_RC_INVALID_STATE - The SMSG connection has entered an invalid state.
5253  *
5254  * Description:
5255  * This function returns a pointer to the header of the newly arrived message and
5256  * makes this message current. An application may decide to copy the message out
5257  * of the mailbox or process it immediately. This is a non-blocking call.
5258  *
5259  **/
5260 gni_return_t
5261         gni_smsg_getnext(
5262                 IN  gni_ep_handle_t     ep_hndl,
5263                 OUT void                **header
5264                 );
5265
5266 /**
5267  * gni_smsg_release - Release current message
5268  *
5269  * Parameters:
5270  * IN
5271  * ep_hndl      Instance of an Endpoint.
5272  *
5273  * Returns:
5274  * GNI_RC_SUCCESS - The current message is successfully released.
5275  * GNI_RC_INVALID_PARAM - The Endpoint handle was invalid or the Endpoint
5276  *                        is not initialized for short messaging.
5277  * GNI_RC_NOT_DONE - There is no current message. The GetNext function must
5278  *                   return GNI_RC_SUCCESS before calling this function.
5279  *
5280  * Description:
5281  * This function releases the current message buffer. It must be called only
5282  * after GetNext has returned GNI_RC_SUCCESS. This is a non-blocking call.
5283  * The message returned by the GetNext function must be copied out or processed
5284  * prior to making this call.
5285  *
5286  **/
5287 gni_return_t
5288         gni_smsg_release(
5289                 IN gni_ep_handle_t      ep_hndl
5290                 );
5291
5292 /**
5293  * gni_smsg_set_max_retrans - Configures SMSG max retransmit count.
5294  *
5295  * IN
5296  * nic_handle           The NIC handle to alter.
5297  * max_retrans          The new SMSG max retransmit count.
5298  *
5299  * Returns:
5300  * GNI_RC_SUCCESS - Operation completed successfully.
5301  * GNI_RC_INVALID_PARAM - Invalid NIC handle specified.
5302  * Description:
5303  * This functions sets the maximum retransmit counts for SMSG transactions.
5304  * EPs associated with the NIC handle provided will give up retransmitting SMSG
5305  * transactions and return GNI_RC_TRANSACTION_ERROR when the retransmit count
5306  * has been reached.
5307  **/
5308 gni_return_t
5309         gni_smsg_set_max_retrans(
5310                 IN gni_nic_handle_t     nic_handle,
5311                 IN uint16_t             max_retrans
5312                 );
5313
5314 /**
5315  * gni_subscribe_errors - Subscribe to error events on associated NIC.
5316  *
5317  * Parameters:
5318  * IN
5319  * nic_handle           The handle of the associated NIC.
5320  * mask                 The error mask with corresponding bits set for notification.
5321  * EEQ_size             Size of the EEQ. If 0 is passed in there will be no queue.
5322  * EQ_new_event         A callback that can be triggered when new events are entered in the EQ.
5323  * app_crit_err         A critical event which would kill a user app will also trigger this callback.
5324  *
5325  * OUT
5326  * err_handle           The handle of the subscribed error events.
5327  *
5328  * Returns:
5329  * GNI_RC_SUCCESS       - Operation completed successfully.
5330  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
5331  * GNI_RC_ERROR_NOMEM   - The event queue could not be created due to insufficient memory.
5332  *
5333  * Description:
5334  * This function creates an error event queue. When this function
5335  * returns, events start reporting immediately.
5336  *
5337  * Also, the mask value can be a bitwise OR of the error categories as
5338  * defined by the GNI_ERRMASK_* flags found in gni_pub.h.
5339  *
5340  **/
5341 gni_return_t
5342         gni_subscribe_errors(
5343                 IN  gni_nic_handle_t    nic_handle,
5344                 IN  gni_error_mask_t    mask,
5345                 IN  uint32_t            EEQ_size,
5346                 IN  void                (*EQ_new_event)(gni_err_handle_t),
5347                 IN  void                (*app_crit_err)(gni_err_handle_t),
5348                 OUT gni_err_handle_t    *err_handle
5349                 );
5350
5351 /**
5352  * gni_release_errors - Release error event notification.
5353  *
5354  * Parameters:
5355  * IN
5356  * err_handle           The handle of the subscribed error events.
5357  *
5358  * Returns:
5359  * GNI_RC_SUCCESS       - Operation completed successfully.
5360  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
5361  * GNI_RC_NOT_DONE      - A thread is still waiting on the event queue.
5362  *
5363  * Description:
5364  * This function releases the error event notification and cleans up
5365  * the memory resources for the event queue.
5366  *
5367  **/
5368 gni_return_t
5369         gni_release_errors(
5370                 IN gni_err_handle_t     err_handle
5371                 );
5372
5373 /**
5374  * gni_get_error_mask - Get the currently set error mask.
5375  *
5376  * Parameters:
5377  * IN
5378  * err_handle           The handle of the subscribed error events.
5379  *
5380  * OUT
5381  * mask                 The pointer to copy the mask value to.
5382  *
5383  * Returns:
5384  * GNI_RC_SUCCESS       - Operation completed successfully.
5385  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
5386  *
5387  * Description:
5388  * The error mask is used to match error events, and decide if the
5389  * subscriber wants an event delivered. This is a convenience
5390  * function.
5391  *
5392  **/
5393 gni_return_t
5394         gni_get_error_mask(
5395                 IN  gni_err_handle_t    err_handle,
5396                 OUT gni_error_mask_t    *mask
5397                 );
5398
5399 /**
5400  * gni_set_error_mask - Set a new error mask for matching events.
5401  *
5402  * Parameters:
5403  * IN
5404  * err_handle           The handle of the subscribed error events.
5405  * mask_in              The error mask with corresponding bits set for notification.
5406  * mask_out             The pointer to copy the pre-set mask value to.
5407  *
5408  * Returns:
5409  * GNI_RC_SUCCESS       - Operation completed successfully.
5410  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
5411  *
5412  * Description:
5413  * Set a new error mask used to match for error event delivery.
5414  *
5415  **/
5416 gni_return_t
5417         gni_set_error_mask(
5418                 IN gni_err_handle_t     err_handle,
5419                 IN gni_error_mask_t     mask_in,
5420                 IN gni_error_mask_t     *mask_out
5421                 );
5422
5423 /**
5424  * gni_get_error_event - Get an error event, if available.
5425  *
5426  * Parameters:
5427  * IN
5428  * err_handle           The handle of the subscribed error events.
5429  * event                The pointer to the buffer to copy the event into.
5430  *
5431  * Returns:
5432  * GNI_RC_SUCCESS          - Operation completed successfully.
5433  * GNI_RC_INVALID_PARAM    - One of the input parameters was invalid.
5434  * GNI_RC_NOT_DONE         - No event was found in the event queue.
5435  *
5436  * Description:
5437  * This function is non-blocking and when it is called it will return
5438  * any new events in the event pointer.
5439  *
5440  **/
5441 gni_return_t
5442         gni_get_error_event(
5443                 IN gni_err_handle_t     err_handle,
5444                 IN gni_error_event_t    *event
5445                 );
5446
5447 /**
5448  * gni_wait_error_events - Wait until an error event occurs.
5449  *
5450  * Parameters:
5451  * IN
5452  * err_handle           The handle of the subscribed error events.
5453  * events               The pointer to the buffer to copy the events into.
5454  * events_size          The number of events in the events pointer.
5455  * timeout              After first event is triggered, time to wait for subsequent events.
5456  *
5457  * OUT
5458  * num_events           The number of events copied into the events buffer.
5459  *
5460  * Returns:
5461  * GNI_RC_SUCCESS          - Operation completed successfully.
5462  * GNI_RC_INVALID_PARAM    - One of the input parameters was invalid.
5463  * GNI_RC_NOT_DONE         - No event was found in the event queue.
5464  * GNI_RC_TIMEOUT          - Timeout was triggered before any more events came.
5465  *
5466  * Description:
5467  * This function will block waiting forever waiting for one event to
5468  * occur. When that one event is triggered, it will delay returning to
5469  * try and coalesce error events. The timeout value is specified in
5470  * number of milliseconds. The number of events copied are stored in
5471  * the num_events structure.
5472  *
5473  **/
5474 gni_return_t
5475         gni_wait_error_events(
5476                 IN  gni_err_handle_t    err_handle,
5477                 IN  gni_error_event_t   *events,
5478                 IN  uint32_t            events_size,
5479                 IN  uint32_t            timeout,
5480                 OUT uint32_t            *num_events
5481                 );
5482
5483 /**
5484  * gni_set_error_ptag - Set protection tag for error reporting.
5485  *
5486  * Parameters:
5487  * IN
5488  * err_handle           The handle of the subscribed error events.
5489  * ptag                 The protect tag to set for matching error events.
5490  *
5491  * Returns:
5492  * GNI_RC_SUCCESS          - Operation completed successfully.
5493  * GNI_RC_INVALID_PARAM    - One of the input parameters was invalid.
5494  * GNI_RC_PERMISSION_ERROR - Only super-user can set ptag to something other than the communication domain.
5495  *
5496  * Description:
5497  * This is a privileged operation only. This function allows error
5498  * event capturing on other ptags. It also can be set to 0 to specify
5499  * capturing all events.
5500  *
5501  **/
5502 gni_return_t
5503         gni_set_error_ptag(
5504                 IN gni_err_handle_t     err_handle,
5505                 IN uint8_t              ptag
5506                 );
5507
5508 /**
5509  * gni_set_quiesce_callback - Setup quiesce callback
5510  *
5511  * Parameters:
5512  * IN
5513  * nic_hndl     Handle of the associated Gemini NIC.
5514  * qsce_func    A callback func for when quiesce has completed
5515  *
5516  * Returns:
5517  * GNI_RC_SUCCESS       - Operation completed successfully.
5518  * GNI_RC_INVALID_PARAM - One of the input parameters was invalid.
5519  * GNI_RC_INVALID_STATE - The nic_hndl was already registered with a quiesce function
5520  *
5521  * Description:
5522  *
5523  * This is a private function available to Cray specific kernel
5524  * modules which need to be notified of quiesce state. This function
5525  * is called when quiesce is completed. Thus, any timers that
5526  * triggered in the meantime, are aware of why transfers may have
5527  * stalled. The callback function must not go to sleep. It is called
5528  * with a lock, for correctness. Finally, the second argument to the
5529  * callback is the time it took to quiesce in milliseconds.
5530  **/
5531 gni_return_t
5532         gni_set_quiesce_callback(
5533                 IN gni_nic_handle_t     nic_hndl,
5534                 IN void                 (*qsce_func)(gni_nic_handle_t, uint64_t)
5535                 );
5536
5537 /**
5538  * gni_get_quiesce_state - Return quiesce status
5539  *
5540  * Parameters:
5541  * IN
5542  * nic_hndl     Handle of the associated Gemini NIC.
5543  *
5544  * Returns:
5545  * 0   - Quiesce is not in progress
5546  * 1   - Quiesce is currently turned on
5547  *
5548  * Description:
5549  *
5550  * This is a private function available to Cray specific kernel
5551  * modules which need to query the quiesce state. Thus the unusual
5552  * return value.
5553  **/
5554 uint32_t
5555         gni_get_quiesce_status(
5556                 IN gni_nic_handle_t     nic_hndl
5557                 );
5558
5559
5560 /**
5561  * gni_get_errno - Return local CPU kgni errno value
5562  *
5563  * Parameters:
5564  * IN
5565  * nic_hndl     Handle of the associated Gemini NIC.
5566  *
5567  * OUT
5568  * errno_ptr    Pointer to the gni_errno_t structure to copy the local CPU GNI
5569  *              errno data into.
5570  *
5571  * Returns:
5572  * GNI_RC_SUCCESS       - GNI errno data was copied into the structre at errno_ptr.
5573  * GNI_RC_INVALID_PARAM - One of the parameters was invalid.
5574  * GNI_RC_INVALID_STATE - The local CPU GNI errno data has not been updated
5575  *                        since the last call to gni_get_errno().
5576  *
5577  * Description:
5578  *
5579  * This function returns extra information after certain kgni interface errors
5580  * occur on a CPU.  On initialization, each CPU's GNI errno data is invalid.
5581  * When a kgni public interface call returns an error, the local CPU's
5582  * gni_errno data could be set if the local CPU's gni_errno data is invalid.
5583  * When set, a CPU's gni_errno data must be invalidated with a call to
5584  * gni_get_errno() before new gni_errno data can be saved.  New errno data will
5585  * not be saved on the local CPU until this call is made.  Due to this, data
5586  * for the first kgni error (if several may occur in a single interface call)
5587  * will be saved in the local CPU's gni_errno data.
5588  **/
5589 gni_return_t
5590         gni_get_errno(
5591                 IN  gni_nic_handle_t    nic_hndl,
5592                 OUT gni_errno_t         *errno_ptr
5593                 );
5594
5595 #endif /*__KERNEL__*/
5596
5597 #ifdef __cplusplus
5598 } /* extern "C" */
5599 #endif
5600
5601 #endif /*_GNI_PUB_H_*/