1 .. SPDX-License-Identifier: GPL-2.0+
3 Linux Base Driver for 10 Gigabit Intel(R) Ethernet Network Connection
4 =====================================================================
13 - Identifying Your Adapter
14 - Command Line Parameters
15 - Improving Performance
16 - Additional Configurations
17 - Known Issues/Troubleshooting
25 This file describes the ixgb Linux Base Driver for the 10 Gigabit Intel(R)
26 Network Connection. This driver includes support for Itanium(R)2-based
29 For questions related to hardware requirements, refer to the documentation
30 supplied with your 10 Gigabit adapter. All hardware requirements listed apply
33 The following features are available in this kernel:
35 - Channel Bonding (teaming)
38 Channel Bonding documentation can be found in the Linux kernel source:
39 /Documentation/networking/bonding.txt
41 The driver information previously displayed in the /proc filesystem is not
42 supported in this release. Alternatively, you can use ethtool (version 1.6
43 or later), lspci, and iproute2 to obtain the same information.
45 Instructions on updating ethtool can be found in the section "Additional
46 Configurations" later in this document.
49 Identifying Your Adapter
50 ========================
52 The following Intel network adapters are compatible with the drivers in this
55 +------------+------------------------------+----------------------------------+
56 | Controller | Adapter Name | Physical Layer |
57 +============+==============================+==================================+
58 | 82597EX | Intel(R) PRO/10GbE LR/SR/CX4 | - 10G Base-LR (fiber) |
59 | | Server Adapters | - 10G Base-SR (fiber) |
60 | | | - 10G Base-CX4 (copper) |
61 +------------+------------------------------+----------------------------------+
63 For more information on how to identify your adapter, go to the Adapter &
66 https://support.intel.com
69 Command Line Parameters
70 =======================
72 If the driver is built as a module, the following optional parameters are
73 used by entering them on the command line with the modprobe command using
76 modprobe ixgb [<option>=<VAL1>,<VAL2>,...]
78 For example, with two 10GbE PCI adapters, entering::
80 modprobe ixgb TxDescriptors=80,128
82 loads the ixgb driver with 80 TX resources for the first adapter and 128 TX
83 resources for the second adapter.
85 The default value for each parameter is generally the recommended setting,
86 unless otherwise noted.
93 This is the maximum size of packet that is copied to a new buffer on
98 :Valid Range: 0-16 (0=none,...,16=all)
101 This parameter adjusts the level of debug messages displayed in the
106 :Valid Range: 0-3 (0=none, 1=Rx only, 2=Tx only, 3=Rx&Tx)
107 :Default Value: 1 if no EEPROM, otherwise read from EEPROM
109 This parameter controls the automatic generation(Tx) and response(Rx) to
110 Ethernet PAUSE frames. There are hardware bugs associated with enabling
111 Tx flow control so beware.
115 :Valid Range: 64-4096
118 This value is the number of receive descriptors allocated by the driver.
119 Increasing this value allows the driver to buffer more incoming packets.
120 Each descriptor is 16 bytes. A receive buffer is also allocated for
121 each descriptor and can be either 2048, 4056, 8192, or 16384 bytes,
122 depending on the MTU setting. When the MTU size is 1500 or less, the
123 receive buffer size is 2048 bytes. When the MTU is greater than 1500 the
124 receive buffer size will be either 4056, 8192, or 16384 bytes. The
125 maximum MTU size is 16114.
129 :Valid Range: 64-4096
132 This value is the number of transmit descriptors allocated by the driver.
133 Increasing this value allows the driver to queue more transmits. Each
134 descriptor is 16 bytes.
138 :Valid Range: 0-65535 (0=off)
141 This value delays the generation of receive interrupts in units of
142 0.8192 microseconds. Receive interrupt reduction can improve CPU
143 efficiency if properly tuned for specific network traffic. Increasing
144 this value adds extra latency to frame reception and can end up
145 decreasing the throughput of TCP traffic. If the system is reporting
146 dropped receives, this value may be set too high, causing the driver to
147 run out of available receive descriptors.
151 :Valid Range: 0-65535 (0=off)
154 This value delays the generation of transmit interrupts in units of
155 0.8192 microseconds. Transmit interrupt reduction can improve CPU
156 efficiency if properly tuned for specific network traffic. Increasing
157 this value adds extra latency to frame transmission and can end up
158 decreasing the throughput of TCP traffic. If this value is set too high,
159 it will cause the driver to run out of available transmit descriptors.
166 A value of '1' indicates that the driver should enable IP checksum
167 offload for received packets (both UDP and TCP) to the adapter hardware.
171 :Valid Range: 1,536-262,136 (0x600 - 0x3FFF8, 8 byte granularity)
172 :Default Value: 196,608 (0x30000)
174 Receive Flow control high threshold (when we send a pause frame)
178 :Valid Range: 64-262,136 (0x40 - 0x3FFF8, 8 byte granularity)
179 :Default Value: 163,840 (0x28000)
181 Receive Flow control low threshold (when we send a resume frame)
185 :Valid Range: 1-65535
186 :Default Value: 65535
188 Flow control request timeout (how long to pause the link partner's tx)
195 Interrupt Delay, 0 disables transmit interrupt delay and 1 enables it.
198 Improving Performance
199 =====================
201 With the 10 Gigabit server adapters, the default Linux configuration will
202 very likely limit the total available throughput artificially. There is a set
203 of configuration changes that, when applied together, will increase the ability
204 of Linux to transmit and receive data. The following enhancements were
205 originally acquired from settings published at http://www.spec.org/web99/ for
206 various submitted results using Linux.
209 These changes are only suggestions, and serve as a starting point for
210 tuning your network performance.
212 The changes are made in three major ways, listed in order of greatest effect:
214 - Use ip link to modify the mtu (maximum transmission unit) and the txqueuelen
216 - Use sysctl to modify /proc parameters (essentially kernel tuning)
217 - Use setpci to modify the MMRBC field in PCI-X configuration space to increase
218 transmit burst lengths on the bus.
221 setpci modifies the adapter's configuration registers to allow it to read
222 up to 4k bytes at a time (for transmits). However, for some systems the
223 behavior after modifying this register may be undefined (possibly errors of
224 some kind). A power-cycle, hard reset or explicitly setting the e6 register
225 back to 22 (setpci -d 8086:1a48 e6.b=22) may be required to get back to a
226 stable configuration.
228 - COPY these lines and paste them into ixgb_perf.sh:
233 echo "configuring network performance , edit this file to change the interface
234 or device ID of 10GbE card"
235 # set mmrbc to 4k reads, modify only Intel 10GbE device IDs
236 # replace 1a48 with appropriate 10GbE device's ID installed on the system,
238 setpci -d 8086:1a48 e6.b=2e
239 # set the MTU (max transmission unit) - it requires your switch and clients
242 # your ixgb adapter should be loaded as eth1 for this to work, change if needed
243 ip li set dev eth1 mtu 9000 txqueuelen 1000 up
244 # call the sysctl utility to modify /proc/sys entries
245 sysctl -p ./sysctl_ixgb.conf
247 - COPY these lines and paste them into sysctl_ixgb.conf:
251 # some of the defaults may be different for your kernel
252 # call this file with sysctl -p <this file>
253 # these are just suggested values that worked well to increase throughput in
254 # several network benchmark tests, your mileage may vary
256 ### IPV4 specific settings
257 # turn TCP timestamp support off, default 1, reduces CPU use
258 net.ipv4.tcp_timestamps = 0
259 # turn SACK support off, default on
260 # on systems with a VERY fast bus -> memory interface this is the big gainer
261 net.ipv4.tcp_sack = 0
262 # set min/default/max TCP read buffer, default 4096 87380 174760
263 net.ipv4.tcp_rmem = 10000000 10000000 10000000
264 # set min/pressure/max TCP write buffer, default 4096 16384 131072
265 net.ipv4.tcp_wmem = 10000000 10000000 10000000
266 # set min/pressure/max TCP buffer space, default 31744 32256 32768
267 net.ipv4.tcp_mem = 10000000 10000000 10000000
269 ### CORE settings (mostly for socket and UDP effect)
270 # set maximum receive socket buffer size, default 131071
271 net.core.rmem_max = 524287
272 # set maximum send socket buffer size, default 131071
273 net.core.wmem_max = 524287
274 # set default receive socket buffer size, default 65535
275 net.core.rmem_default = 524287
276 # set default send socket buffer size, default 65535
277 net.core.wmem_default = 524287
278 # set maximum amount of option memory buffers, default 10240
279 net.core.optmem_max = 524287
280 # set number of unprocessed input packets before kernel starts dropping them; default 300
281 net.core.netdev_max_backlog = 300000
283 Edit the ixgb_perf.sh script if necessary to change eth1 to whatever interface
284 your ixgb driver is using and/or replace '1a48' with appropriate 10GbE device's
285 ID installed on the system.
288 Unless these scripts are added to the boot process, these changes will
289 only last only until the next system reboot.
292 Resolving Slow UDP Traffic
293 --------------------------
294 If your server does not seem to be able to receive UDP traffic as fast as it
295 can receive TCP traffic, it could be because Linux, by default, does not set
296 the network stack buffers as large as they need to be to support high UDP
297 transfer rates. One way to alleviate this problem is to allow more memory to
298 be used by the IP stack to store incoming data.
300 For instance, use the commands::
302 sysctl -w net.core.rmem_max=262143
306 sysctl -w net.core.rmem_default=262143
308 to increase the read buffer memory max and default to 262143 (256k - 1) from
309 defaults of max=131071 (128k - 1) and default=65535 (64k - 1). These variables
310 will increase the amount of memory used by the network stack for receives, and
311 can be increased significantly more if necessary for your application.
314 Additional Configurations
315 =========================
317 Configuring the Driver on Different Distributions
318 -------------------------------------------------
319 Configuring a network driver to load properly when the system is started is
320 distribution dependent. Typically, the configuration process involves adding
321 an alias line to /etc/modprobe.conf as well as editing other system startup
322 scripts and/or configuration files. Many popular Linux distributions ship
323 with tools to make these changes for you. To learn the proper way to
324 configure a network device for your system, refer to your distribution
325 documentation. If during this process you are asked for the driver or module
326 name, the name for the Linux Base Driver for the Intel 10GbE Family of
329 Viewing Link Messages
330 ---------------------
331 Link messages will not be displayed to the console if the distribution is
332 restricting system messages. In order to see network driver link messages on
333 your console, set dmesg to eight by entering the following::
337 NOTE: This setting is not saved across reboots.
341 The driver supports Jumbo Frames for all adapters. Jumbo Frames support is
342 enabled by changing the MTU to a value larger than the default of 1500.
343 The maximum value for the MTU is 16114. Use the ip command to
344 increase the MTU size. For example::
346 ip li set dev ethx mtu 9000
348 The maximum MTU setting for Jumbo Frames is 16114. This value coincides
349 with the maximum Jumbo Frames size of 16128.
353 The driver utilizes the ethtool interface for driver configuration and
354 diagnostics, as well as displaying statistical information. The ethtool
355 version 1.6 or later is required for this functionality.
357 The latest release of ethtool can be found from
358 https://www.kernel.org/pub/software/network/ethtool/
361 The ethtool version 1.6 only supports a limited set of ethtool options.
362 Support for a more complete ethtool feature set can be enabled by
363 upgrading to the latest version.
367 NAPI (Rx polling mode) is supported in the ixgb driver.
369 See https://wiki.linuxfoundation.org/networking/napi for more information on
373 Known Issues/Troubleshooting
374 ============================
377 After installing the driver, if your Intel Network Connection is not
378 working, verify in the "In This Release" section of the readme that you have
379 installed the correct driver.
381 Cable Interoperability Issue with Fujitsu XENPAK Module in SmartBits Chassis
382 ----------------------------------------------------------------------------
383 Excessive CRC errors may be observed if the Intel(R) PRO/10GbE CX4
384 Server adapter is connected to a Fujitsu XENPAK CX4 module in a SmartBits
385 chassis using 15 m/24AWG cable assemblies manufactured by Fujitsu or Leoni.
386 The CRC errors may be received either by the Intel(R) PRO/10GbE CX4
387 Server adapter or the SmartBits. If this situation occurs using a different
388 cable assembly may resolve the issue.
390 Cable Interoperability Issues with HP Procurve 3400cl Switch Port
391 -----------------------------------------------------------------
392 Excessive CRC errors may be observed if the Intel(R) PRO/10GbE CX4 Server
393 adapter is connected to an HP Procurve 3400cl switch port using short cables
394 (1 m or shorter). If this situation occurs, using a longer cable may resolve
397 Excessive CRC errors may be observed using Fujitsu 24AWG cable assemblies that
398 Are 10 m or longer or where using a Leoni 15 m/24AWG cable assembly. The CRC
399 errors may be received either by the CX4 Server adapter or at the switch. If
400 this situation occurs, using a different cable assembly may resolve the issue.
402 Jumbo Frames System Requirement
403 -------------------------------
404 Memory allocation failures have been observed on Linux systems with 64 MB
405 of RAM or less that are running Jumbo Frames. If you are using Jumbo
406 Frames, your system may require more than the advertised minimum
407 requirement of 64 MB of system memory.
409 Performance Degradation with Jumbo Frames
410 -----------------------------------------
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.
417 Allocating Rx Buffers when Using Jumbo Frames
418 ---------------------------------------------
419 Allocating Rx buffers when using Jumbo Frames on 2.6.x kernels may fail if
420 the available memory is heavily fragmented. This issue may be seen with PCI-X
421 adapters or with packet split disabled. This can be reduced or eliminated
422 by changing the amount of available memory for receive buffer allocation, by
423 increasing /proc/sys/vm/min_free_kbytes.
425 Multiple Interfaces on Same Ethernet Broadcast Network
426 ------------------------------------------------------
427 Due to the default ARP behavior on Linux, it is not possible to have
428 one system on two IP networks in the same Ethernet broadcast domain
429 (non-partitioned switch) behave as expected. All Ethernet interfaces
430 will respond to IP traffic for any IP address assigned to the system.
431 This results in unbalanced receive traffic.
433 If you have multiple interfaces in a server, do either of the following:
435 - Turn on ARP filtering by entering::
437 echo 1 > /proc/sys/net/ipv4/conf/all/arp_filter
439 - Install the interfaces in separate broadcast domains - either in
440 different switches or in a switch partitioned to VLANs.
442 UDP Stress Test Dropped Packet Issue
443 --------------------------------------
444 Under small packets UDP stress test with 10GbE driver, the Linux system
445 may drop UDP packets due to the fullness of socket buffers. You may want
446 to change the driver's Flow Control variables to the minimum value for
447 controlling packet reception.
449 Tx Hangs Possible Under Stress
450 ------------------------------
451 Under stress conditions, if TX hangs occur, turning off TSO
452 "ethtool -K eth0 tso off" may resolve the problem.
457 For general information, go to the Intel support website at:
459 https://www.intel.com/support/
461 or the Intel Wired Networking project hosted by Sourceforge at:
463 https://sourceforge.net/projects/e1000
465 If an issue is identified with the released source code on a supported kernel
466 with a supported adapter, email the specific information related to the issue
467 to e1000-devel@lists.sf.net