1.\" $OpenBSD: if_rxr_init.9,v 1.10 2022/09/10 08:50:53 jsg 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: September 10 2022 $ 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_livelocked , 25.Nm if_rxr_needrefill , 26.Nm if_rxr_inuse , 27.Nm if_rxr_cwm , 28.Nm if_rxr_ioctl , 29.Nm if_rxr_info_ioctl 30.Nd Interface Receive Ring accounting 31.Sh SYNOPSIS 32.In net/if.h 33.Ft void 34.Fn if_rxr_init "struct if_rxring *rxr" "unsigned int lwm" "unsigned int hwm" 35.Ft unsigned int 36.Fn if_rxr_get "struct if_rxring *rxr" "unsigned int max" 37.Ft void 38.Fn if_rxr_put "struct if_rxring *rxr" "unsigned int n" 39.Ft void 40.Fn if_rxr_livelocked "struct if_rxring *rxr" 41.Ft int 42.Fn if_rxr_needrefill "struct if_rxring *rxr" 43.Ft unsigned int 44.Fn if_rxr_inuse "struct if_rxring *rxr" 45.Ft unsigned int 46.Fn if_rxr_cwm "struct if_rxring *rxr" 47.Ft int 48.Fo if_rxr_ioctl 49.Fa "struct if_rxrinfo *ifri" 50.Fa "const char *name" 51.Fa "unsigned int size" 52.Fa "struct if_rxring *rxr" 53.Fc 54.Ft int 55.Fo if_rxr_info_ioctl 56.Fa "struct if_rxrinfo *ifri" 57.Fa "unsigned int n" 58.Fa "struct if_rxring_info *rings" 59.Fc 60.Sh DESCRIPTION 61The Interface Receive Ring accounting API provides a mechanism to 62manage the number of available descriptors on a network card's receive 63ring. 64The API restricts the allocation of receive descriptors using a 65heuristic that monitors the use of the ring. 66The number of descriptors granted on the ring may increase over time 67as the interface proves it uses them. 68Additionally, if the algorithm detects that the system is livelocked 69as a result of being overwhelmed with network traffic, it will 70restrict the number of available receive descriptors. 71.Pp 72.Fn if_rxr_init 73initialises the 74.Fa rxr 75structure. 76The 77.Fa lwm 78argument defines the minimum number of descriptors the chip needs 79to operate the ring correctly. 80.Fa hwm 81is used to describe the maximum number of descriptors the ring can contain. 82.Pp 83.Fn if_rxr_get 84allocates and accounts for up to 85.Fa max 86descriptors in the ring as being used. 87.Pp 88.Fn if_rxr_put 89returns 90.Fa n 91receive descriptor slots to the ring. 92.Pp 93.Fn if_rxr_livelocked 94can signal that the receive ring is generating too much load. 95.Pp 96.Fn if_rxr_needrefill 97signals that the receive ring runs below the low watermark of descriptors. 98.Pp 99.Fn if_rxr_inuse 100can be used to determine how many descriptor slots have been allocated 101on the ring. 102.Pp 103.Fn if_rxr_cwm 104can be used to determine what the current watermark is for the ring. 105.Pp 106The 107.Fn if_rxr_ioctl 108and 109.Fn if_rxr_info_ioctl 110functions are provided to assist drivers in reporting their rings' 111state to userland via a 112.Dv SIOCGIFRXR 113ioctl request. 114The ioctl data payload will be an ifreq structure, with ifr_data pointing at a 115struct if_rxrinfo in userland memory. 116This if_rxrinfo pointer should be passed via 117.Fa ifri . 118.Pp 119If a driver only has a single receive ring, it may pass the ring state to 120.Fn if_rxr_ioctl 121via the 122.Fa rxr 123argument. 124.Fa size 125is used to describe the size of the mbuf cluster the receive ring uses. 126If the driver wishes to name the ring it can pass it via 127.Fa name , 128otherwise 129.Dv NULL . 130.Pp 131If the driver has multiple receive rings, it can prepare an array 132of if_rxring_info structures and pass that to 133.Fn if_rxr_info_ioctl 134via 135.Fa rings 136with the number of elements in the array passed via 137.Fa n . 138.Pp 139For the heuristic to work correctly, a driver using this API should 140return all possible descriptor slots with 141.Fn if_rxr_put 142before calling 143.Fn if_rxr_get 144to fill them again. 145.Sh CONTEXT 146.Fn if_rxr_init , 147.Fn if_rxr_get , 148.Fn if_rxr_put , 149.Fn if_rxr_livelocked , 150.Fn if_rxr_needrefill , 151.Fn if_rxr_inuse , 152and 153.Fn if_rxr_cwm 154can be called during autoconf, from process context, or from interrupt context. 155.Pp 156.Fn if_rxr_ioctl 157and 158.Fn if_rxr_info_ioctl 159can be called from process context, and only from the context of 160the process generating an ioctl call. 161.Pp 162It is up to the caller to provide appropriate locking around calls 163to these functions to prevent inconsistencies in the relevant 164if_rxring data structure. 165.Sh RETURN VALUES 166.Fn if_rxr_get 167returns the number of receive descriptors available on the ring. 168The number of descriptors may be less than the 169.Fa max 170requested. 171.Pp 172.Fn if_rxr_needrefill 173returns 1 if the number of receive descriptor slots currently in use on the 174ring is below the value of 175.Fa lwm . 176Otherwise, zero is returned. 177.Pp 178.Fn if_rxr_inuse 179returns the number of receive descriptor slots currently in use on the ring. 180.Pp 181.Fn if_rxr_cwm 182returns the currently allowed allocation watermark. 183.Sh SEE ALSO 184.Xr autoconf 9 185.Sh HISTORY 186The Interface Receive Ring API was originally written by 187.An David Gwynne Aq Mt dlg@openbsd.org . 188The API first appeared in 189.Ox 5.6 . 190