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