dat_lmr_create(3dat)

1dat_lmr_create(3DAT)Direct Access Transport Library Functiondsat_lmr_create(3DAT)
2
3
4

NAME

6       dat_lmr_create - register a memory region with an IA
7

SYNOPSIS

9       cc [ flag... ] file... -ldat [ library... ]
10       #include <dat/udat.h>
11
12       DAT_RETURN
13           dat_lmr_create (
14           IN    DAT_IA_HANDLE          ia_handle,
15           IN    DAT_MEM_TYPE           mem_type,
16           IN    DAT_REGION_DESCRIPTION region_description,
17           IN    DAT_VLEN               length,
18           IN    DAT_PZ_HANDLE          pz_handle,
19           IN    DAT_MEM_PRIV_FLAGS     mem_privileges,
20           OUT   DAT_LMR_HANDLE         *lmr_handle,
21           OUT   DAT_LMR_CONTEXT        *lmr_context,
22           OUT   DAT_RMR_CONTEXT        *rmr_context,
23           OUT   DAT_VLEN               *registered_size,
24           OUT   DAT_VADDR              *registered_address
25           )
26
27

PARAMETERS

29       ia_handle
30
31           Handle for an open instance of the IA.
32
33
34       mem_type
35
36           Type  of  memory  to be registered. The following list outlines the
37           memory type specifications.
38
39           DAT_MEM_TYPE_VIRTUAL
40
41               Consumer virtual memory.
42
43               Region description: A pointer  to  a  contiguous  user  virtual
44               range.
45
46               Length: Length of the Memory Region.
47
48
49           DAT_MEM_TYPE_SO_VIRTUAL
50
51               Consumer  virtual memory with strong memory ordering. This type
52               is a Solaris specific addition. If  the  ia_handle  was  opened
53               without    RO_AWARE_   (see   dat_ia_open(3DAT)),   then   type
54               DAT_MEM_TYPE_VIRTUAL is implicitly converted to this type.
55
56               Region description: A pointer to a   contiguous   user  virtual
57               range.
58
59               Length: Length of the Memory Region.
60
61
62           DAT_MEM_TYPE_LMR
63
64               LMR.
65
66               Region description: An LMR_handle.
67
68               Length: Length parameter is ignored.
69
70
71           DAT_MEM_TYPE_SHARED_VIRTUAL
72
73               Shared  memory  region.  All  DAT  Consumers  of the same uDAPL
74               Provider specify the same Consumer cookie to  indicate  who  is
75               sharing  the shared memory region. This supports a peer-to-peer
76               model of shared memory. All DAT Consumers of the shared  memory
77               must  allocate  the  memory region as shared memory using Plat‐
78               form-specific primitives.
79
80               Region description: A structure  with  2  elements,  where  the
81               first  one is of type DAT_LMR_COOKIE and is a unique identifier
82               of the shared memory region, and the second one is a pointer to
83               a contiguous user virtual range.
84
85               Length: Length of the Memory Region
86
87
88
89       region_description
90
91           Pointer  to  type-specific data describing the memory in the region
92           to be registered. The type is derived from the mem_type parameter.
93
94
95       length
96
97           Length parameter accompanying the region_description.
98
99
100       pz_handle
101
102           Handle for an instance of the Protection Zone.
103
104
105       mem_privileges:
106
107           Consumer-requested memory  access  privileges  for  the  registered
108           local  memory  region. The Default value is DAT_MEM_PRIV_NONE_FLAG.
109           The constant value DAT_MEM_PRIV_ALL_FLAG =  0x33,  which  specifies
110           both  Read  and Write privileges, is also defined. Memory privilege
111           definitions are as follows:
112
113           Local Read      DAT_MEM_PRIV_LOCAL_READ_FLAG
114
115                           0x01    Local read access requested.
116
117
118
119           Local Write     DAT_MEM_PRIV_LOCAL_WRITE_FLAG
120
121                           0x10    Local write access requested.
122
123
124
125           Remote Read     DAT_MEM_PRIV_REMOTE_READ_FLAG
126
127                           0x02    Remote read access requested.
128
129
130
131           Remote Write    DAT_MEM_PRIV_REMOTE_WRITE_FLAG
132
133                           0x20    Remote write access requested.
134
135
136
137
138       lmr_handle
139
140           Handle for the created instance of the LMR.
141
142
143       lmr_context
144
145           Context for the created instance of the LMR to use  for  DTO  local
146           buffers.
147
148
149       registered_size
150
151           Actual memory size registered by the Provider.
152
153
154       registered_address
155
156           Actual base address of the memory registered by the Provider.
157
158

