mlx5dv_devx_umem..._devx_umem_dereg(3)

💅 mlx5dv_devx_umem_reg / mlx5dv_devx_umem_reg_ex / mlx5dv_devx_umem_dereg

okay so bestie, you're in the mlx5dv section 3 pages, and this one is literally all about registering user memory so the devx interface can use it ✨ stay with me, it's actually so clean once you get it.

---

🌸 NAME

• mlx5dv_devx_umem_reg — register a user memory to be used by the devx interface
• mlx5dv_devx_umem_reg_ex — register a user memory to be used by the devx interface (yes, the fancy one 🎀)
• mlx5dv_devx_umem_dereg — deregister a devx umem object

---

✨ SYNOPSIS

#include <infiniband/mlx5dv.h>

struct mlx5dv_devx_umem {
    uint32_t umem_id;
};

struct mlx5dv_devx_umem *
mlx5dv_devx_umem_reg(struct ibv_context *context, void *addr, size_t size,
             uint32_t access)

struct mlx5dv_devx_umem_in {
    void *addr;
    size_t size;
    uint32_t access;
    uint64_t pgsz_bitmap;
    uint64_t comp_mask;
    int dmabuf_fd;
};

struct mlx5dv_devx_umem *
mlx5dv_devx_umem_reg_ex(struct ibv_context *ctx, struct mlx5dv_devx_umem_in *umem_in);

int mlx5dv_devx_umem_dereg(struct mlx5dv_devx_umem *dv_devx_umem)

---

🦋 DESCRIPTION

So basically: you're registering (or deregistering) a chunk of user memory so the devx interface can play with it. That's the whole vibe.

The register verb exposes a UMEM DEVX object for user memory registration for DMA 👑 and the way it works is: the API takes your user address, length and access flags as input, and hands you back an object as output — that object holds the UMEM ID that the firmware returned for this registered memory. iconic behavior honestly.

Now, if you want to ask for specific page sizes for the given address and length? That's the "I have opinions" path, and for that you should use mlx5dv_devx_umem_reg_ex() 🎀. But heads up: if the kernel couldn't find a matching page size from the given umem_in->pgsz_bitmap bitmap, the API will fail. no cap.

Then you take that UMEM ID and use it in device direct commands that use this memory instead of the physical addresses list — for example when you call mlx5dv_devx_obj_create to create a QP. that's the moment, that's the whole point 💅.

---

🧚 ARGUMENTS

• context — RDMA device context to create the action on. the main character of this whole operation.
• addr — The memory start address to register. where your memory starts, obvi.
• size — The size of addr buffer. how much of it we're talking about.
• access — The desired memory protection attributes; it is either 0 or the bitwise OR of one or more of enum ibv_access_flags. pick your permissions, babe.
• umem_in — A structure that holds the argument bundle 🎁 (the whole little package of args).

and inside that struct:

• pgsz_bitmap — Represents the required page sizes. umem creation will fail if it cannot be created with these page sizes. so like… choose wisely 🙈
• comp_mask — Flags indicating the additional fields. the "did you bring extra stuff" flag.
• dmabuf_fd — If MLX5DV_UMEM_MASK_DMABUF is set in comp_mask then this value must be a FD of a dmabuf. In this mode the dmabuf is used as the backing memory to create the umem out of. The dmabuf must be pinnable. And addr is interpreted as the starting offset of the dmabuf. 🫶

fr fr, that last one is a whole mode shift — the dmabuf is the backing memory, addr is just an offset. don't get it twisted.

---

💜 RETURN VALUE

Upon success, mlx5dv_devx_umem_reg / mlx5dv_devx_umem_reg_ex will return a new struct mlx5dv_devx_umem object 🎉 — on error NULL will be returned and errno will be set. so check your returns, bestie, always.

mlx5dv_devx_umem_dereg returns 0 on success, or the value of errno on failure (which indicates the failure reason). yep, it literally tells you why it's mad 😭

---

🌈 SEE ALSO

• mlx5dv_open_device(3)
• ibv_reg_mr(3)
• mlx5dv_devx_obj_create(3)

---

👑 AUTHOR

Yishai Hadas <yishaih@mellanox.com>

---

and that's the page, bestie 🍓 — this is the mlx5dv_devx_umem..._devx_umem_dereg(3) page from the mlx5dv manual (the title and the manual name are the same mlx5dv_devx_umem..._devx_umem_dereg(3) string, printed top and bottom of the original, and the date/version line is that same footer), so go register some memory and slay 💖🧚✨