sys/dev/netif/e1000/README

   1 $FreeBSD$
   2 FreeBSD* Driver for Intel Network Connection
   3 =============================================
   4
   5 May 30, 2007
   6
   7
   8 Contents
   9 ========
  10
  11 - Overview
  12 - Identifying Your Adapter
  13 - Building and Installation
  14 - Speed and Duplex Configuration
  15 - Additional Configurations
  16 - Known Limitations
  17 - Support
  18 - License
  19
  20
  21 Overview
  22 ========
  23
  24 This file describes the FreeBSD* driver for Intel Network Connection.
  25 This driver has been developed for use with FreeBSD, Release 7.x.
  26
  27 For questions related to hardware requirements, refer to the documentation
  28 supplied with your Gigabit adapter. All hardware requirements listed
  29 apply to use with FreeBSD.
  30
  31
  32 Identifying Your Adapter
  33 ========================
  34
  35 For information on how to identify your adapter, go to the Adapter &
  36 Driver ID Guide at:
  37
  38 http://support.intel.com/support/network/sb/cs-012904.htm
  39
  40
  41 For the latest Intel network drivers for FreeBSD, see:
  42
  43 http://downloadfinder.intel.com/scripts-df-external/support_intel.aspx
  44
  45
  46 NOTE: Mobile adapters are not fully supported.
  47 NOTE: The Intel(R) 82562v 10/100 Network Connection only provides 10/100
  48 support.
  49
  50 Building and Installation
  51 =========================
  52
  53 NOTE: The driver can be installed as a dynamic loadable kernel module or
  54       compiled into the kernel. You must have kernel sources installed in
  55       order to compile the driver module.
  56
  57 In the instructions below, x.x.x is the driver version as indicated in the
  58 name of the driver tar file.
  59
  60 1. Move the base driver tar file to the directory of your choice. For
  61    example, use /home/username/em or /usr/local/src/em.
  62
  63 2. Untar/unzip the archive:
  64
  65         tar xzvf em-x.x.x.tar.gz
  66
  67    This will create an em-x.x.x directory.
  68
  69 3. To create a loadable module, perform the following steps.
  70    NOTE: To compile the driver into the kernel, go directly to step 4.
  71
  72         a. To compile the module
  73
  74                   cd em-x.x.x
  75                   make
  76
  77         b. To install the compiled module to the system directory:
  78
  79                   make install
  80
  81         c. If you want the driver to load automatically when the system is booted:
  82
  83               1. Edit /boot/loader.conf, and add the following line:
  84
  85                   if_em_load="YES"
  86
  87 4. To compile the driver into the kernel, enter:
  88
  89         cd em-x.x.x/src
  90         cp *.[ch] /usr/src/sys/dev/em
  91
  92         Edit the kernel configuration file (i.e., GENERIC or MYKERNEL) in
  93         /usr/src/sys/i386/conf, and ensure the following line is present:
  94
  95         device em
  96
  97         Compile and install the kernel. The system must be rebooted for the
  98         kernel updates to take effect. For additional information on compiling
  99         the kernel, consult the FreeBSD operating system documentation.
 100
 101 5. To assign an IP address to the interface, enter the following:
 102
 103         ifconfig em<interface_num> <IP_address>
 104
 105 6. Verify that the interface works. Enter the following, where <IP_address>
 106    is the IP address for another machine on the same subnet as the interface
 107    that is being tested:
 108
 109         ping <IP_address>
 110
 111 7. To configure the IP address to remain after reboot, edit /etc/rc.conf,
 112    and create the appropriate ifconfig_em<interface_num>entry:
 113
 114         ifconfig_em<interface_num>="<ifconfig_settings>"
 115
 116    Example usage:
 117
 118         ifconfig_em0="inet 192.168.10.1 netmask 255.255.255.0"
 119
 120    NOTE: For assistance, see the ifconfig man page.
 121
 122
 123 Speed and Duplex Configuration
 124 ==============================
 125
 126 By default, the adapter auto-negotiates the speed and duplex of the
 127 connection. If there is a specific need, the ifconfig utility can be used to
 128 configure the speed and duplex settings on the adapter. Example usage:
 129
 130         ifconfig em<interface_num> <IP_address> media 100baseTX mediaopt
 131             full-duplex
 132
 133    NOTE: Only use mediaopt to set the driver to full-duplex. If mediaopt is
 134          not specified and you are not running at gigabit speed, the driver
 135          defaults to half-duplex.
 136
 137 If the interface is currently forced to 100 full duplex, in order to change
 138 to half duplex you must use this command:
 139
 140         ifconfig em<interface_num> <IP_address> media 100baseTX -mediaopt
 141             full-duplex
 142
 143
 144 This driver supports the following media type options:
 145
 146    autoselect      -  Enables auto-negotiation for speed and duplex.
 147
 148    10baseT/UTP     -  Sets speed to 10 Mbps. Use the ifconfig mediaopt
 149                       option to select full-duplex mode.
 150
 151    100baseTX       -  Sets speed to 100 Mbps. Use the ifconfig mediaopt
 152                       option to select full-duplex mode.
 153
 154    1000baseTX      -  Sets speed to 1000 Mbps. In this case, the driver
 155                       supports only full-duplex mode.
 156
 157    1000baseSX      -  Sets speed to 1000 Mbps. In this case, the driver
 158                       supports only full-duplex mode.
 159
 160 For more information on the ifconfig utility, see the ifconfig man page.
 161
 162
 163 Additional Configurations
 164 =========================
 165
 166 The driver supports Transmit/Receive Checksum Offload and Jumbo Frames on
 167 all but the 82542-based adapters.  For specific adapters, refer to the
 168 Identifying Your Adapter section.
 169
 170   Jumbo Frames
 171   ------------
 172   To enable Jumbo Frames, use the ifconfig utility to set the Maximum
 173   Transport Unit (MTU) frame size above its default of 1500 bytes.
 174
 175   The Jumbo Frames MTU range for Intel Adapters is 1500 to 16110. To modify
 176   the setting, enter the following:
 177
 178         ifconfig em<interface_num> <hostname or IP address> mtu 9000
 179
 180   To confirm the MTU used between two specific devices, use:
 181
 182         route get <destination_IP_address>
 183
 184   Notes:
 185
 186   - Only enable Jumbo Frames if your network infrastructure supports them.
 187
 188   - To enable Jumbo Frames, increase the MTU size on the interface beyond
 189     1500.
 190
 191   - The Jumbo Frames setting on the switch must be set to at least 22 bytes
 192     larger than that of the MTU.
 193
 194   - The maximum MTU setting for Jumbo Frames is 16110.  This value coincides
 195     with the maximum Jumbo Frames size of 16128.
 196
 197   - Some Intel gigabit adapters that support Jumbo Frames have a frame size
 198     limit of 9238 bytes, with a corresponding MTU size limit of 9216 bytes.
 199     The adapters with this limitation are based on the Intel(R) 82571EB,
 200     82572EI, 82573L, 82566, 82562, and 80003ES2LAN controller.  These
 201     correspond to the following product names:
 202      Intel(R) PRO/1000 PT Server Adapter
 203      Intel(R) PRO/1000 PT Desktop Adapter
 204      Intel(R) PRO/1000 PT Network Connection
 205      Intel(R) PRO/1000 PT Dual Port Server Adapter
 206      Intel(R) PRO/1000 PT Dual Port Network Connection
 207      Intel(R) PRO/1000 PT Quad Port Server Adapter
 208      Intel(R) PRO/1000 PF Quad Port Server Adapter
 209      Intel(R) PRO/1000 PF Server Adapter
 210      Intel(R) PRO/1000 PF Network Connection
 211      Intel(R) PRO/1000 PF Dual Port Server Adapter
 212      Intel(R) PRO/1000 PB Server Connection
 213      Intel(R) PRO/1000 PL Network Connection
 214      Intel(R) PRO/1000 EB Network Connection with I/O Acceleration
 215      Intel(R) PRO/1000 EB Backplane Connection with I/O Acceleration
 216      Intel(R) 82566DM-2 Gigabit Network Connection
 217
 218   - Adapters based on the Intel(R) 82542 and 82573V/E controller do not
 219     support Jumbo Frames. These correspond to the following product names:
 220      Intel(R) PRO/1000 Gigabit Server Adapter
 221      Intel(R) PRO/1000 PM Network Connection
 222
 223   - Using Jumbo Frames at 10 or 100 Mbps may result in poor performance or
 224     loss of link.
 225
 226   - The following adapters do not support Jumbo Frames:
 227     Intel(R) 82562V 10/100 Network Connection
 228     Intel(R) 82566DM Gigabit Network Connection
 229     Intel(R) 82566DC Gigabit Network Connection
 230     Intel(R) 82566MM Gigabit Network Connection
 231     Intel(R) 82566MC Gigabit Network Connection
 232     Intel(R) 82562GT 10/100 Network Connection
 233     Intel(R) 82562G 10/100 Network Connection
 234     Intel(R) 82566DC-2 Gigabit Network Connection
 235     Intel(R) 82562V-2 10/100 Network Connection
 236     Intel(R) 82562G-2 10/100 Network Connection
 237     Intel(R) 82562GT-2 10/100 Network Connection
 238
 239   VLANs
 240   -----
 241   To create a new VLAN interface:
 242
 243         ifconfig <vlan_name> create
 244
 245   To associate the VLAN interface with a physical interface and
 246   assign a VLAN ID, IP address, and netmask:
 247
 248         ifconfig <vlan_name> <ip_address> netmask <subnet_mask> vlan
 249            <vlan_id> vlandev <physical_interface>
 250
 251   Example:
 252
 253         ifconfig vlan10 10.0.0.1 netmask 255.255.255.0 vlan 10 vlandev em0
 254
 255   In this example, all packets will be marked on egress with 802.1Q VLAN
 256   tags, specifying a VLAN ID of 10.
 257
 258   To remove a VLAN interface:
 259
 260   Intel Network Connection        ifconfig <vlan_name> destroy
 261
 262
 263   Polling
 264   -------
 265
 266   To enable polling in the driver, add the following options to the kernel
 267   configuration, and then recompile the kernel:
 268
 269         options DEVICE_POLLING
 270         options HZ=1000
 271
 272   At runtime use:
 273         ifconfig emX polling (to turn polling on)
 274   and:
 275         ifconfig emX -polling  (to turn it off)
 276
 277
 278   Checksum Offload
 279   ----------------
 280   Checksum offloading is not supported on 82542 Gigabit adapters.
 281
 282   Checksum offloading supports both TCP and UDP packets and is
 283   supported for both transmit and receive.
 284
 285   Checksum offloading can be enabled or disabled using ifconfig.
 286   Both transmit and receive offloading will be either enabled or
 287   disabled together. You cannot enable/disable one without the other.
 288
 289   To enable checksum offloading:
 290
 291          ifconfig <interface_num> rxcsum
 292
 293   To disable checksum offloading:
 294
 295          ifconfig <interface_num> -rxcsum
 296
 297   To confirm the current setting:
 298
 299          ifconfig <interface_num>
 300
 301   Look for the presence or absence of the following line:
 302
 303          options=3 <RXCSUM,TXCSUM>
 304
 305   See the ifconfig man page for further information.
 306
 307
 308   TSO
 309   ---
 310   The FreeBSD driver offers support for TSO (TCP Segmentation Offload).
 311
 312   You can enable/disable it in two ways/places:
 313
 314         -  sysctl net.inet.tcp.tso=0    (or 1 to enable it)
 315
 316   Doing this disables TSO in the stack and will affect all adapters.
 317
 318         -  ifconfig emX -tso
 319
 320   Doing this will disable TSO only for this adapter.
 321
 322   To enable:
 323
 324         -  ifconfig emX tso
 325
 326   NOTES: By default only PCI-Express adapters are ENABLED to do TSO. Others
 327   can be enabled by the user at their own risk
 328   TSO is not supported on 82547 and 82544-based adapters, as well as older adapters.
 329
 330
 331 Known Limitations
 332 =================
 333
 334   Detected Tx Unit Hang in Quad Port Adapters
 335   -------------------------------------------
 336
 337   In some cases ports 3 and 4 wont pass traffic. Ports 1 and 2 don't show
 338   any errors and will pass traffic.
 339
 340   This issue MAY be resolved by updating to the latest BIOS. You can
 341   check your system's BIOS by downloading the Linux Firmware Developer Kit
 342   that can be obtained at http://www.linuxfirmwarekit.org/
 343
 344
 345   There are known performance issues with this driver when running UDP traffic
 346   with Jumbo Frames.
 347   ----------------------------------------------------------------------------
 348
 349   82541/82547 can't link or is slow to link with some link partners
 350   -----------------------------------------------------------------
 351
 352   There is a known compatibility issue where time to link is slow or link is not
 353   established between 82541/82547 controllers and some switches.  Known switches
 354   include:
 355         Planex FXG-08TE
 356         I-O Data ETG-SH8
 357
 358   The driver can be compiled with the following changes:
 359
 360   Edit ./em.x.x.x/src/if_em.h to change the #define EM_MASTER_SLAVE
 361   For example, change from:
 362
 363       #define EM_MASTER_SLAVE   e1000_ms_hw_default
 364   to:
 365       #define EM_MASTER_SLAVE   2
 366
 367   Use one of the following options:
 368       1 = Master mode
 369       2 = Slave mode
 370       3 = Auto master/slave
 371   Setting 2 is recommended.
 372
 373   Recompile the module:
 374           a. To compile the module
 375                 cd em-x.x.x
 376                 make clean
 377                 make
 378
 379    b. To install the compiled module in system directory:
 380                 make install
 381
 382
 383 Support
 384 =======
 385
 386 For general information and support, go to the Intel support website at:
 387
 388         http://support.intel.com
 389
 390 If an issue is identified, support is through email only at:
 391 freebsdnic@mailbox.intel.com
 392
 393
 394 License
 395 =======
 396
 397 This software program is released under the terms of a license agreement
 398 between you ('Licensee') and Intel. Do not use or load this software or any
 399 associated materials (collectively, the 'Software') until you have carefully
 400 read the full terms and conditions of the LICENSE located in this software
 401 package. By loading or using the Software, you agree to the terms of this
 402 Agreement. If you do not agree with the terms of this Agreement, do not
 403 install or use the Software.
 404
 405 * Other names and brands may be claimed as the property of others.