1dat_ep_post_rdma_wriDtier(e3cDtATA)ccess Transport LibrarydFautn_cetpi_opnosst_rdma_write(3DAT)
2
6 dat_ep_post_rdma_write - write all data to the remote data buffer
7
9 cc [ flag... ] file... -ldat [ library... ]
10 #include <dat/udat.h>
11 DAT_RETURN
13 dat_ep_post_rdma_read (
14 IN DAT_EP_HANDLE ep_handle,
15 IN DAT_COUNT num_segments,
16 IN DAT_LMR_TRIPLET *local_iov,
17 IN DAT_DTO_COOKIE user_cookie,
18 IN DAT_RMR_TRIPLET *remote_buffer,
19 IN DAT_COMPLETION_FLAGS completion_flags
20 )
21
24 ep_handle Handle for an instance of the Endpoint.
25 num_segments Number of lmr_triplets in local_iov.
28 local_iov I/O Vector that specifies the local buffer from
31 which the data is transferred.
32 user_cookie User-provided cookie that is returned to the Con‐
35 sumer at the completion of the RDMA Write.
36 remote_buffer A pointer to an RMR Triplet that specifies the
39 remote buffer from which the data is read.
40 completion_flags Flags for posted RDMA read. The default DAT_COMPLE‐
43 TION_DEFAULT_FLAG is 0x00. Other values are as fol‐
44 lows:
45 Completion Suppression DAT_COMPLETION_SUP‐
47 PRESS_FLAG
48 0x01 Suppress suc‐
50 cessful Com‐
51 pletion.
52 Notification of Completion DAT_COMPLE‐
56 TION_UNSIGNALLED_FLAG
57 0x04 Non-notifica‐
59 tion comple‐
60 tion. Local
61 Endpoint must
62 be configured
63 for Notifica‐
64 tion Suppres‐
65 sion.
66 Barrier Fence DAT_COMPLETION_BAR‐
70 RIER_FENCE_FLAG
71 0x08 Request for
73 Barrier
74 Fence.
75
80 The dat_ep_post_rdma_write() function requests the transfer of all the
81 data specified by the local_iov over the connection of the ep_handle
82 Endpoint into the remote_buffer.
83 The num_segments parameter specifies the number of segments in the
86 local_iov. The local_iov segments are traversed in the I/O Vector order
87 until all the data is transferred.
88 A Consumer must not modify the local_iov or its content until the DTO
91 is completed. When a Consumer does not adhere to this rule, the behav‐
92 ior of the Provider and the underlying Transport is not defined.
93 Providers that allow Consumers to get ownership of the local_iov but
94 not the memory it specifies back after the dat_ep_post_rdma_write()
95 returns should document this behavior and also specify its support in
96 Provider attributes. This behavior allows Consumers full control of the
97 local_iov after dat_ep_post_rdma_write() returns. Because this behavior
98 is not guaranteed by all Providers, portable Consumers should not rely
99 on this behavior. Consumers should not rely on the Provider copying
100 local_iov information.
101 The DAT_SUCCESS return of the dat_ep_post_rdma_write() is at least the
104 equivalent of posting an RDMA Write operation directly by native Trans‐
105 port. Providers should avoid resource allocation as part of
106 dat_ep_post_rdma_write() to ensure that this operation is nonblocking
107 and thread safe for an UpCall.
108 The completion of the posted RDMA Write is reported to the Consumer
111 asynchronously through a DTO Completion event based on the specified
112 completion_flags value. The value of DAT_COMPLETION_UNSIGNALLED_FLAG is
113 only valid if the Endpoint Request Completion Flags DAT_COMPLE‐
114 TION_UNSIGNALLED_FLAG. Otherwise, DAT_INVALID_PARAMETER is returned.
115 The user_cookie allows Consumers to have unique identifiers for each
118 DTO. These identifiers are completely under user control and are opaque
119 to the Provider. There is no requirement on the Consumer that the value
120 user_cookie should be unique for each DTO. The user_cookie is returned
121 to the Consumer in the Completion event for the posted RDMA Write.
122 The operation is valid for the Endpoint in the DAT_EP_STATE_CONNECTED
125 and DAT_EP_STATE_DISCONNECTED states. If the operation returns success‐
126 fully for the Endpoint in the DAT_EP_STATE_DISCONNECTED state, the
127 posted RDMA Write is immediately flushed to request_evd_handle.
128
130 DAT_SUCCESS The operation was successful.
131 DAT_INSUFFICIENT_RESOURCES The operation failed due to resource lim‐
134 itations.
135 DAT_INVALID_PARAMETER Invalid parameter. For example, one of
138 the IOV segments pointed to a memory out‐
139 side its LMR.
140 DAT_INVALID_HANDLE The ep_handle parameter is invalid.
143 DAT_INVALID_STATE A parameter is in an invalid state. End‐
146 point was not in the DAT_EP_STATE_CON‐
147 NECTED or DAT_EP_STATE_DISCONNECTED
148 state.
149 DAT_LENGTH_ERROR The size of the receiving buffer is too
152 small for sending buffer data. The size
153 of the remote buffer is too small for the
154 data of the local buffer.
155 DAT_PROTECTION_VIOLATION Protection violation for local or remote
158 memory access. Protection Zone mismatch
159 between either an LMR of one of the
160 local_iov segments and the local Endpoint
161 or the rmr_context and the remote End‐
162 point.
163 DAT_PRIVILEGES_VIOLATION Privileges violation for local or remote
166 memory access. Either one of the LMRs
167 used in local_iov is invalid or does not
168 have the local read privileges, or
169 rmr_context does not have the remote
170 write privileges.
171
174 For best RDMA Write operation performance, the Consumer should align
175 each buffer segment of local_iov to the Optimal Buffer Alignment
176 attribute of the Provider. For portable applications, the Consumer
177 should align each buffer segment of local_iov to the DAT_OPTIMAL_ALIGN‐
178 MENT.
179
181 See attributes(5) for descriptions of the following attributes:
182 ┌─────────────────────────────┬─────────────────────────────┐
187 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
188 ├─────────────────────────────┼─────────────────────────────┤
189 │Interface Stability │Standard: uDAPL, 1.1, 1.2 │
190 ├─────────────────────────────┼─────────────────────────────┤
191 │MT-Level │Unsafe │
192 └─────────────────────────────┴─────────────────────────────┘
193
195 libdat(3LIB), attributes(5)
196SunOS 5.11 16 Jul 2004 dat_ep_post_rdma_write(3DAT)