1.\" $OpenBSD: if_rxr_init.9,v 1.3 2014/09/05 01:06:36 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: September 5 2014 $ 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_ixr_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 unsigned int 37.Fn "if_rxr_inuse" "struct if_rxring *rxr" 38.Ft int 39.Fn "if_rxr_ioctl" "struct if_rxrinfo *ifri" "const char *name" "unsigned int size" "struct if_rxring *rxr" 40.Ft int 41.Fn "if_rxr_info_ioctl" "struct if_rxrinfo *ifri" "unsigned int n" "struct if_rxring_info *rings" 42.Sh DESCRIPTION 43The Interface Receive Ring accounting API provides a mechanism to 44manage the number of available descriptors on a network card's receive 45ring. 46The API restricts the allocation of receive descriptors using a 47heuristic that monitors the use of the ring. 48The number of descriptors granted on the ring may increase over time 49as the interface proves it uses them. 50Additionally, if the algorithm detects that the system is livelocked 51as a result of being overwhelmed with network traffic, it will 52restrict the number of available receive descriptors. 53.Pp 54.Fn if_rxr_init 55initialises the 56.Fa rxr 57structure. 58The 59.Fa lwm 60argument defines the minimum number of descriptors the chip needs 61to operate the ring correctly. 62.Fa hwm 63is used to describe the maximum number of descriptors the ring can contain. 64.Pp 65.Fn if_rxr_get 66allocates and accounts for up to 67.Fa max 68descriptors in the ring as being used. 69.Pp 70.Fn if_rxr_put 71returns 72.Fa n 73receive descriptor slots to the ring. 74.Pp 75.Fn if_rxr_inuse 76can be used to determine how many descriptor slots have been allocated 77on the ring. 78.Pp 79The 80.Fn if_rxr_ioctl 81and 82.Fn if_rxr_info_ioctl 83functions are provided to assist drivers in reporting their rings' 84state to userland via a 85.Dv SIOCGIFRXR 86ioctl request. 87The ioctl data payload will be an ifreq structure, with ifr_data pointing at a 88struct if_rxrinfo in userland memory. 89This if_rxrinfo pointer should be passed via 90.Fa ifri . 91.Pp 92If a driver only has a single receive ring, it may pass the ring state to 93.Fn if_rxr_ioctl 94via the 95.Fa rxr 96argument. 97.Fa size 98is used to describe the size of the mbuf cluster the receive ring uses. 99If the driver wishes to name the ring it can pass it via 100.Fa name , 101otherwise 102.Dv NULL . 103.Pp 104If the driver has multiple receive rings, it can prepare an array 105of if_rxring_info structures and pass that to 106.Fn if_rxr_info_ioctl 107via 108.Fa rings 109with the number of elements in the array passed via 110.Fa n . 111.Pp 112For the heuristic to work correctly, a driver using this API should 113return all possible descriptor slots with 114.Fn if_rxr_put 115before calling 116.Fn if_rxr_get 117to fill them again. 118.Sh CONTEXT 119.Fn if_rxr_init , 120.Fn if_rxr_get , 121.Fn if_rxr_put , 122and 123.Fn if_rxr_inuse 124can be called during autoconf, from process context, or from interrupt context. 125.Pp 126.Fn if_rxr_ioctl 127and 128.Fn if_rxr_info_ioctl 129can be called from process context, and only from the context of 130the process generating an ioctl call. 131.Pp 132It is up to the caller to provide appropriate locking around calls 133to these functions to prevent inconsistencies in the relevant 134if_rxring data structure. 135.Sh RETURN VALUES 136.Fn if_rxr_get 137returns the number of receive descriptors available on the ring. 138The number of descriptors may be less than the 139.Fa max 140requested. 141.Pp 142.Fn if_rxr_inuse 143returns the number of receive descriptor slots currently in use on the ring. 144.Sh SEE ALSO 145.Xr autoconf 9 146.Sh HISTORY 147The Interface Receive Ring API was originally written by 148.An David Gwynne Aq Mt dlg@openbsd.org . 149The API first appeared in 150.Ox 5.6 . 151