struct ibv_cq *ibv_create_cq(struct ibv_context *context, int cqe,
                             void *cq_context,
                             struct ibv_comp_channel *channel,
                             int comp_vector);

Description

ibv_create_cq() creates a Completion Queue (CQ) for an RDMA device context.

When an outstanding Work Request, within a Send or Receive Queue, is completed, a Work Completion is being added to the CQ of that Work Queue. This Work Completion indicates that the outstanding Work Request has been completed (and no longer considered outstanding) and provides details on it (status, direction, opcode, etc.).

A single CQ can be shared for sending, receiving, and sharing across multiple QPs. The Work Completion holds the information to specify the QP number and the Queue (Send or Receive) that it came from.

The user can define the minimum size of the CQ. The actual created size can be equal or higher than this value.

Parameters

Return Values

Examples

1. Create a CQ with 100 entries and destroy it:

struct ibv_cq *cq;
 
cq = ibv_create_cq(context, 100, NULL, NULL, 0);
if (!cq) {
	fprintf(stderr, "Error, ibv_create_cq() failed\n");
	return -1;
}
 
if (ibv_destroy_cq(cq)) {
	fprintf(stderr, "Error, ibv_destroy_cq() failed\n");
	return -1;
}

2. Create a CQ with 100 entries associated with a Completion event channel:
(in this example we assume that the Completion event channel was already created before):

struct ibv_cq *cq;
struct ibv_comp_channel *channel;
 
cq = ibv_create_cq(context, 100, NULL, channel, 0);
if (!cq) {
	fprintf(stderr, "Error, ibv_create_cq() failed\n");
	return -1;
}

FAQs

Why is a CQ good for anyway?

CQ is used to hold Work Completion for any Work Request, that was completed and should produce a Work Completion, and provides details on it.

Can I use different CQs for Send/Receive Queues in the same QP?

Yes. In any QP the CQ of the Send Queue and the CQ of the Receive Queue may be the same or may be different. This is flexible and up to the user to decide.

Can several QPs be associated with the same CQ?

Yes. Several QPs can be associated with the same CQ in they Send or Receive Queues or in both of them.

What should be the CQ size?

A CQ should have enough room to hold all of Work Completions of the Outstanding Work Requests of the Queues that are associated with that CQ, so the CQ size shouldn't be less than the total number of Work Request that may be outstanding.

What will happen if the CQ size that I choose is too small??

If there will be a case that the CQ will be full and a new Work Completion is going to be added to that CQ, there will be a CQ overrun. A Completion with error will be added to the CQ and an asynchronous event IBV_EVENT_CQ_ERR will be generated.

Which value can I use as the cq_context?

Since the cq_context is a void *, you can put any value that you wish.

Written by: Dotan Barak on November 3, 2012.on January 31, 2014.