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) _______________________________________________ openib-general mailing list [EMAIL PROTECTED] http://openib.org/mailman/listinfo/openib-general To unsubscribe, please visit http://openib.org/mailman/listinfo/openib-general