IBV_POST_SRQ_OPS(3)

💖 IBV_POST_SRQ_OPS 💖

okay bestie, so this is a page from the Libibverbs Programmer's Manual — IBV_POST_SRQ_OPS(3) — and it's genuinely so much cooler than the name makes it sound, i promise. grab a snack, we're doing tag matching SRQ config today. 🎀

✨ NAME ✨

ibv_post_srq_ops — do a lil series of configuration manipulations on a special shared receive queue (SRQ). yes, special. main character SRQ. 👑

🌸 SYNOPSIS 🌸

#include <infiniband/verbs.h>

int ibv_post_srq_ops(struct ibv_srq *srq, struct ibv_ops_wr *wr,
                     struct ibv_ops_wr **bad_wr);

🦋 DESCRIPTION 🦋

so ibv_post_srq_ops() performs a whole series of offload configuration manipulations on special types of SRQ, and that SRQ is srq. right now it's used to configure a tag matching SRQ. the series of configuration operations is defined by a linked list of struct ibv_ops_wr elements, starting from wr. it's giving... linked list energy. 🔗

struct ibv_ops_wr {
        uint64_t                wr_id;   /* User defined WR ID */
        /* Pointer to next WR in list, NULL if last WR */
        struct ibv_ops_wr      *next;
        enum ibv_ops_wr_opcode  opcode;  /* From enum ibv_ops_wr_opcode */
        int                     flags;   /* From enum ibv_ops_flags */
        struct {
                /* Number of unexpected messages
                 * handled by SW */
                uint32_t unexpected_cnt;
                /* Input parameter for the DEL opcode
                 * and output parameter for the ADD opcode */
                uint32_t handle;
                struct {
                        uint64_t                recv_wr_id;   /* User defined WR ID for TM_RECV */
                        struct ibv_sge         *sg_list; /* Pointer to the s/g array */
                        int                     num_sge; /* Size of the s/g array */
                        uint64_t                tag;
                        uint64_t                mask;    /* Incoming message considered matching if
                                                            TMH.tag & entry.mask == entry.tag */
                } add;
        } tm;
};

the first part of struct ibv_ops_wr keeps that classic ibv_send_wr notion, okay? opcode defines the operation to perform. currently supported values are IBV_WR_TAG_ADD, IBV_WR_TAG_DEL and IBV_WR_TAG_SYNC. detailed description is right below, don't worry bestie. 💅

to allow reliable data delivery, the TM SRQ maintains a special low level synchronization primitive — phase synchronization. receive side message handling is literally two concurrent activities: posting tagged buffers by SW, and receiving incoming messages by HW. this process is considered coherent only if all unexpected messages received by HW are completely processed in SW. to pass the number of processed unexpected messages to hardware, use the unexpected_cnt field and set the IBV_OPS_TM_SYNC flag. 🫶

to request a WC for tag list operations, pass the IBV_OPS_SIGNALED flags. in that case a WC will be generated on the TM SRQ's CQ, and the provided wr_id will identify that WC. ✨

opcode IBV_WR_TAG_ADD is used to add a tag entry to the tag matching list. a tag entry consists of:

• the SGE list
• tag & mask (the matching parameters)
• a user specified opaque wr_id (passed via the recv_wr_id field)
• and it's uniquely identified by handle (returned by the driver)

the size of the tag matching list is limited by max_num_tags, and the SGE list size is limited by max_sge. no cap. 😌

opcode IBV_WR_TAG_DEL removes a previously added tag entry. the handle field should be set to the value returned by a previously performed IBV_WR_TAG_ADD operation. heads up though: the operation may fail due to concurrent tag consumption — in that case IBV_WC_TM_ERR status will be returned in the WC. 😭

opcode IBV_WR_TAG_SYNC may be used if no changes to the matching list are required, just to update the unexpected messages counter. lowkey the chill one. 🌈

the IBV_WC_TM_SYNC_REQ flag returned in a list operation WC shows that counter synchronization is required. this flag may also be returned by an unexpected receive WC, asking for an IBV_WR_TAG_SYNC operation to keep TM coherence consistency. 🔥

⭐ RETURN VALUE ⭐

ibv_post_srq_ops() returns 0 on success, or the value of errno on failure (which indicates the failure reason). so if it's not zero, that's the universe telling you why. 🙈

💜 SEE ALSO 💜

• ibv_create_srq_ex(3),

🎀 AUTHORS 🎀

• Artemy Kovalyov <artemyko@mellanox.com>

and that's the whole page bestie, you ate that fr fr 💅✨ this was libibverbs, dated 2017-03-26 — iconic behavior honestly, go forth and post those SRQ ops 🦋🌸