'\" te
.\" This manual page is derived from the DAT/uDAPL 1.2 specification.
.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" 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.
.\" 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.
.\" 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]
.TH DAT_EP_RECV_QUERY 3DAT "Jul 16, 2004"
.SH NAME
dat_ep_recv_query \- provide Endpoint receive queue consumption on SRQ
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <\fBdat/udat.h\fR>

DAT_RETURN
    dat_ep_recv_query (
        IN      DAT_EP_HANDLE       ep_handle,
        OUT     DAT_COUNT           *nbufs_allocated,
        OUT     DAT_COUNT           *bufs_alloc_span
    )
.fi

.SH PARAMETERS
.sp
.ne 2
.na
\fB\fIep_handle\fR\fR
.ad
.RS 19n
Handle for an instance of the EP.
.RE

.sp
.ne 2
.na
\fB\fInbufs_allocated\fR\fR
.ad
.RS 19n
The number of buffers at the EP for which completions have not yet been
generated.
.RE

.sp
.ne 2
.na
\fB\fIbufs_alloc_span\fR\fR
.ad
.RS 19n
The span of buffers that EP needs to complete arriving messages.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBdat_ep_recv_query()\fR function provides to the Consumer a snapshot for
Recv buffers on EP. The values for \fInbufs_allocated\fR and
\fIbufs_alloc_span\fR are not defined when \fBDAT_RETURN\fR is not
\fBDAT_SUCCESS\fR.
.sp
.LP
The Provider might not support \fInbufs_allocated\fR, \fIbufs_alloc_span\fR or
both. Check the Provider attribute for EP Recv info support. When the Provider
does not support both of these counts, the return value for the operation can
be \fBDAT_MODEL_NOT_SUPPORTED\fR.
.sp
.LP
If \fInbufs_allocated\fR is not \fINULL\fR, the count pointed to by
\fInbufs_allocated\fR will return a snapshot count of the number of buffers
allocated to \fIep_handle\fR but not yet completed.
.sp
.LP
Once a buffer has been allocated to an EP, it will be completed to the EP
\fIrecv_evd\fR if the EVD has not overflowed. When an EP does not use SRQ, a
buffer is allocated as soon as it is posted to the EP. For EP that uses SRQ, a
buffer is allocated to the EP when EP removes it from SRQ.
.sp
.LP
If \fIbufs_alloc_span\fR is not \fINULL\fR, then the count to which
\fIbufs_alloc_span\fR pointed will return the span of buffers allocated to the
\fIep_handle\fR. The span is the number of additional successful Recv
completions that EP can generate if all the messages it is currently receiving
will complete successfully.
.sp
.LP
If a message sequence number is assigned to all received messages, the buffer
span is the difference between the latest message sequence number of an
allocated buffer minus the latest message sequence number for which completion
has been generated. This sequence number only counts Send messages of remote
Endpoint of the connection.
.sp
.LP
The Message Sequence Number (MSN) represents the order that Send messages were
submitted by the remote Consumer. The ordering of sends is intrinsic to the
definition of a reliable service. Therefore every send message does have a MSN
whether or not the native transport has a field with that name.
.sp
.LP
For both \fInbufs_allocated\fR and \fIbufs_alloc_span\fR, the Provider can
return the reserved value \fBDAT_VALUE_UNKNOWN\fR if it cannot obtain the
requested count at a reasonable cost.
.SH RETURN VALUES
.sp
.ne 2
.na
\fB\fBDAT_SUCCESS\fR\fR
.ad
.RS 27n
The operation was successful.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_PARAMETER\fR\fR
.ad
.RS 27n
Invalid parameter.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_HANDLE\fR\fR
.ad
.RS 27n
The DAT handle ep_handle is invalid.
.RE

.sp
.ne 2
.na
\fB\fBDAT_MODEL_NOT_SUPPORTED\fR\fR
.ad
.RS 27n
The requested Model was not supported by the Provider.
.RE

.SH USAGE
.sp
.LP
If the Provider cannot support the query for \fInbufs_allocated\fR or
\fIbufs_alloc_span\fR, the value returned for that attribute must be
\fBDAT_VALUE_UNKNOWN\fR.
.sp
.LP
An implementation that processes incoming packets out of order and allocates
from SRQs on an arrival basis can have gaps in the MSNs associated with buffers
allocated to an Endpoint.
.sp
.LP
For example, suppose Endpoint X has received buffer fragments for MSNs 19, 22,
and 23. With arrival ordering, the EP would have allocated three buffers from
the SRQ for messages 19, 22, and 23. The number allocated would be 3, but the
span would be 5. The difference of two represents the buffers that will have to
be allocated for messages 20 and 21. They have not yet been allocated, but
messages 22 and 23 will not be delivered until after messages 20 and 21 have
not only had their buffers allocated but have also completed.
.sp
.LP
An implementation can choose to allocate 20 and 21 as soon as any higher buffer
is allocated. This makes sense if you presume that this is a valid connection,
because obviously 20 and 21 are in flight.  However, it creates a greater
vulnerability to Denial Of Service attacks. There are also other implementation
tradeoffs, so the Consumer should accept that different RNICs for iWARP will
employ different strategies on when to perform these allocations.
.sp
.LP
Each implementation will have some method of tracking the receive buffers
already associated with an EP and knowing which buffer matches which incoming
message, though those methods might vary. In particular, there are valid
implementations such as linked lists, where a count of the outstanding buffers
is not instantly available. Such implementations would have to scan the
allocated list to determine both the number of buffers and their span. If such
a scan is necessary, it is important that it be only a single scan. The set of
buffers that was counted must be the same set of buffers for which the span is
reported.
.sp
.LP
The implementation should not scan twice, once to count the buffers and then
again to determine their span. Not only is it inefficient, but it might produce
inconsistent results if buffers were completed or arrived between the two
scans.
.sp
.LP
Other implementations can simply maintain counts of these values to easily
filter invalid packets. If so, these status counters should be updated and
referenced atomically.
.sp
.LP
The implementation must never report \fIn\fR buffers in a span that is less
than \fIn\fR.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Standard: uDAPL, 1.2
_
MT-Level	Unsafe
.TE

.SH SEE ALSO
.sp
.LP
\fBdat_ep_create\fR(3DAT), \fBdat_srq_create\fR(3DAT),
\fBdat_srq_free\fR(3DAT), \fBdat_srq_query\fR(3DAT),
\fBdat_ep_set_watermark\fR(3DAT), \fBlibdat\fR(3LIB), \fBattributes\fR(5)