ibv_alloc_buf(3)

okay so this is ibv_alloc_buf(3) from the Libibverbs Programmer’s Manual — the page for allocating provider-aware buffers and registering them as memory regions. Buckle up, bestie. 💖

🌸 NAME 🌸

ibv_alloc_buf, ibv_free_buf, ibv_reg_buf_mr, ibv_export_buf_dmabuf_fd — allocate provider-aware buffers and register them as memory regions. The whole squad is here, and yes they are iconic. 💅

✨ SYNOPSIS ✨

okay, here’s the literal include and the function signatures — keep these exactly as written, iykyk:

              #include <infiniband/verbs.h>

              void *ibv_alloc_buf(struct ibv_pd *pd, size_t size, struct ibv_buf **buf);

              void ibv_free_buf(struct ibv_buf *buf);

              struct ibv_mr *ibv_reg_buf_mr(struct ibv_pd *pd, struct ibv_buf *buf, void *addr,
                                            size_t length, int access);

              int ibv_export_buf_dmabuf_fd(struct ibv_buf *buf);

🦋 DESCRIPTION 🦋

ibv_alloc_buf() allocates a buffer using the allocation method selected by the provider for the protection domain pd. On success it returns the mapped address and stores an opaque buffer handle in buf. That handle is used by ibv_free_buf(), ibv_reg_buf_mr(), ibv_reg_mr_ex() with IBV_REG_MR_MASK_BUF, and ibv_export_buf_dmabuf_fd(); it must not be interpreted by applications. Like, do not poke the mystery handle, bestie — it’s not for you. 🙈

ibv_free_buf() releases a buffer handle returned by ibv_alloc_buf(). The protection domain used for allocation must remain valid until the buffer is freed. Periodt.

ibv_reg_buf_mr() registers a memory region for a buffer returned by ibv_alloc_buf(). Applications can register the same buffer through ibv_reg_mr_ex() by setting both IBV_REG_MR_MASK_BUF and IBV_REG_MR_MASK_ADDR, passing the buffer handle in mr_init_attr->buf and the address to register in mr_init_attr->addr.

bestie warning: when IBV_REG_MR_MASK_BUF is set, the caller must not set IBV_REG_MR_MASK_FD or IBV_REG_MR_MASK_FD_OFFSET, and, for a DMA-buf backed buffer, must not set IBV_REG_MR_MASK_IOVA — libibverbs derives these from the buffer handle and otherwise fails with EINVAL. no cap, that’s the rule. 💀

The pd argument must be the same protection domain that was used to allocate the buffer. If a different protection domain is supplied, registration fails with EINVAL. For ordinary memory it behaves like ibv_reg_mr(). For provider allocations backed by a DMA-buf, it registers the corresponding DMA-buf range using the metadata stored in the opaque buf handle. The way that works is lowkey elegant. ✨

ibv_export_buf_dmabuf_fd() exports a new file descriptor for a buffer that is backed by a DMA-buf. This allows applications to pass provider-allocated memory to other APIs that import DMA-buf file descriptors. The returned file descriptor is owned by the caller and should be closed with close(2) when no longer needed. Calling ibv_export_buf_dmabuf_fd() does not transfer ownership of the buffer handle or the internal descriptor used by libibverbs. So close your fd, but don’t get it twisted about ownership. 🫶

🎀 ARGUMENTS 🎀

• pd — For ibv_alloc_buf(), the protection domain (or parent domain) to allocate from; its provider selects the buffer’s backing allocation method. It must remain valid until the buffer is freed with ibv_free_buf(). For ibv_reg_buf_mr(), the same protection domain that allocated buf (otherwise registration fails with EINVAL).
• size — Size of the buffer to allocate, in bytes (ibv_alloc_buf()).
• buf — For ibv_alloc_buf(), an output parameter set on success to an opaque buffer handle. For ibv_free_buf() and ibv_reg_buf_mr(), the buffer handle returned by ibv_alloc_buf() to be released or registered, respectively. For ibv_export_buf_dmabuf_fd(), the buffer handle whose DMA-buf fd should be exported.
• addr — The start address to register (ibv_reg_buf_mr()): the buffer base returned by ibv_alloc_buf() or an address within that buffer.
• length — Length in bytes to register (ibv_reg_buf_mr()); addr + length must stay within the buffer.
• access — Access flags for the memory region (ibv_reg_buf_mr()), the same as for ibv_reg_mr().

💖 RETURN VALUE 💖

• ibv_alloc_buf() returns the mapped buffer address on success, or NULL if the request fails.
• ibv_reg_buf_mr() returns a pointer to the registered MR on success, or NULL if the request fails.
• ibv_free_buf() does not return a value.
• ibv_export_buf_dmabuf_fd() returns a file descriptor >= 0 on success, or -1 if the request fails with errno set. If buf is not backed by a DMA-buf, errno is set to ENODATA.

🌈 NOTES 🌈

Applications running in a CoCo guest that need unprotected/shared memory should first create a parent domain with IBV_PARENT_DOMAIN_INIT_ATTR_ALLOW_CC_UNPROTECTED_ALLOC, then use that parent domain as the pd argument to ibv_alloc_buf() and ibv_reg_buf_mr() (or ibv_reg_mr_ex() with IBV_REG_MR_MASK_BUF). That’s the whole glow-up path, bestie. 🧚

⭐ SEE ALSO ⭐

• ibv_alloc_parent_domain(3)
• ibv_reg_mr(3)
• ibv_reg_mr_ex(3)
• ibv_reg_dmabuf_mr(3)

---

xoxo, source/version: libibverbs, date: 2026-05-29 — go be iconic with your buffers 💅✨