blob: 2ebd4058d46d4b3b17df8d2b04310a47ffd1baf4 [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001Linux* Base Driver for the Intel(R) PRO/1000 Family of Adapters
2===============================================================
3
4November 17, 2004
5
6
7Contents
8========
9
10- In This Release
11- Identifying Your Adapter
12- Command Line Parameters
13- Speed and Duplex Configuration
14- Additional Configurations
15- Known Issues
16- Support
17
18
19In This Release
20===============
21
22This file describes the Linux* Base Driver for the Intel(R) PRO/1000 Family
23of Adapters, version 5.x.x.
24
25For questions related to hardware requirements, refer to the documentation
26supplied with your Intel PRO/1000 adapter. All hardware requirements listed
27apply to use with Linux.
28
29Native VLANs are now available with supported kernels.
30
31Identifying Your Adapter
32========================
33
34For more information on how to identify your adapter, go to the Adapter &
35Driver ID Guide at:
36
37 http://support.intel.com/support/network/adapter/pro100/21397.htm
38
39For the latest Intel network drivers for Linux, refer to the following
40website. In the search field, enter your adapter name or type, or use the
41networking link on the left to search for your adapter:
42
43 http://downloadfinder.intel.com/scripts-df/support_intel.asp
44
45Command Line Parameters
46=======================
47
48If the driver is built as a module, the following optional parameters are
49used by entering them on the command line with the modprobe or insmod command
50using this syntax:
51
52 modprobe e1000 [<option>=<VAL1>,<VAL2>,...]
53
54 insmod e1000 [<option>=<VAL1>,<VAL2>,...]
55
56For example, with two PRO/1000 PCI adapters, entering:
57
58 insmod e1000 TxDescriptors=80,128
59
60loads the e1000 driver with 80 TX descriptors for the first adapter and 128 TX
61descriptors for the second adapter.
62
63The default value for each parameter is generally the recommended setting,
64unless otherwise noted. Also, if the driver is statically built into the
65kernel, the driver is loaded with the default values for all the parameters.
66Ethtool can be used to change some of the parameters at runtime.
67
68 NOTES: For more information about the AutoNeg, Duplex, and Speed
69 parameters, see the "Speed and Duplex Configuration" section in
70 this document.
71
72 For more information about the InterruptThrottleRate, RxIntDelay,
73 TxIntDelay, RxAbsIntDelay, and TxAbsIntDelay parameters, see the
74 application note at:
75 http://www.intel.com/design/network/applnots/ap450.htm
76
77 A descriptor describes a data buffer and attributes related to the
78 data buffer. This information is accessed by the hardware.
79
80AutoNeg (adapters using copper connections only)
81Valid Range: 0x01-0x0F, 0x20-0x2F
82Default Value: 0x2F
83 This parameter is a bit mask that specifies which speed and duplex
84 settings the board advertises. When this parameter is used, the Speed and
85 Duplex parameters must not be specified.
86 NOTE: Refer to the Speed and Duplex section of this readme for more
87 information on the AutoNeg parameter.
88
89Duplex (adapters using copper connections only)
90Valid Range: 0-2 (0=auto-negotiate, 1=half, 2=full)
91Default Value: 0
92 Defines the direction in which data is allowed to flow. Can be either one
93 or two-directional. If both Duplex and the link partner are set to auto-
94 negotiate, the board auto-detects the correct duplex. If the link partner
95 is forced (either full or half), Duplex defaults to half-duplex.
96
97FlowControl
98Valid Range: 0-3 (0=none, 1=Rx only, 2=Tx only, 3=Rx&Tx)
99Default: Read flow control settings from the EEPROM
100 This parameter controls the automatic generation(Tx) and response(Rx) to
101 Ethernet PAUSE frames.
102
103InterruptThrottleRate
104Valid Range: 100-100000 (0=off, 1=dynamic)
105Default Value: 8000
106 This value represents the maximum number of interrupts per second the
107 controller generates. InterruptThrottleRate is another setting used in
108 interrupt moderation. Dynamic mode uses a heuristic algorithm to adjust
109 InterruptThrottleRate based on the current traffic load.
110Un-supported Adapters: InterruptThrottleRate is NOT supported by 82542, 82543
111 or 82544-based adapters.
112
113 NOTE: InterruptThrottleRate takes precedence over the TxAbsIntDelay and
114 RxAbsIntDelay parameters. In other words, minimizing the receive
115 and/or transmit absolute delays does not force the controller to
116 generate more interrupts than what the Interrupt Throttle Rate
117 allows.
118 CAUTION: If you are using the Intel PRO/1000 CT Network Connection
119 (controller 82547), setting InterruptThrottleRate to a value
120 greater than 75,000, may hang (stop transmitting) adapters under
121 certain network conditions. If this occurs a NETDEV WATCHDOG
122 message is logged in the system event log. In addition, the
123 controller is automatically reset, restoring the network
124 connection. To eliminate the potential for the hang, ensure
125 that InterruptThrottleRate is set no greater than 75,000 and is
126 not set to 0.
127 NOTE: When e1000 is loaded with default settings and multiple adapters are
128 in use simultaneously, the CPU utilization may increase non-linearly.
129 In order to limit the CPU utilization without impacting the overall
130 throughput, we recommend that you load the driver as follows:
131
132 insmod e1000.o InterruptThrottleRate=3000,3000,3000
133
134 This sets the InterruptThrottleRate to 3000 interrupts/sec for the
135 first, second, and third instances of the driver. The range of 2000 to
136 3000 interrupts per second works on a majority of systems and is a
137 good starting point, but the optimal value will be platform-specific.
138 If CPU utilization is not a concern, use RX_POLLING (NAPI) and default
139 driver settings.
140
141RxDescriptors
142Valid Range: 80-256 for 82542 and 82543-based adapters
143 80-4096 for all other supported adapters
144Default Value: 256
145 This value is the number of receive descriptors allocated by the driver.
146 Increasing this value allows the driver to buffer more incoming packets.
147 Each descriptor is 16 bytes. A receive buffer is allocated for each
148 descriptor and can either be 2048 or 4096 bytes long, depending on the MTU
149
150 setting. An incoming packet can span one or more receive descriptors.
151 The maximum MTU size is 16110.
152
153 NOTE: MTU designates the frame size. It only needs to be set for Jumbo
154 Frames.
155 NOTE: Depending on the available system resources, the request for a
156 higher number of receive descriptors may be denied. In this case,
157 use a lower number.
158
159RxIntDelay
160Valid Range: 0-65535 (0=off)
161Default Value: 0
162 This value delays the generation of receive interrupts in units of 1.024
163 microseconds. Receive interrupt reduction can improve CPU efficiency if
164 properly tuned for specific network traffic. Increasing this value adds
165 extra latency to frame reception and can end up decreasing the throughput
166 of TCP traffic. If the system is reporting dropped receives, this value
167 may be set too high, causing the driver to run out of available receive
168 descriptors.
169
170 CAUTION: When setting RxIntDelay to a value other than 0, adapters may
171 hang (stop transmitting) under certain network conditions. If
172 this occurs a NETDEV WATCHDOG message is logged in the system
173 event log. In addition, the controller is automatically reset,
174 restoring the network connection. To eliminate the potential for
175 the hang ensure that RxIntDelay is set to 0.
176
177RxAbsIntDelay (82540, 82545 and later adapters only)
178Valid Range: 0-65535 (0=off)
179Default Value: 128
180 This value, in units of 1.024 microseconds, limits the delay in which a
181 receive interrupt is generated. Useful only if RxIntDelay is non-zero,
182 this value ensures that an interrupt is generated after the initial
183 packet is received within the set amount of time. Proper tuning,
184 along with RxIntDelay, may improve traffic throughput in specific network
185 conditions.
186
187Speed (adapters using copper connections only)
188Valid Settings: 0, 10, 100, 1000
189Default Value: 0 (auto-negotiate at all supported speeds)
190 Speed forces the line speed to the specified value in megabits per second
191 (Mbps). If this parameter is not specified or is set to 0 and the link
192 partner is set to auto-negotiate, the board will auto-detect the correct
193 speed. Duplex should also be set when Speed is set to either 10 or 100.
194
195TxDescriptors
196Valid Range: 80-256 for 82542 and 82543-based adapters
197 80-4096 for all other supported adapters
198Default Value: 256
199 This value is the number of transmit descriptors allocated by the driver.
200 Increasing this value allows the driver to queue more transmits. Each
201 descriptor is 16 bytes.
202
203 NOTE: Depending on the available system resources, the request for a
204 higher number of transmit descriptors may be denied. In this case,
205 use a lower number.
206
207TxIntDelay
208Valid Range: 0-65535 (0=off)
209Default Value: 64
210 This value delays the generation of transmit interrupts in units of
211 1.024 microseconds. Transmit interrupt reduction can improve CPU
212 efficiency if properly tuned for specific network traffic. If the
213 system is reporting dropped transmits, this value may be set too high
214 causing the driver to run out of available transmit descriptors.
215
216TxAbsIntDelay (82540, 82545 and later adapters only)
217Valid Range: 0-65535 (0=off)
218Default Value: 64
219 This value, in units of 1.024 microseconds, limits the delay in which a
220 transmit interrupt is generated. Useful only if TxIntDelay is non-zero,
221 this value ensures that an interrupt is generated after the initial
222 packet is sent on the wire within the set amount of time. Proper tuning,
223 along with TxIntDelay, may improve traffic throughput in specific
224 network conditions.
225
226XsumRX (not available on the 82542-based adapter)
227Valid Range: 0-1
228Default Value: 1
229 A value of '1' indicates that the driver should enable IP checksum
230 offload for received packets (both UDP and TCP) to the adapter hardware.
231
232Speed and Duplex Configuration
233==============================
234
235Three keywords are used to control the speed and duplex configuration. These
236keywords are Speed, Duplex, and AutoNeg.
237
238If the board uses a fiber interface, these keywords are ignored, and the
239fiber interface board only links at 1000 Mbps full-duplex.
240
241For copper-based boards, the keywords interact as follows:
242
243 The default operation is auto-negotiate. The board advertises all supported
244 speed and duplex combinations, and it links at the highest common speed and
245 duplex mode IF the link partner is set to auto-negotiate.
246
247 If Speed = 1000, limited auto-negotiation is enabled and only 1000 Mbps is
248 advertised (The 1000BaseT spec requires auto-negotiation.)
249
250 If Speed = 10 or 100, then both Speed and Duplex should be set. Auto-
251 negotiation is disabled, and the AutoNeg parameter is ignored. Partner SHOULD
252 also be forced.
253
254The AutoNeg parameter is used when more control is required over the auto-
255negotiation process. When this parameter is used, Speed and Duplex parameters
256must not be specified. The following table describes supported values for the
257AutoNeg parameter:
258
259Speed (Mbps) 1000 100 100 10 10
260Duplex Full Full Half Full Half
261Value (in base 16) 0x20 0x08 0x04 0x02 0x01
262
263Example: insmod e1000 AutoNeg=0x03, loads e1000 and specifies (10 full duplex,
26410 half duplex) for negotiation with the peer.
265
266Note that setting AutoNeg does not guarantee that the board will link at the
267highest specified speed or duplex mode, but the board will link at the
268highest possible speed/duplex of the link partner IF the link partner is also
269set to auto-negotiate. If the link partner is forced speed/duplex, the
270adapter MUST be forced to the same speed/duplex.
271
272
273Additional Configurations
274=========================
275
276 Configuring the Driver on Different Distributions
277 -------------------------------------------------
278
279 Configuring a network driver to load properly when the system is started is
280 distribution dependent. Typically, the configuration process involves adding
281 an alias line to /etc/modules.conf as well as editing other system startup
282 scripts and/or configuration files. Many popular Linux distributions ship
283 with tools to make these changes for you. To learn the proper way to
284 configure a network device for your system, refer to your distribution
285 documentation. If during this process you are asked for the driver or module
286 name, the name for the Linux Base Driver for the Intel PRO/1000 Family of
287 Adapters is e1000.
288
289 As an example, if you install the e1000 driver for two PRO/1000 adapters
290 (eth0 and eth1) and set the speed and duplex to 10full and 100half, add the
291 following to modules.conf:
292
293 alias eth0 e1000
294 alias eth1 e1000
295 options e1000 Speed=10,100 Duplex=2,1
296
297 Viewing Link Messages
298 ---------------------
299
300 Link messages will not be displayed to the console if the distribution is
301 restricting system messages. In order to see network driver link messages on
302 your console, set dmesg to eight by entering the following:
303
304 dmesg -n 8
305
306 NOTE: This setting is not saved across reboots.
307
308 Jumbo Frames
309 ------------
310
311 The driver supports Jumbo Frames for all adapters except 82542-based
312 adapters. Jumbo Frames support is enabled by changing the MTU to a value
313 larger than the default of 1500. Use the ifconfig command to increase the
314 MTU size. For example:
315
316 ifconfig ethx mtu 9000 up
317
318 The maximum MTU setting for Jumbo Frames is 16110. This value coincides
319 with the maximum Jumbo Frames size of 16128.
320
321 NOTE: Jumbo Frames are supported at 1000 Mbps only. Using Jumbo Frames at
322 10 or 100 Mbps may result in poor performance or loss of link.
323
324
325 NOTE: MTU designates the frame size. To enable Jumbo Frames, increase the
326 MTU size on the interface beyond 1500.
327
328 Ethtool
329 -------
330
331 The driver utilizes the ethtool interface for driver configuration and
332 diagnostics, as well as displaying statistical information. Ethtool
333 version 1.6 or later is required for this functionality.
334
335 The latest release of ethtool can be found from
336 http://sf.net/projects/gkernel.
337
338 NOTE: Ethtool 1.6 only supports a limited set of ethtool options. Support
339 for a more complete ethtool feature set can be enabled by upgrading
340 ethtool to ethtool-1.8.1.
341
342 Enabling Wake on LAN* (WoL)
343 ---------------------------
344
345 WoL is configured through the Ethtool* utility. Ethtool is included with
346 all versions of Red Hat after Red Hat 7.2. For other Linux distributions,
347 download and install Ethtool from the following website:
348 http://sourceforge.net/projects/gkernel.
349
350 For instructions on enabling WoL with Ethtool, refer to the website listed
351 above.
352
353 WoL will be enabled on the system during the next shut down or reboot.
354 For this driver version, in order to enable WoL, the e1000 driver must be
355 loaded when shutting down or rebooting the system.
356
357 NAPI
358 ----
359
360 NAPI (Rx polling mode) is supported in the e1000 driver. NAPI is enabled
361 or disabled based on the configuration of the kernel.
362
363 See www.cyberus.ca/~hadi/usenix-paper.tgz for more information on NAPI.
364
365
366Known Issues
367============
368
369 Jumbo Frames System Requirement
370 -------------------------------
371
372 Memory allocation failures have been observed on Linux systems with 64 MB
373 of RAM or less that are running Jumbo Frames. If you are using Jumbo Frames,
374 your system may require more than the advertised minimum requirement of 64 MB
375 of system memory.
376
377
378Support
379=======
380
381For general information, go to the Intel support website at:
382
383 http://support.intel.com
384
385If an issue is identified with the released source code on the supported
386kernel with a supported adapter, email the specific information related to
387the issue to linux.nics@intel.com.
388
389
390License
391=======
392
393This software program is released under the terms of a license agreement
394between you ('Licensee') and Intel. Do not use or load this software or any
395associated materials (collectively, the 'Software') until you have carefully
396read the full terms and conditions of the LICENSE located in this software
397package. By loading or using the Software, you agree to the terms of this
398Agreement. If you do not agree with the terms of this Agreement, do not
399install or use the Software.
400
401* Other names and brands may be claimed as the property of others.