README revision 169240
197785Spdeuskar$FreeBSD: head/sys/dev/em/README 169240 2007-05-04 00:00:12Z jfv $ 2169240SjfvFreeBSD Driver for the Gigabit Family of Adapters 397785Spdeuskar============================================================ 497785Spdeuskar 5169240SjfvApril 18, 2007 697785Spdeuskar 797785Spdeuskar 897785SpdeuskarContents 997785Spdeuskar======== 1097785Spdeuskar 11112472Spdeuskar- Overview 12146663Stackerman- Identifying Your Adapter 1397785Spdeuskar- Building and Installation 1497785Spdeuskar- Speed and Duplex Configuration 1597785Spdeuskar- Additional Configurations 1697785Spdeuskar- Known Limitations 1797785Spdeuskar- Support 1897785Spdeuskar- License 1997785Spdeuskar 2097785Spdeuskar 21112472SpdeuskarOverview 22112472Spdeuskar======== 2397785Spdeuskar 24169240SjfvThis file describes the FreeBSD* driver for the Gigabit Family of 25160949SglebiusAdapters. This driver has been developed for use with FreeBSD, Release 6.x. 2697785Spdeuskar 27146663StackermanFor questions related to hardware requirements, refer to the documentation 28169240Sjfvsupplied with your Gigabit adapter. All hardware requirements listed 2997785Spdeuskarapply to use with FreeBSD. 3097785Spdeuskar 3197785Spdeuskar 32146663StackermanIdentifying Your Adapter 33146663Stackerman======================== 3497785Spdeuskar 35146663StackermanFor information on how to identify your adapter, go to the Adapter & 36146663StackermanDriver ID Guide at: 3797785Spdeuskar 38157566Sglebiushttp://support.intel.com/support/network/sb/cs-012904.htm 3997785Spdeuskar 4097785Spdeuskar 41146663StackermanFor the latest Intel network drivers for FreeBSD, see: 4297785Spdeuskar 43157566Sglebiushttp://downloadfinder.intel.com/scripts-df-external/support_intel.aspx 4497785Spdeuskar 4597785Spdeuskar 46146663StackermanNOTE: Mobile adapters are not fully supported. 47160949SglebiusNOTE: The Intel(R) 82562v 10/100 Network Connection only provides 10/100 48160949Sglebiussupport. 4997785Spdeuskar 5097785SpdeuskarBuilding and Installation 5197785Spdeuskar========================= 5297785Spdeuskar 53146663StackermanNOTE: The driver can be installed as a dynamic loadable kernel module or 54146663Stackerman compiled into the kernel. You must have kernel sources installed in 55112472Spdeuskar order to compile the driver module. 5697785Spdeuskar 57146663StackermanIn the instructions below, x.x.x is the driver version as indicated in the 58112472Spdeuskarname of the driver tar file. 5997785Spdeuskar 60146663Stackerman1. Move the base driver tar file to the directory of your choice. For 6197785Spdeuskar example, use /home/username/em or /usr/local/src/em. 6297785Spdeuskar 6397785Spdeuskar2. Untar/unzip the archive: 6497785Spdeuskar 65169240Sjfv tar xzvf em-x.x.x.tar.gz 6697785Spdeuskar 67112472Spdeuskar This will create an em-x.x.x directory. 6897785Spdeuskar 69146663Stackerman3. To create a loadable module, perform the following steps. 70112472Spdeuskar NOTE: To compile the driver into the kernel, go directly to step 4. 7197785Spdeuskar 72146663Stackerman a. To compile the module 7397785Spdeuskar 74146663Stackerman cd em-x.x.x 75146663Stackerman make 7697785Spdeuskar 77169240Sjfv b. To install the compiled module to the system directory: 7897785Spdeuskar 79146663Stackerman make install 8097785Spdeuskar 81146663Stackerman c. If you want the driver to load automatically when the system is booted: 8297785Spdeuskar 83146663Stackerman 1. Edit /boot/loader.conf, and add the following line: 84146663Stackerman 85146663Stackerman if_em_load="YES" 86146663Stackerman 87169240Sjfv4. To compile the driver into the kernel, enter: 8897785Spdeuskar 89112472Spdeuskar cd em-x.x.x/src 90169240Sjfv cp *.[ch] /usr/src/sys/dev/em 91115878Spdeuskar cp Makefile.kernel /usr/src/sys/modules/em/Makefile 9297785Spdeuskar 93169240Sjfv NOTE: At this point you MUST install a patch, kernbuild.patch, which is 94169240Sjfv located in the patches directory. This is applied as shown below where 95169240Sjfv "$PATH_TO_KERNBUILD_PATCH" is the location of the kernbuild.patch: 9697785Spdeuskar 97169240Sjfv cd /usr/src/sys; patch -p1 < $PATH_TO_KERNBUILD_PATCH 9897785Spdeuskar 99169240Sjfv Edit the kernel configuration file (i.e., GENERIC or MYKERNEL) in 100169240Sjfv /usr/src/sys/i386/conf, and ensure the following line is present: 10197785Spdeuskar 102112472Spdeuskar device em 10397785Spdeuskar 104169240Sjfv Compile and install the kernel. The system must be rebooted for the 105169240Sjfv kernel updates to take effect. For additional information on compiling 106169240Sjfv the kernel, consult the FreeBSD operating system documentation. 10797785Spdeuskar 108112472Spdeuskar5. To assign an IP address to the interface, enter the following: 10997785Spdeuskar 110112472Spdeuskar ifconfig em<interface_num> <IP_address> 11197785Spdeuskar 112112472Spdeuskar6. Verify that the interface works. Enter the following, where <IP_address> 113112472Spdeuskar is the IP address for another machine on the same subnet as the interface 114112472Spdeuskar that is being tested: 11597785Spdeuskar 116112472Spdeuskar ping <IP_address> 11797785Spdeuskar 118146663Stackerman7. To configure the IP address to remain after reboot, edit /etc/rc.conf, 119146663Stackerman and create the appropriate ifconfig_em<interface_num>entry: 12097785Spdeuskar 121112472Spdeuskar ifconfig_em<interface_num>="<ifconfig_settings>" 122112472Spdeuskar 123112472Spdeuskar Example usage: 124112472Spdeuskar 125112472Spdeuskar ifconfig_em0="inet 192.168.10.1 netmask 255.255.255.0" 126112472Spdeuskar 127112472Spdeuskar NOTE: For assistance, see the ifconfig man page. 128112472Spdeuskar 129112472Spdeuskar 13097785SpdeuskarSpeed and Duplex Configuration 13197785Spdeuskar============================== 13297785Spdeuskar 133146663StackermanBy default, the adapter auto-negotiates the speed and duplex of the 134146663Stackermanconnection. If there is a specific need, the ifconfig utility can be used to 13597785Spdeuskarconfigure the speed and duplex settings on the adapter. Example usage: 13697785Spdeuskar 137146663Stackerman ifconfig em<interface_num> <IP_address> media 100baseTX mediaopt 13897785Spdeuskar full-duplex 13997785Spdeuskar 140146663Stackerman NOTE: Only use mediaopt to set the driver to full-duplex. If mediaopt is 141146663Stackerman not specified and you are not running at gigabit speed, the driver 14297785Spdeuskar defaults to half-duplex. 14397785Spdeuskar 144169240SjfvIf the interface is currently forced to 100 full duplex, in order to change 145169240Sjfvto half duplex you must use this command: 14697785Spdeuskar 147169240Sjfv ifconfig em<interface_num> <IP_address> media 100baseTX -mediaopt 148169240Sjfv full-duplex 149169240Sjfv 150169240Sjfv 15197785SpdeuskarThis driver supports the following media type options: 15297785Spdeuskar 15397785Spdeuskar autoselect - Enables auto-negotiation for speed and duplex. 15497785Spdeuskar 155146663Stackerman 10baseT/UTP - Sets speed to 10 Mbps. Use the ifconfig mediaopt 15697785Spdeuskar option to select full-duplex mode. 15797785Spdeuskar 15897785Spdeuskar 100baseTX - Sets speed to 100 Mbps. Use the ifconfig mediaopt 15997785Spdeuskar option to select full-duplex mode. 16097785Spdeuskar 16197785Spdeuskar 1000baseTX - Sets speed to 1000 Mbps. In this case, the driver 16297785Spdeuskar supports only full-duplex mode. 16397785Spdeuskar 16497785Spdeuskar 1000baseSX - Sets speed to 1000 Mbps. In this case, the driver 16597785Spdeuskar supports only full-duplex mode. 16697785Spdeuskar 16797785SpdeuskarFor more information on the ifconfig utility, see the ifconfig man page. 16897785Spdeuskar 16997785Spdeuskar 17097785SpdeuskarAdditional Configurations 17197785Spdeuskar========================= 17297785Spdeuskar 173146663StackermanThe driver supports Transmit/Receive Checksum Offload and Jumbo Frames on 174157566Sglebiusall but the 82542-based adapters. For specific adapters, refer to the 175146663StackermanIdentifying Your Adapter section. 176112472Spdeuskar 17797785Spdeuskar Jumbo Frames 17897785Spdeuskar ------------ 179157566Sglebius To enable Jumbo Frames, use the ifconfig utility to set the Maximum 180157566Sglebius Transport Unit (MTU) frame size above its default of 1500 bytes. 18197785Spdeuskar 182157566Sglebius The Jumbo Frames MTU range for Intel Adapters is 1500 to 16110. To modify 183157566Sglebius the setting, enter the following: 18497785Spdeuskar 185157566Sglebius ifconfig em<interface_num> <hostname or IP address> mtu 9000 186146663Stackerman 187157566Sglebius To confirm the MTU used between two specific devices, use: 188146663Stackerman 189157566Sglebius route get <destination_IP_address> 190146663Stackerman 191157566Sglebius Notes: 19297785Spdeuskar 193157566Sglebius - Only enable Jumbo Frames if your network infrastructure supports them. 19497785Spdeuskar 195157566Sglebius - To enable Jumbo Frames, increase the MTU size on the interface beyond 196157566Sglebius 1500. 197112472Spdeuskar 198157566Sglebius - The Jumbo Frames setting on the switch must be set to at least 22 bytes 199157566Sglebius larger than that of the MTU. 200112472Spdeuskar 201157566Sglebius - The maximum MTU setting for Jumbo Frames is 16110. This value coincides 202157566Sglebius with the maximum Jumbo Frames size of 16128. 203157566Sglebius 204157566Sglebius - Some Intel gigabit adapters that support Jumbo Frames have a frame size 205157566Sglebius limit of 9238 bytes, with a corresponding MTU size limit of 9216 bytes. 206157566Sglebius The adapters with this limitation are based on the Intel(R) 82571EB, 207169240Sjfv 82572EI, 82573L, 82566, 82562, and 80003ES2LAN controller. These 208169240Sjfv correspond to the following product names: 209157566Sglebius Intel(R) PRO/1000 PT Server Adapter 210157566Sglebius Intel(R) PRO/1000 PT Desktop Adapter 211157566Sglebius Intel(R) PRO/1000 PT Network Connection 212157566Sglebius Intel(R) PRO/1000 PT Dual Port Server Adapter 213157566Sglebius Intel(R) PRO/1000 PT Dual Port Network Connection 214157566Sglebius Intel(R) PRO/1000 PF Server Adapter 215157566Sglebius Intel(R) PRO/1000 PF Network Connection 216157566Sglebius Intel(R) PRO/1000 PF Dual Port Server Adapter 217157566Sglebius Intel(R) PRO/1000 PB Server Connection 218157566Sglebius Intel(R) PRO/1000 PL Network Connection 219157566Sglebius Intel(R) PRO/1000 EB Network Connection with I/O Acceleration 220157566Sglebius Intel(R) PRO/1000 EB Backplane Connection with I/O Acceleration 221169240Sjfv Intel(R) 82566DM-2 Gigabit Network Connection 222157566Sglebius 223157566Sglebius - Adapters based on the Intel(R) 82542 and 82573V/E controller do not 224157566Sglebius support Jumbo Frames. These correspond to the following product names: 225157566Sglebius Intel(R) PRO/1000 Gigabit Server Adapter 226157566Sglebius Intel(R) PRO/1000 PM Network Connection 227157566Sglebius 228157566Sglebius - Using Jumbo Frames at 10 or 100 Mbps may result in poor performance or 229157566Sglebius loss of link. 230157566Sglebius 231160949Sglebius - The following adapters do not support Jumbo Frames: 232160949Sglebius Intel(R) 82562V 10/100 Network Connection 233160949Sglebius Intel(R) 82566DM Gigabit Network Connection 234160949Sglebius Intel(R) 82566DC Gigabit Network Connection 235160949Sglebius Intel(R) 82566MM Gigabit Network Connection 236160949Sglebius Intel(R) 82566MC Gigabit Network Connection 237169240Sjfv Intel(R) 82562GT 10/100 Network Connection 238169240Sjfv Intel(R) 82562G 10/100 Network Connection 239169240Sjfv Intel(R) 82566DC-2 Gigabit Network Connection 240169240Sjfv Intel(R) 82562V-2 10/100 Network Connection 241169240Sjfv Intel(R) 82562G-2 10/100 Network Connection 242169240Sjfv Intel(R) 82562GT-2 10/100 Network Connection 243157566Sglebius 24497785Spdeuskar VLANs 24597785Spdeuskar ----- 246146663Stackerman To create a new VLAN interface: 24797785Spdeuskar 248112472Spdeuskar ifconfig <vlan_name> create 24997785Spdeuskar 250146663Stackerman To associate the VLAN interface with a physical interface and 251112472Spdeuskar assign a VLAN ID, IP address, and netmask: 25297785Spdeuskar 253146663Stackerman ifconfig <vlan_name> <ip_address> netmask <subnet_mask> vlan 254112472Spdeuskar <vlan_id> vlandev <physical_interface> 25597785Spdeuskar 256112472Spdeuskar Example: 25797785Spdeuskar 258169240Sjfv ifconfig vlan10 10.0.0.1 netmask 255.255.255.0 vlan 10 vlandev em0 25997785Spdeuskar 260169240Sjfv In this example, all packets will be marked on egress with 802.1Q VLAN 261112472Spdeuskar tags, specifying a VLAN ID of 10. 26297785Spdeuskar 263146663Stackerman To remove a VLAN interface: 26497785Spdeuskar 265112472Spdeuskar ifconfig <vlan_name> destroy 26697785Spdeuskar 267157566Sglebius 268112472Spdeuskar Polling 269112472Spdeuskar ------- 270169240Sjfv NOTES: Device Polling is only valid for non-SMP (Symmetric MultiProcessing) 271169240Sjfv kernels. 272169240Sjfv 273169240Sjfv The driver has to be compiled into the kernel for Device Polling to be 274169240Sjfv enabled in the driver. 275169240Sjfv 276146663Stackerman To enable polling in the driver, add the following options to the kernel 277112472Spdeuskar configuration, and then recompile the kernel: 27897785Spdeuskar 279112472Spdeuskar options DEVICE_POLLING 280112472Spdeuskar options HZ=1000 281112472Spdeuskar 282146663Stackerman At runtime use: 283169240Sjfv sysctl kern.polling.enable=1 to turn polling on 284146663Stackerman Use: 285169240Sjfv sysctl kern.polling.enable=0 to turn polling off 286112472Spdeuskar 287157566Sglebius 288146663Stackerman Checksum Offload 289146663Stackerman ---------------- 290146663Stackerman Checksum offloading is not supported on 82542 Gigabit adapters. 291112472Spdeuskar 292146663Stackerman Checksum offloading supports both TCP and UDP packets and is 293146663Stackerman supported for both transmit and receive. 294112472Spdeuskar 295146663Stackerman Checksum offloading can be enabled or disabled using ifconfig. 296146663Stackerman Both transmit and receive offloading will be either enabled or 297146663Stackerman disabled together. You cannot enable/disable one without the other. 298112472Spdeuskar 299146663Stackerman To enable checksum offloading: 300112472Spdeuskar 301146663Stackerman ifconfig <interface_num> rxcsum 302112472Spdeuskar 303146663Stackerman To disable checksum offloading: 304146663Stackerman 305146663Stackerman ifconfig <interface_num> -rxcsum 306146663Stackerman 307146663Stackerman To confirm the current setting: 308146663Stackerman 309146663Stackerman ifconfig <interface_num> 310146663Stackerman 311146663Stackerman Look for the presence or absence of the following line: 312146663Stackerman 313146663Stackerman options=3 <RXCSUM,TXCSUM> 314146663Stackerman 315146663Stackerman See the ifconfig man page for further information. 316146663Stackerman 317157566Sglebius 318169240Sjfv TSO 319169240Sjfv --- 320169240Sjfv The FreeBSD driver now offers support for TSO (TCP Segmentation Offload). 321169240Sjfv To enable this support perform the following: 322169240Sjfv 323169240Sjfv Patch the kernel with the patch supplied in the tarball. 324169240Sjfv Rebuild and install the kernel. 325169240Sjfv Recompile the driver. You must alter the Makefile to build the driver with 326169240Sjfv E1000_TSO defined. 327169240Sjfv 328169240Sjfv Enable or disable TSO: 329169240Sjfv sysctl net.inet.tcp.tso=1 or 0 330169240Sjfv 0=disabled, 1=enabled (TSO is enabled by default). 331169240Sjfv 332169240Sjfv NOTE: TSO is not supported on 82547 and 82544-based adapters, as well as 333169240Sjfv older adapters. 334169240Sjfv 335169240Sjfv 33697785SpdeuskarKnown Limitations 33797785Spdeuskar================= 338146663Stackerman 339169240Sjfv Detected Tx Unit Hang in Quad Port Adapters 340169240Sjfv ------------------------------------------- 341169240Sjfv 342169240Sjfv In some cases ports 3 and 4 wont pass traffic. Ports 1 and 2 don't show 343169240Sjfv any errors and will pass traffic. 344169240Sjfv 345169240Sjfv This issue MAY be resolved by updating to the latest BIOS. You can 346169240Sjfv check your system's BIOS by downloading the Linux Firmware Developer Kit 347169240Sjfv that can be obtained at http://www.linuxfirmwarekit.org/ 348169240Sjfv 349169240Sjfv FreeBSD version 4.x with Symmetric MultiProcessing (SMP) 350169240Sjfv -------------------------------------------------------- 351169240Sjfv 352157566Sglebius In FreeBSD version 4.x with Symmetric MultiProcessing (SMP), there is a known 353169240Sjfv issue on some newer hardware. The problem is kernel generic and only in SMP 354157566Sglebius mode. The workaround is to either use FreeBSD version 4.x in single processor 355157566Sglebius mode, or use FreeBSD 5.4 or later. 356157566Sglebius 357119509Spdeuskar There are known performance issues with this driver when running UDP traffic 358146663Stackerman with Jumbo Frames. 359169240Sjfv ---------------------------------------------------------------------------- 36097785Spdeuskar 361169240Sjfv 82541/82547 can't link or is slow to link with some link partners 362169240Sjfv ----------------------------------------------------------------- 363169240Sjfv 364146663Stackerman There is a known compatibility issue where time to link is slow or link is not 365146663Stackerman established between 82541/82547 controllers and some switches. Known switches 366146663Stackerman include: 367119509Spdeuskar Planex FXG-08TE 368119509Spdeuskar I-O Data ETG-SH8 369119509Spdeuskar 370146663Stackerman The driver can be compiled with the following changes: 371119509Spdeuskar 372169240Sjfv Edit ./em.x.x.x/src/if_em.h to uncomment the #define E1000_MASTER_SLAVE 373146663Stackerman from within the comments. For example, change from: 374119509Spdeuskar 375169240Sjfv /* #define E1000_MASTER_SLAVE 2 */ 376146663Stackerman to: 377169240Sjfv #define E1000_MASTER_SLAVE 2 378119509Spdeuskar 379146663Stackerman Use one of the following options: 380119509Spdeuskar 1 = Master mode 381119509Spdeuskar 2 = Slave mode 382119509Spdeuskar 3 = Auto master/slave 383146663Stackerman Setting 2 is recommended. 384119509Spdeuskar 385146663Stackerman Recompile the module: 386146663Stackerman a. To compile the module 387146663Stackerman cd em-x.x.x 388146663Stackerman make clean 389146663Stackerman make 390119509Spdeuskar 391119509Spdeuskar b. To install the compiled module in system directory: 392146663Stackerman make install 393119509Spdeuskar 394119509Spdeuskar 39597785SpdeuskarSupport 39697785Spdeuskar======= 39797785Spdeuskar 39897785SpdeuskarFor general information and support, go to the Intel support website at: 39997785Spdeuskar 40097785Spdeuskar http://support.intel.com 40197785Spdeuskar 402146663StackermanIf an issue is identified, support is through email only at: 403146663Stackermanfreebsdnic@mailbox.intel.com 40497785Spdeuskar 405157566Sglebius 40697785SpdeuskarLicense 40797785Spdeuskar======= 40897785Spdeuskar 409146663StackermanThis software program is released under the terms of a license agreement 410146663Stackermanbetween you ('Licensee') and Intel. Do not use or load this software or any 411146663Stackermanassociated materials (collectively, the 'Software') until you have carefully 412146663Stackermanread the full terms and conditions of the LICENSE located in this software 413146663Stackermanpackage. By loading or using the Software, you agree to the terms of this 414146663StackermanAgreement. If you do not agree with the terms of this Agreement, do not 41597785Spdeuskarinstall or use the Software. 41697785Spdeuskar 41797785Spdeuskar* Other names and brands may be claimed as the property of others. 418