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