sys/dev/netif/em/README

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