[MTHCA\MT23108\IBAL] change to support TRAP and TRAP_REPRESS
[mirror/winof/.git] / inc / iba / ib_ci.h
1 /*\r
2  * Copyright (c) 2005 SilverStorm Technologies.  All rights reserved.\r
3  * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. \r
4  *\r
5  * This software is available to you under the OpenIB.org BSD license\r
6  * below:\r
7  *\r
8  *     Redistribution and use in source and binary forms, with or\r
9  *     without modification, are permitted provided that the following\r
10  *     conditions are met:\r
11  *\r
12  *      - Redistributions of source code must retain the above\r
13  *        copyright notice, this list of conditions and the following\r
14  *        disclaimer.\r
15  *\r
16  *      - Redistributions in binary form must reproduce the above\r
17  *        copyright notice, this list of conditions and the following\r
18  *        disclaimer in the documentation and/or other materials\r
19  *        provided with the distribution.\r
20  *\r
21  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,\r
22  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\r
23  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\r
24  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS\r
25  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN\r
26  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
27  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r
28  * SOFTWARE.\r
29  *\r
30  * $Id$\r
31  */\r
32 \r
33 \r
34 #if !defined(__IB_CI_H__)\r
35 #define __IB_CI_H__\r
36 \r
37 #include <iba/ib_types.h>\r
38 \r
39 \r
40 #ifdef __cplusplus\r
41 extern "C"\r
42 {\r
43 #endif  /* __cplusplus */\r
44 \r
45 \r
46 /****h* IB_API/Verbs\r
47 * NAME\r
48 *       Verbs -- Verbs implements the hardware and software glue to the OS layer.\r
49 * COPYRIGHT\r
50 *       Copyright© 2001 Intel Corporation - All Rights Reserved.\r
51 * DESCRIPTION\r
52 *       The Verbs API definition defines the interface mechanism between an IHV\r
53 *       supplied driver component. It implements verbs functionality as defined\r
54 *       Volume 1, of the InfiniBand(tm) specifications.\r
55 * AUTHOR\r
56 *       Intel Corporation\r
57 * CREATION DATE\r
58 *       XX.XX.XX\r
59 * NOTES\r
60 *       Evolving Spec!!\r
61 *       Invalid Handle checks are a mere signature checks in kernel mode. Hence\r
62 *       passing invalid pointer would lead to panics in the kernel. For user mode\r
63 *       These are verified for most verbs that need to take a kernel transition.\r
64 *       Verbs those are entirely done in user mode that would affect speed path\r
65 *       do not perform consistency checks. So invalid pointers would lead to\r
66 *       application crash with core dumps.\r
67 ***********\r
68 */\r
69 \r
70 \r
71 /*\r
72  * Version that identifies this version of the header file for interface\r
73  * definition.\r
74  */\r
75 #define VERBS_MAJOR_VER                 (0x0001)\r
76 #define VERBS_MINOR_VER                 (0x0003)\r
77 \r
78 #define VERBS_VERSION                   (((VERBS_MAJOR_VER) << 16) | (VERBS_MINOR_VER))\r
79 #define MK_VERBS_VERSION(maj,min)       ((((maj) & 0xFFFF) << 16) | \\r
80                                                                         ((min) & 0xFFFF))\r
81 \r
82 /*\r
83  * TODO: The in and out buffers should be separated (usage can still make\r
84  * both point to the same actual memory region.\r
85  */\r
86 /****s* Verbs/ci_umv_buf_t\r
87 * NAME\r
88 *       ci_umv_buf_t -- Vendor specific structure to facilitate user mode IO\r
89 * DESCRIPTION\r
90 *       This structure is provided to assist the vendor specific user mode\r
91 *       library to exchange information with its kernel mode driver. The\r
92 *       user mode InfiniBand(tm) Access Layer will call the vendor specific\r
93 *       module before a call is made to the kernel mode driver. The kernel mode\r
94 *       driver is expected to know the format and data in the p_inout_buf,\r
95 *       and copy any necessary data that must be handed to the user mode\r
96 *       vendor library.\r
97 * PURPOSE\r
98 *       command\r
99 *               A command code that is understood by the vendor specific kernel\r
100 *               mode driver.\r
101 *       p_inout_buf\r
102 *               The user mode component of the vendor specific library allocates\r
103 *               this memory and passes information in this buffer. vendor is expected\r
104 *               to set both the input and output buffer sizes appropriately.\r
105 *               This information is required since the kernel mode proxy that passes\r
106 *               this buffer to the kernel mode vendor specific library will copy the\r
107 *               content of this buffer to a kernel mode buffer. The kernel mode\r
108 *               vendor specific driver would copy the data that needs to be returned\r
109 *               to the user mode component, and set the output size appropriately\r
110 *               so that the proxy can now copy the data back to user mode buffer.\r
111 *\r
112 *               In the Infiniband Access Layer, it is important to know the\r
113 *               usage of umv_buf and whether the contents of the p_inout_buf\r
114 *               can have embedded user-mode pointers. When invoked from an\r
115 *               arbitrary thread context, Vendor driver can NOT access user-mode\r
116 *               pointers of a user-process.\r
117 *       input_size\r
118 *               Size of the input buffer, must be set by the user mode vendor\r
119 *               specific library.\r
120 *       output_size\r
121 *               Size of the output buffer. Must be set by the user mode component\r
122 *               to specify the maximum size of the data expected from its kernel\r
123 *               mode driver. The kernel mode driver would set the size to the exact\r
124 *               size that needs to be returned to its user mode counterpart.\r
125 *       status\r
126 *               Indicates the status of the operation from the kernel mode vendor\r
127 *               specific driver. The caller is supposed to initialize it appropriately\r
128 *               to identify if an operation succeded, or failed. For e.g. when\r
129 *               the user mode library is called after a resource creation, the user\r
130 *               mode vendor specific code must be able to identify if there is\r
131 *               post processing required, or if any resource allocation failed.\r
132 * SOURCE\r
133 */\r
134 typedef struct _umv_buf\r
135 {\r
136         uint32_t                command;\r
137         uint32_t                status;\r
138         uint32_t                input_size;\r
139         uint32_t                output_size;\r
140         void* __ptr64   p_inout_buf;\r
141 } ci_umv_buf_t;\r
142 /******/\r
143 \r
144 /****f* Verbs/ci_completion_cb_t\r
145 * NAME\r
146 *       ci_completion_cb_t -- Completion Notification callback.\r
147 * SYNOPSIS\r
148 */\r
149 \r
150 typedef void\r
151 (*ci_completion_cb_t)(\r
152         IN      void    *cq_context );\r
153 \r
154 /*\r
155 * DESCRIPTION\r
156 *       This function prototype indicates the parameter passed to ci_open_ca()\r
157 *       to receive completion callbacks.\r
158 * PARAMETERS\r
159 *       cq_context\r
160 *               [in] Completion queue context passed during the ci_create_cq\r
161 * RETURN VALUE\r
162 *       None\r
163 * NOTES\r
164 *       The consumer only gets the cq_context and ca_context. It is the client\r
165 *       responsibility to store the cq_handle in the context after the creation\r
166 *       time. So it can call ci_poll_cq() after the arrival of the notification.\r
167 * SEE ALSO\r
168 *       ci_open_ca, ci_create_cq\r
169 ******\r
170 */\r
171 \r
172 \r
173 /****f* Verbs/ci_async_event_cb_t\r
174 * NAME\r
175 *       ci_async_event_cb_t\r
176 *\r
177 * DESCRIPTION\r
178 *       Asynchronous event notification routine.\r
179 *\r
180 * SYNOPSIS\r
181 */\r
182 typedef void\r
183 (*ci_async_event_cb_t)(\r
184         IN      const   ib_event_rec_t* const                   p_event_record );\r
185 /*\r
186 * PARAMETERS\r
187 *       p_event_record\r
188 *               [in] Information describing the type of event that has occurred.\r
189 *\r
190 * NOTES\r
191 *       This routine is called when an asynchronous event is generated by a\r
192 *       channel adapter.  The event notification record passed has relevant\r
193 *       information on the type of the event, the source that caused the event,\r
194 *       and the context associated.\r
195 *****/\r
196 \r
197 \r
198 /****f* Verbs/ci_open_ca\r
199 * NAME\r
200 *       ci_open_ca -- open and possibly obtain a handle to access the HCA.\r
201 * SYNOPSIS\r
202 */\r
203 \r
204 typedef ib_api_status_t\r
205 (*ci_open_ca) (\r
206         IN              const   ib_net64_t                                      ca_guid,\r
207         IN              const   ci_completion_cb_t                      pfn_completion_cb,\r
208         IN              const   ci_async_event_cb_t                     pfn_async_event_cb,\r
209         IN              const   void* const                                     ca_context,\r
210                 OUT                     ib_ca_handle_t                          *ph_ca );\r
211 /*\r
212 * DESCRIPTION\r
213 *       This routine returns a handle to an open instance of a HCA. Client can call\r
214 *       this routine to retrieve a new open instance. Only one instance of the\r
215 *       open call is active at any time. If a duplicate open is called by the\r
216 *       consumer or any other consumer, it IB_RESOURCE_BUSY error status is\r
217 *       returned.\r
218 * PARAMETERS\r
219 *       ca_guid\r
220 *               [in] The HCA adapter's EUI64 identifier. Clients would use other\r
221 *               enumeration API's to locate all available adapters and their\r
222 *               guids in a system, e.g. GetCaGuids(), maintained by the IB\r
223 *               Access Layer. User mode consumers also have the same mechanism\r
224 *               to retrieve this information.\r
225 *       pfn_completion_cb\r
226 *               [in] Completion Handler, one per open instance.\r
227 *       pfn_async_event_cb\r
228 *               [in] Asynchronous event handler, one per open instance.\r
229 *       ca_context\r
230 *               [in] Verbs consumer supplied value, which is returned on calls to\r
231 *               handlers which in turn is used by clients to identify the\r
232 *               open instance.\r
233 *       ph_ca\r
234 *               [out] Pointer to a handle to the newly open instance of the CA returned\r
235 *               by the Verbs Provider.\r
236 *\r
237 * RETURN VALUE\r
238 *       IB_SUCCESS\r
239 *               The HCA is successfully opened and returned handle is valid.\r
240 *       IB_INSUFFICIENT_RESOURCES\r
241 *               Insufficient resources to satisfy request.\r
242 *       IB_INVALID_PARAMETER\r
243 *               Callback routine are not provided, GUID value is zero, or ph_ca is NULL\r
244 *       IB_RESOURCE_BUSY\r
245 *               The interface is already open by another consumer.\r
246 *       IB_NOT_FOUND\r
247 *               ca_guid passed is not valid\r
248 *\r
249 * SEE ALSO\r
250 *       ci_query_ca, ci_modify_ca, ci_close_ca\r
251 *********/\r
252 \r
253 \r
254 /****f* Verbs/ci_um_open_ca\r
255 * NAME\r
256 *       ci_um_open_ca -- Create a CA context for use by user-mode processes.\r
257 * SYNOPSIS\r
258 */\r
259 typedef ib_api_status_t\r
260 (*ci_um_open_ca_t) (\r
261         IN              const   ib_ca_handle_t                          h_ca,\r
262         IN      OUT                     ci_umv_buf_t* const                     p_umv_buf,\r
263                 OUT                     ib_ca_handle_t* const           ph_um_ca );\r
264 /*\r
265 * DESCRIPTION\r
266 *       This routine is used called on behalf of a user-mode application to\r
267 *       establish a per-CA context in user-mode.\r
268 *\r
269 * PARAMETERS\r
270 *       h_ca\r
271 *               [in] Handle returned by an earlier call to ci_open_ca()\r
272 *       p_umv_buf\r
273 *               [in/out] Vendor specific parameter to support user mode IO.\r
274 *       ph_um_ca\r
275 *               [out] Handle to pass into ci_um_close_ca call to free any kernel\r
276 *               resources allocated for the user-mode appliation.\r
277 *\r
278 * RETURN VALUE\r
279 *       IB_SUCCESS\r
280 *               The user-mode context information is returned successfully.\r
281 *       IB_INSUFFICIENT_MEMORY\r
282 *               The size of the p_ca_attr buffer, specified through p_size, is\r
283 *               insufficient to store all of the CA attribute information.\r
284 *       IB_INVALID_CA_HANDLE\r
285 *               h_ca is invalid\r
286 *       IB_INVALID_PARAMETER\r
287 *               The p_umv_buf parameters are insufficient to complete the request.\r
288 *\r
289 * SEE ALSO\r
290 *       ci_query_ca, ci_modify_ca, ci_close_ca\r
291 *********/\r
292 \r
293 \r
294 /****f* Verbs/ci_query_ca\r
295 * NAME\r
296 *       ci_query_ca -- Query the attributes of the HCA\r
297 * SYNOPSIS\r
298 */\r
299 \r
300 typedef ib_api_status_t\r
301 (*ci_query_ca) (\r
302         IN              const   ib_ca_handle_t                          h_ca,\r
303                 OUT                     ib_ca_attr_t                            *p_ca_attr OPTIONAL,\r
304         IN      OUT                     uint32_t                                        *p_size,\r
305         IN      OUT                     ci_umv_buf_t                            *p_umv_buf OPTIONAL );\r
306 /*\r
307 * DESCRIPTION\r
308 *       This routine retrieves vital information about this hca. It returns\r
309 *       necessary information about HCA guid, port guids, LID's assigned by\r
310 *       the master SM. Clients can use this information to communicate with the\r
311 *       Master SM node to perform path queries etc.\r
312 * PARAMETERS\r
313 *       h_ca\r
314 *               [in] Handle returned by an earlier call to ci_open_ca()\r
315 *       p_ca_attr\r
316 *               [out] CA attribute of this Host Channel adapter\r
317 *       p_size\r
318 *               [in/out] On input, this references the size of the data buffer\r
319 *               referenced by the p_ca_attr parameter.\r
320 *               On output, the number of bytes used or needed to copy all CA\r
321 *               attribute information.\r
322 *       p_umv_buf\r
323 *               [in out] Vendor specific parameter to support user mode IO.\r
324 * RETURN VALUE\r
325 *       IB_SUCCESS\r
326 *               The attribute structure is returned completely.\r
327 *       IB_INSUFFICIENT_MEMORY\r
328 *               The size of the p_ca_attr buffer, specified through p_size, is\r
329 *               insufficient to store all of the CA attribute information.\r
330 *       IB_INVALID_CA_HANDLE\r
331 *               h_ca is invalid\r
332 *       IB_INVALID_PARAMETER\r
333 *               p_size is NULL.\r
334 * NOTES\r
335 *       Users may obtain the size of the data buffer required to obtain the\r
336 *       CA attributes by calling this function with p_ca_attr set to NULL.\r
337 *       The channel interface will then return the necessary size in the\r
338 *       variable referenced by the p_size parameter.  The caller can then allocate\r
339 *       exact size and call this routine again. No partial information is returned\r
340 *       if the size is not sufficient.\r
341 * SEE ALSO\r
342 *       ci_open_ca, ci_modify_ca\r
343 ********/\r
344 \r
345 /****f* Verbs/ci_modify_ca\r
346 * NAME\r
347 *       ci_modify_ca -- Modify port attributes and error counters\r
348 * SYNOPSIS\r
349 */\r
350 \r
351 typedef ib_api_status_t\r
352 (*ci_modify_ca) (\r
353         IN      const ib_ca_handle_t            h_ca,\r
354         IN      const uint8_t                           port_num,\r
355         IN      const ib_ca_mod_t                       ca_mod,\r
356         IN      const ib_port_attr_mod_t        *p_port_attr_mod );\r
357 /*\r
358 * DESCRIPTION\r
359 *       Modifies either the P_KEY/Q_KEY violation counters, or sets the capability\r
360 *       mask in the port attributes. This is effectively translated to PORTINFO\r
361 *       values responded later when a MAD from SM or another node arrives to\r
362 *       retrieve port related attributes.\r
363 *\r
364 * PARAMETERS\r
365 *       h_ca\r
366 *               [in] Handle returned by previous call to ci_open_ca()\r
367 *       port_num\r
368 *               [in] Port number, which needs to be modified.\r
369 *       ca_mod\r
370 *               [in] Command mask to perform operations on.\r
371 *       p_port_attr_mod\r
372 *               [in] port attribute which needs this change to be performed.\r
373 *               if the capability bit is set, then that corresponding\r
374 *               port capability is turned on.\r
375 * RETURN VALUE\r
376 *       IB_SUCCESS\r
377 *               Modify port attributes was performed\r
378 *       IB_INVALID_PORT\r
379 *               Invalid port number supplied in port_att.\r
380 *       IB_INVALID_PARAMETER\r
381 *               Unknown Command supplied in port_attr.\r
382 *       IB_UNSUPPORTED\r
383 *               Optional Q_KEY and P_KEY violation counters are not supported.\r
384 *       IB_INVALID_CA_HANDLE\r
385 *               h_ca is invalid\r
386 * NOTES\r
387 * No ownership checks are performed in the Verbs Provider Driver.\r
388 * All such permission checks are to be performed by the IB access layer\r
389 * before passing requests down to the HCA driver. These operations can be\r
390 * performed only by the special QP owner. Either the QP0 or QP1. Since port\r
391 * attributes is really maintained by the QP0 for SMA to respond with correct\r
392 * values, but the agent capability is really a QP1 functionality.\r
393 * SEE ALSO\r
394 *       ci_open_ca, ci_query_ca, ci_close_ca\r
395 */\r
396 /********/\r
397 \r
398 /****f* Verbs/ci_close_ca\r
399 * NAME\r
400 *       ci_close_ca -- Close access to adapter via this h_ca\r
401 * SYNOPSIS\r
402 */\r
403 \r
404 typedef ib_api_status_t\r
405 (*ci_close_ca) (\r
406         IN              ib_ca_handle_t  h_ca );\r
407 /*\r
408 * DESCRIPTION\r
409 *       This routine is called when the client no longer wishes to use HCA\r
410 *       resources obtained via this h_ca. All resources allocated as part\r
411 *       this handle during the ci_open_ca are destroyed.\r
412 * PARAMETERS\r
413 *       h_ca\r
414 *               [in] CA handle returned via the ci_open_ca() call.\r
415 * RETURN VALUE\r
416 *       IB_SUCCESS\r
417 *               The intend to destroy is registered. No further calls for\r
418 *               completion or async event will be sent to this instance. When it is\r
419 *               appropriate to destroy this instance, the event h_kevent is signaled.\r
420 *       IB_RESOURCE_BUSY\r
421 *               Some resource allocated via this handle is not freed.\r
422 *       IB_INVALID_CA_HANDLE\r
423 *               h_ca is invalid\r
424 * NOTES\r
425 *       This call cannot be called from any of the notification functions invoked\r
426 *       by the Verbs driver. For e.g. the completion handler or the async error\r
427 *       callback provided during the ci_open_ca() call. The call will block until\r
428 *       all references to this adapter object is closed which includes all the\r
429 *       pending callbacks returning back to the verbs provider driver.\r
430 *\r
431 *       Resources allocated during the ci_open_ca() is deallocated. Other resource\r
432 *       cleanup are responsibility of the consumer .\r
433 * SEE ALSO\r
434 *       ci_open_ca\r
435 ********/\r
436 \r
437 /****f* Verbs/ci_um_close_ca_t\r
438 * NAME\r
439 *       ci_um_close_ca_t -- Close user-mode access to adapter via this h_ca\r
440 * SYNOPSIS\r
441 */\r
442 typedef void\r
443 (*ci_um_close_ca_t) (\r
444         IN                              ib_ca_handle_t                          h_ca,\r
445         IN                              ib_ca_handle_t                          h_um_ca );\r
446 /*\r
447 * DESCRIPTION\r
448 *       This routine is called when the client no longer wishes to use HCA\r
449 *       resources obtained via this h_ca. All resources allocated as part\r
450 *       this handle during the ci_um_open_ca are destroyed.\r
451 * PARAMETERS\r
452 *       h_ca\r
453 *               [in] CA handle returned via the ci_open_ca() call.\r
454 *       h_um_ca\r
455 *               [in] CA handle returned via the ci_um_open_ca() call.\r
456 *\r
457 * RETURN VALUE\r
458 *       This funtion does not return a value.\r
459 * NOTES\r
460 *       This call is invoked from the context of a UM application when such an\r
461 *       appliation closes the HCA in user-mode.\r
462 *\r
463 *       Resources allocated during the ci_um_open_ca() are deallocated.\r
464 *\r
465 * SEE ALSO\r
466 *       ci_um_open_ca\r
467 ********/\r
468 \r
469 /****f* Verbs/ci_allocate_pd\r
470 * NAME\r
471 *       ci_allocate_pd -- Allocate a protection domain for this adapter.\r
472 * SYNOPSIS\r
473 */\r
474 \r
475 typedef ib_api_status_t\r
476 (*ci_allocate_pd) (\r
477         IN              const   ib_ca_handle_t                          h_ca,\r
478         IN              const   ib_pd_type_t                            type,\r
479                 OUT                     ib_pd_handle_t                          *ph_pd,\r
480         IN      OUT                     ci_umv_buf_t                            *p_umv_buf OPTIONAL );\r
481 /*\r
482 * DESCRIPTION\r
483 *       This routine allocates a protection domain handle, which is later\r
484 *       used to create QP's, Register Memory Regions, Bind Memory Windows\r
485 *       and address vectors. Protection domain has no InfiniBand architectural\r
486 *       attributes but the OS implements policy on its usage and allocation.\r
487 * PARAMETERS\r
488 *       h_ca\r
489 *               [in] Handle returned by ci_open_ca()\r
490 *\r
491 *       type\r
492 *               [in] Type of the protection domain.  CA vendors may use this\r
493 *               information to optimize how the PD is allocated.\r
494 *\r
495 *       ph_pd\r
496 *               [out] The handle to the newly created protection domain\r
497 *\r
498 *       p_umv_buf\r
499 *               [in/out] Vendor specific parameter to support user mode IO.\r
500 *\r
501 * RETURN VALUE\r
502 *       IB_SUCCESS\r
503 *               PD is successfully allocated and the ph_pd is valid.\r
504 *\r
505 *       IB_INSUFFICIENT_RESOURCES\r
506 *               No more PD's available for this adapter.\r
507 *\r
508 *       IB_INVALID_CA_HANDLE\r
509 *               HCA handle is not valid\r
510 *\r
511 * SEE ALSO\r
512 *       ci_deallocate_pd\r
513 *******/\r
514 \r
515 /****f* Verbs/ci_deallocate_pd\r
516 * NAME\r
517 *       ci_deallocate_pd -- Deallocate a protection domain object.\r
518 * SYNOPSIS\r
519 */\r
520 \r
521 typedef ib_api_status_t\r
522 (*ci_deallocate_pd) (\r
523         IN              ib_pd_handle_t          h_pd );\r
524 \r
525 /*\r
526 * DESCRIPTION\r
527 *       This routine deallocates a pd that is allocated via the ci_allocate_pd()\r
528 *       call. The PD cannot be deallocated if it is still bound to a QP, any memory\r
529 *       region, memory window or address vector.\r
530 * PARAMETERS\r
531 *       h_pd\r
532 *               [in] Handle allocated via the ci_allocate_pd()\r
533 * RETURN VALUE\r
534 *       IB_SUCCESS\r
535 *               PD is freed successfully\r
536 *       IB_INVALID_PD_HANDLE\r
537 *               pd_handle is invalid\r
538 *       IB_RESOURCE_BUSY\r
539 *               PD is probably still bound to some resource\r
540 * SEE ALSO\r
541 *       ci_allocate_pd\r
542 *******\r
543 */\r
544 \r
545 \r
546 /****f* Verbs/ci_create_av\r
547 * NAME\r
548 *       ci_create_av -- Create an address vector for use in UD.\r
549 * SYNOPSIS\r
550 */\r
551 \r
552 typedef ib_api_status_t\r
553 (*ci_create_av) (\r
554         IN              const   ib_pd_handle_t                          h_pd,\r
555         IN              const   ib_av_attr_t                            *p_av_attr,\r
556                 OUT                     ib_av_handle_t                          *ph_av,\r
557         IN      OUT                     ci_umv_buf_t                            *p_umv_buf OPTIONAL );\r
558 \r
559 /*\r
560 * DESCRIPTION\r
561 *       This routine creates an address vector for use in unreliable datagram\r
562 *       queue pairs. The information necessary to create the address vector\r
563 *       handle is supplied in the ib_av_attr_t parameter.\r
564 * PARAMETERS\r
565 *       h_pd\r
566 *               [in] Protection domain to which this av is associated.\r
567 *       p_av_attr\r
568 *               [in] Parameters to create the address vector handle\r
569 *       ph_av\r
570 *               [out] Handle to use for datagram sends.\r
571 *       p_umv_buf\r
572 *               [in out] Vendor specific parameter to support user mode IO.\r
573 * RETURN VALUE\r
574 *       IB_SUCCESS\r
575 *               The create operation was successful\r
576 *       IB_INSUFFICIENT_RESOURCES\r
577 *               No more address handles are available\r
578 *       IB_INVALID_PD_HANDLE\r
579 *               The specified protection domain handle is invalid\r
580 *       IB_INVALID_PORT\r
581 *               Invalid port number supplied.\r
582 *       IB_INVALID_PARAMETER\r
583 *               One of the p_av_attr or p_av_attr was NULL.\r
584 * NOTES\r
585 *       The values in the p_av_attr is not validated for correctness. The values\r
586 *       in the attribute such as port number, protection domain etc are also\r
587 *       validated during processing by the channel adapter. If the attribute\r
588 *       validation fails a processing error IB_WCS_LOCAL_OP_ERR.\r
589 * SEE ALSO\r
590 *       ci_allocate_pd\r
591 ********/\r
592 \r
593 /****f* Verbs/ci_query_av\r
594 * NAME\r
595 *       ci_query_av -- Obtain the address vector associated with the handle\r
596 * SYNOPSIS\r
597 */\r
598 \r
599 typedef ib_api_status_t\r
600 (*ci_query_av) (\r
601         IN              const   ib_av_handle_t                          h_av,\r
602                 OUT                     ib_av_attr_t                            *p_av_attr,\r
603                 OUT                     ib_pd_handle_t                          *ph_pd,\r
604         IN      OUT                     ci_umv_buf_t                            *p_umv_buf OPTIONAL );\r
605 \r
606 /*\r
607 * DESCRIPTION\r
608 *       This routine returns the address vector and pd_handle associated with the\r
609 *       av_handle.\r
610 * PARAMETERS\r
611 *       h_av\r
612 *               [in] Handle to the address vector\r
613 *       p_av_attr\r
614 *               [out] address vector data referred by the av_handle\r
615 *       ph_pd\r
616 *               [out] pd handle associated with the av_handle\r
617 *       p_umv_buf\r
618 *               [in out] Vendor specific parameter to support user mode IO.\r
619 * RETURN VALUE\r
620 *       IB_SUCCESS\r
621 *               returned values are valid\r
622 *       IB_INVALID_AV_HANDLE\r
623 *               The address vector handle was invalid\r
624 *       IB_INVALID_PARAMETER\r
625 *               One of the p_av_attr or ph_pd parameters was NULL.\r
626 *       IB_INVALID_PORT\r
627 *               Invalid port number passed in the Address Vector.\r
628 * SEE ALSO\r
629 *       ci_create_av, ci_modify_av\r
630 *******\r
631 */\r
632 \r
633 /****f* Verbs/ci_modify_av\r
634 * NAME\r
635 *       ci_modify_av -- Change the address vector referred by the av_handle\r
636 * SYNOPSIS\r
637 */\r
638 \r
639 typedef ib_api_status_t\r
640 (*ci_modify_av) (\r
641         IN              const   ib_av_handle_t                          h_av,\r
642         IN              const   ib_av_attr_t                            *p_av_attr,\r
643         IN      OUT                     ci_umv_buf_t                            *p_umv_buf OPTIONAL );\r
644 /*\r
645 * DESCRIPTION\r
646 *       This routine allows a consumer to modify the address information\r
647 *       passed.\r
648 * PARAMETERS\r
649 *       h_av\r
650 *               [in] Address handle that needs to be updated with new info.\r
651 *       p_av_attr\r
652 *               [in] New address vector to associate with the addr_handle.\r
653 *       p_umv_buf\r
654 *               [in out] Vendor specific parameter to support user mode IO.\r
655 * RETURN VALUE\r
656 *       IB_SUCCESS\r
657 *               Operation was successful\r
658 *       IB_INVALID_AV_HANDLE\r
659 *               The address vector handle was invalid\r
660 *       IB_INVALID_PORT\r
661 *               Invalid port number passed in the Address Vector.\r
662 *       IB_INVALID_PARAMETER\r
663 *               The parameter p_av_attr is not valid.\r
664 * NOTES\r
665 *       The values in the p_av_attr is not validated for correctness. The values\r
666 *       in the attribute such as port number, protection domain etc are validated\r
667 *       during processing by the channel adapter. If the attribute validation fails\r
668 *       a processing error IB_WCS_LOCAL_OP_ERR.\r
669 * SEE ALSO\r
670 *       ci_create_av, ci_query_av\r
671 *********\r
672 */\r
673 \r
674 /****f* Verbs/ci_destroy_av\r
675 * NAME\r
676 *       ci_destroy_av -- Destroy the address vector\r
677 * SYNOPSIS\r
678 */\r
679 \r
680 typedef ib_api_status_t\r
681 (*ci_destroy_av) (\r
682         IN      const   ib_av_handle_t          h_av );\r
683 /*\r
684 * DESCRIPTION\r
685 *       This routine destroys the specified address handle. After the routine\r
686 *       returns, this address handle cannot be used to reference the destination.\r
687 * PARAMETERS\r
688 *       h_av\r
689 *               [in] Handle that needs to be destroyed.\r
690 * RETURN VALUE\r
691 *       IB_SUCCESS\r
692 *               Operation was successful.\r
693 *       IB_INVALID_AV_HANDLE\r
694 *               The address vector handle was invalid\r
695 * SEE ALSO\r
696 *       ci_create_av\r
697 *********\r
698 */\r
699 \r
700 /****f* Verbs/ci_create_qp\r
701 * NAME\r
702 *       ci_create_qp -- Create a Queue Pair for the specified HCA\r
703 * SYNOPSIS\r
704 */\r
705 \r
706 typedef ib_api_status_t\r
707 (*ci_create_qp) (\r
708         IN              const   ib_pd_handle_t                          h_pd,\r
709         IN              const   void                                            *qp_context,\r
710         IN              const   ib_qp_create_t                          *p_create_attr,\r
711                 OUT                     ib_qp_attr_t                            *p_qp_attr,\r
712                 OUT                     ib_qp_handle_t                          *ph_qp,\r
713         IN      OUT                     ci_umv_buf_t                            *p_umv_buf OPTIONAL );\r
714 /*\r
715 * DESCRIPTION\r
716 *       A new queue pair is created on the specified HCA. The initial set of\r
717 *       parameters is provided by the qp_create_attr parameter. The newly created\r
718 *       queue pair, with its attributes such as the qp number is returned\r
719 *       in the qp_query_attr structure.\r
720 * PARAMETERS\r
721 *       h_pd\r
722 *               [in] Handle to Protection Domain\r
723 *       qp_context\r
724 *               [in] A user specified context passed in a asynchronous error callback.\r
725 *       p_create_attr\r
726 *               [in] Initial attributes with which the qp must be created.\r
727 *       p_qp_attr\r
728 *               [out] Attributes of the newly created queue pair.\r
729 *       ph_qp\r
730 *               [out] Handle to the queue pair newly created.\r
731 *       p_umv_buf\r
732 *               [in out] Vendor specific parameter to support user mode IO.\r
733 * RETURN VALUE\r
734 *       IB_SUCCESS\r
735 *               The queue pair is successfully created with the provided initial\r
736 *               attributes.\r
737 *       IB_INSUFFICIENT_RESOURCES\r
738 *               Insufficient resources to complete request.\r
739 *       IB_INVALID_PD_HANDLE\r
740 *               pd_handle supplied in the qp_create_attr is invalid\r
741 *       IB_INVALID_CQ_HANDLE\r
742 *               cq_handle supplied for send/receive is invalid.\r
743 *       IB_INVALID_SERVICE_TYPE\r
744 *               Invalid service type.\r
745 *       IB_INVALID_MAX_WRS\r
746 *               Max WRS capacity exceeded\r
747 *       IB_INVALID_MAX_SGE\r
748 *               Max Scatter gather element request exceeds HCA capability\r
749 *       IB_UNSUPPORTED\r
750 *               Unreliable datagram not supported\r
751 *       IB_INVALID_PARAMETER\r
752 *               The parameter p_create_attr is invalid.\r
753 * NOTES\r
754 *       If any of the initial parameters is not valid, the queue pair is not\r
755 *       created. If the routine call is not successful then the contents of\r
756 *       qp_query_attr and qp_handle is undefined.\r
757 * SEE ALSO\r
758 *       ci_create_spl_qp, ci_query_qp, ci_modify_qp, ci_destroy_qp\r
759 ******\r
760 */\r
761 \r
762 /****f* Verbs/ci_create_spl_qp\r
763 * NAME\r
764 *       ci_create_spl_qp -- Create a special queue pair.\r
765 * SYNOPSIS\r
766 */\r
767 \r
768 typedef ib_api_status_t\r
769 (*ci_create_spl_qp) (\r
770         IN              const   ib_pd_handle_t          h_pd,\r
771         IN              const   uint8_t                         port_num,\r
772         IN              const   void                            *qp_context,\r
773         IN              const   ib_qp_create_t          *p_create_attr,\r
774                 OUT                     ib_qp_attr_t            *p_qp_attr,\r
775                 OUT                     ib_qp_handle_t          *ph_qp );\r
776 /*\r
777 * DESCRIPTION\r
778 *       Create and return a handle to for the indicated service type on the\r
779 *       specified port. QP service types can be one of SMI, GSI, Raw IPv6 or\r
780 *       Raw ether type as specified in qp_type_t.\r
781 * PARAMETERS\r
782 *       h_pd\r
783 *               [in] Handle to the PD on which the special queue pair is to be created.\r
784 *       port_num\r
785 *               [in] Port number for which this special queue pair is created.\r
786 *       qp_context\r
787 *               [in] User specified context passed during the async error callback\r
788 *               routine.\r
789 *       p_create_attr\r
790 *               [in] Initial set of attributes with which the queue pair is to be\r
791 *               created.\r
792 *       p_qp_attr\r
793 *               [out] QP attributes after the qp is successfully created.\r
794 *\r
795 *       ph_qp\r
796 *               [out] Handle to the special qp after its creation.\r
797 * RETURN VALUE\r
798 *       IB_SUCCESS\r
799 *               The special queue pair of the requested service type is created.\r
800 *       IB_INSUFFICIENT_RESOURCES\r
801 *               Insufficient resources to satisfy the request.\r
802 *       IB_NOT_FOUND\r
803 *               Indicated port guid is not found on this HCA.\r
804 *       IB_INVALID_CQ_HANDLE\r
805 *               Invalid cq handle passed to send/receive side.\r
806 *       IB_INVALID_MAX_WRS\r
807 *               Max WRS capacity exceeded\r
808 *       IB_INVALID_MAX_SGE\r
809 *               Max Scatter gather element request exceeds HCA capability\r
810 *       IB_RESOURCE_BUSY\r
811 *               Applicable to SMI/GSI qp's. This return code means that the SMI/GSI\r
812 *               QP is already allocated.\r
813 *       IB_INVALID_PD\r
814 *               Invalid protection domain supplied.\r
815 *       IB_INVALID_PORT\r
816 *               Invalid port number supplied.\r
817 *       IB_UNSUPPORTED\r
818 *               Raw datagram unsupported.\r
819 *       IB_INVALID_PARAMETER\r
820 *               The parameter p_create_attr is not valid.\r
821 * NOTES\r
822 *       This verb is privileged and only available in kernel mode. The User mode\r
823 *       clients that need access to SMI/GSI qp's is recommended to do this via\r
824 *       a higher level of abstraction.\r
825 * SEE ALSO\r
826 *       ci_create_qp, ci_query_qp, ci_modify_qp, ci_destroy_qp\r
827 ******\r
828 */\r
829 \r
830 /****f* Verbs/ci_modify_qp\r
831 * NAME\r
832 *       ci_modify_qp -- Modify attributes of the specified QP.\r
833 * SYNOPSIS\r
834 */\r
835 \r
836 typedef ib_api_status_t\r
837 (*ci_modify_qp) (\r
838         IN              const   ib_qp_handle_t                          h_qp,\r
839         IN              const   ib_qp_mod_t                                     *p_modify_attr,\r
840                 OUT                     ib_qp_attr_t                            *p_qp_attr OPTIONAL,\r
841         IN      OUT                     ci_umv_buf_t                            *p_umv_buf OPTIONAL );\r
842 /*\r
843 * DESCRIPTION\r
844 *       This routine is used to modify the qp states or other attributes of the\r
845 *       QP. On successful completion, the requested state transition is performed\r
846 *       and the QP is transitioned to the required state.\r
847 * PARAMETERS\r
848 *       h_qp\r
849 *               [in] Handle to the queue pair whose state is to be modified.\r
850 *       p_modify_attr\r
851 *               [in] Specifies what attributes need to be modified in the qp.\r
852 *       p_qp_attr\r
853 *               [out] QP attributes after the qp is successfully created.\r
854 *       p_umv_buf\r
855 *               [in out] Vendor specific parameter to support user mode IO.\r
856 * RETURN VALUE\r
857 *       IB_SUCCESS\r
858 *               The operation was successful and the QP attributes are modified\r
859 *               to the requested state.\r
860 *       IB_INSUFFICIENT_RESOURCES\r
861 *               Insufficient resources to complete the requested operation.\r
862 *       IB_INVALID_QP_HANDLE\r
863 *               Invalid QP handle was passed.\r
864 *       IB_UNSUPPORTED\r
865 *               Requested operation is not supported, for e.g. Atomic operations.\r
866 *       IB_QP_INVALID_STATE\r
867 *               Invalid state transition request. Current QP state not in allowable\r
868 *               state.\r
869 *       IB_INVALID_PKEY\r
870 *               Pkey specified in modify request not valid entry in P_KEY table. Or\r
871 *               index is out of range.\r
872 *       IB_INVALID_APM_STATE\r
873 *               Invalid automatic path migration state specified in the request.\r
874 *       IB_INVALID_PARAMETER\r
875 *               The parameter p_modify_attr is not valid.\r
876 * NOTES\r
877 *       Refer to Table 79 in chapter 11, Volume 1 of the InfiniBand Specifications.\r
878 * SEE ALSO\r
879 *       ci_create_qp, ci_create_spl_qp, ci_query_qp\r
880 ******\r
881 */\r
882 \r
883 /****f* Verbs/ci_query_qp\r
884 * NAME\r
885 *       ci_query_qp -- Query the current QP attributes\r
886 * SYNOPSIS\r
887 */\r
888 \r
889 typedef ib_api_status_t\r
890 (*ci_query_qp) (\r
891         IN              const   ib_qp_handle_t                          h_qp,\r
892                 OUT                     ib_qp_attr_t* const                     p_qp_attr,\r
893         IN      OUT                     ci_umv_buf_t                            *p_umv_buf OPTIONAL );\r
894 /*\r
895 * DESCRIPTION\r
896 *       This routine queries the current attributes for the QP\r
897 *       corresponding to h_qp. The attributes are returned in p_query_attr.\r
898 *       Depending on the current state of the QP, some of the fields in the\r
899 *       attribute structure may not be valid.\r
900 * PARAMETERS\r
901 *       h_qp\r
902 *               [in] Handle to the QP for which the attributes are being retrieved\r
903 *       p_qp_attr\r
904 *               [out] Pointer to the ib_qp_query_t structure where the current\r
905 *               attributes of the QP is returned.\r
906 *       p_umv_buf\r
907 *               [in out] Vendor specific parameter to support user mode IO.\r
908 * RETURN VALUE\r
909 *       IB_SUCCESS\r
910 *               The values returned in p_qp_attr are valid.\r
911 *       IB_INVALID_QP_HANDLE\r
912 *               The h_qp supplied is not a valid handle.\r
913 *       IB_INVALID_PARAMETER\r
914 *               Parameter p_qp_attr is not valid.\r
915 * SEE ALSO\r
916 *       ci_create_qp\r
917 *****\r
918 */\r
919 \r
920 /****f* Verbs/ci_destroy_qp\r
921 * NAME\r
922 *       ci_destroy_qp -- Destroy the specified Queue Pair.\r
923 * SYNOPSIS\r
924 */\r
925 \r
926 typedef ib_api_status_t\r
927 (*ci_destroy_qp) (\r
928         IN      const   ib_qp_handle_t          h_qp,\r
929         IN      const   uint64_t                        timewait );\r
930 /*\r
931 * DESCRIPTION\r
932 *       Destroys the associated QP. The QP could have outstanding work requests\r
933 *       when this call is made. Any outstanding work requests *SHALL NOT* be\r
934 *       completed after this routine returns.\r
935 * PARAMETERS\r
936 *       h_qp\r
937 *               [in] Handle to the qp that needs to be destroyed.\r
938 *       timewait\r
939 *               [in] Time (in microseconds) at which the QP should leave\r
940 *               the timewait state and can be reused.\r
941 *\r
942 * RETURN VALUE\r
943 *       IB_SUCCESS\r
944 *               The intend to destroy this queue pair is registered and no further\r
945 *               work requests will be processed. When no pending callbacks are in\r
946 *               progress, the destroy_callback function is invoked which marks the\r
947 *               destruction of the resource. The consumer can be guaranteed that\r
948 *               no future callbacks will be propagated on behalf of this resource.\r
949 *       IB_INVALID_QP_HANDLE\r
950 *               The handle passed is invalid.\r
951 *       IB_RESOURCE_BUSY\r
952 *               If the queue pair is a unreliable datagram service type, and\r
953 *               is still bound to a multicast group.\r
954 * NOTES\r
955 *       This call cannot be called from any of the notification functions invoked\r
956 *       by the Verbs driver. For e.g. the completion handler or the async error\r
957 *       callback provided during the ci_open_ca() call. The call will block until\r
958 *       all references to this adapter object is closed which includes all the\r
959 *       pending callbacks returning back to the verbs provider driver.\r
960 *\r
961 *       If the CQ associated with this QP is still not destroyed, the completions\r
962 *       on behalf of this QP can still be pulled via the ci_poll_cq() call. Any\r
963 *       resources allocated by the Channel Interface must be deallocated as part\r
964 *       of this call.\r
965 * SEE ALSO\r
966 *       ci_create_qp, ci_create_spl_qp\r
967 ******\r
968 */\r
969 \r
970 /****f* Verbs/ci_create_cq\r
971 * NAME\r
972 *       ci_create_cq -- Create a completion queue (CQ) on the specified HCA.\r
973 * SYNOPSIS\r
974 */\r
975 \r
976 typedef ib_api_status_t\r
977 (*ci_create_cq) (\r
978         IN              const   ib_ca_handle_t                          h_ca,\r
979         IN              const   void                                            *cq_context,\r
980         IN      OUT                     uint32_t* const                         p_size,\r
981                 OUT                     ib_cq_handle_t                          *ph_cq,\r
982         IN      OUT                     ci_umv_buf_t                            *p_umv_buf OPTIONAL );\r
983 /*\r
984 * DESCRIPTION\r
985 *       The consumer must specify the minimum number of entries in the CQ. The\r
986 *       exact number of entries the Channel Interface created is returned to the\r
987 *       client. If the requested number of entries is larger than what this\r
988 *       HCA can support, an error is returned.\r
989 * PARAMETERS\r
990 *       h_ca\r
991 *               [in] A handle to the open HCA\r
992 *       cq_context\r
993 *               [in] The context that is passed during the completion callbacks.\r
994 *       p_size\r
995 *               [in out] Points to a variable containing the number of CQ entries\r
996 *               requested by the consumer. On completion points to the size of the\r
997 *               CQ that was created by the provider.\r
998 *       ph_cq\r
999 *               [out] Handle to the newly created CQ on successful creation.\r
1000 *       p_umv_buf\r
1001 *               [in out] Vendor specific parameter to support user mode IO.\r
1002 * RETURN VALUE\r
1003 *       IB_SUCCESS\r
1004 *               The operation was successful.\r
1005 *       IB_INVALID_CA_HANDLE\r
1006 *               The h_ca passed is invalid.\r
1007 *       IB_INSUFFICIENT_RESOURCES\r
1008 *               Insufficient resources to complete request.\r
1009 *       IB_INVALID_CQ_SIZE\r
1010 *               Requested CQ Size is not supported.\r
1011 *       IB_INVALID_PARAMETER\r
1012 *               one of the parameters was NULL.\r
1013 * NOTES\r
1014 *       The consumer would need a way to retrieve the cq_handle associated with\r
1015 *       context being returned, so it can perform ci_poll_cq() to retrieve\r
1016 *       completion queue entries. The handle as such is not being passed, since\r
1017 *       there is no information in the handle that is visible to the consumer.\r
1018 *       Passing a context directly would help avoid any reverse lookup that the\r
1019 *       consumer would need to perform in order to identify it's own internal\r
1020 *       data-structures needed to process this completion completely.\r
1021 * SEE ALSO\r
1022 *       ci_destroy_cq, ci_query_cq, ci_resize_cq\r
1023 ******\r
1024 */\r
1025 \r
1026 /****f* Verbs/ci_resize_cq\r
1027 * NAME\r
1028 *       ci_resize_cq -- Modify the maximum number of entries the CQ could hold.\r
1029 * SYNOPSIS\r
1030 */\r
1031 \r
1032 typedef ib_api_status_t\r
1033 (*ci_resize_cq) (\r
1034         IN              const   ib_cq_handle_t                          h_cq,\r
1035         IN      OUT                     uint32_t* const                         p_size,\r
1036         IN      OUT                     ci_umv_buf_t                            *p_umv_buf OPTIONAL );\r
1037 /*\r
1038 * DESCRIPTION\r
1039 *       This routine allows the caller to modify the maximum number of entries\r
1040 *       the CQ could hold. It is possible to resize the CQ while there are\r
1041 *       entries in the CQ, and with outstanding work requests that will generate\r
1042 *       completions. If the entries in the CQ are more than the new size which is\r
1043 *       being created, an error is returned.\r
1044 * PARAMETERS\r
1045 *       h_cq\r
1046 *               [in] Completion Queue handle\r
1047 *       p_size\r
1048 *               [in out] This parameter indicates the requested size of the CQ. On\r
1049 *               successful completion, the current size allocated is returned in\r
1050 *               this same parameter.\r
1051 *       p_umv_buf\r
1052 *               [in out] Vendor specific parameter to support user mode IO.\r
1053 * RETURN VALUE\r
1054 *       IB_SUCCESS\r
1055 *               The resize operation was successful.\r
1056 *       IB_INVALID_CQ_HANDLE\r
1057 *               The CQ handle is invalid.\r
1058 *       IB_INSUFFICIENT_RESOURCES\r
1059 *               Insufficient resources to complete request.\r
1060 *       IB_INVALID_PARAMETER\r
1061 *               one of the parameters was NULL.\r
1062 *       IB_INVALID_CQ_SIZE\r
1063 *               Requested CQ Size is not supported.\r
1064 *       IB_OVERFLOW\r
1065 *               The CQ has more entries than the resize request. The CQ is not\r
1066 *               modified, and old entries still exist.\r
1067 * NOTES\r
1068 *       If the consumer wishes to resize the CQ smaller than originally created,\r
1069 *       it is recommended to retrieve all entries before performing a CQ resize\r
1070 *       operation. It is left to the verb implementer on resize operations, to\r
1071 *       actually reduce the entries, or leave it as it. The consumer must make no\r
1072 *       assumptions on the successful completion, and should only rely on the\r
1073 *       size returned in p_size.\r
1074 * SEE ALSO\r
1075 *       ci_create_cq\r
1076 ******\r
1077 */\r
1078 \r
1079 /****f* Verbs/ci_query_cq\r
1080 * NAME\r
1081 *       ci_query_cq -- Query the number of entries configured for the CQ.\r
1082 * SYNOPSIS\r
1083 */\r
1084 \r
1085 typedef ib_api_status_t\r
1086 (*ci_query_cq) (\r
1087         IN              const   ib_cq_handle_t                          h_cq,\r
1088                 OUT                     uint32_t                                        *p_size,\r
1089         IN      OUT                     ci_umv_buf_t                            *p_umv_buf OPTIONAL );\r
1090 /*\r
1091 * DESCRIPTION\r
1092 *       This routine returns the maximum number of entries this completion\r
1093 *       queue is configured.\r
1094 * PARAMETERS\r
1095 *       h_cq\r
1096 *               [in] Handle to the completion queue\r
1097 *       p_size\r
1098 *               [out] The number of entries the completion queue is configured to hold\r
1099 *       p_umv_buf\r
1100 *               [in out] Vendor specific parameter to support user mode IO.\r
1101 * RETURN VALUE\r
1102 *       IB_SUCCESS\r
1103 *               The call completed successfully, and the returned values are valid\r
1104 *       IB_INVALID_CQ_HANDLE\r
1105 *               The cq_handle passed is invalid.\r
1106 *       IB_INVALID_PARAMETER\r
1107 *               one of the parameters was NULL.\r
1108 * SEE ALSO\r
1109 *       ci_create_cq, ci_resize_cq\r
1110 ******\r
1111 */\r
1112 \r
1113 /****f* Verbs/ci_destroy_cq\r
1114 * NAME\r
1115 *       ci_destroy_cq -- Destroy a completion queue.\r
1116 * SYNOPSIS\r
1117 */\r
1118 \r
1119 typedef ib_api_status_t\r
1120 (*ci_destroy_cq) (\r
1121         IN      const   ib_cq_handle_t          h_cq );\r
1122 /*\r
1123 * DESCRIPTION\r
1124 *       Destroys a completion queue. If any queue pairs are still bound\r
1125 *       to this CQ, the attempt to destroy will fail, and the CQ and associated\r
1126 *       resources are *NOT* destroyed.\r
1127 * PARAMETERS\r
1128 *       cq_handle\r
1129 *               [in] Handle to the cq that is to be destroyed.\r
1130 * RETURN VALUE\r
1131 *       IB_SUCCESS\r
1132 *               The intend to destroy the completion queue is registered successfully.\r
1133 *               The destroy_callback function will be invoked when it is safe and\r
1134 *               guarantees that no more completion callbacks will be invoked for\r
1135 *               this CQ. Any pending CQ notifications are discarded.\r
1136 *       IB_INVALID_CQ_HANDLE\r
1137 *               The CQ handle is invalid.\r
1138 *       IB_RESOURCE_BUSY\r
1139 *               Queue pairs may still be bound to this completion queue.\r
1140 *       IB_INVALID_PARAMETER\r
1141 *               one of the parameters was NULL.\r
1142 * SEE ALSO\r
1143 *       ci_create_cq\r
1144 * NOTES\r
1145 *       This call cannot be called from any of the notification functions invoked\r
1146 *       by the Verbs driver. For e.g. the completion handler or the async error\r
1147 *       callback provided during the ci_open_ca() call. The call will block until\r
1148 *       all references to this adapter object is closed which includes all the\r
1149 *       pending callbacks returning back to the verbs provider driver.\r
1150 ******\r
1151 */\r
1152 \r
1153 \r
1154 \r
1155 /****f* Verbs/ci_register_mr\r
1156 * NAME\r
1157 *       ci_register_mr -- Register a memory region with the HCA.\r
1158 * SYNOPSIS\r
1159 */\r
1160 \r
1161 typedef ib_api_status_t\r
1162 (*ci_register_mr) (\r
1163         IN              const   ib_pd_handle_t                          h_pd,\r
1164         IN              const   ib_mr_create_t* const           p_mr_create,\r
1165                 OUT                     net32_t* const                          p_lkey,\r
1166                 OUT                     net32_t* const                          p_rkey,\r
1167                 OUT                     ib_mr_handle_t* const           ph_mr,\r
1168         IN                              boolean_t                                       um_call );\r
1169 /*\r
1170 * DESCRIPTION\r
1171 *       This routine registers a virtually contiguous region of memory with the\r
1172 *       HCA. All memory regions that need to be used by the HCA must be registered\r
1173 *       prior to use in data transfer operations. On successful completion\r
1174 *       the region handle, lkey are returned. If remote access rights are specified\r
1175 *       then the rkey is also returned.\r
1176 * PARAMETERS\r
1177 *       h_pd\r
1178 *               [in] Handle to the PD on which memory is being registered\r
1179 *       p_mr_create\r
1180 *               [in] Holds attributes for the region being registered. Look at\r
1181 *               ib_mr_create_t for more details.\r
1182 *       p_lkey\r
1183 *               [out] Local Key Attributes of the registered memory region\r
1184 *       p_rkey\r
1185 *               [out] Remote key of the registered memory region. The verbs provider\r
1186 *               is required to give this in the expected ordering on the wire. When\r
1187 *               rkey's are exchanged between remote nodes, no swapping of this data\r
1188 *               will be performed.\r
1189 *       ph_mr\r
1190 *               [out] Handle to the registered memory region. This handle is used when\r
1191 *               submitting work requests to refer to this region of memory.\r
1192 *       um_call\r
1193 *               [in] Boolean indicating whether the registration originated in user-mode.\r
1194 * RETURN VALUE\r
1195 *       IB_SUCCESS\r
1196 *               Registration with the adapter was successful.\r
1197 *       IB_INSUFFICIENT_RESOURCES\r
1198 *               Insufficient resources to satisfy request.\r
1199 *       IB_INVALID_PARAMETER\r
1200 *               One of the input pointers was NULL.\r
1201 *       IB_INVALID_PD_HANDLE\r
1202 *               Invalid mr_pdhandle\r
1203 *       IB_INVALID_PERMISSION\r
1204 *               Invalid access rights.\r
1205 * NOTES\r
1206 *       In addition to registration, the routine also pins memory, so that the\r
1207 *       physical page associated with the virtual address does not get swapped\r
1208 *       out during the time the HCA is attempting to transfer data to this\r
1209 *       address. If the memory is not pinned, this could lead to data-corruption\r
1210 *       and unpredictable behavior by the operating environment.\r
1211 *\r
1212 * SEE ALSO\r
1213 *       ci_deregister_mr, ci_query_mr, ci_register_pmr, ci_modify_mr,\r
1214 *       ci_register_smr\r
1215 ******\r
1216 */\r
1217 \r
1218 /****f* Verbs/ci_register_pmr\r
1219 * NAME\r
1220 *       ci_register_pmr -- Register a physical memory region with the HCA.\r
1221 * SYNOPSIS\r
1222 */\r
1223 \r
1224 typedef ib_api_status_t\r
1225 (*ci_register_pmr) (\r
1226         IN              const   ib_pd_handle_t                          h_pd,\r
1227         IN              const   ib_phys_create_t*const          p_pmr_create,\r
1228         IN      OUT                     uint64_t* const                         p_vaddr,\r
1229                 OUT                     net32_t* const                          p_lkey,\r
1230                 OUT                     net32_t* const                          p_rkey,\r
1231                 OUT                     ib_mr_handle_t* const           ph_mr,\r
1232         IN                              boolean_t                                       um_call );\r
1233 /*\r
1234 * DESCRIPTION\r
1235 *       This routine registers an array of physical pages as a single virtually\r
1236 *       contiguous region with the HCA. All memory regions that need to be used by\r
1237 *       the HCA must be registered prior to use in data transfer operations.\r
1238 *       On successful completion the region handle, lkey and rkey used for\r
1239 *       local and remote access authentication are returned.\r
1240 * PARAMETERS\r
1241 *       h_pd\r
1242 *               [in] Handle to the PD on which memory is being registered\r
1243 *       p_pmr_create\r
1244 *               [in] Holds attributes for the region being registered.\r
1245 *       p_vaddr\r
1246 *               [in/out] On input, references the requested virtual address for the\r
1247 *               start of the physical region.  On output, references the actual\r
1248 *               virtual address assigned to the registered region.\r
1249 *       p_lkey\r
1250 *               [out] Local key of the registered memory region\r
1251 *       p_rkey\r
1252 *               [out] Remote key of the registered memory region.The verbs provider\r
1253 *               is required to give this in the expected ordering on the wire. When\r
1254 *               rkey's are exchanged between remote nodes, no swapping of this data\r
1255 *               will be performed.\r
1256 *       ph_mr\r
1257 *               [out] Handle to the registered memory region. This handle is used when\r
1258 *               submitting work requests to refer to this region of memory.\r
1259 *       um_call\r
1260 *               [in] Boolean indicating whether the registration originated in user-mode.\r
1261 * RETURN VALUE\r
1262 *       IB_SUCCESS\r
1263 *               Registration with the adapter was successful.\r
1264 *       IB_INSUFFICIENT_RESOURCES\r
1265 *               Insufficient resources to satisfy request.\r
1266 *       IB_INVALID_PARAMETER\r
1267 *               Invalid length or address in p_mr_create. Also returned if the page_size\r
1268 *               passed is not one of supported page sizes by the HCA.\r
1269 *       IB_INVALID_PD_HANDLE\r
1270 *               Invalid mr_pdhandle\r
1271 *       IB_INVALID_PERMISSION\r
1272 *               Invalid access rights.\r
1273 * PORTABILITY\r
1274 *       Kernel Mode only\r
1275 * NOTES\r
1276 *       Remote and Atomic access settings in ib_access_ctrl_t, requires local\r
1277 *       write access to be enabled, otherwise IB_INVALID_PERMISSION is returned.\r
1278 *       The p_vaddr returned could be different from the vaddr specified in\r
1279 *       p_pmr_create.  If the requested virtual addr offset in a page does not\r
1280 *       match, the channel interface is free to pick and assign a pseudo virtual\r
1281 *       address. The address constructed is not a system virtual address, and only\r
1282 *       meaningful to the adapter to which this registration is targeted.\r
1283 * SEE ALSO\r
1284 *       ci_deregister_mr, ci_query_mr, ci_register_mr, ci_modify_mr,\r
1285 *       ci_register_smr\r
1286 ******\r
1287 */\r
1288 \r
1289 /****f* Verbs/ci_query_mr\r
1290 * NAME\r
1291 *       ci_query_mr -- Query attributes of a registered memory region\r
1292 * SYNOPSIS\r
1293 */\r
1294 \r
1295 typedef ib_api_status_t\r
1296 (*ci_query_mr) (\r
1297         IN              const   ib_mr_handle_t                  h_mr,\r
1298                 OUT                     ib_mr_attr_t*   const   p_mr_query );\r
1299 /*\r
1300 * DESCRIPTION\r
1301 *       This routine retrieves the memory region attributed of a\r
1302 *       registered memory region. The memory handle could have been\r
1303 *       obtained via ci_register_mr or ci_register_pmr.\r
1304 * PARAMETERS\r
1305 *       h_mr\r
1306 *               [in] Memory handle for which the attributes need to be retrieved.\r
1307 *       p_mr_query\r
1308 *               [out] Attributes of the memory region associated with memory handle.\r
1309 * RETURN VALUE\r
1310 *       IB_SUCCESS\r
1311 *               The routine completed successfully and attributes returned\r
1312 *               are valid.\r
1313 *       IB_INVALID_MR_HANDLE\r
1314 *               The memory handle is not valid.\r
1315 *       IB_INVALID_PARAMETER\r
1316 *               One of the input pointers was NULL.\r
1317 * NOTES\r
1318 *       Invalid handle checks are a mere signature checks in kernel mode.\r
1319 *       Drivers in kernel are expected to be good corporate citizens.\r
1320 *       In user mode, proper ownership is determined before passing handles\r
1321 *       down to kernel to protect from rogue applications.\r
1322 * SEE ALSO\r
1323 *       ci_register_mr, ci_register_pmr\r
1324 ******\r
1325 */\r
1326 \r
1327 /****f* Verbs/ci_modify_mr\r
1328 * NAME\r
1329 *       ci_modify_mr -- Modify some or all parameters of a memory region.\r
1330 * SYNOPSIS\r
1331 */\r
1332 \r
1333 typedef ib_api_status_t\r
1334 (*ci_modify_mr) (\r
1335         IN              const   ib_mr_handle_t                          h_mr,\r
1336         IN              const   ib_mr_mod_t                                     mr_modify_mask,\r
1337         IN              const   ib_mr_create_t* const           p_mr_create OPTIONAL,\r
1338                 OUT                     net32_t* const                          p_lkey,\r
1339                 OUT                     net32_t* const                          p_rkey,\r
1340         IN              const   ib_pd_handle_t                          h_pd OPTIONAL,\r
1341         IN                              boolean_t                                       um_call );\r
1342 /*\r
1343 * DESCRIPTION\r
1344 *       This routine modifies attributes of the specified memory region\r
1345 *       irrespective of whether the handle was obtained via ci_register_mr\r
1346 *       or ci_register_pmr. This verb conceptually performs a de-registration\r
1347 *       followed by a ci_register_mr.\r
1348 * PARAMETERS\r
1349 *       h_mr\r
1350 *               [in] Handle to the memory region whose attributes are to be modified.\r
1351 *       mr_modify_mask\r
1352 *               [in] Command specifying which parts of the mem_region is valid. The\r
1353 *               command is specified as a bit mask.\r
1354 *       p_mr_create\r
1355 *               [in] Desired attributes that need to be modified for mem_handle.\r
1356 *               This is an optional parameter which can be NULL if mr_modify_mask\r
1357 *               is set to IB_MR_MOD_PD.\r
1358 *       p_lkey\r
1359 *               [out] The new l_key for this newly registered memory region.\r
1360 *       p_rkey\r
1361 *               [out] The new r_key for this newly registered memory region.\r
1362 *               The verbs provider is required to give this in the expected ordering\r
1363 *               on the wire. When rkey's are exchanged between remote nodes, no\r
1364 *               swapping of this data will be performed.\r
1365 *       h_pd\r
1366 *               [in] This parameter is valid only if the IB_MR_MOD_PD flag is set\r
1367 *               in the mr_modify_req parameter. This field supplies the new\r
1368 *               protection domain to which the modified region should be\r
1369 *               associated with.\r
1370 *       um_call\r
1371 *               [in] Boolean indicating whether the registration originated in user-mode.\r
1372 * RETURN VALUE\r
1373 *       IB_SUCCESS\r
1374 *               The modify memory region request completed successfully.\r
1375 *       IB_RESOURCE_BUSY\r
1376 *               The memory region has windows bound to it.\r
1377 *       IB_INSUFFICIENT_RESOURCES\r
1378 *               Insufficient resources to complete the request.\r
1379 *       IB_INVALID_MR_HANDLE\r
1380 *               The memory handle supplied is not a valid memory region handle.\r
1381 *       IB_INVALID_PERMISSION\r
1382 *               Invalid access rights specified.\r
1383 *       IB_INVALID_PARAMETER\r
1384 *               A reference to the lkey or rkey was not provided or the specified\r
1385 *               modify mask is invalid.\r
1386 *       IB_INVALID_SETTING\r
1387 *               The specified memory region attributes are invalid.\r
1388 *       IB_INVALID_PD_HANDLE\r
1389 *               Protection domain handle supplied is not valid.\r
1390 * NOTES\r
1391 *       Remote and Atomic access settings in ib_access_ctrl_t, requires local\r
1392 *       write access to be enabled.\r
1393 *       TBD: How to handle shared memory region being passed to modify_mem?\r
1394 * SEE ALSO\r
1395 *       ci_register_mr, ci_register_pmr, ci_register_smr\r
1396 *******\r
1397 */\r
1398 \r
1399 /****f* Verbs/ci_modify_pmr\r
1400 * NAME\r
1401 *       ci_modify_pmr -- Modify some or all parameters of a memory region.\r
1402 * SYNOPSIS\r
1403 */\r
1404 \r
1405 typedef ib_api_status_t\r
1406 (*ci_modify_pmr) (\r
1407         IN              const   ib_mr_handle_t                          h_mr,\r
1408         IN              const   ib_mr_mod_t                                     mr_modify_mask,\r
1409         IN              const   ib_phys_create_t* const         p_pmr_create,\r
1410         IN      OUT                     uint64_t* const                         p_vaddr,\r
1411                 OUT                     net32_t* const                          p_lkey,\r
1412                 OUT                     net32_t* const                          p_rkey,\r
1413         IN              const   ib_pd_handle_t                          h_pd OPTIONAL,\r
1414         IN                              boolean_t                                       um_call );\r
1415 /*\r
1416 * DESCRIPTION\r
1417 *       This routine modifies attributes of the specified memory region\r
1418 *       irrespective of whether the handle was obtained via ci_register_mr\r
1419 *       or ci_register_pmr. This verb conceptually performs a de-registration\r
1420 *       followed by a ci_register_pmr.\r
1421 * PARAMETERS\r
1422 *       h_mr\r
1423 *               [in] Handle to the memory region whose attributes are to be modified.\r
1424 *       mr_modify_mask\r
1425 *               [in] Command specifying which parts of the mem_region is valid. The\r
1426 *               command is specified as a bit mask.\r
1427 *       p_pmr_create\r
1428 *               [in] Desired attributes that need to be modified for mem_handle.\r
1429 *       p_vaddr\r
1430 *               [in/out] On input, references the requested virtual address for the\r
1431 *               start of the physical region.  On output, references the actual\r
1432 *               virtual address assigned to the registered region.\r
1433 *       p_lkey\r
1434 *               [out] The new l_key for this newly registered physical memory region.\r
1435 *       p_rkey\r
1436 *               [out] The new r_key for this newly registered physical memory region.\r
1437 *               VPD is required to give this in the expected ordering on the wire. When\r
1438 *               rkey's are exchanged between remote nodes, no swapping of this data\r
1439 *               will be performed.\r
1440 *       h_pd\r
1441 *               [in] This parameter is valid only if the IB_MR_MOD_PD flag is set\r
1442 *               in the mr_modify_req parameter. This field supplies the new\r
1443 *               protection domain to which the modified region should be\r
1444 *               associated with.\r
1445 *       um_call\r
1446 *               [in] Boolean indicating whether the registration originated in user-mode.\r
1447 * RETURN VALUE\r
1448 *       IB_SUCCESS\r
1449 *               The modify memory region request completed successfully.\r
1450 *       IB_RESOURCE_BUSY\r
1451 *               The memory region has windows bound to it.\r
1452 *       IB_INSUFFICIENT_RESOURCES\r
1453 *               Insufficient resources to complete the request.\r
1454 *       IB_INVALID_MR_HANDLE\r
1455 *               The memory handle supplied is not a valid memory region handle.\r
1456 *       IB_INVALID_PERMISSION\r
1457 *               Invalid access rights specified.\r
1458 *       IB_INVALID_PARAMETER\r
1459 *               A reference to the virtual address, lkey, rkey was not provided or\r
1460 *               the specified modify mask is invalid.\r
1461 *       IB_INVALID_SETTING\r
1462 *               The specified memory region attributes are invalid.\r
1463 * PORTABILITY\r
1464 *       Kernel Mode only\r
1465 * NOTES\r
1466 *       Remote and Atomic access settings in ib_access_ctrl_t, requires local\r
1467 *       write access to be enabled.\r
1468 * SEE ALSO\r
1469 *       ci_register_mr, ci_register_pmr, ci_register_smr\r
1470 *********\r
1471 */\r
1472 \r
1473 /****f* Verbs/ci_register_smr\r
1474 * NAME\r
1475 *       ci_register_smr -- Register a memory region using same physical pages as\r
1476 *                      an existing memory region.\r
1477 * SYNOPSIS\r
1478 */\r
1479 \r
1480 typedef ib_api_status_t\r
1481 (*ci_register_smr) (\r
1482         IN              const   ib_mr_handle_t                          h_mr,\r
1483         IN              const   ib_pd_handle_t                          h_pd,\r
1484         IN              const   ib_access_t                                     access_ctrl,\r
1485         IN      OUT                     uint64_t* const                         p_vaddr,\r
1486                 OUT                     net32_t* const                          p_lkey,\r
1487                 OUT                     net32_t* const                          p_rkey,\r
1488                 OUT                     ib_mr_handle_t* const           ph_mr,\r
1489         IN                              boolean_t                                       um_call );\r
1490 /*\r
1491 * DESCRIPTION\r
1492 *       This routine registers a new memory region but shares the same set of\r
1493 *       physical pages associated with memory handle. For user mode applications\r
1494 *       the process *must* be owning memory handle for this call to be successful.\r
1495 * PARAMETERS\r
1496 *       h_mr\r
1497 *               [in] Handle to memory region whose physical pages are being registered\r
1498 *               by this shared registration.\r
1499 *       h_pd\r
1500 *               [in] Handle to the PD on which memory is being registered\r
1501 *       access_ctrl\r
1502 *               [in] Memory access restrictions on the registered memory.\r
1503 *       p_vaddr\r
1504 *               [in/out] On input, references the requested virtual address for the\r
1505 *               start of the physical region.  On output, references the actual\r
1506 *               virtual address assigned to the registered region.\r
1507 *       p_lkey\r
1508 *               [out] L_KEY for this memory region.\r
1509 *       p_rkey\r
1510 *               [out] R_KEY for this memory region. This is valid only when remote\r
1511 *               access is enabled for this region. The verbs provider\r
1512 *               is required to give this in the expected ordering on the wire. When\r
1513 *               rkey's are exchanged between remote nodes, no swapping of this data\r
1514 *               will be performed.\r
1515 *       ph_mr\r
1516 *               [out] Handle to the registered memory region. This handle is used when\r
1517 *               submitting work requests to refer to this region of memory.\r
1518 *       um_call\r
1519 *               [in] Boolean indicating whether the registration originated in user-mode.\r
1520 * RETURN VALUE\r
1521 *       IB_SUCCESS\r
1522 *               The call is successful and a new region handle returned is valid.\r
1523 *       IB_INVALID_MR_HANDLE\r
1524 *               mr_handle is invalid.\r
1525 *       IB_INVALID_PD_HANDLE\r
1526 *               mr_pdhandle supplied is invalid.\r
1527 *       IB_INVALID_PERMISSION\r
1528 *               Invalid access rights passed in mr_access.\r
1529 * NOTES\r
1530 *       ISSUE: how to deal with ci_deregister_mr, ci_modify_mr, ci_modify_pmr\r
1531 *       should we treat them as memory windows and fail those if a shared region\r
1532 *       was registered?\r
1533 * SEE ALSO\r
1534 *       ci_register_mr, ci_register_pmr, ci_modify_mr, ci_modify_pmr\r
1535 ******\r
1536 */\r
1537 \r
1538 /****f* Verbs/ci_deregister_mr\r
1539 * NAME\r
1540 *       ci_deregister_mr -- Deregister a memory region\r
1541 * SYNOPSIS\r
1542 */\r
1543 \r
1544 typedef ib_api_status_t\r
1545 (*ci_deregister_mr) (\r
1546         IN      const   ib_mr_handle_t          h_mr );\r
1547 /*\r
1548 * DESCRIPTION\r
1549 *       This routine deregisters  a memory region from the HCA. The region can\r
1550 *       de-registered only if there are no existing memory windows bound to\r
1551 *       this region, and if no existing shared memory regions were registered\r
1552 *       that refers to the same set of physical pages associated with the memory\r
1553 *       handle.  If there are outstanding work requests referring to this memory\r
1554 *       region, then after this call is successful, those work requests will\r
1555 *       complete with WRS_LOCAL_PROTECTION_ERR.\r
1556 * PARAMETERS\r
1557 *       h_mr\r
1558 *               [in] Memory handle that is being de-registered.\r
1559 * RETURN VALUE\r
1560 *       IB_SUCCESS\r
1561 *               The memory de-registration was successful\r
1562 *       IB_INVALID_MR_HANDLE\r
1563 *               The memory handle supplied is not a valid memory handle.\r
1564 *       IB_RESOURCE_BUSY\r
1565 *               The memory region has active windows bound.\r
1566 * NOTES\r
1567 * SEE ALSO\r
1568 *       ci_register_mr, ci_register_pmr, ci_register_smr\r
1569 ******\r
1570 */\r
1571 \r
1572 \r
1573 #ifdef CL_KERNEL\r
1574 /****f* Verbs/ci_alloc_mlnx_fmr\r
1575 * NAME\r
1576 *       ci_alloc_mlnx_fmr -- Allocate a Mellanox fast memory region with the HCA.\r
1577 * SYNOPSIS\r
1578 */\r
1579 typedef ib_api_status_t\r
1580 (*ci_alloc_mlnx_fmr) (\r
1581         IN              const   ib_pd_handle_t                          h_pd,\r
1582         IN                              mlnx_fmr_create_t const         *p_fmr_ctreate,\r
1583                 OUT                     mlnx_fmr_handle_t* const        ph_fmr);\r
1584 /*\r
1585 * DESCRIPTION\r
1586 *       //TODO \r
1587 * PARAMETERS\r
1588 *       h_pd\r
1589 *               [in] Handle to the PD on which fast memory is being registered\r
1590 *       mr_access_flags\r
1591 *               [in] mask of the access rights to the memory region\r
1592 *       p_fmr_attr\r
1593 *               [in] attribute of this fmr\r
1594 *       ph_fmr\r
1595 *               [out] Handle to the fast memory region. This handle is used when\r
1596 *               mapin/unmaping fmr\r
1597\r
1598 * RETURN VALUE\r
1599 *       IB_SUCCESS\r
1600 *               Registration with the adapter was successful.\r
1601 *       IB_INSUFFICIENT_RESOURCES\r
1602 *               Insufficient resources to satisfy request.\r
1603 *       IB_INVALID_PARAMETER\r
1604 *               One of the input pointers was NULL.\r
1605 *       IB_INVALID_PD_HANDLE\r
1606 *               Invalid pd handle\r
1607 *       IB_INVALID_PERMISSION\r
1608 *               Invalid access rights.\r
1609 *\r
1610 * NOTES\r
1611 *       The Alloc operation does not map nor pinned any memory.\r
1612 *       In order to use the FMR the user need to call map\r
1613 *\r
1614 *       This is a Mellanox specific extension to verbs.\r
1615 *\r
1616 * SEE ALSO\r
1617 *       ci_dealloc_mlnx_fmr, ci_map_phys_mlnx_fmr, ci_unmap_mlnx_fmr\r
1618 ******\r
1619 */\r
1620 \r
1621 \r
1622 /****f* Verbs/ci_map_phys_mlnx_fmr\r
1623 * NAME\r
1624 *       ci_map_phys_mlnx_fmr -- Map a Mellanox fast memory region with a\r
1625 *       given page list.\r
1626 *\r
1627 * SYNOPSIS\r
1628 */\r
1629 typedef ib_api_status_t\r
1630 (*ci_map_phys_mlnx_fmr) (\r
1631         IN              const   mlnx_fmr_handle_t                       h_fmr,\r
1632         IN              const   uint64_t* const                         paddr_list,\r
1633         IN              const   int                                                     list_len,\r
1634         IN      OUT                     uint64_t* const                         p_vaddr,\r
1635                 OUT                     net32_t* const                          p_lkey,\r
1636                 OUT                     net32_t* const                          p_rkey);\r
1637 /*\r
1638 * DESCRIPTION\r
1639 *       //TODO\r
1640 *\r
1641 * PARAMETERS\r
1642 *       h_fmr\r
1643 *               [in] Handle to the fast memory region that  these pages map to \r
1644 *       page_list\r
1645 *               [in] array of phys address\r
1646 *       list_len\r
1647 *               [in] number of pages in the list\r
1648 *       p_vaddr\r
1649 *               [in/out] On input, references the requested virtual address for the\r
1650 *               start of the FMR.  On output, references the actual\r
1651 *               virtual address assigned to the FMR.\r
1652 *       p_lkey\r
1653 *               [out] The local access key associated with this registered memory\r
1654 *               region.\r
1655 *       p_rkey\r
1656 *               [out] A key that may be used by a remote end-point when performing\r
1657 *               RDMA or atomic operations to this registered memory region.\r
1658 *\r
1659 * RETURN VALUE\r
1660 *       IB_SUCCESS\r
1661 *               Registration with the adapter was successful.\r
1662 *       IB_INSUFFICIENT_RESOURCES\r
1663 *               Insufficient resources to satisfy request.\r
1664 *       IB_INVALID_PARAMETER\r
1665 *               One of the input pointers was NULL.\r
1666 *       IB_INVALID_PD_HANDLE\r
1667 *               Invalid pd handle\r
1668 *       IB_INVALID_PERMISSION\r
1669 *               Invalid access rights.\r
1670 *\r
1671 * NOTES\r
1672 *       The Alloc operation does not map nor pinned any memory.\r
1673 *       In order to use the FMR the user need to call map \r
1674 *\r
1675 *       This is a Mellanox specific extension to verbs.\r
1676 *\r
1677 * SEE ALSO\r
1678 *       ci_dealloc_mlnx_fmr, ci_alloc_mlnx_fmr, ci_unmap_mlnx_fmr\r
1679 ******\r
1680 */\r
1681 \r
1682 \r
1683 /****f* Verbs/ci_unmap_mlnx_fmr\r
1684 * NAME\r
1685 *       ci_unmap_mlnx_fmr -- UnMap a Mellanox fast memory region.\r
1686 * SYNOPSIS\r
1687 */\r
1688 typedef ib_api_status_t\r
1689 (*ci_unmap_mlnx_fmr) (\r
1690         IN              const   mlnx_fmr_handle_t                       h_fmr);\r
1691 /*\r
1692 * DESCRIPTION\r
1693 *       //TODO\r
1694 *\r
1695 * PARAMETERS\r
1696 *       h_fmr\r
1697 *               [in] Handle to the fast memory region that  these pages map to \r
1698 *\r
1699 * RETURN VALUE\r
1700 *       IB_SUCCESS\r
1701 *               Registration with the adapter was successful.\r
1702 *       IB_INSUFFICIENT_RESOURCES\r
1703 *               Insufficient resources to satisfy request.\r
1704 *       IB_INVALID_PARAMETER\r
1705 *               One of the input pointers was NULL.\r
1706 *       IB_INVALID_PD_HANDLE\r
1707 *               Invalid pd handle\r
1708 *       IB_INVALID_PERMISSION\r
1709 *               Invalid access rights.\r
1710 *\r
1711 * NOTES\r
1712 *       The Alloc operation does not map nor pinned any memory.\r
1713 *       In order to use the FMR the user need to call map \r
1714 *\r
1715 *       This is a Mellanox specific extension to verbs.\r
1716 *\r
1717 * SEE ALSO\r
1718 *       ci_dealloc_mlnx_fmr, ci_alloc_mlnx_fmr, ci_map_phy_mlnx_fmr\r
1719 ******\r
1720 */\r
1721 \r
1722 \r
1723 /****f* Verbs/ci_dealloc_mlnx_fmr\r
1724 * NAME\r
1725 *       ci_dealloc_mlnx_fmr -- Deallocate a Mellanox fast memory region.\r
1726 *\r
1727 * SYNOPSIS\r
1728 */\r
1729 typedef ib_api_status_t\r
1730 (*ci_dealloc_mlnx_fmr) (\r
1731         IN                      mlnx_fmr_handle_t       const           h_fmr);\r
1732 /*\r
1733 * DESCRIPTION\r
1734 *       //TODO\r
1735 *\r
1736 * PARAMETERS\r
1737 *       h_fmr\r
1738 *               [in] Handle to the fast memory region. This handle is used when\r
1739 *               mapin/unmaping fmr\r
1740 *\r
1741 * RETURN VALUE\r
1742 *       IB_SUCCESS\r
1743 *               Registration with the adapter was successful.\r
1744 *       IB_INSUFFICIENT_RESOURCES\r
1745 *               Insufficient resources to satisfy request.\r
1746 *       IB_INVALID_PARAMETER\r
1747 *               One of the input pointers was NULL.\r
1748 *       IB_INVALID_PD_HANDLE\r
1749 *               Invalid pd handle\r
1750 *       IB_INVALID_PERMISSION\r
1751 *               Invalid access rights.\r
1752 *\r
1753 * NOTES\r
1754 *       This is a Mellanox specific extension to verbs.\r
1755 *\r
1756 * SEE ALSO\r
1757 *       ci_dealloc_mlnx_fmr, ci_map_phys_mlnx_fmr, ci_unmap_mlnx_fmr\r
1758 ******\r
1759 */\r
1760 #endif\r
1761 \r
1762 \r
1763 /****f* Verbs/ci_create_mw\r
1764 * NAME\r
1765 *       ci_create_mw -- Create a memory window entry for later use\r
1766 * SYNOPSIS\r
1767 */\r
1768 \r
1769 typedef ib_api_status_t\r
1770 (*ci_create_mw) (\r
1771         IN              const   ib_pd_handle_t                          h_pd,\r
1772                 OUT                     net32_t* const                          p_rkey,\r
1773                 OUT                     ib_mw_handle_t                          *ph_mw,\r
1774         IN      OUT                     ci_umv_buf_t                            *p_umv_buf OPTIONAL );\r
1775 /*\r
1776 * DESCRIPTION\r
1777 *       This routine allocates a memory window. This window entry cannot be used\r
1778 *       for remote access unless this window is bound to a memory region\r
1779 *       via the ci_bind_mw call.\r
1780 * PARAMETERS\r
1781 *       h_pd\r
1782 *               [in] Protection domain handle to use for this memory window\r
1783 *       p_rkey\r
1784 *               [out] Remote access key that can be exchanged with a remote node to\r
1785 *               perform RDMA transactions on this memory window. This R_KEY is still not\r
1786 *               bound to any memory regions, until a successful call to ci_bind_mw.\r
1787 *               VPD is required to give this in the expected ordering on the wire. When\r
1788 *               rkey's are exchanged between remote nodes, no swapping of this data\r
1789 *               will be performed.\r
1790 *       ph_mw\r
1791 *               [out] Handle to the newly created memory window.\r
1792 *       p_umv_buf\r
1793 *               [in out] Vendor specific parameter to support user mode IO.\r
1794 * RETURN VALUE\r
1795 *       IB_SUCCESS\r
1796 *               The memory window allocation completed successfully.\r
1797 *       IB_INSUFFICIENT_RESOURCES\r
1798 *               Not enough resources to complete the request.\r
1799 *       IB_INVALID_PD_HANDLE\r
1800 *               pd_handle supplied is invalid.\r
1801 *       IB_INVALID_PARAMETER\r
1802 *               One of the pointers was not valid.\r
1803 * SEE ALSO\r
1804 *       ci_destroy_mw, ci_query_mw, ci_bind_mw\r
1805 ******\r
1806 */\r
1807 \r
1808 /****f* Verbs/ci_query_mw\r
1809 * NAME\r
1810 *       ci_query_mw -- Query memory window attributes for memory window handle\r
1811 * SYNOPSIS\r
1812 */\r
1813 \r
1814 typedef ib_api_status_t\r
1815 (*ci_query_mw) (\r
1816         IN              const   ib_mw_handle_t                          h_mw,\r
1817                 OUT                     ib_pd_handle_t                          *ph_pd,\r
1818                 OUT                     net32_t* const                          p_rkey,\r
1819         IN      OUT                     ci_umv_buf_t                            *p_umv_buf OPTIONAL );\r
1820 /*\r
1821 * DESCRIPTION\r
1822 *       This routine retrieves the current R_KEY and protection domain\r
1823 *       handle associated with this mw_handle.\r
1824 * PARAMETERS\r
1825 *       h_mw\r
1826 *               [in] Memory window handle whose attributes are being retrieved.\r
1827 *       ph_pd\r
1828 *               [out] Protection domain handle associated with this mw_handle\r
1829 *       p_rkey\r
1830 *               [out] Current R_KEY associated with this mw_handle.The verbs provider\r
1831 *               is required to give this in the expected ordering on the wire. When\r
1832 *               rkey's are exchanged between remote nodes, no swapping of this data\r
1833 *               will be performed.\r
1834 *       p_umv_buf\r
1835 *               [in out] Vendor specific parameter to support user mode IO.\r
1836 * RETURN VALUE\r
1837 *       IB_SUCCESS\r
1838 *               The query operation completed successfully.\r
1839 *       IB_INVALID_MW_HANDLE\r
1840 *               mw_handle supplied is an invalid handle\r
1841 *       IB_INVALID_PARAMETER\r
1842 *               One of the pointers was not valid.\r
1843 * SEE ALSO\r
1844 *       ci_create_mw, ci_bind_mw\r
1845 ******\r
1846 */\r
1847 \r
1848 /****f* Verbs/ci_bind_mw\r
1849 * NAME\r
1850 *       ci_bind_mw -- Bind a memory window to a memory region.\r
1851 * SYNOPSIS\r
1852 */\r
1853 \r
1854 typedef ib_api_status_t\r
1855 (*ci_bind_mw) (\r
1856         IN              const   ib_mw_handle_t                          h_mw,\r
1857         IN              const   ib_qp_handle_t                          h_qp,\r
1858         IN                              ib_bind_wr_t* const                     p_mw_bind,\r
1859                 OUT                     net32_t* const                          p_rkey );\r
1860 /*\r
1861 * DESCRIPTION\r
1862 *       This routine posts a request to bind a memory window to a registered\r
1863 *       memory region. If the queue pair was created with selectable signaling,\r
1864 *       once the operation is completed successfully then a completion queue entry\r
1865 *       is generated indicating the bind operation has completed. The IB_POST_FENCE\r
1866 *       option could be specified to cause the requestor to wait until outstanding\r
1867 *       RDMA operations can be completed.\r
1868 * PARAMETERS\r
1869 *       h_mw\r
1870 *               [in] Handle to memory window that needs to be bound to a memory region.\r
1871 *       h_qp\r
1872 *               [in] Queue Pair to which this bind request is to be posted.\r
1873 *       p_mw_bind\r
1874 *               [in] Input parameters for this bind request, consisting of virtual\r
1875 *               addr range of bind request etc.\r
1876 *       p_rkey\r
1877 *               [out] On successful completion, the new R_KEY is returned.\r
1878 *               VPD is required to give this in the expected ordering on the wire. When\r
1879 *               rkey's are exchanged between remote nodes, no swapping of this data\r
1880 *               will be performed.\r
1881 * RETURN VALUE\r
1882 *       IB_SUCCESS\r
1883 *               The memory bind operation was posted successfully.\r
1884 *       IB_INSUFFICIENT_RESOURCES\r
1885 *               Insufficient resources to complete the request.\r
1886 *               No more WQE's to post this request\r
1887 *               No more free WQE's to post this request\r
1888 *       IB_INVALID_MW_HANDLE\r
1889 *               memw_handle supplied is an invalid memory window handle.\r
1890 *       IB_INVALID_PERMISSION\r
1891 *               Invalid access rights specified in request\r
1892 *       IB_INVALID_SERVICE_TYPE\r
1893 *               Invalid service type for this qp_handle.\r
1894 *       IB_INVALID_PARAMETER\r
1895 *               One of the pointers was not valid.\r
1896 *       IB_INVALID_RKEY\r
1897 *               R_KEY specified is invalid for the memory region being bound.\r
1898 *       IB_INVALID_QP_HANDLE\r
1899 *               h_qp supplied was an invalid QP handle.\r
1900 * NOTES\r
1901 *       - A previously bound memory window can be bound to the same or different\r
1902 *       memory region.\r
1903 *\r
1904 *       - A bind operation with length of 0, invalidates any previous binding\r
1905 *       and returns an R_KEY in the unbound state.\r
1906 * SEE ALSO\r
1907 *       ci_create_mw\r
1908 ******\r
1909 */\r
1910 \r
1911 /****f* Verbs/ci_destroy_mw\r
1912 * NAME\r
1913 *       ci_destroy_mw -- Destroy a memory window.\r
1914 * SYNOPSIS\r
1915 */\r
1916 \r
1917 typedef ib_api_status_t\r
1918 (*ci_destroy_mw) (\r
1919         IN      const   ib_mw_handle_t          h_mw );\r
1920 /*\r
1921 * DESCRIPTION\r
1922 *       This routine deallocates a window entry created via a ci_create_mw.\r
1923 *       Once this operation is complete, the channel interface guarantees that\r
1924 *       no future remote accesses will be permitted to this window entry.\r
1925 * PARAMETERS\r
1926 *       h_mw\r
1927 *               [in] Handle to the memory window that is being destroyed.\r
1928 * RETURN VALUE\r
1929 *       IB_SUCCESS\r
1930 *               The destroy window request completed successfully.\r
1931 *       IB_INVALID_MW_HANDLE\r
1932 *               memw_handle supplied is invalid.\r
1933 * NOTES\r
1934 *       Deallocate memory window implicitly means the window is also unbound\r
1935 *       once the call completes successfully. Any future remote access with\r
1936 *       the same R_KEY should fail with protection violation.\r
1937 * SEE ALSO\r
1938 *       ci_create_mw\r
1939 ******\r
1940 */\r
1941 \r
1942 /****f* Verbs/ci_post_send\r
1943 * NAME\r
1944 *       ci_post_send -- Post a work request to the send side of a queue pair.\r
1945 * SYNOPSIS\r
1946 */\r
1947 \r
1948 typedef ib_api_status_t\r
1949 (*ci_post_send) (\r
1950         IN              const   ib_qp_handle_t                  h_qp,\r
1951         IN                              ib_send_wr_t*   const   p_send_wr,\r
1952                 OUT                     ib_send_wr_t                    **pp_failed );\r
1953 /*\r
1954 * DESCRIPTION\r
1955 *       This routine posts a work request to the send side of the queue pair.\r
1956 *       The different types of work request that can be posted are explained in\r
1957 *       the ib_wr_t structure. For exact details on ordering rules please consult\r
1958 *       the Volume 1, of the InfiniBand Specifications. If there is more\r
1959 *       outstanding requests posted that what the queue is configured for, an\r
1960 *       immediate error is returned.\r
1961 * PARAMETERS\r
1962 *       h_qp\r
1963 *               [in] The queue pair to which this work request is being submitted.\r
1964 *       p_send_wr\r
1965 *               [in] A pointer to the head of the list that must be posted to the\r
1966 *               Send Queue.\r
1967 *       pp_failed\r
1968 *               [out] A pointer to the head of the list that holds the failed WRs.\r
1969 *               If all the entries provided are posted with the CI, then this parameter\r
1970 *               would be set to NULL.\r
1971 * RETURN VALUE\r
1972 *       Any unsuccessful status indicates the status of the first failed request.\r
1973 *\r
1974 *       IB_SUCCESS\r
1975 *               All the work requests are completed successfully\r
1976 *       IB_INVALID_QP_HANDLE\r
1977 *               The qp_handle supplied is invalid.\r
1978 *       IB_INSUFFICIENT_RESOURCES\r
1979 *               Insufficient resources to complete the request.\r
1980 *               There are no more work elements in the channel interface to\r
1981 *               process this request, and the total outstanding work request has\r
1982 *               been exceeded.\r
1983 *       IB_INVALID_WR_TYPE\r
1984 *               The work request type was not valid.\r
1985 *       IB_INVALID_QP_STATE\r
1986 *               The queue pair is either in Reset, Init, RTR or Error state.\r
1987 *       IB_INVALID_MAX_SGE\r
1988 *               The work request has too many scatter gather elements than what the\r
1989 *               QP is configured.\r
1990 *       IB_UNSUPPORTED\r
1991 *               Atomics or Reliable datagram request is not supported by this HCA.\r
1992 *       IB_INVALID_ADDR_HANDLE\r
1993 *               Address handle supplied in the work request is invalid.\r
1994 * NOTES\r
1995 *       Please refer to Table 81 and Table 82 for allowed operation types\r
1996 *       on different types of queue pairs, and the different modifiers\r
1997 *       acceptable for the work request for different QP service types.\r
1998 * SEE ALSO\r
1999 *       ci_post_recv, ci_poll_cq\r
2000 ******\r
2001 */\r
2002 \r
2003 /****f* Verbs/ci_post_recv\r
2004 * NAME\r
2005 *       ci_post_recv -- Post a work request to the receive queue of a queue pair.\r
2006 * SYNOPSIS\r
2007 */\r
2008 \r
2009 typedef ib_api_status_t\r
2010 (*ci_post_recv) (\r
2011         IN              const   ib_qp_handle_t                  h_qp,\r
2012         IN                              ib_recv_wr_t*   const   p_recv_wr,\r
2013                 OUT                     ib_recv_wr_t                    **pp_failed );\r
2014 /*\r
2015 * DESCRIPTION\r
2016 *       This routine allows to queue a work request to the receive side of a\r
2017 *       queue pair. The work_req holds necessary data to satisfy an incoming\r
2018 *       receive message. If an attempt is made to queue more work requests than\r
2019 *       what is available, an error is returned.\r
2020 * PARAMETERS\r
2021 *       h_qp\r
2022 *               [in] Handle to the queue pair to which the receive work request is being\r
2023 *               posted.\r
2024 *       p_recv_wr\r
2025 *               [in] Holds the WRs to be posted to the receive queue.\r
2026 *       pp_failed\r
2027 *               [out] If any entry could not be posted with the CI, then this points\r
2028 *               to the first WR that completed unsuccessfully. If all entries are\r
2029 *               posted, then this field is set to NULL on successful exit.\r
2030 * RETURN VALUE\r
2031 *       Any unsuccessful status indicates the status of the first failed request.\r
2032 *\r
2033 *       IB_SUCCESS\r
2034 *               The work request was successfully queued to the receive side of the QP.\r
2035 *       IB_INVALID_QP_HANDLE\r
2036 *               qp_handle supplied is not valid.\r
2037 *       IB_INSUFFICIENT_RESOURCES\r
2038 *               The qp has exceeded its receive queue depth than what is has been\r
2039 *               configured.\r
2040 *       IB_INVALID_WR_TYPE\r
2041 *               Invalid work request type found in the request.\r
2042 *       IB_INVALID_QP_STATE\r
2043 *               QP was in reset or init state.\r
2044 *               (TBD: there may be an errata that allows posting in init state)\r
2045 * SEE ALSO\r
2046 *       ci_post_send, ci_poll_cq.\r
2047 ******\r
2048 */\r
2049 \r
2050 /****f* Verbs/ci_peek_cq\r
2051 * NAME\r
2052 *       ci_peek_cq\r
2053 *\r
2054 * DESCRIPTION\r
2055 *       Returns the number of entries currently on the completion queue.\r
2056 *\r
2057 * SYNOPSIS\r
2058 */\r
2059 typedef ib_api_status_t\r
2060 (*ci_peek_cq) (\r
2061         IN              const   ib_cq_handle_t                          h_cq,\r
2062         OUT                             uint32_t* const                         p_n_cqes );\r
2063 /*\r
2064 * PARAMETERS\r
2065 *       h_cq\r
2066 *               [in] Handle to the completion queue to peek.\r
2067 *\r
2068 *       p_n_cqes\r
2069 *               [out] The number of completion entries on the CQ.\r
2070 *\r
2071 * RETURN VALUES\r
2072 *       IB_SUCCESS\r
2073 *               The peek operation completed successfully.\r
2074 *       IB_INVALID_CQ_HANDLE\r
2075 *               The completion queue handle was invalid.\r
2076 *       IB_INVALID_PARAMETER\r
2077 *               A reference to the completion queue entry count was not provided.\r
2078 *       IB_UNSUPPORTED\r
2079 *               This operation is not supported by the channel adapter.\r
2080 *\r
2081 * NOTES\r
2082 *       The value returned is a snapshot of the number of compleiton queue\r
2083 *       entries curently on the completion queue.  Support for this operation\r
2084 *       is optional by a channel adapter vendor.\r
2085 *\r
2086 * SEE ALSO\r
2087 *       ci_create_cq, ci_poll_cq, ci_enable_cq_notify, ci_enable_ncomp_cq_notify\r
2088 *****/\r
2089 \r
2090 /****f* Verbs/ci_poll_cq\r
2091 * NAME\r
2092 *       ci_poll_cq -- Retrieve a work completion record from a completion queue\r
2093 * SYNOPSIS\r
2094 */\r
2095 \r
2096 typedef ib_api_status_t\r
2097 (*ci_poll_cq) (\r
2098         IN              const   ib_cq_handle_t                          h_cq,\r
2099         IN      OUT                     ib_wc_t** const                         pp_free_wclist,\r
2100                 OUT                     ib_wc_t** const                         pp_done_wclist );\r
2101 /*\r
2102 * DESCRIPTION\r
2103 *       This routine retrieves a work completion entry from the specified\r
2104 *       completion queue. The contents of the data returned in a work completion\r
2105 *       is specified in ib_wc_t.\r
2106 * PARAMETERS\r
2107 *       h_cq\r
2108 *               [in] Handle to the completion queue being polled.\r
2109 *       pp_free_wclist\r
2110 *               [in out] A list of work request structures provided by the consumer\r
2111 *               for the channel interface to return completed Completion Queue\r
2112 *               entries.  If not all the entries are consumed, this list holds the\r
2113 *               list of un-utilized completion entries provided back to the consumer.\r
2114 *       pp_done_wclist\r
2115 *               [out] A list of work completions retrieved from the completion queue\r
2116 *               and successfully processed.\r
2117 * RETURN VALUE\r
2118 *       IB_SUCCESS\r
2119 *               Poll completed successfully and found one or more entries. If on\r
2120 *               completion the pp_free_wclist is empty, then there are potentially more\r
2121 *               entries and the consumer must continue to retrieve entries.\r
2122 *       IB_INVALID_CQ_HANDLE\r
2123 *               The cq_handle supplied is not valid.\r
2124 *       IB_NOT_FOUND\r
2125 *               There were no completion entries found in the specified CQ.\r
2126 * SEE ALSO\r
2127 *       ci_create_cq, ci_post_send, ci_post_recv, ci_bind_mw\r
2128 ******\r
2129 */\r
2130 \r
2131 /****f* Verbs/ci_enable_cq_notify\r
2132 * NAME\r
2133 *       ci_enable_cq_notify -- Invoke the Completion handler, on next entry added.\r
2134 * SYNOPSIS\r
2135 */\r
2136 \r
2137 typedef ib_api_status_t\r
2138 (*ci_enable_cq_notify) (\r
2139         IN      const   ib_cq_handle_t          h_cq,\r
2140         IN      const   boolean_t                       solicited );\r
2141 /*\r
2142 * DESCRIPTION\r
2143 *       This routine instructs the channel interface to invoke the completion\r
2144 *       handler when the next completion queue entry is added to this CQ.\r
2145 *       Please refer to Volume 1, of the InfiniBand specification for a complete\r
2146 *       description.\r
2147 * PARAMETERS\r
2148 *       h_cq\r
2149 *               [in] Handle to the CQ on which the notification is being enabled.\r
2150 *       solicited\r
2151 *               [in] A boolean flag indicating whether the request is to generate a\r
2152 *               notification on the next entry or on the next solicited entry\r
2153 *               being added to the completion queue.\r
2154 * RETURN VALUE\r
2155 *       IB_SUCCESS\r
2156 *               The notification request was registered successfully.\r
2157 *       IB_INVALID_CQ_HANDLE\r
2158 *               cq_handle supplied is not a valid handle.\r
2159 * NOTES\r
2160 *       The consumer cannot call a request for notification without emptying\r
2161 *       entries from the CQ. i.e if a consumer registers for a notification\r
2162 *       request in the completion callback before pulling entries from the\r
2163 *       CQ via ci_poll_cq, the notification is not generated for completions\r
2164 *       already in the CQ. For e.g. in the example below, if there are no calls\r
2165 *   to ci_poll_cq()     after the ci_enable_cq_notify(). For any CQ entries added\r
2166 *       before calling this ci_enable_cq_notify() call, the consumer does not\r
2167 *       get a completion notification callback. In order to comply with the verb\r
2168 *       spec, consumer is supposed to perform a ci_poll_cq() after the\r
2169 *       ci_enable_cq_notify() is made to retrive any entries that might have\r
2170 *       been added to the CQ before the CI registers the notification enable.\r
2171 *\r
2172 *                       while ((ret_val = ci_poll_cq(cq_handle, &free_list, &done_list)\r
2173 *                               == FSUCCESS))\r
2174 *                       {\r
2175 *                               process entries;\r
2176 *                       }\r
2177 *                       if (ret_val == IB_NOT_FOUND)\r
2178 *                               ci_enable_cq_notify(cq_handle);\r
2179 *                       // Need to perform a ci_poll_cq()\r
2180 *           // after the enable.\r
2181 * SEE ALSO\r
2182 *       ci_create_cq, ci_peek_cq, ci_poll_cq, ci_enable_ncomp_cq_notify\r
2183 ******\r
2184 */\r
2185 \r
2186 /****f* Verbs/ci_enable_ncomp_cq_notify\r
2187 * NAME\r
2188 *       ci_enable_ncomp_cq_notify -- Invoke the Completion handler when the next\r
2189 *       N completions are added.\r
2190 * SYNOPSIS\r
2191 */\r
2192 \r
2193 typedef ib_api_status_t\r
2194 (*ci_enable_ncomp_cq_notify) (\r
2195         IN              const   ib_cq_handle_t                          h_cq,\r
2196         IN              const   uint32_t                                        n_cqes );\r
2197 /*\r
2198 * DESCRIPTION\r
2199 *       This routine instructs the channel interface to invoke the completion\r
2200 *       handler when the next N completions have been added to this CQ.\r
2201 * PARAMETERS\r
2202 *       h_cq\r
2203 *               [in] Handle to the CQ on which the notification is being enabled.\r
2204 *       n_cqes\r
2205 *               [in] The number of completion queue entries to be added to the\r
2206 *               completion queue before notifying the client.  This value must\r
2207 *               greater than or equal to one and less than or equal to the size\r
2208 *               of the completion queue.\r
2209 *\r
2210 * RETURN VALUE\r
2211 *       IB_SUCCESS\r
2212 *               The notification request was registered successfully.\r
2213 *       IB_INVALID_CQ_HANDLE\r
2214 *               cq_handle supplied is not a valid handle.\r
2215 *       IB_INVALID_PARAMETER\r
2216 *               The requested number of completion queue entries was invalid.\r
2217 *       IB_UNSUPPORTED\r
2218 *               This operation is not supported by the channel adapter.\r
2219 *\r
2220 * NOTES\r
2221 *       This routine instructs the channel interface to invoke the completion\r
2222 *       handler when the next N completions have been added to this CQ regardless\r
2223 *       of the completion type (solicited or unsolicited).  Any CQ entries that\r
2224 *       existed before the rearm is enabled will not result in a call to the\r
2225 *       handler.  Support for this operation is optional by a channel adapter\r
2226 *       vendor.\r
2227 *\r
2228 * SEE ALSO\r
2229 *       ci_create_cq, ci_peek_cq, ci_poll_cq, ci_enable_cq_notify\r
2230 ******\r
2231 */\r
2232 \r
2233 /****f* Verbs/ci_attach_mcast\r
2234 * NAME\r
2235 *       ci_attach_mcast -- Attach a queue pair to a multicast group\r
2236 * SYNOPSIS\r
2237 */\r
2238 \r
2239 typedef ib_api_status_t\r
2240 (*ci_attach_mcast) (\r
2241         IN              const   ib_qp_handle_t                          h_qp,\r
2242         IN              const   ib_gid_t                                        *p_mcast_gid,\r
2243         IN              const   ib_net16_t                                      mcast_lid,\r
2244                 OUT                     ib_mcast_handle_t                       *ph_mcast,\r
2245         IN      OUT                     ci_umv_buf_t                            *p_umv_buf OPTIONAL );\r
2246 /*\r
2247 * DESCRIPTION\r
2248 *       This routine attaches the given qp_handle to a multicast gid as specified\r
2249 *       by mcast_gid parameter.\r
2250 * PARAMETERS\r
2251 *       h_qp\r
2252 *               [in] Queue pair handle which needs to be added to the multicast group\r
2253 *               on the adapter.\r
2254 *       mcast_lid\r
2255 *               [in] The multicast group LID value.\r
2256 *       p_mcast_gid\r
2257 *               [in] IPv6 address associated with this multicast group.\r
2258 *       ph_mcast\r
2259 *               [out] Multicast handle holding the association of this queue pair\r
2260 *               to the multicast group.\r
2261 *       p_umv_buf\r
2262 *               [in out] Vendor specific parameter to support user mode IO.\r
2263 * RETURN VALUE\r
2264 *       IB_SUCCESS\r
2265 *               The queue pair handle was successfully added to the multicast\r
2266 *               group.\r
2267 *       IB_INVALID_QP_HANDLE\r
2268 *               qp_handle supplied is invalid.\r
2269 *       IB_INVALID_SERVICE_TYPE\r
2270 *               Queue pair handle supplied is not of unreliable datagram type.\r
2271 *       IB_INVALID_GID\r
2272 *               The supplied addr is not a valid multicast ipv6 address.\r
2273 *       IB_INVALID_LID\r
2274 *               The supplied lid is not a valid multicast lid.\r
2275 *       IB_UNSUPPORTED\r
2276 *               Multicast is not supported by this HCA.\r
2277 *       IB_INSUFFICIENT_RESOURCES\r
2278 *               Insufficient resources to complete request.\r
2279 *       IB_INVALID_PARAMETER\r
2280 *               One of the parameters was NULL.\r
2281 * SEE ALSO\r
2282 *       ci_create_qp, ci_detach_mcast\r
2283 ******\r
2284 */\r
2285 \r
2286 \r
2287 /****f* Verbs/ci_detach_mcast\r
2288 * NAME\r
2289 *       ci_detach_mcast -- Detach a queue pair from a multicast group\r
2290 * SYNOPSIS\r
2291 */\r
2292 \r
2293 typedef ib_api_status_t\r
2294 (*ci_detach_mcast) (\r
2295         IN      const   ib_mcast_handle_t               h_mcast );\r
2296 /*\r
2297 * DESCRIPTION\r
2298 *       This routine detaches a queue pair from its previously associated multicast\r
2299 *       group.\r
2300 * PARAMETERS\r
2301 *       h_mcast\r
2302 *               [in] The multicast handle passed back to consumer after the\r
2303 *               ci_mcast_attach call.\r
2304 * RETURN VALUE\r
2305 *       IB_SUCCESS\r
2306 *               The qp was successfully detached from the multicast group.\r
2307 *       IB_INVALID_MCAST_HANDLE\r
2308 *               mcast_handle supplied is an invalid handle\r
2309 *       IB_INVALID_PARAMETER\r
2310 *               One of the parameters was NULL.\r
2311 * SEE ALSO\r
2312 *       ci_attach_mcast\r
2313 ******\r
2314 */\r
2315 \r
2316 /****f* Verbs/ci_local_mad\r
2317 * NAME\r
2318 *       ci_local_mad -- Request a mad to be processed by the local adapter.\r
2319 * SYNOPSIS\r
2320 */\r
2321 \r
2322 typedef ib_api_status_t\r
2323 (*ci_local_mad) (\r
2324         IN              const   ib_ca_handle_t          h_ca,\r
2325         IN              const   uint8_t                         port_num,\r
2326         IN              const   ib_av_attr_t                    *p_src_av_attr,\r
2327         IN              const   ib_mad_t                        *p_mad_in,\r
2328         OUT                     ib_mad_t                        *p_mad_out );\r
2329 /*\r
2330 * DESCRIPTION\r
2331 *       This routine is OPTIONAL for the channel interface. This is required\r
2332 *       for adapters which do not have the agents such as Subnet Management\r
2333 *       agent (SMA) Or the GSA in the Verbs Provider driver.\r
2334 *       hardware, for all such adapters the exact queue pair management of\r
2335 *       special queue pairs happen above the channel interface. This routine\r
2336 *       is used to perform local operations, since there is no agent below the\r
2337 *       channel interface. For e.g: If a Subnet Management packet (SMP) to\r
2338 *       set PORT_STATE is received, this reception is processed above the channel\r
2339 *       interface, then this call is done to set the port state on the local\r
2340 *       adapter. On successful return, the response is generated and sent to the\r
2341 *       Subnet Manager.\r
2342 * PARAMETERS\r
2343 *       h_ca\r
2344 *               [in] A handle to the channel adapter that should process the MAD.\r
2345 *               This must be the same adapter that the MAD was received on.\r
2346 *       port_num\r
2347 *               [in] port number to which this request is directed is to be sent.\r
2348 *       p_mad_in\r
2349 *               [in] pointer to a management datagram (MAD) structure containing\r
2350 *               the command to be processed.\r
2351 *       p_mad_out\r
2352 *               [out] Response packet after processing the command. The storage to this\r
2353 *               must be allocated by the consumer.\r
2354 * RETURN VALUE\r
2355 *       IB_SUCCESS\r
2356 *               Command processed successfully.\r
2357 *       IB_INVALID_CA_HANDLE\r
2358 *               The HCA handle supplied is not valid.\r
2359 *       IB_INVALID_PORT\r
2360 *               The port number supplied is invalid.\r
2361 * PORTABILITY\r
2362 *       Kernel Mode only\r
2363 * NOTES\r
2364 *       This call is provided to aid adapters that don't have a agent functionality\r
2365 *       built in the channel interface. Some adapters do have a local processor\r
2366 *       to process these packets, hence even for local port management, we can\r
2367 *       use the same mechanism we use to configure external nodes by using a\r
2368 *       hop counter = 1 in the MAD packets. If the SMA indicates it has a local\r
2369 *       sma in the ib_ca_attr_t, then the packets are posted to the adapter\r
2370 *       instead of making a private call to the adapter.\r
2371 * SEE ALSO\r
2372 *       ci_query_ca, ci_ca_attr_t\r
2373 ******\r
2374 */\r
2375 \r
2376 \r
2377 /****f* Verbs/ci_vendor_call\r
2378 * NAME\r
2379 *       ci_vendor_call\r
2380 *\r
2381 * DESCRIPTION\r
2382 *       Performs a vendor specific CA interface function call.\r
2383 *\r
2384 * SYNOPSIS\r
2385 */\r
2386 typedef ib_api_status_t\r
2387 (*ci_vendor_call)(\r
2388         IN              const   ib_ca_handle_t                          h_ca,\r
2389         IN              const   void* __ptr64* const            handle_array    OPTIONAL,\r
2390         IN                              uint32_t                                        num_handles,\r
2391         IN                              ib_ci_op_t* const                       p_ci_op,\r
2392         IN      OUT                     ci_umv_buf_t                            *p_umv_buf OPTIONAL );\r
2393 /*\r
2394 * PARAMETERS\r
2395 *       h_ca\r
2396 *               [in] A handle to an opened CA.\r
2397 *\r
2398 *       handle_array\r
2399 *               [in] This parameter references an array containing handles of\r
2400 *               existing CA resources.  This array should contain all of the\r
2401 *               handles specified in the vendor specific data provided with this\r
2402 *               call.  All handles specified through this array are validated by\r
2403 *               the verbs provider driver to ensure that the number and type of\r
2404 *               handles are correct for the requested operation.\r
2405 *\r
2406 *       num_handles\r
2407 *               [in] The number of the handles in handle array.  This count is\r
2408 *               verified by the access layer.\r
2409 *\r
2410 *       p_ci_op\r
2411 *               [in] A reference to the vendor specific CA interface data\r
2412 *               structure containing the operation parameters.\r
2413 *\r
2414 *       p_umv_buf\r
2415 *               [in out] Vendor specific parameter to support user mode IO.\r
2416 *\r
2417 * RETURN VALUES\r
2418 *       IB_SUCCESS\r
2419 *               The operation was successful.\r
2420 *\r
2421 *       IB_INVALID_CA_HANDLE\r
2422 *               The CA handle was invalid.\r
2423 *\r
2424 *       IB_INVALID_PARAMETER\r
2425 *               A reference to the vendor specific data was not provided.\r
2426 *\r
2427 *       IB_INVALID_HANDLE\r
2428 *               A handle specified in the handle array was invalid.\r
2429 *\r
2430 *       IB_INSUFFICIENT_MEMORY\r
2431 *               There was insufficient memory to perform the operation.\r
2432 *\r
2433 *       IB_ERROR\r
2434 *               An error occurred while processing the command.  Additional\r
2435 *               error information is provided in the p_ci_op status field.\r
2436 *\r
2437 * NOTES\r
2438 *       This routine performs a vendor specific CA interface function call.\r
2439 *       The p_ci_op structure provides a means to pass vendor specific data to\r
2440 *       the verbs provider driver.  If the vendor specific data contains handles,\r
2441 *       the client should provide the optional handle array that lists all of\r
2442 *        all of the handles specified in the vendor specific data.  The handles\r
2443 *       in the handle array are restricted to the following types:  ib_ca_handle_t,\r
2444 *       ib_pd_handle_t, ib_cq_handle_t, ib_av_handle_t, ib_qp_handle_t,\r
2445 *       ib_mr_handle_t, or ib_mw_handle_t\r
2446 *       The contents of the handle array are verified by the\r
2447 *       access layer and the verbs provider driver.\r
2448 *\r
2449 * SEE ALSO\r
2450 *       ci_open_ca, ci_allocate_pd, ci_create_av, ci_create_cq,\r
2451 *       ci_create_qp, ci_register_mr, ci_register_pmr,\r
2452 *       ci_register_smr, ci_create_mw, ib_ci_op_t\r
2453 *****/\r
2454 \r
2455 \r
2456 #define MAX_LIB_NAME            32\r
2457 \r
2458 #ifdef CL_KERNEL\r
2459 \r
2460 /****s* Verbs/ci_interface_t\r
2461 * NAME\r
2462 *       ci_interface_t -- Interface holding Channel Interface API's\r
2463 * PURPOSE\r
2464 *       The following structure is supplied by a Channel Interface\r
2465 *       providing verbs functionality.\r
2466 * SOURCE\r
2467 */\r
2468 \r
2469 typedef struct _ci_interface\r
2470 {\r
2471         net64_t                         guid;\r
2472 \r
2473         /*\r
2474          * Device object of the HCA.  In Windows, this is a pointer to the PDO\r
2475          * for the HCA device.\r
2476          */\r
2477         void                            *p_hca_dev;\r
2478 \r
2479         /*\r
2480          * Vendor ID, Device ID, Device Revision of the HCA\r
2481          * libname refers to the user mode library to load\r
2482          * to support direct user mode IO. If vendor does not support one\r
2483          * then the fields must be initialized to all zero's.\r
2484          */\r
2485         uint32_t                        vend_id;\r
2486         uint16_t                        dev_id;\r
2487         uint16_t                        dev_revision;\r
2488         char                            libname[MAX_LIB_NAME];\r
2489         /*\r
2490          * Version of the header file this interface export can handle\r
2491          */\r
2492         uint32_t                        version;\r
2493 \r
2494         /*\r
2495          * HCA Access Verbs\r
2496          */\r
2497         ci_open_ca                      open_ca;\r
2498         ci_um_open_ca_t         um_open_ca;\r
2499         ci_query_ca                     query_ca;\r
2500         ci_modify_ca            modify_ca;\r
2501         ci_close_ca                     close_ca;\r
2502         ci_um_close_ca_t        um_close_ca;\r
2503 \r
2504         ci_vendor_call          vendor_call;\r
2505 \r
2506         /*\r
2507          * Protection Domain\r
2508          */\r
2509         ci_allocate_pd          allocate_pd;\r
2510         ci_deallocate_pd        deallocate_pd;\r
2511 \r
2512         /*\r
2513          * Address Vector Management Verbs\r
2514          */\r
2515 \r
2516         ci_create_av            create_av;\r
2517         ci_query_av                     query_av;\r
2518         ci_modify_av            modify_av;\r
2519         ci_destroy_av           destroy_av;\r
2520 \r
2521         /*\r
2522          * QP Management Verbs\r
2523          */\r
2524         ci_create_qp            create_qp;\r
2525         ci_create_spl_qp        create_spl_qp;\r
2526         ci_modify_qp            modify_qp;\r
2527         ci_query_qp                     query_qp;\r
2528         ci_destroy_qp           destroy_qp;\r
2529 \r
2530         /*\r
2531          * Completion Queue Management Verbs\r
2532          */\r
2533         ci_create_cq            create_cq;\r
2534         ci_resize_cq            resize_cq;\r
2535         ci_query_cq                     query_cq;\r
2536         ci_destroy_cq           destroy_cq;\r
2537 \r
2538         /*\r
2539          * Memory Management Verbs\r
2540          */\r
2541         ci_register_mr          register_mr;\r
2542         ci_register_pmr         register_pmr;\r
2543         ci_query_mr                     query_mr;\r
2544         ci_modify_mr            modify_mr;\r
2545         ci_modify_pmr           modify_pmr;\r
2546         ci_register_smr         register_smr;\r
2547         ci_deregister_mr        deregister_mr;\r
2548 \r
2549         /*\r
2550          * Mellanox Fast Memory Management Verbs\r
2551          */\r
2552         ci_alloc_mlnx_fmr               alloc_mlnx_fmr;\r
2553         ci_map_phys_mlnx_fmr    map_phys_mlnx_fmr;\r
2554         ci_unmap_mlnx_fmr               unmap_mlnx_fmr;\r
2555         ci_dealloc_mlnx_fmr             dealloc_mlnx_fmr;\r
2556 \r
2557 \r
2558         /*\r
2559          * Memory Window Verbs\r
2560          */\r
2561         ci_create_mw            create_mw;\r
2562         ci_query_mw                     query_mw;\r
2563         ci_bind_mw                      bind_mw;\r
2564         ci_destroy_mw           destroy_mw;\r
2565 \r
2566         /*\r
2567          * Work Request Processing Verbs\r
2568          */\r
2569         ci_post_send            post_send;\r
2570         ci_post_recv            post_recv;\r
2571 \r
2572         /*\r
2573          * Completion Processing and\r
2574          * Completion Notification Request Verbs.\r
2575          */\r
2576         ci_peek_cq                                      peek_cq;                                /* Optional */\r
2577         ci_poll_cq                                      poll_cq;\r
2578         ci_enable_cq_notify                     enable_cq_notify;\r
2579         ci_enable_ncomp_cq_notify       enable_ncomp_cq_notify; /* Optional */\r
2580 \r
2581         /*\r
2582          * Multicast Support Verbs\r
2583          */\r
2584         ci_attach_mcast         attach_mcast;\r
2585         ci_detach_mcast         detach_mcast;\r
2586 \r
2587         /*\r
2588          * Local MAD support, for HCA's that do not support\r
2589          * Agents in the HW.\r
2590          */\r
2591         ci_local_mad            local_mad;\r
2592 \r
2593 } ci_interface_t;\r
2594 /********/\r
2595 \r
2596 \r
2597 /****f* Verbs/ib_register_ca\r
2598 * NAME\r
2599 *       ib_register_ca -- Inform the IB Access Layer about a new HCA\r
2600 * SYNOPSIS\r
2601 */\r
2602 AL_EXPORT ib_api_status_t\r
2603 ib_register_ca (\r
2604         IN              const   ci_interface_t                          *p_ci );\r
2605 /*\r
2606 * DESCRIPTION\r
2607 *       This routine is called by a HCA kernel mode driver to inform the\r
2608 *       IB Access Layer about a new HCA that is ready for use. It is expected\r
2609 *       that the Access Layer could immediatly turn around and call for services\r
2610 *       even before the call returns back the HCA driver code. The HCA driver\r
2611 *       must initialize all resources and be ready to service any calls before adding\r
2612 *       its services to the IB Access Layer.\r
2613 *\r
2614 * PARAMETERS\r
2615 *       p_ci\r
2616 *               [in] Pointer to the ci_interface_t structure that has the function\r
2617 *               vector to support verbs functionality.\r
2618 *\r
2619 * RETURN VALUE\r
2620 *       IB_SUCCESS\r
2621 *               The registration is successful.\r
2622 *\r
2623 *       IB_INVALID_PARAMETER\r
2624 *               A reference to the CI interface structure was not provided.\r
2625 *\r
2626 *       IB_INSUFFICIENT_RESOURCES\r
2627 *               Insufficient memory to satisfy resource requirements.\r
2628 *\r
2629 *       IB_DUPLICATE_CA\r
2630 *               HCA GUID is already registered with the IB Access Layer\r
2631 *\r
2632 * PORTABILITY\r
2633 *       Kernel Mode only\r
2634 *\r
2635 * SEE ALSO\r
2636 *       ib_deregister_ca, ci_interface_t\r
2637 *******/\r
2638 \r
2639 /****f* Verbs/ib_deregister_ca\r
2640 * NAME\r
2641 *       ib_deregister_ca -- Inform the IB Access Layer that this HCA is no longer available\r
2642 * SYNOPSIS\r
2643 */\r
2644 AL_EXPORT ib_api_status_t\r
2645 ib_deregister_ca (\r
2646         IN              const   net64_t                                         ca_guid );\r
2647 /*\r
2648 * DESCRIPTION\r
2649 *       This routine is called by the HCA driver when this HCA would no longer be\r
2650 *       available for services. The access layer is expected to return all resources\r
2651 *       back to the HCA driver, and perform a ci_close_ca on this interface.\r
2652 *\r
2653 * PARAMETERS\r
2654 *       ca_guid\r
2655 *               [in] GUID of the HCA that is being removed.\r
2656 *\r
2657 * RETURN VALUE\r
2658 *       IB_SUCCESS\r
2659 *               The deregistration is successful.\r
2660 *\r
2661 *       IB_NOT_FOUND\r
2662 *               No HCA with the specified GUID is registered.\r
2663 *\r
2664 *       IB_BUSY\r
2665 *               The HCA is still in use and cannot be released.\r
2666 *\r
2667 * PORTABILITY\r
2668 *       Kernel Mode only\r
2669 *\r
2670 * SEE ALSO\r
2671 *       ib_register_ca, ci_interface_t\r
2672 *******/\r
2673 #endif /* CL_KERNEL */\r
2674 \r
2675 \r
2676 #ifdef __cplusplus\r
2677 }       /* extern "C" */\r
2678 #endif  /* __cplusplus */\r
2679 \r
2680 #endif // __IB_CI_H__\r