Linux Driver for the Intel(R) PRO/1000 Family of Adapters
=========================================================

November 19, 2001


Contents
========

- In This Release
- Supported Adapters
- Building and Installation
- Command Line Parameters
- Speed and Duplex Configuration
- Additional Configurations
- Known Issue
- Troubleshooting
- Support
- License


In This Release
===============

This file describes the Linux driver, version 3.5.x, for the Intel 
PRO/1000 family of server adapters. This driver is known to 
build properly on 2.2.x kernels through 2.2.19 and on the 2.4.x kernel 
through 2.4.9. This driver includes support for Itanium(TM)-based
systems.

The Intel PRO/1000 driver is only supported as a loadable module at 
this time. Intel is not supplying patches against the kernel source 
to allow for static linking of the driver. For questions related to 
hardware requirements, refer to the documentation supplied with your 
Intel PRO/1000 adapter. All hardware requirements listed apply to 
use with Linux.

This release version includes the following:

   - hooks for Intel ANS, the Intel Advanced Networking Services driver.
     Some base driver versions within specific distributions, including
     Red Hat*, do not include these hooks.

   - support for the ethtool interface.  A third-party application can
     use the ethtool interface to get and set driver settings such as
     speed and duplex.

   - the zero copy feature to provide faster information throughput.
     By default, zero copy is on if using a kernel that supports it.
     Zero copy is not supported on the original PRO/1000 Gigabit Server
     Adapter.


Supported Adapters
==================

The following Intel network adapters are compatible with the drivers 
in this release:

Controller  Adapter Name                     Board IDs
----------  ------------                     ---------

82542       PRO/1000 Gigabit Server Adapter  700262-xxx, 717037-xxx

82543       PRO/1000 F Server Adapter        738640-xxx, A38888-xxx,
                                             A06512-xxx

82543       PRO/1000 T Server Adapter        A19845-xxx, A33948-xxx

82544       PRO/1000 XT Server Adapter       A51580-xxx

82544       PRO/1000 XF Server Adapter       A50484-xxx

82544       PRO/1000 T Desktop Adapter       A62947-xxx


To verify your Intel adapter is supported, find the board ID number
on the adapter. Look for a label that has a barcode and a number
in the format of 123456-001 (six digits hyphen three digits). Match
this to the list of numbers above.

For more information on how to identify your adapter, go to the
Adapter & Driver ID Guide at:

    http://support.intel.com/support/network/adapter/pro100/21397.htm

For the latest Intel network drivers for Linux, see:

    http://appsr.intel.com/scripts-df/support_intel.asp


Building and Installation
=========================

NOTE: For the build to work properly, the currently running kernel 
      MUST match the version and configuration of the installed
      kernel sources. Also, if you have just recompiled the kernel,
      reboot the system now.

1. Move the base driver tar file to the directory of your choice.
   For example, use /home/username/e1000 or /usr/local/src/e1000

2. Untar/unzip archive:

     tar zxf e1000-x.x.x.tar.gz

3. Change to the driver src directory:

     cd e1000-x.x.x/src/

4. Compile the driver module:

     make install

   The binary will be installed as:
     For Linux 2.2.x systems:
        /lib/modules/[KERNEL_VERSION]/net/e1000.o
     For Linux 2.4.x systems:
        /lib/modules/[KERNEL_VERSION]/kernel/drivers/net/e1000.o

5. Install the module:

     insmod e1000 [parameter=value]

6. Assign an IP address to the interface by entering the following, where
   # is interface number:

     ifconfig eth# <IP_address>

7. Verify that the interface works:

     ping  <your_IP_address>

To build a binary RPM* package of this driver, run 
'rpm -tb <filename.tar.gz>'. Replace <filename.tar.gz> with the 
specific file name of the driver.


Command Line Parameters
=======================

The following parameters are used by entering them on the command line
with the modprobe or insmod command.
For example, with two PRO/1000 PCI adapters, entering:

    insmod e1000 TxDescriptors=80,128

loads the e1000 driver with 80 TX resources for the first adapter and
128 TX resources for the second adapter.

AutoNeg (Intel PRO/1000 T and PRO/1000 XT server adapters Only)
Valid Range: 0-0x0F, 0x20-0x2F
Default Value: 0x2F
    This parameter is a bit mask that specifies which speed and duplex
    settings the board advertises. When this parameter is used, the
    Speed and Duplex parameters must not be specified.  

    See the section "Speed and Duplex Configuration" in this document.

