.\"-
.\" SPDX-License-Identifier: BSD-3-Clause
.\"
.\" Copyright (c) 2001-2003, 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 16, 2026
.Dt EM 4
.Os
.Sh NAME
.Nm em ,
.Nm lem ,
.Nm igb ,
.Nm igbv
.Nd Intel PRO/1000 Gigabit Ethernet adapter driver
.Sh SYNOPSIS
.Cd device iflib
.Cd device em
.Cd options PCI_IOV
.Pp
In
.Xr loader.conf 5 :
.Cd hw.em.disable_crc_stripping
.Cd hw.em.eee_setting
.Cd hw.em.smart_pwr_down
.Cd hw.em.sbp
.Cd hw.em.rx_int_delay
.Cd hw.em.rx_abs_int_delay
.Cd hw.em.tx_int_delay
.Cd hw.em.tx_abs_int_delay
.Cd hw.em.max_interrupt_rate
.Cd hw.em.enable_aim
.Cd hw.em.rx_process_limit
.Cd if_em_load="YES"
.Sh DESCRIPTION
The
.Nm
driver provides support for PCI/PCI-X Gigabit Ethernet adapters based on
the Intel 82540, 82541ER, 82541PI, 82542, 82543, 82544, 82545, 82546,
82546EB, 82546GB, and 82547 controller chips.
.Pp
The
.Nm
driver provides support for PCI Express Gigabit Ethernet adapters
based on the Intel 82571, 82572, 82573, 82574, and 82583 Ethernet
controller chips.
.Pp
The
.Nm
driver provides support for Gigabit Ethernet adapters connected to I/O
Controller Hub (ICH) and Platform Controller Hub (PCH) including Intel
80003ES2LAN, 82562, 82566, 82567, 82577, 82578, 82579, i217, i218, and i219.
.Pp
The
.Nm
driver provides support for PCI Express Gigabit Ethernet adapters
based on the Intel 82575, 82576, 82580, i210, i211, and i35x.
Physical functions appear as
.Nm igb
interfaces to maintain compatibility with existing infrastructure.
Virtual functions provided by 82576 and I350 physical functions appear as
.Nm igbv
interfaces.
.Pp
On Hyper-V,
.Nm igbv
supports 82576 and I350 virtual functions using the host-assigned MAC address
and a single transmit/receive queue pair.
The VF can be used by
.Xr hn 4
as the accelerated data path for its synthetic interface.
The host controls MAC, multicast, promiscuous-mode, and VLAN-filter policy;
changing these on the VF does not reconfigure the host.
Hyper-V VFs currently support an MTU of at most 1500 bytes.
.Pp
Only host-assigned access VLANs with untagged guest traffic are supported
on Hyper-V; guest VLAN registration is ignored.
With Windows I350 PF driver version 14.1.5.0, tagged VF transmissions can
trigger host malicious driver detection and
disable the VF's queues even when the Hyper-V port is configured for trunk mode.
This limitation is also reproducible with Windows VF drivers.
For guest VLAN trunks, disable SR-IOV for the virtual network adapter on
the host and use the
.Xr hn 4
synthetic data path.
.Pp
If the host unexpectedly disables a running Hyper-V VF transmit queue,
the driver reports link down.
If the hardware reports carrier up, the driver requests recovery through
the normal stop/init path.
These recovery requests are rate-limited if the host keeps the queue disabled.
.Pp
The driver supports Transmit/Receive checksum offload.
Jumbo Frames are supported except on 82542-based adapters and Hyper-V VFs.
.Pp
Physical functions on supported boards and ports advertise one or more of the
.Cm wol_magic ,
.Cm wol_ucast ,
and
.Cm wol_mcast
capabilities shown by
.Xr ifconfig 8 .
The available modes depend on the controller and board.
The NVM APME setting normally selects whether magic-packet wake is enabled by
default without hiding modes that the hardware and board support.
Wake support can be restricted to particular ports on multi-port adapters and
is not available on
.Nm igbv
virtual functions.
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.em.0.wake=1
.Ed
The
.Xr ifconfig 8
wake capabilities select the controller packet filters; they do not enable
the ACPI wake source.
On supported PCH controllers, suspend uses the PHY ultra-low-power mode when
the selected wake filters permit it and preserves negotiated Energy Efficient
Ethernet operation while the wake link remains active.
.Pp
Furthermore it supports TCP segmentation offload (TSO) on all adapters but
those based on the 82542, 82543, 82544 and 82547 controller chips.
The identification LEDs of the adapters supported by the
.Nm
driver can be controlled via the
.Xr led 4
API for localization purposes.
For further hardware information, see the
.Pa README
included with the driver.
.Pp
For questions related to hardware requirements, refer to the
documentation supplied with your Intel PRO/1000 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 16114.
.Pp
This driver supports hardware assisted VLANs.
The
.Nm
driver supports the following media types:
.Bl -tag -width ".Cm 10baseT/UTP"
.It Cm autoselect
Enables auto-negotiation for speed and duplex.
.It Cm 10baseT/UTP
Sets 10Mbps operation.
Use the
.Cm mediaopt
option to select
.Cm full-duplex
mode.
.It Cm 100baseTX
Sets 100Mbps operation.
Use the
.Cm mediaopt
option to select
.Cm full-duplex
mode.
.It Cm 1000baseSX
Sets 1000Mbps operation.
Only
.Cm full-duplex
mode is supported at this speed.
.It Cm 1000baseTX
Sets 1000Mbps operation.
Only
.Cm full-duplex
mode is supported at this speed.
.El
.Pp
The
.Nm
driver supports the following media options:
.Bl -tag -width ".Cm full-duplex"
.It Cm full-duplex
Forces full-duplex operation
.It Cm half-duplex
Forces half-duplex operation.
.El
.Pp
Only use
.Cm mediaopt
to set the driver to
.Cm full-duplex .
If
.Cm mediaopt
is not specified, the driver defaults to
.Cm half-duplex .
.Pp
For more information on configuring this device, see
.Xr ifconfig 8 .
.Sh SR-IOV
When the kernel is built with
.Cd PCI_IOV ,
the
.Nm igb
PF driver supports SR-IOV on 82576 and I350 controllers.
Up to seven VFs can be created per PF.
PF SR-IOV is not featured on 82575, 82580, I210, I211, or I354 controllers.
.Pp
Passing a VF through to a guest requires an IOMMU to isolate its DMA.
The packet filters described below do not constrain descriptor DMA;
.Xr bhyve 8
refuses to assign a passthrough device when it cannot create an IOMMU domain.
.Pp
The supported SR-IOV configuration uses one PF transmit and receive queue and
requires MSI-X.
I350 requires this layout; 82576 hardware can combine VMDq with per-pool RSS,
but that mode is not implemented by this driver.
The PF may be administratively down when VFs are created and remains down
afterward.
VF mailbox and datapath service begin when the PF is brought up, and the PF
must remain up to provide those services.
Creating or destroying VFs temporarily stops and restarts a running PF.
Set the following per-device
.Xr iflib 4
loader tunables before the PF attaches:
.Bd -literal -offset indent
dev.igb.N.iflib.override_ntxqs=1
dev.igb.N.iflib.override_nrxqs=1
.Ed
.Pp
The following VF parameters are accepted in
.Xr iovctl.conf 5 :
.Bl -tag -width "mac-anti-spoof"
.It Va mac-addr
Assign a unicast MAC address to the VF.
If omitted, the PF uses the stable address generator described by
.Xr ether_gen_addr 9
with a distinct name for each VF.
.It Va mac-anti-spoof
Enable source MAC anti-spoofing.
The default is true.
The check binds transmissions to MAC addresses currently assigned to that VF.
It prevents impersonating the PF or a sibling VF, but a VF permitted to change
its MAC can select an address belonging to an off-host station.
.It Va allow-set-mac
Permit the VF to replace its primary MAC address, whether assigned by
.Va mac-addr
or generated by the PF, and to install up to three auxiliary unicast
addresses.
Each auxiliary address expands both the VF's receive filters and the source
addresses permitted by transmit anti-spoofing.
The default is false.
.It Va allow-promisc
Permit explicit VF mailbox requests for unicast or multicast promiscuous mode
within its VLAN membership.
The default is false.
VF promiscuous-mode changes are applied asynchronously.
If the PF refuses a request, the VF logs the failure after
.Xr ifconfig 8
has returned.
.It Va vlan
Assign the VF an access VLAN from 1 through 4095.
The PF inserts this tag on VF transmissions, admits only this VLAN to the VF,
and strips the tag on reception so the VF operates on untagged traffic.
VF mailbox requests to change VLAN membership are rejected while an access
VLAN is assigned.
The default value,
.Dq trunk ,
instead permits the VF to manage its VLAN memberships through the mailbox.
VLAN 0 cannot be assigned as an access VLAN.
.El
.Pp
I350 hides an assigned access VLAN in hardware.
On 82576, transparent delivery depends on the VF driver ignoring stripped
VLAN metadata for VLANs it did not request; the in-tree
.Nm igbv
VF driver does so.
DPDK guests and
.Fx
guests with an older
.Nm igb
driver do not apply this workaround and can expose the assigned VLAN tag
instead.
.Pp
The VF mailbox carries at most 30 multicast hashes.
If the VF reports more, the PF automatically enables reception of all
multicast within that VF's VLAN membership.
This overflow fallback is independent of
.Va allow-promisc .
The multicast hash table is shared by the port, so hash collisions can also
deliver matching multicast traffic to another multicast-enabled pool in the
same VLAN.
.Pp
A VF with
.Va allow-set-mac
enabled can install at most three auxiliary unicast receive addresses.
These filters come from a controller-wide pool; exhaustion makes later
requests fail without replacing existing filters.
.Pp
The hardware provides 32 VLAN-to-pool filter entries for VLANs assigned to
VFs, including PF-assigned access VLANs, and rejects a request that would
exceed 32 distinct VF VLANs.
A trunk VF's implicit VID-0 membership consumes one shared entry, leaving
31 entries for nonzero VF VLANs while any trunk VF is active.
.Pp
Each VF can burst 64 VLAN-add requests and then receives eight additional
additions per second.
This permits two complete 31-VLAN replays while bounding repeated global
filter-table rebuilds.
VLAN removals and requests that do not change membership are not limited.
A PF-wide reinitialization replenishes the burst; VF-initiated resets do not.
The
.Nm igbv
VF driver retries failed VLAN additions at the PF's sustained rate for up to
eight seconds.
This heals transient rate-limit failures without polling indefinitely when
the shared VLAN table is full.
.Pp
On 82576, a PF-only VLAN uses the default PF pool without consuming one of
these entries; an entry shared by the PF and VFs includes all member pools.
I350 can additionally place the PF in VLAN-promiscuous mode when its PF
memberships do not fit.
Because the entries are shared, VF allocations can force this PF fallback.
DMA coalescing is disabled while I350 SR-IOV is active.
.Pp
The PF enables malicious-driver detection.
Hardware stops a VF transmit queue that submits a malformed descriptor, such as
a legacy descriptor in a virtualized mode, or a descriptor requesting VLAN
insertion while an access VLAN is assigned.
The PF logs
.Ql malicious-driver event ,
clears the offending VF's queue enables and PF-owned filter state, and sends a
control message directing the guest to complete a new reset handshake.
Recovery is unconditional; there is no tunable to disable it.
A VF that submits further malformed descriptors is stopped and recovered again.
.Pp
Transmissions failing the anti-spoof checks are dropped by hardware without
stopping the queue or resetting the VF.
The PF logs
.Ql spoof event detected
for an offending VF at most once every two seconds.
.Pp
If a VF retains mailbox ownership while the PF is reading a request, the PF
retries with a bounded backoff, then logs
.Ql mailbox remained busy
and revokes that VF's clear-to-send state.
Requests from that VF are ignored until a hardware reset begins a new mailbox
epoch.
A guest that resets through the VF control register or through a function level
reset recovers automatically; a guest that only sends the reset mailbox message
does not.
.Pp
PF and VF statistics are sampled once per interface watchdog interval, so
exported counters can trail the hardware by up to 500 milliseconds.
.Sh HARDWARE
The
.Nm
driver supports Gigabit Ethernet adapters based on the Intel
82540, 82541ER, 82541PI, 82542, 82543, 82544, 82545, 82546, 82546EB,
82546GB, 82547, 82571, 82572, 82573, 82574, 82575, 82576, and 82580
controller chips:
.Pp
.Bl -bullet -compact
.It
Intel Gigabit ET Dual Port Server Adapter (82576)
.It
Intel Gigabit VT Quad Port Server Adapter (82575)
.It
Intel Single, Dual and Quad Gigabit Ethernet Controller (82580)
.It
Intel i210 and i211 Gigabit Ethernet Controller
.It
Intel i350 and i354 Gigabit Ethernet Controller
.It
Intel PRO/1000 CT Network Connection (82547)
.It
Intel PRO/1000 F Server Adapter (82543)
.It
Intel PRO/1000 Gigabit Server Adapter (82542)
.It
Intel PRO/1000 GT Desktop Adapter (82541PI)
.It
Intel PRO/1000 MF Dual Port Server Adapter (82546)
.It
Intel PRO/1000 MF Server Adapter (82545)
.It
Intel PRO/1000 MF Server Adapter (LX) (82545)
.It
Intel PRO/1000 MT Desktop Adapter (82540)
.It
Intel PRO/1000 MT Desktop Adapter (82541)
.It
Intel PRO/1000 MT Dual Port Server Adapter (82546)
.It
Intel PRO/1000 MT Quad Port Server Adapter (82546EB)
.It
Intel PRO/1000 MT Server Adapter (82545)
.It
Intel PRO/1000 PF Dual Port Server Adapter (82571)
.It
Intel PRO/1000 PF Quad Port Server Adapter (82571)
.It
Intel PRO/1000 PF Server Adapter (82572)
.It
Intel PRO/1000 PT Desktop Adapter (82572)
.It
Intel PRO/1000 PT Dual Port Server Adapter (82571)
.It
Intel PRO/1000 PT Quad Port Server Adapter (82571)
.It
Intel PRO/1000 PT Server Adapter (82572)
.It
Intel PRO/1000 T Desktop Adapter (82544)
.It
Intel PRO/1000 T Server Adapter (82543)
.It
Intel PRO/1000 XF Server Adapter (82544)
.It
Intel PRO/1000 XT Server Adapter (82544)
.El
.Sh LOADER TUNABLES
Tunables can be set at the
.Xr loader 8
prompt before booting the kernel or stored in
.Xr loader.conf 5 .
See
.Xr iflib 4
for per-instance variables.
.Bl -tag -width indent
.It Va hw.em.disable_crc_stripping
Disable or enable hardware stripping of CRC field.
This is mostly useful on BMC/IPMI shared interfaces where stripping the CRC
causes remote access over IPMI to fail.
Default 0 (enabled).
.It Va hw.em.eee_setting
Disable or enable Energy Efficient Ethernet.
Default 1 (disabled).
.It Va hw.em.smart_pwr_down
Enable or disable smart power down features on newer adapters.
Default 0 (disabled).
.It Va hw.em.sbp
Show bad packets when in promiscuous mode.
Default 0 (off).
.It Va hw.em.rx_int_delay
This value delays the generation of receive interrupts in units of
1.024 microseconds.
The default value is 0, since adapters may hang with this feature
being enabled.
.It Va hw.em.rx_abs_int_delay
If
.Va hw.em.rx_int_delay
is non-zero, this tunable limits the maximum delay in which a receive
interrupt is generated.
.It Va hw.em.tx_int_delay
This value delays the generation of transmit interrupts in units of
1.024 microseconds.
The default value is 64.
.It Va hw.em.tx_abs_int_delay
If
.Va hw.em.tx_int_delay
is non-zero, this tunable limits the maximum delay in which a transmit
interrupt is generated.
.It Va hw.em.max_interrupt_rate
Maximum interrupts per second.
The default value is 8000.
This is the rate used when adaptive interrupt moderation is disabled, and
the fallback when it has no usable measurement.
.It Va hw.em.enable_aim
Adaptive interrupt moderation.
The interrupt rate is derived from the average size of the packets seen
since the previous interrupt, so that bulk traffic is coalesced while small
packet traffic keeps its latency.
A value of 0 disables it and pins the rate to
.Va hw.em.max_interrupt_rate ,
1 selects the normal range, and 2 selects the low-latency range.
The default value is 1.
Setting 2 raises the interrupt rate substantially on small packet workloads
and is rarely a win; prefer the default unless latency has been measured to
matter more than the additional interrupt load.
.It Va hw.em.rx_process_limit
Maximum number of received packets to process at a time, -1 means unlimited.
The default value is 100.
.El
.Sh FILES
.Bl -tag -width "/dev/led/igb*"
.It Pa /dev/led/em* , Pa /dev/led/igb*
identification LED device nodes
.El
.Sh EXAMPLES
Make the identification LED of em0 blink:
.Pp
.Dl "echo f2 > /dev/led/em0"
.Pp
Turn the identification LED of em0 off again:
.Pp
.Dl "echo 0 > /dev/led/em0"
.Sh DIAGNOSTICS
.Bl -diag
.It "em%d: Unable to allocate bus resource: memory"
A fatal initialization error has occurred.
.It "em%d: Unable to allocate bus resource: interrupt"
A fatal initialization error has occurred.
.It "em%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 hn 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 iovctl 8 ,
.Xr ether_gen_addr 9
.Sh HISTORY
The
.Nm
device driver first appeared in
.Fx 4.4 .
.Nm
was merged with the
.Nm lem
and
.Nm igb
device drivers and converted to the
.Xr iflib 4
framework in
.Fx 12.0 .
.Sh AUTHORS
.An -nosplit
The
.Nm
driver was originally written by
.An Intel Corporation Aq Mt freebsd@intel.com .
It was merged with the
.Nm igb
driver and converted to the
.Xr iflib 4
framework by
.An Matthew Macy Aq Mt mmacy@mattmacy.io
and
.An Sean Bruno Aq Mt sbruno@FreeBSD.org .