From patchwork Thu Jul 11 15:04:22 2013 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Yishai Hadas X-Patchwork-Id: 2826506 Return-Path: X-Original-To: patchwork-linux-rdma@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork1.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.19.201]) by patchwork1.web.kernel.org (Postfix) with ESMTP id 6E9999F7D6 for ; Thu, 11 Jul 2013 16:04:59 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id B1EC620291 for ; Thu, 11 Jul 2013 16:04:57 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 92F3B20286 for ; Thu, 11 Jul 2013 16:04:54 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932427Ab3GKQEt (ORCPT ); Thu, 11 Jul 2013 12:04:49 -0400 Received: from mailp.voltaire.com ([193.47.165.129]:56253 "EHLO mellanox.co.il" rhost-flags-OK-FAIL-OK-FAIL) by vger.kernel.org with ESMTP id S932102Ab3GKQEs (ORCPT ); Thu, 11 Jul 2013 12:04:48 -0400 Received: from Internal Mail-Server by MTLPINE1 (envelope-from yishaih@mellanox.com) with SMTP; 11 Jul 2013 19:04:43 +0300 Received: from vnc17.lab.mtl.com (vnc17.mtl.labs.mlnx [10.7.2.17]) by labmailer.mlnx (8.13.8/8.13.8) with ESMTP id r6BG4hsg019164; Thu, 11 Jul 2013 19:04:43 +0300 Received: from vnc17.lab.mtl.com (localhost.localdomain [127.0.0.1]) by vnc17.lab.mtl.com (8.13.8/8.13.8) with ESMTP id r6BF5qaI001558; Thu, 11 Jul 2013 18:05:52 +0300 Received: (from yishaih@localhost) by vnc17.lab.mtl.com (8.13.8/8.13.8/Submit) id r6BF5q3K001557; Thu, 11 Jul 2013 18:05:52 +0300 From: Yishai Hadas To: linux-rdma@vger.kernel.org, roland@purestorage.com Cc: tzahio@mellanox.com, yishaih@mellanox.com, Sean Hefty Subject: [PATCH V7 libibverbs 6/7] XRC man pages Date: Thu, 11 Jul 2013 18:04:22 +0300 Message-Id: <1373555063-31790-7-git-send-email-yishaih@mellanox.com> X-Mailer: git-send-email 1.7.8.2 In-Reply-To: <1373555063-31790-1-git-send-email-yishaih@mellanox.com> References: <1373555063-31790-1-git-send-email-yishaih@mellanox.com> Sender: linux-rdma-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-rdma@vger.kernel.org X-Spam-Status: No, score=-7.2 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_HI, RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=ham version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP From: Sean Hefty Signed-off-by: Sean Hefty Signed-off-by: Yishai Hadas --- Changes from V6: Fixed ibv_open_qp man page to match latest API. Added missing man pages. Put man pages as part of installation. Makefile.am | 8 +++- man/ibv_create_qp_ex.3 | 83 +++++++++++++++++++++++++++++++++++++++++++++++ man/ibv_create_srq_ex.3 | 71 ++++++++++++++++++++++++++++++++++++++++ man/ibv_get_srq_num.3 | 32 ++++++++++++++++++ man/ibv_open_qp.3 | 51 +++++++++++++++++++++++++++++ man/ibv_open_xrcd.3 | 76 +++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 319 insertions(+), 2 deletions(-) create mode 100644 man/ibv_create_qp_ex.3 create mode 100644 man/ibv_create_srq_ex.3 create mode 100644 man/ibv_get_srq_num.3 create mode 100644 man/ibv_open_qp.3 create mode 100644 man/ibv_open_xrcd.3 diff --git a/Makefile.am b/Makefile.am index 40e83be..aa6097a 100644 --- a/Makefile.am +++ b/Makefile.am @@ -54,7 +54,9 @@ man_MANS = man/ibv_asyncwatch.1 man/ibv_devices.1 man/ibv_devinfo.1 \ man/ibv_post_srq_recv.3 man/ibv_query_device.3 man/ibv_query_gid.3 \ man/ibv_query_pkey.3 man/ibv_query_port.3 man/ibv_query_qp.3 \ man/ibv_query_srq.3 man/ibv_rate_to_mult.3 man/ibv_reg_mr.3 \ - man/ibv_req_notify_cq.3 man/ibv_resize_cq.3 man/ibv_rate_to_mbps.3 + man/ibv_req_notify_cq.3 man/ibv_resize_cq.3 man/ibv_rate_to_mbps.3 \ + man/ibv_create_qp_ex.3 man/ibv_create_srq_ex.3 man/ibv_open_xrcd.3 \ + man/ibv_get_srq_num.3 man/ibv_open_qp.3 DEBIAN = debian/changelog debian/compat debian/control debian/copyright \ debian/ibverbs-utils.install debian/libibverbs1.install \ @@ -89,6 +91,7 @@ install-data-hook: $(RM) ibv_node_type_str.3 && \ $(RM) ibv_port_state_str.3 && \ $(RM) mbps_to_ibv_rate.3 && \ + $(RM) ibv_close_xrcd.3 && \ $(LN_S) ibv_get_async_event.3 ibv_ack_async_event.3 && \ $(LN_S) ibv_get_cq_event.3 ibv_ack_cq_events.3 && \ $(LN_S) ibv_open_device.3 ibv_close_device.3 && \ @@ -105,4 +108,5 @@ install-data-hook: $(LN_S) ibv_rate_to_mult.3 mult_to_ibv_rate.3 && \ $(LN_S) ibv_event_type_str.3 ibv_node_type_str.3 && \ $(LN_S) ibv_event_type_str.3 ibv_port_state_str.3 && \ - $(LN_S) ibv_rate_to_mbps.3 mbps_to_ibv_rate.3 + $(LN_S) ibv_rate_to_mbps.3 mbps_to_ibv_rate.3 && \ + $(LN_S) ibv_open_xrcd.3 ibv_close_xrcd.3 diff --git a/man/ibv_create_qp_ex.3 b/man/ibv_create_qp_ex.3 new file mode 100644 index 0000000..f772a57 --- /dev/null +++ b/man/ibv_create_qp_ex.3 @@ -0,0 +1,83 @@ +.\" -*- nroff -*- +.\" +.TH IBV_CREATE_QP_EX 3 2013-06-26 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_create_qp_ex, ibv_destroy_qp \- create or destroy a queue pair (QP) +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "struct ibv_qp *ibv_create_qp_ex(struct ibv_context " "*context" , +.BI " struct ibv_qp_init_attr_ex " "*qp_init_attr" ); +.sp +.BI "int ibv_destroy_qp(struct ibv_qp " "*qp" ); +.fi +.SH "DESCRIPTION" +.B ibv_create_qp_ex() +creates a queue pair (QP) associated with the protection domain +.I pd\fR. +The argument +.I qp_init_attr_ex +is an ibv_qp_init_attr_ex struct, as defined in . +.PP +.nf +struct ibv_qp_init_attr_ex { +.in +8 +void *qp_context; /* Associated context of the QP */ +struct ibv_cq *send_cq; /* CQ to be associated with the Send Queue (SQ) */ +struct ibv_cq *recv_cq; /* CQ to be associated with the Receive Queue (RQ) */ +struct ibv_srq *srq; /* SRQ handle if QP is to be associated with an SRQ, otherwise NULL */ +struct ibv_qp_cap cap; /* QP capabilities */ +enum ibv_qp_type qp_type; /* QP Transport Service Type: IBV_QPT_RC, IBV_QPT_UC, IBV_QPT_UD or IBV_QPT_RAW_PACKET */ +int sq_sig_all; /* If set, each Work Request (WR) submitted to the SQ generates a completion entry */ +uint32_t comp_mask; /* Identifies valid fields */ +struct ibv_pd *pd; /* PD to be associated with the QP */ +struct ibv_xrcd *xrcd; /* XRC domain to be associated with the target QP */ +enum ibv_qp_create_flags create_flags; /* Creation flags for this QP */ +.in -8 +}; +.sp +.nf +struct ibv_qp_cap { +.in +8 +uint32_t max_send_wr; /* Requested max number of outstanding WRs in the SQ */ +uint32_t max_recv_wr; /* Requested max number of outstanding WRs in the RQ */ +uint32_t max_send_sge; /* Requested max number of scatter/gather (s/g) elements in a WR in the SQ */ +uint32_t max_recv_sge; /* Requested max number of s/g elements in a WR in the SQ */ +uint32_t max_inline_data;/* Requested max number of data (bytes) that can be posted inline to the SQ, otherwise 0 */ +.in -8 +}; +.fi +.PP +The function +.B ibv_create_qp_ex() +will update the +.I qp_init_attr_ex\fB\fR->cap +struct with the actual \s-1QP\s0 values of the QP that was created; +the values will be greater than or equal to the values requested. +.PP +.B ibv_destroy_qp() +destroys the QP +.I qp\fR. +.SH "RETURN VALUE" +.B ibv_create_qp_ex() +returns a pointer to the created QP, or NULL if the request fails. +Check the QP number (\fBqp_num\fR) in the returned QP. +.PP +.B ibv_destroy_qp() +returns 0 on success, or the value of errno on failure (which indicates the failure reason). +.SH "NOTES" +.PP +The attributes max_recv_wr and max_recv_sge are ignored by +.B ibv_create_qp_ex() +if the QP is to be associated with an SRQ. +.PP +.B ibv_destroy_qp() +fails if the QP is attached to a multicast group. +.SH "SEE ALSO" +.BR ibv_alloc_pd (3), +.BR ibv_modify_qp (3), +.BR ibv_query_qp (3) +.SH "AUTHORS" +.TP +Yishai Hadas diff --git a/man/ibv_create_srq_ex.3 b/man/ibv_create_srq_ex.3 new file mode 100644 index 0000000..9151d6e --- /dev/null +++ b/man/ibv_create_srq_ex.3 @@ -0,0 +1,71 @@ +.\" -*- nroff -*- +.\" +.TH IBV_CREATE_SRQ_EX 3 2013-06-26 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_create_srq_ex, ibv_destroy_srq \- create or destroy a shared receive queue (SRQ) +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "struct ibv_srq *ibv_create_srq_ex(struct ibv_context " "*context" ", struct " +.BI " ibv_srq_init_attr_ex " "*srq_init_attr_ex" ); +.sp +.BI "int ibv_destroy_srq(struct ibv_srq " "*srq" ); +.fi +.SH "DESCRIPTION" +.B ibv_create_srq_ex() +creates a shared receive queue (SRQ) supporting both basic and xrc modes. +The argument +.I srq_init_attr_ex +is an ibv_srq_init_attr_ex struct, as defined in . +.PP +.nf +struct ibv_srq_init_attr_ex { +.in +8 +void *srq_context; /* Associated context of the SRQ */ +struct ibv_srq_attr attr; /* SRQ attributes */ +uint32_t comp_mask; /* Identifies valid fields */ +enum ibv_srq_type srq_type; /* Basic / XRC */ +struct ibv_pd *pd; /* PD associated with the SRQ */ +struct ibv_xrcd *xrcd; /* XRC domain to associate with the SRQ */ +struct ibv_cq *cq; /* CQ to associate with the SRQ for XRC mode */ +.in -8 +}; +.sp +.nf +struct ibv_srq_attr { +.in +8 +uint32_t max_wr; /* Requested max number of outstanding work requests (WRs) in the SRQ */ +uint32_t max_sge; /* Requested max number of scatter elements per WR */ +uint32_t srq_limit; /* The limit value of the SRQ */ +.in -8 +}; +.fi +.PP +The function +.B ibv_create_srq_ex() +will update the +.I srq_init_attr_ex +struct with the original values of the SRQ that was created; the +values of max_wr and max_sge will be greater than or equal to the +values requested. +.PP +.B ibv_destroy_srq() +destroys the SRQ +.I srq\fR. +.SH "RETURN VALUE" +.B ibv_create_srq_ex() +returns a pointer to the created SRQ, or NULL if the request fails. +.PP +.B ibv_destroy_srq() +returns 0 on success, or the value of errno on failure (which indicates the failure reason). +.SH "NOTES" +.B ibv_destroy_srq() +fails if any queue pair is still associated with this SRQ. +.SH "SEE ALSO" +.BR ibv_alloc_pd (3), +.BR ibv_modify_srq (3), +.BR ibv_query_srq (3) +.SH "AUTHORS" +.TP +Yishai Hadas diff --git a/man/ibv_get_srq_num.3 b/man/ibv_get_srq_num.3 new file mode 100644 index 0000000..00e4fb4 --- /dev/null +++ b/man/ibv_get_srq_num.3 @@ -0,0 +1,32 @@ +.\" -*- nroff -*- +.\" +.TH IBV_GET_SRQ_NUM 3 2013-06-26 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_get_srq_num \- return srq number associated with the given shared receive queue (SRQ) +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "int ibv_get_srq_num(struct ibv_srq " "*srq" , +.BI " uint32_t " "*srq_num" ); +.fi +.SH "DESCRIPTION" +.B ibv_get_srq_num() +return srq number associated with the given shared receive queue +The argument +.I srq +is an ibv_srq struct, as defined in . +.I srq_num +is an output parameter that holds the returned srq number. +.PP +.nf +.SH "RETURN VALUE" +.B ibv_get_srq_num() +returns 0 on success, or the value of errno on failure (which indicates the failure reason). +.SH "SEE ALSO" +.BR ibv_alloc_pd (3), +.BR ibv_modify_srq (3), +.BR ibv_create_srq_ex (3) +.SH "AUTHORS" +.TP +Yishai Hadas diff --git a/man/ibv_open_qp.3 b/man/ibv_open_qp.3 new file mode 100644 index 0000000..71b5d46 --- /dev/null +++ b/man/ibv_open_qp.3 @@ -0,0 +1,51 @@ +.\" -*- nroff -*- +.\" +.TH IBV_OPEN_QP 3 2011-08-12 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_open_qp \- open a shareable queue pair (QP) +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "struct ibv_qp *ibv_open_qp(struct ibv_context " "*context" , +.BI " struct ibv_qp_open_attr " "*qp_open_attr" ); +.fi +.SH "DESCRIPTION" +.B ibv_open_qp() +opens an existing queue pair (QP) associated with the extended protection domain +.I xrcd\fR. +The argument +.I qp_open_attr +is an ibv_qp_open_attr struct, as defined in . +.PP +.nf +struct ibv_qp_open_attr { +.in +8 +uint32_t comp_mask; /* Identifies valid fields */ +uint32_t qp_num; /* QP number */ +struct *ibv_xrcd; /* XRC domain */ +void *qp_context; /* User defined opaque value */ +enum ibv_qp_type qp_type; /* QP transport service type */ +.fi +.PP +.B ibv_destroy_qp() +closes the opened QP and destroys the underlying QP if it has no +other references. +.I qp\fR. +.SH "RETURN VALUE" +.B ibv_open_qp() +returns a pointer to the opened QP, or NULL if the request fails. +Check the QP number (\fBqp_num\fR) in the returned QP. +.SH "NOTES" +.B ibv_open_qp() +will fail if a it is asked to open a QP that does not exist within +the xrcd with the specified qp_num and qp_type. +.SH "SEE ALSO" +.BR ibv_alloc_pd (3), +.BR ibv_create_qp (3), +.BR ibv_create_qp_ex (3), +.BR ibv_modify_qp (3), +.BR ibv_query_qp (3) +.SH "AUTHORS" +.TP +Sean Hefty diff --git a/man/ibv_open_xrcd.3 b/man/ibv_open_xrcd.3 new file mode 100644 index 0000000..b9724bf --- /dev/null +++ b/man/ibv_open_xrcd.3 @@ -0,0 +1,76 @@ +.\" -*- nroff -*- +.\" +.TH IBV_OPEN_XRCD 3 2011-06-17 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_open_xrcd, ibv_close_xrcd \- open or close an XRC protection domain (XRCDs) +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "struct ibv_xrcd *ibv_open_xrcd(struct ibv_context " "*context" "," +.BI " struct ibv_xrcd_init_attr " "*xrcd_init_attr" ); +.sp +.BI "int ibv_close_xrcd(struct ibv_xrcd " "*xrcd" ); +.fi +.SH "DESCRIPTION" +.B ibv_open_xrcd() +open an XRC domain for the RDMA device context +.I context +.I xrcd_init_attr +is an ibv_xrcd_init_attr struct, as defined in . +.PP +.nf +struct ibv_xrcd_init_attr { +.in +8 +uint32_t comp_mask; /* Identifies valid fields */ +int fd; +int oflag; +.fi +.PP +.I fd +is the file descriptor to associate with the XRCD. +.I oflag +describes the desired creation attributes. It is a bitwise OR of zero or more +of the following flags: +.PP +.TP +.B O_CREAT +Indicates that an XRCD should be created and associated with the inode referenced +by the given fd. If the XRCD exists, this flag has no effect except as noted under +.BR O_EXCL +below.\fR +.TP +.B O_EXCL +If +.BR O_EXCL +and +.BR O_CREAT +are set, open will fail if an XRCD associated with the inode exists. +.PP +If +.I fd +equals -1, no inode is associated with the XRCD. To indicate that XRCD should be created, use +.I oflag += +.B O_CREAT\fR. +.PP +.B ibv_close_xrcd() +closes the XRCD +.I xrcd\fR. +If this is the last reference, the XRCD will be destroyed. +.SH "RETURN VALUE" +.B ibv_open_xrcd() +returns a pointer to the opened XRCD, or NULL if the request fails. +.PP +.B ibv_close_xrcd() +returns 0 on success, or the value of errno on failure (which indicates the +failure reason). +.SH "NOTES" +.B ibv_close_xrcd() +may fail if any other resource is still associated with the XRCD being closed. +.SH "SEE ALSO" +.BR ibv_create_srq_ex (3), +.BR ibv_create_qp_ex (3), +.SH "AUTHORS" +.TP +Sean Hefty