7 .Nd Network Interface Driver Framework
13 is a framework for network interface drivers for
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
20 names, rather than each driver naming them individually.
22 These variables must be set before loading the driver, either via
26 They are all prefixed by
28 where X is the driver name, and Y is the instance number.
29 .Bl -tag -width indent
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.
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.
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.
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.
57 Disables MSI-X interrupts for the device.
59 Specifies a starting core offset to assign queues to.
60 If the value is unspecified or 65535, cores are assigned sequentially across
63 Requests that RX and TX queues not be paired on the same core.
64 If this is zero or not set, an RX and TX queue pair will be assigned to each
66 When set to a non-zero value, TX queues are assigned to cores following the
72 variables can be changed at any time:
73 .Bl -tag -width indent
75 Controls how the transmit ring is serviced.
76 If set to zero, when a frame is submitted to the transmission ring, the same
77 task that is submitting it will service the ring unless there's already a
78 task servicing the TX ring.
79 This ensures that whenever there is a pending transmission,
80 the transmit ring is being serviced.
81 This results in higher transmit throughput.
82 If set to a non-zero value, task returns immediately and the transmit
83 ring is serviced by a different task.
84 This returns control to the caller faster and under high receive load,
85 may result in fewer dropped RX frames.
87 Sets the maximum number of frames to be received at a time.
88 Zero (the default) indicates the default (currently 16) should be used.
91 There are also some global sysctls which can change behaviour for all drivers,
92 and may be changed at any time.
93 .Bl -tag -width indent
94 .It Va net.iflib.min_tx_latency
95 If this is set to a non-zero value, iflib will avoid any attempt to combine
96 multiple transmits, and notify the hardware as quickly as possible of
98 This will lower the maximum throughput, but will also lower transmit latency.
99 .It Va net.iflib.no_tx_batch
100 Some NICs allow processing completed transmit descriptors in batches.
101 Doing so usually increases the transmit throughput by reducing the number of
103 Setting this to a non-zero value will disable the use of this feature.
108 variables are read-only:
109 .Bl -tag -width indent
110 .It Va driver_version
111 A string indicating the internal version of the driver.
114 There are a number of queue state
117 .Bl -tag -width indent
119 The following are repeated for each transmit queue, where Z is the transmit
120 queue instance number:
121 .Bl -tag -width indent
123 Number of consumer abdications in the MP ring for this queue.
124 An abdication occurs on every ring submission when tx_abdicate is true.
126 Number of consumer restarts in the MP ring for this queue.
127 A restart occurs when an attempt to drain a non-empty ring fails,
128 and the ring is already in the STALLED state.
130 Number of consumer stalls in the MP ring for this queue.
131 A stall occurs when an attempt to drain a non-empty ring fails.
133 Number of normal consumer starts in the MP ring for this queue.
134 A start occurs when the MP ring transitions from IDLE to BUSY.
136 Number of drops in the MP ring for this queue.
137 A drop occurs when there is an attempt to add an entry to an MP ring with
140 Number of entries which have been enqueued to the MP ring for this queue.
142 MP (soft) ring state.
143 This privides a snapshot of the current MP ring state, including the producer
144 head and tail indexes, the consumer index, and the state.
145 The state is one of "IDLE", "BUSY",
146 "STALLED", or "ABDICATED".
148 The number of transmit descriptors which have been reclaimed.
151 The number of transmit descriptors which have been processed, but may not yet
154 Descriptors which have been added to the transmit queue,
155 but have not yet been cleaned.
156 This value will include both untransmitted descriptors as well as descriptors
157 which have been processed.
158 .It Va txq_cidx_processed
159 The transmit queue consumer index of the next descriptor to process.
161 The transmit queue consumer index of the oldest descriptor to reclaim.
163 The transmit queue producer index where the next descriptor to transmit will
165 .It Va no_tx_dma_setup
166 Number of times DMA mapping a transmit mbuf failed for reasons other than
168 .It Va txd_encap_efbig
169 Number of times DMA mapping a transmit mbuf failed due to requiring too many
172 Number of times DMA mapping a transmit mbuf failed for any reason
173 (sum of no_tx_dma_setup and txd_encap_efbig)
175 Number of times a descriptor couldn't be added to the transmit ring because
176 the transmit ring was full.
177 .It Va mbuf_defrag_failed
185 result from DMA mapping a transmit mbuf.
189 was called attempting to parse a header.
196 The following are repeated for each receive queue, where Z is the
197 receive queue instance number:
198 .Bl -tag -width indent
199 .It Va rxq_fl0.credits
200 Credits currently available in the receive ring.
202 Current receive ring consumer index.
204 Current receive ring producer index.
208 Additional OIDs useful for driver and iflib development are exposed when the
209 INVARIANTS and/or WITNESS options are enabled in the kernel.
213 This framework was introduced in