EM(4)

NAME
em, emx - Intel(R) PRO/1000 Gigabit Ethernet adapter driver

SYNOPSIS
To compile this driver into the kernel, place the following lines in your kernel configuration file:

device ig_hal
device em # for em(4)
device emx # for emx(4)

Alternatively, to load the driver as a module at boot time, place the following lines in loader.conf(5):

    ig_hal_load="YES"
    if_em_load="YES"  # for em(4)
    if_emx_load="YES" # for emx(4)

DESCRIPTION
The em driver provides support for PCI Gigabit Ethernet adapters based on the Intel 82540, 82541ER, 82541PI, 82542, 82543, 82544, 82545, 82546, 82546EB, 82546GB, 82547, 82571, 81572, 82573, 82574, I217, I218 and I219 Ethernet controller chips. The driver supports Transmit/Receive checksum offload and Jumbo Frames on all but 82542-based adapters. Furthermore it supports TCP segmentation offload (TSO) on PCI-E adapters.

The emx is a version of the em driver for 82571, 82572, 82573, 82574, I217, I218 and I219 Ethernet controller chips that additionally supports Receive Side Scaling (RSS, 2 reception queues). By default, the emx driver will try enabling 2 reception queues if there are multiple CPUs on the system. For 82571, 82572, 82574, I217, I218 and I219 the emx driver could be configured to enable 2 transmission queues. By default, the emx driver only enables 1 transmission queue, since enabling 2 transmission queues will require setting up context descriptor for every packets requiring hardware transmission offloading, which hurts tiny packet transmission performance. However, if the workload is mainly bulk data or hardware transmission offloading is rarely required, extra transmission queue could be enabled to reduce contention on transmission path. 2 transmission queues will only be used when polling(4) is enabled on the device. If multiple transmission queues are used, the round-robin arbitration is performed among the transmission queues. It should be noted that if both TSO and multiple transmission queues are used, the round-robin arbitration between transmission queues is done at the TSO packet boundary.

Support for Jumbo Frames is provided via the interface MTU setting. Selecting an MTU larger than 1500 bytes with the ifconfig(8) utility configures the adapter to receive and transmit Jumbo Frames. The maximum MTU size for Jumbo Frames is 16114.

This driver version supports VLANs. The em and emx drivers support 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.

1000baseT
    Sets 1000Mbps operation. Only full-duplex mode is supported at this speed.

The em and emx drivers support the following media options:

full-duplex
    Forces full-duplex operation

half-duplex
    Forces half-duplex operation.

rxpause
    Enable flow control PAUSE reception. This is only supported by autoselect and full-duplex mode.

txpause
    Enable flow control PAUSE transmission. This is only supported by autoselect and full-duplex mode.

forcepause
    Force flow control PAUSE operation as configured by rxpause and txpause media options.

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).

The em and emx drivers support polling(4).

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, I217, I218 and I219 controller chips:

•   Intel 82540EM Gigabit Ethernet Controller
•   Intel 82540EP Gigabit Ethernet Controller
•   Intel 82543GC Gigabit Ethernet Controller
•   Intel 82544EI Gigabit Ethernet Controller
•   Intel 82544GC Gigabit Ethernet Controller
•   Intel 82545GM Gigabit Ethernet Controller
•   Intel 82546EB Gigabit Ethernet Controller
•   Intel 82547GI Gigabit Ethernet Controller
•   Intel 82567 Gigabit Ethernet Controller
•   Intel 82571EB Gigabit Ethernet Controller
•   Intel 82572EI Gigabit Ethernet Controller
•   Intel 82573E Gigabit Ethernet Controller
•   Intel 82573L Gigabit Ethernet Controller
•   Intel 82573V Gigabit Ethernet Controller
•   Intel 82574IT Gigabit Ethernet Controller
•   Intel 82574L Gigabit Ethernet Controller
•   Intel 82578DC Gigabit Ethernet PHY
•   Intel 82578DM Gigabit Ethernet PHY
•   Intel 82579LM Gigabit Ethernet PHY
•   Intel 82579V Gigabit Ethernet PHY
•   Intel Ethernet Connection I217-LM
•   Intel Ethernet Connection I217-V
•   Intel Ethernet Connection I218-LM
•   Intel Ethernet Connection I218-V
•   Intel Ethernet Connection I219-LM
•   Intel Ethernet Connection I219-V
•   Intel Gigabit CT Desktop Adapter
•   Intel PRO/1000 F Server Adapter
•   Intel PRO/1000 MF Dual Port Server Adapter
•   Intel PRO/1000 MF Server Adapter
•   Intel PRO/1000 MF Server Adapter (LX)
•   Intel PRO/1000 MT Dual Port Server Adapter
•   Intel PRO/1000 MT Quad Port Server Adapter
•   Intel PRO/1000 PF Dual Port Server Adapter
•   Intel PRO/1000 PT Dual Port Server Adapter
•   Intel PRO/1000 PT Quad Port Low Profile Server Adapter
•   Intel PRO/1000 PT Quad Port Server Adapter
•   Intel PRO/1000 T Server Adapter
•   Intel PRO/1000 XT Low Profile Server Adapter
•   Intel PRO/1000 XT Server Adapter

