Documentation/networking/e1000.rst

   1 ===========================================================
   2 Linux* Base Driver for Intel(R) Ethernet Network Connection
   3 ===========================================================
   4
   5 Intel Gigabit Linux driver.
   6 Copyright(c) 1999 - 2013 Intel Corporation.
   7
   8 Contents
   9 ========
  10
  11 - Identifying Your Adapter
  12 - Command Line Parameters
  13 - Speed and Duplex Configuration
  14 - Additional Configurations
  15 - Support
  16
  17 Identifying Your Adapter
  18 ========================
  19
  20 For more information on how to identify your adapter, go to the Adapter &
  21 Driver ID Guide at:
  22
  23     http://support.intel.com/support/go/network/adapter/idguide.htm
  24
  25 For the latest Intel network drivers for Linux, refer to the following
  26 website.  In the search field, enter your adapter name or type, or use the
  27 networking link on the left to search for your adapter:
  28
  29     http://support.intel.com/support/go/network/adapter/home.htm
  30
  31 Command Line Parameters
  32 =======================
  33
  34 The default value for each parameter is generally the recommended setting,
  35 unless otherwise noted.
  36
  37 NOTES:
  38         For more information about the AutoNeg, Duplex, and Speed
  39         parameters, see the "Speed and Duplex Configuration" section in
  40         this document.
  41
  42         For more information about the InterruptThrottleRate,
  43         RxIntDelay, TxIntDelay, RxAbsIntDelay, and TxAbsIntDelay
  44         parameters, see the application note at:
  45         http://www.intel.com/design/network/applnots/ap450.htm
  46
  47 AutoNeg
  48 -------
  49
  50 (Supported only on adapters with copper connections)
  51
  52 :Valid Range:   0x01-0x0F, 0x20-0x2F
  53 :Default Value: 0x2F
  54
  55 This parameter is a bit-mask that specifies the speed and duplex settings
  56 advertised by the adapter.  When this parameter is used, the Speed and
  57 Duplex parameters must not be specified.
  58
  59 NOTE:
  60        Refer to the Speed and Duplex section of this readme for more
  61        information on the AutoNeg parameter.
  62
  63 Duplex
  64 ------
  65
  66 (Supported only on adapters with copper connections)
  67
  68 :Valid Range:   0-2 (0=auto-negotiate, 1=half, 2=full)
  69 :Default Value: 0
  70
  71 This defines the direction in which data is allowed to flow.  Can be
  72 either one or two-directional.  If both Duplex and the link partner are
  73 set to auto-negotiate, the board auto-detects the correct duplex.  If the
  74 link partner is forced (either full or half), Duplex defaults to half-
  75 duplex.
  76
  77 FlowControl
  78 -----------
  79
  80 :Valid Range:   0-3 (0=none, 1=Rx only, 2=Tx only, 3=Rx&Tx)
  81 :Default Value: Reads flow control settings from the EEPROM
  82
  83 This parameter controls the automatic generation(Tx) and response(Rx)
  84 to Ethernet PAUSE frames.
  85
  86 InterruptThrottleRate
  87 ---------------------
  88
  89 (not supported on Intel(R) 82542, 82543 or 82544-based adapters)
  90
  91 :Valid Range:
  92    0,1,3,4,100-100000 (0=off, 1=dynamic, 3=dynamic conservative,
  93    4=simplified balancing)
  94 :Default Value: 3
  95
  96 The driver can limit the amount of interrupts per second that the adapter
  97 will generate for incoming packets. It does this by writing a value to the
  98 adapter that is based on the maximum amount of interrupts that the adapter
  99 will generate per second.
 100
 101 Setting InterruptThrottleRate to a value greater or equal to 100
 102 will program the adapter to send out a maximum of that many interrupts
 103 per second, even if more packets have come in. This reduces interrupt
 104 load on the system and can lower CPU utilization under heavy load,
 105 but will increase latency as packets are not processed as quickly.
 106
 107 The default behaviour of the driver previously assumed a static
 108 InterruptThrottleRate value of 8000, providing a good fallback value for
 109 all traffic types,but lacking in small packet performance and latency.
 110 The hardware can handle many more small packets per second however, and
 111 for this reason an adaptive interrupt moderation algorithm was implemented.
 112
 113 Since 7.3.x, the driver has two adaptive modes (setting 1 or 3) in which
 114 it dynamically adjusts the InterruptThrottleRate value based on the traffic
 115 that it receives. After determining the type of incoming traffic in the last
 116 timeframe, it will adjust the InterruptThrottleRate to an appropriate value
 117 for that traffic.
 118
 119 The algorithm classifies the incoming traffic every interval into
 120 classes.  Once the class is determined, the InterruptThrottleRate value is
 121 adjusted to suit that traffic type the best. There are three classes defined:
 122 "Bulk traffic", for large amounts of packets of normal size; "Low latency",
 123 for small amounts of traffic and/or a significant percentage of small
 124 packets; and "Lowest latency", for almost completely small packets or
 125 minimal traffic.
 126
 127 In dynamic conservative mode, the InterruptThrottleRate value is set to 4000
 128 for traffic that falls in class "Bulk traffic". If traffic falls in the "Low
 129 latency" or "Lowest latency" class, the InterruptThrottleRate is increased
 130 stepwise to 20000. This default mode is suitable for most applications.
 131
 132 For situations where low latency is vital such as cluster or
 133 grid computing, the algorithm can reduce latency even more when
 134 InterruptThrottleRate is set to mode 1. In this mode, which operates
 135 the same as mode 3, the InterruptThrottleRate will be increased stepwise to
 136 70000 for traffic in class "Lowest latency".
 137
 138 In simplified mode the interrupt rate is based on the ratio of TX and
 139 RX traffic.  If the bytes per second rate is approximately equal, the
 140 interrupt rate will drop as low as 2000 interrupts per second.  If the
 141 traffic is mostly transmit or mostly receive, the interrupt rate could
 142 be as high as 8000.
 143
 144 Setting InterruptThrottleRate to 0 turns off any interrupt moderation
 145 and may improve small packet latency, but is generally not suitable
 146 for bulk throughput traffic.
 147
 148 NOTE:
 149        InterruptThrottleRate takes precedence over the TxAbsIntDelay and
 150        RxAbsIntDelay parameters.  In other words, minimizing the receive
 151        and/or transmit absolute delays does not force the controller to
 152        generate more interrupts than what the Interrupt Throttle Rate
 153        allows.
 154
 155 CAUTION:
 156           If you are using the Intel(R) PRO/1000 CT Network Connection
 157           (controller 82547), setting InterruptThrottleRate to a value
 158           greater than 75,000, may hang (stop transmitting) adapters
 159           under certain network conditions.  If this occurs a NETDEV
 160           WATCHDOG message is logged in the system event log.  In
 161           addition, the controller is automatically reset, restoring
 162           the network connection.  To eliminate the potential for the
 163           hang, ensure that InterruptThrottleRate is set no greater
 164           than 75,000 and is not set to 0.
 165
 166 NOTE:
 167        When e1000 is loaded with default settings and multiple adapters
 168        are in use simultaneously, the CPU utilization may increase non-
 169        linearly.  In order to limit the CPU utilization without impacting
 170        the overall throughput, we recommend that you load the driver as
 171        follows::
 172
 173            modprobe e1000 InterruptThrottleRate=3000,3000,3000
 174
 175        This sets the InterruptThrottleRate to 3000 interrupts/sec for
 176        the first, second, and third instances of the driver.  The range
 177        of 2000 to 3000 interrupts per second works on a majority of
 178        systems and is a good starting point, but the optimal value will
 179        be platform-specific.  If CPU utilization is not a concern, use
 180        RX_POLLING (NAPI) and default driver settings.
 181
 182 RxDescriptors
 183 -------------
 184
 185 :Valid Range:
 186  - 48-256 for 82542 and 82543-based adapters
 187  - 48-4096 for all other supported adapters
 188 :Default Value: 256
 189
 190 This value specifies the number of receive buffer descriptors allocated
 191 by the driver.  Increasing this value allows the driver to buffer more
 192 incoming packets, at the expense of increased system memory utilization.
 193
 194 Each descriptor is 16 bytes.  A receive buffer is also allocated for each
 195 descriptor and can be either 2048, 4096, 8192, or 16384 bytes, depending
 196 on the MTU setting. The maximum MTU size is 16110.
 197
 198 NOTE:
 199        MTU designates the frame size.  It only needs to be set for Jumbo
 200        Frames.  Depending on the available system resources, the request
 201        for a higher number of receive descriptors may be denied.  In this
 202        case, use a lower number.
 203
 204 RxIntDelay
 205 ----------
 206
 207 :Valid Range:   0-65535 (0=off)
 208 :Default Value: 0
 209
 210 This value delays the generation of receive interrupts in units of 1.024
 211 microseconds.  Receive interrupt reduction can improve CPU efficiency if
 212 properly tuned for specific network traffic.  Increasing this value adds
 213 extra latency to frame reception and can end up decreasing the throughput
 214 of TCP traffic.  If the system is reporting dropped receives, this value
 215 may be set too high, causing the driver to run out of available receive
 216 descriptors.
 217
 218 CAUTION:
 219           When setting RxIntDelay to a value other than 0, adapters may
 220           hang (stop transmitting) under certain network conditions.  If
 221           this occurs a NETDEV WATCHDOG message is logged in the system
 222           event log.  In addition, the controller is automatically reset,
 223           restoring the network connection.  To eliminate the potential
 224           for the hang ensure that RxIntDelay is set to 0.
 225
 226 RxAbsIntDelay
 227 -------------
 228
 229 (This parameter is supported only on 82540, 82545 and later adapters.)
 230
 231 :Valid Range:   0-65535 (0=off)
 232 :Default Value: 128
 233
 234 This value, in units of 1.024 microseconds, limits the delay in which a
 235 receive interrupt is generated.  Useful only if RxIntDelay is non-zero,
 236 this value ensures that an interrupt is generated after the initial
 237 packet is received within the set amount of time.  Proper tuning,
 238 along with RxIntDelay, may improve traffic throughput in specific network
 239 conditions.
 240
 241 Speed
 242 -----
 243
 244 (This parameter is supported only on adapters with copper connections.)
 245
 246 :Valid Settings: 0, 10, 100, 1000
 247 :Default Value:  0 (auto-negotiate at all supported speeds)
 248
 249 Speed forces the line speed to the specified value in megabits per second
 250 (Mbps).  If this parameter is not specified or is set to 0 and the link
 251 partner is set to auto-negotiate, the board will auto-detect the correct
 252 speed.  Duplex should also be set when Speed is set to either 10 or 100.
 253
 254 TxDescriptors
 255 -------------
 256
 257 :Valid Range:
 258   - 48-256 for 82542 and 82543-based adapters
 259   - 48-4096 for all other supported adapters
 260 :Default Value: 256
 261
 262 This value is the number of transmit descriptors allocated by the driver.
 263 Increasing this value allows the driver to queue more transmits.  Each
 264 descriptor is 16 bytes.
 265
 266 NOTE:
 267        Depending on the available system resources, the request for a
 268        higher number of transmit descriptors may be denied.  In this case,
 269        use a lower number.
 270
 271 TxIntDelay
 272 ----------
 273
 274 :Valid Range:   0-65535 (0=off)
 275 :Default Value: 8
 276
 277 This value delays the generation of transmit interrupts in units of
 278 1.024 microseconds.  Transmit interrupt reduction can improve CPU
 279 efficiency if properly tuned for specific network traffic.  If the
 280 system is reporting dropped transmits, this value may be set too high
 281 causing the driver to run out of available transmit descriptors.
 282
 283 TxAbsIntDelay
 284 -------------
 285
 286 (This parameter is supported only on 82540, 82545 and later adapters.)
 287
 288 :Valid Range:   0-65535 (0=off)
 289 :Default Value: 32
 290
 291 This value, in units of 1.024 microseconds, limits the delay in which a
 292 transmit interrupt is generated.  Useful only if TxIntDelay is non-zero,
 293 this value ensures that an interrupt is generated after the initial
 294 packet is sent on the wire within the set amount of time.  Proper tuning,
 295 along with TxIntDelay, may improve traffic throughput in specific
 296 network conditions.
 297
 298 XsumRX
 299 ------
 300
 301 (This parameter is NOT supported on the 82542-based adapter.)
 302
 303 :Valid Range:   0-1
 304 :Default Value: 1
 305
 306 A value of '1' indicates that the driver should enable IP checksum
 307 offload for received packets (both UDP and TCP) to the adapter hardware.
 308
 309 Copybreak
 310 ---------
 311
 312 :Valid Range:   0-xxxxxxx (0=off)
 313 :Default Value: 256
 314 :Usage: modprobe e1000.ko copybreak=128
 315
 316 Driver copies all packets below or equaling this size to a fresh RX
 317 buffer before handing it up the stack.
 318
 319 This parameter is different than other parameters, in that it is a
 320 single (not 1,1,1 etc.) parameter applied to all driver instances and
 321 it is also available during runtime at
 322 /sys/module/e1000/parameters/copybreak
 323
 324 SmartPowerDownEnable
 325 --------------------
 326
 327 :Valid Range: 0-1
 328 :Default Value:  0 (disabled)
 329
 330 Allows PHY to turn off in lower power states. The user can turn off
 331 this parameter in supported chipsets.
 332
 333 Speed and Duplex Configuration
 334 ==============================
 335
 336 Three keywords are used to control the speed and duplex configuration.
 337 These keywords are Speed, Duplex, and AutoNeg.
 338
 339 If the board uses a fiber interface, these keywords are ignored, and the
 340 fiber interface board only links at 1000 Mbps full-duplex.
 341
 342 For copper-based boards, the keywords interact as follows:
 343
 344 - The default operation is auto-negotiate.  The board advertises all
 345   supported speed and duplex combinations, and it links at the highest
 346   common speed and duplex mode IF the link partner is set to auto-negotiate.
 347
 348 - If Speed = 1000, limited auto-negotiation is enabled and only 1000 Mbps
 349   is advertised (The 1000BaseT spec requires auto-negotiation.)
 350
 351 - If Speed = 10 or 100, then both Speed and Duplex should be set.  Auto-
 352   negotiation is disabled, and the AutoNeg parameter is ignored.  Partner
 353   SHOULD also be forced.
 354
 355 The AutoNeg parameter is used when more control is required over the
 356 auto-negotiation process.  It should be used when you wish to control which
 357 speed and duplex combinations are advertised during the auto-negotiation
 358 process.
 359
 360 The parameter may be specified as either a decimal or hexadecimal value as
 361 determined by the bitmap below.
 362
 363 ============== ====== ====== ======= ======= ====== ====== ======= ======
 364 Bit position   7      6      5       4       3      2      1       0
 365 Decimal Value  128    64     32      16      8      4      2       1
 366 Hex value      80     40     20      10      8      4      2       1
 367 Speed (Mbps)   N/A    N/A    1000    N/A     100    100    10      10
 368 Duplex                       Full            Full   Half   Full    Half
 369 ============== ====== ====== ======= ======= ====== ====== ======= ======
 370
 371 Some examples of using AutoNeg::
 372
 373   modprobe e1000 AutoNeg=0x01 (Restricts autonegotiation to 10 Half)
 374   modprobe e1000 AutoNeg=1 (Same as above)
 375   modprobe e1000 AutoNeg=0x02 (Restricts autonegotiation to 10 Full)
 376   modprobe e1000 AutoNeg=0x03 (Restricts autonegotiation to 10 Half or 10 Full)
 377   modprobe e1000 AutoNeg=0x04 (Restricts autonegotiation to 100 Half)
 378   modprobe e1000 AutoNeg=0x05 (Restricts autonegotiation to 10 Half or 100
 379   Half)
 380   modprobe e1000 AutoNeg=0x020 (Restricts autonegotiation to 1000 Full)
 381   modprobe e1000 AutoNeg=32 (Same as above)
 382
 383 Note that when this parameter is used, Speed and Duplex must not be specified.
 384
 385 If the link partner is forced to a specific speed and duplex, then this
 386 parameter should not be used.  Instead, use the Speed and Duplex parameters
 387 previously mentioned to force the adapter to the same speed and duplex.
 388
 389 Additional Configurations
 390 =========================
 391
 392 Jumbo Frames
 393 ------------
 394
 395   Jumbo Frames support is enabled by changing the MTU to a value larger than
 396   the default of 1500.  Use the ifconfig command to increase the MTU size.
 397   For example::
 398
 399        ifconfig eth<x> mtu 9000 up
 400
 401   This setting is not saved across reboots.  It can be made permanent if
 402   you add::
 403
 404        MTU=9000
 405
 406   to the file /etc/sysconfig/network-scripts/ifcfg-eth<x>.  This example
 407   applies to the Red Hat distributions; other distributions may store this
 408   setting in a different location.
 409
 410 Notes:
 411   Degradation in throughput performance may be observed in some Jumbo frames
 412   environments. If this is observed, increasing the application's socket buffer
 413   size and/or increasing the /proc/sys/net/ipv4/tcp_*mem entry values may help.
 414   See the specific application manual and /usr/src/linux*/Documentation/
 415   networking/ip-sysctl.txt for more details.
 416
 417   - The maximum MTU setting for Jumbo Frames is 16110.  This value coincides
 418     with the maximum Jumbo Frames size of 16128.
 419
 420   - Using Jumbo frames at 10 or 100 Mbps is not supported and may result in
 421     poor performance or loss of link.
 422
 423   - Adapters based on the Intel(R) 82542 and 82573V/E controller do not
 424     support Jumbo Frames. These correspond to the following product names::
 425
 426      Intel(R) PRO/1000 Gigabit Server Adapter
 427      Intel(R) PRO/1000 PM Network Connection
 428
 429 ethtool
 430 -------
 431
 432   The driver utilizes the ethtool interface for driver configuration and
 433   diagnostics, as well as displaying statistical information.  The ethtool
 434   version 1.6 or later is required for this functionality.
 435
 436   The latest release of ethtool can be found from
 437   https://www.kernel.org/pub/software/network/ethtool/
 438
 439 Enabling Wake on LAN* (WoL)
 440 ---------------------------
 441
 442   WoL is configured through the ethtool* utility.
 443
 444   WoL will be enabled on the system during the next shut down or reboot.
 445   For this driver version, in order to enable WoL, the e1000 driver must be
 446   loaded when shutting down or rebooting the system.
 447
 448 Support
 449 =======
 450
 451 For general information, go to the Intel support website at:
 452
 453     http://support.intel.com
 454
 455 or the Intel Wired Networking project hosted by Sourceforge at:
 456
 457     http://sourceforge.net/projects/e1000
 458
 459 If an issue is identified with the released source code on the supported
 460 kernel with a supported adapter, email the specific information related
 461 to the issue to e1000-devel@lists.sf.net