1.\" $OpenBSD: if_rxr_init.9,v 1.7 2017/11/17 03:51:32 dlg Exp $ 2.\" 3.\" Copyright (c) 2014 David Gwynne <dlg@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: November 17 2017 $ 18.Dt IF_RXR_INIT 9 19.Os 20.Sh NAME 21.Nm if_rxr_init , 22.Nm if_rxr_get , 23.Nm if_rxr_put , 24.Nm if_rxr_inuse , 25.Nm if_rxr_ioctl , 26.Nm if_rxr_info_ioctl 27.Nd Interface Receive Ring accounting 28.Sh SYNOPSIS 29.In net/if.h 30.Ft void 31.Fn if_rxr_init "struct if_rxring *rxr" "unsigned int lwm" "unsigned int hwm" 32.Ft unsigned int 33.Fn if_rxr_get "struct if_rxring *rxr" "unsigned int max" 34.Ft void 35.Fn if_rxr_put "struct if_rxring *rxr" "unsigned int n" 36.Ft void 37.Fn if_rxr_livelocked "struct if_rxring *rxr" 38.Ft unsigned int 39.Fn if_rxr_inuse "struct if_rxring *rxr" 40.Ft unsigned int 41.Fn if_rxr_cwm "struct if_rxring *rxr" 42.Ft int 43.Fo if_rxr_ioctl 44.Fa "struct if_rxrinfo *ifri" 45.Fa "const char *name" 46.Fa "unsigned int size" 47.Fa "struct if_rxring *rxr" 48.Fc 49.Ft int 50.Fo if_rxr_info_ioctl 51.Fa "struct if_rxrinfo *ifri" 52.Fa "unsigned int n" 53.Fa "struct if_rxring_info *rings" 54.Fc 55.Sh DESCRIPTION 56The Interface Receive Ring accounting API provides a mechanism to 57manage the number of available descriptors on a network card's receive 58ring. 59The API restricts the allocation of receive descriptors using a 60heuristic that monitors the use of the ring. 61The number of descriptors granted on the ring may increase over time 62as the interface proves it uses them. 63Additionally, if the algorithm detects that the system is livelocked 64as a result of being overwhelmed with network traffic, it will 65restrict the number of available receive descriptors. 66.Pp 67.Fn if_rxr_init 68initialises the 69.Fa rxr 70structure. 71The 72.Fa lwm 73argument defines the minimum number of descriptors the chip needs 74to operate the ring correctly. 75.Fa hwm 76is used to describe the maximum number of descriptors the ring can contain. 77.Pp 78.Fn if_rxr_get 79allocates and accounts for up to 80.Fa max 81descriptors in the ring as being used. 82.Pp 83.Fn if_rxr_put 84returns 85.Fa n 86receive descriptor slots to the ring. 87.Pp 88.Fn if_rxr_livelocked 89can signal that that receive ring is generating too much load. 90.Pp 91.Fn if_rxr_inuse 92can be used to determine how many descriptor slots have been allocated 93on the ring. 94.Pp 95.Fn if_rxr_cwm 96can be used to determine what the current watermark is for the ring. 97.Pp 98The 99.Fn if_rxr_ioctl 100and 101.Fn if_rxr_info_ioctl 102functions are provided to assist drivers in reporting their rings' 103state to userland via a 104.Dv SIOCGIFRXR 105ioctl request. 106The ioctl data payload will be an ifreq structure, with ifr_data pointing at a 107struct if_rxrinfo in userland memory. 108This if_rxrinfo pointer should be passed via 109.Fa ifri . 110.Pp 111If a driver only has a single receive ring, it may pass the ring state to 112.Fn if_rxr_ioctl 113via the 114.Fa rxr 115argument. 116.Fa size 117is used to describe the size of the mbuf cluster the receive ring uses. 118If the driver wishes to name the ring it can pass it via 119.Fa name , 120otherwise 121.Dv NULL . 122.Pp 123If the driver has multiple receive rings, it can prepare an array 124of if_rxring_info structures and pass that to 125.Fn if_rxr_info_ioctl 126via 127.Fa rings 128with the number of elements in the array passed via 129.Fa n . 130.Pp 131For the heuristic to work correctly, a driver using this API should 132return all possible descriptor slots with 133.Fn if_rxr_put 134before calling 135.Fn if_rxr_get 136to fill them again. 137.Sh CONTEXT 138.Fn if_rxr_init , 139.Fn if_rxr_get , 140.Fn if_rxr_put , 141.Fn if_rxr_livelocked , 142.Fn if_rxr_inuse , 143and 144.Fn if_rxr_cwm 145can be called during autoconf, from process context, or from interrupt context. 146.Pp 147.Fn if_rxr_ioctl 148and 149.Fn if_rxr_info_ioctl 150can be called from process context, and only from the context of 151the process generating an ioctl call. 152.Pp 153It is up to the caller to provide appropriate locking around calls 154to these functions to prevent inconsistencies in the relevant 155if_rxring data structure. 156.Sh RETURN VALUES 157.Fn if_rxr_get 158returns the number of receive descriptors available on the ring. 159The number of descriptors may be less than the 160.Fa max 161requested. 162.Pp 163.Fn if_rxr_inuse 164returns the number of receive descriptor slots currently in use on the ring. 165.Pp 166.Fn if_rxr_cwm 167returns the currently allowed allocation watermark. 168.Sh SEE ALSO 169.Xr autoconf 9 170.Sh HISTORY 171The Interface Receive Ring API was originally written by 172.An David Gwynne Aq Mt dlg@openbsd.org . 173The API first appeared in 174.Ox 5.6 . 175