1IBV_CREATE_CQ_EX(3) Libibverbs Programmer's Manual IBV_CREATE_CQ_EX(3)
2
6 ibv_create_cq_ex - create a completion queue (CQ)
7
9 #include <infiniband/verbs.h>
10 struct ibv_cq_ex *ibv_create_cq_ex(struct ibv_context *context,
12 struct ibv_cq_init_attr_ex *cq_attr);
13
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 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 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 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 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
58 In order to poll an extended CQ efficiently, a user could use the fol‐
59 lowing functions.
60 Completion iterator functions
63 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 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 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 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 uint64_t wr_id - Can be accessed directly from struct ibv_cq_ex.
101 enum ibv_wc_status - Can be accessed directly from struct
103 ibv_cq_ex.
104 enum ibv_wc_opcode ibv_wc_read_opcode(struct ibv_cq_ex *cq); Get
106 the opcode from the current completion.
107 uint32_t ibv_wc_read_vendor_err(struct ibv_cq_ex *cq); Get the
109 vendor error from the current completion.
110 uint32_t ibv_wc_read_byte_len(struct ibv_cq_ex *cq); Get the
112 vendor error from the current completion.
113 __be32 ibv_wc_read_imm_data(struct ibv_cq_ex *cq); Get the imme‐
115 diate data field from the current completion.
116 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 uint32_t ibv_wc_read_qp_num(struct ibv_cq_ex *cq); Get the QP
122 number field from the current completion.
123 uint32_t ibv_wc_read_src_qp(struct ibv_cq_ex *cq); Get the
125 source QP number field from the current completion.
126 int ibv_wc_read_wc_flags(struct ibv_cq_ex *cq); Get the QP flags
128 field from the current completion.
129 uint16_t ibv_wc_read_pkey_index(struct ibv_cq_ex *cq); Get the
131 pkey index field from the current completion.
132 uint32_t ibv_wc_read_slid(struct ibv_cq_ex *cq); Get the slid
134 field from the current completion.
135 uint8_t ibv_wc_read_sl(struct ibv_cq_ex *cq); Get the sl field
137 from the current completion.
138 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 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 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 uint16_t ibv_wc_read_cvlan(struct ibv_cq_ex *cq); Get the CVLAN
151 field from the current completion.
152 uint32_t ibv_wc_read_flow_tag(struct ibv_cq_ex *cq); Get flow
154 tag from the current completion.
155 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
166 ibv_create_cq_ex() returns a pointer to the CQ, or NULL if the request
167 fails.
168
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 CQ should be destroyed with ibv_destroy_cq.
175
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
182 Matan Barak <matanb@mellanox.com>
183libibverbs 2016-05-08 IBV_CREATE_CQ_EX(3)