share/man/man3dat/dat_ep_recv_query.3dat

   1 '\" te
   2 .\" This manual page is derived from the DAT/uDAPL 1.2 specification.
   3 .\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH DAT_EP_RECV_QUERY 3DAT "Jul 16, 2004"
   8 .SH NAME
   9 dat_ep_recv_query \- provide Endpoint receive queue consumption on SRQ
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ]
  14 #include <\fBdat/udat.h\fR>
  15
  16 DAT_RETURN
  17     dat_ep_recv_query (
  18         IN      DAT_EP_HANDLE       ep_handle,
  19         OUT     DAT_COUNT           *nbufs_allocated,
  20         OUT     DAT_COUNT           *bufs_alloc_span
  21     )
  22 .fi
  23
  24 .SH PARAMETERS
  25 .sp
  26 .ne 2
  27 .na
  28 \fB\fIep_handle\fR\fR
  29 .ad
  30 .RS 19n
  31 Handle for an instance of the EP.
  32 .RE
  33
  34 .sp
  35 .ne 2
  36 .na
  37 \fB\fInbufs_allocated\fR\fR
  38 .ad
  39 .RS 19n
  40 The number of buffers at the EP for which completions have not yet been
  41 generated.
  42 .RE
  43
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fIbufs_alloc_span\fR\fR
  48 .ad
  49 .RS 19n
  50 The span of buffers that EP needs to complete arriving messages.
  51 .RE
  52
  53 .SH DESCRIPTION
  54 .sp
  55 .LP
  56 The \fBdat_ep_recv_query()\fR function provides to the Consumer a snapshot for
  57 Recv buffers on EP. The values for \fInbufs_allocated\fR and
  58 \fIbufs_alloc_span\fR are not defined when \fBDAT_RETURN\fR is not
  59 \fBDAT_SUCCESS\fR.
  60 .sp
  61 .LP
  62 The Provider might not support \fInbufs_allocated\fR, \fIbufs_alloc_span\fR or
  63 both. Check the Provider attribute for EP Recv info support. When the Provider
  64 does not support both of these counts, the return value for the operation can
  65 be \fBDAT_MODEL_NOT_SUPPORTED\fR.
  66 .sp
  67 .LP
  68 If \fInbufs_allocated\fR is not \fINULL\fR, the count pointed to by
  69 \fInbufs_allocated\fR will return a snapshot count of the number of buffers
  70 allocated to \fIep_handle\fR but not yet completed.
  71 .sp
  72 .LP
  73 Once a buffer has been allocated to an EP, it will be completed to the EP
  74 \fIrecv_evd\fR if the EVD has not overflowed. When an EP does not use SRQ, a
  75 buffer is allocated as soon as it is posted to the EP. For EP that uses SRQ, a
  76 buffer is allocated to the EP when EP removes it from SRQ.
  77 .sp
  78 .LP
  79 If \fIbufs_alloc_span\fR is not \fINULL\fR, then the count to which
  80 \fIbufs_alloc_span\fR pointed will return the span of buffers allocated to the
  81 \fIep_handle\fR. The span is the number of additional successful Recv
  82 completions that EP can generate if all the messages it is currently receiving
  83 will complete successfully.
  84 .sp
  85 .LP
  86 If a message sequence number is assigned to all received messages, the buffer
  87 span is the difference between the latest message sequence number of an
  88 allocated buffer minus the latest message sequence number for which completion
  89 has been generated. This sequence number only counts Send messages of remote
  90 Endpoint of the connection.
  91 .sp
  92 .LP
  93 The Message Sequence Number (MSN) represents the order that Send messages were
  94 submitted by the remote Consumer. The ordering of sends is intrinsic to the
  95 definition of a reliable service. Therefore every send message does have a MSN
  96 whether or not the native transport has a field with that name.
  97 .sp
  98 .LP
  99 For both \fInbufs_allocated\fR and \fIbufs_alloc_span\fR, the Provider can
 100 return the reserved value \fBDAT_VALUE_UNKNOWN\fR if it cannot obtain the
 101 requested count at a reasonable cost.
 102 .SH RETURN VALUES
 103 .sp
 104 .ne 2
 105 .na
 106 \fB\fBDAT_SUCCESS\fR\fR
 107 .ad
 108 .RS 27n
 109 The operation was successful.
 110 .RE
 111
 112 .sp
 113 .ne 2
 114 .na
 115 \fB\fBDAT_INVALID_PARAMETER\fR\fR
 116 .ad
 117 .RS 27n
 118 Invalid parameter.
 119 .RE
 120
 121 .sp
 122 .ne 2
 123 .na
 124 \fB\fBDAT_INVALID_HANDLE\fR\fR
 125 .ad
 126 .RS 27n
 127 The DAT handle ep_handle is invalid.
 128 .RE
 129
 130 .sp
 131 .ne 2
 132 .na
 133 \fB\fBDAT_MODEL_NOT_SUPPORTED\fR\fR
 134 .ad
 135 .RS 27n
 136 The requested Model was not supported by the Provider.
 137 .RE
 138
 139 .SH USAGE
 140 .sp
 141 .LP
 142 If the Provider cannot support the query for \fInbufs_allocated\fR or
 143 \fIbufs_alloc_span\fR, the value returned for that attribute must be
 144 \fBDAT_VALUE_UNKNOWN\fR.
 145 .sp
 146 .LP
 147 An implementation that processes incoming packets out of order and allocates
 148 from SRQs on an arrival basis can have gaps in the MSNs associated with buffers
 149 allocated to an Endpoint.
 150 .sp
 151 .LP
 152 For example, suppose Endpoint X has received buffer fragments for MSNs 19, 22,
 153 and 23. With arrival ordering, the EP would have allocated three buffers from
 154 the SRQ for messages 19, 22, and 23. The number allocated would be 3, but the
 155 span would be 5. The difference of two represents the buffers that will have to
 156 be allocated for messages 20 and 21. They have not yet been allocated, but
 157 messages 22 and 23 will not be delivered until after messages 20 and 21 have
 158 not only had their buffers allocated but have also completed.
 159 .sp
 160 .LP
 161 An implementation can choose to allocate 20 and 21 as soon as any higher buffer
 162 is allocated. This makes sense if you presume that this is a valid connection,
 163 because obviously 20 and 21 are in flight.  However, it creates a greater
 164 vulnerability to Denial Of Service attacks. There are also other implementation
 165 tradeoffs, so the Consumer should accept that different RNICs for iWARP will
 166 employ different strategies on when to perform these allocations.
 167 .sp
 168 .LP
 169 Each implementation will have some method of tracking the receive buffers
 170 already associated with an EP and knowing which buffer matches which incoming
 171 message, though those methods might vary. In particular, there are valid
 172 implementations such as linked lists, where a count of the outstanding buffers
 173 is not instantly available. Such implementations would have to scan the
 174 allocated list to determine both the number of buffers and their span. If such
 175 a scan is necessary, it is important that it be only a single scan. The set of
 176 buffers that was counted must be the same set of buffers for which the span is
 177 reported.
 178 .sp
 179 .LP
 180 The implementation should not scan twice, once to count the buffers and then
 181 again to determine their span. Not only is it inefficient, but it might produce
 182 inconsistent results if buffers were completed or arrived between the two
 183 scans.
 184 .sp
 185 .LP
 186 Other implementations can simply maintain counts of these values to easily
 187 filter invalid packets. If so, these status counters should be updated and
 188 referenced atomically.
 189 .sp
 190 .LP
 191 The implementation must never report \fIn\fR buffers in a span that is less
 192 than \fIn\fR.
 193 .SH ATTRIBUTES
 194 .sp
 195 .LP
 196 See \fBattributes\fR(5) for descriptions of the following attributes:
 197 .sp
 198
 199 .sp
 200 .TS
 201 box;
 202 c | c
 203 l | l .
 204 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 205 _
 206 Interface Stability     Standard: uDAPL, 1.2
 207 _
 208 MT-Level        Unsafe
 209 .TE
 210
 211 .SH SEE ALSO
 212 .sp
 213 .LP
 214 \fBdat_ep_create\fR(3DAT), \fBdat_srq_create\fR(3DAT),
 215 \fBdat_srq_free\fR(3DAT), \fBdat_srq_query\fR(3DAT),
 216 \fBdat_ep_set_watermark\fR(3DAT), \fBlibdat\fR(3LIB), \fBattributes\fR(5)