ibv_poll

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.