unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OpenBSD-5.7)
Page:
Section:
Apropos / Subsearch:
optional field

IF_RXR_INIT(9)           BSD Kernel Developer's Manual          IF_RXR_INIT(9)

NAME
     if_rxr_init, if_rxr_get, if_rxr_put, if_ixr_inuse, if_rxr_ioctl,
     if_rxr_info_ioctl -- Interface Receive Ring accounting

SYNOPSIS
     #include <&lt;net/if.h>&gt;

     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);

     unsigned int
     if_rxr_inuse(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 cor-
     rectly.  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_inuse() can be used to determine how many descriptor slots have
     been allocated on 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 struc-
     ture, 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(), and if_rxr_inuse() 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 con-
     text, 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_inuse() returns the number of receive descriptor slots currently
     in use on the ring.

SEE ALSO
     autoconf(9)

HISTORY
     The Interface Receive Ring API was originally written by David Gwynne
     <dlg@openbsd.org>.  The API first appeared in OpenBSD 5.6.

BSD                            September 5, 2014                           BSD