[DAPL2] sync with WinOF 2.1 branch
[mirror/winof/.git] / inc / iba / ib_al.h
1 /*\r
2  * Copyright (c) 2005 SilverStorm Technologies.  All rights reserved.\r
3  * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. \r
4  * Portions Copyright (c) 2008 Microsoft Corporation.  All rights reserved.\r
5  *\r
6  * This software is available to you under the OpenIB.org BSD license\r
7  * below:\r
8  *\r
9  *     Redistribution and use in source and binary forms, with or\r
10  *     without modification, are permitted provided that the following\r
11  *     conditions are met:\r
12  *\r
13  *      - Redistributions of source code must retain the above\r
14  *        copyright notice, this list of conditions and the following\r
15  *        disclaimer.\r
16  *\r
17  *      - Redistributions in binary form must reproduce the above\r
18  *        copyright notice, this list of conditions and the following\r
19  *        disclaimer in the documentation and/or other materials\r
20  *        provided with the distribution.\r
21  *\r
22  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,\r
23  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\r
24  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\r
25  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS\r
26  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN\r
27  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
28  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r
29  * SOFTWARE.\r
30  *\r
31  * $Id$\r
32  */\r
33 \r
34 \r
35 #if !defined(__IB_AL_H__)\r
36 #define __IB_AL_H__\r
37 \r
38 #include <iba/ib_types.h>\r
39 #include <complib/cl_waitobj.h>\r
40 #include <complib/cl_qlist.h>\r
41 \r
42 #ifdef __cplusplus\r
43 extern "C"\r
44 {\r
45 #endif  /* __cplusplus */\r
46 \r
47 /****h* IB Access Layer API/Access Layer\r
48 * NAME\r
49 *       InfiniBand Access Layer\r
50 * COPYRIGHT\r
51 *       Copyright (c) 2003 Intel Corporation - All Rights Reserved.\r
52 * DESCRIPTION\r
53 *       The access layer provides transport level access to an InfiniBand fabric.\r
54 *       It supplies a foundation upon which a channel driver may be built.  The\r
55 *       access layer exposes the capabilities of the InfiniBand architecture and\r
56 *       adds support for higher-level functionality required by most users of an\r
57 *       InfiniBand fabric.  Users define the protocols and policies used by the\r
58 *       access layer, and the access layer implements them under the direction\r
59 *       of a user.\r
60 ****/\r
61 \r
62 typedef struct _ib_al*                                  ib_al_handle_t;\r
63 typedef struct _al_pnp*                                 ib_pnp_handle_t;\r
64 typedef struct _al_reg_svc*                             ib_reg_svc_handle_t;\r
65 typedef struct _al_mad_send*                    ib_mad_send_handle_t;\r
66 typedef struct _al_mad_svc*                             ib_mad_svc_handle_t;\r
67 typedef struct _al_query*                               ib_query_handle_t;\r
68 typedef struct _al_sub*                                 ib_sub_handle_t;\r
69 typedef struct _al_listen*                              ib_listen_handle_t;\r
70 typedef struct _al_ioc*                                 ib_ioc_handle_t;\r
71 typedef struct _al_svc_entry*                   ib_svc_handle_t;\r
72 typedef struct _al_pool_key*                    ib_pool_key_t;\r
73 typedef struct _al_pool*                                ib_pool_handle_t;\r
74 typedef struct _mlnx_fmr_pool_element*  mlnx_fmr_pool_el_t;\r
75 \r
76 \r
77 typedef struct _ib_cm_handle\r
78 {\r
79         ib_al_handle_t          h_al;\r
80         ib_qp_handle_t          h_qp;\r
81         net32_t                         cid;\r
82 \r
83 }       ib_cm_handle_t;\r
84 \r
85 \r
86 /****s* Access Layer/ib_shmid_t\r
87 * NAME\r
88 *       ib_shmid_t\r
89 *\r
90 * DESCRIPTION\r
91 *       Shared Memory Identifier, used to uniquely identify a shared memory region.\r
92 *\r
93 * SYNOPSIS\r
94 */\r
95 typedef uint8_t         ib_shmid_t[64];\r
96 /*\r
97 * SEE ALSO\r
98 *       ib_reg_shmid\r
99 *********/\r
100 \r
101 \r
102 /****d* Access Layer/ATS\r
103 * NAME\r
104 *       DAPL Address Translation Service\r
105 *\r
106 * DESCRIPTION\r
107 *       ATS service ID, service name, and IPv4 offset for DAPL-compliant\r
108 *       ATS service records.\r
109 */\r
110 #define ATS_SERVICE_ID          CL_NTOH64( 0x10000CE100415453 )\r
111 #define ATS_NAME                        "DAPL Address Translation Service"\r
112 #define ATS_IPV4_OFFSET         12\r
113 /**********/\r
114 \r
115 \r
116 /****s* Access Layer/ib_mad_element_t\r
117 * NAME\r
118 *       ib_mad_element_t\r
119 *\r
120 * DESCRIPTION\r
121 *       Information used to submit a work request to a management datagram (MAD)\r
122 *       queue pair.\r
123 *\r
124 * SYNOPSIS\r
125 */\r
126 typedef struct _ib_mad_element\r
127 {\r
128         TO_LONG_PTR(struct _ib_mad_element*, p_next);\r
129         TO_LONG_PTR(const void*,        context1);\r
130         TO_LONG_PTR(const void*,        context2);\r
131 \r
132         /* Request/completion data. */\r
133         TO_LONG_PTR(ib_mad_t*,          p_mad_buf);\r
134         uint32_t                                        size;\r
135         uint32_t                                        immediate_data;\r
136         ib_net32_t                                      remote_qp;\r
137 \r
138         /* Send request information. */\r
139         TO_LONG_PTR(ib_av_handle_t,     h_av);\r
140         ib_send_opt_t                           send_opt;\r
141         ib_net32_t                                      remote_qkey;\r
142         boolean_t                                       resp_expected;\r
143         uint32_t                                        timeout_ms;\r
144         uint32_t                                        retry_cnt;\r
145         uint8_t                                         rmpp_version;\r
146 \r
147         /* Completion information. */\r
148         ib_wc_status_t                          status;\r
149         boolean_t                                       grh_valid;\r
150         TO_LONG_PTR(ib_grh_t*,          p_grh);\r
151 \r
152         /* Completed receive data or send request information if h_av is NULL. */\r
153         uint32_t                                        recv_opt;\r
154         ib_net16_t                                      remote_lid;\r
155         uint8_t                                         remote_sl;\r
156         uint16_t                                        pkey_index;\r
157         uint8_t                                         path_bits;\r
158 \r
159         /* Transaction completion data. */\r
160         TO_LONG_PTR(void*,                      send_context1);\r
161         TO_LONG_PTR(void*,                      send_context2);\r
162 \r
163 }       ib_mad_element_t;\r
164 /*\r
165 * FIELDS\r
166 *       p_next\r
167 *               A pointer used to chain MAD elements together.  This value is\r
168 *               set to NULL to mark the end of the chain.\r
169 *\r
170 *       context1\r
171 *               User-defined context information associated with the datagram.\r
172 *\r
173 *       context2\r
174 *               User-defined context information associated with the datagram.\r
175 *\r
176 *       p_buffer\r
177 *               The local data buffer contain the MAD.\r
178 *\r
179 *       size\r
180 *               The size of the MAD referenced by p_buffer.\r
181 *\r
182 *       immediate_data\r
183 *               32-bit field sent or received as part of a datagram message.\r
184 *               This field is valid for send operations if the send_opt\r
185 *               IB_SEND_OPT_IMMEDIATE flag has been set.  This field is valid\r
186 *               on received datagram completions if the recv_opt\r
187 *               IB_RECV_OPT_IMMEDIATE flag is set.\r
188 *\r
189 *       remote_qp\r
190 *               Identifies the destination queue pair of a datagram send operation or\r
191 *               the source queue pair of a received datagram.\r
192 *\r
193 *       h_av\r
194 *               An address vector that specifies the path information used to route\r
195 *               the outbound datagram to the destination queue pair.  This handle may\r
196 *               be NULL when sending a directed route SMP or if the access layer\r
197 *               should create the address vector for the user.\r
198 *\r
199 *       send_opt\r
200 *               Optional send control parameters.  The following options are valid:\r
201 *               IB_SEND_OPT_IMMEDIATE and IB_SEND_OPT_SOLICITED.  IB_SEND_OPT_FENCE\r
202 *               is only valid on MAD QPs.\r
203 *\r
204 *       remote_qkey\r
205 *               The qkey for the destination queue pair.\r
206 *\r
207 *       resp_expected\r
208 *               This field is used to indicate that the submitted operation expects\r
209 *               a response.  When set, the access layer will retry this send operation\r
210 *               until the corresponding response is successfully received, or the\r
211 *               request times out.  Send operations for which a response is expected\r
212 *               will always be completed by the access layer before the corresponding\r
213 *               received response.\r
214 *\r
215 *       timeout_ms\r
216 *               Specifies the number of milliseconds to wait for a response to\r
217 *               a request until retrying or timing out the request.  This field is\r
218 *               ignored if resp_expected is set to FALSE.\r
219 *\r
220 *       retry_cnt\r
221 *               Specifies the number of times that the request will be retried\r
222 *               before failing the request.  This field is ignored if resp_expected\r
223 *               is set to FALSE.\r
224 *\r
225 *       rmpp_version\r
226 *               Indicates the version of the RMPP protocol to use when sending this\r
227 *               MAD.  For MADs posted to MAD services of type IB_MAD_SVC_DEFAULT,\r
228 *               setting this field to 0 disables RMPP on user-defined management\r
229 *               classes or invokes the default RMPP version for well-defined management\r
230 *               classes, if appropriate.  For MADs posted to MAD services of type\r
231 *               IB_MAD_SVC_RMPP, setting this field to 0 disables RMPP on the sent\r
232 *               MAD.  Note that if the RMPP header exists, but the RMPP protocol is\r
233 *               not activated for this MAD, the user must ensure that the RMPP header\r
234 *               has been zeroed.  This field is intended to help support backwards\r
235 *               compatibility.\r
236 *\r
237 *       status\r
238 *               The result of the MAD work request.\r
239 *\r
240 *       grh_valid\r
241 *               A flag indicating whether the p_grh reference is valid.\r
242 *\r
243 *       p_grh\r
244 *               A reference to the global route header information.\r
245 *\r
246 *       recv_opt\r
247 *               Indicates optional fields valid as part of a work request that\r
248 *               completed on an unreliable datagram queue pair.\r
249 *\r
250 *       remote_lid\r
251 *               The source LID of the received datagram.\r
252 *\r
253 *       remote_sl\r
254 *               The service level used by the source of the received datagram.\r
255 *\r
256 *       pkey_index\r
257 *               This is valid only for IB_QPT_QP1 and IB_QPT_QP1_ALIAS QP types.\r
258 *               For received datagrams, this field contains the pkey index for\r
259 *               the source queue pair.  For send operations, this field contains\r
260 *               the pkey index to use when posting the send work request. \r
261 *\r
262 *       path_bits\r
263 *               The portion of the remote_lid that may be changed to vary the path\r
264 *               through the subnet to the remote port.\r
265 *\r
266 *       send_context1\r
267 *               If this datagram was received as a response to a sent datagram, this\r
268 *               field contains the context1 value of the send operation.  If this is\r
269 *               an unsolicited receive, this field will be 0.\r
270 *\r
271 *       send_context2\r
272 *               If this datagram was received as a response to a sent datagram, this\r
273 *               field contains the context2 value of the send operation.  If this is\r
274 *               an unsolicited receive, this field will be 0.\r
275 *\r
276 *       remote_qp\r
277 *               Identifies the source queue pair of a received datagram.\r
278 *\r
279 * NOTES\r
280 *       The format of data sent over the fabric is expected to be in the form\r
281 *       of a MAD.  MADs are expected to match the format defined by the\r
282 *       Infiniband specification and must be in network-byte order when posted\r
283 *       to a MAD service.\r
284 *\r
285 *       This structure is received to notify a user that a datagram has been\r
286 *       received for a registered management class.  Information of the source\r
287 *       of the data is provided, along with the data buffer.\r
288 *\r
289 *       The MAD element structure is defined such that a received MAD element\r
290 *       may be re-used as a sent response.  In such cases, the h_av field may be\r
291 *       NULL.  The address vector will be created and destroyed by the access\r
292 *       layer.\r
293 *\r
294 * SEE ALSO\r
295 *       ib_get_mad, ib_put_mad, ib_send_mad, ib_local_ds_t, ib_send_opt_t,\r
296 *       ib_pfn_mad_recv_cb_t, ib_get_mad_buf\r
297 *****/\r
298 \r
299 \r
300 /****f* Access Layer/ib_get_mad_buf\r
301 * NAME\r
302 *       ib_get_mad_buf\r
303 *\r
304 * DESCRIPTION\r
305 *       Returns a pointer to the MAD buffer associated with a MAD element.\r
306 *\r
307 * SYNOPSIS\r
308 */\r
309 #pragma warning(push)\r
310 #pragma warning(disable: 4244 ) \r
311 AL_INLINE void* AL_API\r
312 ib_get_mad_buf(\r
313         IN              const   ib_mad_element_t* const         p_mad_element )\r
314 {\r
315         CL_ASSERT( p_mad_element );\r
316         return( p_mad_element->p_mad_buf );\r
317 }\r
318 #pragma warning (pop)\r
319 /*\r
320 * PARAMETERS\r
321 *       p_mad_element\r
322 *               [in] A pointer to a MAD element.\r
323 *\r
324 * NOTES\r
325 *       Returns a pointer to the MAD buffer associated with a MAD element.\r
326 *\r
327 * SEE ALSO\r
328 *       ib_mad_element_t\r
329 *****/\r
330 \r
331 \r
332 /****f* Access Layer/ib_pfn_comp_cb_t\r
333 * NAME\r
334 *       ib_pfn_comp_cb_t\r
335 *\r
336 * DESCRIPTION\r
337 *       Completion callback provided by a client.\r
338 *\r
339 * SYNOPSIS\r
340 */\r
341 typedef void\r
342 (AL_API *ib_pfn_comp_cb_t)(\r
343         IN              const   ib_cq_handle_t                          h_cq,\r
344         IN                              void                                            *cq_context );\r
345 /*\r
346 * PARAMETERS\r
347 *       h_cq\r
348 *               [in] Handle for the completion queue on which the completion occurred.\r
349 *\r
350 *       cq_context\r
351 *               [in] User-specified context for the completion queue on which the\r
352 *               completion occurred.\r
353 *\r
354 * NOTES\r
355 *       This function is invoked upon completion of a work request on a queue pair\r
356 *       associated with the completion queue.  The context associated with the\r
357 *       completion queue on which the completion occurred is return to the client\r
358 *       through the callback.\r
359 *\r
360 *       In the kernel, this callback is usually invoked using a tasklet, dependent\r
361 *       on the implementation of the underlying verbs provider driver.\r
362 *****/\r
363 \r
364 \r
365 /****d* Access Layer/ib_al_flags_t\r
366 * NAME\r
367 *       ib_al_flags_t\r
368 *\r
369 * DESCRIPTION\r
370 *       Access layer flags used to direct the operation of various calls.\r
371 *\r
372 * SYNOPSIS\r
373 */\r
374 typedef uint32_t                                                        ib_al_flags_t;\r
375 #define IB_FLAGS_SYNC                                           0x00000001\r
376 /*\r
377 * VALUES\r
378 *       IB_FLAGS_SYNC\r
379 *               Indicates that the given operation should be performed synchronously.\r
380 *               The call will block until it completes.  Callbacks will still be\r
381 *               invoked.\r
382 *\r
383 * SEE ALSO\r
384 *       ib_cm_req_t, ib_cm_rep_t, ib_cm_dreq_t, ib_cm_lap_t,\r
385 *       ib_reg_svc_req_t, ib_mcast_req_t, ib_query_req_t, ib_sub_req_t\r
386 *****/\r
387 \r
388 \r
389 /****f* Access Layer/ib_pfn_destroy_cb_t\r
390 * NAME\r
391 *       ib_pfn_destroy_cb_t\r
392 *\r
393 * DESCRIPTION\r
394 *       Asynchronous callback invoked after a resource has been successfully\r
395 *       destroyed.\r
396 *\r
397 * SYNOPSIS\r
398 */\r
399 typedef void\r
400 (AL_API *ib_pfn_destroy_cb_t)(\r
401         IN                              void                                            *context );\r
402 /*\r
403 * PARAMETERS\r
404 *       context\r
405 *               [in] User-specified context associated with the resource being\r
406 *               destroyed.  The context for the resource is usually set during the\r
407 *               object's creation.\r
408 *\r
409 * NOTES\r
410 *       This callback notifies a client that a resource has been successfully\r
411 *       destroyed.  It is used to indicate that all pending callbacks associated\r
412 *       with the resource have completed, and no additional events will be\r
413 *       generated for that resource.\r
414 *\r
415 *       This callback is invoked within a system thread context in the kernel.\r
416 *\r
417 *       If the user specifies ib_sync_destroy as the asynchronous callback, then\r
418 *       the object being destroyed will be destroyed synchronously.  This may \r
419 *       result in the calling thread blocking while outstanding callbacks complete.\r
420 *\r
421 * SEE ALSO\r
422 *       ib_sync_destroy\r
423 *****/\r
424 \r
425 \r
426 \r
427 /****f* Access Layer/ib_sync_destroy\r
428 * NAME\r
429 *       ib_sync_destroy\r
430 *\r
431 * DESCRIPTION\r
432 *       Access layer routine used to indicate synchronous destruction of an\r
433 *       object.\r
434 *\r
435 * SYNOPSIS\r
436 */\r
437 static const ib_pfn_destroy_cb_t ib_sync_destroy = (ib_pfn_destroy_cb_t)(LONG_PTR)-1;\r
438 /*\r
439 * PARAMETERS\r
440 *       Not Applicable.\r
441 *\r
442 * NOTES\r
443 *       Users specify ib_sync_destroy as the ib_pfn_destroy_cb_t callback in order\r
444 *       to force synchronous object destruction.  This may result in the calling\r
445 *       thread blocking while outstanding callbacks complete.\r
446 *\r
447 * SEE ALSO\r
448 *       ib_pfn_destroy_cb_t\r
449 *****/\r
450 \r
451 \r
452 /****s* Access Layer/ib_async_event_rec_t\r
453 * NAME\r
454 *       ib_async_event_rec_t\r
455 *\r
456 * DESCRIPTION\r
457 *       Information returned when an asynchronous event occurs on an allocated\r
458 *       resource.\r
459 *\r
460 * SYNOPSIS\r
461 */\r
462 typedef struct _ib_async_event_rec\r
463 {\r
464         ib_async_event_t                                                        code;\r
465         uint64_t                                                                        vendor_specific;\r
466 \r
467         TO_LONG_PTR(void*,                                                      context);\r
468         union _handle_t\r
469         {\r
470                 TO_LONG_PTR(ib_ca_handle_t,                             h_ca);\r
471                 TO_LONG_PTR(ib_cq_handle_t,                             h_cq);\r
472                 TO_LONG_PTR(ib_qp_handle_t,                             h_qp);\r
473                 TO_LONG_PTR(struct _ib_srq*,                    h_srq);\r
474 \r
475         } handle;\r
476         \r
477         uint8_t                                                                         port_number;\r
478 \r
479 }       ib_async_event_rec_t;\r
480 /*\r
481 * FIELDS\r
482 *       code\r
483 *               A code that identifies the type of event being reported.\r
484 *\r
485 *       vendor_specific\r
486 *               A field containing optional vendor specific information.\r
487 *\r
488 *       context\r
489 *               User-defined context information associated with the resource on\r
490 *               which the error occurred.\r
491 *\r
492 *       handle\r
493 *               A handle to the resource for which this event record was generated.\r
494 *               This handle will match the handle returned during the creation of\r
495 *               resource.  It is provided in case an event occurs before a client's\r
496 *               call to create a resource can return.\r
497 *\r
498 * SEE ALSO\r
499 *       ib_async_event_t, ib_pfn_event_cb_t\r
500 *****/\r
501 \r
502 \r
503 /****f* Access Layer/ib_pfn_event_cb_t\r
504 * NAME\r
505 *       ib_pfn_event_cb_t\r
506 *\r
507 * DESCRIPTION\r
508 *       A user-specified callback that is invoked after an asynchronous event\r
509 *       has occurred on an allocated resource.\r
510 *\r
511 * SYNOPSIS\r
512 */\r
513 typedef void\r
514 (AL_API *ib_pfn_event_cb_t)(\r
515         IN                              ib_async_event_rec_t            *p_event_rec );\r
516 /*\r
517 * PARAMETERS\r
518 *       p_event_rec\r
519 *               [in] Information returned to the user, indicating the type of\r
520 *               event and the associated user context.\r
521 *\r
522 * NOTES\r
523 *       This callback is invoked within a system thread context in the kernel.\r
524 *\r
525 * SEE ALSO\r
526 *       ib_async_event_rec_t\r
527 *****/\r
528 \r
529 \r
530 /****f* Access Layer/ib_open_ca\r
531 * NAME\r
532 *       ib_open_ca\r
533 *\r
534 * DESCRIPTION\r
535 *       Opens a channel adapter for additional access.  A channel adapter must\r
536 *       be opened before consuming resources on that adapter.\r
537 *\r
538 * SYNOPSIS\r
539 */\r
540 AL_EXPORT ib_api_status_t AL_API\r
541 ib_open_ca(\r
542         IN              const   ib_al_handle_t                          h_al,\r
543         IN              const   ib_net64_t                                      ca_guid,\r
544         IN              const   ib_pfn_event_cb_t                       pfn_ca_event_cb OPTIONAL,\r
545         IN              const   void* const                                     ca_context,\r
546                 OUT                     ib_ca_handle_t* const           ph_ca );\r
547 /*\r
548 * PARAMETERS\r
549 *       h_al\r
550 *               [in] The handle to an open instance of AL.\r
551 *\r
552 *       ca_guid\r
553 *               [in] The GUID of the channel adapter to open.\r
554 *\r
555 *       pfn_ca_event_cb\r
556 *               [in] A user-specified callback that is invoked after an\r
557 *               asynchronous event has occurred on the channel adapter.\r
558 *\r
559 *       ca_context\r
560 *               [in] A client-specified context to associate with this opened instance\r
561 *               of the channel adapter.  This context is returned to the user when\r
562 *               invoking asynchronous callbacks referencing this channel adapter.\r
563 *\r
564 *       ph_ca\r
565 *               [out] Upon successful completion of this call, this references a\r
566 *               handle to the opened channel adapter.\r
567 *\r
568 * RETURN VALUES\r
569 *       IB_SUCCESS\r
570 *               The operation was successful.\r
571 *\r
572 *       IB_INVALID_AL_HANDLE\r
573 *               The access layer handle was invalid.\r
574 *\r
575 *       IB_INVALID_GUID\r
576 *               No channel adapter in the system was found for the specified ca_guid.\r
577 *\r
578 *       IB_INVALID_PARAMETER\r
579 *               A reference to the CA handle was not provided.\r
580 *\r
581 *       IB_INSUFFICIENT_MEMORY\r
582 *               There was insufficient memory to open the channel adapter.\r
583 *\r
584 * NOTES\r
585 *       When successful, this routine returns a handle to an open instance of a CA.\r
586 *\r
587 * SEE ALSO\r
588 *       ib_query_ca, ib_modify_ca, ib_close_ca, ib_pfn_event_cb_t\r
589 *****/\r
590 \r
591 \r
592 /****f* Access Layer/ib_query_ca\r
593 * NAME\r
594 *       ib_query_ca\r
595 *\r
596 * DESCRIPTION\r
597 *       Queries the attributes of an opened channel adapter.\r
598 *\r
599 * SYNOPSIS\r
600 */\r
601 AL_EXPORT ib_api_status_t AL_API\r
602 ib_query_ca(\r
603         IN              const   ib_ca_handle_t                          h_ca,\r
604                 OUT                     ib_ca_attr_t* const                     p_ca_attr OPTIONAL,\r
605         IN      OUT                     uint32_t* const                         p_size );\r
606 /*\r
607 * PARAMETERS\r
608 *       h_ca\r
609 *               [in] The handle to an open channel adapter.\r
610 *\r
611 *       p_ca_attr\r
612 *               [out] A reference to a buffer where the channel adapter attributes,\r
613 *               including port attribute information will be copied.  If this parameter\r
614 *               is NULL, then the required buffer size needed to return all of the CA\r
615 *               attribute information is returned through the p_size parameter.  The\r
616 *               ib_ca_attr_t structure for the specified channel adapter is stored\r
617 *               at the top of the buffer.\r
618 *\r
619 *       p_size\r
620 *               [in/out] On input, this references the size of the data buffer\r
621 *               referenced by the p_ca_attr parameter.\r
622 *\r
623 *               On output, the number of bytes used or needed to copy all CA\r
624 *               attribute information.\r
625 *\r
626 * RETURN VALUES\r
627 *       IB_SUCCESS\r
628 *               The attributes were returned successfully.\r
629 *\r
630 *       IB_INVALID_CA_HANDLE\r
631 *               The channel adapter handle was invalid.\r
632 *\r
633 *       IB_INSUFFICIENT_MEMORY\r
634 *               The size of the p_ca_attr buffer, specified through p_size, is\r
635 *               insufficient to store all of the CA attribute information.\r
636 *\r
637 *       IB_INVALID_PARAMETER\r
638 *               A reference to the size was not provided.\r
639 *\r
640 * NOTES\r
641 *       This routine returns information about the specified channel adapter,\r
642 *       including port attributes.  The amount of information returned through\r
643 *       this call is variable sized.  Users may obtain the size of the data\r
644 *       buffer required to obtain the CA attributes by calling this function\r
645 *       with p_ca_attr set to NULL.  The access layer will then return the\r
646 *       necessary size in the variable referenced by the p_size parameter.\r
647 *\r
648 * SEE ALSO\r
649 *       ib_open_ca, ib_query_ca_by_guid, ib_modify_ca, ib_close_ca, ib_ca_attr_t\r
650 *****/\r
651 \r
652 \r
653 /****f* Access Layer/ib_query_ca_by_guid\r
654 * NAME\r
655 *       ib_query_ca_by_guid\r
656 *\r
657 * DESCRIPTION\r
658 *       Queries the attributes of an opened channel adapter.\r
659 *\r
660 * SYNOPSIS\r
661 */\r
662 AL_EXPORT ib_api_status_t AL_API\r
663 ib_query_ca_by_guid(\r
664         IN              const   ib_al_handle_t                          h_al,\r
665         IN              const   ib_net64_t                                      ca_guid,\r
666                 OUT                     ib_ca_attr_t* const                     p_ca_attr OPTIONAL,\r
667         IN      OUT                     uint32_t* const                         p_size );\r
668 /*\r
669 * PARAMETERS\r
670 *       h_al\r
671 *               [in] The handle to an open instance of AL.\r
672 *\r
673 *       ca_guid\r
674 *               [in] The GUID of the channel adapter to query.\r
675 *\r
676 *       p_ca_attr\r
677 *               [out] A reference to a buffer where the channel adapter attributes,\r
678 *               including port attribute information will be copied.  If this parameter\r
679 *               is NULL, then the required buffer size needed to return all of the CA\r
680 *               attribute information is returned through the p_size parameter.  The\r
681 *               ib_ca_attr_t structure for the specified channel adapter is stored\r
682 *               at the top of the buffer.\r
683 *\r
684 *       p_size\r
685 *               [in/out] On input, this references the size of the data buffer\r
686 *               referenced by the p_ca_attr parameter.\r
687 *\r
688 *               On output, the number of bytes used or needed to copy all CA\r
689 *               attribute information.\r
690 *\r
691 * RETURN VALUES\r
692 *       IB_SUCCESS\r
693 *               The attributes were returned successfully.\r
694 *\r
695 *       IB_INVALID_AL_HANDLE\r
696 *               The access layer handle was invalid.\r
697 *\r
698 *       IB_INVALID_GUID\r
699 *               No channel adapter in the system was found for the specified ca_guid.\r
700 *\r
701 *       IB_INSUFFICIENT_MEMORY\r
702 *               The size of the p_ca_attr buffer, specified through p_size, is\r
703 *               insufficient to store all of the CA attribute information.\r
704 *\r
705 *       IB_INVALID_PARAMETER\r
706 *               A reference to the size was not provided.\r
707 *\r
708 * NOTES\r
709 *       This routine returns information about the specified channel adapter,\r
710 *       including port attributes.  The amount of information returned through\r
711 *       this call is variable sized.  Users may obtain the size of the data\r
712 *       buffer required to obtain the CA attributes by calling this function\r
713 *       with p_ca_attr set to NULL.  The access layer will then return the\r
714 *       necessary size in the variable referenced by the p_size parameter.\r
715 *\r
716 * SEE ALSO\r
717 *       ib_open_ca, ib_query_ca, ib_modify_ca, ib_close_ca, ib_ca_attr_t\r
718 *****/\r
719 \r
720 \r
721 /****f* Access Layer/ib_modify_ca\r
722 * NAME\r
723 *       ib_modify_ca\r
724 *\r
725 * DESCRIPTION\r
726 *       Modifies the attributes and violation counters associated with a port.\r
727 *\r
728 * SYNOPSIS\r
729 */\r
730 AL_EXPORT ib_api_status_t AL_API\r
731 ib_modify_ca(\r
732         IN              const   ib_ca_handle_t                          h_ca,\r
733         IN              const   uint8_t                                         port_num,\r
734         IN              const   ib_ca_mod_t                                     ca_mod,\r
735         IN              const   ib_port_attr_mod_t* const       p_port_attr_mod );\r
736 /*\r
737 * PARAMETERS\r
738 *       h_ca\r
739 *               [in] A handle to an opened channel adapter.\r
740 *\r
741 *       port_num\r
742 *               [in] An index to the port that is being modified.  The port_num matches\r
743 *               the index of the port as returned through the ib_query_ca call.\r
744 *\r
745 *       ca_mod\r
746 *               [in] A mask of the attributes and counters to modify.\r
747 *\r
748 *       p_port_attr_mod\r
749 *               [in] A list of the specific port attribute information to modify.  For\r
750 *               the access layer to modify an attribute, its corresponding bit must be\r
751 *               set in the ca_mod parameter.\r
752 *\r
753 * RETURN VALUES\r
754 *       IB_SUCCESS\r
755 *               The attributes were successfully modified.\r
756 *\r
757 *       IB_INVALID_CA_HANDLE\r
758 *               The channel adapter handle was invalid.\r
759 *\r
760 *       IB_INVALID_PORT\r
761 *               The port number supplied was invalid for the given channel adapter.\r
762 *\r
763 *       IB_INVALID_PARAMETER\r
764 *               The supplied ca_mod mask is invalid or a reference to the port\r
765 *               attribute information was not provided.\r
766 *\r
767 *       IB_UNSUPPORTED\r
768 *               The optional qkey and pkey violation counters are not supported by\r
769 *               this channel adapter, but an attempt was made to modify them.\r
770 *\r
771 * NOTES\r
772 *       This call sets the attributes for a port in its associated PORT_INFO\r
773 *       structure.  It will also reset pkey and qkey violation counters.\r
774 *\r
775 * SEE ALSO\r
776 *       ib_open_ca, ib_query_ca, ib_close_ca, ib_ca_mod_t, ib_port_attr_mod_t\r
777 *****/\r
778 \r
779 \r
780 /****f* Access Layer/ib_close_ca\r
781 * NAME\r
782 *       ib_close_ca\r
783 *\r
784 * DESCRIPTION\r
785 *       Closes an opened channel adapter.  Once closed, no further access to this\r
786 *       channel adapter is possible.\r
787 *\r
788 * SYNOPSIS\r
789 */\r
790 AL_EXPORT ib_api_status_t AL_API\r
791 ib_close_ca(\r
792         IN              const   ib_ca_handle_t                          h_ca,\r
793         IN              const   ib_pfn_destroy_cb_t                     pfn_destroy_cb OPTIONAL );\r
794 /*\r
795 * PARAMETERS\r
796 *       h_ca\r
797 *               [in] A handle to an opened channel adapter.\r
798 *\r
799 *       pfn_destroy_cb\r
800 *               [in] A user-specified callback that is invoked after the channel\r
801 *               adapter has been successfully destroyed.\r
802 *\r
803 * RETURN VALUES\r
804 *       IB_SUCCESS\r
805 *               The close request was registered.\r
806 *\r
807 *       IB_INVALID_CA_HANDLE\r
808 *               The channel adapter handle was invalid.\r
809 *\r
810 * NOTES\r
811 *       This call closes the opened channel adapter and frees all associated\r
812 *       resources, such as queue pairs, protection domains, and completion\r
813 *       queues.  Since callbacks may be outstanding against the channel adapter\r
814 *       or one of its resources at the time the close operation is invoked, this\r
815 *       call operates asynchronously.  The user will be notified through a callback\r
816 *       once the close operation completes, indicating that no additional callbacks\r
817 *       will be invoked for the specified channel adapter or a related resource.\r
818 *\r
819 * SEE ALSO\r
820 *       ib_open_ca\r
821 *****/\r
822 \r
823 \r
824 /****f* Access Layer/ib_alloc_pd\r
825 * NAME\r
826 *       ib_alloc_pd\r
827 *\r
828 * DESCRIPTION\r
829 *       Allocates a protection domain on the specified channel adapter.\r
830 *\r
831 * SYNOPSIS\r
832 */\r
833 AL_EXPORT ib_api_status_t AL_API\r
834 ib_alloc_pd(\r
835         IN              const   ib_ca_handle_t                          h_ca,\r
836         IN              const   ib_pd_type_t                            pd_type,\r
837         IN              const   void* const                                     pd_context,\r
838                 OUT                     ib_pd_handle_t* const           ph_pd );\r
839 /*\r
840 * PARAMETERS\r
841 *       h_ca\r
842 *               [in] A handle to an opened channel adapter.\r
843 *\r
844 *       pd_type\r
845 *               [in] Indicates the type of protection domain being created.\r
846 *\r
847 *       pd_context\r
848 *               [in] A client-specified context to associate with this allocated\r
849 *               protection domain.  This context is returned to the user when\r
850 *               invoking asynchronous callbacks referencing this protection domain.\r
851 *\r
852 *       ph_pd\r
853 *               [out] Upon successful completion of this call, this references a\r
854 *               handle to the allocated protection domain.\r
855 *\r
856 * RETURN VALUES\r
857 *       IB_SUCCESS\r
858 *               The operation was successful.\r
859 *\r
860 *       IB_INVALID_CA_HANDLE\r
861 *               The channel adapter handle was invalid.\r
862 *\r
863 *       IB_INVALID_PARAMETER\r
864 *               The supplied pd_type value is invalid or a reference to the protection\r
865 *               domain handle was not provided.\r
866 *\r
867 *       IB_INSUFFICIENT_MEMORY\r
868 *               There was insufficient memory to allocate the protection domain.\r
869 *\r
870 *       IB_INSUFFICIENT_RESOURCES\r
871 *               There were insufficient resources currently available on the channel\r
872 *               adapter to create the protection domain.\r
873 *\r
874 * NOTES\r
875 *       When successful, this routine returns a handle to a newly allocated\r
876 *       protection domain.\r
877 *\r
878 * SEE ALSO\r
879 *       ib_dealloc_pd, ib_pd_type_t\r
880 *****/\r
881 \r
882 \r
883 /****f* Access Layer/ib_dealloc_pd\r
884 * NAME\r
885 *       ib_dealloc_pd\r
886 *\r
887 * DESCRIPTION\r
888 *       Deallocates a protection domain.\r
889 *\r
890 * SYNOPSIS\r
891 */\r
892 AL_EXPORT ib_api_status_t AL_API\r
893 ib_dealloc_pd(\r
894         IN              const   ib_pd_handle_t                          h_pd,\r
895         IN              const   ib_pfn_destroy_cb_t                     pfn_destroy_cb OPTIONAL );\r
896 /*\r
897 * PARAMETERS\r
898 *       h_pd\r
899 *               [in] A handle to an allocated protection domain.\r
900 *\r
901 *       pfn_destroy_cb\r
902 *               [in] A user-specified callback that is invoked after the protection\r
903 *               domain has been successfully destroyed.\r
904 *\r
905 * RETURN VALUES\r
906 *       IB_SUCCESS\r
907 *               The operation was successful.\r
908 *\r
909 *       IB_INVALID_PD_HANDLE\r
910 *               The protection domain handle was invalid.\r
911 *\r
912 * NOTES\r
913 *       This call deallocates a protection domain and releases all associated\r
914 *       resources, including queue pairs and registered memory regions.  Since\r
915 *       callbacks may be outstanding against one of protection domain's related\r
916 *       resources at the time the deallocation call is invoked, this call operates\r
917 *       asynchronously.  The user will be notified through a callback once the\r
918 *       deallocation call completes, indicating that no additional callbacks\r
919 *       will be invoked for a related resource.\r
920 *\r
921 * SEE ALSO\r
922 *       ib_alloc_pd\r
923 *****/\r
924 \r
925 \r
926 /****f* Access Layer/ib_create_av\r
927 * NAME\r
928 *       ib_create_av\r
929 *\r
930 * DESCRIPTION\r
931 *       Creates an address vector.\r
932 *\r
933 * SYNOPSIS\r
934 */\r
935 AL_EXPORT ib_api_status_t AL_API\r
936 ib_create_av(\r
937         IN              const   ib_pd_handle_t                          h_pd,\r
938         IN              const   ib_av_attr_t* const                     p_av_attr,\r
939                 OUT                     ib_av_handle_t* const           ph_av );\r
940 /*\r
941 * PARAMETERS\r
942 *       h_pd\r
943 *               [in] A handle to an allocated protection domain that the address\r
944 *               vector will be associated with.\r
945 *\r
946 *       p_av_attr\r
947 *               [in] Attributes for the newly created address vector.\r
948 *\r
949 *       ph_av\r
950 *               [out] Upon successful completion of this call, this references a\r
951 *               handle to the newly created address vector.\r
952 *\r
953 * RETURN VALUES\r
954 *       IB_SUCCESS\r
955 *               The operation was successful.\r
956 *\r
957 *       IB_INVALID_PD_HANDLE\r
958 *               The protection domain handle was invalid.\r
959 *\r
960 *       IB_INVALID_PARAMETER\r
961 *               A reference to the address vector attributes or handle was not\r
962 *               provided.\r
963 *\r
964 *       IB_INSUFFICIENT_MEMORY\r
965 *               There was insufficient memory to create the address vector.\r
966 *\r
967 *       IB_INVALID_PORT\r
968 *               The port number supplied, through the address vector attributes,\r
969 *               was invalid for the given channel adapter.\r
970 *\r
971 *       IB_INSUFFICIENT_RESOURCES\r
972 *               There were insufficient resources currently available on the channel\r
973 *               adapter to create the address vector.\r
974 *\r
975 * NOTES\r
976 *       This routine creates an address vector.  Clients specify the attributes\r
977 *       of the address vector through the p_av_attr parameter.\r
978 *\r
979 * SEE ALSO\r
980 *       ib_query_av, ib_modify_av, ib_destroy_av\r
981 *****/\r
982 \r
983 \r
984 /****f* Access Layer/ib_query_av\r
985 * NAME\r
986 *       ib_query_av\r
987 *\r
988 * DESCRIPTION\r
989 *       Returns the attributes of an address vector.\r
990 *\r
991 * SYNOPSIS\r
992 */\r
993 AL_EXPORT ib_api_status_t AL_API\r
994 ib_query_av(\r
995         IN              const   ib_av_handle_t                          h_av,\r
996                 OUT                     ib_av_attr_t* const                     p_av_attr,\r
997                 OUT                     ib_pd_handle_t* const           ph_pd );\r
998 /*\r
999 * PARAMETERS\r
1000 *       h_av\r
1001 *               [in] A handle to an existing address vector.\r
1002 *\r
1003 *       p_av_attr\r
1004 *               [out] Upon successful completion, the structure referenced by this\r
1005 *               parameter contains the attributes of the specified address vector.\r
1006 *\r
1007 *       ph_pd\r
1008 *               [out] Upon successful completion, this references a handle to the\r
1009 *               protection domain associated with the address vector.\r
1010 *\r
1011 * RETURN VALUES\r
1012 *       IB_SUCCESS\r
1013 *               The attributes were returned successfully.\r
1014 *\r
1015 *       IB_INVALID_AV_HANDLE\r
1016 *               The address vector handle was invalid.\r
1017 *\r
1018 *       IB_INVALID_PARAMETER\r
1019 *               A reference to the address vector attributes structure or protection\r
1020 *               domain handle was not provided.\r
1021 *\r
1022 * SEE ALSO\r
1023 *       ib_create_av, ib_modify_av, ib_destroy_av, ib_av_attr_t\r
1024 *****/\r
1025 \r
1026 \r
1027 /****f* Access Layer/ib_modify_av\r
1028 * NAME\r
1029 *       ib_modify_av\r
1030 *\r
1031 * DESCRIPTION\r
1032 *       Modifies the attributes of an existing address vector.\r
1033 *\r
1034 * SYNOPSIS\r
1035 */\r
1036 AL_EXPORT ib_api_status_t AL_API\r
1037 ib_modify_av(\r
1038         IN              const   ib_av_handle_t                          h_av,\r
1039         IN              const   ib_av_attr_t* const                     p_av_attr );\r
1040 /*\r
1041 * PARAMETERS\r
1042 *       h_av\r
1043 *               [in] A handle to an existing address vector.\r
1044 *\r
1045 *       p_av_attr\r
1046 *               [in] The new attributes to use when modifying the address vector.\r
1047 *\r
1048 * RETURN VALUES\r
1049 *       IB_SUCCESS\r
1050 *               The address vector was successfully modified.\r
1051 *\r
1052 *       IB_INVALID_AV_HANDLE\r
1053 *               The address vector handle was invalid.\r
1054 *\r
1055 *       IB_INVALID_PARAMETER\r
1056 *               A reference to the address vector attributes structure was not\r
1057 *               provided.\r
1058 *\r
1059 *       IB_INVALID_PORT\r
1060 *               The port number supplied, through the address vector attributes,\r
1061 *               was invalid for the given channel adapter.\r
1062 *\r
1063 * NOTES\r
1064 *       This routine modifies the attributes of an existing address vector.\r
1065 *       The new attributes are specified through the p_av_attr parameter.\r
1066 *\r
1067 * SEE ALSO\r
1068 *       ib_create_av, ib_destroy_av\r
1069 *****/\r
1070 \r
1071 \r
1072 /****f* Access Layer/ib_destroy_av\r
1073 * NAME\r
1074 *       ib_destroy_av\r
1075 *\r
1076 * DESCRIPTION\r
1077 *       Destroys an existing address vector.\r
1078 *\r
1079 * SYNOPSIS\r
1080 */\r
1081 AL_EXPORT ib_api_status_t AL_API\r
1082 ib_destroy_av(\r
1083         IN              const   ib_av_handle_t                          h_av );\r
1084 /*\r
1085 * PARAMETERS\r
1086 *       h_av\r
1087 *               [in] A handle to an existing address vector.\r
1088 *\r
1089 * RETURN VALUES\r
1090 *       IB_SUCCESS\r
1091 *               The address vector was successfully destroyed.\r
1092 *\r
1093 *       IB_INVALID_AV_HANDLE\r
1094 *               The address vector handle was invalid.\r
1095 *\r
1096 * NOTES\r
1097 *       This routine destroys an existing address vector.\r
1098 *\r
1099 * SEE ALSO\r
1100 *       ib_create_av\r
1101 *****/\r
1102 \r
1103 \r
1104 /****f* Access Layer/ib_create_srq\r
1105 * NAME\r
1106 *       ib_create_srq\r
1107 *\r
1108 * DESCRIPTION\r
1109 *       Creates a shared receive queue and returns its handle to the user.\r
1110 *\r
1111 * SYNOPSIS\r
1112 */\r
1113 AL_EXPORT ib_api_status_t AL_API\r
1114 ib_create_srq(\r
1115         IN              const   ib_pd_handle_t                  h_pd,\r
1116         IN              const   ib_srq_attr_t* const            p_srq_attr,\r
1117         IN              const   void* const                             srq_context,\r
1118         IN              const   ib_pfn_event_cb_t                       pfn_srq_event_cb OPTIONAL,\r
1119                 OUT             ib_srq_handle_t* const          ph_srq );\r
1120 /*\r
1121 * PARAMETERS\r
1122 *       h_pd\r
1123 *               [in] This is a handle to a protection domain associated with the shared queue\r
1124 *               pair.\r
1125 *\r
1126 *       p_srq_attr\r
1127 *               [in] Attributes necessary to allocate and initialize a shared receive queue.\r
1128 *\r
1129 *       srq_context\r
1130 *               [in] A user-specified context information associated with the shared\r
1131 *               receive queue.\r
1132 *\r
1133 *       pfn_qp_event_cb\r
1134 *               [in] User-specified error callback routine invoked after an\r
1135 *               asynchronous event has occurred on the shared receive queue.\r
1136 *\r
1137 *       ph_srq\r
1138 *               [out] Upon successful completion of this call, this references a\r
1139 *               handle to the newly created shared receive queue.\r
1140 *\r
1141 * RETURN VALUES\r
1142 *       IB_SUCCESS\r
1143 *               The receive queue was successfully created.\r
1144 *\r
1145 *       IB_INVALID_PD_HANDLE\r
1146 *               The protection domain to associate with the shared receive queue was invalid.\r
1147 *\r
1148 *       IB_INVALID_PARAMETER\r
1149 *               A reference to the shared receive queue attributes or handle was not provided.\r
1150 *\r
1151 *       IB_INSUFFICIENT_MEMORY\r
1152 *               There was insufficient memory to create the shared receive queue.\r
1153 *\r
1154 *       IB_INSUFFICIENT_RESOURCES\r
1155 *               There were insufficient resources currently available on the channel\r
1156 *               adapter to create the shared receive queue.\r
1157 *\r
1158 *       IB_INVALID_SETTING\r
1159 *               The specified shared receive queue creation attributes are invalid.\r
1160 *\r
1161 *       IB_INVALID_MAX_WRS\r
1162 *               The requested maximum send or receive work request depth could not be\r
1163 *               supported.\r
1164 *\r
1165 *       IB_INVALID_MAX_SGE\r
1166 *               The requested maximum number of scatter-gather entries for the send or\r
1167 *               receive queue could not be supported.\r
1168 *\r
1169 * NOTES\r
1170 *       This routine allocates a shared receive queue with the specified attributes.  If\r
1171 *       the shared receive queue cannot be allocated, an error is returned.  When creating\r
1172 *       the shared receive queue, users associate a context with the shared receive queue.  This\r
1173 *       context is returned to the user through the asynchronous event callback\r
1174 *       if an event occurs.\r
1175 *\r
1176 *       This routine is used to create receive queues, which work with QPs of type:\r
1177 *\r
1178 *       IB_QPT_RELIABLE_CONN\r
1179 *       IB_QPT_UNRELIABLE_CONN\r
1180 *       IB_QPT_UNRELIABLE_DGRM\r
1181 *\r
1182 * SEE ALSO\r
1183 *       ib_query_srq, ib_modify_srq, ib_destroy_srq, ib_srq_attr_t,\r
1184 *       ib_srq_attr_mask_t, ib_pfn_event_cb_t, ib_qp_attr_t\r
1185 *****/\r
1186 \r
1187 \r
1188 /****f* Access Layer/ib_query_srq\r
1189 * NAME\r
1190 *       ib_query_srq\r
1191 *\r
1192 * DESCRIPTION\r
1193 *       Query the current attributes of the shared receive queue.\r
1194 *\r
1195 * SYNOPSIS\r
1196 */\r
1197 AL_EXPORT ib_api_status_t AL_API\r
1198 ib_query_srq(\r
1199         IN              const   ib_srq_handle_t                         h_srq,\r
1200                 OUT                     ib_srq_attr_t* const                    p_srq_attr );\r
1201 /*\r
1202 * PARAMETERS\r
1203 *       h_srq\r
1204 *               [in] A handle to an existing shared receive queue.\r
1205 *\r
1206 *       p_srq_attr\r
1207 *               [out] Upon successful completion of this call, the structure\r
1208 *               referenced by this parameter contains the attributes of the specified\r
1209 *               quere pair.\r
1210 *\r
1211 * RETURN VALUES\r
1212 *       IB_SUCCESS\r
1213 *               The shared receive queue attributes were returned successfully.\r
1214 *\r
1215 *       IB_INVALID_SRQ_HANDLE\r
1216 *               The shared receive queue handle was invalid.\r
1217 *\r
1218 *       IB_INVALID_PARAMETER\r
1219 *               A reference to the shared receive queue attributes structure was not provided.\r
1220 *\r
1221 * NOTES\r
1222 *       This routine returns information about the specified shared receive queue.\r
1223 *\r
1224 * SEE ALSO\r
1225 *       ib_query_srq, ib_modify_srq, ib_destroy_srq, ib_srq_attr_t,\r
1226 *       ib_srq_attr_mask_t, ib_pfn_event_cb_t, ib_qp_attr_t\r
1227 *****/\r
1228 \r
1229 \r
1230 /****f* Access Layer/ib_modify_srq\r
1231 * NAME\r
1232 *       ib_modify_srq\r
1233 *\r
1234 * DESCRIPTION\r
1235 *       Modifies the attributes of an existing shared receive queue.\r
1236 *\r
1237 * SYNOPSIS\r
1238 */\r
1239 AL_EXPORT ib_api_status_t AL_API\r
1240 ib_modify_srq(\r
1241         IN              const   ib_srq_handle_t                 h_srq,\r
1242         IN              const   ib_srq_attr_t* const            p_srq_attr,\r
1243         IN              const   ib_srq_attr_mask_t                      srq_attr_mask );\r
1244 /*\r
1245 * PARAMETERS\r
1246 *       h_srq\r
1247 *               [in] A handle to an existing shared receive queue.\r
1248 *\r
1249 *       p_srq_attr\r
1250 *               [in] Attributes necessary to allocate and initialize a shared receive queue.\r
1251 *\r
1252 *       srq_attr_mask\r
1253 *               [in] Flags, indicating which fields in the previous structure are valid.\r
1254 *\r
1255 * RETURN VALUES\r
1256 *       IB_SUCCESS\r
1257 *               The shared receive queue was successfully modified.\r
1258 *\r
1259 *       IB_INVALID_SRQ_HANDLE\r
1260 *               The shared receive queue handle was invalid.\r
1261 *\r
1262 *       IB_INVALID_PARAMETER\r
1263 *               A reference to the shared receive queue attributes was not provided.\r
1264 *\r
1265 *       IB_INVALID_SETTING\r
1266 *               The specified shared receive queue attributes were invalid.\r
1267 *\r
1268 *       IB_UNSUPPORTED\r
1269 *               The required action is not supported yet.\r
1270 *\r
1271 *       IB_INSUFFICIENT_RESOURCES\r
1272 *               There were insufficient resources currently available on the channel\r
1273 *               adapter to register the modify the shared receive queue.\r
1274 *\r
1275 * NOTES\r
1276 *       This routine modifies the attributes of an existing shared receive queue and\r
1277 *       transitions it to a new state.  The new state and attributes are\r
1278 *       specified through the p_qp_mod parameter.  Upon successful completion,\r
1279 *       the shared receive queue is in the requested state.\r
1280 *\r
1281 * SEE ALSO\r
1282 *       ib_query_srq, ib_modify_srq, ib_destroy_srq, ib_srq_attr_t,\r
1283 *       ib_srq_attr_mask_t, ib_pfn_event_cb_t, ib_qp_attr_t\r
1284 *****/\r
1285 \r
1286 \r
1287 /****f* Access Layer/ib_destroy_srq\r
1288 * NAME\r
1289 *       ib_destroy_srq\r
1290 *\r
1291 * DESCRIPTION\r
1292 *       Release a shared receive queue.  Once destroyed, no further access to this\r
1293 *       shared receive queue is possible.\r
1294 *\r
1295 * SYNOPSIS\r
1296 */\r
1297 AL_EXPORT ib_api_status_t AL_API\r
1298 ib_destroy_srq(\r
1299         IN              const   ib_srq_handle_t                         h_srq,\r
1300         IN              const   ib_pfn_destroy_cb_t                     pfn_destroy_cb OPTIONAL );\r
1301 /*\r
1302 * PARAMETERS\r
1303 *       h_srq\r
1304 *               [in] A handle to an existing shared shared receive queue.\r
1305 *\r
1306 *       pfn_destroy_cb\r
1307 *               [in] A user-specified callback that is invoked after the shared receive queue\r
1308 *               has been successfully destroyed.\r
1309 *\r
1310 * RETURN VALUES\r
1311 *       IB_SUCCESS\r
1312 *               The destroy request was registered.\r
1313 *\r
1314 *       IB_INVALID_SRQ_HANDLE\r
1315 *               The shared receive queue handle was invalid.\r
1316 *\r
1317 *       IB_RESOURCE_BUSY\r
1318 *               There are QPs, bound to the shared receive queue\r
1319 *\r
1320 * NOTES\r
1321 *       This call destroys an existing shared receive queue.  Since callbacks may be\r
1322 *       outstanding against the shared receive queue at the time the destroy operation is\r
1323 *       invoked, then this call operates asynchronously.  The user will be notified\r
1324 *       through a callback once the destroy operation completes, indicating that\r
1325 *       no additional callbacks will be invoked for the specified shared receive queue.\r
1326 *\r
1327 * SEE ALSO\r
1328 *       ib_query_srq, ib_modify_srq, ib_destroy_srq, ib_srq_attr_t,\r
1329 *       ib_srq_attr_mask_t, ib_pfn_event_cb_t, ib_qp_attr_t\r
1330 *****/\r
1331 \r
1332 \r
1333 /****f* Access Layer/ib_post_srq_recv\r
1334 * NAME\r
1335 *       ib_post_srq_recv\r
1336 *\r
1337 * DESCRIPTION\r
1338 *       This routine posts a work request to the shared receive queue of a shared receive queue.\r
1339 *\r
1340 * SYNOPSIS\r
1341 */\r
1342 AL_EXPORT ib_api_status_t AL_API\r
1343 ib_post_srq_recv(\r
1344         IN              const   ib_srq_handle_t                         h_srq,\r
1345         IN                              ib_recv_wr_t* const                     p_recv_wr,\r
1346                 OUT                     ib_recv_wr_t                            **pp_recv_failure OPTIONAL );\r
1347 /*\r
1348 * PARAMETERS\r
1349 *       h_srq\r
1350 *               [in] The shared receive queue to which this work request is being submitted.\r
1351 *\r
1352 *       p_recv_wr\r
1353 *               [in] A reference to the head of the work request list.\r
1354 *\r
1355 *       pp_recv_failure\r
1356 *               [out] If the post receive operation failed, this references the work\r
1357 *               request in the p_recv_wr list where the first failure occurred.\r
1358 *               This parameter may be NULL if only a single work request is being\r
1359 *               posted to the QP.\r
1360 *\r
1361 * RETURN VALUES\r
1362 *       IB_SUCCESS\r
1363 *               All work requests were successfully posted.\r
1364 *\r
1365 *       IB_INVALID_QP_HANDLE\r
1366 *               The shared receive queue handle was invalid.\r
1367 *\r
1368 *       IB_INVALID_PARAMETER\r
1369 *               A reference to the receive work request list was not provided.\r
1370 *\r
1371 *       IB_INSUFFICIENT_RESOURCES\r
1372 *               The number of posted work requests exceed the current depth available\r
1373 *               on the receive queue.\r
1374 *\r
1375 *       IB_INVALID_WR_TYPE\r
1376 *               The work request type was invalid.\r
1377 *\r
1378 *       IB_INVALID_QP_STATE\r
1379 *               The current shared receive queue state does not allow posting receives.\r
1380 *\r
1381 * NOTES\r
1382 *       This routine posts a work request to the shared receive queue.\r
1383 *       The type of work to perform is defined by the p_recv_wr parameter.  This\r
1384 *       call is used to post data buffers to receive incoming message sends.\r
1385 *\r
1386 * SEE ALSO\r
1387 *       ib_recv_wr_t\r
1388 *****/\r
1389 \r
1390 \r
1391 /****f* Access Layer/ib_create_qp\r
1392 * NAME\r
1393 *       ib_create_qp\r
1394 *\r
1395 * DESCRIPTION\r
1396 *       Creates a queue pair and returns its handle to the user.\r
1397 *\r
1398 * SYNOPSIS\r
1399 */\r
1400 AL_EXPORT ib_api_status_t AL_API\r
1401 ib_create_qp(\r
1402         IN              const   ib_pd_handle_t                          h_pd,\r
1403         IN              const   ib_qp_create_t* const           p_qp_create,\r
1404         IN              const   void* const                                     qp_context,\r
1405         IN              const   ib_pfn_event_cb_t                       pfn_qp_event_cb OPTIONAL,\r
1406                 OUT                     ib_qp_handle_t* const           ph_qp );\r
1407 /*\r
1408 * PARAMETERS\r
1409 *       h_pd\r
1410 *               [in] This is a handle to a protection domain associated with the queue\r
1411 *               pair.\r
1412 *\r
1413 *       p_qp_create\r
1414 *               [in] Attributes necessary to allocate and initialize the queue pair.\r
1415 *\r
1416 *       qp_context\r
1417 *               [in] A user-specified context information associated with the\r
1418 *               queue pair.\r
1419 *\r
1420 *       pfn_qp_event_cb\r
1421 *               [in] User-specified error callback routine invoked after an\r
1422 *               asynchronous event has occurred on the queue pair.\r
1423 *\r
1424 *       ph_qp\r
1425 *               [out] Upon successful completion of this call, this references a\r
1426 *               handle to the newly created queue pair.\r
1427 *\r
1428 * RETURN VALUES\r
1429 *       IB_SUCCESS\r
1430 *               The queue pair was successfully created.\r
1431 *\r
1432 *       IB_INVALID_PD_HANDLE\r
1433 *               The protection domain to associate with the queue pair was invalid.\r
1434 *\r
1435 *       IB_INVALID_PARAMETER\r
1436 *               A reference to the queue pair attributes or handle was not provided.\r
1437 *\r
1438 *       IB_INSUFFICIENT_MEMORY\r
1439 *               There was insufficient memory to create the queue pair.\r
1440 *\r
1441 *       IB_INSUFFICIENT_RESOURCES\r
1442 *               There were insufficient resources currently available on the channel\r
1443 *               adapter to create the queue pair.\r
1444 *\r
1445 *       IB_INVALID_CQ_HANDLE\r
1446 *               The send or receive completion queue to associate with the queue pair\r
1447 *               was invalid.\r
1448 *\r
1449 *       IB_INVALID_SRQ_HANDLE\r
1450 *               The shared receive queue to be associated with the queue pair\r
1451 *               was invalid.\r
1452 *\r
1453 *       IB_INVALID_SETTING\r
1454 *               The specified queue pair creation attributes are invalid.\r
1455 *\r
1456 *       IB_UNSUPPORTED\r
1457 *               The specified queue pair type was not supported by the channel adapter.\r
1458 *\r
1459 *       IB_INVALID_MAX_WRS\r
1460 *               The requested maximum send or receive work request depth could not be\r
1461 *               supported.\r
1462 *\r
1463 *       IB_INVALID_MAX_SGE\r
1464 *               The requested maximum number of scatter-gather entries for the send or\r
1465 *               receive queue could not be supported.\r
1466 *\r
1467 * NOTES\r
1468 *       1. This routine allocates a queue pair with the specified attributes.  If\r
1469 *       the queue pair cannot be allocated, an error is returned.  When creating\r
1470 *       the queue pair, users associate a context with the queue pair.  This\r
1471 *       context is returned to the user through the asynchronous event callback\r
1472 *       if an event occurs.\r
1473 *\r
1474 *       2. For QPs that are associated with an SRQ, the Consumer should take\r
1475 *       the QP through the Error State before invoking a Destroy QP or a Modify\r
1476 *       QP to the Reset State. The Consumer may invoke the Destroy QP without\r
1477 *       first performing a Modify QP to the Error State and waiting for the Affiliated \r
1478 *       Asynchronous Last WQE Reached Event. However, if the Consumer\r
1479 *       does not wait for the Affiliated Asynchronous Last WQE Reached Event,\r
1480 *       then WQE and Data Segment leakage may occur.\r
1481 *\r
1482 *       3. This routine is used to create queue pairs of type:\r
1483 *               IB_QPT_RELIABLE_CONN\r
1484 *               IB_QPT_UNRELIABLE_CONN\r
1485 *               IB_QPT_UNRELIABLE_DGRM\r
1486 *               IB_QPT_MAD\r
1487 *\r
1488 *       4. Callers of ib_create_qp should call ib_init_dgrm_svc if the queue pair\r
1489 *       is of type IB_QPT_UNRELIABLE_DGRM or IB_QPT_MAD before sending or\r
1490 *       receiving data.  IB_QPT_RELIABLE_CONN, IB_QPT_UNRELIABLE_CONN type\r
1491 *       queue pairs should be used by the connection establishment process\r
1492 *       before data may be sent or received on the QP.\r
1493 *\r
1494 *       This call does not return the QP attributes as MAD QPs do not support\r
1495 *       such an operation.  This is a minor specification deviation.\r
1496 *\r
1497 * SEE ALSO\r
1498 *       ib_query_qp, ib_modify_qp, ib_destroy_qp, ib_cm_req, ib_cm_rep, ib_cm_rtu\r
1499 *       ib_init_dgrm_svc, ib_qp_create_t, ib_pfn_event_cb_t, ib_qp_attr_t\r
1500 *****/\r
1501 \r
1502 \r
1503 /****f* Access Layer/ib_get_spl_qp\r
1504 * NAME\r
1505 *       ib_get_spl_qp\r
1506 *\r
1507 * DESCRIPTION\r
1508 *       Create a special QP or QP alias.  This call provides access to queue\r
1509 *       pairs 0 and 1, and the raw queue pair types.\r
1510 *\r
1511 * SYNOPSIS\r
1512 */\r
1513 AL_EXPORT ib_api_status_t AL_API\r
1514 ib_get_spl_qp(\r
1515         IN              const   ib_pd_handle_t                          h_pd,\r
1516         IN              const   ib_net64_t                                      port_guid,\r
1517         IN              const   ib_qp_create_t* const           p_qp_create,\r
1518         IN              const   void* const                                     qp_context,\r
1519         IN              const   ib_pfn_event_cb_t                       pfn_qp_event_cb OPTIONAL,\r
1520                 OUT                     ib_pool_key_t* const            p_pool_key OPTIONAL,\r
1521                 OUT                     ib_qp_handle_t* const           ph_qp );\r
1522 /*\r
1523 * PARAMETERS\r
1524 *       h_pd\r
1525 *               [in] This is a handle to a protection domain associated with the queue\r
1526 *               pair.  This must be a protection domain alias for aliased QP types.\r
1527 *\r
1528 *       port_guid\r
1529 *               [in] The port GUID that the special QP will be associated with.\r
1530 *\r
1531 *       p_qp_create\r
1532 *               [in] Attributes necessary to allocate and initialize the queue pair.\r
1533 *\r
1534 *       qp_context\r
1535 *               [in] A user-specified context information associated with the\r
1536 *               queue pair.\r
1537 *\r
1538 *       pfn_qp_ervent_cb\r
1539 *               [in] User-specified error callback routine invoked after an\r
1540 *               asynchronous event has occurred on the queue pair.\r
1541 *\r
1542 *       p_pool_key\r
1543 *               [in] A key to a pool of MAD elements that are used to send MADs.\r
1544 *               This key is only valid for aliased QP types.\r
1545 *\r
1546 *       ph_qp\r
1547 *               [out] Upon successful completion of this call, this references a\r
1548 *               handle to the newly created queue pair.\r
1549 *\r
1550 * RETURN VALUES\r
1551 *       IB_SUCCESS\r
1552 *               The queue pair was successfully created.\r
1553 *\r
1554 *       IB_INVALID_PD_HANDLE\r
1555 *               The protection domain to associate with the queue pair was invalid.\r
1556 *\r
1557 *       IB_INVALID_PORT\r
1558 *               The port number supplied was invalid for the given channel adapter.\r
1559 *\r
1560 *       IB_INVALID_PARAMETER\r
1561 *               A reference to the queue pair attributes or handle was not provided.\r
1562 *\r
1563 *       IB_INVALID_PERMISSION\r
1564 *               The calling process does not have sufficient privilege to create the\r
1565 *               requested queue pair type.\r
1566 *\r
1567 *       IB_INSUFFICIENT_MEMORY\r
1568 *               There was insufficient memory to create the queue pair.\r
1569 *\r
1570 *       IB_INSUFFICIENT_RESOURCES\r
1571 *               There were insufficient resources currently available on the channel\r
1572 *               adapter to create the queue pair.\r
1573 *\r
1574 *       IB_INVALID_CQ_HANDLE\r
1575 *               The send or receive completion queue to associate with the queue pair\r
1576 *               was invalid.\r
1577 *\r
1578 *       IB_INVALID_SETTING\r
1579 *               The specified queue pair type was invalid.\r
1580 *\r
1581 *       IB_UNSUPPORTED\r
1582 *               The specified queue pair type was not supported by the channel adapter.\r
1583 *\r
1584 *       IB_INVALID_MAX_WRS\r
1585 *               The requested maximum send or receive work request depth could not be\r
1586 *               supported.\r
1587 *\r
1588 *       IB_INVALID_MAX_SGE\r
1589 *               The requested maximum number of scatter-gather entries for the send or\r
1590 *               receive queue could not be supported.\r
1591 *\r
1592 * NOTES\r
1593 *       This routine allocates a queue pair with the specified attributes.  If\r
1594 *       the queue pair cannot be allocated, an error is returned.  When creating\r
1595 *       the queue pair, users associate a context with the queue pair.  This\r
1596 *       context is returned to the user through the asynchronous event callback\r
1597 *       if an event occurs.\r
1598 *\r
1599 *       This routine is used to create queue pairs of type:\r
1600 *\r
1601 *       IB_QPT_QP0\r
1602 *       IB_QPT_QP1\r
1603 *       IB_QPT_RAW_IPV6\r
1604 *       IB_QPT_RAW_ETHER\r
1605 *       IB_QPT_QP0_ALIAS\r
1606 *       IB_QPT_QP1_ALIAS\r
1607 *\r
1608 *       Callers of ib_get_spl_qp should call ib_init_dgrm_svc if the queue pair is\r
1609 *       of type IB_QPT_QP0, IB_QPT_QP1, IB_QPT_RAW_IPV6, IB_QPT_RAW_ETHER before\r
1610 *       sending or receiving data.  MADs may be sent on aliased QPs on the\r
1611 *       successful return of this routine.\r
1612 *\r
1613 * SEE ALSO\r
1614 *       ib_query_qp, ib_modify_qp, ib_destroy_qp, ib_get_mad\r
1615 *       ib_init_dgrm_svc, ib_qp_create_t, ib_pfn_event_cb_t, ib_qp_attr_t\r
1616 *****/\r
1617 \r
1618 \r
1619 /****f* Access Layer/ib_query_qp\r
1620 * NAME\r
1621 *       ib_query_qp\r
1622 *\r
1623 * DESCRIPTION\r
1624 *       Query the current attributes of the queue pair.\r
1625 *\r
1626 * SYNOPSIS\r
1627 */\r
1628 AL_EXPORT ib_api_status_t AL_API\r
1629 ib_query_qp(\r
1630         IN              const   ib_qp_handle_t                          h_qp,\r
1631                 OUT                     ib_qp_attr_t* const                     p_qp_attr );\r
1632 /*\r
1633 * PARAMETERS\r
1634 *       h_qp\r
1635 *               [in] A handle to an existing queue pair.\r
1636 *\r
1637 *       p_qp_attr\r
1638 *               [out] Upon successful completion of this call, the structure\r
1639 *               referenced by this parameter contains the attributes of the specified\r
1640 *               quere pair.\r
1641 *\r
1642 * RETURN VALUES\r
1643 *       IB_SUCCESS\r
1644 *               The queue pair attributes were returned successfully.\r
1645 *\r
1646 *       IB_INVALID_QP_HANDLE\r
1647 *               The queue pair handle was invalid.\r
1648 *\r
1649 *       IB_INVALID_PARAMETER\r
1650 *               A reference to the queue pair attributes structure was not provided.\r
1651 *\r
1652 * NOTES\r
1653 *       This routine returns information about the specified queue pair.\r
1654 *\r
1655 * SEE ALSO\r
1656 *       ib_create_qp, ib_modify_qp, ib_qp_attr_t\r
1657 *****/\r
1658 \r
1659 \r
1660 /****f* Access Layer/ib_modify_qp\r
1661 * NAME\r
1662 *       ib_modify_qp\r
1663 *\r
1664 * DESCRIPTION\r
1665 *       Modifies the attributes of an existing queue pair.\r
1666 *\r
1667 * SYNOPSIS\r
1668 */\r
1669 AL_EXPORT ib_api_status_t AL_API\r
1670 ib_modify_qp(\r
1671         IN              const   ib_qp_handle_t                          h_qp,\r
1672         IN              const   ib_qp_mod_t* const                      p_qp_mod );\r
1673 /*\r
1674 * PARAMETERS\r
1675 *       h_qp\r
1676 *               [in] A handle to an existing queue pair.\r
1677 *\r
1678 *       p_qp_mod\r
1679 *               [in] The new attributes to use when modifying the queue pair.\r
1680 *\r
1681 * RETURN VALUES\r
1682 *       IB_SUCCESS\r
1683 *               The queue pair was successfully modified.\r
1684 *\r
1685 *       IB_INVALID_QP_HANDLE\r
1686 *               The queue pair handle was invalid.\r
1687 *\r
1688 *       IB_INVALID_PARAMETER\r
1689 *               A reference to the queue pair attributes was not provided.\r
1690 *\r
1691 *       IB_INVALID_SETTING\r
1692 *               The specified queue pair attributes were invalid.\r
1693 *\r
1694 *       IB_INSUFFICIENT_RESOURCES\r
1695 *               There were insufficient resources currently available on the channel\r
1696 *               adapter to register the modify the queue pair.\r
1697 *\r
1698 *       IB_UNSUPPORTED\r
1699 *               The requested modification was not supported.\r
1700 *\r
1701 *       IB_INVALID_QP_STATE\r
1702 *               The queue pair was in an invalid state for the requested operation.\r
1703 *\r
1704 *       IB_INVALID_PKEY\r
1705 *               The specified pkey was not valid.\r
1706 *\r
1707 *       IB_INVALID_APM_STATE\r
1708 *               The specified automatic path migration state was not valid.\r
1709 *\r
1710 * NOTES\r
1711 *       This routine modifies the attributes of an existing queue pair and\r
1712 *       transitions it to a new state.  The new state and attributes are\r
1713 *       specified through the p_qp_mod parameter.  Upon successful completion,\r
1714 *       the queue pair is in the requested state.\r
1715 *\r
1716 * SEE ALSO\r
1717 *       ib_create_qp, ib_destroy_qp, ib_qp_mod_t\r
1718 *****/\r
1719 \r
1720 \r
1721 /****f* Access Layer/ib_destroy_qp\r
1722 * NAME\r
1723 *       ib_destroy_qp\r
1724 *\r
1725 * DESCRIPTION\r
1726 *       Release a queue pair.  Once destroyed, no further access to this\r
1727 *       queue pair is possible.\r
1728 *\r
1729 * SYNOPSIS\r
1730 */\r
1731 AL_EXPORT ib_api_status_t AL_API\r
1732 ib_destroy_qp(\r
1733         IN              const   ib_qp_handle_t                          h_qp,\r
1734         IN              const   ib_pfn_destroy_cb_t                     pfn_destroy_cb OPTIONAL );\r
1735 /*\r
1736 * PARAMETERS\r
1737 *       h_qp\r
1738 *               [in] A handle to an existing queue pair.\r
1739 *\r
1740 *       pfn_destroy_cb\r
1741 *               [in] A user-specified callback that is invoked after the queue pair\r
1742 *               has been successfully destroyed.\r
1743 *\r
1744 * RETURN VALUES\r
1745 *       IB_SUCCESS\r
1746 *               The destroy request was registered.\r
1747 *\r
1748 *       IB_INVALID_QP_HANDLE\r
1749 *               The queue pair handle was invalid.\r
1750 *\r
1751 * NOTES\r
1752 *       This call destroys an existing queue pair.  Since callbacks may be\r
1753 *       outstanding against the queue pair at the time the destroy operation is\r
1754 *       invoked, the this call operates asynchronously.  The user will be notified\r
1755 *       through a callback once the destroy operation completes, indicating that\r
1756 *       no additional callbacks will be invoked for the specified queue pair.\r
1757 *\r
1758 * SEE ALSO\r
1759 *       ib_create_qp\r
1760 *****/\r
1761 \r
1762 \r
1763 /****s* Access Layer/ib_cq_create_t\r
1764 * NAME\r
1765 *       ib_cq_create_t\r
1766 *\r
1767 * DESCRIPTION\r
1768 *       Attributes used to initialize a completion queue at creation time.\r
1769 *\r
1770 * SYNOPSIS\r
1771 */\r
1772 typedef struct _ib_cq_create\r
1773 {\r
1774         uint32_t                                                                size;\r
1775         ib_pfn_comp_cb_t                                                pfn_comp_cb;\r
1776         cl_waitobj_handle_t                                             h_wait_obj;\r
1777 \r
1778 }       ib_cq_create_t;\r
1779 /*\r
1780 * FIELDS\r
1781 *       size\r
1782 *               Specifies the maximum number of work completions that may be on the\r
1783 *               completion queue.  If the creation call is successful, the actual\r
1784 *               size of the completion queue will be returned.  The actual size of\r
1785 *               the CQ will be greater than or equal to the requested size.\r
1786 *\r
1787 *       pfn_comp_cb\r
1788 *               A callback that is invoked whenever a signaled completion occurs on\r
1789 *               the completion queue.  This field is mutually exclusive with the\r
1790 *               p_event field.\r
1791 *\r
1792 *       h_wait_obj\r
1793 *               A wait object that is triggered whenever a signaled completion occurs\r
1794 *               on the completion queue.  This field is mutually exclusive with the\r
1795 *               pfn_comp_cb field and is only valid for user-mode clients.  The wait\r
1796 *               object must be ready for use when the call to ib_create_cq is invoked.\r
1797 *\r
1798 * NOTES\r
1799 *       Clients must specify either an event or a callback when creating a\r
1800 *       completion queue.  When a signaled completion occurs on the completion\r
1801 *       queue, the client will be notified through the callback or by\r
1802 *       signaling the specified event.\r
1803 *\r
1804 * SEE ALSO\r
1805 *       ib_create_cq, ib_pfn_comp_cb_t\r
1806 *****/\r
1807 \r
1808 \r
1809 /****f* Access Layer/ib_create_cq\r
1810 * NAME\r
1811 *       ib_create_cq\r
1812 *\r
1813 * DESCRIPTION\r
1814 *       Creates a completion queue and returns its handle to the user.\r
1815 *\r
1816 * SYNOPSIS\r
1817 */\r
1818 AL_EXPORT ib_api_status_t AL_API\r
1819 ib_create_cq(\r
1820         IN              const   ib_ca_handle_t                          h_ca,\r
1821         IN      OUT                     ib_cq_create_t* const           p_cq_create,\r
1822         IN              const   void* const                                     cq_context,\r
1823         IN              const   ib_pfn_event_cb_t                       pfn_cq_event_cb OPTIONAL,\r
1824                 OUT                     ib_cq_handle_t* const           ph_cq );\r
1825 /*\r
1826 * PARAMETERS\r
1827 *       h_ca\r
1828 *               [in] A handle to an open channel adapter.\r
1829 *\r
1830 *       p_cq_create\r
1831 *               [in] Attributes necessary to allocate and initialize the\r
1832 *               completion queue.\r
1833 *\r
1834 *       cq_context\r
1835 *               [in] A user-specified context associated with the completion queue.\r
1836 *\r
1837 *       pfn_cq_event_cb\r
1838 *               [in] User-specified error callback routine invoked after an\r
1839 *               asynchronous event has occurred on the completion queue.\r
1840 *\r
1841 *       ph_cq\r
1842 *               [out] Upon successful completion of this call, this references a\r
1843 *               handle to the newly created completion queue.\r
1844 *\r
1845 * RETURN VALUES\r
1846 *       IB_SUCCESS\r
1847 *               The completion queue was successfully created.\r
1848 *\r
1849 *       IB_INVALID_CA_HANDLE\r
1850 *               The channel adapter handle was invalid.\r
1851 *\r
1852 *       IB_INVALID_PARAMETER\r
1853 *               A reference to the completion queue attributes or handle was not\r
1854 *               provided.\r
1855 *\r
1856 *       IB_INVALID_SETTING\r
1857 *               The specified attributes that should be used to create the completion\r
1858 *               queue are invalid.  Both completion callback and wait object\r
1859 *               information were supplied or are missing.\r
1860 *\r
1861 *       IB_INSUFFICIENT_MEMORY\r
1862 *               There was insufficient memory to create the completion queue.\r
1863 *\r
1864 *       IB_INSUFFICIENT_RESOURCES\r
1865 *               There were insufficient resources currently available on the channel\r
1866 *               adapter to create the completion queue.\r
1867 *\r
1868 *       IB_INVALID_CQ_SIZE\r
1869 *               The requested size of the completion queue was larger than the\r
1870 *               maximum supported by the associated channel adapter.\r
1871 *\r
1872 * NOTES\r
1873 *       This routine allocates a completion queue on the specified channel\r
1874 *       adapter.  If the completion queue cannot be allocated, an error is\r
1875 *       returned.  When creating the completion queue, users associate a context\r
1876 *       with the completion queue.  This context is returned to the user through\r
1877 *       the completion and asynchronous event callbacks.\r
1878 *\r
1879 * SEE ALSO\r
1880 *       ib_query_cq, ib_modify_cq, ib_destroy_cq, ib_cq_create_t, ib_pfn_event_cb_t\r
1881 *****/\r
1882 \r
1883 \r
1884 /****f* Access Layer/ib_modify_cq\r
1885 * NAME\r
1886 *       ib_modify_cq\r
1887 *\r
1888 * DESCRIPTION\r
1889 *       Modifies the attributes associated with a completion queue, allowing the\r
1890 *       completion queue to be resized.\r
1891 *\r
1892 * SYNOPSIS\r
1893 */\r
1894 AL_EXPORT ib_api_status_t AL_API\r
1895 ib_modify_cq(\r
1896         IN              const   ib_cq_handle_t                          h_cq,\r
1897         IN      OUT                     uint32_t* const                         p_size );\r
1898 /*\r
1899 * PARAMETERS\r
1900 *       h_cq\r
1901 *               [in] A handle to an existing completion queue.\r
1902 *\r
1903 *       p_size\r
1904 *               [in/out] Specifies the new size of the completion queue.  If the\r
1905 *               modify call is successful, the actual size of the completion queue\r
1906 *               will be returned.  The actual size of the CQ will be greater than or\r
1907 *               equal to the requested size.\r
1908 *\r
1909 * RETURN VALUES\r
1910 *       IB_SUCCESS\r
1911 *               The completion queue was successfully modified.\r
1912 *\r
1913 *       IB_INVALID_CQ_HANDLE\r
1914 *               The completion queue handle was invalid.\r
1915 *\r
1916 *       IB_INVALID_PARAMETER\r
1917 *               A reference to the completion queue size was not provided.\r
1918 *\r
1919 *       IB_INVALID_CQ_SIZE\r
1920 *               The requested size of the completion queue was larger than the\r
1921 *               maximum supported by the associated channel adapter.\r
1922 *\r
1923 *       IB_OVERFLOW\r
1924 *               The specified size of the completion queue is smaller than the number\r
1925 *               of work completions currently on the completion queue.\r
1926 *\r
1927 *       IB_INSUFFICIENT_MEMORY\r
1928 *               There was insufficient memory to modify the completion queue.\r
1929 *\r
1930 * NOTES\r
1931 *       This routine allows a client to modify the size of a completion queue.\r
1932 *       If the new size is larger than what the associated channel adapter can\r
1933 *       support, an error is returned.  If the completion queue has valid\r
1934 *       completion entries on it and the requested size is smaller than the\r
1935 *       number of entries, an overflow error is returned and the modify\r
1936 *       operation is aborted.\r
1937 *\r
1938 * SEE ALSO\r
1939 *       ib_create_cq\r
1940 *****/\r
1941 \r
1942 \r
1943 /****f* Access Layer/ib_query_cq\r
1944 * NAME\r
1945 *       ib_query_cq\r
1946 *\r
1947 * DESCRIPTION\r
1948 *       Returns information about the specified completion queue.\r
1949 *\r
1950 * SYNOPSIS\r
1951 */\r
1952 AL_EXPORT ib_api_status_t AL_API\r
1953 ib_query_cq(\r
1954         IN              const   ib_cq_handle_t          h_cq,\r
1955         OUT             uint32_t* const                         p_size );\r
1956 /*\r
1957 * PARAMETERS\r
1958 *       h_cq\r
1959 *               [in] A handle to an existing completion queue.\r
1960 *\r
1961 *       p_size\r
1962 *               [out] Upon successful completion of this call, contains the actual\r
1963 *               size of the completion queue.\r
1964 *\r
1965 * RETURN VALUES\r
1966 *       IB_SUCCESS\r
1967 *               The completion queue was successfully queried.\r
1968 *\r
1969 *       IB_INVALID_CQ_HANDLE\r
1970 *               The completion queue handle was invalid.\r
1971 *\r
1972 *       IB_INVALID_PARAMETER\r
1973 *               A reference to the completion queue size was not provided.\r
1974 *\r
1975 * SEE ALSO\r
1976 *       ib_create_cq\r
1977 *****/\r
1978 \r
1979 \r
1980 /****f* Access Layer/ib_destroy_cq\r
1981 * NAME\r
1982 *       ib_destroy_cq\r
1983 *\r
1984 * DESCRIPTION\r
1985 *       Destroys a completion queue.  Once destroyed, no further access to the\r
1986 *       completion queue is possible.\r
1987 *\r
1988 * SYNOPSIS\r
1989 */\r
1990 AL_EXPORT ib_api_status_t AL_API\r
1991 ib_destroy_cq(\r
1992         IN              const   ib_cq_handle_t                          h_cq,\r
1993         IN              const   ib_pfn_destroy_cb_t                     pfn_destroy_cb OPTIONAL );\r
1994 /*\r
1995 * PARAMETERS\r
1996 *       h_qp\r
1997 *               [in] A handle to an existing completion queue.\r
1998 *\r
1999 *       pfn_destroy_cb\r
2000 *               [in] A user-provided callback that is invoked after the\r
2001 *               completion queue has been successfully destroyed.\r
2002 *\r
2003 * RETURN VALUES\r
2004 *       IB_SUCCESS\r
2005 *               The destroy request was registered.\r
2006 *\r
2007 *       IB_INVALID_CQ_HANDLE\r
2008 *               The completion queue handle was invalid.\r
2009 *\r
2010 * NOTES\r
2011 *       This call destroys an existing completion queue.  Since callbacks may be\r
2012 *       outstanding against the completion queue at the time the destroy operation\r
2013 *       is invoked, the this call operates asynchronously.  The user will be\r
2014 *       notified through a callback once the destroy operation completes,\r
2015 *       indicating that no additional callbacks will be invoked for the specified\r
2016 *       completion queue.\r
2017 *\r
2018 *       If there are still queue pairs associated with the completion queue when\r
2019 *       this function is invoked, the destroy operation will fail with status\r
2020 *       IB_RESOURCE_BUSY.\r
2021 *\r
2022 * SEE ALSO\r
2023 *       ib_create_cq, ib_pfn_destroy_cb_t\r
2024 *****/\r
2025 \r
2026 \r
2027 /****f* Access Layer/ib_reg_mem\r
2028 * NAME\r
2029 *       ib_reg_mem\r
2030 *\r
2031 * DESCRIPTION\r
2032 *       Registers a virtual memory region with a channel adapter.\r
2033 *\r
2034 * SYNOPSIS\r
2035 */\r
2036 AL_EXPORT ib_api_status_t AL_API\r
2037 ib_reg_mem(\r
2038         IN              const   ib_pd_handle_t                          h_pd,\r
2039         IN              const   ib_mr_create_t* const           p_mr_create,\r
2040                 OUT                     net32_t* const                          p_lkey,\r
2041                 OUT                     net32_t* const                          p_rkey,\r
2042                 OUT                     ib_mr_handle_t* const           ph_mr );\r
2043 /*\r
2044 * PARAMETERS\r
2045 *       h_pd\r
2046 *               [in] A handle to an existing protection domain that the memory\r
2047 *               should be registered with.\r
2048 *\r
2049 *       p_mr_create\r
2050 *               [in] Information describing the memory region to register.\r
2051 *\r
2052 *       p_lkey\r
2053 *               [out] The local access key associated with this registered memory\r
2054 *               region.\r
2055 *\r
2056 *       p_rkey\r
2057 *               [out] A key that may be used by a remote end-point when performing\r
2058 *               RDMA or atomic operations to this registered memory region.\r
2059 *\r
2060 *       ph_mr\r
2061 *               [out] Upon successful completion of this call, this references a\r
2062 *               handle to the registered memory region.  This handle is used when\r
2063 *               performing data transfers and to deregister the memory.\r
2064 *\r
2065 * RETURN VALUES\r
2066 *       IB_SUCCESS\r
2067 *               The memory region was successfully registered.\r
2068 *\r
2069 *       IB_INVALID_PD_HANDLE\r
2070 *               The protection domain to associate with the memory region was invalid.\r
2071 *\r
2072 *       IB_INVALID_PARAMETER\r
2073 *               A reference to the memory region information, lkey, rkey, or handle\r
2074 *               was not provided.\r
2075 *\r
2076 *       IB_INSUFFICIENT_MEMORY\r
2077 *               There was insufficient memory to register the memory region.\r
2078 *\r
2079 *       IB_INSUFFICIENT_RESOURCES\r
2080 *               There were insufficient resources currently available on the channel\r
2081 *               adapter to register the memory region.\r
2082 *\r
2083 *       IB_UNSUPPORTED\r
2084 *               The requested access rights are not supported by the channel adapter.\r
2085 *\r
2086 *       IB_INVALID_PERMISSION\r
2087 *               The requested access rights are invalid.\r
2088 *\r
2089 * NOTES\r
2090 *       This routine registers a virtual memory region with a channel adapter.\r
2091 *       Memory must be registered before being used in a data transfer operation.\r
2092 *\r
2093 * SEE ALSO\r
2094 *       ib_dereg_mr, ib_reg_phys, ib_reg_shared, ib_mr_create_t\r
2095 *****/\r
2096 \r
2097 \r
2098 /****f* Access Layer/ib_reg_phys\r
2099 * NAME\r
2100 *       ib_reg_phys\r
2101 *\r
2102 * DESCRIPTION\r
2103 *       Registers a physical memory region with a channel adapter.\r
2104 *\r
2105 * SYNOPSIS\r
2106 */\r
2107 AL_EXPORT ib_api_status_t AL_API\r
2108 ib_reg_phys(\r
2109         IN              const   ib_pd_handle_t                          h_pd,\r
2110         IN              const   ib_phys_create_t* const         p_phys_create,\r
2111         IN      OUT                     uint64_t* const                         p_vaddr,\r
2112                 OUT                     net32_t* const                          p_lkey,\r
2113                 OUT                     net32_t* const                          p_rkey,\r
2114                 OUT                     ib_mr_handle_t* const           ph_mr );\r
2115 /*\r
2116 * PARAMETERS\r
2117 *       h_pd\r
2118 *               [in] A handle to an existing protection domain that the memory\r
2119 *               should be registered with.\r
2120 *\r
2121 *       p_phys_create\r
2122 *               [in] Information describing the memory region to register.\r
2123 *\r
2124 *       p_vaddr\r
2125 *               [in/out] On input, references the requested virtual address for the\r
2126 *               start of the physical region.  On output, references the actual\r
2127 *               virtual address assigned to the registered region.\r
2128 *\r
2129 *       p_lkey\r
2130 *               [out] The local access key associated with this registered memory\r
2131 *               region.\r
2132 *\r
2133 *       p_rkey\r
2134 *               [out] A key that may be used by a remote end-point when performing\r
2135 *               RDMA or atomic operations to this registered memory region.\r
2136 *\r
2137 *       ph_mr\r
2138 *               [out] Upon successful completion of this call, this references a\r
2139 *               handle to the registered memory region.  This handle is used when\r
2140 *               performing data transfers and to deregister the memory.\r
2141 *\r
2142 * RETURN VALUES\r
2143 *       IB_SUCCESS\r
2144 *               The physical memory region was successfully registered.\r
2145 *\r
2146 *       IB_INVALID_PD_HANDLE\r
2147 *               The protection domain to associate with the physical memory region\r
2148 *               was invalid.\r
2149 *\r
2150 *       IB_INVALID_PARAMETER\r
2151 *               A reference to the physical memory region information, virtual address,\r
2152 *               lkey, rkey, or handle was not provided.\r
2153 *\r
2154 *       IB_INSUFFICIENT_MEMORY\r
2155 *               There was insufficient memory to register the physical memory region.\r
2156 *\r
2157 *       IB_INSUFFICIENT_RESOURCES\r
2158 *               There were insufficient resources currently available on the channel\r
2159 *               adapter to register the physical memory region.\r
2160 *\r
2161 *       IB_UNSUPPORTED\r
2162 *               The requested access rights are not supported by the channel adapter.\r
2163 *\r
2164 *       IB_INVALID_PERMISSION\r
2165 *               The requested access rights are invalid.\r
2166 *\r
2167 * NOTES\r
2168 *       This routine registers an array of physical pages as a single virtually\r
2169 *       contiguous region with a channel adapter.  Memory must be registered\r
2170 *       before being used in a data transfer operation.\r
2171 *\r
2172 * SEE ALSO\r
2173 *       ib_dereg_mr, ib_reg_mem, ib_reg_shared, ib_phys_create_t\r
2174 *****/\r
2175 \r
2176 \r
2177 /****f* Access Layer/ib_query_mr\r
2178 * NAME\r
2179 *       ib_query_mr\r
2180 *\r
2181 * DESCRIPTION\r
2182 *       Query the current attributes of a memory region.\r
2183 *\r
2184 * SYNOPSIS\r
2185 */\r
2186 AL_EXPORT ib_api_status_t AL_API\r
2187 ib_query_mr(\r
2188         IN              const   ib_mr_handle_t                          h_mr,\r
2189                 OUT                     ib_mr_attr_t* const                     p_mr_attr );\r
2190 /*\r
2191 * PARAMETERS\r
2192 *       h_mr\r
2193 *               [in] A handle to a registered memory region.\r
2194 *\r
2195 *       p_mr_attr\r
2196 *               [out] A reference to a structure where the registered memory attributes\r
2197 *               will be copied.\r
2198 *\r
2199 * RETURN VALUES\r
2200 *       IB_SUCCESS\r
2201 *               The memory region attributes were returned successfully.\r
2202 *\r
2203 *       IB_INVALID_MR_HANDLE\r
2204 *               The memory region handle was invalid.\r
2205 *\r
2206 *       IB_INVALID_PARAMETER\r
2207 *               A reference to the memory region attributes was not provided.\r
2208 *\r
2209 * NOTES\r
2210 *       This routine returns information about the specified registered memory\r
2211 *       region.\r
2212 *\r
2213 * SEE ALSO\r
2214 *       ib_dereg_mr, ib_reg_mem, ib_reg_shared, ib_mr_attr_t\r
2215 *****/\r
2216 \r
2217 \r
2218 /****f* Access Layer/ib_rereg_mem\r
2219 * NAME\r
2220 *       ib_rereg_mem\r
2221 *\r
2222 * DESCRIPTION\r
2223 *       Modifies the attributes of an existing memory region.\r
2224 *\r
2225 * SYNOPSIS\r
2226 */\r
2227 AL_EXPORT ib_api_status_t AL_API\r
2228 ib_rereg_mem(\r
2229         IN              const   ib_mr_handle_t                          h_mr,\r
2230         IN              const   ib_mr_mod_t                                     mr_mod_mask,\r
2231         IN              const   ib_mr_create_t* const           p_mr_create OPTIONAL,\r
2232                 OUT                     net32_t* const                          p_lkey,\r
2233                 OUT                     net32_t* const                          p_rkey,\r
2234         IN              const   ib_pd_handle_t                          h_pd OPTIONAL );\r
2235 /*\r
2236 * PARAMETERS\r
2237 *       h_mr\r
2238 *               [in] A handle to the registered memory region being modified.\r
2239 *\r
2240 *       mr_mod_mask\r
2241 *               [in] A mask used to specify which attributes of the memory region are\r
2242 *               being modified.\r
2243 *\r
2244 *       p_mr_create\r
2245 *               [in] This references information needed to perform the modification on\r
2246 *               the registered memory region.  This parameter may be NULL if only the\r
2247 *               protection domain will be modified.\r
2248 *\r
2249 *       p_lkey\r
2250 *               [out] The local access key associated with this registered memory\r
2251 *               region.\r
2252 *\r
2253 *       p_rkey\r
2254 *               [out] A key that may be used by a remote end-point when performing RDMA\r
2255 *               or atomic operations to this registered memory region.\r
2256 *\r
2257 *       h_pd\r
2258 *               [in] An optionally provided parameter used to modify the protection\r
2259 *               domain of a registered region.\r
2260 *\r
2261 * RETURN VALUES\r
2262 *       IB_SUCCESS\r
2263 *               The memory region attributes were modified successfully.\r
2264 *\r
2265 *       IB_INVALID_MR_HANDLE\r
2266 *               The memory region handle was invalid.\r
2267 *\r
2268 *       IB_INVALID_PARAMETER\r
2269 *               A reference to the lkey or rkey was not provided or the specified\r
2270 *               modify mask is invalid.\r
2271 *\r
2272 *       IB_INVALID_SETTING\r
2273 *               The specified memory region attributes are invalid.\r
2274 *\r
2275 *       IB_INVALID_PD_HANDLE\r
2276 *               The protection domain handle was invalid.\r
2277 *\r
2278 *       IB_INSUFFICIENT_RESOURCES\r
2279 *               There were insufficient resources currently available on the channel\r
2280 *               adapter to modify the memory region.\r
2281 *\r
2282 *       IB_UNSUPPORTED\r
2283 *               The requested access rights are not supported by the channel adapter.\r
2284 *\r
2285 *       IB_INVALID_PERMISSION\r
2286 *               The requested access rights are invalid.\r
2287 *\r
2288 *       IB_RESOURCE_BUSY\r
2289 *               The memory region has windows bound to it.\r
2290 *\r
2291 * NOTES\r
2292 *       This routine modifies the attributes of the specified memory region.\r
2293 *       The memory being modified may have been registered using either virtual\r
2294 *       or physical registration.  Conceptually, this routine is equivalent to\r
2295 *       to calling ib_dereg_mr, followed by ib_reg_mem, but may be higher\r
2296 *       performing.\r
2297 *\r
2298 * SEE ALSO\r
2299 *       ib_reg_mem, ib_reg_phys, ib_dereg_mr, ib_mr_mod_t, ib_mr_create_t\r
2300 *****/\r
2301 \r
2302 \r
2303 /****f* Access Layer/ib_rereg_phys\r
2304 * NAME\r
2305 *       ib_rereg_phys\r
2306 *\r
2307 * DESCRIPTION\r
2308 *       Modifies the attributes of an existing memory region.\r
2309 *\r
2310 * SYNOPSIS\r
2311 */\r
2312 AL_EXPORT ib_api_status_t AL_API\r
2313 ib_rereg_phys(\r
2314         IN              const   ib_mr_handle_t                          h_mr,\r
2315         IN              const   ib_mr_mod_t                                     mr_mod_mask,\r
2316         IN              const   ib_phys_create_t* const         p_phys_create OPTIONAL,\r
2317         IN      OUT                     uint64_t* const                         p_vaddr,\r
2318                 OUT                     net32_t* const                          p_lkey,\r
2319                 OUT                     net32_t* const                          p_rkey,\r
2320         IN              const   ib_pd_handle_t                          h_pd OPTIONAL );\r
2321 /*\r
2322 * PARAMETERS\r
2323 *       h_mr\r
2324 *               [in] A handle to the registered memory region being modified.\r
2325 *\r
2326 *       mr_mod_mask\r
2327 *               [in] A mask used to specify which attributes of the memory region are\r
2328 *               being modified.\r
2329 *\r
2330 *       p_phys_create\r
2331 *               [in] This references information needed to perform the modification on\r
2332 *               the registered memory region.  This parameter may be NULL if\r
2333 *               only the protection domain will be modified.\r
2334 *\r
2335 *       p_vaddr\r
2336 *               [in/out] On input, this specifies the requested virtual address for the\r
2337 *               start of the physical region.  On output, this references the actual\r
2338 *               virtual address assigned to the registered region.\r
2339 *\r
2340 *       p_lkey\r
2341 *               [out] The local access key associated with this registered memory\r
2342 *               region.\r
2343 *\r
2344 *       p_rkey\r
2345 *               [out] A key that may be used by a remote end-point when performing RDMA\r
2346 *               or atomic operations to this registered memory region.\r
2347 *\r
2348 *       h_pd\r
2349 *               [in] An optionally provided parameter used to modify the protection\r
2350 *               domain of a registered region.\r
2351 *\r
2352 * RETURN VALUES\r
2353 *       IB_SUCCESS\r
2354 *               The memory region attributes were modified successfully.\r
2355 *\r
2356 *       IB_INVALID_MR_HANDLE\r
2357 *               The memory region handle was invalid.\r
2358 *\r
2359 *       IB_INVALID_PARAMETER\r
2360 *               A reference to the virtual address, lkey, rkey was not provided or\r
2361 *               the specified modify mask is invalid.\r
2362 *\r
2363 *       IB_INVALID_SETTING\r
2364 *               The specified memory region attributes are invalid.\r
2365 *\r
2366 *       IB_INVALID_PD_HANDLE\r
2367 *               The protection domain handle was invalid.\r
2368 *\r
2369 *       IB_INSUFFICIENT_RESOURCES\r
2370 *               There were insufficient resources currently available on the channel\r
2371 *               adapter to modify the memory region.\r
2372 *\r
2373 *       IB_UNSUPPORTED\r
2374 *               The requested access rights are not supported by the channel adapter.\r
2375 *\r
2376 *       IB_INVALID_PERMISSION\r
2377 *               The requested access rights are invalid.\r
2378 *\r
2379 *       IB_RESOURCE_BUSY\r
2380 *               The memory region has windows bound to it.\r
2381 *\r
2382 * NOTES\r
2383 *       This routine modifies the attributes of the specified memory region.\r
2384 *       The memory being modified may have been registered using either virtual\r
2385 *       or physical registration.  Conceptually, this routine is equivalent to\r
2386 *       to calling ib_dereg_mr, followed by ib_reg_phys, but may be higher\r
2387 *       performing.\r
2388 *\r
2389 * SEE ALSO\r
2390 *       ib_reg_mem, ib_reg_phys, ib_dereg_mr, ib_mr_mod_t, ib_mr_create_t\r
2391 *****/\r
2392 \r
2393 \r
2394 /****f* Access Layer/ib_reg_shared\r
2395 * NAME\r
2396 *       ib_reg_shared\r
2397 *\r
2398 * DESCRIPTION\r
2399 *       Registers a memory region that has the same physical pages as an\r
2400 *       existing registered memory region.\r
2401 *\r
2402 * SYNOPSIS\r
2403 */\r
2404 AL_EXPORT ib_api_status_t AL_API\r
2405 ib_reg_shared(\r
2406         IN              const   ib_mr_handle_t                          h_mr,\r
2407         IN              const   ib_pd_handle_t                          h_pd,\r
2408         IN              const   ib_access_t                                     access_ctrl,\r
2409         IN      OUT                     uint64_t* const                         p_vaddr,\r
2410                 OUT                     net32_t* const                          p_lkey,\r
2411                 OUT                     net32_t* const                          p_rkey,\r
2412                 OUT                     ib_mr_handle_t* const           ph_mr );\r
2413 /*\r
2414 * PARAMETERS\r
2415 *       h_mr\r
2416 *               [in] A handle to an existing registered memory region that this\r
2417 *               registration should share physical pages with.\r
2418 *\r
2419 *       h_pd\r
2420 *               [in] Handle to the PD on which memory is being registered\r
2421 *\r
2422 *       access_ctrl\r
2423 *               [in] Access rights of the registered region.\r
2424 *\r
2425 *       p_vaddr\r
2426 *               [in/out] On input, this specifies the requested virtual address for the\r
2427 *               start of the physical region.  On output, this references the actual\r
2428 *               virtual address assigned to the registered region.  This is always a\r
2429 *               64-bit quantity to support registering more than 4GB of memory on\r
2430 *               32-bit systems with PAE.\r
2431 *\r
2432 *       p_lkey\r
2433 *               [out] The local access key associated with this registered memory\r
2434 *               region.\r
2435 *\r
2436 *       p_rkey\r
2437 *               [out] A key that may be used by a remote end-point when performing RDMA\r
2438 *               or atomic operations to this registered memory region.\r
2439 *\r
2440 *       ph_mr\r
2441 *               [out] Upon successful completion of this call, this references a handle\r
2442 *               to the registered memory region.  This handle is used when performing\r
2443 *               data transfers and to deregister the memory.\r
2444 *\r
2445 * RETURN VALUES\r
2446 *       IB_SUCCESS\r
2447 *               The shared memory region was successfully registered.\r
2448 *\r
2449 *       IB_INVALID_MR_HANDLE\r
2450 *               The memory region handle was invalid.\r
2451 *\r
2452 *       IB_INVALID_PD_HANDLE\r
2453 *               The protection domain handle was invalid.\r
2454 *\r
2455 *       IB_INVALID_PARAMETER\r
2456 *               A reference to the virtual address, lkey, rkey, or handle was not\r
2457 *               provided.\r
2458 *\r
2459 *       IB_INSUFFICIENT_MEMORY\r
2460 *               There was insufficient memory to register the shared memory region.\r
2461 *\r
2462 *       IB_INSUFFICIENT_RESOURCES\r
2463 *               There were insufficient resources currently available on the channel\r
2464 *               adapter to register the shared memory region.\r
2465 *\r
2466 *       IB_UNSUPPORTED\r
2467 *               The requested access rights are not supported by the channel adapter.\r
2468 *\r
2469 *       IB_INVALID_PERMISSION\r
2470 *               The requested access rights are invalid.\r
2471 *\r
2472 * NOTES\r
2473 *       This routine registers a memory region that shares the same set of\r
2474 *       physical pages associated with an existing registered memory region.\r
2475 *\r
2476 * SEE ALSO\r
2477 *       ib_dereg_mr, ib_reg_mem, ib_reg_phys, ib_reg_shared, ib_mr_create_t\r
2478 *****/\r
2479 \r
2480 \r
2481 /****f* Access Layer/ib_reg_shmid\r
2482 * NAME\r
2483 *       ib_reg_shmid\r
2484 *\r
2485 * DESCRIPTION\r
2486 *       Registers a memory region to be shared across multiple processes.\r
2487 *       The memory is referenced by a shared memory identifier.\r
2488 *\r
2489 * SYNOPSIS\r
2490 */\r
2491 AL_EXPORT ib_api_status_t AL_API\r
2492 ib_reg_shmid(\r
2493         IN              const   ib_pd_handle_t                          h_pd,\r
2494         IN              const   ib_shmid_t                                      shmid,\r
2495         IN              const   ib_mr_create_t* const           p_mr_create,\r
2496                 OUT                     uint64_t* const                         p_vaddr,\r
2497                 OUT                     net32_t* const                          p_lkey,\r
2498                 OUT                     net32_t* const                          p_rkey,\r
2499                 OUT                     ib_mr_handle_t* const           ph_mr );\r
2500 /*\r
2501 * PARAMETERS\r
2502 *       h_pd\r
2503 *               [in] A handle to an existing protection domain that the memory\r
2504 *               should be registered with.\r
2505 *\r
2506 *       shmid\r
2507 *               [in] An identifier for the shared memory region.\r
2508 *\r
2509 *       p_mr_create\r
2510 *               [in] Information describing the attributes of the memory region to\r
2511 *               register.\r
2512 *\r
2513 *       p_vaddr,\r
2514 *               [out] The HCA assigned, HCA relative virtual address for the\r
2515 *               memory region.\r
2516 *\r
2517 *       p_lkey\r
2518 *               [out] The local access key associated with this registered memory\r
2519 *               region.\r
2520 *\r
2521 *       p_rkey\r
2522 *               [out] A key that may be used by a remote end-point when performing RDMA\r
2523 *               or atomic operations to this registered memory region.\r
2524 *\r
2525 *       ph_mr\r
2526 *               [out] Upon successful completion of this call, this references a handle\r
2527 *               to the registered memory region.  This handle is used when performing\r
2528 *               data transfers and to deregister the memory.\r
2529 *\r
2530 * RETURN VALUES\r
2531 *       IB_SUCCESS\r
2532 *               The shared memory region was successfully registered.\r
2533 *\r
2534 *       IB_INVALID_PD_HANDLE\r
2535 *               The protection domain handle was invalid.\r
2536 *\r
2537 *       IB_INVALID_PARAMETER\r
2538 *               A reference to the memory region information, lkey, rkey, or handle\r
2539 *               was not provided.\r
2540 *\r
2541 *       IB_INVALID_SETTING\r
2542 *               The length and page mapping for the memory region do not match those\r
2543 *               of the region identified by the provided SHMID.\r
2544 *\r
2545 *       IB_INSUFFICIENT_MEMORY\r
2546 *               There was insufficient memory to register the shared memory region.\r
2547 *\r
2548 *       IB_INSUFFICIENT_RESOURCES\r
2549 *               There were insufficient resources currently available on the channel\r
2550 *               adapter to register the shared memory region.\r
2551 *\r
2552 *       IB_UNSUPPORTED\r
2553 *               The requested access rights are not supported by the channel adapter.\r
2554 *\r
2555 *       IB_INVALID_PERMISSION\r
2556 *               The requested access rights are invalid.\r
2557 *\r
2558 * NOTES\r
2559 *       This routine registers a memory region that is shared between processes.\r
2560 *       The region being registered is identified through a shared memory\r
2561 *       identifier.  The registered region shares hardware resources as much\r
2562 *       as possible.\r
2563 *\r
2564 * SEE ALSO\r
2565 *       ib_dereg_mr, ib_reg_mem, ib_reg_shared, ib_mr_create_t\r
2566 *****/\r
2567 \r
2568 \r
2569 /****f* Access Layer/ib_dereg_mr\r
2570 * NAME\r
2571 *       ib_dereg_mr\r
2572 *\r
2573 * DESCRIPTION\r
2574 *       Deregisters a registered memory region.\r
2575 *\r
2576 * SYNOPSIS\r
2577 */\r
2578 AL_EXPORT ib_api_status_t AL_API\r
2579 ib_dereg_mr(\r
2580         IN              const   ib_mr_handle_t                          h_mr );\r
2581 /*\r
2582 * PARAMETERS\r
2583 *       h_mr\r
2584 *               [in] A handle to a registered memory region that will be unregistered.\r
2585 *\r
2586 * RETURN VALUES\r
2587 *       IB_SUCCESS\r
2588 *               The memory region was successfully deregistered.\r
2589 *\r
2590 *       IB_INVALID_MR_HANDLE\r
2591 *               The memory region handle was invalid.\r
2592 *\r
2593 *       IB_RESOURCE_BUSY\r
2594 *               The memory region has memory windows bound to it.\r
2595 *\r
2596 * NOTES\r
2597 *       This routine deregisters a memory region with a channel adapter.  The\r
2598 *       region may be deregistered only if there are no memory  windows or\r
2599 *       existing shared memory regions currently bound to the region.  Work\r
2600 *       requests referencing this region when it is deregistered will fail\r
2601 *       with a WRS_LOCAL_PROTECTION_ERR error.\r
2602 *\r
2603 * SEE ALSO\r
2604 *       ib_reg_mem, ib_reg_phys, ib_reg_shared\r
2605 *****/\r
2606 \r
2607 \r
2608 #ifdef CL_KERNEL\r
2609 \r
2610 /****f* Access Layer/mlnx_create_fmr\r
2611 * NAME\r
2612 *       mlnx_create_fmr\r
2613 *\r
2614 * DESCRIPTION\r
2615 *       Creates a Mellanox fast memory region.\r
2616 *\r
2617 * SYNOPSIS\r
2618 */\r
2619 AL_EXPORT ib_api_status_t AL_API\r
2620 mlnx_create_fmr(\r
2621         IN              const   ib_pd_handle_t                          h_pd,\r
2622         IN              const   mlnx_fmr_create_t* const        p_fmr_create,\r
2623                 OUT                     mlnx_fmr_handle_t* const        ph_fmr );\r
2624 /*\r
2625 * PARAMETERS\r
2626 *       h_pd\r
2627 *               [in] An optionally provided parameter used to modify the protection\r
2628 *               domain of a registered region.\r
2629 *       p_fmr_create\r
2630 *               [in] This references information needed to perform the modification on\r
2631 *               the registered memory region.  This parameter may be NULL if only the\r
2632 *               protection domain will be modified.\r
2633 *       ph_fmr\r
2634 *               [out] A handle to the registered memory region being modified.\r
2635 *\r
2636 * RETURN VALUES\r
2637 *       IB_SUCCESS\r
2638 *               The memory region attributes were modified successfully.\r
2639 *\r
2640 *       IB_INVALID_MR_HANDLE\r
2641 *               The memory region handle was invalid.\r
2642 *\r
2643 *       IB_INVALID_PARAMETER\r
2644 *               A reference to the lkey or rkey was not provided or the specified\r
2645 *               modify mask is invalid.\r
2646 *\r
2647 *       IB_INVALID_SETTING\r
2648 *               The specified memory region attributes are invalid.\r
2649 *\r
2650 *       IB_INVALID_PD_HANDLE\r
2651 *               The protection domain handle was invalid.\r
2652 *\r
2653 *       IB_INSUFFICIENT_RESOURCES\r
2654 *               There were insufficient resources currently available on the channel\r
2655 *               adapter to modify the memory region.\r
2656 *\r
2657 *       IB_UNSUPPORTED\r
2658 *               The requested access rights are not supported by the channel adapter.\r
2659 *\r
2660 *       IB_INVALID_PERMISSION\r
2661 *               The requested access rights are invalid.\r
2662 *\r
2663 *       IB_RESOURCE_BUSY\r
2664 *               The memory region has windows bound to it.\r
2665 *\r
2666 * NOTES\r
2667 *       This is a Mellanox specific extension to verbs.\r
2668 *\r
2669 * SEE ALSO\r
2670 *       mlnx_destroy_fmr, mlnx_fmr_create_t\r
2671 *****/\r
2672 \r
2673 \r
2674 /****f* Access Layer/mlnx_map_fmr\r
2675 * NAME\r
2676 *       mlnx_map_fmr\r
2677 *\r
2678 * DESCRIPTION\r
2679 *       //TODO\r
2680 *\r
2681 * SYNOPSIS\r
2682 */\r
2683 AL_EXPORT ib_api_status_t AL_API\r
2684 mlnx_map_phys_fmr(\r
2685         IN              const   mlnx_fmr_handle_t                       h_fmr,\r
2686         IN              const   uint64_t* const                         paddr_list,\r
2687         IN              const   int                                                     list_len,\r
2688         IN      OUT                     uint64_t* const                         p_vaddr,\r
2689                 OUT                     net32_t* const                          p_lkey,\r
2690                 OUT                     net32_t* const                          p_rkey );\r
2691 /*\r
2692 * PARAMETERS\r
2693 *       h_fmr\r
2694 *               [in] Handle to the fast memory region that  these pages map to \r
2695 *       page_list\r
2696 *               [in] array of phys address\r
2697 *       list_len\r
2698 *               [in] number of pages in the list\r
2699 *       p_vaddr\r
2700 *               [in/out] On input, references the requested virtual address for the\r
2701 *               start of the FMR.  On output, references the actual\r
2702 *               virtual address assigned to the FMR.\r
2703 *       p_lkey\r
2704 *               [out] The local access key associated with this registered memory\r
2705 *               region.\r
2706 *       p_rkey\r
2707 *               [out] A key that may be used by a remote end-point when performing\r
2708 *               RDMA or atomic operations to this registered memory region.\r
2709 *\r
2710 * RETURN VALUES\r
2711 *       IB_SUCCESS\r
2712 *               The memory region attributes were modified successfully.\r
2713 *\r
2714 *       IB_INVALID_MR_HANDLE\r
2715 *               The memory region handle was invalid.\r
2716 *\r
2717 *       IB_INVALID_PARAMETER\r
2718 *               A reference to the lkey or rkey was not provided or the specified\r
2719 *               modify mask is invalid.\r
2720 *\r
2721 *       IB_INVALID_SETTING\r
2722 *               The specified memory region attributes are invalid.\r
2723 *\r
2724 *       IB_INVALID_PD_HANDLE\r
2725 *               The protection domain handle was invalid.\r
2726 *\r
2727 *       IB_INSUFFICIENT_RESOURCES\r
2728 *               There were insufficient resources currently available on the channel\r
2729 *               adapter to modify the memory region.\r
2730 *\r
2731 *       IB_UNSUPPORTED\r
2732 *               The requested access rights are not supported by the channel adapter.\r
2733 *\r
2734 *       IB_INVALID_PERMISSION\r
2735 *               The requested access rights are invalid.\r
2736 *\r
2737 *       IB_RESOURCE_BUSY\r
2738 *               The memory region has windows bound to it.\r
2739 *\r
2740 * NOTES\r
2741 *       This is a Mellanox specific extension to verbs.\r
2742 *\r
2743 * SEE ALSO\r
2744 *       mlnx_destroy_fmr, mlnx_fmr_create_t\r
2745 *****/\r
2746 \r
2747 \r
2748 /****f* Access Layer/mlnx_unmap_fmr\r
2749 * NAME\r
2750 *       mlnx_unmap_fmr\r
2751 *\r
2752 * DESCRIPTION\r
2753 *       //TODO\r
2754 *\r
2755 * SYNOPSIS\r
2756 */\r
2757 AL_EXPORT ib_api_status_t AL_API\r
2758 mlnx_unmap_fmr(\r
2759         IN              const   mlnx_fmr_handle_t                       h_fmr );\r
2760 /*\r
2761 * PARAMETERS\r
2762 *       h_fmr\r
2763 *\r
2764 * RETURN VALUES\r
2765 *       IB_SUCCESS\r
2766 *               The memory region attributes were modified successfully.\r
2767 *\r
2768 *       IB_INVALID_MR_HANDLE\r
2769 *               The memory region handle was invalid.\r
2770 *\r
2771 *       IB_INVALID_PARAMETER\r
2772 *               A reference to the lkey or rkey was not provided or the specified\r
2773 *               modify mask is invalid.\r
2774 *\r
2775 *       IB_INVALID_SETTING\r
2776 *               The specified memory region attributes are invalid.\r
2777 *\r
2778 *       IB_INVALID_PD_HANDLE\r
2779 *               The protection domain handle was invalid.\r
2780 *\r
2781 *       IB_INSUFFICIENT_RESOURCES\r
2782 *               There were insufficient resources currently available on the channel\r
2783 *               adapter to modify the memory region.\r
2784 *\r
2785 *       IB_UNSUPPORTED\r
2786 *               The requested access rights are not supported by the channel adapter.\r
2787 *\r
2788 *       IB_INVALID_PERMISSION\r
2789 *               The requested access rights are invalid.\r
2790 *\r
2791 *       IB_RESOURCE_BUSY\r
2792 *               The memory region has windows bound to it.\r
2793 *\r
2794 * NOTES\r
2795 *       This is a Mellanox specific extension to verbs.\r
2796 *\r
2797 * SEE ALSO\r
2798 *       mlnx_destroy_fmr, mlnx_fmr_create_t\r
2799 *****/\r
2800 \r
2801 \r
2802 /****f* Access Layer/mlnx_destroy_fmr\r
2803 * NAME\r
2804 *       mlnx_destroy_fmr\r
2805 *\r
2806 * DESCRIPTION\r
2807 *       Destroys an existing Mellanox fast memory region.\r
2808 *\r
2809 * SYNOPSIS\r
2810 */\r
2811 AL_EXPORT ib_api_status_t AL_API\r
2812 mlnx_destroy_fmr(\r
2813         IN              const   mlnx_fmr_handle_t                       h_fmr );\r
2814 /*\r
2815 * PARAMETERS\r
2816 *       h_fmr\r
2817 *               [in] A handle to the registered memory region being modified.\r
2818 *\r
2819 * RETURN VALUES\r
2820 *       IB_SUCCESS\r
2821 *               The memory region attributes were modified successfully.\r
2822 *\r
2823 *       IB_INVALID_MR_HANDLE\r
2824 *               The memory region handle was invalid.\r
2825 *\r
2826 *       IB_INVALID_PARAMETER\r
2827 *               A reference to the lkey or rkey was not provided or the specified\r
2828 *               modify mask is invalid.\r
2829 *\r
2830 *       IB_INVALID_SETTING\r
2831 *               The specified memory region attributes are invalid.\r
2832 *\r
2833 *       IB_INVALID_PD_HANDLE\r
2834 *               The protection domain handle was invalid.\r
2835 *\r
2836 *       IB_INSUFFICIENT_RESOURCES\r
2837 *               There were insufficient resources currently available on the channel\r
2838 *               adapter to modify the memory region.\r
2839 *\r
2840 *       IB_UNSUPPORTED\r
2841 *               The requested access rights are not supported by the channel adapter.\r
2842 *\r
2843 *       IB_INVALID_PERMISSION\r
2844 *               The requested access rights are invalid.\r
2845 *\r
2846 *       IB_RESOURCE_BUSY\r
2847 *               The memory region has windows bound to it.\r
2848 *\r
2849 * NOTES\r
2850 *       This is a Mellanox specific extension to verbs.\r
2851 *\r
2852 * SEE ALSO\r
2853 *       mlnx_destroy_fmr, mlnx_fmr_create_t\r
2854 *****/\r
2855 \r
2856 \r
2857 /****f* Access Layer/ib_create_fmr_pool\r
2858 * NAME\r
2859 *       ib_create_fmr_pool\r
2860 *\r
2861 * DESCRIPTION\r
2862 *       Creates a pool of FMR elements for use \r
2863 *\r
2864 * SYNOPSIS\r
2865 */\r
2866 AL_EXPORT ib_api_status_t AL_API\r
2867 mlnx_create_fmr_pool(\r
2868         IN              const   ib_pd_handle_t                          h_pd,\r
2869         IN              const   mlnx_fmr_pool_create_t          *p_fmr_pool_attr,\r
2870         OUT             mlnx_fmr_pool_handle_t* const           ph_pool );\r
2871 /*\r
2872 * PARAMETERS\r
2873 TODO\r
2874 *\r
2875 * RETURN VALUES\r
2876 TODO\r
2877 *\r
2878 * NOTES\r
2879 TODO\r
2880 *\r
2881 * SEE ALSO\r
2882 TOD\r
2883 *****/\r
2884 \r
2885 \r
2886 /****f* Access Layer/ib_destroy_fmr_pool\r
2887 * NAME\r
2888 *       ib_destroy_fmr_pool\r
2889 *\r
2890 * DESCRIPTION\r
2891 *       Destroys a MAD pool and all associated resources.\r
2892 *\r
2893 * SYNOPSIS\r
2894 */\r
2895 AL_EXPORT ib_api_status_t AL_API\r
2896 mlnx_destroy_fmr_pool(\r
2897         IN              const   mlnx_fmr_pool_handle_t                  h_pool );\r
2898 /*\r
2899 * PARAMETERS\r
2900 TODO\r
2901 *\r
2902 * RETURN VALUES\r
2903 TODO\r
2904 *\r
2905 * NOTES\r
2906 TODO\r
2907 *\r
2908 * SEE ALSO\r
2909 TODO\r
2910 *****/\r
2911 \r
2912 \r
2913 \r
2914 \r
2915 \r
2916 \r
2917 \r
2918 /****f* Access Layer/ib_fmr_pool_map_phys\r
2919 * NAME\r
2920 *       ib_destroy_fmr_pool\r
2921 *\r
2922 * DESCRIPTION\r
2923 *       Destroys a MAD pool and all associated resources.\r
2924 *\r
2925 * SYNOPSIS\r
2926 */\r
2927 AL_EXPORT ib_api_status_t AL_API\r
2928 mlnx_map_phys_fmr_pool(\r
2929         IN              const   mlnx_fmr_pool_handle_t          h_pool ,\r
2930         IN              const   uint64_t* const                         paddr_list,\r
2931         IN              const   int                                                     list_len,\r
2932         IN      OUT                     uint64_t* const                         p_vaddr,\r
2933         OUT             net32_t* const                                  p_lkey,\r
2934         OUT             net32_t* const                                  p_rkey,\r
2935         OUT                             mlnx_fmr_pool_el_t              *pp_fmr_el);\r
2936 /*\r
2937 * PARAMETERS\r
2938 TODO\r
2939 *\r
2940 * RETURN VALUES\r
2941 TODO\r
2942 *\r
2943 * NOTES\r
2944 TODO\r
2945 *\r
2946 * SEE ALSO\r
2947 TODO\r
2948 *****/\r
2949 \r
2950 \r
2951 \r
2952 \r
2953 \r
2954 /****f* Access Layer/ib_destroy_fmr_pool\r
2955 * NAME\r
2956 *       ib_destroy_fmr_pool\r
2957 *\r
2958 * DESCRIPTION\r
2959 *       Destroys a MAD pool and all associated resources.\r
2960 *\r
2961 * SYNOPSIS\r
2962 */\r
2963 AL_EXPORT ib_api_status_t AL_API\r
2964 mlnx_unmap_fmr_pool(\r
2965         IN                      mlnx_fmr_pool_el_t                      p_fmr_el );\r
2966 /*\r
2967 * PARAMETERS\r
2968 TODO\r
2969 *\r
2970 * RETURN VALUES\r
2971 TODO\r
2972 *\r
2973 * NOTES\r
2974 TODO\r
2975 *\r
2976 * SEE ALSO\r
2977 TODO\r
2978 *****/\r
2979 \r
2980 \r
2981 /****f* Access Layer/ib_flush_fmr_pool\r
2982 * NAME\r
2983 *       ib_flush_fmr_pool\r
2984 *\r
2985 * DESCRIPTION\r
2986 *       Destroys a MAD pool and all associated resources.\r
2987 *\r
2988 * SYNOPSIS\r
2989 */\r
2990 ib_api_status_t\r
2991 mlnx_flush_fmr_pool(mlnx_fmr_pool_handle_t  h_pool); \r
2992 /*\r
2993 * PARAMETERS\r
2994 TODO\r
2995 *\r
2996 * RETURN VALUES\r
2997 TODO\r
2998 *\r
2999 * NOTES\r
3000 TODO\r
3001 *\r
3002 * SEE ALSO\r
3003 TODO\r
3004 *****/\r
3005 #endif  /* CL_KERNEL */\r
3006 \r
3007 /****f* Access Layer/ib_create_mw\r
3008 * NAME\r
3009 *       ib_create_mw\r
3010 *\r
3011 * DESCRIPTION\r
3012 *       Creates a memory window associated with the specified protection domain.\r
3013 *       Newly created windows are not bound to any specific memory region.\r
3014 *\r
3015 * SYNOPSIS\r
3016 */\r
3017 AL_EXPORT ib_api_status_t AL_API\r
3018 ib_create_mw(\r
3019         IN              const   ib_pd_handle_t                          h_pd,\r
3020                 OUT                     net32_t* const                          p_rkey,\r
3021                 OUT                     ib_mw_handle_t* const           ph_mw );\r
3022 /*\r
3023 * PARAMETERS\r
3024 *       h_pd\r
3025 *               [in] A handle to an existing protection domain that the memory window\r
3026 *               should be created within.\r
3027 *\r
3028 *       p_rkey\r
3029 *               [out] The current rkey associated with the memory window.  This key is\r
3030 *               used to bind the window to a registered memory region.\r
3031 *\r
3032 *       ph_mw\r
3033 *               [out] Upon successful completion of this call, this references a handle\r
3034 *               to the memory window.  This handle is used to bind and destroy\r
3035 *               the window.\r
3036 *\r
3037 * RETURN VALUES\r
3038 *       IB_SUCCESS\r
3039 *               The memory window was successfully created.\r
3040 *\r
3041 *       IB_INVALID_PD_HANDLE\r
3042 *               The protection domain handle was invalid.\r
3043 *\r
3044 *       IB_INVALID_PARAMETER\r
3045 *               A reference to the memory window rkey or handle was not provided.\r
3046 *\r
3047 *       IB_INSUFFICIENT_MEMORY\r
3048 *               There was insufficient memory to create the memory window.\r
3049 *\r
3050 *       IB_INSUFFICIENT_RESOURCES\r
3051 *               There were insufficient resources currently available on the channel\r
3052 *               adapter to create the memory window.\r
3053 *\r
3054 * NOTES\r
3055 *       This routine creates an unbound memory window associated with a specified\r
3056 *       protection domain.  The memory window cannot be used for data transfer\r
3057 *       operations until being bound to a registered memory region.\r
3058 *\r
3059 * SEE ALSO\r
3060 *       ib_destroy_mw, ib_query_mw, ib_bind_mw\r
3061 *****/\r
3062 \r
3063 \r
3064 /****f* Access Layer/ib_query_mw\r
3065 * NAME\r
3066 *       ib_query_mw\r
3067 *\r
3068 * DESCRIPTION\r
3069 *       Query the current attributes of a memory window.\r
3070 *\r
3071 * SYNOPSIS\r
3072 */\r
3073 AL_EXPORT ib_api_status_t AL_API\r
3074 ib_query_mw(\r
3075         IN              const   ib_mw_handle_t                          h_mw,\r
3076                 OUT                     ib_pd_handle_t* const           ph_pd,\r
3077                 OUT                     net32_t* const                          p_rkey );\r
3078 /*\r
3079 * PARAMETERS\r
3080 *       h_mw\r
3081 *               [in] A handle to an existing memory window.\r
3082 *\r
3083 *       ph_pd\r
3084 *               [out] Upon successful completion of this call, this will reference\r
3085 *               the protection domain associated with this memory window.\r
3086 *\r
3087 *       p_rkey\r
3088 *               [out] Upon successful completion of this call, this will reference\r
3089 *               the current rkey associated with this memory window.\r
3090 *\r
3091 * RETURN VALUES\r
3092 *       IB_SUCCESS\r
3093 *               The memory window attributes were returned successfully.\r
3094 *\r
3095 *       IB_INVALID_MW_HANDLE\r
3096 *               The memory window handle was invalid.\r
3097 *\r
3098 *       IB_INVALID_PARAMETER\r
3099 *               A reference to the protection domain handle or rkey was not provided.\r
3100 *\r
3101 * NOTES\r
3102 *       This routine returns information about the specified memory window.\r
3103 *\r
3104 * SEE ALSO\r
3105 *       ib_create_mw\r
3106 *****/\r
3107 \r
3108 \r
3109 /****f* Access Layer/ib_bind_mw\r
3110 * NAME\r
3111 *       ib_bind_mw\r
3112 *\r
3113 * DESCRIPTION\r
3114 *       Binds a memory window to a registered memory region.\r
3115 *\r
3116 * SYNOPSIS\r
3117 */\r
3118 AL_EXPORT ib_api_status_t AL_API\r
3119 ib_bind_mw(\r
3120         IN              const   ib_mw_handle_t                          h_mw,\r
3121         IN              const   ib_qp_handle_t                          h_qp,\r
3122         IN                              ib_bind_wr_t* const                     p_mw_bind,\r
3123                 OUT                     net32_t* const                          p_rkey );\r
3124 /*\r
3125 * PARAMETERS\r
3126 *       h_mw\r
3127 *               [in] A handle to an existing memory window.\r
3128 *\r
3129 *       h_qp\r
3130 *               [in] A handle to a queue pair that the bind request will be posted to.\r
3131 *\r
3132 *       p_mw_bind\r
3133 *               [in] Describes the memory window bind request.\r
3134 *\r
3135 *       p_rkey\r
3136 *               [out] The new rkey for the memory window that may be used by a remote\r
3137 *               end-point when performing RDMA or atomic operations to this memory\r
3138 *               region.\r
3139 *\r
3140 * RETURN VALUES\r
3141 *       IB_SUCCESS\r
3142 *               The memory window bind operation was successfully posted.\r
3143 *\r
3144 *       IB_INVALID_MW_HANDLE\r
3145 *               The memory window handle was invalid.\r
3146 *\r
3147 *       IB_INVALID_QP_HANDLE\r
3148 *               The queue pair handle was invalid.\r
3149 *\r
3150 *       IB_INVALID_PARAMETER\r
3151 *               A reference to the memory window bind work request or rkey was not\r
3152 *               provided.\r
3153 *\r
3154 *       IB_INVALID_SERVICE_TYPE\r
3155 *               The queue pair configuration does not support this type of service.\r
3156 *\r
3157 *       IB_INVALID_MR_HANDLE\r
3158 *               The memory region handle was invalid.\r
3159 *\r
3160 *       IB_INVALID_RKEY\r
3161 *               The rkey is invalid for the memory region being bound.\r
3162 *\r
3163 *       IB_UNSUPPORTED\r
3164 *               The requested access rights are not supported by the channel adapter.\r
3165 *\r
3166 *       IB_INVALID_PERMISSION\r
3167 *               The requested access rights are invalid.\r
3168 *\r
3169 *       IB_INSUFFICIENT_RESOURCES\r
3170 *               There were insufficient resources currently available on the channel\r
3171 *               adapter to bind the memory window.\r
3172 *\r
3173 * NOTES\r
3174 *       This routine posts a request to bind a memory window to a registered\r
3175 *       memory region.  The bind operation occurs on the specified queue pair,\r
3176 *       but the bound region is usable across all queue pairs within the same\r
3177 *       protection domain.\r
3178 *\r
3179 * SEE ALSO\r
3180 *       ib_create_mw, ib_bind_wr_t\r
3181 *****/\r
3182 \r
3183 \r
3184 /****f* Access Layer/ib_destroy_mw\r
3185 * NAME\r
3186 *       ib_destroy_mw\r
3187 *\r
3188 * DESCRIPTION\r
3189 *       Destroys a memory window.\r
3190 *\r
3191 * SYNOPSIS\r
3192 */\r
3193 AL_EXPORT ib_api_status_t AL_API\r
3194 ib_destroy_mw(\r
3195         IN              const   ib_mw_handle_t                          h_mw );\r
3196 /*\r
3197 * PARAMETERS\r
3198 *       h_mw\r
3199 *               [in] A handle to an existing memory window.\r
3200 *\r
3201 * RETURN VALUES\r
3202 *       IB_SUCCESS\r
3203 *               The memory window was successfully destroyed.\r
3204 *\r
3205 *       IB_INVALID_MW_HANDLE\r
3206 *               The memory window handle was invalid.\r
3207 *\r
3208 * NOTES\r
3209 *       This routine deallocates a window entry created via a ib_create_mw.\r
3210 *       Once this operation is complete, future accesses to the window will fail.\r
3211 *\r
3212 * SEE ALSO\r
3213 *       ib_create_mw\r
3214 *****/\r
3215 \r
3216 \r
3217 /****f* Access Layer/ib_post_send\r
3218 * NAME\r
3219 *       ib_post_send\r
3220 *\r
3221 * DESCRIPTION\r
3222 *       This routine posts a work request to the send queue of a queue pair.\r
3223 *\r
3224 * SYNOPSIS\r
3225 */\r
3226 AL_EXPORT ib_api_status_t AL_API\r
3227 ib_post_send(\r
3228         IN              const   ib_qp_handle_t                          h_qp,\r
3229         IN                              ib_send_wr_t* const                     p_send_wr,\r
3230                 OUT                     ib_send_wr_t                            **pp_send_failure OPTIONAL );\r
3231 /*\r
3232 * PARAMETERS\r
3233 *       h_qp\r
3234 *               [in] The queue pair to which this work request is being submitted.\r
3235 *\r
3236 *       p_send_wr\r
3237 *               [in] A reference to the head of the work request list.\r
3238 *\r
3239 *       pp_send_failure\r
3240 *               [out] If the post send operation failed, this references the work\r
3241 *               request in the p_send_wr list where the first failure occurred.\r
3242 *               This parameter may be NULL if only a single work request is being\r
3243 *               posted to the QP.\r
3244 *\r
3245 * RETURN VALUES\r
3246 *       IB_SUCCESS\r
3247 *               All work requests were successfully posted.\r
3248 *\r
3249 *       IB_INVALID_QP_HANDLE\r
3250 *               The queue pair handle was invalid.\r
3251 *\r
3252 *       IB_INVALID_PARAMETER\r
3253 *               A reference to the send work request list was not provided.\r
3254 *\r
3255 *       IB_INSUFFICIENT_RESOURCES\r
3256 *               The number of posted work requests exceed the current depth available\r
3257 *               on the send queue.\r
3258 *\r
3259 *       IB_INVALID_WR_TYPE\r
3260 *               The work request type was invalid.\r
3261 *\r
3262 *       IB_INVALID_QP_STATE\r
3263 *               The current queue pair state does not allow posting sends.\r
3264 *\r
3265 *       IB_INVALID_MAX_SGE\r
3266 *               The number of work request scatter gather elements exceed the queue\r
3267 *               pair configuration.\r
3268 *\r
3269 *       IB_UNSUPPORTED\r
3270 *               The requested operation is not supported by the channel adapter.\r
3271 *\r
3272 * NOTES\r
3273 *       This routine posts a work request to the send queue of a queue pair.\r
3274 *       The type of work to perform is defined by the p_send_wr parameter.\r
3275 *\r
3276 * SEE ALSO\r
3277 *       ib_send_wr_t\r
3278 *****/\r
3279 \r
3280 \r
3281 /****f* Access Layer/ib_post_recv\r
3282 * NAME\r
3283 *       ib_post_recv\r
3284 *\r
3285 * DESCRIPTION\r
3286 *       This routine posts a work request to the receive queue of a queue pair.\r
3287 *\r
3288 * SYNOPSIS\r
3289 */\r
3290 AL_EXPORT ib_api_status_t AL_API\r
3291 ib_post_recv(\r
3292         IN              const   ib_qp_handle_t                          h_qp,\r
3293         IN                              ib_recv_wr_t* const                     p_recv_wr,\r
3294                 OUT                     ib_recv_wr_t                            **pp_recv_failure OPTIONAL );\r
3295 /*\r
3296 * PARAMETERS\r
3297 *       h_qp\r
3298 *               [in] The queue pair to which this work request is being submitted.\r
3299 *\r
3300 *       p_recv_wr\r
3301 *               [in] A reference to the head of the work request list.\r
3302 *\r
3303 *       pp_recv_failure\r
3304 *               [out] If the post receive operation failed, this references the work\r
3305 *               request in the p_recv_wr list where the first failure occurred.\r
3306 *               This parameter may be NULL if only a single work request is being\r
3307 *               posted to the QP.\r
3308 *\r
3309 * RETURN VALUES\r
3310 *       IB_SUCCESS\r
3311 *               All work requests were successfully posted.\r
3312 *\r
3313 *       IB_INVALID_QP_HANDLE\r
3314 *               The queue pair handle was invalid.\r
3315 *\r
3316 *       IB_INVALID_PARAMETER\r
3317 *               A reference to the receive work request list was not provided.\r
3318 *\r
3319 *       IB_INSUFFICIENT_RESOURCES\r
3320 *               The number of posted work requests exceed the current depth available\r
3321 *               on the receive queue.\r
3322 *\r
3323 *       IB_INVALID_WR_TYPE\r
3324 *               The work request type was invalid.\r
3325 *\r
3326 *       IB_INVALID_QP_STATE\r
3327 *               The current queue pair state does not allow posting receives.\r
3328 *\r
3329 * NOTES\r
3330 *       This routine posts a work request to the receive queue of a queue pair.\r
3331 *       The type of work to perform is defined by the p_recv_wr parameter.  This\r
3332 *       call is used to post data buffers to receive incoming message sends.\r
3333 *\r
3334 * SEE ALSO\r
3335 *       ib_recv_wr_t\r
3336 *****/\r
3337 \r
3338 \r
3339 /****f* Access Layer/ib_send_mad\r
3340 * NAME\r
3341 *       ib_send_mad\r
3342 *\r
3343 * DESCRIPTION\r
3344 *       This routine posts a work request to the send queue of a queue pair.\r
3345 *\r
3346 * SYNOPSIS\r
3347 */\r
3348 AL_EXPORT ib_api_status_t AL_API\r
3349 ib_send_mad(\r
3350         IN              const   ib_mad_svc_handle_t                     h_mad_svc,\r
3351         IN                              ib_mad_element_t* const         p_mad_element_list,\r
3352                 OUT                     ib_mad_element_t                        **pp_mad_failure OPTIONAL );\r
3353 /*\r
3354 * PARAMETERS\r
3355 *       h_mad_svc\r
3356 *               [in] The MAD service to which this work request is being submitted.\r
3357 *\r
3358 *       p_mad_element_list\r
3359 *               [in] A list of MAD elements that will be posted to the send queue.\r
3360 *\r
3361 *       pp_mad_failure\r
3362 *               [out] If the send MAD operation failed, this references the MAD\r
3363 *               element in the p_mad_element_list where the first failure occurred.\r
3364 *               This parameter is optional if p_mad_element_list contains a single\r
3365 *               MAD.\r
3366 *\r
3367 * RETURN VALUES\r
3368 *       IB_SUCCESS\r
3369 *               The MAD element list was successfully posted.\r
3370 *\r
3371 *       IB_INVALID_HANDLE\r
3372 *               The MAD service handle was invalid.\r
3373 *\r
3374 *       IB_INVALID_PARAMETER\r
3375 *               A reference to the MAD element list was not provided.\r
3376 *\r
3377 *       IB_INSUFFICIENT_RESOURCES\r
3378 *               There were insufficient resources currently available to complete\r
3379 *               the request.\r
3380 *\r
3381 *       IB_INVALID_SETTING\r
3382 *               The MAD element RMPP version is not supported by the access layer.\r
3383 *\r
3384 *       IB_INSUFFICIENT_MEMORY\r
3385 *               There was insufficient memory to complete the request.\r
3386 *\r
3387 * NOTES\r
3388 *       This routine posts a work request to send a MAD on a MAD service.  All\r
3389 *       MAD elements successfully posted by this call are under the control of\r
3390 *       the access layer and should not be accessed until the send operation\r
3391 *       completes.\r
3392 *\r
3393 *       In order to guarantee that MADs sent by separate clients do not use the\r
3394 *       same transaction ID, the access layer reserves the upper 32-bits of the\r
3395 *       TID on all unsolicited MADs.  MADs sent with the response bit set will\r
3396 *       not have their transaction ID's modified.  Unsolicited MADs will have the\r
3397 *       upper 32-bits of their TID set to an access layer generated client ID.\r
3398 *\r
3399 * SEE ALSO\r
3400 *       ib_mad_element_t, ib_cancel_mad\r
3401 *****/\r
3402 \r
3403 \r
3404 /****f* Access Layer/ib_cancel_mad\r
3405 * NAME\r
3406 *       ib_cancel_mad\r
3407 *\r
3408 * DESCRIPTION\r
3409 *       This routine cancels a pending send transaction to a MAD service.\r
3410 *\r
3411 * SYNOPSIS\r
3412 */\r
3413 AL_EXPORT ib_api_status_t AL_API\r
3414 ib_cancel_mad(\r
3415         IN              const   ib_mad_svc_handle_t                     h_mad_svc,\r
3416         IN                              ib_mad_element_t* const         p_mad_element );\r
3417 /*\r
3418 * PARAMETERS\r
3419 *       h_mad_svc\r
3420 *               [in] The MAD service to which the send operation was directed.\r
3421 *\r
3422 *       p_mad_element\r
3423 *               [in] A handle to a sent MAD element.\r
3424 *\r
3425 * RETURN VALUES\r
3426 *       IB_SUCCESS\r
3427 *               The requested MAD transaction was located and canceled.\r
3428 *\r
3429 *       IB_INVALID_PARAMETER\r
3430 *               A reference to the MAD element list was not provided.\r
3431 *\r
3432 *       IB_NOT_FOUND\r
3433 *               The requested transaction was not located or had already completed.\r
3434 *\r
3435 * NOTES\r
3436 *       This routine cancels a pending send transaction to a MAD service.  If\r
3437 *       the request is successfully located and has not yet completed, it will\r
3438 *       be completed with its status set to IB_CANCELED.  The canceled operation\r
3439 *       will be returned to the user through the normal MAD completion callback.\r
3440 *       If the send transaction has already completed, this call will return\r
3441 *       IB_NOT_FOUND.\r
3442 *\r
3443 * SEE ALSO\r
3444 *       ib_send_mad\r
3445 *****/\r
3446 \r
3447 \r
3448 /****f* Access Layer/ib_peek_cq\r
3449 * NAME\r
3450 *       ib_peek_cq\r
3451 *\r
3452 * DESCRIPTION\r
3453 *       Returns the number of entries currently on the completion queue.\r
3454 *\r
3455 * SYNOPSIS\r
3456 */\r
3457 AL_EXPORT ib_api_status_t AL_API\r
3458 ib_peek_cq(\r
3459         IN              const   ib_cq_handle_t                          h_cq,\r
3460         OUT                             uint32_t* const                         p_n_cqes );\r
3461 /*\r
3462 * PARAMETERS\r
3463 *       h_cq\r
3464 *               [in] Handle to the completion queue to peek.\r
3465 *\r
3466 *       p_n_cqes\r
3467 *               [out] Upon successful completion of this call, contains the number\r
3468 *               of completion queue entries currently on the completion queue.\r
3469 *\r
3470 * RETURN VALUES\r
3471 *       IB_SUCCESS\r
3472 *               The peek operation completed successfully.\r
3473 *\r
3474 *       IB_INVALID_CQ_HANDLE\r
3475 *               The completion queue handle was invalid.\r
3476 *\r
3477 *       IB_INVALID_PARAMETER\r
3478 *               A reference to the completion queue entry count was not provided.\r
3479 *\r
3480 *       IB_UNSUPPORTED\r
3481 *               This operation is not supported by the channel adapter.\r
3482 *\r
3483 * NOTES\r
3484 *       The value returned is a snapshot of the number of compleiton queue\r
3485 *       entries curently on the completion queue.  Support for this operation\r
3486 *       is optional by a channel adapter vendor.\r
3487 *\r
3488 * SEE ALSO\r
3489 *       ib_create_cq, ib_poll_cq, ib_rearm_cq, ib_rearm_n_cq\r
3490 *****/\r
3491 \r
3492 \r
3493 /****f* Access Layer/ib_poll_cq\r
3494 * NAME\r
3495 *       ib_poll_cq\r
3496 *\r
3497 * DESCRIPTION\r
3498 *       Checks a completion queue for completed work requests.\r
3499 *\r
3500 * SYNOPSIS\r
3501 */\r
3502 AL_EXPORT ib_api_status_t AL_API\r
3503 ib_poll_cq(\r
3504         IN              const   ib_cq_handle_t                          h_cq,\r
3505         IN      OUT                     ib_wc_t** const                         pp_free_wclist,\r
3506                 OUT                     ib_wc_t** const                         pp_done_wclist );\r
3507 /*\r
3508 * PARAMETERS\r
3509 *       h_cq\r
3510 *               [in] A handle to a completion queue to check for completions on.\r
3511 *\r
3512 *       pp_free_wclist\r
3513 *               [in/out] On input, a list of work completion structures provided by\r
3514 *               the client.  These are used to report completed work requests through\r
3515 *               the pp_done_wclist.\r
3516 *\r
3517 *               On output, this contains the list of work completions structures for\r
3518 *               which no work completion was found.\r
3519 *\r
3520 *       pp_done_wclist\r
3521 *               [out] A list of work completions retrieved from the completion queue.\r
3522 *\r
3523 * RETURN VALUES\r
3524 *       IB_SUCCESS\r
3525 *               The poll operation completed successfully.  If the work completion\r
3526 *               structures referenced by the pp_free_wclist list is empty there are\r
3527 *               potentially more completions available to retrieve.\r
3528 *\r
3529 *       IB_INVALID_PARAMETER\r
3530 *               A reference to the free or done work completion list was not provided.\r
3531 *\r
3532 *       IB_INVALID_CQ_HANDLE\r
3533 *               The completion queue handle was invalid.\r
3534 *\r
3535 *       IB_NOT_FOUND\r
3536 *               No completed work requests were removed from the completion queue.\r