1dat_ep_post_rdma_reaDdi(r3eDcAtT)Access Transport Library Fduantc_teipo_npsost_rdma_read(3DAT)
2
6 dat_ep_post_rdma_read - transfer all data to the local 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 to fill.
31 user_cookie User-provided cookie that is returned to the Con‐
34 sumer at the completion of the RDMA Read. Can be
35 NULL.
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_read() function requests the transfer of all the
81 data specified by the remote_buffer over the connection of the ep_han‐
82 dle Endpoint into the local_iov.
83 The num_segments parameter specifies the number of segments in the
86 local_iov. The local_iov segments are filled in the I/O Vector order
87 until the whole message is received. This ensures that all the "front"
88 segments of the local_iov I/O Vector are completely filled, only one
89 segment is partially filled, if needed, and all segments that follow it
90 are not filled at all.
91 The user_cookie allows Consumers to have unique identifiers for each
94 DTO. These identifiers are completely under user control and are opaque
95 to the Provider. There is no requirement on the Consumer that the value
96 user_cookie should be unique for each DTO. The user_cookie is returned
97 to the Consumer in the Completion event for the posted RDMA Read.
98 A Consumer must not modify the local_iov or its content until the DTO
101 is completed. When a Consumer does not adhere to this rule, the behav‐
102 ior of the Provider and the underlying Transport is not defined.
103 Providers that allow Consumers to get ownership of the local_iov but
104 not the memory it specifies back after the dat_ep_post_rdma_read()
105 returns should document this behavior and also specify its support in
106 Provider attributes. This behavior allows Consumers full control of the
107 local_iov after dat_ep_post_rdma_read() returns. Because this behavior
108 is not guaranteed by all Providers, portable Consumers should not rely
109 on this behavior. Consumers should not rely on the Provider copying
110 local_iov information.
111 The completion of the posted RDMA Read is reported to the Consumer
114 asynchronously through a DTO Completion event based on the specified
115 completion_flags value. The value of DAT_COMPLETION_UNSIGNALLED_FLAG is
116 only valid if the Endpoint Request Completion Flags DAT_COMPLE‐
117 TION_UNSIGNALLED_FLAG. Otherwise, DAT_INVALID_PARAMETER is returned.
118 The DAT_SUCCESS return of the dat_ep_post_rdma_read() is at least the
121 equivalent of posting an RDMA Read operation directly by native Trans‐
122 port. Providers should avoid resource allocation as part of
123 dat_ep_post_rdma_read() to ensure that this operation is nonblocking
124 and thread safe for an UpCall.
125 The operation is valid for the Endpoint in the DAT_EP_STATE_CONNECTED
128 and DAT_EP_STATE_DISCONNECTED states. If the operation returns success‐
129 fully for the Endpoint in the DAT_EP_STATE_DISCONNECTED state, the
130 posted RDMA Read is immediately flushed to request_evd_handle.
131
133 DAT_SUCCESS The operation was successful.
134 DAT_INSUFFICIENT_RESOURCES The operation failed due to resource lim‐
137 itations.
138 DAT_INVALID_PARAMETER Invalid parameter. For example, one of
141 the IOV segments pointed to a memory out‐
142 side its LMR.
143 DAT_INVALID_HANDLE The ep_handle parameter is invalid.
146 DAT_INVALID_STATE A parameter is in an invalid state. End‐
149 point was not in the DAT_EP_STATE_CON‐
150 NECTED or DAT_EP_STATE_DISCONNECTED
151 state.
152 DAT_LENGTH_ERROR The size of the receiving buffer is too
155 small for sending buffer data. The size
156 of the local buffer is too small for the
157 data of the remote buffer.
158 DAT_PROTECTION_VIOLATION Protection violation for local or remote
161 memory access. Protection Zone mismatch
162 between either an LMR of one of the
163 local_iov segments and the local Endpoint
164 or the rmr_context and the remote End‐
165 point.
166 DAT_PRIVILEGES_VIOLATION Privileges violation for local or remote
169 memory access. Either one of the LMRs
170 used in local_iov is invalid or does not
171 have the local write privileges, or
172 rmr_context does not have the remote read
173 privileges.
174
177 For best RDMA Read operation performance, the Consumer should align
178 each buffer segment of local_iov to the Optimal Buffer Alignment
179 attribute of the Provider. For portable applications, the Consumer
180 should align each buffer segment of local_iov to the DAT_OPTIMAL_ALIGN‐
181 MENT.
182 If connection was established without outstanding RDMA Read attributes
185 matching on Endpoints on both sides (outstanding RDMA Read outgoing on
186 one end is larger than the outstanding RDMA Read incoming on the other
187 end), connection is broken when the number of incoming RDMA Read
188 exceeds the outstanding RDMA Read incoming attribute of the Endpoint.
189 The Consumer can use its own flow control to ensure that it does not
190 post more RDMA Reads then the remote EP outstanding RDMA Read incoming
191 attribute is. Thus, they do not rely on the underlying Transport
192 enforcing it.
193
195 See attributes(5) for descriptions of the following attributes:
196 ┌─────────────────────────────┬─────────────────────────────┐
201 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
202 ├─────────────────────────────┼─────────────────────────────┤
203 │Interface Stability │Standard: uDAPL, 1.1, 1.2 │
204 ├─────────────────────────────┼─────────────────────────────┤
205 │MT-Level │Unsafe │
206 └─────────────────────────────┴─────────────────────────────┘
207
209 libdat(3LIB), attributes(5)
210SunOS 5.11 16 Jul 2004 dat_ep_post_rdma_read(3DAT)