share/man/man4/iflib.4

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