contrib/ofed/libibverbs/man/ibv_poll_cq.3

   1 .\" -*- nroff -*-
   2 .\" Licensed under the OpenIB.org BSD license (FreeBSD Variant) - See COPYING.md
   3 .\"
   4 .TH IBV_POLL_CQ 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual"
   5 .SH "NAME"
   6 ibv_poll_cq \- poll a completion queue (CQ)
   7 .SH "SYNOPSIS"
   8 .nf
   9 .B #include <infiniband/verbs.h>
  10 .sp
  11 .BI "int ibv_poll_cq(struct ibv_cq " "*cq" ", int " "num_entries" ,
  12 .BI "                struct ibv_wc " "*wc" );
  13 .fi
  14 .SH "DESCRIPTION"
  15 .B ibv_poll_cq()
  16 polls the CQ
  17 .I cq
  18 for work completions and returns the first
  19 .I num_entries
  20 (or all available completions if the CQ contains fewer than this number) in the array
  21 .I wc\fR.
  22 The argument
  23 .I wc
  24 is a pointer to an array of ibv_wc structs, as defined in <infiniband/verbs.h>.
  25 .PP
  26 .nf
  27 struct ibv_wc {
  28 .in +8
  29 uint64_t                wr_id;          /* ID of the completed Work Request (WR) */
  30 enum ibv_wc_status      status;         /* Status of the operation */
  31 enum ibv_wc_opcode      opcode;         /* Operation type specified in the completed WR */
  32 uint32_t                vendor_err;     /* Vendor error syndrome */
  33 uint32_t                byte_len;       /* Number of bytes transferred */
  34 union {
  35 .in +8
  36 __be32                  imm_data;         /* Immediate data (in network byte order) */
  37 uint32_t                invalidated_rkey; /* Local RKey that was invalidated */
  38 .in -8
  39 };
  40 uint32_t                qp_num;         /* Local QP number of completed WR */
  41 uint32_t                src_qp;         /* Source QP number (remote QP number) of completed WR (valid only for UD QPs) */
  42 int                     wc_flags;       /* Flags of the completed WR */
  43 uint16_t                pkey_index;     /* P_Key index (valid only for GSI QPs) */
  44 uint16_t                slid;           /* Source LID */
  45 uint8_t                 sl;             /* Service Level */
  46 uint8_t                 dlid_path_bits; /* DLID path bits (not applicable for multicast messages) */
  47 .in -8
  48 };
  49 .sp
  50 .fi
  51 .PP
  52 The attribute wc_flags describes the properties of the work completion.
  53 It is either 0 or the bitwise OR of one or more of the following flags:
  54 .PP
  55 .TP
  56 .B IBV_WC_GRH \fR      GRH is present (valid only for UD QPs)
  57 .TP
  58 .B IBV_WC_WITH_IMM \fR Immediate data value is valid
  59 .TP
  60 .B IBV_WC_WITH_INV \fR Invalidated RKey data value is valid (cannot be combined with IBV_WC_WITH_IMM)
  61 .TP
  62 .B IBV_WC_IP_CSUM_OK \fR TCP/UDP checksum over IPv4 and IPv4 header checksum are
  63 verified.
  64 Valid only when \fBdevice_cap_flags\fR in device_attr indicates current QP is
  65 supported by checksum offload.
  66 .PP
  67 Not all
  68 .I wc
  69 attributes are always valid. If the completion status is other than
  70 .B IBV_WC_SUCCESS\fR,
  71 only the following attributes are valid: wr_id, status, qp_num, and vendor_err.
  72 .SH "RETURN VALUE"
  73 On success,
  74 .B ibv_poll_cq()
  75 returns a non-negative value equal to the number of completions
  76 found.  On failure, a negative value is returned.
  77 .SH "NOTES"
  78 .PP
  79 Each polled completion is removed from the CQ and cannot be returned to it.
  80 .PP
  81 The user should consume work completions at a rate that prevents CQ
  82 overrun from occurrence.  In case of a CQ overrun, the async event
  83 .B IBV_EVENT_CQ_ERR
  84 will be triggered, and the CQ cannot be used.
  85 .SH "SEE ALSO"
  86 .BR ibv_post_send (3),
  87 .BR ibv_post_recv (3)
  88 .SH "AUTHORS"
  89 .TP
  90 Dotan Barak <dotanba@gmail.com>