NAME

       ibv_alloc_parent_domain(), ibv_dealloc_pd() - allocate and deallocate the parent domain object

SYNOPSIS

       #include <infiniband/verbs.h>

       struct ibv_pd *ibv_alloc_parent_domain(struct ibv_context *context, struct ibv_parent_domain_init_attr *attr);

DESCRIPTION

       ibv_alloc_parent_domain() allocates a parent domain object for the RDMA device context context.

       The  parent  domain object extends the normal protection domain with additional objects, such as a thread
       domain.

       A parent domain is completely interchangeable with the struct ibv_pd used to create it, and can  be  used
       as an input argument to any function accepting a struct ibv_pd.

       The  behavior  of  each  verb  may  be different if the verb is passed a parent domain struct ibv_pd that
       contains a struct ibv_td pointer.  For instance the verb may choose to share  resources  between  objects
       using the same thread domain. The exact behavior is provider dependent.

       The attr argument specifies the following:

       enum ibv_parent_domain_init_attr_mask {
               IBV_PARENT_DOMAIN_INIT_ATTR_ALLOCATORS = 1 << 0,
               IBV_PARENT_DOMAIN_INIT_ATTR_PD_CONTEXT = 1 << 1,
       };

       struct ibv_parent_domain_init_attr {
               struct ibv_pd *pd; /* reference to a protection domain, can't be NULL */
               struct ibv_td *td; /* reference 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;
       };

       ibv_dealloc_pd() will deallocate the parent domain as its exposed as an ibv_pd pd.  All resources created
       with the parent domain should be destroyed prior to deallocating the parent domain.

ARGUMENTS

       pd Reference to the protection domain that this parent domain uses.

       td An optional thread domain that the parent domain uses.

       comp_mask Bit-mask of optional fields in the ibv_parent_domain_init_attr struct.

       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 pd and the
       user-specified context pd_context.  In addition, the callback receives the size and the alignment of  the
       requested buffer, as well a vendor-specific 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 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.

       free Callback to free memory buffers that were allocated using a successful alloc().

       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.

RETURN VALUE

       ibv_alloc_parent_domain() returns a pointer to the allocated struct ibv_pd object, or NULL if the request
       fails (and sets errno to indicate the failure reason).

SEE ALSO

       ibv_alloc_parent_domain(3), ibv_dealloc_pd(3), ibv_alloc_pd(3), ibv_alloc_td(3)

AUTHORS

       Alex Rosenbaum <alexr@mellanox.com>

       Yishai Hadas <yishaih@mellanox.com>

libibverbs                                         2017-11-06                         IBV_ALLOC_PARENT_DOMAIN(3)