78 lines
2.7 KiB
Groff
78 lines
2.7 KiB
Groff
.\" -*- 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 (valid only for UD QPs) */
|
|
int 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 (valid only for UD QPs)
|
|
.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>
|