IBV_CREATE_QP(3)

💖 IBV_CREATE_QP(3) — the libibverbs programmer's manual, but make it make sense 💖

okay bestie, so we're in the libibverbs programmer's manual and today's main character is the queue pair. yes, that queue pair. the QP. the icon, the moment, the whole entire vibe of your RDMA life. two functions, one page, let's go 🦋

---

✨ NAME ✨

ibv_create_qp, ibv_destroy_qp — create or destroy a queue pair (QP)

like… making a QP and un-making a QP. birth and departure. that's the whole thing 🌸

---

✨ SYNOPSIS ✨

#include <infiniband/verbs.h>

struct ibv_qp *ibv_create_qp(struct ibv_pd *pd,
                             struct ibv_qp_init_attr *qp_init_attr);

int ibv_destroy_qp(struct ibv_qp *qp);

---

✨ DESCRIPTION ✨

so ibv_create_qp() creates a queue pair (QP) that's associated with the protection domain pd. the qp_init_attr argument is an ibv_qp_init_attr struct, and it's defined in <infiniband/verbs.h>. slay 💅

struct ibv_qp_init_attr {
        void                   *qp_context;     /* Associated context of the QP */
        struct ibv_cq          *send_cq;        /* CQ to be associated with the Send Queue (SQ) */
        struct ibv_cq          *recv_cq;        /* CQ to be associated with the Receive Queue (RQ) */
        struct ibv_srq         *srq;            /* SRQ handle if QP is to be associated with an SRQ, otherwise NULL */
        struct ibv_qp_cap       cap;            /* QP capabilities */
        enum ibv_qp_type        qp_type;        /* QP Transport Service Type: IBV_QPT_RC, IBV_QPT_UC, IBV_QPT_UD, IBV_QPT_RAW_PACKET or IBV_QPT_DRIVER */
        int                     sq_sig_all;     /* If set, each Work Request (WR) submitted to the SQ generates a completion entry */
};

and inside that there's ibv_qp_cap, the little struct holding all your hopes, dreams, and queue sizes:

struct ibv_qp_cap {
        uint32_t                max_send_wr;    /* Requested max number of outstanding WRs in the SQ */
        uint32_t                max_recv_wr;    /* Requested max number of outstanding WRs in the RQ */
        uint32_t                max_send_sge;   /* Requested max number of scatter/gather (s/g) elements in a WR in the SQ */
        uint32_t                max_recv_sge;   /* Requested max number of s/g elements in a WR in the RQ */
        uint32_t                max_inline_data;/* Requested max number of data (bytes) that can be posted inline to the SQ, otherwise 0 */
};

the way that ibv_create_qp() updates the qp_init_attr->cap struct with the actual QP values of the QP it just created… obsessed. and here's the tea: those values will be greater than or equal to the values you requested. you asked for a snack, the universe gave you a feast 🍓

and then ibv_destroy_qp() destroys the QP qp. goodbye queen, you served 👑

---

✨ RETURN VALUE ✨

ibv_create_qp() returns a pointer to the created QP, or NULL if the request fails. and please, please bestie, check the QP number (qp_num) in the returned QP. do not skip that step, i'm begging 🙈

ibv_destroy_qp() returns 0 on success, or the value of errno on failure (which is basically the universe telling you why it went wrong).

---

✨ NOTES ✨

• ibv_create_qp() will fail if it's asked to create a QP of a type other than IBV_QPT_RC or IBV_QPT_UD associated with an SRQ. so like… don't do that. not the vibe 🚫
• the attributes max_recv_wr and max_recv_sge are ignored by ibv_create_qp() if the QP is going to be associated with an SRQ. they're just standing there, unread, minding their business 💀
• ibv_destroy_qp() fails if the QP is attached to a multicast group. detach first, girl.
• IBV_QPT_DRIVER does not represent a specific service and is used for vendor specific QP logic. it's giving "mystery flavor" iykyk 🧚

---

✨ SEE ALSO ✨

ibv_alloc_pd(3), ibv_modify_qp(3), ibv_query_qp(3)

the friend group 🫶 go read them, they're all part of the same storyline.

---

✨ AUTHORS ✨

Dotan Barak <dotanba@gmail.com> — thank you for your service 🎀

---

and that's the page, bestie! this little bundle of joy came to you from libibverbs, dated 2006-10-31, and it lives its life as IBV_CREATE_QP(3) in the Libibverbs Programmer's Manual. go forth and create (and destroy) responsibly 💜✨