1.\" $FreeBSD$ 2.Dd September 27, 2018 3.Dt IFLIB 4 4.Os 5.Sh NAME 6.Nm iflib 7.Nd Network Interface Driver Framework 8.Sh SYNOPSIS 9.Cd "device pci" 10.Cd "device iflib" 11.Sh DESCRIPTION 12.Nm 13is a framework for network interface drivers for 14.Fx . 15It is designed to remove a large amount of the boilerplate that is often 16needed for modern network interface devices, allowing driver authors to 17focus on the specific code needed for their hardware. 18This allows for a shared set of 19.Xr sysctl 8 20names, rather than each driver naming them individually. 21.Sh SYSCTL VARIABLES 22These variables must be set before loading the driver, either via 23.Xr loader.conf 5 24or through the use of 25.Xr kenv 1 . 26They are all prefixed by 27.Va dev.X.Y.iflib\&. 28where X is the driver name, and Y is the instance number. 29.Bl -tag -width indent 30.It Va override_nrxds 31Override the number of RX descriptors for each queue. 32The value is a comma separated list of positive integers. 33Some drivers only use a single value, but others may use more. 34These numbers must be powers of two, and zero means to use the default. 35Individual drivers may have additional restrictions on allowable values. 36Defaults to all zeros. 37.It Va override_ntxds 38Override the number of TX descriptors for each queue. 39The value is a comma separated list of positive integers. 40Some drivers only use a single value, but others may use more. 41These numbers must be powers of two, and zero means to use the default. 42Individual drivers may have additional restrictions on allowable values. 43Defaults to all zeros. 44.It Va override_qs_enable 45When set, allows the number of transmit and receive queues to be different. 46If not set, the lower of the number of TX or RX queues will be used for both. 47.It Va override_nrxqs 48Set the number of RX queues. 49If zero, the number of RX queues is derived from the number of cores on the 50socket connected to the controller. 51Defaults to 0. 52.It Va override_ntxqs 53Set the number of TX queues. 54If zero, the number of TX queues is derived from the number of cores on the 55socket connected to the controller. 56.It Va disable_msix 57Disables MSI-X interrupts for the device. 58.El 59.Pp 60These 61.Xr sysctl 8 62variables can be changed at any time: 63.Bl -tag -width indent 64.It Va tx_abdicate 65Controls how the transmit ring is serviced. 66If set to zero, when a frame is submitted to the transmission ring, the same 67task that is submitting it will service the ring unless there's already a 68task servicing the TX ring. 69This ensures that whenever there is a pending transmission, 70the transmit ring is being serviced. 71This results in higher transmit throughput. 72If set to a non-zero value, task returns immediately and the transmit 73ring is serviced by a different task. 74This returns control to the caller faster and under high receive load, 75may result in fewer dropped RX frames. 76.It Va rx_budget 77Sets the maximum number of frames to be received at a time. 78Zero (the default) indicates the default (currently 16) should be used. 79.El 80.Pp 81There are also some global sysctls which can change behaviour for all drivers, 82and may be changed at any time. 83.Bl -tag -width indent 84.It Va net.iflib.min_tx_latency 85If this is set to a non-zero value, iflib will avoid any attempt to combine 86multiple transmits, and notify the hardware as quickly as possible of 87new descriptors. 88This will lower the maximum throughput, but will also lower transmit latency. 89.It Va net.iflib.no_tx_batch 90Some NICs allow processing completed transmit descriptors in batches. 91Doing so usually increases the transmit throughput by reducing the number of 92transmit interrupts. 93Setting this to a non-zero value will disable the use of this feature. 94.El 95.Pp 96These 97.Xr sysctl 8 98variables are read-only: 99.Bl -tag -width indent 100.It Va driver_version 101A string indicating the internal version of the driver. 102.El 103.Pp 104There are a number of queue state 105.Xr sysctl 8 106variables as well: 107.Bl -tag -width indent 108.It Va txqZ 109The following are repeated for each transmit queue, where Z is the transmit 110queue instance number: 111.Bl -tag -width indent 112.It Va r_abdications 113Number of consumer abdications in the MP ring for this queue. 114An abdication occurs on every ring submission when tx_abdicate is true. 115.It Va r_restarts 116Number of consumer restarts in the MP ring for this queue. 117A restart occurs when an attempt to drain a non-empty ring fails, 118and the ring is already in the STALLED state. 119.It Va r_stalls 120Number of consumer stalls in the MP ring for this queue. 121A stall occurs when an attempt to drain a non-empty ring fails. 122.It Va r_starts 123Number of normal consumer starts in the MP ring for this queue. 124A start occurs when the MP ring transitions from IDLE to BUSY. 125.It Va r_drops 126Number of drops in the MP ring for this queue. 127A drop occurs when there is an attempt to add an entry to an MP ring with 128no available space. 129.It Va r_enqueues 130Number of entries which have been enqueued to the MP ring for this queue. 131.It Va ring_state 132MP (soft) ring state. 133This privides a snapshot of the current MP ring state, including the producer 134head and tail indexes, the consumer index, and the state. 135The state is one of "IDLE", "BUSY", 136"STALLED", or "ABDICATED". 137.It Va txq_cleaned 138The number of transmit descriptors which have been reclaimed. 139Total cleaned. 140.It Va txq_processed 141The number of transmit descriptors which have been processed, but may not yet 142have been reclaimed. 143.It Va txq_in_use 144Descriptors which have been added to the transmit queue, 145but have not yet been cleaned. 146This value will include both untransmitted descriptors as well as descriptors 147which have been processed. 148.It Va txq_cidx_processed 149The transmit queue consumer index of the next descriptor to process. 150.It Va txq_cidx 151The transmit queue consumer index of the oldest descriptor to reclaim. 152.It Va txq_pidx 153The transmit queue producer index where the next descriptor to transmit will 154be inserted. 155.It Va no_tx_dma_setup 156Number of times DMA mapping a transmit mbuf failed for reasons other than 157.Er EFBIG . 158.It Va txd_encap_efbig 159Number of times DMA mapping a transmit mbuf failed due to requiring too many 160segments. 161.It Va tx_map_failed 162Number of times DMA mapping a transmit mbuf failed for any reason 163(sum of no_tx_dma_setup and txd_encap_efbig) 164.It Va no_desc_avail 165Number of times a descriptor couldn't be added to the transmit ring because 166the transmit ring was full. 167.It Va mbuf_defrag_failed 168Number of times both 169.Xr m_collapse 9 170and 171.Xr m_defrag 9 172failed after an 173.Er EFBIG 174error 175result from DMA mapping a transmit mbuf. 176.It Va m_pullups 177Number of times 178.Xr m_pullup 9 179was called attempting to parse a header. 180.It Va mbuf_defrag 181Number of times 182.Xr m_defrag 9 183was called. 184.El 185.It Va rxqZ 186The following are repeated for each receive queue, where Z is the 187receive queue instance number: 188.Bl -tag -width indent 189.It Va rxq_fl0.credits 190Credits currently available in the receive ring. 191.It Va rxq_fl0.cidx 192Current receive ring consumer index. 193.It Va rxq_fl0.pidx 194Current receive ring producer index. 195.El 196.El 197.Pp 198Additional OIDs useful for driver and iflib development are exposed when the 199INVARIANTS and/or WITNESS options are enabled in the kernel. 200.Sh SEE ALSO 201.Xr iflib 9 202.Sh HISTORY 203This framework was introduced in 204.Fx 11.0 . 205