Add the rest of the manpages for libibverbs functions in section 3.
These manpages were written by Dotan Barak <dotanb@mellanox.co.il>.
Signed-off-by: Roland Dreier <rolandd@cisco.com>
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 \
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
+
-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
--- /dev/null
+.\" -*- 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 <infiniband/verbs.h>
+.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 <dotanb@mellanox.co.il>
--- /dev/null
+.\" -*- 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 <infiniband/verbs.h>
+.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 <dotanb@mellanox.co.il>
--- /dev/null
+.\" -*- 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 <infiniband/verbs.h>
+.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 <infiniband/verbs.h>.
+.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 <dotanb@mellanox.co.il>
--- /dev/null
+.\" -*- 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 <infiniband/verbs.h>
+.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 <dotanb@mellanox.co.il>
--- /dev/null
+.\" -*- 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 <infiniband/verbs.h>
+.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 <dotanb@mellanox.co.il>
--- /dev/null
+.\" -*- 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 <infiniband/verbs.h>
+.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 <dotanb@mellanox.co.il>
--- /dev/null
+.\" -*- 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 <infiniband/verbs.h>
+.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 <infiniband/verbs.h>.
+.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 <dotanb@mellanox.co.il>
--- /dev/null
+.\" -*- 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 <infiniband/verbs.h>
+.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 <infiniband/verbs.h>.
+.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 <dotanb@mellanox.co.il>
--- /dev/null
+.\" -*- 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 <infiniband/verbs.h>
+.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 <infiniband/verbs.h>.
+.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 <dotanb@mellanox.co.il>
--- /dev/null
+.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 <infiniband/verbs.h>
+.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 >
--- /dev/null
+.\" -*- 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 <infiniband/verbs.h>
+.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 <infiniband/verbs.h>.
+.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 <dotanb@mellanox.co.il>
--- /dev/null
+.\" -*- 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 <infiniband/verbs.h>
+.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 <infiniband/verbs.h>.
+.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 <dotanb@mellanox.co.il>
--- /dev/null
+.\" -*- 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 <infiniband/verbs.h>
+.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 <infiniband/verbs.h>.
+.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 <dotanb@mellanox.co.il>
--- /dev/null
+.\" -*- 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 <infiniband/verbs.h>
+.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 <infiniband/verbs.h>.
+.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 <dotanb@mellanox.co.il>
--- /dev/null
+.\" -*- 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 <infiniband/verbs.h>
+.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 <infiniband/verbs.h>.
+.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 <dotanb@mellanox.co.il>
--- /dev/null
+.\" -*- 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 <infiniband/verbs.h>
+.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 <infiniband/verbs.h>.
+.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 <dotanb@mellanox.co.il>
--- /dev/null
+.\" -*- 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 <infiniband/verbs.h>
+.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 <infiniband/verbs.h>.
+.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 <dotanb@mellanox.co.il>
--- /dev/null
+.\" -*- 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 <infiniband/verbs.h>
+.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 <dotanb@mellanox.co.il>
--- /dev/null
+.\" -*- 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 <infiniband/verbs.h>
+.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 <dotanb@mellanox.co.il>
--- /dev/null
+.\" -*- 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 <infiniband/verbs.h>
+.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 <infiniband/verbs.h>.
+.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 <dotanb@mellanox.co.il>
--- /dev/null
+.\" -*- 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 <infiniband/verbs.h>
+.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 <infiniband/verbs.h>.
+.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 <dotanb@mellanox.co.il>
--- /dev/null
+.\" -*- 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 <infiniband/verbs.h>
+.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 <infiniband/verbs.h>.
+.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 <dotanb@mellanox.co.il>
--- /dev/null
+.\" -*- 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 <infiniband/verbs.h>
+.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 <dotanb@mellanox.co.il>
--- /dev/null
+.\" -*- 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 <infiniband/verbs.h>
+.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 <dotanb@mellanox.co.il>
--- /dev/null
+.\" -*- 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 <infiniband/verbs.h>
+.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 <dotanb@mellanox.co.il>
--- /dev/null
+.\" -*- 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 <infiniband/verbs.h>
+.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 <dotanb@mellanox.co.il>
projects / ~shefty / libibverbs.git / commitdiff