Whamcloud - gitweb
LU-5710 all: second batch of corrected typos and grammar errors
[fs/lustre-release.git] / 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