Duplex (Intel PRO/1000 T and PRO/1000 XT server adapters only)
Valid Range: 0-2 (0=auto-negotiate, 1=half, 2=full)
Default Value: 0
    Defines the direction in which data is allowed to flow -- either
    one or two-directional. If this parameter is not specified or is
    set to 0 and the link partner is set to auto-negotiate, the board
    auto-detects the correct duplex. If the link partner is forced
    (either full or half), Duplex defaults to half-duplex.

    See the section "Speed and Duplex Configuration" in this document.

FlowControl
Valid Range: 0-3 (0=none, 1=Rx only, 2=Tx only, 3=Rx&Tx)
Default: 3
    This parameter controls the automatic generation(Tx) 
    and response(Rx) to Ethernet PAUSE frames.

RxDescriptors
Valid Range: 80-256 for 82542 and 82543-based adapters
             80-4096 for 82544-based adapters
Default Value: 256
    This value is the number of receive descriptors allocated by the
    driver. Increasing this value allows the driver to buffer more
    incoming packets.  Each descriptor is 16 bytes.  A receive buffer is
    also allocated for each descriptor and can be either 2048, 4096, 8192,
    or 16384 bytes, depending on the MTU setting.

RxIntDelay
Valid Range: 0-65535 (0=off)
Default Value: 64
    This value delays the generation of receive interrupts in units of
    1.024 microseconds.  Receive interrupt reduction can improve CPU
    efficiency if properly tuned for specific network traffic.
    Increasing this value adds extra latency to frame reception
    and can end up decreasing the throughput of TCP traffic.  If the
    system is reporting dropped receives, this value may be set too high,
    causing the driver to run out of available receive descriptors.

Speed (Intel PRO/1000 T and PRO/1000 XT server adapters only)
Valid Range: 0, 10, 100, 1000
Default Value: 0 (auto-negotiate at all supported speeds)
    Speed forces the line speed to the specified value in megabits 
    per second (Mbps). If this parameter is not specified or is set 
    to 0 and the link partner is set to auto-negotiate, the board 
    will auto-detect the correct speed. The duplex must also be set 
    when the speed parameter is set to either 10 or 100.

    See the section "Speed and Duplex Configuration" in this document.

TxDescriptors
Valid Range: 80-256 for 82542 and 82543-based adapters
             80-4096 for 82544-based adapters
Default Value: 256
    This value is the number of transmit descriptors allocated by the
    driver. Increasing this value allows the driver to queue more
    transmits. Each descriptor is 16 bytes.

TxIntDelay
Valid Range: 0-65535 (0=off)
Default Value: 64
    This value delays the generation of transmit interrupts in units of
    1.024 microseconds.  Transmit interrupt reduction can improve CPU
    efficiency if properly tuned for specific network traffic.  If the
    system is reporting dropped transmits, this value may be set too high
    causing the driver to run out of available transmit descriptors.

XsumRX (not available on the PRO/1000 Gigabit Server Adapter)
Valid Range: 0-1
Default Value: 1
    A value of '1' indicates that the driver should enable IP checksum
    offload for received packets (both UDP and TCP) to the adapter
    hardware.


Speed and Duplex Configuration
==============================

Three keywords are used to control the speed and duplex configuration of
the PRO/1000 T and PRO/1000 XT server adapters. These keywords are Speed,
Duplex, and AutoNeg.

If the board uses a fiber interface, these keywords are ignored, and the 
fiber interface board only links at 1000 Mbps full-duplex.

For copper-based boards, the keywords interact as follows:

The default operation is auto-negotiate. The board advertises all supported
speed and duplex combinations, and it links at the highest common speed and
duplex mode IF the link partner is set to auto-negotiate.

If Speed = 1000, limited auto-negotiation is enabled and only 1000 Mbps is
advertised (The 1000BaseT spec requires auto-negotiation.)

If Speed = 10 or 100, then both Speed and Duplex must be set. Auto-
negotiation is disabled, and the AutoNeg parameter is ignored. Partner 
MUST also be forced.

The AutoNeg parameter is used when more control is required over the 
auto-negotiation process.  When this parameter is used, Speed and Duplex
must not be specified.  This parameter is a bitmap that specifies which 
speed and duplex settings are advertised to the link partner.

