Direct Access Transport Library Functions datlmrcreate(3DAT)
NAME
datlmrcreate - register a memory region with an IA
SYNOPSIS
cc [ flag... ] file... -ldat [ library... ]
#include
DATRETURN
datlmrcreate (
IN DATIAHANDLE iahandle,
IN DATMEMTYPE memtype,
IN DATREGIONDESCRIPTION regiondescription,
IN DATVLEN length,
IN DATPZHANDLE pzhandle,
IN DATMEMPRIVFLAGS memprivileges,
OUT DATLMRHANDLE *lmrhandle,
OUT DATLMRCONTEXT *lmrcontext,
OUT DATRMRCONTEXT *rmrcontext,
OUT DATVLEN *registeredsize,
OUT DATVADR *registeredaddress
)
PARAMETERS
iahandle
Handle for an open instance of the IA.
memtype
Type of memory to be registered. The following list out-
lines the memory type specifications.
DATMEMTYPEVIRTUAL
Consumer virtual memory.
Region description: A pointer to a contiguous user
virtual range.
Length: Length of the Memory Region.
DATMEMTYPESOVIRTUAL
Consumer virtual memory with strong memory ordering.
This type is a Solaris specific addition. If the
iahandle was opened without ROAWARE (see
datiaopen(3DAT)), then type DATMEMTYPEVIRTUAL
is implicitly converted to this type.
SunOS 5.11 Last change: 28 Jan 2009 1
Direct Access Transport Library Functions datlmrcreate(3DAT)
Region description: A pointer to a contiguous user
virtual range.
Length: Length of the Memory Region.
DATMEMTYPELMR
LMR.
Region description: An LMRhandle.
Length: Length parameter is ignored.
DATMEMTYPESHAREDVIRTUAL
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 DATLMRCOKIE 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
regiondescription
Pointer to type-specific data describing the memory in
the region to be registered. The type is derived from
the memtype parameter.
length
Length parameter accompanying the regiondescription.
pzhandle
Handle for an instance of the Protection Zone.
SunOS 5.11 Last change: 28 Jan 2009 2
Direct Access Transport Library Functions datlmrcreate(3DAT)
memprivileges:
Consumer-requested memory access privileges for the
registered local memory region. The Default value is
DATMEMPRIVNONEFLAG. The constant value
DATMEMPRIVALFLAG = 0x33, which specifies both Read
and Write privileges, is also defined. Memory privilege
definitions are as follows:
Local Read DATMEMPRIVLOCALREADFLAG
0x01 Local read access requested.
Local Write DATMEMPRIVLOCALWRITEFLAG
0x10 Local write access requested.
Remote Read DATMEMPRIVREMOTEREADFLAG
0x02 Remote read access requested.
Remote Write DATMEMPRIVREMOTEWRITEFLAG
0x20 Remote write access requested.
lmrhandle
Handle for the created instance of the LMR.
lmrcontext
Context for the created instance of the LMR to use for
DTO local buffers.
registeredsize
Actual memory size registered by the Provider.
registeredaddress
SunOS 5.11 Last change: 28 Jan 2009 3
Direct Access Transport Library Functions datlmrcreate(3DAT)
Actual base address of the memory registered by the Pro-
vider.
DESCRIPTION
The datlmrcreate() 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 lmrcontext can be
used for local buffers of DTOs and for binding RMRs, and
lmrhandle can be used for creating other LMRs. For uDAPL
the scope of the lmrcontext is the address space of the DAT
Consumer.
The return values of registeredsize and registeredaddress
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 memtype 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 pzhandle parameter allows Consumers to restrict local
accesses to the registered LMR by DTOs.
DATLMRCOKIE is a pointer to a unique identifier of the
shared memory region of the DATMEMTYPESHAREDVIRTUAL 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 rmrcontext can be transferred by the
local Consumer to a Consumer on a remote host to be used for
an RDMA DTO.
If memprivileges does not specify remote Read and Write
privileges, rmrcontext is not generated and NUL 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 datlmrcreate(3DAT)
RETURN VALUES
DATSUCES The operation was successful.
DATUNSUFICIENTRESOURCES The operation failed due to
resource limitations.
DATINVALIDPARAMETER Invalid parameter.
DATINVALIDHANDLE Invalid DAT handle.
DATINVALIDSTATE Parameter in an invalid state.
For example, shared virtual
buffer was not created shared
by the platform.
DATMODELNOTSUPORTED 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 rmrcontext with caution. Once
advertised to a remote peer, the rmrcontext of the LMR can-
not be invalidated. The only way to invalidate it is to des-
troy the LMR with datlmrfree(3DAT).
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 28 Jan 2009 5
Direct Access Transport Library Functions datlmrcreate(3DAT)
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed
MT-Level Safe
Standard uDAPL, 1.1, 1.2 (except
DATMEMTYPESOVIRTUAL)
SEE ALSO
datlmrfree(3DAT), libdat(3LIB), attributes(5)
SunOS 5.11 Last change: 28 Jan 2009 6
|
