.\" -*- nroff -*-
.\" Licensed under the OpenIB.org BSD license (FreeBSD Variant) - See COPYING.md
.\"
.TH IBV_ALLOC_PARENT_DOMAIN 3 2017-11-06 libibverbs "Libibverbs Programmer's Manual"
.SH "NAME"
ibv_alloc_parent_domain(), ibv_dealloc_pd() \- allocate and deallocate the parent domain object
.SH "SYNOPSIS"
.nf
.B #include <infiniband/verbs.h>
.sp
.BI "struct ibv_pd *ibv_alloc_parent_domain(struct ibv_context "*context" ", struct ibv_parent_domain_init_attr " "*attr");
.sp
.SH "DESCRIPTION"
.B ibv_alloc_parent_domain()
allocates a parent domain object for the RDMA device context
.I context\fR.
.sp
The parent domain object extends the normal protection domain with additional
objects, such as a thread domain.
.sp
A parent domain is completely interchangeable with the
.I
struct ibv_pd
used to create it, and can be used as an input argument to any function accepting a
.I
struct ibv_pd.
.sp
The behavior of each verb may be different if the verb is passed a parent
domain
.I
struct ibv_pd
that contains a
.I
struct ibv_td pointer\fR.
For instance the verb my choose to share resources
between objects using the same thread domain. The exact behavior is provider
dependent.
.sp
The
.I attr
argument specifies the following:
.PP
.nf
enum ibv_parent_domain_init_attr_mask {
.in +8
IBV_PARENT_DOMAIN_INIT_ATTR_ALLOCATORS = 1 << 0,
IBV_PARENT_DOMAIN_INIT_ATTR_PD_CONTEXT = 1 << 1,
.in -8
};

struct ibv_parent_domain_init_attr {
.in +8
struct ibv_pd *pd; /* referance to a protection domain, can't be NULL */
struct ibv_td *td; /* referance to a thread domain, or NULL */
uint32_t comp_mask;
void *(*alloc)(struct ibv_pd *pd, void *pd_context, size_t size,
               size_t alignment, uint64_t resource_type);
void (*free)(struct ibv_pd *pd, void *pd_context, void *ptr,
             uint64_t resource_type);
void *pd_context;
.in -8
};
.fi
.PP
.sp
.B ibv_dealloc_pd()
will deallocate the parent domain as its exposed as an ibv_pd
.I pd\fR.
All resources created with the parent domain
should be destroyed prior to deallocating the parent domain\fR.
.SH "ARGUMENTS"
.B pd
Reference to the protection domain that this parent domain uses.
.PP
.B td
An optional thread domain that the parent domain uses.
.PP
.B comp_mask
Bit-mask of optional fields in the ibv_parent_domain_init_attr struct.
.PP
.B alloc
Custom memory allocation function for this parent domain. Provider
memory allocations will use this function to allocate the needed memory.
The allocation function is passed the parent domain
.B pd
and the user-specified context
.B pd_context.
In addition, the callback receives the
.B size
and the
.B alignment
of the requested buffer, as well a vendor-specific
.B resource_type
, which is derived from the rdma_driver_id enum (upper 32 bits) and a vendor
specific resource code.
The function returns the pointer to the allocated buffer, or NULL to
designate an error.  It may also return
.B IBV_ALLOCATOR_USE_DEFAULT
asking the callee to allocate the buffer using the default allocator.

The callback makes sure the allocated buffer is initialized with zeros. It is
also the responsibility of the callback to make sure the memory cannot be
COWed, e.g. by using madvise(MADV_DONTFORK) or by allocating anonymous shared
memory.
.PP
.B free
Callback to free memory buffers that were allocated using a successful
alloc().
.PP
.B pd_context
A pointer for additional user-specific data to be associated with this
parent domain. The pointer is passed back to the custom allocator functions.
.SH "RETURN VALUE"
.B ibv_alloc_parent_domain()
returns a pointer to the allocated struct
.I ibv_pd
object, or NULL if the request fails (and sets errno to indicate the failure reason).
.sp
.SH "SEE ALSO"
.BR ibv_alloc_parent_domain (3),
.BR ibv_dealloc_pd (3),
.BR ibv_alloc_pd (3),
.BR ibv_alloc_td (3)
.SH "AUTHORS"
.TP
Alex Rosenbaum <alexr@mellanox.com>
.TP
Yishai Hadas <yishaih@mellanox.com>