xref: /freebsd/share/man/man4/iflib.4 (revision 2eb4d8dc723da3cf7d735a3226ae49da4c8c5dbc)
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.It Va core_offset
59Specifies a starting core offset to assign queues to.
60If the value is unspecified or 65535, cores are assigned sequentially across
61controllers.
62.It Va separate_txrx
63Requests that RX and TX queues not be paired on the same core.
64If this is zero or not set, an RX and TX queue pair will be assigned to each
65core.
66When set to a non-zero value, TX queues are assigned to cores following the
67last RX queue.
68.El
69.Pp
70These
71.Xr sysctl 8
72variables can be changed at any time:
73.Bl -tag -width indent
74.It Va tx_abdicate
75Controls how the transmit ring is serviced.
76If set to zero, when a frame is submitted to the transmission ring, the same
77task that is submitting it will service the ring unless there's already a
78task servicing the TX ring.
79This ensures that whenever there is a pending transmission,
80the transmit ring is being serviced.
81This results in higher transmit throughput.
82If set to a non-zero value, task returns immediately and the transmit
83ring is serviced by a different task.
84This returns control to the caller faster and under high receive load,
85may result in fewer dropped RX frames.
86.It Va rx_budget
87Sets the maximum number of frames to be received at a time.
88Zero (the default) indicates the default (currently 16) should be used.
89.El
90.Pp
91There are also some global sysctls which can change behaviour for all drivers,
92and may be changed at any time.
93.Bl -tag -width indent
94.It Va net.iflib.min_tx_latency
95If this is set to a non-zero value, iflib will avoid any attempt to combine
96multiple transmits, and notify the hardware as quickly as possible of
97new descriptors.
98This will lower the maximum throughput, but will also lower transmit latency.
99.It Va net.iflib.no_tx_batch
100Some NICs allow processing completed transmit descriptors in batches.
101Doing so usually increases the transmit throughput by reducing the number of
102transmit interrupts.
103Setting this to a non-zero value will disable the use of this feature.
104.El
105.Pp
106These
107.Xr sysctl 8
108variables are read-only:
109.Bl -tag -width indent
110.It Va driver_version
111A string indicating the internal version of the driver.
112.El
113.Pp
114There are a number of queue state
115.Xr sysctl 8
116variables as well:
117.Bl -tag -width indent
118.It Va txqZ
119The following are repeated for each transmit queue, where Z is the transmit
120queue instance number:
121.Bl -tag -width indent
122.It Va r_abdications
123Number of consumer abdications in the MP ring for this queue.
124An abdication occurs on every ring submission when tx_abdicate is true.
125.It Va r_restarts
126Number of consumer restarts in the MP ring for this queue.
127A restart occurs when an attempt to drain a non-empty ring fails,
128and the ring is already in the STALLED state.
129.It Va r_stalls
130Number of consumer stalls in the MP ring for this queue.
131A stall occurs when an attempt to drain a non-empty ring fails.
132.It Va r_starts
133Number of normal consumer starts in the MP ring for this queue.
134A start occurs when the MP ring transitions from IDLE to BUSY.
135.It Va r_drops
136Number of drops in the MP ring for this queue.
137A drop occurs when there is an attempt to add an entry to an MP ring with
138no available space.
139.It Va r_enqueues
140Number of entries which have been enqueued to the MP ring for this queue.
141.It Va ring_state
142MP (soft) ring state.
143This privides a snapshot of the current MP ring state, including the producer
144head and tail indexes, the consumer index, and the state.
145The state is one of "IDLE", "BUSY",
146"STALLED", or "ABDICATED".
147.It Va txq_cleaned
148The number of transmit descriptors which have been reclaimed.
149Total cleaned.
150.It Va txq_processed
151The number of transmit descriptors which have been processed, but may not yet
152have been reclaimed.
153.It Va txq_in_use
154Descriptors which have been added to the transmit queue,
155but have not yet been cleaned.
156This value will include both untransmitted descriptors as well as descriptors
157which have been processed.
158.It Va txq_cidx_processed
159The transmit queue consumer index of the next descriptor to process.
160.It Va txq_cidx
161The transmit queue consumer index of the oldest descriptor to reclaim.
162.It Va txq_pidx
163The transmit queue producer index where the next descriptor to transmit will
164be inserted.
165.It Va no_tx_dma_setup
166Number of times DMA mapping a transmit mbuf failed for reasons other than
167.Er EFBIG .
168.It Va txd_encap_efbig
169Number of times DMA mapping a transmit mbuf failed due to requiring too many
170segments.
171.It Va tx_map_failed
172Number of times DMA mapping a transmit mbuf failed for any reason
173(sum of no_tx_dma_setup and txd_encap_efbig)
174.It Va no_desc_avail
175Number of times a descriptor couldn't be added to the transmit ring because
176the transmit ring was full.
177.It Va mbuf_defrag_failed
178Number of times both
179.Xr m_collapse 9
180and
181.Xr m_defrag 9
182failed after an
183.Er EFBIG
184error
185result from DMA mapping a transmit mbuf.
186.It Va m_pullups
187Number of times
188.Xr m_pullup 9
189was called attempting to parse a header.
190.It Va mbuf_defrag
191Number of times
192.Xr m_defrag 9
193was called.
194.El
195.It Va rxqZ
196The following are repeated for each receive queue, where Z is the
197receive queue instance number:
198.Bl -tag -width indent
199.It Va rxq_fl0.credits
200Credits currently available in the receive ring.
201.It Va rxq_fl0.cidx
202Current receive ring consumer index.
203.It Va rxq_fl0.pidx
204Current receive ring producer index.
205.El
206.El
207.Pp
208Additional OIDs useful for driver and iflib development are exposed when the
209INVARIANTS and/or WITNESS options are enabled in the kernel.
210.Sh SEE ALSO
211.Xr iflib 9
212.Sh HISTORY
213This framework was introduced in
214.Fx 11.0 .
215