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>