ibv_poll_cq

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() function polls the change queue (CQ) for work completions and returns the first num_entries parameter with completions (or all available completions if the CQ contains less than this number) in the wc array. The wc argument is a pointer to an array of ibv_wc struct that is defined in the <rdma/verbs.h> file.

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 (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) */
};

The wc_flags attribute describes the properties of the work completion. The flag 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 a CQ overrun from occurrence. In a CQ overrun, the asynchronous IBV_EVENT_CQ_ERR event is triggered, and the CQ cannot be used.

Input Parameters

Item	Descriptor
cq	Specifies the `ibv_cq` struct from the ibv_create_cq function.
num_entries	Specifies the maximum number of completion queue entries (CQE) to return.

Output Parameters

Item	Descriptor
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.