1IBV_CREATE_CQ_EX(3)     Libibverbs Programmer's Manual     IBV_CREATE_CQ_EX(3)
2
3
4

NAME

6       ibv_create_cq_ex - create a completion queue (CQ)
7

SYNOPSIS

9       #include <infiniband/verbs.h>
10
11       struct ibv_cq_ex *ibv_create_cq_ex(struct ibv_context *context,
12                                          struct ibv_cq_init_attr_ex *cq_attr);
13

DESCRIPTION

15       ibv_create_cq_ex() creates a completion queue (CQ) for RDMA device con‐
16       text  context.   The  argument  cq_attr  is   a   pointer   to   struct
17       ibv_cq_init_attr_ex as defined in <infiniband/verbs.h>.
18
19       struct ibv_cq_init_attr_ex {
20               int                     cqe;               /* Minimum number of entries required for CQ */
21               void                    *cq_context;       /* Consumer-supplied context returned for completion events */
22               struct ibv_comp_channel *channel;          /* Completion channel where completion events will be queued. May be NULL if completion events will not be used. */
23               int                     comp_vector;       /* Completion vector used to signal completion events. Must be >= 0 and < context->num_comp_vectors. */
24               uint64_t                wc_flags;          /* The wc_flags that should be returned in ibv_poll_cq_ex. Or'ed bit of enum ibv_wc_flags_ex. */
25               uint32_t                comp_mask;         /* compatibility mask (extended verb). */
26               uint32_t                flags              /* One or more flags from enum ibv_create_cq_attr_flags */
27               struct ibv_pd           *parent_domain;    /* Parent domain to be used by this CQ */
28       };
29
30       enum ibv_wc_flags_ex {
31               IBV_WC_EX_WITH_BYTE_LEN              = 1 << 0,  /* Require byte len in WC */
32               IBV_WC_EX_WITH_IMM                   = 1 << 1,  /* Require immediate in WC */
33               IBV_WC_EX_WITH_QP_NUM                = 1 << 2,  /* Require QP number in WC */
34               IBV_WC_EX_WITH_SRC_QP                = 1 << 3,  /* Require source QP in WC */
35               IBV_WC_EX_WITH_SLID                  = 1 << 4,  /* Require slid in WC */
36               IBV_WC_EX_WITH_SL                    = 1 << 5,  /* Require sl in WC */
37               IBV_WC_EX_WITH_DLID_PATH_BITS        = 1 << 6,  /* Require dlid path bits in WC */
38               IBV_WC_EX_WITH_COMPLETION_TIMESTAMP  = 1 << 7,  /* Require completion device timestamp in WC /*
39               IBV_WC_EX_WITH_CVLAN                 = 1 << 8,  /* Require VLAN info in WC */
40               IBV_WC_EX_WITH_FLOW_TAG              = 1 << 9,  /* Require flow tag in WC */
41               IBV_WC_EX_WITH_COMPLETION_TIMESTAMP_WALLCLOCK  = 1 << 11, /* Require completion wallclock timestamp in WC */
42       };
43
44       enum ibv_cq_init_attr_mask {
45               IBV_CQ_INIT_ATTR_MASK_FLAGS             = 1 << 0,
46               IBV_CQ_INIT_ATTR_MASK_PD                = 1 << 1,
47       };
48
49       enum ibv_create_cq_attr_flags {
50               IBV_CREATE_CQ_ATTR_SINGLE_THREADED      = 1 << 0, /* This CQ is used from a single threaded, thus no locking is required */
51               IBV_CREATE_CQ_ATTR_IGNORE_OVERRUN       = 1 << 1, /* This CQ will not pass to error state if overrun, CQE always will be written to next entry.
52                                                                  * An application must be designed to avoid ever overflowing the CQ, otherwise CQEs might be lost.
53                                                                  */
54       };
55
56

Polling an extended CQ

