| .\" -*- 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 |
| .TP |
| .B IBV_WC_IP_CSUM_OK \fR TCP/UDP checksum over IPv4 and IPv4 header checksum are |
| verified. |
| Valid only when \fBdevice_cap_flags\fR in device_attr indicates current QP is |
| supported by checksum offload. |
| .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 <dotanba@gmail.com> |
