contrib/ofed/libibverbs/man/ibv_poll_cq.3

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