From: Roland Dreier Date: Wed, 21 Feb 2007 00:05:27 +0000 (-0800) Subject: Add remaining libibverbs manpages X-Git-Url: https://openfabrics.org/gitweb/?a=commitdiff_plain;h=9845a77c8812cd416cad18c73c6051fc337158f3;p=~shefty%2Flibibverbs.git Add remaining libibverbs manpages Add the rest of the manpages for libibverbs functions in section 3. These manpages were written by Dotan Barak . Signed-off-by: Roland Dreier --- diff --git a/Makefile.am b/Makefile.am index c57e5fd..5d2383e 100644 --- a/Makefile.am +++ b/Makefile.am @@ -38,11 +38,21 @@ libibverbsinclude_HEADERS = include/infiniband/arch.h include/infiniband/driver. include/infiniband/kern-abi.h include/infiniband/opcode.h include/infiniband/verbs.h \ include/infiniband/sa-kern-abi.h include/infiniband/sa.h include/infiniband/marshall.h -man_MANS = man/ibv_asyncwatch.1 man/ibv_devices.1 man/ibv_devinfo.1 \ +man_MANS = man/ibv_asyncwatch.1 man/ibv_devices.1 man/ibv_devinfo.1 \ man/ibv_rc_pingpong.1 man/ibv_uc_pingpong.1 man/ibv_ud_pingpong.1 \ man/ibv_srq_pingpong.1 \ - man/ibv_get_device_list.3 man/ibv_get_device_name.3 \ - man/ibv_get_device_guid.3 man/ibv_open_device.3 man/ibv_fork_init.3 + man/ibv_alloc_pd.3 man/ibv_attach_mcast.3 man/ibv_create_ah.3 \ + man/ibv_create_ah_from_wc.3 man/ibv_create_comp_channel.3 \ + man/ibv_create_cq.3 man/ibv_create_qp.3 man/ibv_create_srq.3 \ + man/ibv_fork_init.3 man/ibv_get_async_event.3 \ + man/ibv_get_cq_event.3 man/ibv_get_device_guid.3 \ + man/ibv_get_device_list.3 man/ibv_get_device_name.3 \ + man/ibv_modify_qp.3 man/ibv_modify_srq.3 man/ibv_open_device.3 \ + man/ibv_poll_cq.3 man/ibv_post_recv.3 man/ibv_post_send.3 \ + 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 DEBIAN = debian/changelog debian/compat debian/control debian/copyright \ debian/ibverbs-utils.install debian/libibverbs1.install \ @@ -60,5 +70,18 @@ dist-hook: libibverbs.spec install-data-hook: cd $(DESTDIR)$(mandir)/man3 && \ + $(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 && \ + $(LN_S) ibv_alloc_pd.3 ibv_dealloc_pd.3 && \ + $(LN_S) ibv_reg_mr.3 ibv_dereg_mr.3 && \ + $(LN_S) ibv_create_ah.3 ibv_destroy_ah.3 && \ + $(LN_S) ibv_create_comp_channel.3 ibv_destroy_comp_channel.3 && \ + $(LN_S) ibv_create_cq.3 ibv_destroy_cq.3 && \ + $(LN_S) ibv_create_qp.3 ibv_destroy_qp.3 && \ + $(LN_S) ibv_create_srq.3 ibv_destroy_srq.3 && \ + $(LN_S) ibv_attach_mcast.3 ibv_detach_mcast.3 && \ $(LN_S) ibv_get_device_list.3 ibv_free_device_list.3 && \ - $(LN_S) ibv_open_device.3 ibv_close_device.3 + $(LN_S) ibv_create_ah_from_wc.3 ibv_init_ah_from_wc.3 && \ + $(LN_S) ibv_rate_to_mult.3 mult_to_ibv_rate.3 + diff --git a/debian/libibverbs-dev.links b/debian/libibverbs-dev.links index 44f6c50..5478330 100644 --- a/debian/libibverbs-dev.links +++ b/debian/libibverbs-dev.links @@ -1,2 +1,14 @@ -usr/share/man/man3/ibv_get_device_list.3 usr/share/man/man3/ibv_free_device_list.3 +usr/share/man/man3/ibv_get_async_event.3 usr/share/man/man3/ibv_ack_async_event.3 +usr/share/man/man3/ibv_get_cq_event.3 usr/share/man/man3/ibv_ack_cq_events.3 usr/share/man/man3/ibv_open_device.3 usr/share/man/man3/ibv_close_device.3 +usr/share/man/man3/ibv_alloc_pd.3 usr/share/man/man3/ibv_dealloc_pd.3 +usr/share/man/man3/ibv_reg_mr.3 usr/share/man/man3/ibv_dereg_mr.3 +usr/share/man/man3/ibv_create_ah.3 usr/share/man/man3/ibv_destroy_ah.3 +usr/share/man/man3/ibv_create_comp_channel.3 usr/share/man/man3/ibv_destroy_comp_channel.3 +usr/share/man/man3/ibv_create_cq.3 usr/share/man/man3/ibv_destroy_cq.3 +usr/share/man/man3/ibv_create_qp.3 usr/share/man/man3/ibv_destroy_qp.3 +usr/share/man/man3/ibv_create_srq.3 usr/share/man/man3/ibv_destroy_srq.3 +usr/share/man/man3/ibv_attach_mcast.3 usr/share/man/man3/ibv_detach_mcast.3 +usr/share/man/man3/ibv_get_device_list.3 usr/share/man/man3/ibv_free_device_list.3 +usr/share/man/man3/ibv_create_ah_from_wc.3 usr/share/man/man3/ibv_init_ah_from_wc.3 +usr/share/man/man3/ibv_rate_to_mult.3 usr/share/man/man3/mult_to_ibv_rate.3 diff --git a/man/ibv_alloc_pd.3 b/man/ibv_alloc_pd.3 new file mode 100644 index 0000000..017ab32 --- /dev/null +++ b/man/ibv_alloc_pd.3 @@ -0,0 +1,40 @@ +.\" -*- nroff -*- +.\" +.TH IBV_ALLOC_PD 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_alloc_pd, ibv_dealloc_pd \- allocate or deallocate a protection domain (PDs) +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "struct ibv_pd *ibv_alloc_pd(struct ibv_context " "*context" ); +.nl +.BI "int ibv_dealloc_pd(struct ibv_pd " "*pd" ); +.fi +.SH "DESCRIPTION" +.B ibv_alloc_pd() +allocates a PD for the InfiniBand device context +.I context\fR. +.PP +.B ibv_dealloc_pd() +deallocates the PD +.I pd\fR. +.SH "RETURN VALUE" +.B ibv_alloc_pd() +returns a pointer to the allocated PD, or NULL if the request fails. +.PP +.B ibv_dealloc_pd() +returns 0 on success, or the value of errno on failure (which indicates the failure reason). +.SH "NOTES" +.B ibv_dealloc_pd() +may fail if any other InfiniBand resource is still associated with the +PD being freed. +.SH "SEE ALSO" +.BR ibv_reg_mr (3), +.BR ibv_create_srq (3), +.BR ibv_create_qp (3), +.BR ibv_create_ah (3), +.BR ibv_create_ah_from_wc (3) +.SH "AUTHORS" +.TP +Dotan Barak diff --git a/man/ibv_attach_mcast.3 b/man/ibv_attach_mcast.3 new file mode 100644 index 0000000..cb6ddf2 --- /dev/null +++ b/man/ibv_attach_mcast.3 @@ -0,0 +1,53 @@ +.\" -*- nroff -*- +.\" +.TH IBV_ATTACH_MCAST 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_attach_mcast, ibv_detach_mcast \- attach and detach a queue pair +(QPs) to/from a multicast group +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "int ibv_attach_mcast(struct ibv_qp " "*qp" ", union ibv_gid " "*gid" ", +.BI " uint16_t " "lid" "); +.nl +.BI "int ibv_detach_mcast(struct ibv_qp " "*qp" ", union ibv_gid " "*gid" ", +.BI " uint16_t " "lid" "); +.fi +.SH "DESCRIPTION" +.B ibv_attach_mcast() +attaches the QP +.I qp +to the multicast group having MGID +.I gid +and MLID +.I lid\fR. +.PP +.B ibv_detach_mcast() +detaches the QP +.I qp +to the multicast group having MGID +.I gid +and MLID +.I lid\fR. +.SH "RETURN VALUE" +.B ibv_attach_mcast() +and +.B ibv_detach_mcast() +returns 0 on success, or the value of errno on failure (which indicates the failure reason). +.SH "NOTES" +Only QPs of Transport Service Type +.BR IBV_QPT_UD +may be attached to multicast groups. +.PP +If a QP is attached to the same multicast group multiple times, the QP will still receive a single copy of a multicast message. +.PP +In order to receive multicast messages, a join request for the +multicast group must be sent to the subnet administrator (SA), so that +the fabric's multicast routing is configured to deliver messages to +the local port. +.SH "SEE ALSO" +.BR ibv_create_qp (3) +.SH "AUTHORS" +.TP +Dotan Barak diff --git a/man/ibv_create_ah.3 b/man/ibv_create_ah.3 new file mode 100644 index 0000000..85e4a71 --- /dev/null +++ b/man/ibv_create_ah.3 @@ -0,0 +1,64 @@ +.\" -*- nroff -*- +.\" +.TH IBV_CREATE_AH 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_create_ah, ibv_destroy_ah \- create or destroy an address handle (AH) +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "struct ibv_ah *ibv_create_ah(struct ibv_pd " "*pd" ", +.BI " struct ibv_ah_attr " "*attr" "); +.nl +.BI "int ibv_destroy_ah(struct ibv_ah " "*ah" "); +.fi +.SH "DESCRIPTION" +.B ibv_create_ah() +creates an address handle (AH) associated with the protection domain +.I pd\fR. +The argument +.I attr +is an ibv_ah_attr struct, as defined in . +.PP +.nf +struct ibv_ah_attr { +.in +8 +struct ibv_global_route grh; /* Global Routing Header (GRH) attributes */ +uint16_t dlid; /* Destination LID */ +uint8_t sl; /* Service Level */ +uint8_t src_path_bits; /* Source path bits */ +uint8_t static_rate; /* Maximum static rate */ +uint8_t is_global; /* GRH attributes are valid */ +uint8_t port_num; /* Physical port number */ +.in -8 +}; +.sp +.nf +struct ibv_global_route { +.in +8 +union ibv_gid dgid; /* Destination GID or MGID */ +uint32_t flow_label; /* Flow label */ +uint8_t sgid_index; /* Source GID index */ +uint8_t hop_limit; /* Hop limit */ +uint8_t traffic_class; /* Traffic class */ +.in -8 +}; +.fi +.sp +.PP +.B ibv_destroy_ah() +destroys the AH +.I ah\fR. +.SH "RETURN VALUE" +.B ibv_create_ah() +returns a pointer to the created AH, or NULL if the request fails. +.PP +.B ibv_destroy_ah() +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_init_ah_from_wc (3), +.BR ibv_create_ah_from_wc (3) +.SH "AUTHORS" +.TP +Dotan Barak diff --git a/man/ibv_create_ah_from_wc.3 b/man/ibv_create_ah_from_wc.3 new file mode 100644 index 0000000..487f053 --- /dev/null +++ b/man/ibv_create_ah_from_wc.3 @@ -0,0 +1,63 @@ +.\" -*- nroff -*- +.\" +.TH IBV_CREATE_AH_FROM_WC 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_init_ah_from_wc, ibv_create_ah_from_wc \- initialize or create an +address handle (AH) from a work completion +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "int ibv_init_ah_from_wc(struct ibv_context " "*context" ", uint8_t " "port_num" , +.BI " struct ibv_wc " "*wc" ", struct ibv_grh " "*grh" , +.BI " struct ibv_ah_attr " "*ah_attr" ); +.nl +.BI "struct ibv_ah *ibv_create_ah_from_wc(struct ibv_pd " "*pd" , +.BI " struct ibv_wc " "*wc" , +.BI " struct ibv_grh " "*grh" , +.BI " uint8_t " "port_num" ); +.fi +.SH "DESCRIPTION" +.B ibv_init_ah_from_wc() +initializes the address handle (AH) attribute structure +.I ah_attr +for the InfiniBand device context +.I context +using the port number +.I port_num\fR, +using attributes from the work completion +.I wc +and the Global Routing Header (GRH) structure +.I grh\fR. +.PP +.B ibv_create_ah_from_wc() +creates an AH associated with the protection domain +.I pd +using the port number +.I port_num\fR, +using attributes from the work completion +.I wc +and the Global Routing Header (GRH) structure +.I grh\fR. +.SH "RETURN VALUE" +.B ibv_init_ah_from_wc() +returns 0 on success, and \-1 on error. +.PP +.B ibv_create_ah_from_wc() +returns a pointer to the created AH, or NULL if the request fails. +.SH "NOTES" +The filled structure +.I ah_attr +returned from +.B ibv_init_ah_from_wc() +can be used to create a new AH using +.B ibv_create_ah()\fR. +.SH "SEE ALSO" +.BR ibv_open_device (3), +.BR ibv_alloc_pd (3), +.BR ibv_create_ah (3), +.BR ibv_destroy_ah (3), +.BR ibv_poll_cq (3) +.SH "AUTHORS" +.TP +Dotan Barak diff --git a/man/ibv_create_comp_channel.3 b/man/ibv_create_comp_channel.3 new file mode 100644 index 0000000..e0e1e68 --- /dev/null +++ b/man/ibv_create_comp_channel.3 @@ -0,0 +1,49 @@ +.\" -*- nroff -*- +.\" +.TH IBV_CREATE_COMP_CHANNEL 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_create_comp_channel, ibv_destroy_comp_channel \- create or +destroy a completion event channel +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "struct ibv_comp_channel *ibv_create_comp_channel(struct ibv_context +.BI " " "*context" ); +.nl +.BI "int ibv_destroy_comp_channel(struct ibv_comp_channel " "*channel" ); +.fi +.SH "DESCRIPTION" +.B ibv_create_comp_channel() +creates a completion event channel for the InfiniBand device context +.I context\fR. +.PP +.B ibv_destroy_comp_channel() +destroys the completion event channel +.I channel\fR. +.SH "RETURN VALUE" +.B ibv_create_comp_channel() +returns a pointer to the created completion event channel, or NULL if the request fails. +.PP +.B ibv_destroy_comp_channel() +returns 0 on success, or the value of errno on failure (which indicates the failure reason). +.SH "NOTES" +A "completion channel" is an abstraction introduced by libibverbs that +does not exist in the InfiniBand Architecture verbs specification. A +completion channel is essentially file descriptor that is used to +deliver completion notifications to a userspace process. When a +completion event is generated for a completion queue (CQ), the event +is delivered via the completion channel attached to that CQ. This may +be useful to steer completion events to different threads by using +multiple completion channels. +.PP +.B ibv_destroy_comp_channel() +fails if any CQs are still associated with the completion event +channel being destroyed. +.SH "SEE ALSO" +.BR ibv_open_device (3), +.BR ibv_create_cq (3), +.BR ibv_get_cq_event (3) +.SH "AUTHORS" +.TP +Dotan Barak diff --git a/man/ibv_create_cq.3 b/man/ibv_create_cq.3 new file mode 100644 index 0000000..c39fe83 --- /dev/null +++ b/man/ibv_create_cq.3 @@ -0,0 +1,57 @@ +.\" -*- nroff -*- +.\" +.TH IBV_CREATE_CQ 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_create_cq, ibv_destroy_cq \- create or destroy a completion queue (CQ) +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "struct ibv_cq *ibv_create_cq(struct ibv_context " "*context" ", int " "cqe" , +.BI " void " "*cq_context" , +.BI " struct ibv_comp_channel " "*channel" , +.BI " int " "comp_vector" ); +.nl +.BI "int ibv_destroy_cq(struct ibv_cq " "*cq" ); +.fi +.SH "DESCRIPTION" +.B ibv_create_cq() +creates a completion queue (CQ) with at least +.I cqe +entries for the InfiniBand device context +.I context\fR. +The pointer +.I cq_context +will be used to set user context pointer of the CQ structure. The argument +.I channel +is optional; if not NULL, the completion channel +.I channel +will be used to return completion events. The CQ will use the +completion vector +.I comp_vector +for signaling completion events; it must be at least zero and less than +.I context\fR->num_comp_vectors. +.PP +.B ibv_destroy_cq() +destroys the CQ +.I cq\fR. +.SH "RETURN VALUE" +.B ibv_create_cq() +returns a pointer to the CQ, or NULL if the request fails. +.PP +.B ibv_destroy_cq() +returns 0 on success, or the value of errno on failure (which indicates the failure reason). +.SH "NOTES" +.B ibv_create_cq() +may create a CQ with size greater than or equal to the requested +size. Check the cqe attribute in the returned CQ for the actual size. +.PP +.B ibv_destroy_cq() +fails if any queue pair is still associated with this CQ. +.SH "SEE ALSO" +.BR ibv_resize_cq (3), +.BR ibv_req_notify_cq (3), +.BR ibv_create_qp (3) +.SH "AUTHORS" +.TP +Dotan Barak diff --git a/man/ibv_create_qp.3 b/man/ibv_create_qp.3 new file mode 100644 index 0000000..68a08b0 --- /dev/null +++ b/man/ibv_create_qp.3 @@ -0,0 +1,85 @@ +.\" -*- nroff -*- +.\" +.TH IBV_CREATE_QP 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_create_qp, ibv_destroy_qp \- create or destroy a queue pair (QP) +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "struct ibv_qp *ibv_create_qp(struct ibv_pd " "*pd" , +.BI " struct ibv_qp_init_attr " "*qp_init_attr)" ; +.nl +.BI "int ibv_destroy_qp(struct ibv_qp " "*qp)" ; +.fi +.SH "DESCRIPTION" +.B ibv_create_qp() +creates a queue pair (QP) associated with the protection domain +.I pd\fR. +The argument +.I qp_init_attr +is an ibv_qp_init_attr struct, as defined in . +.PP +.nf +struct ibv_qp_init_attr { +.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, or IBV_QPT_UD */ +int sq_sig_all; /* If set, each Work Request (WR) submitted to the SQ generates a completion entry */ +.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() +will update the +.I qp_init_attr\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() +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" +.B ibv_create_qp() +will fail if a it is asked to create QP of a type other than +.B IBV_QPT_RC +or +.B IBV_QPT_UD +associated with an SRQ. +.PP +The attributes max_recv_wr and max_recv_sge are ignored by +.B ibv_create_qp() +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 +Dotan Barak diff --git a/man/ibv_create_srq.3 b/man/ibv_create_srq.3 new file mode 100644 index 0000000..ff33736 --- /dev/null +++ b/man/ibv_create_srq.3 @@ -0,0 +1,67 @@ +.\" -*- nroff -*- +.\" +.TH IBV_CREATE_SRQ 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_create_srq, ibv_destroy_srq \- create or destroy a shared receive queue (SRQ) +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "struct ibv_srq *ibv_create_srq(struct ibv_pd " "*pd" ", struct " +.BI " ibv_srq_init_attr " "*srq_init_attr" ); +.nl +.BI "int ibv_destroy_srq(struct ibv_srq " "*srq" ); +.fi +.SH "DESCRIPTION" +.B ibv_create_srq() +creates a shared receive queue (SRQ) associated with the protection domain +.I pd\fR. +The argument +.I srq_init_attr +is an ibv_srq_init_attr struct, as defined in . +.PP +.nf +struct ibv_srq_init_attr { +.in +8 +void *srq_context; /* Associated context of the SRQ */ +struct ibv_srq_attr attr; /* SRQ attributes */ +.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 (irrelevant for ibv_create_srq) */ +.in -8 +}; +.fi +.PP +The function +.B ibv_create_srq() +will update the +.I srq_init_attr +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() +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 +Dotan Barak diff --git a/man/ibv_get_async_event.3 b/man/ibv_get_async_event.3 new file mode 100644 index 0000000..bb6d068 --- /dev/null +++ b/man/ibv_get_async_event.3 @@ -0,0 +1,117 @@ +.\" -*- nroff -*- +.\" +.TH IBV_GET_ASYNC_EVENT 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_get_async_event, ibv_ack_async_event \- get or acknowledge asynchronous events +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "int ibv_get_async_event(struct ibv_context " "*context" , +.BI " struct ibv_async_event " "*event" ); +.nl +.BI "void ibv_ack_async_event(struct ibv_async_event " "*event" ); +.fi +.SH "DESCRIPTION" +.B ibv_get_async_event() +waits for the next async event of the InfiniBand device context +.I context +and returns it through the pointer +.I event\fR, +which is an ibv_async_event struct, as defined in . +.PP +.nf +struct ibv_async_event { +.in +8 +union { +.in +8 +struct ibv_cq *cq; /* CQ that got the event */ +struct ibv_qp *qp; /* QP that got the event */ +struct ibv_srq *srq; /* SRQ that got the event */ +int port_num; /* port number that got the event */ +.in -8 +} element; +enum ibv_event_type event_type; /* type of the event */ +.in -8 +}; +.fi +.PP +One member of the element union will be valid, depending on the +event_type member of the structure. event_type will be one of the +following events: +.PP +.I QP events: +.TP +.B IBV_EVENT_QP_FATAL \fR Error occurred on a QP and it transitioned to error state +.TP +.B IBV_EVENT_QP_REQ_ERR \fR Invalid Request Local Work Queue Error +.TP +.B IBV_EVENT_QP_ACCESS_ERR \fR Local access violation error +.TP +.B IBV_EVENT_COMM_EST \fR Communication was established on a QP +.TP +.B IBV_EVENT_SQ_DRAINED \fR Send Queue was drained of outstanding messages in progress +.TP +.B IBV_EVENT_PATH_MIG \fR A connection has migrated to the alternate path +.TP +.B IBV_EVENT_PATH_MIG_ERR \fR A connection failed to migrate to the alternate path +.TP +.B IBV_EVENT_QP_LAST_WQE_REACHED \fR Last WQE Reached on a QP associated with an SRQ +.PP +.I CQ events: +.TP +.B IBV_EVENT_CQ_ERR \fR CQ is in error (CQ overrun) +.PP +.I SRQ events: +.TP +.B IBV_EVENT_SRQ_ERR \fR Error occurred on an SRQ +.TP +.B IBV_EVENT_SRQ_LIMIT_REACHED \fR SRQ limit was reached +.PP +.I Port events: +.TP +.B IBV_EVENT_PORT_ACTIVE \fR Link became active on a port +.TP +.B IBV_EVENT_PORT_ERR \fR Link became unavailable on a port +.TP +.B IBV_EVENT_LID_CHANGE \fR LID was changed on a port +.TP +.B IBV_EVENT_PKEY_CHANGE \fR P_Key table was changed on a port +.TP +.B IBV_EVENT_SM_CHANGE \fR SM was changed on a port +.TP +.B IBV_EVENT_CLIENT_REREGISTER \fR SM sent a CLIENT_REREGISTER request to a port +.PP +.I CA events: +.TP +.B IBV_EVENT_DEVICE_FATAL \fR CA is in FATAL state +.PP +.B ibv_ack_async_event() +acknowledge the async event +.I event\fR. +.SH "RETURN VALUE" +.B ibv_get_async_event() +returns 0 on success, and \-1 on error. +.PP +.B ibv_ack_async_event() +returns no value. +.SH "NOTES" +All async events that +.B ibv_get_async_event() +returns must be acknowledged using +.B ibv_ack_async_event()\fR. +To avoid races, destroying an object (CQ, SRQ or QP) will wait for all +affiliated events for the object to be acknowledged; this avoids an +application retrieving an affiliated event after the corresponding +object has already been destroyed. +.PP +.B ibv_get_async_event() +is a blocking function. If multiple threads call this function +simultaneously, then when an async event occurs, only one thread will +receive it, and it is not possible to predict which thread will +receive it. +.SH "SEE ALSO" +.BR ibv_open_device (3) +.SH "AUTHORS" +.TP +Dotan Barak diff --git a/man/ibv_get_cq_event.3 b/man/ibv_get_cq_event.3 new file mode 100644 index 0000000..c48f2a1 --- /dev/null +++ b/man/ibv_get_cq_event.3 @@ -0,0 +1,115 @@ +.TH IBV_GET_CQ_EVENT 3 "2006-10-31" "OpenIB" "OpenIB Programmer's Manual" + +.SH "NAME" +ibv_get_cq_event, ibv_ack_cq_events \- get and acknowledge completion queue (CQ) events + +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "int ibv_get_cq_event(struct ibv_comp_channel " "*channel" , +.BI " struct ibv_cq " "**cq" ", void " "**cq_context" ); +.nl +.BI "void ibv_ack_cq_events(struct ibv_cq " "*cq" ", unsigned int " "nevents" ); +.fi + +.SH "DESCRIPTION" +.B ibv_get_cq_event() +get the next event from the completion event channel +.I channel\fR. +Fill the arguemnt +.I cq +with the CQ that got the event, and its context in +.I cq_context\fR. +.PP +.B ibv_ack_cq_events() +acknowledge +.I nevents +events on the CQ +.I cq\fR. + +.SH "RETURN VALUE" +.B ibv_get_cq_event() +returns 0 on success, and \-1 on error. +.PP +.B ibv_ack_cq_events() +returns no value. +.SH "NOTES" +All completion events that +.B ibv_get_cq_event() +returns must be acknowledged using +.B ibv_ack_cq_events()\fR. +To avoid races, destroying a CQ will wait for all completion events to be acknowledged; this guarntees a one-to-one +correspondence between acks and successful gets. + +.SH "EXAMPLES" +The following code example demonstrates one possible way to work with completion events. It performs the following steps: +.PP +Stage I: Preparation +1. Creates a CQ +2. Requests for notification upon a new (first) completion event +.PP +Stage II: Completion Handling Routine +3. Wait for the completion event +4. Request for notification upon the next completion event +5. Empty the CQ +.PP +Note that an extra event may be triggered without having a corresponding completion entry in the CQ. This occurs if a completion entry is added to the CQ between Step 4 and Step 5, and is then emptied (polled). +.PP +.nf +cq = ibv_create_cq(ctx, 1, ev_ctx, channel, 0); +if (!cq) { + fprintf(stderr, "Failed to create CQ\en"); + return 1; +} +.PP +/* Request notification before any completion can be created */ +if (ibv_req_notify_cq(cq, 0)) { + fprintf(stderr, "Couldn't request CQ notification\en"); + return 1; +} +.PP +\&. +\&. +\&. +.PP +/* Wait for the completion event */ +if (ibv_get_cq_event(ctx->channel, &ev_cq, &ev_ctx)) { + fprintf(stderr, "Failed to get cq_event\en"); + return 1; +} +.PP +/* Request notification upon the next completion event */ +if (ibv_req_notify_cq(ctx->cq, 0)) { + fprintf(stderr, "Couldn't request CQ notification\en"); + return 1; +} +.PP +/* Empty the CQ: poll all of the completions from the CQ (if any exist) */ +do { + ne = ibv_poll_cq(cq, 1, &wc); + if (ne < 0) { + fprintf(stderr, "Failed to poll completions from the CQ\en"); + return 1; + } +.PP + if (wc.status != IBV_WC_SUCCESS) { + fprintf(stderr, "Completion with status 0x%x was found\en", wc.status); + return 1; + } +} while (ne); +.fi + +.SH "CONFORMING TO" +InfiniBand Architecture Specification, Release 1.2. + +.SH "SEE ALSO" +.BR ibv_create_comp_channel (3), +.BR ibv_create_cq (3), +.BR ibv_req_notify_cq (3), +.BR ibv_poll_cq (3) + +.SH "AUTHORS" +.TP +Dotan Barak +.RI < dotanb@mellanox.co.il > diff --git a/man/ibv_modify_qp.3 b/man/ibv_modify_qp.3 new file mode 100644 index 0000000..264baf3 --- /dev/null +++ b/man/ibv_modify_qp.3 @@ -0,0 +1,169 @@ +.\" -*- nroff -*- +.\" +.TH IBV_MODIFY_QP 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_modify_qp \- modify the attributes of a queue pair (QP) +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "int ibv_modify_qp(struct ibv_qp " "*qp" ", struct ibv_qp_attr " "*attr" , +.BI " enum ibv_qp_attr_mask " "attr_mask" ); +.fi +.SH "DESCRIPTION" +.B ibv_modify_qp() +modifies the attributes of QP +.I qp +with the attributes in +.I attr +according to the mask +.I attr_mask\fR. +The argument \fIattr\fR is an ibv_qp_attr struct, as defined in . +.PP +.nf +struct ibv_qp_attr { +.in +8 +enum ibv_qp_state qp_state; /* Move the QP to this state */ +enum ibv_qp_state cur_qp_state; /* Assume this is the current QP state */ +enum ibv_mtu path_mtu; /* Path MTU (valid only for RC/UC QPs) */ +enum ibv_mig_state path_mig_state; /* Path migration state (valid if HCA supports APM) */ +uint32_t qkey; /* QKey for the QP (valid only for UD QPs) */ +uint32_t rq_psn; /* PSN for receive queue (valid only for RC/UC QPs) */ +uint32_t sq_psn; /* PSN for send queue (valid only for RC/UC QPs) */ +uint32_t dest_qp_num; /* Destination QP number (valid only for RC/UC QPs) */ +int qp_access_flags; /* Mask of enabled remote access operations (valid only for RC/UC QPs) */ +struct ibv_qp_cap cap; /* QP capabilities (valid if HCA supports QP resizing) */ +struct ibv_ah_attr ah_attr; /* Primary path address vector (valid only for RC/UC QPs) */ +struct ibv_ah_attr alt_ah_attr; /* Alternate path address vector (valid only for RC/UC QPs) */ +uint16_t pkey_index; /* Primary PKey index */ +uint16_t alt_pkey_index; /* Alternate PKey index */ +uint8_t en_sqd_async_notify; /* Enable SQD.drained async notification (Valid only if qp_state is SQD) */ +uint8_t sq_draining; /* Is the QP draining? Irrelevant for ibv_modify_qp() */ +uint8_t max_rd_atomic; /* Number of outstanding RDMA reads & atomic operations on the destination QP (valid only for RC QPs) */ +uint8_t max_dest_rd_atomic; /* Number of responder resources for handling incoming RDMA reads & atomic operations (valid only for RC QPs) */ +uint8_t min_rnr_timer; /* Minimum RNR NAK timer (valid only for RC QPs) */ +uint8_t port_num; /* Primary port number */ +uint8_t timeout; /* Local ack timeout for primary path (valid only for RC QPs) */ +uint8_t retry_cnt; /* Retry count (valid only for RC QPs) */ +uint8_t rnr_retry; /* RNR retry (valid only for RC QPs) */ +uint8_t alt_port_num; /* Alternate port number */ +uint8_t alt_timeout; /* Local ack timeout for alternate path (valid only for RC QPs) */ +.in -8 +}; +.fi +.PP +For details on struct ibv_qp_cap see the description of +.B ibv_create_qp()\fR. +For details on struct ibv_ah_attr see the description of +.B ibv_create_ah()\fR. +.PP +The argument +.I attr_mask +specifies the QP attributes to be modified. +The argument is either 0 or the bitwise OR of one or more of the following flags: +.PP +.TP +.B IBV_QP_STATE \fR Modify qp_state +.TP +.B IBV_QP_CUR_STATE \fR Set cur_qp_state +.TP +.B IBV_QP_EN_SQD_ASYNC_NOTIFY \fR Set en_sqd_async_notify +.TP +.B IBV_QP_ACCESS_FLAGS \fR Set qp_access_flags +.TP +.B IBV_QP_PKEY_INDEX \fR Set pkey_index +.TP +.B IBV_QP_PORT \fR Set port_num +.TP +.B IBV_QP_QKEY \fR Set qkey +.TP +.B IBV_QP_AV \fR Set ah_attr +.TP +.B IBV_QP_PATH_MTU \fR Set path_mtu +.TP +.B IBV_QP_TIMEOUT \fR Set timeout +.TP +.B IBV_QP_RETRY_CNT \fR Set retry_cnt +.TP +.B IBV_QP_RNR_RETRY \fR Set rnr_retry +.TP +.B IBV_QP_RQ_PSN \fR Set rq_psn +.TP +.B IBV_QP_MAX_QP_RD_ATOMIC \fR Set max_rd_atomic +.TP +.B IBV_QP_ALT_PATH \fR Set the alternative path via: alt_ah_attr, alt_pkey_index, alt_port_num, alt_timeout +.TP +.B IBV_QP_MIN_RNR_TIMER \fR Set min_rnr_timer +.TP +.B IBV_QP_SQ_PSN \fR Set sq_psn +.TP +.B IBV_QP_MAX_DEST_RD_ATOMIC \fR Set max_dest_rd_atomic +.TP +.B IBV_QP_PATH_MIG_STATE \fR Set path_mig_state +.TP +.B IBV_QP_CAP \fR Set cap +.TP +.B IBV_QP_DEST_QPN \fR Set dest_qp_num +.SH "RETURN VALUE" +.B ibv_modify_qp() +returns 0 on success, or the value of errno on failure (which indicates the failure reason). +.SH "NOTES" +If any of the modify attributes or the modify mask are invalid, none +of the attributes will be modified (including the QP state). +.PP +Not all devices support resizing QPs. To check if a device supports it, check if the +.B IBV_DEVICE_RESIZE_MAX_WR +bit is set in the device capabilities flags. +.PP +Not all devices support alternate paths. To check if a device supports it, check if the +.B IBV_DEVICE_AUTO_PATH_MIG +bit is set in the device capabilities flags. +.PP +The following tables indicate for each QP Transport Service Type, the +minimum list of attributes that must be changed upon transitioning QP +state from: Reset \-\-> Init \-\-> RTR \-\-> RTS. +.PP +.nf +For QP Transport Service Type \fB IBV_QPT_UD\fR: +.sp +Next state Required attributes +\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +Init \fB IBV_QP_STATE, IBV_QP_PKEY_INDEX, IBV_QP_PORT, \fR + \fB IBV_QP_QKEY \fR +RTR \fB None \fR +RTS \fB IBV_QP_STATE, IBV_QP_SQ_PSN \fR +.fi +.PP +.nf +For QP Transport Service Type \fB IBV_QPT_UC\fR: +.sp +Next state Required attributes +\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +Init \fB IBV_QP_STATE, IBV_QP_PKEY_INDEX, IBV_QP_PORT, \fR + \fB IBV_QP_ACCESS_FLAGS \fR +RTR \fB IBV_QP_STATE, IBV_QP_AV, IBV_QP_PATH_MTU, \fR + \fB IBV_QP_DEST_QPN, IBV_QP_RQ_PSN \fR +RTS \fB IBV_QP_STATE, IBV_QP_SQ_PSN \fR +.fi +.PP +.nf +For QP Transport Service Type \fB IBV_QPT_RC\fR: +.sp +Next state Required attributes +\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +Init \fB IBV_QP_STATE, IBV_QP_PKEY_INDEX, IBV_QP_PORT, \fR + \fB IBV_QP_ACCESS_FLAGS \fR +RTR \fB IBV_QP_STATE, IBV_QP_AV, IBV_QP_PATH_MTU, \fR + \fB IBV_QP_DEST_QPN, IBV_QP_RQ_PSN, \fR + \fB IBV_QP_MAX_DEST_RD_ATOMIC, IBV_QP_MIN_RNR_TIMER \fR +RTS \fB IBV_QP_STATE, IBV_QP_SQ_PSN, IBV_QP_MAX_QP_RD_ATOMIC, \fR + \fB IBV_QP_RETRY_CNT, IBV_QP_RNR_RETRY, IBV_QP_TIMEOUT \fR +.fi +.SH "SEE ALSO" +.BR ibv_create_qp (3), +.BR ibv_destroy_qp (3), +.BR ibv_query_qp (3), +.BR ibv_create_ah (3) +.SH "AUTHORS" +.TP +Dotan Barak diff --git a/man/ibv_modify_srq.3 b/man/ibv_modify_srq.3 new file mode 100644 index 0000000..9118994 --- /dev/null +++ b/man/ibv_modify_srq.3 @@ -0,0 +1,63 @@ +.\" -*- nroff -*- +.\" +.TH IBV_MODIFY_SRQ 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_modify_srq \- modify attributes of a shared receive queue (SRQ) +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "int ibv_modify_srq(struct ibv_srq " "*srq" , +.BI " struct ibv_srq_attr " "*srq_attr" , +.BI " enum ibv_srq_attr_mask " "srq_attr_mask" ); +.fi +.SH "DESCRIPTION" +.B ibv_modify_srq() +modifies the attributes of SRQ +.I srq +with the attributes in +.I srq_attr +according to the mask +.I srq_attr_mask\fR. +The argument \fIsrq_attr\fR is an ibv_srq_attr struct, as defined in . +.PP +.nf +struct ibv_srq_attr { +.in +8 +uint32_t max_wr; /* maximum number of outstanding work requests (WRs) in the SRQ */ +uint32_t max_sge; /* number of scatter elements per WR (irrelevant for ibv_modify_srq) */ +uint32_t srq_limit; /* the limit value of the SRQ */ +.in -8 +}; +.fi +.PP +The argument +.I srq_attr_mask +specifies the SRQ attributes to be modified. +The argument is either 0 or the bitwise OR of one or more of the following flags: +.PP +.TP +.B IBV_SRQ_MAX_WR \fR Resize the SRQ +.TP +.B IBV_SRQ_LIMIT \fR Set the SRQ limit +.SH "RETURN VALUE" +.B ibv_modify_srq() +returns 0 on success, or the value of errno on failure (which indicates the failure reason). +.SH "NOTES" +If any of the modify attributes is invalid, none of the attributes will be modified. +.PP +Not all devices support resizing SRQs. To check if a device supports it, check if the +.B IBV_DEVICE_SRQ_RESIZE +bit is set in the device capabilties flags. +.PP +Modifying the srq_limit arms the SRQ to produce an +.B IBV_EVENT_SRQ_LIMIT_REACHED +"low watermark" asynchronous event once the number of WRs in the SRQ drops below srq_limit. +.SH "SEE ALSO" +.BR ibv_query_device (3), +.BR ibv_create_srq (3), +.BR ibv_destroy_srq (3), +.BR ibv_query_srq (3) +.SH "AUTHORS" +.TP +Dotan Barak diff --git a/man/ibv_poll_cq.3 b/man/ibv_poll_cq.3 new file mode 100644 index 0000000..b634fc9 --- /dev/null +++ b/man/ibv_poll_cq.3 @@ -0,0 +1,77 @@ +.\" -*- nroff -*- +.\" +.TH IBV_POLL_CQ 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_poll_cq \- poll a completion queue (CQ) +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "int ibv_poll_cq(struct ibv_cq " "*cq" ", int " "num_entries" , +.BI " struct ibv_wc " "*wc" ); +.fi +.SH "DESCRIPTION" +.B ibv_poll_cq() +polls the CQ +.I cq +for work completions and returns the first +.I num_entries +(or all available completions if the CQ contains fewer than this number) in the array +.I wc\fR. +The argument +.I wc +is a pointer to an array of ibv_wc structs, as defined in . +.PP +.nf +struct ibv_wc { +.in +8 +uint64_t wr_id; /* ID of the completed Work Request (WR) */ +enum ibv_wc_status status; /* Status of the operation */ +enum ibv_wc_opcode opcode; /* Operation type specified in the completed WR */ +uint32_t vendor_err; /* Vendor error syndrome */ +uint32_t byte_len; /* Number of bytes transferred */ +uint32_t imm_data; /* Immediate data (in network byte order) */ +uint32_t qp_num; /* Local QP number of completed WR */ +uint32_t src_qp; /* Source QP number (remote QP number) of completed WR */ +enum ibv_wc_flags wc_flags; /* Flags of the completed WR */ +uint16_t pkey_index; /* P_Key index (valid only for GSI QPs) */ +uint16_t slid; /* Source LID */ +uint8_t sl; /* Service Level */ +uint8_t dlid_path_bits; /* DLID path bits (not applicable for multicast messages) */ +.in -8 +}; +.sp +.fi +.PP +The attribute wc_flags describes the properties of the work completion. +It is either 0 or the bitwise OR of one or more of the following flags: +.PP +.TP +.B IBV_WC_GRH \fR GRH is present +.TP +.B IBV_WC_WITH_IMM \fR Immediate data value is valid +.PP +Not all +.I wc +attributes are always valid. If the completion status is other than +.B IBV_WC_SUCCESS\fR, +only the following attributes are valid: wr_id, status, qp_num, and vendor_err. +.SH "RETURN VALUE" +On success, +.B ibv_poll_cq() +returns a non-negative value equal to the number of completions +found. On failure, a negative value is returned. +.SH "NOTES" +.PP +Each polled completion is removed from the CQ and cannot be returned to it. +.PP +The user should consume work completions at a rate that prevents CQ +overrun from occurrence. In case of a CQ overrun, the async event +.B IBV_EVENT_CQ_ERR +will be triggered, and the CQ cannot be used. +.SH "SEE ALSO" +.BR ibv_post_send (3), +.BR ibv_post_recv (3) +.SH "AUTHORS" +.TP +Dotan Barak diff --git a/man/ibv_post_recv.3 b/man/ibv_post_recv.3 new file mode 100644 index 0000000..478b67a --- /dev/null +++ b/man/ibv_post_recv.3 @@ -0,0 +1,70 @@ +.\" -*- nroff -*- +.\" +.TH IBV_POST_RECV 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_post_recv \- post a list of work requests (WRs) to a receive queue +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "int ibv_post_recv(struct ibv_qp " "*qp" ", struct ibv_recv_wr " "*wr" , +.BI " struct ibv_recv_wr " "**bad_wr" ); +.fi +.SH "DESCRIPTION" +.B ibv_post_recv() +posts the linked list of work requests (WRs) starting with +.I wr +to the receive queue of the queue pair +.I qp\fR. +It stops processing WRs from this list at the first failure (that can +be detected immediately while requests are being posted), and returns +this failing WR through +.I bad_wr\fR. +.PP +The argument +.I wr +is an ibv_recv_wr struct, as defined in . +.PP +.nf +struct ibv_recv_wr { +.in +8 +uint64_t wr_id; /* User defined WR ID */ +struct ibv_recv_wr *next; /* Pointer to next WR in list, NULL if last WR */ +struct ibv_sge *sg_list; /* Pointer to the s/g array */ +int num_sge; /* Size of the s/g array */ +.in -8 +}; +.sp +.nf +struct ibv_sge { +.in +8 +uint64_t addr; /* Start address of the local memory buffer */ +uint32_t length; /* Length of the buffer */ +uint32_t lkey; /* Key of the local Memory Region */ +.in -8 +}; +.fi + +.SH "RETURN VALUE" +.B ibv_post_recv() +returns 0 on success, or the value of errno on failure (which indicates the failure reason). +.SH "NOTES" +The buffers used by a WR can only be safely reused after WR the +request is fully executed and a work completion has been retrieved +from the corresponding completion queue (CQ). +.PP +If the QP +.I qp +is associated with a shared receive queue, you must use the function +.B ibv_post_srq_recv()\fR, +and not +.B ibv_post_recv()\fR, +since the QP's own receive queue will not be used. +.SH "SEE ALSO" +.BR ibv_create_qp (3), +.BR ibv_post_send (3), +.BR ibv_post_srq_recv (3), +.BR ibv_poll_cq (3) +.SH "AUTHORS" +.TP +Dotan Barak diff --git a/man/ibv_post_send.3 b/man/ibv_post_send.3 new file mode 100644 index 0000000..d1b04fd --- /dev/null +++ b/man/ibv_post_send.3 @@ -0,0 +1,121 @@ +.\" -*- nroff -*- +.\" +.TH IBV_POST_SEND 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_post_send \- post a list of work requests (WRs) to a send queue +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "int ibv_post_send(struct ibv_qp " "*qp" ", struct ibv_send_wr " "*wr" , +.BI " struct ibv_send_wr " "**bad_wr" ); +.fi +.SH "DESCRIPTION" +.B ibv_post_send() +posts the linked list of work requests (WRs) starting with +.I wr +to the send queue of the queue pair +.I qp\fR. +It stops processing WRs from this list at the first failure (that can +be detected immediately while requests are being posted), and returns +this failing WR through +.I bad_wr\fR. +.PP +The argument +.I wr +is an ibv_send_wr struct, as defined in . +.PP +.nf +struct ibv_send_wr { +.in +8 +uint64_t wr_id; /* User defined WR ID */ +struct ibv_send_wr *next; /* Pointer to next WR in list, NULL if last WR */ +struct ibv_sge *sg_list; /* Pointer to the s/g array */ +int num_sge; /* Size of the s/g array */ +enum ibv_wr_opcode opcode; /* Operation type */ +enum ibv_send_flags send_flags; /* Flags of the WR properties */ +uint32_t imm_data; /* Immediate data (in network byte order) */ +union { +.in +8 +struct { +.in +8 +uint64_t remote_addr; /* Start address of remote memory buffer */ +uint32_t rkey; /* Key of the remote Memory Region */ +.in -8 +} rdma; +struct { +.in +8 +uint64_t remote_addr; /* Start address of remote memory buffer */ +uint64_t compare_add; /* Compare operand */ +uint64_t swap; /* Swap operand */ +uint32_t rkey; /* Key of the remote Memory Region */ +.in -8 +} atomic; +struct { +.in +8 +struct ibv_ah *ah; /* Address handle (AH) for the remote node address */ +uint32_t remote_qpn; /* QP number of the destination QP */ +uint32_t remote_qkey; /* Q_Key number of the destination QP */ +.in -8 +} ud; +.in -8 +} wr; +.in -8 +}; +.sp +.nf +struct ibv_sge { +.in +8 +uint64_t addr; /* Start address of the local memory buffer */ +uint32_t length; /* Length of the buffer */ +uint32_t lkey; /* Key of the local Memory Region */ +.in -8 +}; +.fi +.PP +Each QP Transport Service Type supports a specific set of opcodes, as shown in the following table: +.PP +.nf +OPCODE | IBV_QPT_UD | IBV_QPT_UC | IBV_QPT_RC +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\- +IBV_WR_SEND | X | X | X +IBV_WR_SEND_WITH_IMM | X | X | X +IBV_WR_RDMA_WRITE | | X | X +IBV_WR_RDMA_WRITE_WITH_IMM | | X | X +IBV_WR_RDMA_READ | | | X +IBV_WR_ATOMIC_CMP_AND_SWP | | | X +IBV_WR_ATOMIC_FETCH_AND_ADD | | | X +.fi +.PP +The attribute send_flags describes the properties of the \s-1WR\s0. It is either 0 or the bitwise \s-1OR\s0 of one or more of the following flags: +.PP +.TP +.B IBV_SEND_FENCE \fR Set the fence indicator. Valid only for QPs with Transport Service Type \fBIBV_QPT_RC +.TP +.B IBV_SEND_SIGNALED \fR Set the completion notification indicator. Relevant only if QP was created with sq_sig_all=0 +.TP +.B IBV_SEND_SOLICITED \fR Set the solicited event indicator. Valid only for Send and RDMA Write with immediate +.TP +.B IBV_SEND_INLINE \fR Send data in given gather list as inline data +in a send WQE. Valid only for Send and RDMA Write. The L_Key will not be checked. +.SH "RETURN VALUE" +.B ibv_post_send() +returns 0 on success, or the value of errno on failure (which indicates the failure reason). +.SH "NOTES" +The user should not alter or destroy AHs associated with WRs until +request is fully executed and a work completion has been retrieved +from the corresponding completion queue (CQ) to avoid unexpected +behavior. +.PP +The buffers used by a WR can only be safely reused after WR the +request is fully executed and a work completion has been retrieved +from the corresponding completion queue (CQ). +.SH "SEE ALSO" +.BR ibv_create_qp (3), +.BR ibv_create_ah (3), +.BR ibv_post_recv (3), +.BR ibv_post_srq_recv (3), +.BR ibv_poll_cq (3) +.SH "AUTHORS" +.TP +Dotan Barak diff --git a/man/ibv_post_srq_recv.3 b/man/ibv_post_srq_recv.3 new file mode 100644 index 0000000..c7e2302 --- /dev/null +++ b/man/ibv_post_srq_recv.3 @@ -0,0 +1,61 @@ +.\" -*- nroff -*- +.\" +.TH IBV_POST_SRQ_RECV 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_post_srq_recv \- post a list of work requests (WRs) to a shared receive queue (SRQ) +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "int ibv_post_srq_recv(struct ibv_srq " "*srq" ", struct ibv_recv_wr " "*wr" , +.BI " struct ibv_recv_wr " "**bad_wr" ); +.fi +.SH "DESCRIPTION" +.B ibv_post_srq_recv() +posts the linked list of work requests (WRs) starting with +.I wr +to the shared receive queue (SRQ) +.I srq\fR. +It stops processing WRs from this list at the first failure (that can +be detected immediately while requests are being posted), and returns +this failing WR through +.I bad_wr\fR. +.PP +The argument +.I wr +is an ibv_recv_wr struct, as defined in . +.PP +.nf +struct ibv_recv_wr { +.in +8 +uint64_t wr_id; /* User defined WR ID */ +struct ibv_recv_wr *next; /* Pointer to next WR in list, NULL if last WR */ +struct ibv_sge *sg_list; /* Pointer to the s/g array */ +int num_sge; /* Size of the s/g array */ +.in -8 +}; +.sp +.nf +struct ibv_sge { +.in +8 +uint64_t addr; /* Start address of the local memory buffer */ +uint32_t length; /* Length of the buffer */ +uint32_t lkey; /* Key of the local Memory Region */ +.in -8 +}; +.fi +.SH "RETURN VALUE" +.B ibv_post_srq_recv() +returns 0 on success, or the value of errno on failure (which indicates the failure reason). +.SH "NOTES" +The buffers used by a WR can only be safely reused after WR the +request is fully executed and a work completion has been retrieved +from the corresponding completion queue (CQ). +.SH "SEE ALSO" +.BR ibv_create_qp (3), +.BR ibv_post_send (3), +.BR ibv_post_recv (3), +.BR ibv_poll_cq (3) +.SH "AUTHORS" +.TP +Dotan Barak diff --git a/man/ibv_query_device.3 b/man/ibv_query_device.3 new file mode 100644 index 0000000..344f5b3 --- /dev/null +++ b/man/ibv_query_device.3 @@ -0,0 +1,84 @@ +.\" -*- nroff -*- +.\" +.TH IBV_QUERY_DEVICE 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_query_device \- query an InfiniBand device's attributes +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "int ibv_query_device(struct ibv_context " "*context", +.BI " struct ibv_device_attr " "*device_attr" ); +.fi +.SH "DESCRIPTION" +.B ibv_query_device() +returns the attributes of the device with context +.I context\fR. +The argument +.I device_attr +is a pointer to an ibv_device_attr struct, as defined in . +.PP +.nf +struct ibv_device_attr { +.in +8 +char fw_ver[64]; /* FW version */ +uint64_t node_guid; /* Node GUID */ +uint64_t sys_image_guid; /* System image GUID */ +uint64_t max_mr_size; /* Largest contiguous block that can be registered */ +uint64_t page_size_cap; /* Supported memory shift sizes */ +uint32_t vendor_id; /* Vendor ID, per IEEE */ +uint32_t vendor_part_id; /* Vendor supplied part ID */ +uint32_t hw_ver; /* Hardware version */ +int max_qp; /* Maximum number of supported QPs */ +int max_qp_wr; /* Maximum number of outstanding WR on any work queue */ +int device_cap_flags; /* HCA capabilities mask */ +int max_sge; /* Maximum number of s/g per WR for non-RD QPs */ +int max_sge_rd; /* Maximum number of s/g per WR for RD QPs */ +int max_cq; /* Maximum number of supported CQs */ +int max_cqe; /* Maximum number of CQE capacity per CQ */ +int max_mr; /* Maximum number of supported MRs */ +int max_pd; /* Maximum number of supported PDs */ +int max_qp_rd_atom; /* Maximum number of RDMA Read & Atomic operations that can be outstanding per QP */ +int max_ee_rd_atom; /* Maximum number of RDMA Read & Atomic operations that can be outstanding per EEC */ +int max_res_rd_atom; /* Maximum number of resources used for RDMA Read & Atomic operations by this HCA as the Target */ +int max_qp_init_rd_atom; /* Maximum depth per QP for initiation of RDMA Read & Atomic operations */ +int max_ee_init_rd_atom; /* Maximum depth per EEC for initiation of RDMA Read & Atomic operations */ +enum ibv_atomic_cap atomic_cap; /* Atomic operations support level */ +int max_ee; /* Maximum number of supported EE contexts */ +int max_rdd; /* Maximum number of supported RD domains */ +int max_mw; /* Maximum number of supported MWs */ +int max_raw_ipv6_qp; /* Maximum number of supported raw IPv6 datagram QPs */ +int max_raw_ethy_qp; /* Maximum number of supported Ethertype datagram QPs */ +int max_mcast_grp; /* Maximum number of supported multicast groups */ +int max_mcast_qp_attach; /* Maximum number of QPs per multicast group which can be attached */ +int max_total_mcast_qp_attach;/* Maximum number of QPs which can be attached to multicast groups */ +int max_ah; /* Maximum number of supported address handles */ +int max_fmr; /* Maximum number of supported FMRs */ +int max_map_per_fmr; /* Maximum number of (re)maps per FMR before an unmap operation in required */ +int max_srq; /* Maximum number of supported SRQs */ +int max_srq_wr; /* Maximum number of WRs per SRQ */ +int max_srq_sge; /* Maximum number of s/g per SRQ */ +uint16_t max_pkeys; /* Maximum number of partitions */ +uint8_t local_ca_ack_delay; /* Local CA ack delay */ +uint8_t phys_port_cnt; /* Number of physical ports */ +.in -8 +}; +.fi +.SH "RETURN VALUE" +.B ibv_query_device() +returns 0 on success, or the value of errno on failure (which indicates the failure reason). +.SH "NOTES" +The maximum values returned by this function are the upper limits of +supported resources by the device. However, it may not be possible to +use these maximum values, since the actual number of any resource that +can be created may be limited by the machine configuration, the amount +of host memory, user permissions, and the amount of resources already +in use by other users/processes. +.SH "SEE ALSO" +.BR ibv_open_device (3), +.BR ibv_query_port (3), +.BR ibv_query_pkey (3), +.BR ibv_query_gid (3) +.SH "AUTHORS" +.TP +Dotan Barak diff --git a/man/ibv_query_gid.3 b/man/ibv_query_gid.3 new file mode 100644 index 0000000..df3ac10 --- /dev/null +++ b/man/ibv_query_gid.3 @@ -0,0 +1,33 @@ +.\" -*- nroff -*- +.\" +.TH IBV_QUERY_GID 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_query_gid \- query an InfiniBand port's GID table +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "int ibv_query_gid(struct ibv_context " "*context" ", uint8_t " "port_num" , +.BI " int " "index" ", union ibv_gid " "*gid" ); +.fi +.SH "DESCRIPTION" +.B ibv_query_gid() +returns the GID value in entry +.I index +of port +.I port_num +for device context +.I context +through the pointer +.I gid\fR. +.SH "RETURN VALUE" +.B ibv_query_gid() +returns 0 on success, and \-1 on error. +.SH "SEE ALSO" +.BR ibv_open_device (3), +.BR ibv_query_device (3), +.BR ibv_query_port (3), +.BR ibv_query_pkey (3) +.SH "AUTHORS" +.TP +Dotan Barak diff --git a/man/ibv_query_pkey.3 b/man/ibv_query_pkey.3 new file mode 100644 index 0000000..37c408d --- /dev/null +++ b/man/ibv_query_pkey.3 @@ -0,0 +1,33 @@ +.\" -*- nroff -*- +.\" +.TH IBV_QUERY_PKEY 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_query_pkey \- query an InfiniBand port's P_Key table +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "int ibv_query_pkey(struct ibv_context " "*context" ", uint8_t " "port_num" , +.BI " int " "index" ", uint16_t " "*pkey" "); +.fi +.SH "DESCRIPTION" +.B ibv_query_pkey() +returns the P_Key value in entry +.I index +of port +.I port_num +for device context +.I context +through the pointer +.I pkey\fR. +.SH "RETURN VALUE" +.B ibv_query_pkey() +returns 0 on success, and -1 on error. +.SH "SEE ALSO" +.BR ibv_open_device (3), +.BR ibv_query_device (3), +.BR ibv_query_port (3), +.BR ibv_query_gid (3) +.SH "AUTHORS" +.TP +Dotan Barak diff --git a/man/ibv_query_port.3 b/man/ibv_query_port.3 new file mode 100644 index 0000000..a04ebb7 --- /dev/null +++ b/man/ibv_query_port.3 @@ -0,0 +1,61 @@ +.\" -*- nroff -*- +.\" +.TH IBV_QUERY_PORT 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_query_port \- query an InfiniBand port's attributes +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "int ibv_query_port(struct ibv_context " "*context" ", uint8_t " "port_num" , +.BI " struct ibv_port_attr " "*port_attr" "); +.fi +.SH "DESCRIPTION" +.B ibv_query_port() +returns the attributes of port +.I port_num +for device context +.I context +through the pointer +.I port_attr\fR. +The argument +.I port_attr +is an ibv_port_attr struct, as defined in . +.PP +.nf +struct ibv_port_attr { +.in +8 +enum ibv_port_state state; /* Logical port state */ +enum ibv_mtu max_mtu; /* Max MTU supported by port */ +enum ibv_mtu active_mtu; /* Actual MTU */ +int gid_tbl_len; /* Length of source GID table */ +uint32_t port_cap_flags; /* Port capabilities */ +uint32_t max_msg_sz; /* Maximum message size */ +uint32_t bad_pkey_cntr; /* Bad PKey counter */ +uint32_t qkey_viol_cntr; /* QKey violation counter */ +uint16_t pkey_tbl_len; /* Length of partition table */ +uint16_t lid; /* Base port LID */ +uint16_t sm_lid; /* SM LID */ +uint8_t lmc; /* LMC of LID */ +uint8_t max_vl_num; /* Maximum number of VLs */ +uint8_t sm_sl; /* SM service level */ +uint8_t subnet_timeout; /* Subnet propagation delay */ +uint8_t init_type_reply;/* Type of initialization performed by SM */ +uint8_t active_width; /* Currently active link width */ +uint8_t active_speed; /* Currently active link speed */ +uint8_t phys_state; /* Physical port state */ +.in -8 +}; +.sp +.fi +.SH "RETURN VALUE" +.B ibv_query_port() +returns 0 on success, or the value of errno on failure (which indicates the failure reason). +.SH "SEE ALSO" +.BR ibv_create_qp (3), +.BR ibv_destroy_qp (3), +.BR ibv_query_qp (3), +.BR ibv_create_ah (3) +.SH "AUTHORS" +.TP +Dotan Barak diff --git a/man/ibv_query_qp.3 b/man/ibv_query_qp.3 new file mode 100644 index 0000000..43f9767 --- /dev/null +++ b/man/ibv_query_qp.3 @@ -0,0 +1,88 @@ +.\" -*- nroff -*- +.\" +.TH IBV_QUERY_QP 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_query_qp \- get the attributes of a queue pair (QP) +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "int ibv_query_qp(struct ibv_qp " "*qp" ", struct ibv_qp_attr " "*attr" , +.BI " enum ibv_qp_attr_mask " "attr_mask" , +.BI " struct ibv_qp_init_attr " "*init_attr" ); +.fi +.SH "DESCRIPTION" +.B ibv_query_qp() +gets the attributes specified in +.I attr_mask +for the QP +.I qp +and returns them through the pointers +.I attr +and +.I init_attr\fR. +The argument +.I attr +is an ibv_qp_attr struct, as defined in . +.PP +.nf +struct ibv_qp_attr { +.in +8 +enum ibv_qp_state qp_state; /* Current QP state */ +enum ibv_qp_state cur_qp_state; /* Current QP state - irrelevant for ibv_query_qp */ +enum ibv_mtu path_mtu; /* Path MTU (valid only for RC/UC QPs) */ +enum ibv_mig_state path_mig_state; /* Path migration state (valid if HCA supports APM) */ +uint32_t qkey; /* QKey of the QP (valid only for UD QPs) */ +uint32_t rq_psn; /* PSN for receive queue (valid only for RC/UC QPs) */ +uint32_t sq_psn; /* PSN for send queue (valid only for RC/UC QPs) */ +uint32_t dest_qp_num; /* Destination QP number (valid only for RC/UC QPs) */ +int qp_access_flags; /* Mask of enabled remote access operations (valid only for RC/UC QPs) */ +struct ibv_qp_cap cap; /* QP capabilities */ +struct ibv_ah_attr ah_attr; /* Primary path address vector (valid only for RC/UC QPs) */ +struct ibv_ah_attr alt_ah_attr; /* Alternate path address vector (valid only for RC/UC QPs) */ +uint16_t pkey_index; /* Primary PKey index */ +uint16_t alt_pkey_index; /* Alternate PKey index */ +uint8_t en_sqd_async_notify; /* Enable SQD.drained async notification - irrelevant for ibv_query_qp */ +uint8_t sq_draining; /* Is the QP draining? (Valid only if qp_state is SQD) */ +uint8_t max_rd_atomic; /* Number of outstanding RDMA reads & atomic operations on the destination QP (valid only for RC QPs) */ +uint8_t max_dest_rd_atomic; /* Number of responder resources for handling incoming RDMA reads & atomic operations (valid only for RC QPs) */ +uint8_t min_rnr_timer; /* Minimum RNR NAK timer (valid only for RC QPs) */ +uint8_t port_num; /* Primary port number */ +uint8_t timeout; /* Local ack timeout for primary path (valid only for RC QPs) */ +uint8_t retry_cnt; /* Retry count (valid only for RC QPs) */ +uint8_t rnr_retry; /* RNR retry (valid only for RC QPs) */ +uint8_t alt_port_num; /* Alternate port number */ +uint8_t alt_timeout; /* Local ack timeout for alternate path (valid only for RC QPs) */ +.in -8 +}; +.fi +.PP +For details on struct ibv_qp_cap see the description of +.B ibv_create_qp()\fR. +For details on struct ibv_ah_attr see the description of +.B ibv_create_ah()\fR. +.SH "RETURN VALUE" +.B ibv_query_qp() +returns 0 on success, or the value of errno on failure (which indicates the failure reason). +.SH "NOTES" +The argument +.I attr_mask +is a hint that specifies the minimum list of attributes to retrieve. +Some InfiniBand devices may return extra attributes not requested, for +example if the value can be returned cheaply. +.PP +Attribute values are valid if they have been set using +.B ibv_modify_qp()\fR. +The exact list of valid attributes depends on the QP state. +.PP +Multiple calls to +.B ibv_query_qp() +may yield some differences in the values returned for the following attributes: qp_state, path_mig_state, sq_draining, ah_attr (if APM is enabled). +.SH "SEE ALSO" +.BR ibv_create_qp (3), +.BR ibv_destroy_qp (3), +.BR ibv_modify_qp (3), +.BR ibv_create_ah (3) +.SH "AUTHORS" +.TP +Dotan Barak diff --git a/man/ibv_query_srq.3 b/man/ibv_query_srq.3 new file mode 100644 index 0000000..56db4fa --- /dev/null +++ b/man/ibv_query_srq.3 @@ -0,0 +1,44 @@ +.\" -*- nroff -*- +.\" +.TH IBV_QUERY_SRQ 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_query_srq \- get the attributes of a shared receive queue (SRQ) +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "int ibv_query_srq(struct ibv_srq " "*srq" ", struct ibv_srq_attr " "*srq_attr" ); +.fi +.SH "DESCRIPTION" +.B ibv_query_srq() +gets the attributes of the SRQ +.I srq +and returns them through the pointer +.I srq_attr\fR. +The argument +.I srq_attr +is an ibv_srq_attr struct, as defined in . +.PP +.nf +struct ibv_srq_attr { +.in +8 +uint32_t max_wr; /* maximum number of outstanding work requests (WRs) in the SRQ */ +uint32_t max_sge; /* maximum number of scatter elements per WR */ +uint32_t srq_limit; /* the limit value of the SRQ */ +.in -8 +}; +.fi +.SH "RETURN VALUE" +.B ibv_query_srq() +returns 0 on success, or the value of errno on failure (which indicates the failure reason). +.SH "NOTES" +If the value returned for srq_limit is 0, then the SRQ limit reached +("low watermark") event is not (or no longer) armed, and no +asynchronous events will be generated until the event is rearmed. +.SH "SEE ALSO" +.BR ibv_create_srq (3), +.BR ibv_destroy_srq (3), +.BR ibv_modify_srq (3) +.SH "AUTHORS" +.TP +Dotan Barak diff --git a/man/ibv_rate_to_mult.3 b/man/ibv_rate_to_mult.3 new file mode 100644 index 0000000..cf009bf --- /dev/null +++ b/man/ibv_rate_to_mult.3 @@ -0,0 +1,46 @@ +.\" -*- nroff -*- +.\" +.TH IBV_RATE_TO_MULT 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +.nf +ibv_rate_to_mult \- convert IB rate enumeration to multiplier of 2.5 Gbit/sec +.nl +ibv_mult_to_rate \- convert multiplier of 2.5 Gbit/sec to an IB rate enumeration +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "int ibv_rate_to_mult(enum ibv_rate " "rate" "); +.nl +.BI "enum ibv_rate mult_to_ibv_rate(int " "mult" "); +.fi +.SH "DESCRIPTION" +.B ibv_rate_to_mult() +converts the IB transmission rate enumeration +.I rate +to a multiple of 2.5 Gbit/sec (the base rate). For example, if +.I rate +is +.BR IBV_RATE_5_GBPS\fR, +the value 2 will be returned (5 Gbit/sec = 2 * 2.5 Gbit/sec). +.PP +.B mult_to_ibv_rate() +converts the multiplier value (of 2.5 Gbit/sec) +.I mult +to an IB transmission rate enumeration. For example, if +.I mult +is 2, the rate enumeration +.BR IBV_RATE_5_GBPS +will be returned. +.SH "RETURN VALUE" +.B +ibv_rate_to_mult() +returns the multiplier of the base rate 2.5 Gbit/sec. +.PP +.B mult_to_ibv_rate() +returns the enumeration representing the IB transmission rate. +.SH "SEE ALSO" +.BR ibv_query_port (3) +.SH "AUTHORS" +.TP +Dotan Barak diff --git a/man/ibv_reg_mr.3 b/man/ibv_reg_mr.3 new file mode 100644 index 0000000..bd2387b --- /dev/null +++ b/man/ibv_reg_mr.3 @@ -0,0 +1,77 @@ +.\" -*- nroff -*- +.\" +.TH IBV_REG_MR 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_reg_mr, ibv_dereg_mr \- register or deregister a memory region (MR) +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "struct ibv_mr *ibv_reg_mr(struct ibv_pd " "*pd" ", void " "*addr" , +.BI " size_t " "length" , +.BI " enum ibv_access_flags " "access" ); +.nl +.BI "int ibv_dereg_mr(struct ibv_mr " "*mr" ); +.fi +.SH "DESCRIPTION" +.B ibv_reg_mr() +registers a memory region (MR) associated with the protection domain +.I pd\fR. +The MR's starting address is +.I addr +and its size is +.I length\fR. +The argument +.I access +describes the desired memory protection attributes; it is either 0 or the bitwise OR of one or more of the following flags: +.PP +.TP +.B IBV_ACCESS_LOCAL_WRITE \fR Enable Local Write Access +.TP +.B IBV_ACCESS_REMOTE_WRITE \fR Enable Remote Write Access +.TP +.B IBV_ACCESS_REMOTE_READ\fR Enable Remote Read Access +.TP +.B IBV_ACCESS_REMOTE_ATOMIC\fR Enable Remote Atomic Operation Access (if supported) +.TP +.B IBV_ACCESS_MW_BIND\fR Enable Memory Window Binding +.PP +If +.B IBV_ACCESS_REMOTE_WRITE +or +.B IBV_ACCESS_REMOTE_ATOMIC +is set, then +.B IBV_ACCESS_LOCAL_WRITE +must be set too. +.PP +Local read access is always enabled for the MR. +.PP +.B ibv_dereg_mr() +deregisters the MR +.I mr\fR. +.SH "RETURN VALUE" +.B ibv_reg_mr() +returns a pointer to the registered MR, or NULL if the request fails. +The local key (\fBL_Key\fR) field +.B lkey +is used as the lkey field of struct ibv_sge when posting buffers with +ibv_post_* verbs, and the the remote key (\fBR_Key\fR) +field +.B rkey +is used by remote processes to perform Atomic and RDMA operations. The remote process places this +.B rkey +as the rkey field of struct ibv_send_wr passed to the ibv_post_send function. +.PP +.B ibv_dereg_mr() +returns 0 on success, or the value of errno on failure (which indicates the failure reason). +.SH "NOTES" +.B ibv_dereg_mr() +fails if any memory window is still bound to this MR. +.SH "SEE ALSO" +.BR ibv_alloc_pd (3), +.BR ibv_post_send (3), +.BR ibv_post_recv (3), +.BR ibv_post_srq_recv (3) +.SH "AUTHORS" +.TP +Dotan Barak diff --git a/man/ibv_req_notify_cq.3 b/man/ibv_req_notify_cq.3 new file mode 100644 index 0000000..eda5801 --- /dev/null +++ b/man/ibv_req_notify_cq.3 @@ -0,0 +1,43 @@ +.\" -*- nroff -*- +.\" +.TH IBV_REQ_NOTIFY_CQ 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_req_notify_cq \- request completion notification on a completion queue (CQ) +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "int ibv_req_notify_cq(struct ibv_cq " "*cq" ", int " "solicited_only" "); +.SH "DESCRIPTION" +.B ibv_req_notify_cq() +requests a completion notification on the completion queue (CQ) +.I cq\fR. +.PP +Upon the addition of a new CQ entry (CQE) to +.I cq\fR, +a completion event will be added to the completion channel associated +with the CQ. +If the argument +.I solicited_only +is zero, a completion event is generated for any new CQE. If +.I solicited_only +is non\-zero, an event is only generated for a new CQE with that is +considered "solicited." A CQE is solicited if it is a receive +completion for a message with the Solicited Event header bit set, or +if the status is not successful. All other successful receive +completions, or any successful send completion is unsolicited. +.SH "RETURN VALUE" +.B +ibv_req_notify_cq() +returns 0 on success, or the value of errno on failure (which indicates the failure reason). +.SH "NOTES" +The request for notification is "one shot." Only one completion event +will be generated for each call to +.B ibv_req_notify_cq()\fR. +.SH "SEE ALSO" +.BR ibv_create_comp_channel (3), +.BR ibv_create_cq (3), +.BR ibv_get_cq_event (3) +.SH "AUTHORS" +.TP +Dotan Barak diff --git a/man/ibv_resize_cq.3 b/man/ibv_resize_cq.3 new file mode 100644 index 0000000..0563f56 --- /dev/null +++ b/man/ibv_resize_cq.3 @@ -0,0 +1,42 @@ +.\" -*- nroff -*- +.\" +.TH IBV_RESIZE_CQ 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual" +.SH "NAME" +ibv_resize_cq \- resize a completion queue (CQ) +.SH "SYNOPSIS" +.nf +.B #include +.sp +.BI "int ibv_resize_cq(struct ibv_cq " "*cq" ", int " "cqe" "); +.fi +.SH "DESCRIPTION" +.B ibv_resize_cq() +resizes the completion queue (CQ) +.I cq +to have at least +.I cqe +entries. +.I cqe +must be at least the number of unpolled entries in the CQ +.I cq\fR. +If +.I cqe +is a valid value less than the current CQ size, +.B ibv_resize_cq() +may not do anything, since this function is only guaranteed to resize +the CQ to a size at least as big as the requested size. +.SH "RETURN VALUE" +.B ibv_resize_cq() +returns 0 on success, or the value of errno on failure (which indicates the failure reason). +.SH "NOTES" +.B ibv_resize_cq() +may assign a CQ size greater than or equal to the requested size. +The cqe member of +.I cq +will be updated to the actual size. +.SH "SEE ALSO" +.BR ibv_create_cq (3) +.BR ibv_destroy_cq (3) +.SH "AUTHORS" +.TP +Dotan Barak