NAME
if_rxr_init
,
if_rxr_get
, if_rxr_put
,
if_rxr_livelocked
,
if_rxr_needrefill
,
if_rxr_inuse
, if_rxr_cwm
,
if_rxr_ioctl
,
if_rxr_info_ioctl
—
Interface Receive Ring
accounting
SYNOPSIS
#include
<net/if.h>
void
if_rxr_init
(struct
if_rxring *rxr, unsigned
int lwm, unsigned int
hwm);
unsigned int
if_rxr_get
(struct
if_rxring *rxr, unsigned
int max);
void
if_rxr_put
(struct
if_rxring *rxr, unsigned
int n);
void
if_rxr_livelocked
(struct
if_rxring *rxr);
int
if_rxr_needrefill
(struct
if_rxring *rxr);
unsigned int
if_rxr_inuse
(struct
if_rxring *rxr);
unsigned int
if_rxr_cwm
(struct
if_rxring *rxr);
int
if_rxr_ioctl
(struct if_rxrinfo
*ifri, const char *name,
unsigned int size, struct if_rxring
*rxr);
int
if_rxr_info_ioctl
(struct if_rxrinfo
*ifri, unsigned int n, struct
if_rxring_info *rings);
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.
if_rxr_init
()
initialises the rxr structure. The
lwm argument defines the minimum number of descriptors
the chip needs to operate the ring correctly. hwm is
used to describe the maximum number of descriptors the ring can contain.
if_rxr_get
()
allocates and accounts for up to max descriptors in
the ring as being used.
if_rxr_put
()
returns n receive descriptor slots to the ring.
if_rxr_livelocked
()
can signal that the receive ring is generating too much load.
if_rxr_needrefill
()
signals that the receive ring runs below the low watermark of
descriptors.
if_rxr_inuse
()
can be used to determine how many descriptor slots have been allocated on
the ring.
if_rxr_cwm
()
can be used to determine what the current watermark is for the ring.
The
if_rxr_ioctl
()
and if_rxr_info_ioctl
() functions are provided to
assist drivers in reporting their rings' state to userland via a
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
ifri.
If a driver only has a single receive ring, it
may pass the ring state to
if_rxr_ioctl
()
via the rxr argument. 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
name, otherwise NULL
.
If the driver has multiple receive rings,
it can prepare an array of if_rxring_info structures and pass that to
if_rxr_info_ioctl
()
via rings with the number of elements in the array
passed via n.
For the heuristic to work correctly, a driver
using this API should return all possible descriptor slots with
if_rxr_put
()
before calling if_rxr_get
() to fill them again.
CONTEXT
if_rxr_init
(),
if_rxr_get
(), if_rxr_put
(),
if_rxr_livelocked
(),
if_rxr_needrefill
(),
if_rxr_inuse
(), and
if_rxr_cwm
() can be called during autoconf, from
process context, or from interrupt context.
if_rxr_ioctl
() and
if_rxr_info_ioctl
() can be called from process
context, and only from the context of the process generating an ioctl
call.
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.
RETURN VALUES
if_rxr_get
() returns the number of receive
descriptors available on the ring. The number of descriptors may be less
than the max requested.
if_rxr_needrefill
() returns 1 if the
number of receive descriptor slots currently in use on the ring is below the
value of lwm. Otherwise, zero is returned.
if_rxr_inuse
() returns the number of
receive descriptor slots currently in use on the ring.
if_rxr_cwm
() returns the currently allowed
allocation watermark.
SEE ALSO
HISTORY
The Interface Receive Ring API was originally written by David Gwynne <dlg@openbsd.org>. The API first appeared in OpenBSD 5.6.