58       In  order to poll an extended CQ efficiently, a user could use the fol‐
59       lowing functions.
60
61
62       Completion iterator functions
63
64              int ibv_start_poll(struct ibv_cq_ex *cq, struct ibv_poll_cq_attr
65              *attr)
66              Start  polling  a  batch  of work completions.  attr is given in
67              order to make this function easily  extensible  in  the  future.
68              This  function either returns 0 on success or an error code oth‐
69              erwise. When no completions are available on the CQ,  ENOENT  is
70              returned,  but  the  CQ  remains  in  a valid state. On success,
71              querying the completion's attribute  could  be  done  using  the
72              query  functions  described  below.  If  an error code is given,
73              end_poll shouldn't be called.
74
75              int ibv_next_poll(struct ibv_cq_ex *cq)
76              This function is called in order to get the  next  work  comple‐
77              tion.  It  has to be called after start_poll and before end_poll
78              are called. This function either returns  0  on  success  or  an
79              error  code  otherwise. When no completions are available on the
80              CQ, ENOENT is returned, but the CQ remains in a valid state.  On
81              success, querying the completion's attribute could be done using
82              the query functions described below. If an error code is  given,
83              end_poll  should  still be called, indicating this is the end of
84              the polled batch.
85
86              void ibv_end_poll(struct ibv_cq_ex *cq)
87              This function indicates the end of polling batch of work comple‐
88              tions.  After calling this function, the user should start a new
89              batch by calling start_poll.
90
91
92       Polling fields in the completion
93              Below members and functions are used in order to poll  the  cur‐
94              rent  completion. The current completion is the completion which
95              the iterator points to (start_poll and next_poll  advances  this
96              iterator).  Only  fields that the user requested via wc_flags in
97              ibv_create_cq_ex could be queried. In addition, some fields  are
98              only valid in certain opcodes and status codes.
99
100              uint64_t wr_id - Can be accessed directly from struct ibv_cq_ex.
101
102              enum  ibv_wc_status  -  Can  be  accessed  directly  from struct
103              ibv_cq_ex.
104
105              enum ibv_wc_opcode ibv_wc_read_opcode(struct ibv_cq_ex *cq); Get
106              the opcode from the current completion.
107
108              uint32_t  ibv_wc_read_vendor_err(struct  ibv_cq_ex *cq); Get the
109              vendor error from the current completion.
110
111              uint32_t ibv_wc_read_byte_len(struct  ibv_cq_ex  *cq);  Get  the
112              vendor error from the current completion.
113
114              __be32 ibv_wc_read_imm_data(struct ibv_cq_ex *cq); Get the imme‐
115              diate data field from the current completion.
116
117              uint32_t ibv_wc_read_invalidated_rkey(struct ibv_cq_ex *cq); Get
118              the  rkey  invalided  by the SEND_INVAL from the current comple‐
119              tion.
120
121              uint32_t ibv_wc_read_qp_num(struct ibv_cq_ex *cq);  Get  the  QP
122              number field from the current completion.
123
124              uint32_t   ibv_wc_read_src_qp(struct  ibv_cq_ex  *cq);  Get  the
125              source QP number field from the current completion.
126
127              int ibv_wc_read_wc_flags(struct ibv_cq_ex *cq); Get the QP flags
128              field from the current completion.
129
130              uint16_t  ibv_wc_read_pkey_index(struct  ibv_cq_ex *cq); Get the
131              pkey index field from the current completion.
132
133              uint32_t ibv_wc_read_slid(struct ibv_cq_ex *cq);  Get  the  slid
134              field from the current completion.
135
136              uint8_t  ibv_wc_read_sl(struct  ibv_cq_ex *cq); Get the sl field
137              from the current completion.
138
139              uint8_t ibv_wc_read_dlid_path_bits(struct  ibv_cq_ex  *cq);  Get
140              the dlid_path_bits field from the current completion.
141
142              uint64_t  ibv_wc_read_completion_ts(struct  ibv_cq_ex  *cq); Get
143              the completion timestamp from  the  current  completion  in  HCA
144              clock units.
145
146              uint64_t   ibv_wc_read_completion_wallclock_ns(struct  ibv_cq_ex
147              *cq); Get the completion timestamp from the  current  completion
148              and convert it from HCA clock units to wall clock nanoseconds.
149
150              uint16_t  ibv_wc_read_cvlan(struct ibv_cq_ex *cq); Get the CVLAN
151              field from the current completion.
152
153              uint32_t ibv_wc_read_flow_tag(struct ibv_cq_ex  *cq);  Get  flow
154              tag from the current completion.
155
156              void    ibv_wc_read_tm_info(struct    ibv_cq_ex    *cq,   struct
157              ibv_wc_tm_info *tm_info);  Get tag matching info from  the  cur‐
158              rent completion.
159              struct ibv_wc_tm_info {
160                      uint64_t tag;  /* tag from TMH */
161                      uint32_t priv; /* opaque user data from TMH */
162              };
163
164

RETURN VALUE

166       ibv_create_cq_ex()  returns a pointer to the CQ, or NULL if the request
167       fails.
168

NOTES

170       ibv_create_cq_ex() may create a CQ with size greater than or  equal  to
171       the  requested size. Check the cqe attribute in the returned CQ for the
172       actual size.
173
174       CQ should be destroyed with ibv_destroy_cq.
175

SEE ALSO

177       ibv_create_cq(3),         ibv_destroy_cq(3),          ibv_resize_cq(3),
178       ibv_req_notify_cq(3),      ibv_ack_cq_events(3),      ibv_create_qp(3),
179       ibv_alloc_parent_domain(3)
180

AUTHORS

182       Matan Barak <matanb@mellanox.com>
183
184
185
186libibverbs                        2016-05-08               IBV_CREATE_CQ_EX(3)
Impressum