.\"	$OpenBSD: if_rxr_init.9,v 1.3 2014/09/05 01:06:36 dlg Exp $
.\"
.\" Copyright (c) 2014 David Gwynne <dlg@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: September 5 2014 $
.Dt IF_RXR_INIT 9
.Os
.Sh NAME
.Nm if_rxr_init ,
.Nm if_rxr_get ,
.Nm if_rxr_put ,
.Nm if_ixr_inuse ,
.Nm if_rxr_ioctl ,
.Nm if_rxr_info_ioctl
.Nd Interface Receive Ring accounting
.Sh SYNOPSIS
.In net/if.h
.Ft void
.Fn "if_rxr_init" "struct if_rxring *rxr" "unsigned int lwm" "unsigned int hwm"
.Ft unsigned int
.Fn "if_rxr_get" "struct if_rxring *rxr" "unsigned int max"
.Ft void
.Fn "if_rxr_put" "struct if_rxring *rxr" "unsigned int n"
.Ft unsigned int
.Fn "if_rxr_inuse" "struct if_rxring *rxr"
.Ft int
.Fn "if_rxr_ioctl" "struct if_rxrinfo *ifri" "const char *name" "unsigned int size" "struct if_rxring *rxr"
.Ft int
.Fn "if_rxr_info_ioctl" "struct if_rxrinfo *ifri" "unsigned int n" "struct if_rxring_info *rings"
.Sh DESCRIPTION
The Interface Receive Ring accounting API provides a mechanism to
manage the number of available descriptors on a network card's receive
ring.
The API restricts the allocation of receive descriptors using a
heuristic that monitors the use of the ring.
The number of descriptors granted on the ring may increase over time
as the interface proves it uses them.
Additionally, if the algorithm detects that the system is livelocked
as a result of being overwhelmed with network traffic, it will
restrict the number of available receive descriptors.
.Pp
.Fn if_rxr_init
initialises the
.Fa rxr
structure.
The
.Fa lwm
argument defines the minimum number of descriptors the chip needs
to operate the ring correctly.
.Fa hwm
is used to describe the maximum number of descriptors the ring can contain.
.Pp
.Fn if_rxr_get
allocates and accounts for up to
.Fa max
descriptors in the ring as being used.
.Pp
.Fn if_rxr_put
returns
.Fa n
receive descriptor slots to the ring.
.Pp
.Fn if_rxr_inuse
can be used to determine how many descriptor slots have been allocated
on the ring.
.Pp
The
.Fn if_rxr_ioctl
and
.Fn if_rxr_info_ioctl
functions are provided to assist drivers in reporting their rings'
state to userland via a
.Dv SIOCGIFRXR
ioctl request.
The ioctl data payload will be an ifreq structure, with ifr_data pointing at a
struct if_rxrinfo in userland memory.
This if_rxrinfo pointer should be passed via
.Fa ifri .
.Pp
If a driver only has a single receive ring, it may pass the ring state to
.Fn if_rxr_ioctl
via the
.Fa rxr
argument.
.Fa size
is used to describe the size of the mbuf cluster the receive ring uses.
If the driver wishes to name the ring it can pass it via
.Fa name ,
otherwise
.Dv NULL .
.Pp
If the driver has multiple receive rings, it can prepare an array
of if_rxring_info structures and pass that to
.Fn if_rxr_info_ioctl
via
.Fa rings
with the number of elements in the array passed via
.Fa n .
.Pp
For the heuristic to work correctly, a driver using this API should
return all possible descriptor slots with
.Fn if_rxr_put
before calling
.Fn if_rxr_get
to fill them again.
.Sh CONTEXT
.Fn if_rxr_init ,
.Fn if_rxr_get ,
.Fn if_rxr_put ,
and
.Fn if_rxr_inuse
can be called during autoconf, from process context, or from interrupt context.
.Pp
.Fn if_rxr_ioctl
and
.Fn if_rxr_info_ioctl
can be called from process context, and only from the context of
the process generating an ioctl call.
.Pp
It is up to the caller to provide appropriate locking around calls
to these functions to prevent inconsistencies in the relevant
if_rxring data structure.
.Sh RETURN VALUES
.Fn if_rxr_get
returns the number of receive descriptors available on the ring.
The number of descriptors may be less than the
.Fa max
requested.
.Pp
.Fn if_rxr_inuse
returns the number of receive descriptor slots currently in use on the ring.
.Sh SEE ALSO
.Xr autoconf 9
.Sh HISTORY
The Interface Receive Ring API was originally written by
.An David Gwynne Aq Mt dlg@openbsd.org .
The API first appeared in
.Ox 5.6 .