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