2 * Copyright (c) 2005 SilverStorm Technologies. All rights reserved.
\r
3 * Copyright (c) 1996-2003 Intel Corporation. All rights reserved.
\r
5 * This software is available to you under the OpenIB.org BSD license
\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
12 * - Redistributions of source code must retain the above
\r
13 * copyright notice, this list of conditions and the following
\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
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
34 #if !defined(__IB_CI_H__)
\r
37 #include <iba/ib_types.h>
\r
43 #endif /* __cplusplus */
\r
46 /****h* IB_API/Verbs
\r
48 * Verbs -- Verbs implements the hardware and software glue to the OS layer.
\r
50 * Copyright© 2001 Intel Corporation - All Rights Reserved.
\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
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
72 * Version that identifies this version of the header file for interface
\r
75 #define VERBS_MAJOR_VER (0x0001)
\r
76 #define VERBS_MINOR_VER (0x0001)
\r
78 #define VERBS_VERSION (((VERBS_MAJOR_VER) << 16) | (VERBS_MINOR_VER))
\r
79 #define MK_VERBS_VERSION(maj,min) ((((maj) & 0xFFFF) << 16) | \
\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
86 /****s* Verbs/ci_umv_buf_t
\r
88 * ci_umv_buf_t -- Vendor specific structure to facilitate user mode IO
\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
99 * A command code that is understood by the vendor specific kernel
\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
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
118 * Size of the input buffer, must be set by the user mode vendor
\r
119 * specific library.
\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
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
134 typedef struct _umv_buf
\r
138 uint32_t input_size;
\r
139 uint32_t output_size;
\r
140 void* __ptr64 p_inout_buf;
\r
144 /****f* Verbs/ci_completion_cb_t
\r
146 * ci_completion_cb_t -- Completion Notification callback.
\r
151 (*ci_completion_cb_t)(
\r
152 IN void *cq_context );
\r
156 * This function prototype indicates the parameter passed to ci_open_ca()
\r
157 * to receive completion callbacks.
\r
160 * [in] Completion queue context passed during the ci_create_cq
\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
168 * ci_open_ca, ci_create_cq
\r
173 /****f* Verbs/ci_async_event_cb_t
\r
175 * ci_async_event_cb_t
\r
178 * Asynchronous event notification routine.
\r
183 (*ci_async_event_cb_t)(
\r
184 IN const ib_event_rec_t* const p_event_record );
\r
188 * [in] Information describing the type of event that has occurred.
\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
198 /****f* Verbs/ci_open_ca
\r
200 * ci_open_ca -- open and possibly obtain a handle to access the HCA.
\r
204 typedef ib_api_status_t
\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
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
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
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
234 * [out] Pointer to a handle to the newly open instance of the CA returned
\r
235 * by the Verbs Provider.
\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
245 * The interface is already open by another consumer.
\r
247 * ca_guid passed is not valid
\r
250 * ci_query_ca, ci_modify_ca, ci_close_ca
\r
254 /****f* Verbs/ci_um_open_ca
\r
256 * ci_um_open_ca -- Create a CA context for use by user-mode processes.
\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
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
271 * [in] Handle returned by an earlier call to ci_open_ca()
\r
273 * [in/out] Vendor specific parameter to support user mode IO.
\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
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
286 * IB_INVALID_PARAMETER
\r
287 * The p_umv_buf parameters are insufficient to complete the request.
\r
290 * ci_query_ca, ci_modify_ca, ci_close_ca
\r
294 /****f* Verbs/ci_query_ca
\r
296 * ci_query_ca -- Query the attributes of the HCA
\r
300 typedef ib_api_status_t
\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
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
314 * [in] Handle returned by an earlier call to ci_open_ca()
\r
316 * [out] CA attribute of this Host Channel adapter
\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
323 * [in out] Vendor specific parameter to support user mode IO.
\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
332 * IB_INVALID_PARAMETER
\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
342 * ci_open_ca, ci_modify_ca
\r
345 /****f* Verbs/ci_modify_ca
\r
347 * ci_modify_ca -- Modify port attributes and error counters
\r
351 typedef ib_api_status_t
\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
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
366 * [in] Handle returned by previous call to ci_open_ca()
\r
368 * [in] Port number, which needs to be modified.
\r
370 * [in] Command mask to perform operations on.
\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
377 * Modify port attributes was performed
\r
379 * Invalid port number supplied in port_att.
\r
380 * IB_INVALID_PARAMETER
\r
381 * Unknown Command supplied in port_attr.
\r
383 * Optional Q_KEY and P_KEY violation counters are not supported.
\r
384 * IB_INVALID_CA_HANDLE
\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
394 * ci_open_ca, ci_query_ca, ci_close_ca
\r
398 /****f* Verbs/ci_close_ca
\r
400 * ci_close_ca -- Close access to adapter via this h_ca
\r
404 typedef ib_api_status_t
\r
406 IN ib_ca_handle_t h_ca );
\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
414 * [in] CA handle returned via the ci_open_ca() call.
\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
421 * Some resource allocated via this handle is not freed.
\r
422 * IB_INVALID_CA_HANDLE
\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
431 * Resources allocated during the ci_open_ca() is deallocated. Other resource
\r
432 * cleanup are responsibility of the consumer .
\r
437 /****f* Verbs/ci_um_close_ca_t
\r
439 * ci_um_close_ca_t -- Close user-mode access to adapter via this h_ca
\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
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
453 * [in] CA handle returned via the ci_open_ca() call.
\r
455 * [in] CA handle returned via the ci_um_open_ca() call.
\r
458 * This funtion does not return a value.
\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
463 * Resources allocated during the ci_um_open_ca() are deallocated.
\r
469 /****f* Verbs/ci_allocate_pd
\r
471 * ci_allocate_pd -- Allocate a protection domain for this adapter.
\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
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
489 * [in] Handle returned by ci_open_ca()
\r
492 * [in] Type of the protection domain. CA vendors may use this
\r
493 * information to optimize how the PD is allocated.
\r
496 * [out] The handle to the newly created protection domain
\r
499 * [in/out] Vendor specific parameter to support user mode IO.
\r
503 * PD is successfully allocated and the ph_pd is valid.
\r
505 * IB_INSUFFICIENT_RESOURCES
\r
506 * No more PD's available for this adapter.
\r
508 * IB_INVALID_CA_HANDLE
\r
509 * HCA handle is not valid
\r
515 /****f* Verbs/ci_deallocate_pd
\r
517 * ci_deallocate_pd -- Deallocate a protection domain object.
\r
521 typedef ib_api_status_t
\r
522 (*ci_deallocate_pd) (
\r
523 IN ib_pd_handle_t h_pd );
\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
532 * [in] Handle allocated via the ci_allocate_pd()
\r
535 * PD is freed successfully
\r
536 * IB_INVALID_PD_HANDLE
\r
537 * pd_handle is invalid
\r
539 * PD is probably still bound to some resource
\r
546 /****f* Verbs/ci_create_av
\r
548 * ci_create_av -- Create an address vector for use in UD.
\r
552 typedef ib_api_status_t
\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
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
566 * [in] Protection domain to which this av is associated.
\r
568 * [in] Parameters to create the address vector handle
\r
570 * [out] Handle to use for datagram sends.
\r
572 * [in out] Vendor specific parameter to support user mode IO.
\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
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
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
593 /****f* Verbs/ci_query_av
\r
595 * ci_query_av -- Obtain the address vector associated with the handle
\r
599 typedef ib_api_status_t
\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
608 * This routine returns the address vector and pd_handle associated with the
\r
612 * [in] Handle to the address vector
\r
614 * [out] address vector data referred by the av_handle
\r
616 * [out] pd handle associated with the av_handle
\r
618 * [in out] Vendor specific parameter to support user mode IO.
\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
627 * Invalid port number passed in the Address Vector.
\r
629 * ci_create_av, ci_modify_av
\r
633 /****f* Verbs/ci_modify_av
\r
635 * ci_modify_av -- Change the address vector referred by the av_handle
\r
639 typedef ib_api_status_t
\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
646 * This routine allows a consumer to modify the address information
\r
650 * [in] Address handle that needs to be updated with new info.
\r
652 * [in] New address vector to associate with the addr_handle.
\r
654 * [in out] Vendor specific parameter to support user mode IO.
\r
657 * Operation was successful
\r
658 * IB_INVALID_AV_HANDLE
\r
659 * The address vector handle was invalid
\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
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
670 * ci_create_av, ci_query_av
\r
674 /****f* Verbs/ci_destroy_av
\r
676 * ci_destroy_av -- Destroy the address vector
\r
680 typedef ib_api_status_t
\r
682 IN const ib_av_handle_t h_av );
\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
689 * [in] Handle that needs to be destroyed.
\r
692 * Operation was successful.
\r
693 * IB_INVALID_AV_HANDLE
\r
694 * The address vector handle was invalid
\r
700 /****f* Verbs/ci_create_qp
\r
702 * ci_create_qp -- Create a Queue Pair for the specified HCA
\r
706 typedef ib_api_status_t
\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
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
722 * [in] Handle to Protection Domain
\r
724 * [in] A user specified context passed in a asynchronous error callback.
\r
726 * [in] Initial attributes with which the qp must be created.
\r
728 * [out] Attributes of the newly created queue pair.
\r
730 * [out] Handle to the queue pair newly created.
\r
732 * [in out] Vendor specific parameter to support user mode IO.
\r
735 * The queue pair is successfully created with the provided initial
\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
750 * Unreliable datagram not supported
\r
751 * IB_INVALID_PARAMETER
\r
752 * The parameter p_create_attr is invalid.
\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
758 * ci_create_spl_qp, ci_query_qp, ci_modify_qp, ci_destroy_qp
\r
762 /****f* Verbs/ci_create_spl_qp
\r
764 * ci_create_spl_qp -- Create a special queue pair.
\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
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
783 * [in] Handle to the PD on which the special queue pair is to be created.
\r
785 * [in] Port number for which this special queue pair is created.
\r
787 * [in] User specified context passed during the async error callback
\r
790 * [in] Initial set of attributes with which the queue pair is to be
\r
793 * [out] QP attributes after the qp is successfully created.
\r
796 * [out] Handle to the special qp after its creation.
\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
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
811 * Applicable to SMI/GSI qp's. This return code means that the SMI/GSI
\r
812 * QP is already allocated.
\r
814 * Invalid protection domain supplied.
\r
816 * Invalid port number supplied.
\r
818 * Raw datagram unsupported.
\r
819 * IB_INVALID_PARAMETER
\r
820 * The parameter p_create_attr is not valid.
\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
826 * ci_create_qp, ci_query_qp, ci_modify_qp, ci_destroy_qp
\r
830 /****f* Verbs/ci_modify_qp
\r
832 * ci_modify_qp -- Modify attributes of the specified QP.
\r
836 typedef ib_api_status_t
\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
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
849 * [in] Handle to the queue pair whose state is to be modified.
\r
851 * [in] Specifies what attributes need to be modified in the qp.
\r
853 * [out] QP attributes after the qp is successfully created.
\r
855 * [in out] Vendor specific parameter to support user mode IO.
\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
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
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
877 * Refer to Table 79 in chapter 11, Volume 1 of the InfiniBand Specifications.
\r
879 * ci_create_qp, ci_create_spl_qp, ci_query_qp
\r
883 /****f* Verbs/ci_query_qp
\r
885 * ci_query_qp -- Query the current QP attributes
\r
889 typedef ib_api_status_t
\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
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
902 * [in] Handle to the QP for which the attributes are being retrieved
\r
904 * [out] Pointer to the ib_qp_query_t structure where the current
\r
905 * attributes of the QP is returned.
\r
907 * [in out] Vendor specific parameter to support user mode IO.
\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
920 /****f* Verbs/ci_destroy_qp
\r
922 * ci_destroy_qp -- Destroy the specified Queue Pair.
\r
926 typedef ib_api_status_t
\r
928 IN const ib_qp_handle_t h_qp,
\r
929 IN const uint64_t timewait );
\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
937 * [in] Handle to the qp that needs to be destroyed.
\r
939 * [in] Time (in microseconds) at which the QP should leave
\r
940 * the timewait state and can be reused.
\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
952 * If the queue pair is a unreliable datagram service type, and
\r
953 * is still bound to a multicast group.
\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
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
966 * ci_create_qp, ci_create_spl_qp
\r
970 /****f* Verbs/ci_create_cq
\r
972 * ci_create_cq -- Create a completion queue (CQ) on the specified HCA.
\r
976 typedef ib_api_status_t
\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
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
991 * [in] A handle to the open HCA
\r
993 * [in] The context that is passed during the completion callbacks.
\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
999 * [out] Handle to the newly created CQ on successful creation.
\r
1001 * [in out] Vendor specific parameter to support user mode IO.
\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
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
1022 * ci_destroy_cq, ci_query_cq, ci_resize_cq
\r
1026 /****f* Verbs/ci_resize_cq
\r
1028 * ci_resize_cq -- Modify the maximum number of entries the CQ could hold.
\r
1032 typedef ib_api_status_t
\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
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
1046 * [in] Completion Queue handle
\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
1052 * [in out] Vendor specific parameter to support user mode IO.
\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
1065 * The CQ has more entries than the resize request. The CQ is not
\r
1066 * modified, and old entries still exist.
\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
1079 /****f* Verbs/ci_query_cq
\r
1081 * ci_query_cq -- Query the number of entries configured for the CQ.
\r
1085 typedef ib_api_status_t
\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
1092 * This routine returns the maximum number of entries this completion
\r
1093 * queue is configured.
\r
1096 * [in] Handle to the completion queue
\r
1098 * [out] The number of entries the completion queue is configured to hold
\r
1100 * [in out] Vendor specific parameter to support user mode IO.
\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
1109 * ci_create_cq, ci_resize_cq
\r
1113 /****f* Verbs/ci_destroy_cq
\r
1115 * ci_destroy_cq -- Destroy a completion queue.
\r
1119 typedef ib_api_status_t
\r
1120 (*ci_destroy_cq) (
\r
1121 IN const ib_cq_handle_t h_cq );
\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
1129 * [in] Handle to the cq that is to be destroyed.
\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
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
1155 /****f* Verbs/ci_register_mr
\r
1157 * ci_register_mr -- Register a memory region with the HCA.
\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
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
1178 * [in] Handle to the PD on which memory is being registered
\r
1180 * [in] Holds attributes for the region being registered. Look at
\r
1181 * ib_mr_create_t for more details.
\r
1183 * [out] Local Key Attributes of the registered memory region
\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
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
1193 * [in] Boolean indicating whether the registration originated in user-mode.
\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
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
1213 * ci_deregister_mr, ci_query_mr, ci_register_pmr, ci_modify_mr,
\r
1218 /****f* Verbs/ci_register_pmr
\r
1220 * ci_register_pmr -- Register a physical memory region with the HCA.
\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
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
1242 * [in] Handle to the PD on which memory is being registered
\r
1244 * [in] Holds attributes for the region being registered.
\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
1250 * [out] Local key of the registered memory region
\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
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
1260 * [in] Boolean indicating whether the registration originated in user-mode.
\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
1274 * Kernel Mode only
\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
1284 * ci_deregister_mr, ci_query_mr, ci_register_mr, ci_modify_mr,
\r
1289 /****f* Verbs/ci_query_mr
\r
1291 * ci_query_mr -- Query attributes of a registered memory region
\r
1295 typedef ib_api_status_t
\r
1297 IN const ib_mr_handle_t h_mr,
\r
1298 OUT ib_mr_attr_t* const p_mr_query );
\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
1306 * [in] Memory handle for which the attributes need to be retrieved.
\r
1308 * [out] Attributes of the memory region associated with memory handle.
\r
1311 * The routine completed successfully and attributes returned
\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
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
1323 * ci_register_mr, ci_register_pmr
\r
1327 /****f* Verbs/ci_modify_mr
\r
1329 * ci_modify_mr -- Modify some or all parameters of a memory region.
\r
1333 typedef ib_api_status_t
\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
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
1350 * [in] Handle to the memory region whose attributes are to be modified.
\r
1352 * [in] Command specifying which parts of the mem_region is valid. The
\r
1353 * command is specified as a bit mask.
\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
1359 * [out] The new l_key for this newly registered memory region.
\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
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
1371 * [in] Boolean indicating whether the registration originated in user-mode.
\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
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
1395 * ci_register_mr, ci_register_pmr, ci_register_smr
\r
1399 /****f* Verbs/ci_modify_pmr
\r
1401 * ci_modify_pmr -- Modify some or all parameters of a memory region.
\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
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
1423 * [in] Handle to the memory region whose attributes are to be modified.
\r
1425 * [in] Command specifying which parts of the mem_region is valid. The
\r
1426 * command is specified as a bit mask.
\r
1428 * [in] Desired attributes that need to be modified for mem_handle.
\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
1434 * [out] The new l_key for this newly registered physical memory region.
\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
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
1446 * [in] Boolean indicating whether the registration originated in user-mode.
\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
1464 * Kernel Mode only
\r
1466 * Remote and Atomic access settings in ib_access_ctrl_t, requires local
\r
1467 * write access to be enabled.
\r
1469 * ci_register_mr, ci_register_pmr, ci_register_smr
\r
1473 /****f* Verbs/ci_register_smr
\r
1475 * ci_register_smr -- Register a memory region using same physical pages as
\r
1476 * an existing memory region.
\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
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
1497 * [in] Handle to memory region whose physical pages are being registered
\r
1498 * by this shared registration.
\r
1500 * [in] Handle to the PD on which memory is being registered
\r
1502 * [in] Memory access restrictions on the registered memory.
\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
1508 * [out] L_KEY for this memory region.
\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
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
1519 * [in] Boolean indicating whether the registration originated in user-mode.
\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
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
1534 * ci_register_mr, ci_register_pmr, ci_modify_mr, ci_modify_pmr
\r
1538 /****f* Verbs/ci_deregister_mr
\r
1540 * ci_deregister_mr -- Deregister a memory region
\r
1544 typedef ib_api_status_t
\r
1545 (*ci_deregister_mr) (
\r
1546 IN const ib_mr_handle_t h_mr );
\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
1558 * [in] Memory handle that is being de-registered.
\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
1568 * ci_register_mr, ci_register_pmr, ci_register_smr
\r
1572 /****f* Verbs/ci_create_mw
\r
1574 * ci_create_mw -- Create a memory window entry for later use
\r
1578 typedef ib_api_status_t
\r
1580 IN const ib_pd_handle_t h_pd,
\r
1581 OUT net32_t* const p_rkey,
\r
1582 OUT ib_mw_handle_t *ph_mw,
\r
1583 IN OUT ci_umv_buf_t *p_umv_buf OPTIONAL );
\r
1586 * This routine allocates a memory window. This window entry cannot be used
\r
1587 * for remote access unless this window is bound to a memory region
\r
1588 * via the ci_bind_mw call.
\r
1591 * [in] Protection domain handle to use for this memory window
\r
1593 * [out] Remote access key that can be exchanged with a remote node to
\r
1594 * perform RDMA transactions on this memory window. This R_KEY is still not
\r
1595 * bound to any memory regions, until a successful call to ci_bind_mw.
\r
1596 * VPD is required to give this in the expected ordering on the wire. When
\r
1597 * rkey's are exchanged between remote nodes, no swapping of this data
\r
1598 * will be performed.
\r
1600 * [out] Handle to the newly created memory window.
\r
1602 * [in out] Vendor specific parameter to support user mode IO.
\r
1605 * The memory window allocation completed successfully.
\r
1606 * IB_INSUFFICIENT_RESOURCES
\r
1607 * Not enough resources to complete the request.
\r
1608 * IB_INVALID_PD_HANDLE
\r
1609 * pd_handle supplied is invalid.
\r
1610 * IB_INVALID_PARAMETER
\r
1611 * One of the pointers was not valid.
\r
1613 * ci_destroy_mw, ci_query_mw, ci_bind_mw
\r
1617 /****f* Verbs/ci_query_mw
\r
1619 * ci_query_mw -- Query memory window attributes for memory window handle
\r
1623 typedef ib_api_status_t
\r
1625 IN const ib_mw_handle_t h_mw,
\r
1626 OUT ib_pd_handle_t *ph_pd,
\r
1627 OUT net32_t* const p_rkey,
\r
1628 IN OUT ci_umv_buf_t *p_umv_buf OPTIONAL );
\r
1631 * This routine retrieves the current R_KEY and protection domain
\r
1632 * handle associated with this mw_handle.
\r
1635 * [in] Memory window handle whose attributes are being retrieved.
\r
1637 * [out] Protection domain handle associated with this mw_handle
\r
1639 * [out] Current R_KEY associated with this mw_handle.The verbs provider
\r
1640 * is required to give this in the expected ordering on the wire. When
\r
1641 * rkey's are exchanged between remote nodes, no swapping of this data
\r
1642 * will be performed.
\r
1644 * [in out] Vendor specific parameter to support user mode IO.
\r
1647 * The query operation completed successfully.
\r
1648 * IB_INVALID_MW_HANDLE
\r
1649 * mw_handle supplied is an invalid handle
\r
1650 * IB_INVALID_PARAMETER
\r
1651 * One of the pointers was not valid.
\r
1653 * ci_create_mw, ci_bind_mw
\r
1657 /****f* Verbs/ci_bind_mw
\r
1659 * ci_bind_mw -- Bind a memory window to a memory region.
\r
1663 typedef ib_api_status_t
\r
1665 IN const ib_mw_handle_t h_mw,
\r
1666 IN const ib_qp_handle_t h_qp,
\r
1667 IN ib_bind_wr_t* const p_mw_bind,
\r
1668 OUT net32_t* const p_rkey );
\r
1671 * This routine posts a request to bind a memory window to a registered
\r
1672 * memory region. If the queue pair was created with selectable signaling,
\r
1673 * once the operation is completed successfully then a completion queue entry
\r
1674 * is generated indicating the bind operation has completed. The IB_POST_FENCE
\r
1675 * option could be specified to cause the requestor to wait until outstanding
\r
1676 * RDMA operations can be completed.
\r
1679 * [in] Handle to memory window that needs to be bound to a memory region.
\r
1681 * [in] Queue Pair to which this bind request is to be posted.
\r
1683 * [in] Input parameters for this bind request, consisting of virtual
\r
1684 * addr range of bind request etc.
\r
1686 * [out] On successful completion, the new R_KEY is returned.
\r
1687 * VPD is required to give this in the expected ordering on the wire. When
\r
1688 * rkey's are exchanged between remote nodes, no swapping of this data
\r
1689 * will be performed.
\r
1692 * The memory bind operation was posted successfully.
\r
1693 * IB_INSUFFICIENT_RESOURCES
\r
1694 * Insufficient resources to complete the request.
\r
1695 * No more WQE's to post this request
\r
1696 * No more free WQE's to post this request
\r
1697 * IB_INVALID_MW_HANDLE
\r
1698 * memw_handle supplied is an invalid memory window handle.
\r
1699 * IB_INVALID_PERMISSION
\r
1700 * Invalid access rights specified in request
\r
1701 * IB_INVALID_SERVICE_TYPE
\r
1702 * Invalid service type for this qp_handle.
\r
1703 * IB_INVALID_PARAMETER
\r
1704 * One of the pointers was not valid.
\r
1706 * R_KEY specified is invalid for the memory region being bound.
\r
1707 * IB_INVALID_QP_HANDLE
\r
1708 * h_qp supplied was an invalid QP handle.
\r
1710 * - A previously bound memory window can be bound to the same or different
\r
1713 * - A bind operation with length of 0, invalidates any previous binding
\r
1714 * and returns an R_KEY in the unbound state.
\r
1720 /****f* Verbs/ci_destroy_mw
\r
1722 * ci_destroy_mw -- Destroy a memory window.
\r
1726 typedef ib_api_status_t
\r
1727 (*ci_destroy_mw) (
\r
1728 IN const ib_mw_handle_t h_mw );
\r
1731 * This routine deallocates a window entry created via a ci_create_mw.
\r
1732 * Once this operation is complete, the channel interface guarantees that
\r
1733 * no future remote accesses will be permitted to this window entry.
\r
1736 * [in] Handle to the memory window that is being destroyed.
\r
1739 * The destroy window request completed successfully.
\r
1740 * IB_INVALID_MW_HANDLE
\r
1741 * memw_handle supplied is invalid.
\r
1743 * Deallocate memory window implicitly means the window is also unbound
\r
1744 * once the call completes successfully. Any future remote access with
\r
1745 * the same R_KEY should fail with protection violation.
\r
1751 /****f* Verbs/ci_post_send
\r
1753 * ci_post_send -- Post a work request to the send side of a queue pair.
\r
1757 typedef ib_api_status_t
\r
1759 IN const ib_qp_handle_t h_qp,
\r
1760 IN ib_send_wr_t* const p_send_wr,
\r
1761 OUT ib_send_wr_t **pp_failed );
\r
1764 * This routine posts a work request to the send side of the queue pair.
\r
1765 * The different types of work request that can be posted are explained in
\r
1766 * the ib_wr_t structure. For exact details on ordering rules please consult
\r
1767 * the Volume 1, of the InfiniBand Specifications. If there is more
\r
1768 * outstanding requests posted that what the queue is configured for, an
\r
1769 * immediate error is returned.
\r
1772 * [in] The queue pair to which this work request is being submitted.
\r
1774 * [in] A pointer to the head of the list that must be posted to the
\r
1777 * [out] A pointer to the head of the list that holds the failed WRs.
\r
1778 * If all the entries provided are posted with the CI, then this parameter
\r
1779 * would be set to NULL.
\r
1781 * Any unsuccessful status indicates the status of the first failed request.
\r
1784 * All the work requests are completed successfully
\r
1785 * IB_INVALID_QP_HANDLE
\r
1786 * The qp_handle supplied is invalid.
\r
1787 * IB_INSUFFICIENT_RESOURCES
\r
1788 * Insufficient resources to complete the request.
\r
1789 * There are no more work elements in the channel interface to
\r
1790 * process this request, and the total outstanding work request has
\r
1792 * IB_INVALID_WR_TYPE
\r
1793 * The work request type was not valid.
\r
1794 * IB_INVALID_QP_STATE
\r
1795 * The queue pair is either in Reset, Init, RTR or Error state.
\r
1796 * IB_INVALID_MAX_SGE
\r
1797 * The work request has too many scatter gather elements than what the
\r
1798 * QP is configured.
\r
1800 * Atomics or Reliable datagram request is not supported by this HCA.
\r
1801 * IB_INVALID_ADDR_HANDLE
\r
1802 * Address handle supplied in the work request is invalid.
\r
1804 * Please refer to Table 81 and Table 82 for allowed operation types
\r
1805 * on different types of queue pairs, and the different modifiers
\r
1806 * acceptable for the work request for different QP service types.
\r
1808 * ci_post_recv, ci_poll_cq
\r
1812 /****f* Verbs/ci_post_recv
\r
1814 * ci_post_recv -- Post a work request to the receive queue of a queue pair.
\r
1818 typedef ib_api_status_t
\r
1820 IN const ib_qp_handle_t h_qp,
\r
1821 IN ib_recv_wr_t* const p_recv_wr,
\r
1822 OUT ib_recv_wr_t **pp_failed );
\r
1825 * This routine allows to queue a work request to the receive side of a
\r
1826 * queue pair. The work_req holds necessary data to satisfy an incoming
\r
1827 * receive message. If an attempt is made to queue more work requests than
\r
1828 * what is available, an error is returned.
\r
1831 * [in] Handle to the queue pair to which the receive work request is being
\r
1834 * [in] Holds the WRs to be posted to the receive queue.
\r
1836 * [out] If any entry could not be posted with the CI, then this points
\r
1837 * to the first WR that completed unsuccessfully. If all entries are
\r
1838 * posted, then this field is set to NULL on successful exit.
\r
1840 * Any unsuccessful status indicates the status of the first failed request.
\r
1843 * The work request was successfully queued to the receive side of the QP.
\r
1844 * IB_INVALID_QP_HANDLE
\r
1845 * qp_handle supplied is not valid.
\r
1846 * IB_INSUFFICIENT_RESOURCES
\r
1847 * The qp has exceeded its receive queue depth than what is has been
\r
1849 * IB_INVALID_WR_TYPE
\r
1850 * Invalid work request type found in the request.
\r
1851 * IB_INVALID_QP_STATE
\r
1852 * QP was in reset or init state.
\r
1853 * (TBD: there may be an errata that allows posting in init state)
\r
1855 * ci_post_send, ci_poll_cq.
\r
1859 /****f* Verbs/ci_peek_cq
\r
1864 * Returns the number of entries currently on the completion queue.
\r
1868 typedef ib_api_status_t
\r
1870 IN const ib_cq_handle_t h_cq,
\r
1871 OUT uint32_t* const p_n_cqes );
\r
1875 * [in] Handle to the completion queue to peek.
\r
1878 * [out] The number of completion entries on the CQ.
\r
1882 * The peek operation completed successfully.
\r
1883 * IB_INVALID_CQ_HANDLE
\r
1884 * The completion queue handle was invalid.
\r
1885 * IB_INVALID_PARAMETER
\r
1886 * A reference to the completion queue entry count was not provided.
\r
1888 * This operation is not supported by the channel adapter.
\r
1891 * The value returned is a snapshot of the number of compleiton queue
\r
1892 * entries curently on the completion queue. Support for this operation
\r
1893 * is optional by a channel adapter vendor.
\r
1896 * ci_create_cq, ci_poll_cq, ci_enable_cq_notify, ci_enable_ncomp_cq_notify
\r
1899 /****f* Verbs/ci_poll_cq
\r
1901 * ci_poll_cq -- Retrieve a work completion record from a completion queue
\r
1905 typedef ib_api_status_t
\r
1907 IN const ib_cq_handle_t h_cq,
\r
1908 IN OUT ib_wc_t** const pp_free_wclist,
\r
1909 OUT ib_wc_t** const pp_done_wclist );
\r
1912 * This routine retrieves a work completion entry from the specified
\r
1913 * completion queue. The contents of the data returned in a work completion
\r
1914 * is specified in ib_wc_t.
\r
1917 * [in] Handle to the completion queue being polled.
\r
1919 * [in out] A list of work request structures provided by the consumer
\r
1920 * for the channel interface to return completed Completion Queue
\r
1921 * entries. If not all the entries are consumed, this list holds the
\r
1922 * list of un-utilized completion entries provided back to the consumer.
\r
1924 * [out] A list of work completions retrieved from the completion queue
\r
1925 * and successfully processed.
\r
1928 * Poll completed successfully and found one or more entries. If on
\r
1929 * completion the pp_free_wclist is empty, then there are potentially more
\r
1930 * entries and the consumer must continue to retrieve entries.
\r
1931 * IB_INVALID_CQ_HANDLE
\r
1932 * The cq_handle supplied is not valid.
\r
1934 * There were no completion entries found in the specified CQ.
\r
1936 * ci_create_cq, ci_post_send, ci_post_recv, ci_bind_mw
\r
1940 /****f* Verbs/ci_enable_cq_notify
\r
1942 * ci_enable_cq_notify -- Invoke the Completion handler, on next entry added.
\r
1946 typedef ib_api_status_t
\r
1947 (*ci_enable_cq_notify) (
\r
1948 IN const ib_cq_handle_t h_cq,
\r
1949 IN const boolean_t solicited );
\r
1952 * This routine instructs the channel interface to invoke the completion
\r
1953 * handler when the next completion queue entry is added to this CQ.
\r
1954 * Please refer to Volume 1, of the InfiniBand specification for a complete
\r
1958 * [in] Handle to the CQ on which the notification is being enabled.
\r
1960 * [in] A boolean flag indicating whether the request is to generate a
\r
1961 * notification on the next entry or on the next solicited entry
\r
1962 * being added to the completion queue.
\r
1965 * The notification request was registered successfully.
\r
1966 * IB_INVALID_CQ_HANDLE
\r
1967 * cq_handle supplied is not a valid handle.
\r
1969 * The consumer cannot call a request for notification without emptying
\r
1970 * entries from the CQ. i.e if a consumer registers for a notification
\r
1971 * request in the completion callback before pulling entries from the
\r
1972 * CQ via ci_poll_cq, the notification is not generated for completions
\r
1973 * already in the CQ. For e.g. in the example below, if there are no calls
\r
1974 * to ci_poll_cq() after the ci_enable_cq_notify(). For any CQ entries added
\r
1975 * before calling this ci_enable_cq_notify() call, the consumer does not
\r
1976 * get a completion notification callback. In order to comply with the verb
\r
1977 * spec, consumer is supposed to perform a ci_poll_cq() after the
\r
1978 * ci_enable_cq_notify() is made to retrive any entries that might have
\r
1979 * been added to the CQ before the CI registers the notification enable.
\r
1981 * while ((ret_val = ci_poll_cq(cq_handle, &free_list, &done_list)
\r
1984 * process entries;
\r
1986 * if (ret_val == IB_NOT_FOUND)
\r
1987 * ci_enable_cq_notify(cq_handle);
\r
1988 * // Need to perform a ci_poll_cq()
\r
1989 * // after the enable.
\r
1991 * ci_create_cq, ci_peek_cq, ci_poll_cq, ci_enable_ncomp_cq_notify
\r
1995 /****f* Verbs/ci_enable_ncomp_cq_notify
\r
1997 * ci_enable_ncomp_cq_notify -- Invoke the Completion handler when the next
\r
1998 * N completions are added.
\r
2002 typedef ib_api_status_t
\r
2003 (*ci_enable_ncomp_cq_notify) (
\r
2004 IN const ib_cq_handle_t h_cq,
\r
2005 IN const uint32_t n_cqes );
\r
2008 * This routine instructs the channel interface to invoke the completion
\r
2009 * handler when the next N completions have been added to this CQ.
\r
2012 * [in] Handle to the CQ on which the notification is being enabled.
\r
2014 * [in] The number of completion queue entries to be added to the
\r
2015 * completion queue before notifying the client. This value must
\r
2016 * greater than or equal to one and less than or equal to the size
\r
2017 * of the completion queue.
\r
2021 * The notification request was registered successfully.
\r
2022 * IB_INVALID_CQ_HANDLE
\r
2023 * cq_handle supplied is not a valid handle.
\r
2024 * IB_INVALID_PARAMETER
\r
2025 * The requested number of completion queue entries was invalid.
\r
2027 * This operation is not supported by the channel adapter.
\r
2030 * This routine instructs the channel interface to invoke the completion
\r
2031 * handler when the next N completions have been added to this CQ regardless
\r
2032 * of the completion type (solicited or unsolicited). Any CQ entries that
\r
2033 * existed before the rearm is enabled will not result in a call to the
\r
2034 * handler. Support for this operation is optional by a channel adapter
\r
2038 * ci_create_cq, ci_peek_cq, ci_poll_cq, ci_enable_cq_notify
\r
2042 /****f* Verbs/ci_attach_mcast
\r
2044 * ci_attach_mcast -- Attach a queue pair to a multicast group
\r
2048 typedef ib_api_status_t
\r
2049 (*ci_attach_mcast) (
\r
2050 IN const ib_qp_handle_t h_qp,
\r
2051 IN const ib_gid_t *p_mcast_gid,
\r
2052 IN const ib_net16_t mcast_lid,
\r
2053 OUT ib_mcast_handle_t *ph_mcast,
\r
2054 IN OUT ci_umv_buf_t *p_umv_buf OPTIONAL );
\r
2057 * This routine attaches the given qp_handle to a multicast gid as specified
\r
2058 * by mcast_gid parameter.
\r
2061 * [in] Queue pair handle which needs to be added to the multicast group
\r
2064 * [in] The multicast group LID value.
\r
2066 * [in] IPv6 address associated with this multicast group.
\r
2068 * [out] Multicast handle holding the association of this queue pair
\r
2069 * to the multicast group.
\r
2071 * [in out] Vendor specific parameter to support user mode IO.
\r
2074 * The queue pair handle was successfully added to the multicast
\r
2076 * IB_INVALID_QP_HANDLE
\r
2077 * qp_handle supplied is invalid.
\r
2078 * IB_INVALID_SERVICE_TYPE
\r
2079 * Queue pair handle supplied is not of unreliable datagram type.
\r
2081 * The supplied addr is not a valid multicast ipv6 address.
\r
2083 * The supplied lid is not a valid multicast lid.
\r
2085 * Multicast is not supported by this HCA.
\r
2086 * IB_INSUFFICIENT_RESOURCES
\r
2087 * Insufficient resources to complete request.
\r
2088 * IB_INVALID_PARAMETER
\r
2089 * One of the parameters was NULL.
\r
2091 * ci_create_qp, ci_detach_mcast
\r
2096 /****f* Verbs/ci_detach_mcast
\r
2098 * ci_detach_mcast -- Detach a queue pair from a multicast group
\r
2102 typedef ib_api_status_t
\r
2103 (*ci_detach_mcast) (
\r
2104 IN const ib_mcast_handle_t h_mcast );
\r
2107 * This routine detaches a queue pair from its previously associated multicast
\r
2111 * [in] The multicast handle passed back to consumer after the
\r
2112 * ci_mcast_attach call.
\r
2115 * The qp was successfully detached from the multicast group.
\r
2116 * IB_INVALID_MCAST_HANDLE
\r
2117 * mcast_handle supplied is an invalid handle
\r
2118 * IB_INVALID_PARAMETER
\r
2119 * One of the parameters was NULL.
\r
2125 /****f* Verbs/ci_local_mad
\r
2127 * ci_local_mad -- Request a mad to be processed by the local adapter.
\r
2131 typedef ib_api_status_t
\r
2133 IN const ib_ca_handle_t h_ca,
\r
2134 IN const uint8_t port_num,
\r
2135 IN const ib_mad_t *p_mad_in,
\r
2136 OUT ib_mad_t *p_mad_out );
\r
2139 * This routine is OPTIONAL for the channel interface. This is required
\r
2140 * for adapters which do not have the agents such as Subnet Management
\r
2141 * agent (SMA) Or the GSA in the Verbs Provider driver.
\r
2142 * hardware, for all such adapters the exact queue pair management of
\r
2143 * special queue pairs happen above the channel interface. This routine
\r
2144 * is used to perform local operations, since there is no agent below the
\r
2145 * channel interface. For e.g: If a Subnet Management packet (SMP) to
\r
2146 * set PORT_STATE is received, this reception is processed above the channel
\r
2147 * interface, then this call is done to set the port state on the local
\r
2148 * adapter. On successful return, the response is generated and sent to the
\r
2152 * [in] A handle to the channel adapter that should process the MAD.
\r
2153 * This must be the same adapter that the MAD was received on.
\r
2155 * [in] port number to which this request is directed is to be sent.
\r
2157 * [in] pointer to a management datagram (MAD) structure containing
\r
2158 * the command to be processed.
\r
2160 * [out] Response packet after processing the command. The storage to this
\r
2161 * must be allocated by the consumer.
\r
2164 * Command processed successfully.
\r
2165 * IB_INVALID_CA_HANDLE
\r
2166 * The HCA handle supplied is not valid.
\r
2168 * The port number supplied is invalid.
\r
2170 * Kernel Mode only
\r
2172 * This call is provided to aid adapters that don't have a agent functionality
\r
2173 * built in the channel interface. Some adapters do have a local processor
\r
2174 * to process these packets, hence even for local port management, we can
\r
2175 * use the same mechanism we use to configure external nodes by using a
\r
2176 * hop counter = 1 in the MAD packets. If the SMA indicates it has a local
\r
2177 * sma in the ib_ca_attr_t, then the packets are posted to the adapter
\r
2178 * instead of making a private call to the adapter.
\r
2180 * ci_query_ca, ci_ca_attr_t
\r
2185 /****f* Verbs/ci_vendor_call
\r
2190 * Performs a vendor specific CA interface function call.
\r
2194 typedef ib_api_status_t
\r
2195 (*ci_vendor_call)(
\r
2196 IN const ib_ca_handle_t h_ca,
\r
2197 IN const void* __ptr64* const handle_array OPTIONAL,
\r
2198 IN uint32_t num_handles,
\r
2199 IN ib_ci_op_t* const p_ci_op,
\r
2200 IN OUT ci_umv_buf_t *p_umv_buf OPTIONAL );
\r
2204 * [in] A handle to an opened CA.
\r
2207 * [in] This parameter references an array containing handles of
\r
2208 * existing CA resources. This array should contain all of the
\r
2209 * handles specified in the vendor specific data provided with this
\r
2210 * call. All handles specified through this array are validated by
\r
2211 * the verbs provider driver to ensure that the number and type of
\r
2212 * handles are correct for the requested operation.
\r
2215 * [in] The number of the handles in handle array. This count is
\r
2216 * verified by the access layer.
\r
2219 * [in] A reference to the vendor specific CA interface data
\r
2220 * structure containing the operation parameters.
\r
2223 * [in out] Vendor specific parameter to support user mode IO.
\r
2227 * The operation was successful.
\r
2229 * IB_INVALID_CA_HANDLE
\r
2230 * The CA handle was invalid.
\r
2232 * IB_INVALID_PARAMETER
\r
2233 * A reference to the vendor specific data was not provided.
\r
2235 * IB_INVALID_HANDLE
\r
2236 * A handle specified in the handle array was invalid.
\r
2238 * IB_INSUFFICIENT_MEMORY
\r
2239 * There was insufficient memory to perform the operation.
\r
2242 * An error occurred while processing the command. Additional
\r
2243 * error information is provided in the p_ci_op status field.
\r
2246 * This routine performs a vendor specific CA interface function call.
\r
2247 * The p_ci_op structure provides a means to pass vendor specific data to
\r
2248 * the verbs provider driver. If the vendor specific data contains handles,
\r
2249 * the client should provide the optional handle array that lists all of
\r
2250 * all of the handles specified in the vendor specific data. The handles
\r
2251 * in the handle array are restricted to the following types: ib_ca_handle_t,
\r
2252 * ib_pd_handle_t, ib_cq_handle_t, ib_av_handle_t, ib_qp_handle_t,
\r
2253 * ib_mr_handle_t, or ib_mw_handle_t
\r
2254 * The contents of the handle array are verified by the
\r
2255 * access layer and the verbs provider driver.
\r
2258 * ci_open_ca, ci_allocate_pd, ci_create_av, ci_create_cq,
\r
2259 * ci_create_qp, ci_register_mr, ci_register_pmr,
\r
2260 * ci_register_smr, ci_create_mw, ib_ci_op_t
\r
2264 /****s* Verbs/ci_interface_t
\r
2266 * ci_interface_t -- Interface holding Channel Interface API's
\r
2268 * The following structure is supplied by a Channel Interface
\r
2269 * providing verbs functionality.
\r
2272 #define MAX_LIB_NAME 32
\r
2274 typedef struct _ci_interface
\r
2279 * Device object of the HCA. In Windows, this is a pointer to the PDO
\r
2280 * for the HCA device.
\r
2285 * Vendor ID, Device ID, Device Revision of the HCA
\r
2286 * libname refers to the user mode library to load
\r
2287 * to support direct user mode IO. If vendor does not support one
\r
2288 * then the fields must be initialized to all zero's.
\r
2292 uint16_t dev_revision;
\r
2293 char libname[MAX_LIB_NAME];
\r
2295 * Version of the header file this interface export can handle
\r
2300 * HCA Access Verbs
\r
2302 ci_open_ca open_ca;
\r
2303 ci_um_open_ca_t um_open_ca;
\r
2304 ci_query_ca query_ca;
\r
2305 ci_modify_ca modify_ca;
\r
2306 ci_close_ca close_ca;
\r
2307 ci_um_close_ca_t um_close_ca;
\r
2309 ci_vendor_call vendor_call;
\r
2312 * Protection Domain
\r
2314 ci_allocate_pd allocate_pd;
\r
2315 ci_deallocate_pd deallocate_pd;
\r
2318 * Address Vector Management Verbs
\r
2321 ci_create_av create_av;
\r
2322 ci_query_av query_av;
\r
2323 ci_modify_av modify_av;
\r
2324 ci_destroy_av destroy_av;
\r
2327 * QP Management Verbs
\r
2329 ci_create_qp create_qp;
\r
2330 ci_create_spl_qp create_spl_qp;
\r
2331 ci_modify_qp modify_qp;
\r
2332 ci_query_qp query_qp;
\r
2333 ci_destroy_qp destroy_qp;
\r
2336 * Completion Queue Management Verbs
\r
2338 ci_create_cq create_cq;
\r
2339 ci_resize_cq resize_cq;
\r
2340 ci_query_cq query_cq;
\r
2341 ci_destroy_cq destroy_cq;
\r
2344 * Memory Management Verbs
\r
2346 ci_register_mr register_mr;
\r
2347 ci_register_pmr register_pmr;
\r
2348 ci_query_mr query_mr;
\r
2349 ci_modify_mr modify_mr;
\r
2350 ci_modify_pmr modify_pmr;
\r
2351 ci_register_smr register_smr;
\r
2352 ci_deregister_mr deregister_mr;
\r
2355 * Memory Window Verbs
\r
2357 ci_create_mw create_mw;
\r
2358 ci_query_mw query_mw;
\r
2359 ci_bind_mw bind_mw;
\r
2360 ci_destroy_mw destroy_mw;
\r
2363 * Work Request Processing Verbs
\r
2365 ci_post_send post_send;
\r
2366 ci_post_recv post_recv;
\r
2369 * Completion Processing and
\r
2370 * Completion Notification Request Verbs.
\r
2372 ci_peek_cq peek_cq; /* Optional */
\r
2373 ci_poll_cq poll_cq;
\r
2374 ci_enable_cq_notify enable_cq_notify;
\r
2375 ci_enable_ncomp_cq_notify enable_ncomp_cq_notify; /* Optional */
\r
2378 * Multicast Support Verbs
\r
2380 ci_attach_mcast attach_mcast;
\r
2381 ci_detach_mcast detach_mcast;
\r
2384 * Local MAD support, for HCA's that do not support
\r
2385 * Agents in the HW.
\r
2387 ci_local_mad local_mad;
\r
2392 /****f* Verbs/ib_register_ca
\r
2394 * ib_register_ca -- Inform the IB Access Layer about a new HCA
\r
2397 AL_EXPORT ib_api_status_t
\r
2399 IN const ci_interface_t *p_ci );
\r
2402 * This routine is called by a HCA kernel mode driver to inform the
\r
2403 * IB Access Layer about a new HCA that is ready for use. It is expected
\r
2404 * that the Access Layer could immediatly turn around and call for services
\r
2405 * even before the call returns back the HCA driver code. The HCA driver
\r
2406 * must initialize all resources and be ready to service any calls before adding
\r
2407 * its services to the IB Access Layer.
\r
2411 * [in] Pointer to the ci_interface_t structure that has the function
\r
2412 * vector to support verbs functionality.
\r
2416 * The registration is successful.
\r
2418 * IB_INVALID_PARAMETER
\r
2419 * A reference to the CI interface structure was not provided.
\r
2421 * IB_INSUFFICIENT_RESOURCES
\r
2422 * Insufficient memory to satisfy resource requirements.
\r
2425 * HCA GUID is already registered with the IB Access Layer
\r
2428 * Kernel Mode only
\r
2431 * ib_deregister_ca, ci_interface_t
\r
2434 /****f* Verbs/ib_deregister_ca
\r
2436 * ib_deregister_ca -- Inform the IB Access Layer that this HCA is no longer available
\r
2439 AL_EXPORT ib_api_status_t
\r
2440 ib_deregister_ca (
\r
2441 IN const net64_t ca_guid );
\r
2444 * This routine is called by the HCA driver when this HCA would no longer be
\r
2445 * available for services. The access layer is expected to return all resources
\r
2446 * back to the HCA driver, and perform a ci_close_ca on this interface.
\r
2450 * [in] GUID of the HCA that is being removed.
\r
2454 * The deregistration is successful.
\r
2457 * No HCA with the specified GUID is registered.
\r
2460 * The HCA is still in use and cannot be released.
\r
2463 * Kernel Mode only
\r
2466 * ib_register_ca, ci_interface_t
\r
2470 #ifdef __cplusplus
\r
2471 } /* extern "C" */
\r
2472 #endif /* __cplusplus */
\r
2474 #endif // __IB_CI_H__
\r
http://git.etherboot.org / mirror / winof / .git / blob