The emx driver supports Gigabit Ethernet adapters based on the Intel 82571, 82572, 82573, 82574, I217, I218 and I219 controller chips.

TUNABLES
Tunables can be set at the loader(8) prompt before booting the kernel or stored in loader.conf(5). Y is the device unit number.

hw.em.int_throttle_ceil
    Hardware interrupt throttling rate. The default value is 6000Hz. This tunable also applies to emx. emx has a per device tunable hw.emxY.int_throttle_ceil, which serves the same purpose.

hw.em.rxd
    Number of receive descriptors allocated by the driver. The default value is 512. The 82542 and 82543-based adapters can handle up to 256 descriptors, while others can have up to 4096. This tunable also applies to emx. emx has a per device tunable hw.emxY.rxd, which serves the same purpose.

hw.em.txd
    Number of transmit descriptors allocated by the driver. The default value is 512. The 82542 and 82543-based adapters can handle up to 256 descriptors, while others can have up to 4096. This tunable also applies to emx. emx has a per device tunable hw.emxY.txd, which serves the same purpose.

hw.em.msi.enable hw.emY.msi.enable
    By default, the driver will use MSI if it is supported. This behavior can be turned off by setting these tunable to 0. These tunables also applies to emx.

hw.emY.msi.cpu
    If MSI is used, it specifies the MSI's target CPU. This tunable also applies to emx.

hw.emY.irq.unshared
    If legacy interrupt is used, by default, the driver assumes the interrupt could be shared. Setting this tunable to 1 allows the driver to perform certain optimization based on the knowledge that the interrupt is not shared. These tunables also applies to emx.

hw.em.flow_ctrl hw.emY.flow_ctrl
    The default flow control settings. Supported values are: rxpause (only enable PAUSE reception), txpause (only enable PAUSE transmission), full (enable PAUSE reception and transmission), none (disable flow control PAUSE operation), force-rxpause (force PAUSE reception), force-txpause (force PAUSE transmission), force-full (forcefully enable PAUSE reception and transmission), force-none (forcefully disable flow control PAUSE operation). Default is none. These tunables also applies to emx.

hw.emx.rxr hw.emxY.rxr
    This tunable specifies the number of reception queues could be enabled. Maximum allowed value for these tunables is 2. Setting these tunables to 0 allows the driver to enable reception queues based on the number of CPUs. The default value is 0.

hw.emx.txr hw.emxY.txr
    These tunables only take effect on 82571 and 82572. This tunable specifies the number of transmission queues could be enabled. Maximum allowed value for these tunables is 2. Setting these tunables to 0 allows the driver to enable transmission queues based on the number of CPUs. The default value is 1.

MIB Variables
A number of per-interface variables are implemented in the dev.emx.Y or dev.em.Y branch of the sysctl(3) MIB.

rxd Number of reception descriptors enabled (read-only). Use the tunable hw.em.rxd or hw.emY.rxd to configure it.

txd Number of transmission descriptors enabled (read-only). Use the tunable hw.em.txd or hw.emY.txd to configure it.

int_throttle_ceil
    See the tunable hw.em.int_throttle_ceil.

int_tx_nsegs
    This value controls how many transmit descriptors should be consumed by the hardware before the hardware generates a transmit interrupt. The default value is 1/16 of the number of transmit descriptors. If polling(4) is not used on the hardware and the major part of the transmitted data are bulk data, this value could safely be set to 1/2 of the number of transmit descriptors.

tx_wreg_nsegs
    The number of transmission descriptors should be setup before the hardware register is written. Setting this value too high will have negative effect on transmission timeliness. Setting this value too low will hurt overall transmission due to the frequent hardware register writing. Default value is 8.

rx_ring_cnt
    Number of reception queues enabled (read-only). This sysctl only applies to emx. Use the tunable hw.emx.rxr or hw.emxY.rxr to configure it.

tx_ring_cnt
    Number of transmission queues that can be enabled (read-only). This sysctl only applies to emx. Use the tunable hw.emx.txr or hw.emxY.txr to configure it.

tx_ring_inuse
    Number of transmission queues being used (read-only). This sysctl only applies to emx.

SEE ALSO
arp(4), ifmedia(4), netintro(4), ng_ether(4), polling(4), vlan(4), ifconfig(8)

HISTORY
The em device driver first appeared in FreeBSD 4.4 and the emx driver first appeared in DragonFly 2.3.

AUTHORS
-nosplit The em driver was written by Intel Corporation <freebsdnic@mailbox.intel.com>.

The emx driver was written by Sepherosa Ziehau (in parts based on Intel's).