struct ibv_srq *ibv_create_srq(struct ibv_pd *pd, struct
                               ibv_srq_init_attr *srq_init_attr);

Description

ibv_create_srq() creates a Shared Receive Queue (SRQ) associated with a Protection Domain.

This SRQ will later be used when calling ibv_create_qp() to indicate that the Receive Queue of that Queue Pair is shared with other Queue Pairs.

If the value of dev_cap.max_srq is zero, this means that the RDMA device doesn't support Shared Receive Queues.

The user can define the minimum attributes to the SRQ: number of Work Requests and number of scatter/gather entries per Work Request. The actual attributes can be equal or higher than those values.

The struct ibv_srq_init_attr describes the requested attributes of the newly created SRQ.

struct ibv_srq_init_attr {
        void                   *srq_context;
        struct ibv_srq_attr     attr;
};

Here is the full description of struct ibv_srq_init_attr:

struct ibv_srq_attr describes the attributes of the Shared Receive Queue.

struct ibv_srq_attr {
        uint32_t                max_wr;
        uint32_t                max_sge;
        uint32_t                srq_limit;
};

Here is the full description of struct ibv_srq_attr:

Parameters

Return Values

Examples

Create an SRQ and destroy it:

struct ibv_pd *pd;
struct ibv_srq *srq;
struct ibv_srq_init_attr srq_init_attr;
 
memset(&srq_init_attr, 0, sizeof(srq_init_attr));
 
srq_init_attr.attr.max_wr  = 1;
srq_init_attr.attr.max_sge = 2;
 
srq = ibv_create_srq(pd, &srq_init_attr);
if (!srq) {
	fprintf(stderr, "Error, ibv_create_srq() failed\n");
	return -1;
}
 
if (ibv_destroy_srq(srq)) {
	fprintf(stderr, "Error, ibv_destroy_srq() failed\n");
	return -1;
}

FAQs

Why is an SRQ good for anyway?

SRQ, as its name states: is a Shared Receive Queue. Using SRQs decreases the total number of posted Receive Requests compared to using Queue Pairs, each with its own Receive Queue.

Can I use one SRQ with different QPs?

Yes. you can.

Can I use one SRQ with QPs with different transport types?

Yes. you can.

How do I use srq_limit?

If an SRQ was armed with a value, when the number of RRs in that SRQ drop below that value, the affiliated asynchronous event IBV_EVENT_SRQ_LIMIT_REACHED will be generated.

Which attributes should be used for an SRQ?

The number of Work Requests should be enough to hold Receive Requests for all of the incoming Messages in all of the QPs that are associated with this SRQ.
The number of scatter/gather elements should be the maximum number of scatter/gather elements in any Work Request that will be posted to this SRQ.

Which value can I use as the srq_context?

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

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