--- name: "ibv_create_cq_ex" section: "3" platform: "linux" package: "rdma-core" version: "65.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux", "freebsd"] url: "https://new.carta.tech/ibv_create_cq_ex" --- # ibv\_create\_cq\_ex(3) create a completion queue (CQ) ## NAME ibv\_create\_cq\_ex - create a completion queue (CQ) ## SYNOPSIS ``` #include struct ibv_cq_ex *ibv_create_cq_ex(struct ibv_context *context, struct ibv_cq_init_attr_ex *cq_attr); ``` ## DESCRIPTION **ibv\_create\_cq\_ex()** creates a completion queue (CQ) for RDMA device context *context.* The argument *cq\_attr* is a pointer to struct ibv\_cq\_init\_attr\_ex as defined in \. ``` struct ibv_cq_init_attr_ex { int cqe; /* Minimum number of entries required for CQ */ void *cq_context; /* Consumer-supplied context returned for completion events */ struct ibv_comp_channel *channel; /* Completion channel where completion events will be queued. May be NULL if completion events will not be used. */ int comp_vector; /* Completion vector used to signal completion events. Must be >= 0 and < context->num_comp_vectors. */ 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. */ uint32_t comp_mask; /* compatibility mask (extended verb). */ uint32_t flags /* One or more flags from enum ibv_create_cq_attr_flags */ struct ibv_pd *parent_domain; /* Parent domain to be used by this CQ */ }; enum ibv_wc_flags_ex { IBV_WC_EX_WITH_BYTE_LEN = 1 << 0, /* Require byte len in WC */ IBV_WC_EX_WITH_IMM = 1 << 1, /* Require immediate in WC */ IBV_WC_EX_WITH_QP_NUM = 1 << 2, /* Require QP number in WC */ IBV_WC_EX_WITH_SRC_QP = 1 << 3, /* Require source QP in WC */ IBV_WC_EX_WITH_SLID = 1 << 4, /* Require slid in WC */ IBV_WC_EX_WITH_SL = 1 << 5, /* Require sl in WC */ IBV_WC_EX_WITH_DLID_PATH_BITS = 1 << 6, /* Require dlid path bits in WC */ IBV_WC_EX_WITH_COMPLETION_TIMESTAMP = 1 << 7, /* Require completion device timestamp in WC /* IBV_WC_EX_WITH_CVLAN = 1 << 8, /* Require VLAN info in WC */ IBV_WC_EX_WITH_FLOW_TAG = 1 << 9, /* Require flow tag in WC */ IBV_WC_EX_WITH_COMPLETION_TIMESTAMP_WALLCLOCK = 1 << 11, /* Require completion wallclock timestamp in WC */ }; enum ibv_cq_init_attr_mask { IBV_CQ_INIT_ATTR_MASK_FLAGS = 1 << 0, IBV_CQ_INIT_ATTR_MASK_PD = 1 << 1, }; enum ibv_create_cq_attr_flags { IBV_CREATE_CQ_ATTR_SINGLE_THREADED = 1 << 0, /* This CQ is used from a single threaded, thus no locking is required */ 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. * An application must be designed to avoid ever overflowing the CQ, otherwise CQEs might be lost. */ }; ``` ## Polling an extended CQ In order to poll an extended CQ efficiently, a user could use the following functions. - **Completion iterator functions** **int ibv\_start\_poll(struct ibv\_cq\_ex** *\*cq***, struct ibv\_poll\_cq\_attr** *\*attr***)**\ Start polling a batch of work completions. *attr* is given in order to make this function easily extensible in the future. This function either returns 0 on success or an error code otherwise. When no completions are available on the CQ, ENOENT is returned, but the CQ remains in a valid state. On success, querying the completion's attribute could be done using the query functions described below. If an error code is given, end\_poll shouldn't be called. When **IBV\_WC\_EX\_WITH\_COMPLETION\_TIMESTAMP\_WALLCLOCK** is requested, EBUSY may be returned transiently if the device clock information cannot be read due to a concurrent kernel update; the CQ remains in a valid state and the application should retry. **int ibv\_next\_poll(struct ibv\_cq\_ex** *\*cq***)**\ This function is called in order to get the next work completion. It has to be called after *start\_poll* and before *end\_poll* are called. This function either returns 0 on success or an error code otherwise. When no completions are available on the CQ, ENOENT is returned, but the CQ remains in a valid state. On success, querying the completion's attribute could be done using the query functions described below. If an error code is given, end\_poll should still be called, indicating this is the end of the polled batch. **void ibv\_end\_poll(struct ibv\_cq\_ex** *\*cq***)**\ This function indicates the end of polling batch of work completions. After calling this function, the user should start a new batch by calling *start\_poll.* - **Polling fields in the completion** Below members and functions are used in order to poll the current completion. The current completion is the completion which the iterator points to (start\_poll and next\_poll advances this iterator). Only fields that the user requested via wc\_flags in ibv\_create\_cq\_ex could be queried. In addition, some fields are only valid in certain opcodes and status codes. **uint64\_t wr\_id - Can be accessed directly from struct ibv\_cq\_ex***.* **enum ibv\_wc\_status - Can be accessed directly from struct ibv\_cq\_ex***.* **enum ibv\_wc\_opcode ibv\_wc\_read\_opcode(struct ibv\_cq\_ex** *\*cq***);**\ Get the opcode from the current completion. **uint32\_t ibv\_wc\_read\_vendor\_err(struct ibv\_cq\_ex** *\*cq***);**\ Get the vendor error from the current completion. **uint32\_t ibv\_wc\_read\_byte\_len(struct ibv\_cq\_ex** *\*cq***);**\ Get the payload length from the current completion. **\_\_be32 ibv\_wc\_read\_imm\_data(struct ibv\_cq\_ex** *\*cq***);**\ Get the immediate data field from the current completion. **uint32\_t ibv\_wc\_read\_invalidated\_rkey(struct ibv\_cq\_ex** *\*cq***);**\ Get the rkey invalided by the SEND\_INVAL from the current completion. **uint32\_t ibv\_wc\_read\_qp\_num(struct ibv\_cq\_ex** *\*cq***);**\ Get the QP number field from the current completion. **uint32\_t ibv\_wc\_read\_src\_qp(struct ibv\_cq\_ex** *\*cq***);**\ Get the source QP number field from the current completion. **unsigned int ibv\_wc\_read\_wc\_flags(struct ibv\_cq\_ex** *\*cq***);**\ Get the QP flags field from the current completion. **uint16\_t ibv\_wc\_read\_pkey\_index(struct ibv\_cq\_ex** *\*cq***);**\ Get the pkey index field from the current completion. **uint32\_t ibv\_wc\_read\_slid(struct ibv\_cq\_ex** *\*cq***);**\ Get the slid field from the current completion. **uint8\_t ibv\_wc\_read\_sl(struct ibv\_cq\_ex** *\*cq***);**\ Get the sl field from the current completion. **uint8\_t ibv\_wc\_read\_dlid\_path\_bits(struct ibv\_cq\_ex** *\*cq***);**\ Get the dlid\_path\_bits field from the current completion. **uint64\_t ibv\_wc\_read\_completion\_ts(struct ibv\_cq\_ex** *\*cq***);**\ Get the completion timestamp from the current completion in HCA clock units. **uint64\_t ibv\_wc\_read\_completion\_wallclock\_ns(struct ibv\_cq\_ex** *\*cq***);** Get the completion timestamp from the current completion and convert it from HCA clock units to wall clock nanoseconds. **uint16\_t ibv\_wc\_read\_cvlan(struct ibv\_cq\_ex** *\*cq***);**\ Get the CVLAN field from the current completion. **uint32\_t ibv\_wc\_read\_flow\_tag(struct ibv\_cq\_ex** *\*cq***);**\ Get flow tag from the current completion. **void ibv\_wc\_read\_tm\_info(struct ibv\_cq\_ex** *\*cq***,** **struct ibv\_wc\_tm\_info** *\*tm\_info***);** \ Get tag matching info from the current completion. ``` struct ibv_wc_tm_info { uint64_t tag; /* tag from TMH */ uint32_t priv; /* opaque user data from TMH */ }; ``` ## RETURN VALUE **ibv\_create\_cq\_ex()** returns a pointer to the CQ, or NULL if the request fails, and errno is set to indicate the reason. ## NOTES **ibv\_create\_cq\_ex()** may create a CQ with size greater than or equal to the requested size. Check the cqe attribute in the returned CQ for the actual size. CQ should be destroyed with ibv\_destroy\_cq. ## SEE ALSO [**ibv\_create\_cq**(3)](/ibv_create_cq/3.md), [**ibv\_destroy\_cq**(3)](/ibv_destroy_cq/3.md), [**ibv\_resize\_cq**(3)](/ibv_resize_cq/3.md), [**ibv\_req\_notify\_cq**(3)](/ibv_req_notify_cq/3.md), [**ibv\_ack\_cq\_events**(3)](/ibv_ack_cq_events/3.md), [**ibv\_create\_qp**(3)](/ibv_create_qp/3.md), [**ibv\_alloc\_parent\_domain**(3)](/ibv_alloc_parent_domain/3.md) ## AUTHORS - Matan Barak \