.\" Automatically generated by Pandoc 3.6.1
.\"
.TH "ibv_alloc_buf" "3" "2026\-05\-29" "libibverbs" "Libibverbs Programmer\[cq]s Manual"
.SH NAME
ibv_alloc_buf, ibv_free_buf, ibv_reg_buf_mr \- allocate provider\-aware
buffers and register them as memory regions
.SH SYNOPSIS
.IP
.EX
#include \f[B]<infiniband/verbs.h>\f[R]

void *ibv_alloc_buf(\f[B]struct\f[R] ibv_pd *pd, size_t size, \f[B]struct\f[R] ibv_buf **buf);

void ibv_free_buf(\f[B]struct\f[R] ibv_buf *buf);

\f[B]struct\f[R] ibv_mr *ibv_reg_buf_mr(\f[B]struct\f[R] ibv_pd *pd, \f[B]struct\f[R] ibv_buf *buf, void *addr,
                              size_t length, int access);
.EE
.SH DESCRIPTION
\f[B]ibv_alloc_buf()\f[R] allocates a buffer using the allocation method
selected by the provider for the protection domain \f[I]pd\f[R].
On success it returns the mapped address and stores an opaque buffer
handle in \f[I]buf\f[R].
The handle is used by \f[B]ibv_free_buf()\f[R],
\f[B]ibv_reg_buf_mr()\f[R], and \f[B]ibv_reg_mr_ex()\f[R] with
\f[B]IBV_REG_MR_MASK_BUF\f[R], and must not be interpreted by
applications.
.PP
\f[B]ibv_free_buf()\f[R] releases a buffer handle returned by
\f[B]ibv_alloc_buf()\f[R].
The protection domain used for allocation must remain valid until the
buffer is freed.
.PP
\f[B]ibv_reg_buf_mr()\f[R] registers a memory region for a buffer
returned by \f[B]ibv_alloc_buf()\f[R].
Applications can register the same buffer through
\f[B]ibv_reg_mr_ex()\f[R] by setting both \f[B]IBV_REG_MR_MASK_BUF\f[R]
and \f[B]IBV_REG_MR_MASK_ADDR\f[R], passing the buffer handle in
\f[CR]mr_init_attr\->buf\f[R] and the address to register in
\f[CR]mr_init_attr\->addr\f[R].
When \f[B]IBV_REG_MR_MASK_BUF\f[R] is set the caller must not set
\f[B]IBV_REG_MR_MASK_FD\f[R] or \f[B]IBV_REG_MR_MASK_FD_OFFSET\f[R],
and, for a DMA\-buf backed buffer, must not set
\f[B]IBV_REG_MR_MASK_IOVA\f[R]; libibverbs derives these from the buffer
handle and otherwise fails with \f[B]EINVAL\f[R].
The \f[I]pd\f[R] argument must be the same protection domain that was
used to allocate the buffer.
If a different protection domain is supplied, registration fails with
\f[B]EINVAL\f[R].
For ordinary memory it behaves like \f[B]ibv_reg_mr()\f[R].
For provider allocations backed by a DMA\-buf, it registers the
corresponding DMA\-buf range using the metadata stored in the opaque
\f[I]buf\f[R] handle.
.SH ARGUMENTS
.TP
\f[I]pd\f[R]
For \f[B]ibv_alloc_buf()\f[R], the protection domain (or parent domain)
to allocate from; its provider selects the buffer\[cq]s backing
allocation method.
It must remain valid until the buffer is freed with
\f[B]ibv_free_buf()\f[R].
For \f[B]ibv_reg_buf_mr()\f[R], the same protection domain that
allocated \f[I]buf\f[R] (otherwise registration fails with
\f[B]EINVAL\f[R]).
.TP
\f[I]size\f[R]
Size of the buffer to allocate, in bytes (\f[B]ibv_alloc_buf()\f[R]).
.TP
\f[I]buf\f[R]
For \f[B]ibv_alloc_buf()\f[R], an output parameter set on success to an
opaque buffer handle.
For \f[B]ibv_free_buf()\f[R] and \f[B]ibv_reg_buf_mr()\f[R], the buffer
handle returned by \f[B]ibv_alloc_buf()\f[R] to be released or
registered, respectively.
.TP
\f[I]addr\f[R]
The start address to register (\f[B]ibv_reg_buf_mr()\f[R]): the buffer
base returned by \f[B]ibv_alloc_buf()\f[R] or an address within that
buffer.
.TP
\f[I]length\f[R]
Length in bytes to register (\f[B]ibv_reg_buf_mr()\f[R]); \f[I]addr\f[R]
+ \f[I]length\f[R] must stay within the buffer.
.TP
\f[I]access\f[R]
Access flags for the memory region (\f[B]ibv_reg_buf_mr()\f[R]), the
same as for \f[B]ibv_reg_mr()\f[R].
.SH RETURN VALUE
\f[B]ibv_alloc_buf()\f[R] returns the mapped buffer address on success,
or NULL if the request fails.
.PP
\f[B]ibv_reg_buf_mr()\f[R] returns a pointer to the registered MR on
success, or NULL if the request fails.
.PP
\f[B]ibv_free_buf()\f[R] does not return a value.
.SH NOTES
Applications running in a CoCo guest that need unprotected/shared memory
should first create a parent domain with
\f[B]IBV_PARENT_DOMAIN_INIT_ATTR_ALLOW_CC_UNPROTECTED_ALLOC\f[R], then
use that parent domain as the \f[I]pd\f[R] argument to
\f[B]ibv_alloc_buf()\f[R] and \f[B]ibv_reg_buf_mr()\f[R] (or
\f[B]ibv_reg_mr_ex()\f[R] with \f[B]IBV_REG_MR_MASK_BUF\f[R]).
.SH SEE ALSO
\f[B]ibv_alloc_parent_domain\f[R](3), \f[B]ibv_reg_mr\f[R](3),
\f[B]ibv_reg_mr_ex\f[R](3), \f[B]ibv_reg_dmabuf_mr\f[R](3)