Polls a completion queue (CQ).
Syntax
#include <rdma/verbs.h>
int ibv_poll_cq(struct ibv_cq *cq, int num_entries, struct ibv_wc *wc)
Description
The
ibv_poll_cq() routine
polls the CQ
cq for work completions and returns the first
num_entries (or
all available completions if the CQ contains fewer than this number)
in the array
wc. The argument
wc is a pointer to an
array of ibv_wc structs, as defined in <rdma/verbs.h>.
struct ibv_wc {
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) */
};
enum ibv_wc_flags wc_flags; /* Flags of the completed WR */
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:
- IBV_WC_GRH
- GRH is present.
- IBV_WC_WITH_IMM
- Immediate data value is valid.
Not all
wc attributes are always valid. If the
completion status is other than IBV_WC_SUCCESS, only the
wr_id,
status,
qp_num,
and
vendor_err attributes are valid.
Note: Each polled completion
is removed from the CQ and cannot be returned to it. You must consume
work completions at a rate that prevents CQ overrun from occurrence.
In case of a CQ overrun, the async event IBV_EVENT_CQ_ERR is
triggered, and the CQ cannot be used.
Input Parameters
cq |
Specifies the struct ibv_cq from ibv_create_cq. |
num_entries |
Specifies the maximum number of completion queue
entries (CQE) to return. |
Output Parameters
wc |
Specifies the CQE array. |
Return Values
On success, the ibv_poll_cq() function
returns a non negative value equal to the number of completions found.
On failure, a negative value is returned.
-EINVAL |
Error, if cq, or cq->context is NULL. |