FreeBSD manual
download PDF document: iflib.4.pdf
IFLIB(4) FreeBSD Kernel Interfaces Manual IFLIB(4)
NAME
iflib - Network Interface Driver Framework
SYNOPSIS
device pci
device iflib
DESCRIPTION
iflib is a framework for network interface drivers for FreeBSD. It is
designed to remove a large amount of the boilerplate that is often needed
for modern network interface devices, allowing driver authors to focus on
the specific code needed for their hardware. This allows for a shared
set of sysctl(8) names, rather than each driver naming them individually.
SYSCTL VARIABLES
These variables must be set before loading the driver, either via
loader.conf(5) or through the use of kenv(1). They are all prefixed by
dev.X.Y.iflib. where X is the driver name, and Y is the instance number.
override_nrxds
Override the number of RX descriptors for each queue. The value
is a comma separated list of positive integers. Some drivers
only use a single value, but others may use more. These numbers
must be powers of two, and zero means to use the default.
Individual drivers may have additional restrictions on allowable
values. Defaults to all zeros.
override_ntxds
Override the number of TX descriptors for each queue. The value
is a comma separated list of positive integers. Some drivers
only use a single value, but others may use more. These numbers
must be powers of two, and zero means to use the default.
Individual drivers may have additional restrictions on allowable
values. Defaults to all zeros.
override_qs_enable
When set, allows the number of transmit and receive queues to be
different. If not set, the lower of the number of TX or RX
queues will be used for both.
override_nrxqs
Set the number of RX queues. If zero, the number of RX queues is
derived from the number of cores on the socket connected to the
controller. Defaults to 0.
override_ntxqs
Set the number of TX queues. If zero, the number of TX queues is
derived from the number of cores on the socket connected to the
controller.
disable_msix
Disables MSI-X interrupts for the device.
core_offset
Specifies a starting core offset to assign queues to. If the
value is unspecified or 65535, cores are assigned sequentially
across controllers.
These sysctl(8) variables can be changed at any time:
tx_abdicate
Controls how the transmit ring is serviced. If set to zero, when
a frame is submitted to the transmission ring, the same task that
is submitting it will service the ring unless there's already a
task servicing the TX ring. This ensures that whenever there is
a pending transmission, the transmit ring is being serviced.
This results in higher transmit throughput. If set to a non-zero
value, task returns immediately and the transmit ring is serviced
by a different task. This returns control to the caller faster
and under high receive load, may result in fewer dropped RX
frames.
rx_budget
Sets the maximum number of frames to be received at a time. Zero
(the default) indicates the default (currently 16) should be
used.
There are also some global sysctls which can change behaviour for all
drivers, and may be changed at any time.
net.iflib.min_tx_latency
If this is set to a non-zero value, iflib will avoid any attempt
to combine multiple transmits, and notify the hardware as quickly
as possible of new descriptors. This will lower the maximum
throughput, but will also lower transmit latency.
net.iflib.no_tx_batch
Some NICs allow processing completed transmit descriptors in
batches. Doing so usually increases the transmit throughput by
reducing the number of transmit interrupts. Setting this to a
non-zero value will disable the use of this feature.
These sysctl(8) variables are read-only:
driver_version
A string indicating the internal version of the driver.
There are a number of queue state sysctl(8) variables as well:
txqZ The following are repeated for each transmit queue, where Z is
the transmit queue instance number:
r_abdications
Number of consumer abdications in the MP ring for this
queue. An abdication occurs on every ring submission
when tx_abdicate is true.
r_restarts
Number of consumer restarts in the MP ring for this
queue. A restart occurs when an attempt to drain a non-
empty ring fails, and the ring is already in the STALLED
state.
r_stalls
Number of consumer stalls in the MP ring for this queue.
A stall occurs when an attempt to drain a non-empty ring
fails.
Number of drops in the MP ring for this queue. A drop
occurs when there is an attempt to add an entry to an MP
ring with no available space.
r_enqueues
Number of entries which have been enqueued to the MP ring
for this queue.
ring_state
MP (soft) ring state. This privides a snapshot of the
current MP ring state, including the producer head and
tail indexes, the consumer index, and the state. The
state is one of "IDLE", "BUSY", "STALLED", or
"ABDICATED".
txq_cleaned
The number of transmit descriptors which have been
reclaimed. Total cleaned.
txq_processed
The number of transmit descriptors which have been
processed, but may not yet have been reclaimed.
txq_in_use
Descriptors which have been added to the transmit queue,
but have not yet been cleaned. This value will include
both untransmitted descriptors as well as descriptors
which have been processed.
txq_cidx_processed
The transmit queue consumer index of the next descriptor
to process.
txq_cidx
The transmit queue consumer index of the oldest
descriptor to reclaim.
txq_pidx
The transmit queue producer index where the next
descriptor to transmit will be inserted.
no_tx_dma_setup
Number of times DMA mapping a transmit mbuf failed for
reasons other than EFBIG.
txd_encap_efbig
Number of times DMA mapping a transmit mbuf failed due to
requiring too many segments.
tx_map_failed
Number of times DMA mapping a transmit mbuf failed for
any reason (sum of no_tx_dma_setup and txd_encap_efbig)
no_desc_avail
Number of times a descriptor couldn't be added to the
transmit ring because the transmit ring was full.
mbuf_defrag_failed
Number of times both m_collapse(9) and m_defrag(9) failed
mbuf_defrag
Number of times m_defrag(9) was called.
rxqZ The following are repeated for each receive queue, where Z is the
receive queue instance number:
rxq_fl0.credits
Credits currently available in the receive ring.
rxq_fl0.cidx
Current receive ring consumer index.
rxq_fl0.pidx
Current receive ring producer index.
Additional OIDs useful for driver and iflib development are exposed when
the INVARIANTS and/or WITNESS options are enabled in the kernel.
SEE ALSO
iflib(9)
HISTORY
This framework was introduced in FreeBSD 11.0.
FreeBSD 14.0-RELEASE-p11 September 27, 2018 FreeBSD 14.0-RELEASE-p11