share/man/man4/em.4

   1 .\"-
   2 .\" SPDX-License-Identifier: BSD-3-Clause
   3 .\"
   4 .\" Copyright (c) 2001-2003, Intel Corporation
   5 .\" All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions are met:
   9 .\"
  10 .\" 1. Redistributions of source code must retain the above copyright notice,
  11 .\"    this list of conditions and the following disclaimer.
  12 .\"
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" 3. Neither the name of the Intel Corporation nor the names of its
  18 .\"    contributors may be used to endorse or promote products derived from
  19 .\"    this software without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  22 .\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  25 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  26 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  27 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  28 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  29 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  30 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  31 .\" POSSIBILITY OF SUCH DAMAGE.
  32 .\"
  33 .\" * Other names and brands may be claimed as the property of others.
  34 .\"
  35 .Dd March 20, 2024
  36 .Dt EM 4
  37 .Os
  38 .Sh NAME
  39 .Nm em ,
  40 .Nm lem ,
  41 .Nm igb
  42 .Nd "Intel(R) PRO/1000 Gigabit Ethernet adapter driver"
  43 .Sh SYNOPSIS
  44 To compile this driver into the kernel,
  45 place the following lines in your
  46 kernel configuration file:
  47 .Bd -ragged -offset indent
  48 .Cd "device iflib"
  49 .Cd "device em"
  50 .Ed
  51 .Pp
  52 Alternatively, to load the driver as a
  53 module at boot time, place the following line in
  54 .Xr loader.conf 5 :
  55 .Bd -literal -offset indent
  56 if_em_load="YES"
  57 .Ed
  58 .Sh DESCRIPTION
  59 The
  60 .Nm
  61 driver provides support for PCI/PCI-X Gigabit Ethernet adapters based on
  62 the Intel 82540, 82541ER, 82541PI, 82542, 82543, 82544, 82545, 82546,
  63 82546EB, 82546GB, and 82547 controller chips.
  64 .Pp
  65 The
  66 .Nm
  67 driver provides support for PCI Express Gigabit Ethernet adapters
  68 based on the Intel 82571, 82572, 82573, 82574, and 82583 Ethernet
  69 controller chips.
  70 .Pp
  71 The
  72 .Nm
  73 driver provides support for Gigabit Ethernet adapters connected to I/O
  74 Controller Hub (ICH) and Platform Controller Hub (PCH) including Intel
  75 80003ES2LAN, 82562, 82566, 82567, 82577, 82578, 82579, i217, i218, and i219.
  76 .Pp
  77 The
  78 .Nm
  79 driver provides support for PCI Express Gigabit Ethernet adapters
  80 based on the Intel 82575, 82576, 82580, i210, i211, and i35x.
  81 These appear as
  82 .Nm igb
  83 interfaces to maintain compatibility with existing infrastructure.
  84 .Pp
  85 The driver supports Transmit/Receive checksum offload and Jumbo Frames
  86 on all but 82542-based adapters.
  87 .Pp
  88 Furthermore it supports TCP segmentation offload (TSO) on all adapters but
  89 those based on the 82542, 82543, 82544 and 82547 controller chips.
  90 The identification LEDs of the adapters supported by the
  91 .Nm
  92 driver can be controlled via the
  93 .Xr led 4
  94 API for localization purposes.
  95 For further hardware information, see the
  96 .Pa README
  97 included with the driver.
  98 .Pp
  99 For questions related to hardware requirements, refer to the
 100 documentation supplied with your Intel PRO/1000 adapter.
 101 All hardware requirements listed apply to use with
 102 .Fx .
 103 .Pp
 104 Support for Jumbo Frames is provided via the interface MTU setting.
 105 Selecting an MTU larger than 1500 bytes with the
 106 .Xr ifconfig 8
 107 utility configures the adapter to receive and transmit Jumbo Frames.
 108 The maximum MTU size for Jumbo Frames is 16114.
 109 .Pp
 110 This driver supports hardware assisted VLANs.
 111 The
 112 .Nm
 113 driver supports the following media types:
 114 .Bl -tag -width ".Cm 10baseT/UTP"
 115 .It Cm autoselect
 116 Enables auto-negotiation for speed and duplex.
 117 .It Cm 10baseT/UTP
 118 Sets 10Mbps operation.
 119 Use the
 120 .Cm mediaopt
 121 option to select
 122 .Cm full-duplex
 123 mode.
 124 .It Cm 100baseTX
 125 Sets 100Mbps operation.
 126 Use the
 127 .Cm mediaopt
 128 option to select
 129 .Cm full-duplex
 130 mode.
 131 .It Cm 1000baseSX
 132 Sets 1000Mbps operation.
 133 Only
 134 .Cm full-duplex
 135 mode is supported at this speed.
 136 .It Cm 1000baseTX
 137 Sets 1000Mbps operation.
 138 Only
 139 .Cm full-duplex
 140 mode is supported at this speed.
 141 .El
 142 .Pp
 143 The
 144 .Nm
 145 driver supports the following media options:
 146 .Bl -tag -width ".Cm full-duplex"
 147 .It Cm full-duplex
 148 Forces full-duplex operation
 149 .It Cm half-duplex
 150 Forces half-duplex operation.
 151 .El
 152 .Pp
 153 Only use
 154 .Cm mediaopt
 155 to set the driver to
 156 .Cm full-duplex .
 157 If
 158 .Cm mediaopt
 159 is not specified, the driver defaults to
 160 .Cm half-duplex .
 161 .Pp
 162 For more information on configuring this device, see
 163 .Xr ifconfig 8 .
 164 .Sh HARDWARE
 165 The
 166 .Nm
 167 driver supports Gigabit Ethernet adapters based on the Intel
 168 82540, 82541ER, 82541PI, 82542, 82543, 82544, 82545, 82546, 82546EB,
 169 82546GB, 82547, 82571, 82572, 82573, 82574, 82575, 82576, and 82580
 170 controller chips:
 171 .Pp
 172 .Bl -bullet -compact
 173 .It
 174 Intel Gigabit ET Dual Port Server Adapter (82576)
 175 .It
 176 Intel Gigabit VT Quad Port Server Adapter (82575)
 177 .It
 178 Intel Single, Dual and Quad Gigabit Ethernet Controller (82580)
 179 .It
 180 Intel i210 and i211 Gigabit Ethernet Controller
 181 .It
 182 Intel i350 and i354 Gigabit Ethernet Controller
 183 .It
 184 Intel PRO/1000 CT Network Connection (82547)
 185 .It
 186 Intel PRO/1000 F Server Adapter (82543)
 187 .It
 188 Intel PRO/1000 Gigabit Server Adapter (82542)
 189 .It
 190 Intel PRO/1000 GT Desktop Adapter (82541PI)
 191 .It
 192 Intel PRO/1000 MF Dual Port Server Adapter (82546)
 193 .It
 194 Intel PRO/1000 MF Server Adapter (82545)
 195 .It
 196 Intel PRO/1000 MF Server Adapter (LX) (82545)
 197 .It
 198 Intel PRO/1000 MT Desktop Adapter (82540)
 199 .It
 200 Intel PRO/1000 MT Desktop Adapter (82541)
 201 .It
 202 Intel PRO/1000 MT Dual Port Server Adapter (82546)
 203 .It
 204 Intel PRO/1000 MT Quad Port Server Adapter (82546EB)
 205 .It
 206 Intel PRO/1000 MT Server Adapter (82545)
 207 .It
 208 Intel PRO/1000 PF Dual Port Server Adapter (82571)
 209 .It
 210 Intel PRO/1000 PF Quad Port Server Adapter (82571)
 211 .It
 212 Intel PRO/1000 PF Server Adapter (82572)
 213 .It
 214 Intel PRO/1000 PT Desktop Adapter (82572)
 215 .It
 216 Intel PRO/1000 PT Dual Port Server Adapter (82571)
 217 .It
 218 Intel PRO/1000 PT Quad Port Server Adapter (82571)
 219 .It
 220 Intel PRO/1000 PT Server Adapter (82572)
 221 .It
 222 Intel PRO/1000 T Desktop Adapter (82544)
 223 .It
 224 Intel PRO/1000 T Server Adapter (82543)
 225 .It
 226 Intel PRO/1000 XF Server Adapter (82544)
 227 .It
 228 Intel PRO/1000 XT Server Adapter (82544)
 229 .El
 230 .Sh LOADER TUNABLES
 231 Tunables can be set at the
 232 .Xr loader 8
 233 prompt before booting the kernel or stored in
 234 .Xr loader.conf 5 .
 235 See
 236 .Xr iflib 4
 237 for per-instance variables.
 238 .Bl -tag -width indent
 239 .It Va hw.em.disable_crc_stripping
 240 Disable or enable hardware stripping of CRC field.
 241 This is mostly useful on BMC/IPMI shared interfaces where stripping the CRC
 242 causes remote access over IPMI to fail.
 243 Default 0 (enabled).
 244 .It Va hw.em.eee_setting
 245 Disable or enable Energy Efficient Ethernet.
 246 Default 1 (disabled).
 247 .It Va hw.em.smart_pwr_down
 248 Enable or disable smart power down features on newer adapters.
 249 Default 0 (disabled).
 250 .It Va hw.em.sbp
 251 Show bad packets when in promiscuous mode.
 252 Default 0 (off).
 253 .It Va hw.em.rx_int_delay
 254 This value delays the generation of receive interrupts in units of
 255 1.024 microseconds.
 256 The default value is 0, since adapters may hang with this feature
 257 being enabled.
 258 .It Va hw.em.rx_abs_int_delay
 259 If
 260 .Va hw.em.rx_int_delay
 261 is non-zero, this tunable limits the maximum delay in which a receive
 262 interrupt is generated.
 263 .It Va hw.em.tx_int_delay
 264 This value delays the generation of transmit interrupts in units of
 265 1.024 microseconds.
 266 The default value is 64.
 267 .It Va hw.em.tx_abs_int_delay
 268 If
 269 .Va hw.em.tx_int_delay
 270 is non-zero, this tunable limits the maximum delay in which a transmit
 271 interrupt is generated.
 272 .It Va hw.em.max_interrupt_rate
 273 Maximum interrupts per second.
 274 The default value is 8000.
 275 .It Va hw.em.rx_process_limit
 276 Maximum number of received packets to process at a time, -1 means unlimited.
 277 The default value is 100.
 278 .El
 279 .Sh FILES
 280 .Bl -tag -width /dev/led/em*
 281 .It Pa /dev/led/em*
 282 identification LED device nodes
 283 .El
 284 .Sh EXAMPLES
 285 Make the identification LED of em0 blink:
 286 .Pp
 287 .Dl "echo f2 > /dev/led/em0"
 288 .Pp
 289 Turn the identification LED of em0 off again:
 290 .Pp
 291 .Dl "echo 0 > /dev/led/em0"
 292 .Sh DIAGNOSTICS
 293 .Bl -diag
 294 .It "em%d: Unable to allocate bus resource: memory"
 295 A fatal initialization error has occurred.
 296 .It "em%d: Unable to allocate bus resource: interrupt"
 297 A fatal initialization error has occurred.
 298 .It "em%d: watchdog timeout -- resetting"
 299 The device has stopped responding to the network, or there is a problem with
 300 the network connection (cable).
 301 .El
 302 .Sh SUPPORT
 303 For general information and support,
 304 go to the Intel support website at:
 305 .Pa http://support.intel.com .
 306 .Pp
 307 If an issue is identified with the released source code on the supported kernel
 308 with a supported adapter, email the specific information related to the
 309 issue to
 310 .Aq Mt freebsd@intel.com .
 311 .Sh SEE ALSO
 312 .Xr altq 4 ,
 313 .Xr arp 4 ,
 314 .Xr iflib 4 ,
 315 .Xr led 4 ,
 316 .Xr netintro 4 ,
 317 .Xr ng_ether 4 ,
 318 .Xr polling 4 ,
 319 .Xr vlan 4 ,
 320 .Xr ifconfig 8
 321 .Sh HISTORY
 322 The
 323 .Nm
 324 device driver first appeared in
 325 .Fx 4.4 .
 326 .Nm
 327 was merged with the
 328 .Nm lem
 329 and
 330 .Nm igb
 331 device drivers and converted to the
 332 .Xr iflib 4
 333 framework in
 334 .Fx 12.0 .
 335 .Sh AUTHORS
 336 .An -nosplit
 337 The
 338 .Nm
 339 driver was originally written by
 340 .An Intel Corporation Aq Mt freebsd@intel.com .
 341 It was merged with the
 342 .Nm igb
 343 driver and converted to the
 344 .Xr iflib 4
 345 framework by
 346 .An Matthew Macy Aq Mt mmacy@mattmacy.io
 347 and
 348 .An Sean Bruno Aq Mt sbruno@FreeBSD.org .