|
HTML rendering created 2026-09-09 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | ARGUMENTS | RETURN VALUE | NOTES | SEE ALSO | COLOPHON |
|
|
|
ibv_alloc_buf(3) Libibverbs Programmer’s Manual ibv_alloc_buf(3)
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
#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);
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. The 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.
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.
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. 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. 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.
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.
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().
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.
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).
ibv_alloc_parent_domain(3), ibv_reg_mr(3), ibv_reg_mr_ex(3),
ibv_reg_dmabuf_mr(3)
This page is part of the rdma-core (RDMA Core Userspace Libraries
and Daemons) project. Information about the project can be found
at ⟨https://github.com/linux-rdma/rdma-core⟩. If you have a bug
report for this manual page, send it to
linux-rdma@vger.kernel.org. This page was obtained from the
project's upstream Git repository
⟨https://github.com/linux-rdma/rdma-core.git⟩ on 2026-08-04. (At
that time, the date of the most recent commit that was found in
the repository was 2026-07-22.) If you discover any rendering
problems in this HTML version of the page, or you believe there is
a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
man-pages@man7.org
libibverbs 2026-05-29 ibv_alloc_buf(3)
|
HTML rendering created 2026-09-09 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|