EM(4) Kernel Interfaces Manual EM(4) NAME em, lem, igb, igbv -- Intel PRO/1000 Gigabit Ethernet adapter driver SYNOPSIS device iflib device em options PCI_IOV In loader.conf(5): hw.em.disable_crc_stripping hw.em.eee_setting hw.em.smart_pwr_down hw.em.sbp hw.em.rx_int_delay hw.em.rx_abs_int_delay hw.em.tx_int_delay hw.em.tx_abs_int_delay hw.em.max_interrupt_rate hw.em.enable_aim hw.em.rx_process_limit if_em_load="YES" DESCRIPTION The em 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. The em driver provides support for PCI Express Gigabit Ethernet adapters based on the Intel 82571, 82572, 82573, 82574, and 82583 Ethernet con- troller chips. The em 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. The em driver provides support for PCI Express Gigabit Ethernet adapters based on the Intel 82575, 82576, 82580, i210, i211, and i35x. Physical functions appear as igb interfaces to maintain compatibility with existing infrastructure. Virtual functions provided by 82576 and I350 physical functions appear as igbv interfaces. The driver supports Transmit/Receive checksum offload and Jumbo Frames on all but 82542-based adapters. Physical functions on supported boards and ports advertise one or more of the wol_magic, wol_ucast, and wol_mcast capabilities shown by ifconfig(8). The available modes depend on the controller and board. The NVM APME set- ting normally selects whether magic-packet wake is enabled by default with- out 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 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: sysctl dev.em.0.wake=1 The 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. 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 em driver can be con- trolled via the led(4) API for localization purposes. For further hardware information, see the README included with the driver. 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 FreeBSD. Support for Jumbo Frames is provided via the interface MTU setting. Se- lecting an MTU larger than 1500 bytes with the ifconfig(8) utility config- ures the adapter to receive and transmit Jumbo Frames. The maximum MTU size for Jumbo Frames is 16114. This driver supports hardware assisted VLANs. The em driver supports the following media types: autoselect Enables auto-negotiation for speed and duplex. 10baseT/UTP Sets 10Mbps operation. Use the mediaopt option to select full-duplex mode. 100baseTX Sets 100Mbps operation. Use the mediaopt option to select full-duplex mode. 1000baseSX Sets 1000Mbps operation. Only full-duplex mode is supported at this speed. 1000baseTX Sets 1000Mbps operation. Only full-duplex mode is supported at this speed. The em driver supports the following media options: full-duplex Forces full-duplex operation half-duplex Forces half-duplex operation. Only use mediaopt to set the driver to full-duplex. If mediaopt is not specified, the driver defaults to half-duplex. For more information on configuring this device, see ifconfig(8). SR-IOV When the kernel is built with PCI_IOV, the 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. Passing a VF through to a guest requires an IOMMU to isolate its DMA. The packet filters described below do not constrain descriptor DMA; bhyve(8) refuses to assign a passthrough device when it cannot create an IOMMU do- main. 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 de- stroying VFs temporarily stops and restarts a running PF. Set the follow- ing per-device iflib(4) loader tunables before the PF attaches: dev.igb.N.iflib.override_ntxqs=1 dev.igb.N.iflib.override_nrxqs=1 The following VF parameters are accepted in iovctl.conf(5): mac-addr Assign a unicast MAC address to the VF. If omitted, the PF uses the stable address generator described by ether_gen_addr(9) with a distinct name for each VF. mac-anti-spoof Enable source MAC anti-spoofing. The default is true. The check binds transmissions to MAC addresses currently as- signed 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. allow-set-mac Permit the VF to replace its primary MAC address, whether assigned by 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. allow-promisc Permit explicit VF mailbox requests for unicast or multi- cast promiscuous mode within its VLAN membership. The de- fault is false. VF promiscuous-mode changes are applied asynchronously. If the PF refuses a request, the VF logs the failure after ifconfig(8) has returned. 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 oper- ates on untagged traffic. VF mailbox requests to change VLAN membership are rejected while an access VLAN is as- signed. The default value, "trunk", instead permits the VF to manage its VLAN memberships through the mailbox. VLAN 0 cannot be assigned as an access VLAN. I350 hides an assigned access VLAN in hardware. On 82576, transparent de- livery depends on the VF driver ignoring stripped VLAN metadata for VLANs it did not request; the in-tree igbv VF driver does so. DPDK guests and FreeBSD guests with an older igb driver do not apply this workaround and can expose the assigned VLAN tag instead. 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 allow-promisc. The multicast hash table is shared by the port, so hash collisions can also deliver matching multicast traffic to another multi- cast-enabled pool in the same VLAN. A VF with allow-set-mac enabled can install at most three auxiliary unicast receive addresses. These filters come from a controller-wide pool; exhaus- tion makes later requests fail without replacing existing filters. 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 con- sumes one shared entry, leaving 31 entries for nonzero VF VLANs while any trunk VF is active. 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 igbv VF driver re- tries failed VLAN additions at the PF's sustained rate for up to eight sec- onds. This heals transient rate-limit failures without polling indefi- nitely when the shared VLAN table is full. 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. 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 `malicious-driver event', clears the offend- ing VF's queue enables and PF-owned filter state, and sends a control mes- sage directing the guest to complete a new reset handshake. Recovery is unconditional; there is no tunable to disable it. A VF that submits fur- ther malformed descriptors is stopped and recovered again. Transmissions failing the anti-spoof checks are dropped by hardware without stopping the queue or resetting the VF. The PF logs `spoof event detected' for an offending VF at most once every two seconds. If a VF retains mailbox ownership while the PF is reading a request, the PF retries with a bounded backoff, then logs `mailbox remained busy' and re- vokes that VF's clear-to-send state. Requests from that VF are ignored un- til 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. PF and VF statistics are sampled once per interface watchdog interval, so exported counters can trail the hardware by up to 500 milliseconds. HARDWARE The em 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: * Intel Gigabit ET Dual Port Server Adapter (82576) * Intel Gigabit VT Quad Port Server Adapter (82575) * Intel Single, Dual and Quad Gigabit Ethernet Controller (82580) * Intel i210 and i211 Gigabit Ethernet Controller * Intel i350 and i354 Gigabit Ethernet Controller * Intel PRO/1000 CT Network Connection (82547) * Intel PRO/1000 F Server Adapter (82543) * Intel PRO/1000 Gigabit Server Adapter (82542) * Intel PRO/1000 GT Desktop Adapter (82541PI) * Intel PRO/1000 MF Dual Port Server Adapter (82546) * Intel PRO/1000 MF Server Adapter (82545) * Intel PRO/1000 MF Server Adapter (LX) (82545) * Intel PRO/1000 MT Desktop Adapter (82540) * Intel PRO/1000 MT Desktop Adapter (82541) * Intel PRO/1000 MT Dual Port Server Adapter (82546) * Intel PRO/1000 MT Quad Port Server Adapter (82546EB) * Intel PRO/1000 MT Server Adapter (82545) * Intel PRO/1000 PF Dual Port Server Adapter (82571) * Intel PRO/1000 PF Quad Port Server Adapter (82571) * Intel PRO/1000 PF Server Adapter (82572) * Intel PRO/1000 PT Desktop Adapter (82572) * Intel PRO/1000 PT Dual Port Server Adapter (82571) * Intel PRO/1000 PT Quad Port Server Adapter (82571) * Intel PRO/1000 PT Server Adapter (82572) * Intel PRO/1000 T Desktop Adapter (82544) * Intel PRO/1000 T Server Adapter (82543) * Intel PRO/1000 XF Server Adapter (82544) * Intel PRO/1000 XT Server Adapter (82544) LOADER TUNABLES Tunables can be set at the loader(8) prompt before booting the kernel or stored in loader.conf(5). See iflib(4) for per-instance variables. 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). hw.em.eee_setting Disable or enable Energy Efficient Ethernet. Default 1 (disabled). hw.em.smart_pwr_down Enable or disable smart power down features on newer adapters. De- fault 0 (disabled). hw.em.sbp Show bad packets when in promiscuous mode. Default 0 (off). 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. hw.em.rx_abs_int_delay If hw.em.rx_int_delay is non-zero, this tunable limits the maximum delay in which a receive interrupt is generated. hw.em.tx_int_delay This value delays the generation of transmit interrupts in units of 1.024 microseconds. The default value is 64. hw.em.tx_abs_int_delay If hw.em.tx_int_delay is non-zero, this tunable limits the maximum delay in which a transmit interrupt is generated. 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. 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 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. hw.em.rx_process_limit Maximum number of received packets to process at a time, -1 means unlimited. The default value is 100. FILES /dev/led/em*, /dev/led/igb* identification LED device nodes EXAMPLES Make the identification LED of em0 blink: echo f2 > /dev/led/em0 Turn the identification LED of em0 off again: echo 0 > /dev/led/em0 DIAGNOSTICS em%d: Unable to allocate bus resource: memory A fatal initialization error has occurred. em%d: Unable to allocate bus resource: interrupt A fatal initialization error has occurred. em%d: watchdog timeout -- resetting The device has stopped responding to the network, or there is a problem with the network connection (cable). SUPPORT For general information and support, go to the Intel support website at: http://support.intel.com. 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 <freebsd@intel.com>. SEE ALSO altq(4), arp(4), iflib(4), led(4), netintro(4), ng_ether(4), polling(4), vlan(4), iovctl.conf(5), ifconfig(8), iovctl(8), ether_gen_addr(9) HISTORY The em device driver first appeared in FreeBSD 4.4. em was merged with the lem and igb device drivers and converted to the iflib(4) framework in FreeBSD 12.0. AUTHORS The em driver was originally written by Intel Corporation <freebsd@in- tel.com>. It was merged with the igb driver and converted to the iflib(4) framework by Matthew Macy <mmacy@mattmacy.io> and Sean Bruno <sbruno@FreeBSD.org>. FreeBSD 16.0 CURRENT August 30, 2026 EM(4)
NAME | SYNOPSIS | DESCRIPTION | SR-IOV | HARDWARE | LOADER TUNABLES | FILES | EXAMPLES | DIAGNOSTICS | SUPPORT | SEE ALSO | HISTORY | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=em&sektion=4&manpath=FreeBSD+16.0-CURRENT>