Linux-2.6.12-rc2
[linux-3.10.git] / Documentation / networking / e1000.txt
1 Linux* Base Driver for the Intel(R) PRO/1000 Family of Adapters
2 ===============================================================
3
4 November 17, 2004
5
6
7 Contents
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
19 In This Release
20 ===============
21
22 This file describes the Linux* Base Driver for the Intel(R) PRO/1000 Family
23 of Adapters, version 5.x.x.  
24
25 For questions related to hardware requirements, refer to the documentation 
26 supplied with your Intel PRO/1000 adapter. All hardware requirements listed 
27 apply to use with Linux.
28
29 Native VLANs are now available with supported kernels.
30
31 Identifying Your Adapter
32 ========================
33
34 For more information on how to identify your adapter, go to the Adapter & 
35 Driver ID Guide at:
36
37     http://support.intel.com/support/network/adapter/pro100/21397.htm
38
39 For the latest Intel network drivers for Linux, refer to the following 
40 website. In the search field, enter your adapter name or type, or use the 
41 networking link on the left to search for your adapter:
42
43     http://downloadfinder.intel.com/scripts-df/support_intel.asp
44
45 Command Line Parameters
46 =======================
47
48 If the driver is built as a module, the  following optional parameters are 
49 used by entering them on the command line with the modprobe or insmod command
50 using this syntax:
51
52      modprobe e1000 [<option>=<VAL1>,<VAL2>,...]
53
54      insmod e1000 [<option>=<VAL1>,<VAL2>,...] 
55
56 For example, with two PRO/1000 PCI adapters, entering:
57
58      insmod e1000 TxDescriptors=80,128
59
60 loads the e1000 driver with 80 TX descriptors for the first adapter and 128 TX 
61 descriptors for the second adapter.
62
63 The default value for each parameter is generally the recommended setting,
64 unless otherwise noted. Also, if the driver is statically built into the
65 kernel, the driver is loaded with the default values for all the parameters.
66 Ethtool 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
80 AutoNeg (adapters using copper connections only)
81 Valid Range: 0x01-0x0F, 0x20-0x2F
82 Default 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
89 Duplex (adapters using copper connections only)
90 Valid Range: 0-2 (0=auto-negotiate, 1=half, 2=full)
91 Default 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
97 FlowControl
98 Valid Range: 0-3 (0=none, 1=Rx only, 2=Tx only, 3=Rx&Tx)
99 Default: Read flow control settings from the EEPROM
100     This parameter controls the automatic generation(Tx) and response(Rx) to 
101     Ethernet PAUSE frames.
102
103 InterruptThrottleRate
104 Valid Range: 100-100000 (0=off, 1=dynamic)
105 Default 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.
110 Un-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
141 RxDescriptors
142 Valid Range: 80-256 for 82542 and 82543-based adapters
143              80-4096 for all other supported adapters
144 Default 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
159 RxIntDelay
160 Valid Range: 0-65535 (0=off)
161 Default 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
177 RxAbsIntDelay (82540, 82545 and later adapters only)
178 Valid Range: 0-65535 (0=off)
179 Default 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
187 Speed (adapters using copper connections only)
188 Valid Settings: 0, 10, 100, 1000
189 Default 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
195 TxDescriptors
196 Valid Range: 80-256 for 82542 and 82543-based adapters
197              80-4096 for all other supported adapters
198 Default 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
207 TxIntDelay
208 Valid Range: 0-65535 (0=off)
209 Default 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
216 TxAbsIntDelay (82540, 82545 and later adapters only)
217 Valid Range: 0-65535 (0=off)
218 Default 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
226 XsumRX (not available on the 82542-based adapter)
227 Valid Range: 0-1
228 Default 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
232 Speed and Duplex Configuration
233 ==============================
234
235 Three keywords are used to control the speed and duplex configuration. These 
236 keywords are Speed, Duplex, and AutoNeg.
237
238 If the board uses a fiber interface, these keywords are ignored, and the 
239 fiber interface board only links at 1000 Mbps full-duplex.
240
241 For 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
254 The AutoNeg parameter is used when more control is required over the auto-
255 negotiation process. When this parameter is used, Speed and Duplex parameters 
256 must not be specified. The following table describes supported values for the 
257 AutoNeg parameter:
258
259 Speed (Mbps)             1000      100    100    10     10
260 Duplex                   Full      Full   Half   Full   Half
261 Value (in base 16)       0x20      0x08   0x04   0x02   0x01
262
263 Example: insmod e1000 AutoNeg=0x03, loads e1000 and specifies (10 full duplex, 
264 10 half duplex) for negotiation with the peer.
265
266 Note that setting AutoNeg does not guarantee that the board will link at the 
267 highest specified speed or duplex mode, but the board will link at the 
268 highest possible speed/duplex of the link partner IF the link partner is also
269 set to auto-negotiate. If the link partner is forced speed/duplex, the 
270 adapter MUST be forced to the same speed/duplex.
271
272
273 Additional 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
366 Known 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
378 Support
379 =======
380
381 For general information, go to the Intel support website at:
382
383     http://support.intel.com
384
385 If an issue is identified with the released source code on the supported
386 kernel with a supported adapter, email the specific information related to 
387 the issue to linux.nics@intel.com.
388
389
390 License
391 =======
392
393 This software program is released under the terms of a license agreement 
394 between you ('Licensee') and Intel. Do not use or load this software or any 
395 associated materials (collectively, the 'Software') until you have carefully 
396 read the full terms and conditions of the LICENSE located in this software 
397 package. By loading or using the Software, you agree to the terms of this 
398 Agreement. If you do not agree with the terms of this Agreement, do not 
399 install or use the Software.
400
401 * Other names and brands may be claimed as the property of others.