Manual Pages for UNIX Operating System command usage for man dat_lmr_create

Direct Access Transport Library Functions    dat_lmr_create(3DAT)



NAME
     dat_lmr_create - register a memory region with an IA

SYNOPSIS
     cc [ flag... ] file... -ldat [ library... ]
     #include 

     DAT_RETURN
         dat_lmr_create (
         IN    DAT_IA_HANDLE          ia_handle,
         IN    DAT_MEM_TYPE           mem_type,
         IN    DAT_REGION_DESCRIPTION region_description,
         IN    DAT_VLEN               length,
         IN    DAT_PZ_HANDLE          pz_handle,
         IN    DAT_MEM_PRIV_FLAGS     mem_privileges,
         OUT   DAT_LMR_HANDLE         *lmr_handle,
         OUT   DAT_LMR_CONTEXT        *lmr_context,
         OUT   DAT_RMR_CONTEXT        *rmr_context,
         OUT   DAT_VLEN               *registered_size,
         OUT   DAT_VADDR              *registered_address
         )


PARAMETERS
     ia_handle

         Handle for an open instance of the IA.


     mem_type

         Type of memory to be registered. The following list out-
         lines the memory type specifications.

         DAT_MEM_TYPE_VIRTUAL

             Consumer virtual memory.

             Region description: A pointer to a  contiguous  user
             virtual range.

             Length: Length of the Memory Region.


         DAT_MEM_TYPE_SO_VIRTUAL

             Consumer virtual memory with strong memory ordering.
             This  type  is  a  Solaris specific addition. If the
             ia_handle  was   opened   without   RO_AWARE_   (see
             dat_ia_open(3DAT)),  then  type DAT_MEM_TYPE_VIRTUAL
             is implicitly converted to this type.




SunOS 5.11          Last change: 28 Jan 2009                    1






Direct Access Transport Library Functions    dat_lmr_create(3DAT)



             Region description: A pointer to a  contiguous  user
             virtual range.

             Length: Length of the Memory Region.


         DAT_MEM_TYPE_LMR

             LMR.

             Region description: An LMR_handle.

             Length: Length parameter is ignored.


         DAT_MEM_TYPE_SHARED_VIRTUAL

             Shared memory region. All DAT Consumers of the  same
             uDAPL  Provider  specify the same Consumer cookie to
             indicate who is sharing the  shared  memory  region.
             This supports a peer-to-peer model of shared memory.
             All DAT Consumers of the shared memory must allocate
             the  memory  region as shared memory using Platform-
             specific primitives.

             Region description: A  structure  with  2  elements,
             where the first one is of type DAT_LMR_COOKIE and is
             a unique identifier of the shared memory region, and
             the  second  one  is  a pointer to a contiguous user
             virtual range.

             Length: Length of the Memory Region



     region_description

         Pointer to type-specific data describing the  memory  in
         the  region  to  be registered. The type is derived from
         the mem_type parameter.


     length

         Length parameter accompanying the region_description.


     pz_handle

         Handle for an instance of the Protection Zone.





SunOS 5.11          Last change: 28 Jan 2009                    2






Direct Access Transport Library Functions    dat_lmr_create(3DAT)



     mem_privileges:

         Consumer-requested  memory  access  privileges  for  the
         registered  local  memory  region.  The Default value is
         DAT_MEM_PRIV_NONE_FLAG.     The      constant      value
         DAT_MEM_PRIV_ALL_FLAG  = 0x33, which specifies both Read
         and Write privileges, is also defined. Memory  privilege
         definitions are as follows:

         Local Read      DAT_MEM_PRIV_LOCAL_READ_FLAG

                         0x01    Local read access requested.



         Local Write     DAT_MEM_PRIV_LOCAL_WRITE_FLAG

                         0x10    Local write access requested.



         Remote Read     DAT_MEM_PRIV_REMOTE_READ_FLAG

                         0x02    Remote read access requested.



         Remote Write    DAT_MEM_PRIV_REMOTE_WRITE_FLAG

                         0x20    Remote write access requested.




     lmr_handle

         Handle for the created instance of the LMR.


     lmr_context

         Context for the created instance of the LMR to  use  for
         DTO local buffers.


     registered_size

         Actual memory size registered by the Provider.


     registered_address