DESCRIPTION

160       The dat_lmr_create() function registers a memory region with an IA. The
161       specified buffer must have been previously allocated and pinned by  the
162       uDAPL  Consumer on the platform. The Provider must do memory pinning if
163       needed, which includes whatever  OS-dependent  steps  are  required  to
164       ensure  that  the  memory  is  available  on  demand  for the Interface
165       Adapter. uDAPL does not require that the memory never be  swapped  out;
166       just  that  neither the hardware nor the Consumer ever has to deal with
167       it not being there. The created lmr_context can be used for local  buf‐
168       fers  of DTOs and for binding RMRs, and lmr_handle can be used for cre‐
169       ating other LMRs. For uDAPL the scope of the lmr_context is the address
170       space of the DAT Consumer.
171
172
173       The return values of registered_size and registered_address indicate to
174       the Consumer how much the contiguous region of Consumer virtual  memory
175       was  registered by the Provider and where the region starts in the Con‐
176       sumer virtual address.
177
178
179       The mem_type parameter indicates to the Provider the kind of memory  to
180       be  registered,  and can take on any of the values defined in the table
181       in the PARAMETERS section.
182
183
184       The pz_handle parameter allows Consumers to restrict local accesses  to
185       the registered LMR by DTOs.
186
187
188       DAT_LMR_COOKIE is a pointer to a unique identifier of the shared memory
189       region of the DAT_MEM_TYPE_SHARED_VIRTUAL DAT memory type. The  identi‐
190       fier  is  an  array of 40 bytes allocated by the Consumer. The Provider
191       must check the entire 40 bytes and shall not interpret it  as  a  null-
192       terminated string.
193
194
195       The  return  value  of rmr_context can be transferred by the local Con‐
196       sumer to a Consumer on a remote host to be used for an RDMA DTO.
197
198
199       If mem_privileges does not specify remote Read  and  Write  privileges,
200       rmr_context is not generated and NULL is returned. No remote privileges
201       are given for Memory Region unless explicitly asked  for  by  the  Con‐
202       sumer.
203

RETURN VALUES

205       DAT_SUCCESS                   The operation was successful.
206
207
208       DAT_UNSUFFICIENT_RESOURCES    The operation failed due to resource lim‐
209                                     itations.
210
211
212       DAT_INVALID_PARAMETER         Invalid parameter.
213
214
215       DAT_INVALID_HANDLE            Invalid DAT handle.
216
217
218       DAT_INVALID_STATE             Parameter in an invalid state. For  exam‐
219                                     ple,  shared  virtual buffer was not cre‐
220                                     ated shared by the platform.
221
222
223       DAT_MODEL_NOT_SUPPORTED       The requested Model was not supported  by
224                                     the Provider. For example, requested Mem‐
225                                     ory  Type  was  not  supported   by   the
226                                     Provider.
227
228

USAGE

230       Consumers can create an LMR over the existing LMR memory with different
231       Protection Zones and privileges using previously created IA translation
232       table entries.
233
234
235       The  Consumer should use rmr_context with caution. Once advertised to a
236       remote peer, the rmr_context of the LMR cannot be invalidated. The only
237       way to invalidate it is to destroy the LMR with dat_lmr_free(3DAT).
238

ATTRIBUTES

240       See attributes(5) for descriptions of the following attributes:
241
242
243
244
245       ┌─────────────────────────────┬─────────────────────────────┐
246       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
247       ├─────────────────────────────┼─────────────────────────────┤
248       │Interface Stability          │Committed                    │
249       ├─────────────────────────────┼─────────────────────────────┤
250       │MT-Level                     │Safe                         │
251       ├─────────────────────────────┼─────────────────────────────┤
252       │Standard                     │uDAPL,   1.1,  1.2  (except  │
253       │                             │DAT_MEM_TYPE_SO_VIRTUAL)     │
254       └─────────────────────────────┴─────────────────────────────┘
255