.\" Copyright (c) 2001-2008, Intel Corporation
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright notice,
.\"    this list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" 3. Neither the name of the Intel Corporation nor the names of its
.\"    contributors may be used to endorse or promote products derived from
.\"    this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.\" * Other names and brands may be claimed as the property of others.
.\"
.Dd September 2, 2026
.Dt IX 4
.Os
.Sh NAME
.Nm ix
.Nd Intel 10Gb Ethernet driver
.Sh SYNOPSIS
.Cd device iflib
.Cd device ix
.Pp
In
.Xr loader.conf 5 :
.Cd hw.ix.max_interrupt_rate
.Cd hw.ix.flow_control
.Cd hw.ix.advertise_speed
.Cd hw.ix.enable_msix
.Cd hw.ix.allow_unsupported_sfp
.Cd hw.ix.enable_fdir
.Cd hw.ix.enable_rss
.Cd hw.ix.enable_aim
.Cd if_ix_load="YES"
.Pp
In
.Xr loader.conf 5
or
.Xr sysctl.conf 5 :
.Cd dev.ix.?.debug.dump.clusters
.Cd dev.ix.?.debug.dump.dump
.Cd dev.ix.?.debug.fw_log.severity. Ns Aq Ar module
.Cd dev.ix.?.debug.fw_log.register
.Cd dev.ix.?.debug.fw_log.on_load
.Cd dev.ix.?.eee_state
.Cd dev.ix.?.eee.tx_lpi_count
.Cd dev.ix.?.eee.rx_lpi_count
.Sh DESCRIPTION
The
.Nm
driver provides support for Intel(R) 10Gb Ethernet PCIe adapters.
The driver supports Jumbo Frames, MSIX, TSO, and RSS.
.Pp
The identification LED for each port is controlled through its
.Pa /dev/led/ix*
device node.
.Pp
On adapters and ports that expose PCI power-management wake, the driver
supports the
.Cm wol_magic ,
.Cm wol_ucast ,
and
.Cm wol_mcast
capabilities shown by
.Xr ifconfig 8 .
The NVM APME setting selects whether magic-packet wake is enabled by default
without hiding wake modes that the hardware and board support.
Waking the system from an ACPI sleep state also requires enabling the
corresponding device wake source when it is exposed, for example:
.Bd -literal -offset indent
sysctl dev.ix.0.wake=1
.Ed
The interface wake capabilities select the controller packet filters; they do
not enable the ACPI wake source.
.Pp
For questions related to hardware requirements,
refer to the documentation supplied with your Intel 10GbE adapter.
All hardware requirements listed apply to use with
.Fx .
.Pp
Support for Jumbo Frames is provided via the interface MTU setting.
Selecting an MTU larger than 1500 bytes with the
.Xr ifconfig 8
utility configures the adapter to receive and transmit Jumbo Frames.
The maximum MTU size for Jumbo Frames is 9710.
.Pp
This driver version supports VLANs.
For information on enabling VLANs, see
.Xr ifconfig 8 .
.Sh SR-IOV
The driver-specific
.Va vlan
parameter in
.Xr iovctl.conf 5
accepts a VLAN identifier from 1 through 4095 or the keyword
.Dq trunk ,
which is the default.
A numeric VLAN configures an access VF: the PF inserts the VLAN tag on
transmit and strips it on receive.
The stripped administrative tag is not presented to the VF network stack as
.Dv M_VLANTAG ,
so received packets are delivered directly through the VF interface.
With
.Dq trunk ,
the VF may add and remove individual VLAN memberships; tags for VLANs
registered by the VF are presented normally to its network stack.
.Pp
VLAN filtering remains enabled in the hardware while SR-IOV is active so that
the PF can enforce VLAN ownership for each VF pool, including when hardware
VLAN filtering has been disabled on the PF interface.
.Pp
Secondary unicast addresses requested by a VF are accepted only when the VF
is permitted to change its MAC address and
.Va mac-anti-spoof
is disabled in its
.Xr iovctl.conf 5
configuration.
The hardware MAC anti-spoofing control can validate only the VF's primary
source address, so the driver does not silently weaken an enabled policy to
install secondary addresses.
.Pp
Ethertype anti-spoofing and malicious-driver detection and recovery are
available only on X550-family devices, including X552 and X553, and on E610.
The driver cannot enable those hardware protections on earlier devices such
as 82599.
After a malicious-driver event, the PF keeps the offending VF's transmit and
receive paths disabled until the VF completes a new reset handshake.
.Pp
On 82599 and X540 devices, the driver instead watches for transmit stalls
caused by an invalid VF DMA target and resets the VF identified by its PCIe
error status.
After five such events from the same VF, the driver quarantines that VF and
keeps its transmit, receive, and mailbox clear-to-send state disabled.
Quarantine persists across PF reinitialization and is cleared when the SR-IOV
configuration is destroyed and recreated.
The read-only
.Va dev.ix.N.iov_quarantined_vfs
sysctl reports quarantined VF pools as a bitmap.
.Pp
E610 PFs provide physical link state and speed to VFs that negotiate mailbox
API 1.6.
.Sh HARDWARE
The
.Nm
driver supports Intel 10Gb Ethernet PCIe adapters,
including:
.Pp
.Bl -bullet -compact
.It
Intel(R) Ethernet E610
.It
Intel(R) Ethernet X553
.It
Intel(R) Ethernet X552
.It
Intel(R) Ethernet X550
.It
Intel(R) Ethernet X540 Bypass
.It
Intel(R) Ethernet X540
.It
Intel(R) Ethernet X520 Bypass (82599)
.It
Intel(R) Ethernet X520 (82599)
.It
Intel(R) 10 Gigabit Server Adapter (82598EB)
.El
.Sh LOADER TUNABLES
The
.Nm
driver supports the following loader tunables:
.Bl -tag -width "hw.ix.allow_unsupported_sfp"
.It Va hw.ix.max_interrupt_rate
Maximum interrupts per second.
.It Va hw.ix.flow_control
Default flow control used for all adapters.
.It Va hw.ix.advertise_speed
Default advertised speed for all adapters.
.It Va hw.ix.enable_msix
Enable Message Signalled Interrupts (MSI-X).
.It Va hw.ix.allow_unsupported_sfp
Allow unsupported small form-factor pluggable
.Pq SFP
modules.
Use at your own risk.
.It Va hw.ix.enable_fdir
Enable Flow Director.
Flow Director directs Ethernet packets to the core where the
packet consuming process, application, container,
or microservice is running.
SR-IOV configuration is rejected when Flow Director is enabled.
.It Va hw.ix.enable_rss
Enable Receive-Side Scaling (RSS).
When RSS is enabled, all of the receive data processing for
a particular TCP connection is shared across multiple processors
or processor cores.
Without RSS, all of the processing is performed by a single
processor, resulting in inefficient system cache utilization.
This has no effect if your system has only one processing unit.
.It Va hw.ix.enable_aim
Enable Adaptive Interrupt Moderation (AIM).
Vary the interrupt rate over time based on the traffic for
that interrupt vector.
.El
.Sh SYSCTL VARIABLES
The
.Nm
driver supports the following
.Xr sysctl 8
variables:
.Bl -tag -width "dev.ix.?.debug.fw_log.severity.<module>"
.It Va dev.ix.?.debug.dump.clusters
Specify a bitmask to select firmware event clusters
to be included in the debug dump.
Possible values include:
.Pp
.Bl -tag -compact
.It 0
All clusters excluding Manageability Transactions
.It 0x1
Link cluster
.It 0x2
Full CSR Space excluding RCW registers
.El
.Pp
This feature is only supported on E610 devices.
.It Va dev.ix.?.debug.dump.dump
Specify 1 to generate a per-device debugging snapshot.
Output must be redirected to a file
and decoded by Intel Customer Support.
.Pp
This feature is only supported on E610.
.It Va dev.ix.?.debug.fw_log.severity. Ns Aq Ar module
Specify firmware logging verbosity level for the specified module.
Available levels include:
.Pp
.Bl -tag -compact
.It 0
none
.It 1
error
.It 2
warning
.It 3
normal
.It 4
verbose
.El
.Pp
Supported modules: general, ctrl, link, link_topo, dnl, i2c, sdp, mdio,
adminq, hdma, lldp, dcbx, dcb, xlr, nvm, auth, vpd, iosf, parser, sw,
scheduler, txq, acl, post, watchdog, task_dispatch, mng, synce, health,
tsdrv, pfreg, mdlver.
.Pp
This feature is only supported on E610 devices.
.It Va dev.ix.?.debug.fw_log.register
Specify 1 to apply per-device firmware logging configuration.
.Pp
This feature is only supported on E610 devices.
.It Va dev.ix.?.debug.fw_log.on_load
Enable firmware logging during driver initialization when set via
.Xr kenv 1 .
.Pp
This feature is only supported on E610 devices.
.It Va dev.ix.?.eee_state
Enable or disable Energy Efficient Ethernet on supported devices.
.It Va dev.ix.?.eee.tx_lpi_count
Count transmit Low Power Idle events.
.It Va dev.ix.?.eee.rx_lpi_count
Count receive Low Power Idle events.
.El
.Sh DIAGNOSTICS
.Bl -diag
.It "ix%d: Unable to allocate bus resource: memory"
A fatal initialization error has occurred.
.It "ix%d: Unable to allocate bus resource: interrupt"
A fatal initialization error has occurred.
.It "ix%d: watchdog timeout -- resetting"
The device has stopped responding to the network, or there is a problem with
the network connection (cable).
.El
.Sh SUPPORT
For general information and support,
go to the Intel support website at:
.Pa https://support.intel.com .
.Pp
If an issue is identified with the released source code on the supported kernel
with a supported adapter, email the specific information related to the
issue to
.Aq Mt freebsd@intel.com .
.Sh SEE ALSO
.Xr altq 4 ,
.Xr arp 4 ,
.Xr iflib 4 ,
.Xr led 4 ,
.Xr netintro 4 ,
.Xr ng_ether 4 ,
.Xr polling 4 ,
.Xr vlan 4 ,
.Xr iovctl.conf 5 ,
.Xr ifconfig 8 ,
.Xr sysctl 8
.Sh HISTORY
The
.Nm
device driver first appeared in
.Fx 7.0 .
.Sh AUTHORS
The
.Nm
driver was written by
.An Intel Corporation Aq Mt freebsd@intel.com .
.Sh CAVEATS
Intel (R) Flow director support is not fully implemented in
.Fx
at this time and additional work is required
before those features can be supported.
.Pp
Enabling flow director may route traffic to the wrong RX queue of the NIC,
resulting in sub-optimal performance on the receive side.