DragonFly On-Line Manual Pages
EM(4) DragonFly Kernel Interfaces Manual 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:
o Intel 82540EM Gigabit Ethernet Controller
o Intel 82540EP Gigabit Ethernet Controller
o Intel 82543GC Gigabit Ethernet Controller
o Intel 82544EI Gigabit Ethernet Controller
o Intel 82544GC Gigabit Ethernet Controller
o Intel 82545GM Gigabit Ethernet Controller
o Intel 82546EB Gigabit Ethernet Controller
o Intel 82547GI Gigabit Ethernet Controller
o Intel 82567 Gigabit Ethernet Controller
o Intel 82571EB Gigabit Ethernet Controller
o Intel 82572EI Gigabit Ethernet Controller
o Intel 82573E Gigabit Ethernet Controller
o Intel 82573L Gigabit Ethernet Controller
o Intel 82573V Gigabit Ethernet Controller
o Intel 82574IT Gigabit Ethernet Controller
o Intel 82574L Gigabit Ethernet Controller
o Intel 82578DC Gigabit Ethernet PHY
o Intel 82578DM Gigabit Ethernet PHY
o Intel 82579LM Gigabit Ethernet PHY
o Intel 82579V Gigabit Ethernet PHY
o Intel Ethernet Connection I217-LM
o Intel Ethernet Connection I217-V
o Intel Ethernet Connection I218-LM
o Intel Ethernet Connection I218-V
o Intel Ethernet Connection I219-LM
o Intel Ethernet Connection I219-V
o Intel Gigabit CT Desktop Adapter
o Intel PRO/1000 F Server Adapter
o Intel PRO/1000 MF Dual Port Server Adapter
o Intel PRO/1000 MF Server Adapter
o Intel PRO/1000 MF Server Adapter (LX)
o Intel PRO/1000 MT Dual Port Server Adapter
o Intel PRO/1000 MT Quad Port Server Adapter
o Intel PRO/1000 PF Dual Port Server Adapter
o Intel PRO/1000 PT Dual Port Server Adapter
o Intel PRO/1000 PT Quad Port Low Profile Server Adapter
o Intel PRO/1000 PT Quad Port Server Adapter
o Intel PRO/1000 T Server Adapter
o Intel PRO/1000 XT Low Profile Server Adapter
o 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
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).
DragonFly 4.9 December 17, 2017 DragonFly 4.9