MLX5DV_INIT_OBJ(3)

💖 MLX5DV_INIT_OBJ(3) 💖

okay bestie, so this one is mlx5dv_init_obj — it lives in the Library Functions Manual, and it's the little function that hands you all the raw, unfiltered direct-verbs tea about your hardware objects. let's get into it 🫶

---

✨ NAME ✨

mlx5dv_init_obj — Initialize mlx5 direct verbs object from ibv_xxx or mlx5dv_xxx structures

like, it takes your normal boring verbs struct and gives you back the juicy direct-verbs one. it's giving glow-up. 💅

---

🌸 SYNOPSIS 🌸

#include <infiniband/mlx5dv.h>

int mlx5dv_init_obj(struct mlx5dv_obj *obj, uint64_t obj_type);

---

🦋 DESCRIPTION 🦋

mlx5dv_init_obj() — this function will initialize mlx5dv_xxx structs based on supplied type. The information for initialization is taken from ibv_xx or mlx5dv_xxx structs supplied as part of input.

Request information of CQ marks its owned by direct verbs for all consumer index related actions. The initialization type can be combination of several types together.

bestie, that last bit is lowkey the whole point: you can OR together several types in one call and get a whole bundle of structs filled in. iconic behavior, no cap. 🔥

and now, the structs. all of them. every field. i would never gatekeep:

struct mlx5dv_qp {
        uint32_t                *dbrec;
        struct {
                void            *buf;
                uint32_t        wqe_cnt;
                uint32_t        stride;
        } sq;
        struct {
                void            *buf;
                uint32_t        wqe_cnt;
                uint32_t        stride;
        } rq;
        struct {
                void            *reg;
                uint32_t        size;
        } bf;
        uint64_t                comp_mask;
        off_t               uar_mmap_offset;
        uint32_t       tirn;
        uint32_t       tisn;
        uint32_t       rqn;
        uint32_t       sqn;
        uint64_t       tir_icm_address;
};

struct mlx5dv_cq {
        void                    *buf;
        uint32_t                *dbrec;
        uint32_t                cqe_cnt;
        uint32_t                cqe_size;
        void                    *cq_uar;
        uint32_t                cqn;
        uint64_t                comp_mask;
};

struct mlx5dv_srq {
        void                    *buf;
        uint32_t                *dbrec;
        uint32_t                stride;
        uint32_t                head;
        uint32_t                tail;
        uint64_t                comp_mask;
        uint32_t                srqn;
};

struct mlx5dv_rwq {
        void            *buf;
        uint32_t        *dbrec;
        uint32_t        wqe_cnt;
        uint32_t        stride;
        uint64_t        comp_mask;
};

struct mlx5dv_dm {
        void      *buf;
        uint64_t  length;
        uint64_t  comp_mask;
        uint64_t  remote_va;
};

struct mlx5dv_ah {
        struct mlx5_wqe_av    *av;
        uint64_t              comp_mask;
};

struct mlx5dv_pd {
        uint32_t              pdn;
        uint64_t              comp_mask;
};

struct mlx5dv_devx {
        uint32_t              handle; /* The kernel handle, can be used upon direct ioctl destroy */
};

and here's the big input/output wrapper — the one you actually pass in. note that each lil nested struct has an in (what you give it) and an out (what it gives you back). it's giving exchange student energy 💜

struct mlx5dv_obj {
        struct {
                struct ibv_qp           *in;
                struct mlx5dv_qp        *out;
        } qp;
        struct {
                struct ibv_cq           *in;
                struct mlx5dv_cq        *out;
        } cq;
        struct {
                struct ibv_srq          *in;
                struct mlx5dv_srq       *out;
        } srq;
        struct {
                struct ibv_wq           *in;
                struct mlx5dv_rwq       *out;
        } rwq;
        struct {
                struct ibv_dm       *in;
                struct mlx5dv_dm    *out;
        } dm;
        struct {
                struct ibv_ah       *in;
                struct mlx5dv_ah    *out;
        } ah;
        struct {
                struct ibv_pd           *in;
                struct mlx5dv_pd        *out;
        } pd;
        struct {
                struct mlx5dv_devx_obj  *in;
                struct mlx5dv_devx      *out;
        } devx;
};

and last but absolutely not least, the obj_type enum, aka the ✨menu✨ of things you can ask for. these are bit flags, so OR them together like the multitasking queen you are 👑

enum mlx5dv_obj_type {
        MLX5DV_OBJ_QP   = 1 << 0,
        MLX5DV_OBJ_CQ   = 1 << 1,
        MLX5DV_OBJ_SRQ  = 1 << 2,
        MLX5DV_OBJ_RWQ  = 1 << 3,
        MLX5DV_OBJ_DM   = 1 << 4,
        MLX5DV_OBJ_AH   = 1 << 5,
        MLX5DV_OBJ_PD   = 1 << 6,
        MLX5DV_OBJ_DEVX = 1 << 7,
};

---

🎀 RETURN VALUE 🎀

0 on success or the value of errno on failure (which indicates the failure reason).

so if you get a nonzero back, that's errno talking, and it's telling you exactly why it's upset. check it, don't ignore it, we don't do that here 😭

---

💀 NOTES 💀

• The information if doorbell is blueflame is based on mlx5dv_qp->bf->size, in case of 0 it's not a BF.
• Compatibility masks (comp_mask) are in/out fields.

fr fr on that first one — if bf->size is 0, it's not a blueflame doorbell. that's the vibe check right there, don't skip it 🌸

---

🌈 SEE ALSO 🌈

mlx5dv(7)

---

👑 AUTHORS 👑

Leon Romanovsky <leonro@mellanox.com>

---

so yeah bestie, that's the whole page, nothing left out, we ate and left no crumbs 💅✨ this version of MLX5DV_INIT_OBJ(3) came from version 1.0.0, dated 2017-02-02 — and remember, it's in the Library Functions Manual, so you always know where to find it again 🦋💖

ily, go write some direct verbs code 🫶