IBV_CREATE_WQ(3)

💖 ibv_create_wq(3) — the Libibverbs Programmer's Manual era 💖

okay bestie, so this one lives in the Libibverbs Programmer's Manual and it's literally the manual page for ibv_create_wq and ibv_destroy_wq. two functions. one page. main character energy fr fr. 🎀

✨ NAME ✨

ibv_create_wq, ibv_destroy_wq — create or destroy a Work Queue (WQ).

like… you can make a WQ and you can un-make a WQ. that's the whole vibe. 🦋

✨ SYNOPSIS ✨

#include <infiniband/verbs.h>

struct ibv_wq *ibv_create_wq(struct ibv_context *context,
                                     struct ibv_wq_init_attr *wq_init_attr);

int ibv_destroy_wq(struct ibv_wq *wq);

see how one of them gives you back a pointer and the other one just gives you an int? 💅 that's the whole personality of this pair ngl.

✨ DESCRIPTION ✨

ibv_create_wq() creates a WQ that's associated with the ibv_context context. 🫶

the wq_init_attr argument is an ibv_wq_init_attr struct, and it's defined in <infiniband/verbs.h> — so yes, that's where you go looking for it, don't @ me.

struct ibv_wq_init_attr {
        void                      *wq_context;    /* Associated context of the WQ */
        enum ibv_wq_type           wq_type;       /* WQ type */
        uint32_t                   max_wr;        /* Requested max number of outstanding WRs in the WQ */
        uint32_t                   max_sge;       /* Requested max number of scatter/gather (s/g) elements per WR in the WQ */
        struct  ibv_pd            *pd;            /* PD to be associated with the WQ */
        struct  ibv_cq            *cq;            /* CQ to be associated with the WQ */
        uint32_t                   comp_mask;     /* Identifies valid fields. Use ibv_wq_init_attr_mask */
        uint32_t                   create_flags    /* Creation flags for this WQ, use enum ibv_wq_flags */
};

okay so field by field, no skipping, we go through ALL of them:

• wq_context — the associated context of the WQ.
• wq_type — the WQ type, bestie. it's an enum ibv_wq_type.
• max_wr — the requested max number of outstanding WRs in the WQ.
• max_sge — the requested max number of scatter/gather (s/g) elements per WR in the WQ.
• pd — the PD to be associated with the WQ. (struct ibv_pd *)
• cq — the CQ to be associated with the WQ. (struct ibv_cq *)
• comp_mask — identifies valid fields. use ibv_wq_init_attr_mask.
• create_flags — creation flags for this WQ, use enum ibv_wq_flags.

and then the flags enum, which is where it gets spicy 🌶️:

enum ibv_wq_flags {
        IBV_WQ_FLAGS_CVLAN_STRIPPING            = 1 << 0, /* CVLAN field will be stripped from incoming packets */
        IBV_WQ_FLAGS_SCATTER_FCS                = 1 << 1, /* FCS field will be scattered to host memory */
        IBV_WQ_FLAGS_DELAY_DROP                 = 1 << 2, /* Packets won't be dropped immediately if no receive WQEs */
        IBV_WQ_FLAGS_PCI_WRITE_END_PADDING      = 1 << 3, /* Incoming packets will be padded to cacheline size */
        IBV_WQ_FLAGS_RESERVED                   = 1 << 4,
};

breaking those down because we're thorough in this group chat:

• IBV_WQ_FLAGS_CVLAN_STRIPPING — 1 << 0, the CVLAN field will be stripped from incoming packets. 🧹
• IBV_WQ_FLAGS_SCATTER_FCS — 1 << 1, the FCS field will be scattered to host memory.
• IBV_WQ_FLAGS_DELAY_DROP — 1 << 2, packets won't be dropped immediately if no receive WQEs. the packets are getting a lil grace period, periodt. ⏳
• IBV_WQ_FLAGS_PCI_WRITE_END_PADDING — 1 << 3, incoming packets will be padded to cacheline size.
• IBV_WQ_FLAGS_RESERVED — 1 << 4. reserved. that's it. that's the whole note. 🙈

the plot twist tho: the function ibv_create_wq() will update the wq_init_attr->max_wr and wq_init_attr->max_sge fields with the actual WQ values of the WQ that was created — and those values will be greater than or equal to the values you requested. so it's not ignoring you, it's just doing ✨more✨ than you asked. icon behaviour honestly. 👑

and then ibv_destroy_wq() destroys the WQ wq. bye bestie 💀 (affectionate).

✨ RETURN VALUE ✨

• ibv_create_wq() returns a pointer to the created WQ, or NULL if the request fails. 😭
• ibv_destroy_wq() returns 0 on success, or the value of errno on failure (which indicates the failure reason).

so like, if you get NULL back, that's your vibe check failing. check errno on the destroy side, that's where the tea is. 🍵

✨ SEE ALSO ✨

ibv_modify_wq(3)

(yes that's the one — go read it next, iykyk 🌸)

✨ AUTHORS ✨

Yishai Hadas <yishaih@mellanox.com> 💜

lowkey reminder bestie: keep every field, flag and value exactly as written when you actually use this stuff. the vibes are mine, the API is not. 💅

and that's the whole page, slay 🌈 — this was libibverbs, dated 2016-07-27, signing off 🎀✨💖