[openib-general] [PATCH] added documentation for exported functions
Sean Hefty
mshefty at ichips.intel.com
Tue Nov 30 10:40:30 PST 2004
Patch adds documentation for exported functions that did not have it in ib_verbs.h
and device.c. Fixes slight formatting issue in ib_mad.h documentation.
Patch will be committed shortly after sending this.
- Sean
Index: include/ib_verbs.h
===================================================================
--- include/ib_verbs.h (revision 1302)
+++ include/ib_verbs.h (working copy)
@@ -849,28 +849,107 @@
u8 port_num, int port_modify_mask,
struct ib_port_modify *port_modify);
+/**
+ * ib_alloc_pd - Allocates an unused protection domain.
+ * @device: The device on which to allocate the protection domain.
+ *
+ * A protection domain object provides an association between QPs, shared
+ * receive queues, address handles, memory regions, and memory windows.
+ */
struct ib_pd *ib_alloc_pd(struct ib_device *device);
+
+/**
+ * ib_dealloc_pd - Deallocates a protection domain.
+ * @pd: The protection domain to deallocate.
+ */
int ib_dealloc_pd(struct ib_pd *pd);
+/**
+ * ib_create_ah - Creates an address handle for the given address vector.
+ * @pd: The protection domain associated with the address handle.
+ * @ah_attr: The attributes of the address vector.
+ *
+ * The address handle is used to reference a local or global destination
+ * in all UD QP post sends.
+ */
struct ib_ah *ib_create_ah(struct ib_pd *pd, struct ib_ah_attr *ah_attr);
+
+/**
+ * ib_modify_ah - Modifies the address vector associated with an address
+ * handle.
+ * @ah: The address handle to modify.
+ * @ah_attr: The new address vector attributes to associate with the
+ * address handle.
+ */
int ib_modify_ah(struct ib_ah *ah, struct ib_ah_attr *ah_attr);
+
+/**
+ * ib_query_ah - Queries the address vector associated with an address
+ * handle.
+ * @ah: The address handle to query.
+ * @ah_attr: The address vector attributes associated with the address
+ * handle.
+ */
int ib_query_ah(struct ib_ah *ah, struct ib_ah_attr *ah_attr);
+
+/**
+ * ib_destroy_ah - Destroys an address handle.
+ * @ah: The address handle to destroy.
+ */
int ib_destroy_ah(struct ib_ah *ah);
+/**
+ * ib_create_qp - Creates a QP associated with the specified protection
+ * domain.
+ * @pd: The protection domain associated with the QP.
+ * @qp_init_attr: A list of initial attributes required to create the QP.
+ */
struct ib_qp *ib_create_qp(struct ib_pd *pd,
struct ib_qp_init_attr *qp_init_attr);
+/**
+ * ib_modify_qp - Modifies the attributes for the specified QP and then
+ * transitions the QP to the given state.
+ * @qp: The QP to modify.
+ * @qp_attr: On input, specifies the QP attributes to modify. On output,
+ * the current values of selected QP attributes are returned.
+ * @qp_attr_mask: A bit-mask used to specify which attributes of the QP
+ * are being modified.
+ */
int ib_modify_qp(struct ib_qp *qp,
struct ib_qp_attr *qp_attr,
int qp_attr_mask);
+/**
+ * ib_query_qp - Returns the attribute list and current values for the
+ * specified QP.
+ * @qp: The QP to query.
+ * @qp_attr: The attributes of the specified QP.
+ * @qp_attr_mask: A bit-mask used to select specific attributes to query.
+ * @qp_init_attr: Additional attributes of the selected QP.
+ *
+ * The qp_attr_mask may be used to limit the query to gathering only the
+ * selected attributes.
+ */
int ib_query_qp(struct ib_qp *qp,
struct ib_qp_attr *qp_attr,
int qp_attr_mask,
struct ib_qp_init_attr *qp_init_attr);
+/**
+ * ib_destroy_qp - Destroys the specified QP.
+ * @qp: The QP to destroy.
+ */
int ib_destroy_qp(struct ib_qp *qp);
+/**
+ * ib_post_send - Posts a list of work requests to the send queue of
+ * the specified QP.
+ * @qp: The QP to post the work request on.
+ * @send_wr: A list of work requests to post on the send queue.
+ * @bad_send_wr: On an immediate failure, this parameter will reference
+ * the work request that failed to be posted on the QP.
+ */
static inline int ib_post_send(struct ib_qp *qp,
struct ib_send_wr *send_wr,
struct ib_send_wr **bad_send_wr)
@@ -878,6 +957,14 @@
return qp->device->post_send(qp, send_wr, bad_send_wr);
}
+/**
+ * ib_post_recv - Posts a list of work requests to the receive queue of
+ * the specified QP.
+ * @qp: The QP to post the work request on.
+ * @recv_wr: A list of work requests to post on the receive queue.
+ * @bad_recv_wr: On an immediate failure, this parameter will reference
+ * the work request that failed to be posted on the QP.
+ */
static inline int ib_post_recv(struct ib_qp *qp,
struct ib_recv_wr *recv_wr,
struct ib_recv_wr **bad_recv_wr)
@@ -885,12 +972,37 @@
return qp->device->post_recv(qp, recv_wr, bad_recv_wr);
}
+/**
+ * ib_create_cq - Creates a CQ on the specified device.
+ * @device: The device on which to create the CQ.
+ * @comp_handler: A user-specified callback that is invoked when a
+ * completion event occurs on the CQ.
+ * @event_handler: A user-specified callback that is invoked when an
+ * asynchronous event not associated with a completion occurs on the CQ.
+ * @cq_context: Context associated with the CQ returned to the user via
+ * the associated completion and event handlers.
+ * @cqe: The minimum size of the CQ.
+ *
+ * Users can examine the cq structure to determine the actual CQ size.
+ */
struct ib_cq *ib_create_cq(struct ib_device *device,
ib_comp_handler comp_handler,
void (*event_handler)(struct ib_event *, void *),
void *cq_context, int cqe);
+/**
+ * ib_resize_cq - Modifies the capacity of the CQ.
+ * @cq: The CQ to resize.
+ * @cqe: The minimum size of the CQ.
+ *
+ * Users can examine the cq structure to determine the actual CQ size.
+ */
int ib_resize_cq(struct ib_cq *cq, int cqe);
+
+/**
+ * ib_destroy_cq - Destroys the specified CQ.
+ * @cq: The CQ to destroy.
+ */
int ib_destroy_cq(struct ib_cq *cq);
/**
@@ -911,13 +1023,24 @@
return cq->device->poll_cq(cq, num_entries, wc);
}
+/**
+ * ib_peek_cq - Returns the number of unreaped completions currently
+ * on the specified CQ.
+ * @cq: The CQ to peek.
+ * @wc_cnt: A minimum number of unreaped completions to check for.
+ *
+ * If the number of unreaped completions is greater than or equal to wc_cnt,
+ * this function returns wc_cnt, otherwise, it returns the actual number of
+ * unreaped completions.
+ */
int ib_peek_cq(struct ib_cq *cq, int wc_cnt);
/**
- * ib_req_notify_cq - request completion notification
- * @cq:the CQ to generate an event for
- * @cq_notify:%IB_CQ_SOLICITED for next solicited event,
- * %IB_CQ_NEXT_COMP for any completion.
+ * ib_req_notify_cq - Request completion notification on a CQ.
+ * @cq: The CQ to generate an event for.
+ * @cq_notify: If set to %IB_CQ_SOLICITED, completion notification will
+ * occur on the next solicited event. If set to %IB_CQ_NEXT_COMP,
+ * notification will occur on the next completion.
*/
static inline int ib_req_notify_cq(struct ib_cq *cq,
enum ib_cq_notify cq_notify)
@@ -925,6 +1048,13 @@
return cq->device->req_notify_cq(cq, cq_notify);
}
+/**
+ * ib_req_ncomp_notif - Request completion notification when there are
+ * at least the specified number of unreaped completions on the CQ.
+ * @cq: The CQ to generate an event for.
+ * @wc_cnt: The number of unreaped completions that should be on the
+ * CQ before an event is generated.
+ */
static inline int ib_req_ncomp_notif(struct ib_cq *cq, int wc_cnt)
{
return cq->device->req_ncomp_notif ?
@@ -932,14 +1062,52 @@
-ENOSYS;
}
+/**
+ * ib_get_dma_mr - Returns a memory region for system memory that is
+ * usable for DMA.
+ * @pd: The protection domain associated with the memory region.
+ * @mr_access_flags: Specifies the memory access rights.
+ */
struct ib_mr *ib_get_dma_mr(struct ib_pd *pd, int mr_access_flags);
+/**
+ * ib_reg_phys_mr - Prepares a virtually addressed memory region for use
+ * by an HCA.
+ * @pd: The protection domain associated assigned to the registered region.
+ * @phys_buf_array: Specifies a list of physical buffers to use in the
+ * memory region.
+ * @num_phys_buf: Specifies the size of the phys_buf_array.
+ * @mr_access_flags: Specifies the memory access rights.
+ * @iova_start: The offset of the region's starting I/O virtual address.
+ */
struct ib_mr *ib_reg_phys_mr(struct ib_pd *pd,
struct ib_phys_buf *phys_buf_array,
int num_phys_buf,
int mr_access_flags,
u64 *iova_start);
+/**
+ * ib_rereg_phys_mr - Modifies the attributes of an existing memory region.
+ * Conceptually, this call performs the functions deregister memory region
+ * followed by register physical memory region. Where possible,
+ * resources are reused instead of deallocated and reallocated.
+ * @mr: The memory region to modify.
+ * @mr_rereg_mask: A bit-mask used to indicate which of the following
+ * properties of the memory region are being modified.
+ * @pd: If %IB_MR_REREG_PD is set in mr_rereg_mask, this field specifies
+ * the new protection domain to associated with the memory region,
+ * otherwise, this parameter is ignored.
+ * @phys_buf_array: If %IB_MR_REREG_TRANS is set in mr_rereg_mask, this
+ * field specifies a list of physical buffers to use in the new
+ * translation, otherwise, this parameter is ignored.
+ * @num_phys_buf: If %IB_MR_REREG_TRANS is set in mr_rereg_mask, this
+ * field specifies the size of the phys_buf_array, otherwise, this
+ * parameter is ignored.
+ * @mr_access_flags: If %IB_MR_REREG_ACCESS is set in mr_rereg_mask, this
+ * field specifies the new memory access rights, otherwise, this
+ * parameter is ignored.
+ * @iova_start: The offset of the region's starting I/O virtual address.
+ */
int ib_rereg_phys_mr(struct ib_mr *mr,
int mr_rereg_mask,
struct ib_pd *pd,
@@ -948,11 +1116,35 @@
int mr_access_flags,
u64 *iova_start);
+/**
+ * ib_query_mr - Retrieves information about a specific memory region.
+ * @mr: The memory region to retrieve information about.
+ * @mr_attr: The attributes of the specified memory region.
+ */
int ib_query_mr(struct ib_mr *mr, struct ib_mr_attr *mr_attr);
+
+/**
+ * ib_dereg_mr - Deregisters a memory region and removes it from the
+ * HCA translation table.
+ * @mr: The memory region to deregister.
+ */
int ib_dereg_mr(struct ib_mr *mr);
+/**
+ * ib_alloc_mw - Allocates a memory window.
+ * @pd: The protection domain associated with the memory window.
+ */
struct ib_mw *ib_alloc_mw(struct ib_pd *pd);
+/**
+ * ib_bind_mw - Posts a work request to the send queue of the specified
+ * QP, which binds the memory window to the given address range and
+ * remote access attributes.
+ * @qp: QP to post the bind work request on.
+ * @mw: The memory window to bind.
+ * @mw_bind: Specifies information about the memory window, including
+ * its address range, remote access rights, and associated memory region.
+ */
static inline int ib_bind_mw(struct ib_qp *qp,
struct ib_mw *mw,
struct ib_mw_bind *mw_bind)
@@ -963,12 +1155,32 @@
-ENOSYS;
}
+/**
+ * ib_dealloc_mw - Deallocates a memory window.
+ * @mw: The memory window to deallocate.
+ */
int ib_dealloc_mw(struct ib_mw *mw);
+/**
+ * ib_alloc_fmr - Allocates a unmapped fast memory region.
+ * @pd: The protection domain associated with the unmapped region.
+ * @mr_access_flags: Specifies the memory access rights.
+ * @fmr_attr: Attributes of the unmapped region.
+ *
+ * A fast memory region must be mapped before it can be used as part of
+ * a work request.
+ */
struct ib_fmr *ib_alloc_fmr(struct ib_pd *pd,
int mr_access_flags,
struct ib_fmr_attr *fmr_attr);
+/**
+ * ib_map_phys_fmr - Maps a list of physical pages to a fast memory region.
+ * @fmr: The fast memory region to associate with the pages.
+ * @page_list: An array of physical pages to map to the fast memory region.
+ * @list_len: The number of pages in page_list.
+ * @iova: The I/O virtual address to use with the mapped region.
+ */
static inline int ib_map_phys_fmr(struct ib_fmr *fmr,
u64 *page_list, int list_len,
u64 iova)
@@ -976,10 +1188,38 @@
return fmr->device->map_phys_fmr(fmr, page_list, list_len, iova);
}
+/**
+ * ib_unmap_fmr - Removes the mapping from a list of fast memory regions.
+ * @fmr_list: A linked list of fast memory regions to unmap.
+ */
int ib_unmap_fmr(struct list_head *fmr_list);
+
+/**
+ * ib_dealloc_fmr - Deallocates a fast memory region.
+ * @fmr: The fast memory region to deallocate.
+ */
int ib_dealloc_fmr(struct ib_fmr *fmr);
+/**
+ * ib_attach_mcast - Attaches the specified QP to a multicast group.
+ * @qp: QP to attach to the multicast group. The QP must be type
+ * IB_QPT_UD.
+ * @gid: Multicast group GID.
+ * @lid: Multicast group LID in host byte order.
+ *
+ * In order to send and receive multicast packets, subnet
+ * administration must have created the multicast group and configured
+ * the fabric appropriately. The port associated with the specified
+ * QP must also be a member of the multicast group.
+ */
int ib_attach_mcast(struct ib_qp *qp, union ib_gid *gid, u16 lid);
+
+/**
+ * ib_detach_mcast - Detaches the specified QP from a multicast group.
+ * @qp: QP to detach from the multicast group.
+ * @gid: Multicast group GID.
+ * @lid: Multicast group LID in host byte order.
+ */
int ib_detach_mcast(struct ib_qp *qp, union ib_gid *gid, u16 lid);
#endif /* IB_VERBS_H */
Index: include/ib_mad.h
===================================================================
--- include/ib_mad.h (revision 1302)
+++ include/ib_mad.h (working copy)
@@ -110,16 +110,16 @@
/**
* ib_mad_send_handler - callback handler for a sent MAD.
- * @mad_agent - MAD agent that sent the MAD.
- * @mad_send_wc - Send work completion information on the sent MAD.
+ * @mad_agent: MAD agent that sent the MAD.
+ * @mad_send_wc: Send work completion information on the sent MAD.
*/
typedef void (*ib_mad_send_handler)(struct ib_mad_agent *mad_agent,
struct ib_mad_send_wc *mad_send_wc);
/**
* ib_mad_recv_handler - callback handler for a received MAD.
- * @mad_agent - MAD agent requesting the received MAD.
- * @mad_recv_wc - Received work completion information on the received MAD.
+ * @mad_agent: MAD agent requesting the received MAD.
+ * @mad_recv_wc: Received work completion information on the received MAD.
*
* MADs received in response to a send request operation will be handed to
* the user after the send operation completes. All data buffers given
@@ -130,15 +130,15 @@
/**
* ib_mad_agent - Used to track MAD registration with the access layer.
- * @device - Reference to device registration is on.
- * @qp - Reference to QP used for sending and receiving MADs.
- * @recv_handler - Callback handler for a received MAD.
- * @send_handler - Callback handler for a sent MAD.
- * @context - User-specified context associated with this registration.
- * @hi_tid - Access layer assigned transaction ID for this client.
+ * @device: Reference to device registration is on.
+ * @qp: Reference to QP used for sending and receiving MADs.
+ * @recv_handler: Callback handler for a received MAD.
+ * @send_handler: Callback handler for a sent MAD.
+ * @context: User-specified context associated with this registration.
+ * @hi_tid: Access layer assigned transaction ID for this client.
* Unsolicited MADs sent by this client will have the upper 32-bits
* of their TID set to this value.
- * @port_num - Port number on which QP is registered
+ * @port_num: Port number on which QP is registered
*/
struct ib_mad_agent {
struct ib_device *device;
@@ -152,9 +152,9 @@
/**
* ib_mad_send_wc - MAD send completion information.
- * @wr_id - Work request identifier associated with the send MAD request.
- * @status - Completion status.
- * @vendor_err - Optional vendor error information returned with a failed
+ * @wr_id: Work request identifier associated with the send MAD request.
+ * @status: Completion status.
+ * @vendor_err: Optional vendor error information returned with a failed
* request.
*/
struct ib_mad_send_wc {
@@ -165,11 +165,11 @@
/**
* ib_mad_recv_buf - received MAD buffer information.
- * @list - Reference to next data buffer for a received RMPP MAD.
- * @grh - References a data buffer containing the global route header.
+ * @list: Reference to next data buffer for a received RMPP MAD.
+ * @grh: References a data buffer containing the global route header.
* The data refereced by this buffer is only valid if the GRH is
* valid.
- * @mad - References the start of the received MAD.
+ * @mad: References the start of the received MAD.
*/
struct ib_mad_recv_buf {
struct list_head list;
@@ -179,9 +179,9 @@
/**
* ib_mad_recv_wc - received MAD information.
- * @wc - Completion information for the received data.
- * @recv_buf - Specifies the location of the received data buffer(s).
- * @mad_len - The length of the received MAD, without duplicated headers.
+ * @wc: Completion information for the received data.
+ * @recv_buf: Specifies the location of the received data buffer(s).
+ * @mad_len: The length of the received MAD, without duplicated headers.
*
* For received response, the wr_id field of the wc is set to the wr_id
* for the corresponding send request.
@@ -194,12 +194,12 @@
/**
* ib_mad_reg_req - MAD registration request
- * @mgmt_class - Indicates which management class of MADs should be receive
+ * @mgmt_class: Indicates which management class of MADs should be receive
* by the caller. This field is only required if the user wishes to
* receive unsolicited MADs, otherwise it should be 0.
- * @mgmt_class_version - Indicates which version of MADs for the given
+ * @mgmt_class_version: Indicates which version of MADs for the given
* management class to receive.
- * @method_mask - The caller will receive unsolicited MADs for any method
+ * @method_mask: The caller will receive unsolicited MADs for any method
* where @method_mask = 1.
*/
struct ib_mad_reg_req {
@@ -210,21 +210,21 @@
/**
* ib_register_mad_agent - Register to send/receive MADs.
- * @device - The device to register with.
- * @port_num - The port on the specified device to use.
- * @qp_type - Specifies which QP to access. Must be either
+ * @device: The device to register with.
+ * @port_num: The port on the specified device to use.
+ * @qp_type: Specifies which QP to access. Must be either
* IB_QPT_SMI or IB_QPT_GSI.
- * @mad_reg_req - Specifies which unsolicited MADs should be received
+ * @mad_reg_req: Specifies which unsolicited MADs should be received
* by the caller. This parameter may be NULL if the caller only
* wishes to receive solicited responses.
- * @rmpp_version - If set, indicates that the client will send
+ * @rmpp_version: If set, indicates that the client will send
* and receive MADs that contain the RMPP header for the given version.
* If set to 0, indicates that RMPP is not used by this client.
- * @send_handler - The completion callback routine invoked after a send
+ * @send_handler: The completion callback routine invoked after a send
* request has completed.
- * @recv_handler - The completion callback routine invoked for a received
+ * @recv_handler: The completion callback routine invoked for a received
* MAD.
- * @context - User specified context associated with the registration.
+ * @context: User specified context associated with the registration.
*/
struct ib_mad_agent *ib_register_mad_agent(struct ib_device *device,
u8 port_num,
@@ -237,7 +237,7 @@
/**
* ib_unregister_mad_agent - Unregisters a client from using MAD services.
- * @mad_agent - Corresponding MAD registration request to deregister.
+ * @mad_agent: Corresponding MAD registration request to deregister.
*
* After invoking this routine, MAD services are no longer usable by the
* client on the associated QP.
@@ -247,9 +247,9 @@
/**
* ib_post_send_mad - Posts MAD(s) to the send queue of the QP associated
* with the registered client.
- * @mad_agent - Specifies the associated registration to post the send to.
- * @send_wr - Specifies the information needed to send the MAD(s).
- * @bad_send_wr - Specifies the MAD on which an error was encountered.
+ * @mad_agent: Specifies the associated registration to post the send to.
+ * @send_wr: Specifies the information needed to send the MAD(s).
+ * @bad_send_wr: Specifies the MAD on which an error was encountered.
*
* Sent MADs are not guaranteed to complete in the order that they were posted.
*/
@@ -259,8 +259,8 @@
/**
* ib_coalesce_recv_mad - Coalesces received MAD data into a single buffer.
- * @mad_recv_wc - Work completion information for a received MAD.
- * @buf - User-provided data buffer to receive the coalesced buffers. The
+ * @mad_recv_wc: Work completion information for a received MAD.
+ * @buf: User-provided data buffer to receive the coalesced buffers. The
* referenced buffer should be at least the size of the mad_len specified
* by @mad_recv_wc.
*
@@ -273,7 +273,7 @@
/**
* ib_free_recv_mad - Returns data buffers used to receive a MAD to the
* access layer.
- * @mad_recv_wc - Work completion information for a received MAD.
+ * @mad_recv_wc: Work completion information for a received MAD.
*
* Clients receiving MADs through their ib_mad_recv_handler must call this
* routine to return the work completion buffers to the access layer.
@@ -282,8 +282,8 @@
/**
* ib_cancel_mad - Cancels an outstanding send MAD operation.
- * @mad_agent - Specifies the registration associated with sent MAD.
- * @wr_id - Indicates the work request identifier of the MAD to cancel.
+ * @mad_agent: Specifies the registration associated with sent MAD.
+ * @wr_id: Indicates the work request identifier of the MAD to cancel.
*
* MADs will be returned to the user through the corresponding
* ib_mad_send_handler.
@@ -293,15 +293,15 @@
/**
* ib_redirect_mad_qp - Registers a QP for MAD services.
- * @qp - Reference to a QP that requires MAD services.
- * @rmpp_version - If set, indicates that the client will send
+ * @qp: Reference to a QP that requires MAD services.
+ * @rmpp_version: If set, indicates that the client will send
* and receive MADs that contain the RMPP header for the given version.
* If set to 0, indicates that RMPP is not used by this client.
- * @send_handler - The completion callback routine invoked after a send
+ * @send_handler: The completion callback routine invoked after a send
* request has completed.
- * @recv_handler - The completion callback routine invoked for a received
+ * @recv_handler: The completion callback routine invoked for a received
* MAD.
- * @context - User specified context associated with the registration.
+ * @context: User specified context associated with the registration.
*
* Use of this call allows clients to use MAD services, such as RMPP,
* on user-owned QPs. After calling this routine, users may send
@@ -316,8 +316,8 @@
/**
* ib_process_mad_wc - Processes a work completion associated with a
* MAD sent or received on a redirected QP.
- * @mad_agent - Specifies the registered MAD service using the redirected QP.
- * @wc - References a work completion associated with a sent or received
+ * @mad_agent: Specifies the registered MAD service using the redirected QP.
+ * @wc: References a work completion associated with a sent or received
* MAD segment.
*
* This routine is used to complete or continue processing on a MAD request.
Index: core/device.c
===================================================================
--- core/device.c (revision 1302)
+++ core/device.c (working copy)
@@ -556,6 +556,17 @@
}
EXPORT_SYMBOL(ib_modify_device);
+/**
+ * ib_modify_port - Modifies the attributes for the specified port.
+ * @device: The device to modify.
+ * @port_num: The number of the port to modify.
+ * @port_modify_mask: Mask used to specify which attributes of the port
+ * to change.
+ * @port_modify: New attribute values for the port.
+ *
+ * ib_modify_port() changes a port's attributes as specified by the
+ * @port_modify_mask and @port_modify structure.
+ */
int ib_modify_port(struct ib_device *device,
u8 port_num, int port_modify_mask,
struct ib_port_modify *port_modify)
More information about the general
mailing list