lnet/klnds/gnilnd/gni_pub.h

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