Bit            7      6      5       4       3      2      1       0
Speed (Mbps)   N/A    N/A    1000    N/A     100    100    10      10
Duplex                       Full            Full   Half   Full    Half

Note that setting AutoNeg does not guarantee that the board will link at
the highest specified speed or duplex mode, but the board will link at 
the highest possible speed/duplex of the link partner IF the link partner 
is also set to auto-negotiate. If the link partner is forced speed/duplex,
the adapter MUST be forced to the same speed/duplex.


Additional Configurations
=========================

Configuring a network driver to load properly when the system is started
is distribution dependent.  Typically, the configuration process involves
adding an alias line to /etc/modules.conf as well as editing other system
startup scripts and/or configuration files.  Many popular Linux
distributions ship with tools to make these changes for you.  To learn
the proper way to configure a network device for your system, refer to
your distribution documentation. If, during this process, you are asked
for the driver or module name, the driver name for the PRO/1000 is 'e1000'.

Some distributions of Linux display squelched system messages on the console
by default. For Intel's drivers this has the effect of stopping link
messages from appearing on the console. In order to see network driver link
messages on your console, set dmesg to at least six by entering "dmesg -n 6"
on the command line.


Known Issue
===========

Intel is aware that previously released e1000 drivers may hang under very
specific types of heavy traffic loads. This version includes a workaround
that resets the adapter automatically if a hang condition is detected.
This workaround ensures network traffic flow is not affected when a hang
occurs. Additional workarounds or a fix will be added as they become
available.


Troubleshooting
===============

When trying to compile the driver by running make install, the following
error may occur: 

    "Linux kernel source not configured - missing version.h"

To solve this issue, create the version.h file by going to the Linux
source tree and doing a make include/linux/version.h.


Support
=======

For general information and support, go to the Intel support Website at:

    http://support.intel.com

If an issue is identified with the released source code on the supported
kernel with a supported adapter, email the specific information related
to the issue to linux.nics@intel.com.


License
=======

Recipient has requested a license and Intel Corporation ("Intel") is willing
to grant a license for the software entitled Linux Base Driver for the 
Intel(R) PRO/1000 Family of Adapters (e1000) (the "Software") being provided
by Intel Corporation.

The following definitions apply to this License: 

"Licensed Patents" means patent claims licensable by Intel Corporation which 
are necessarily infringed by the use or sale of the Software alone or when 
combined with the operating system referred to below.
"Recipient" means the party to whom Intel delivers this Software.
"Licensee" means Recipient and those third parties that receive a license to 
any operating system available under the GNU Public License version 2.0 or 
later.

Copyright (c) 1996-2001 Intel Corporation 
All rights reserved. 

The license is provided to Recipient and Recipient's Licensees under the 
following terms.  

Redistribution and use in source and binary forms of the Software, with or 
without modification, are permitted provided that the following conditions 
are met: 

Redistributions of source code of the Software may retain the above copyright 
notice, this list of conditions and the following disclaimer. 
Redistributions in binary form of the Software may reproduce the above copyright
notice, this list of conditions and the following disclaimer in the 
documentation and/or other materials provided with the distribution. 
Neither the name of Intel Corporation nor the names of its contributors shall 
be used to endorse or promote products derived from this Software without 
specific prior written permission.

Intel hereby grants Recipient and Licensees a non-exclusive, worldwide, 
royalty-free patent license under Licensed Patents to make, use, sell, offer to 
sell, import and otherwise transfer the Software, if any, in source code and 
object code form. This license shall include changes to the Software that are 
error corrections or other minor changes to the Software that do not add 
functionality  or features when the Software is incorporated in any version of 
a operating system that has been distributed under the GNU General Public 
License 2.0 or later.  This patent license shall apply to the combination of 
the Software and any operating system licensed under the GNU Public License 
version 2.0 or later if, at the time Intel provides the Software to Recipient, 
such addition of the Software to the then publicly available versions of such 
operating system available under the GNU Public License version 2.0 or later 
(whether in gold, beta or alpha form) causes such combination to be covered by 
the Licensed Patents. The patent license shall not apply to any other 
combinations which include the Software. No hardware per se is licensed 
hereunder. 
 
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
DISCLAIMED. IN NO EVENT SHALL INTEL OR ITS CONTRIBUTORS BE LIABLE FOR ANY 
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