SunOS 5.11          Last change: 28 Jan 2009                    3






Direct Access Transport Library Functions    dat_lmr_create(3DAT)



         Actual base address of the memory registered by the Pro-
         vider.


DESCRIPTION
     The dat_lmr_create() function registers a memory region with
     an  IA. The specified buffer must have been previously allo-
     cated and pinned by the uDAPL Consumer on the platform.  The
     Provider  must  do  memory pinning if needed, which includes
     whatever OS-dependent steps are required to ensure that  the
     memory  is  available  on  demand for the Interface Adapter.
     uDAPL does not require that the memory never be swapped out;
     just  that neither the hardware nor the Consumer ever has to
     deal with it not being there. The created lmr_context can be
     used  for  local  buffers  of DTOs and for binding RMRs, and
     lmr_handle can be used for creating other  LMRs.  For  uDAPL
     the scope of the lmr_context is the address space of the DAT
     Consumer.


     The return values of registered_size and  registered_address
     indicate  to  the Consumer how much the contiguous region of
     Consumer virtual memory was registered by the  Provider  and
     where the region starts in the Consumer virtual address.


     The mem_type parameter indicates to the Provider the kind of
     memory  to  be registered, and can take on any of the values
     defined in the table in the PARAMETERS section.


     The pz_handle parameter allows Consumers to  restrict  local
     accesses to the registered LMR by DTOs.


     DAT_LMR_COOKIE is a pointer to a unique  identifier  of  the
     shared  memory region of the DAT_MEM_TYPE_SHARED_VIRTUAL DAT
     memory type. The identifier is an array of  40  bytes  allo-
     cated by the Consumer. The Provider must check the entire 40
     bytes and  shall  not  interpret  it  as  a  null-terminated
     string.


     The return value of rmr_context can be  transferred  by  the
     local Consumer to a Consumer on a remote host to be used for
     an RDMA DTO.


     If mem_privileges does not specify  remote  Read  and  Write
     privileges,   rmr_context  is  not  generated  and  NULL  is
     returned. No remote privileges are given for  Memory  Region
     unless explicitly asked for by the Consumer.



SunOS 5.11          Last change: 28 Jan 2009                    4






Direct Access Transport Library Functions    dat_lmr_create(3DAT)



RETURN VALUES
     DAT_SUCCESS                   The operation was successful.


     DAT_UNSUFFICIENT_RESOURCES    The operation  failed  due  to
                                   resource limitations.


     DAT_INVALID_PARAMETER         Invalid parameter.


     DAT_INVALID_HANDLE            Invalid DAT handle.


     DAT_INVALID_STATE             Parameter in an invalid state.
                                   For  example,  shared  virtual
                                   buffer was not created  shared
                                   by the platform.


     DAT_MODEL_NOT_SUPPORTED       The requested  Model  was  not
                                   supported by the Provider. For
                                   example, requested Memory Type
                                   was  not supported by the Pro-
                                   vider.


USAGE
     Consumers can create an LMR over  the  existing  LMR  memory
     with  different Protection Zones and privileges using previ-
     ously created IA translation table entries.


     The Consumer  should  use  rmr_context  with  caution.  Once
     advertised to a remote peer, the rmr_context of the LMR can-
     not be invalidated. The only way to invalidate it is to des-
     troy the LMR with dat_lmr_free(3DAT).

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:














SunOS 5.11          Last change: 28 Jan 2009                    5






Direct Access Transport Library Functions    dat_lmr_create(3DAT)



     ____________________________________________________________
   |        ATTRIBUTE TYPE       |        ATTRIBUTE VALUE      |
   | ____________________________|_____________________________|_
   |  Interface Stability        |  Committed                  |
   | ____________________________|_____________________________|_
   |  MT-Level                   |  Safe                       |
   | ____________________________|_____________________________|_
   |  Standard                   |  uDAPL,  1.1,  1.2   (except|
   |                             |  DAT_MEM_TYPE_SO_VIRTUAL)   |
   |_____________________________|_____________________________|


SEE ALSO
     dat_lmr_free(3DAT), libdat(3LIB), attributes(5)









































SunOS 5.11          Last change: 28 Jan 2009                    6