README revision 157566
197785Spdeuskar$FreeBSD: head/sys/dev/em/README 157566 2006-04-06 17:09:03Z glebius $ 297785SpdeuskarFreeBSD* Driver for the Intel(R) PRO/1000 Family of Adapters 397785Spdeuskar============================================================ 497785Spdeuskar 5157566SglebiusJanuary 4, 2006 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 24157566SglebiusThis file describes the FreeBSD* driver for the Intel(R) PRO/1000 Family of 25157566SglebiusAdapters. This driver has been developed for use with FreeBSD, Release 4.11 26157566Sglebiusand greater and Release 5.4. 2797785Spdeuskar 28146663StackermanFor questions related to hardware requirements, refer to the documentation 29146663Stackermansupplied with your Intel PRO/1000 adapter. All hardware requirements listed 3097785Spdeuskarapply to use with FreeBSD. 3197785Spdeuskar 3297785Spdeuskar 33146663StackermanIdentifying Your Adapter 34146663Stackerman======================== 3597785Spdeuskar 36146663StackermanFor information on how to identify your adapter, go to the Adapter & 37146663StackermanDriver ID Guide at: 3897785Spdeuskar 39157566Sglebiushttp://support.intel.com/support/network/sb/cs-012904.htm 4097785Spdeuskar 4197785Spdeuskar 42146663StackermanFor the latest Intel network drivers for FreeBSD, see: 4397785Spdeuskar 44157566Sglebiushttp://downloadfinder.intel.com/scripts-df-external/support_intel.aspx 4597785Spdeuskar 4697785Spdeuskar 47146663StackermanNOTE: Mobile adapters are not fully supported. 4897785Spdeuskar 49119509Spdeuskar 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 65112472Spdeuskar tar xvfz 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 77146663Stackerman b. To install the compiled module in 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 87112472Spdeuskar4. To compile the driver into the kernel: 8897785Spdeuskar 89112472Spdeuskar cd em-x.x.x/src 9097785Spdeuskar 91112472Spdeuskar cp if_em* /usr/src/sys/dev/em 9297785Spdeuskar 93115878Spdeuskar cp Makefile.kernel /usr/src/sys/modules/em/Makefile 9497785Spdeuskar 95146663Stackerman Edit the /usr/src/sys/conf/files.i386 file, and add the following lines only if 96146663Stackerman they don't already exist: 9797785Spdeuskar 98112472Spdeuskar dev/em/if_em.c optional em 9997785Spdeuskar 100146663Stackerman dev/em/if_em_hw.c optional em 10197785Spdeuskar 102146663Stackerman Remove the following lines from the /usr/src/sys/conf/files.i386 file, 103112472Spdeuskar if they exist: 10497785Spdeuskar 105112472Spdeuskar dev/em/if_em_fxhw.c optional em 106112472Spdeuskar dev/em/if_em_phy.c optional em 10797785Spdeuskar 108146663Stackerman Edit the kernel configuration file (i.e., GENERIC or MYKERNEL) in 109112472Spdeuskar /usr/src/sys/i386/conf, and ensure the following line is present: 11097785Spdeuskar 111112472Spdeuskar device em 11297785Spdeuskar 113112472Spdeuskar Compile and install the kernel. The system must be rebooted for the kernel 114146663Stackerman updates to take effect. For additional information on compiling the 115112472Spdeuskar kernel, consult the FreeBSD operating system documentation. 11697785Spdeuskar 117112472Spdeuskar5. To assign an IP address to the interface, enter the following: 11897785Spdeuskar 119112472Spdeuskar ifconfig em<interface_num> <IP_address> 12097785Spdeuskar 121112472Spdeuskar6. Verify that the interface works. Enter the following, where <IP_address> 122112472Spdeuskar is the IP address for another machine on the same subnet as the interface 123112472Spdeuskar that is being tested: 12497785Spdeuskar 125112472Spdeuskar ping <IP_address> 12697785Spdeuskar 127146663Stackerman7. To configure the IP address to remain after reboot, edit /etc/rc.conf, 128146663Stackerman and create the appropriate ifconfig_em<interface_num>entry: 12997785Spdeuskar 130112472Spdeuskar ifconfig_em<interface_num>="<ifconfig_settings>" 131112472Spdeuskar 132112472Spdeuskar Example usage: 133112472Spdeuskar 134112472Spdeuskar ifconfig_em0="inet 192.168.10.1 netmask 255.255.255.0" 135112472Spdeuskar 136112472Spdeuskar NOTE: For assistance, see the ifconfig man page. 137112472Spdeuskar 138112472Spdeuskar 13997785SpdeuskarSpeed and Duplex Configuration 14097785Spdeuskar============================== 14197785Spdeuskar 142146663StackermanBy default, the adapter auto-negotiates the speed and duplex of the 143146663Stackermanconnection. If there is a specific need, the ifconfig utility can be used to 14497785Spdeuskarconfigure the speed and duplex settings on the adapter. Example usage: 14597785Spdeuskar 146146663Stackerman ifconfig em<interface_num> <IP_address> media 100baseTX mediaopt 14797785Spdeuskar full-duplex 14897785Spdeuskar 149146663Stackerman NOTE: Only use mediaopt to set the driver to full-duplex. If mediaopt is 150146663Stackerman not specified and you are not running at gigabit speed, the driver 15197785Spdeuskar defaults to half-duplex. 15297785Spdeuskar 15397785Spdeuskar 15497785SpdeuskarThis driver supports the following media type options: 15597785Spdeuskar 15697785Spdeuskar autoselect - Enables auto-negotiation for speed and duplex. 15797785Spdeuskar 158146663Stackerman 10baseT/UTP - Sets speed to 10 Mbps. Use the ifconfig mediaopt 15997785Spdeuskar option to select full-duplex mode. 16097785Spdeuskar 16197785Spdeuskar 100baseTX - Sets speed to 100 Mbps. Use the ifconfig mediaopt 16297785Spdeuskar option to select full-duplex mode. 16397785Spdeuskar 16497785Spdeuskar 1000baseTX - Sets speed to 1000 Mbps. In this case, the driver 16597785Spdeuskar supports only full-duplex mode. 16697785Spdeuskar 16797785Spdeuskar 1000baseSX - Sets speed to 1000 Mbps. In this case, the driver 16897785Spdeuskar supports only full-duplex mode. 16997785Spdeuskar 17097785SpdeuskarFor more information on the ifconfig utility, see the ifconfig man page. 17197785Spdeuskar 17297785Spdeuskar 17397785SpdeuskarAdditional Configurations 17497785Spdeuskar========================= 17597785Spdeuskar 176146663StackermanThe driver supports Transmit/Receive Checksum Offload and Jumbo Frames on 177157566Sglebiusall but the 82542-based adapters. For specific adapters, refer to the 178146663StackermanIdentifying Your Adapter section. 179112472Spdeuskar 18097785Spdeuskar Jumbo Frames 18197785Spdeuskar ------------ 182157566Sglebius To enable Jumbo Frames, use the ifconfig utility to set the Maximum 183157566Sglebius Transport Unit (MTU) frame size above its default of 1500 bytes. 18497785Spdeuskar 185157566Sglebius The Jumbo Frames MTU range for Intel Adapters is 1500 to 16110. To modify 186157566Sglebius the setting, enter the following: 18797785Spdeuskar 188157566Sglebius ifconfig em<interface_num> <hostname or IP address> mtu 9000 189146663Stackerman 190157566Sglebius To confirm the MTU used between two specific devices, use: 191146663Stackerman 192157566Sglebius route get <destination_IP_address> 193146663Stackerman 194157566Sglebius Notes: 19597785Spdeuskar 196157566Sglebius - Only enable Jumbo Frames if your network infrastructure supports them. 19797785Spdeuskar 198157566Sglebius - To enable Jumbo Frames, increase the MTU size on the interface beyond 199157566Sglebius 1500. 200112472Spdeuskar 201157566Sglebius - The Jumbo Frames setting on the switch must be set to at least 22 bytes 202157566Sglebius larger than that of the MTU. 203112472Spdeuskar 204157566Sglebius - The maximum MTU setting for Jumbo Frames is 16110. This value coincides 205157566Sglebius with the maximum Jumbo Frames size of 16128. 206157566Sglebius 207157566Sglebius - Some Intel gigabit adapters that support Jumbo Frames have a frame size 208157566Sglebius limit of 9238 bytes, with a corresponding MTU size limit of 9216 bytes. 209157566Sglebius The adapters with this limitation are based on the Intel(R) 82571EB, 210157566Sglebius 82572EI, 82573L and 80003ES2LAN controller. These correspond to the 211157566Sglebius following product names: 212157566Sglebius Intel(R) PRO/1000 PT Server Adapter 213157566Sglebius Intel(R) PRO/1000 PT Desktop Adapter 214157566Sglebius Intel(R) PRO/1000 PT Network Connection 215157566Sglebius Intel(R) PRO/1000 PT Dual Port Server Adapter 216157566Sglebius Intel(R) PRO/1000 PT Dual Port Network Connection 217157566Sglebius Intel(R) PRO/1000 PF Server Adapter 218157566Sglebius Intel(R) PRO/1000 PF Network Connection 219157566Sglebius Intel(R) PRO/1000 PF Dual Port Server Adapter 220157566Sglebius Intel(R) PRO/1000 PB Server Connection 221157566Sglebius Intel(R) PRO/1000 PL Network Connection 222157566Sglebius Intel(R) PRO/1000 EB Network Connection with I/O Acceleration 223157566Sglebius Intel(R) PRO/1000 EB Backplane Connection with I/O Acceleration 224157566Sglebius 225157566Sglebius - Adapters based on the Intel(R) 82542 and 82573V/E controller do not 226157566Sglebius support Jumbo Frames. These correspond to the following product names: 227157566Sglebius Intel(R) PRO/1000 Gigabit Server Adapter 228157566Sglebius Intel(R) PRO/1000 PM Network Connection 229157566Sglebius 230157566Sglebius - Using Jumbo Frames at 10 or 100 Mbps may result in poor performance or 231157566Sglebius loss of link. 232157566Sglebius 233157566Sglebius 23497785Spdeuskar VLANs 23597785Spdeuskar ----- 236146663Stackerman To create a new VLAN interface: 23797785Spdeuskar 238112472Spdeuskar ifconfig <vlan_name> create 23997785Spdeuskar 240146663Stackerman To associate the VLAN interface with a physical interface and 241112472Spdeuskar assign a VLAN ID, IP address, and netmask: 24297785Spdeuskar 243146663Stackerman ifconfig <vlan_name> <ip_address> netmask <subnet_mask> vlan 244112472Spdeuskar <vlan_id> vlandev <physical_interface> 24597785Spdeuskar 246112472Spdeuskar Example: 24797785Spdeuskar 248112472Spdeuskar ifconfig vlan10 10.0.0.1 netmask 255.255.255.0 vlan10 vlandev em0 24997785Spdeuskar 250146663Stackerman In this example, all packets will be marked on egress with 802.1Q VLAN 251112472Spdeuskar tags, specifying a VLAN ID of 10. 25297785Spdeuskar 253146663Stackerman To remove a VLAN interface: 25497785Spdeuskar 255112472Spdeuskar ifconfig <vlan_name> destroy 25697785Spdeuskar 257157566Sglebius 258112472Spdeuskar Polling 259112472Spdeuskar ------- 260146663Stackerman To enable polling in the driver, add the following options to the kernel 261112472Spdeuskar configuration, and then recompile the kernel: 26297785Spdeuskar 263112472Spdeuskar options DEVICE_POLLING 264112472Spdeuskar options HZ=1000 265112472Spdeuskar 266146663Stackerman At runtime use: 267157566Sglebius ifconfig em0 polling to turn polling on 268146663Stackerman Use: 269157566Sglebius ifconfig em0 -polling to turn polling off 270112472Spdeuskar 271157566Sglebius 272146663Stackerman Checksum Offload 273146663Stackerman ---------------- 274146663Stackerman Checksum offloading is not supported on 82542 Gigabit adapters. 275112472Spdeuskar 276146663Stackerman Checksum offloading supports both TCP and UDP packets and is 277146663Stackerman supported for both transmit and receive. 278112472Spdeuskar 279146663Stackerman Checksum offloading can be enabled or disabled using ifconfig. 280146663Stackerman Both transmit and receive offloading will be either enabled or 281146663Stackerman disabled together. You cannot enable/disable one without the other. 282112472Spdeuskar 283146663Stackerman To enable checksum offloading: 284112472Spdeuskar 285146663Stackerman ifconfig <interface_num> rxcsum 286112472Spdeuskar 287146663Stackerman To disable checksum offloading: 288146663Stackerman 289146663Stackerman ifconfig <interface_num> -rxcsum 290146663Stackerman 291146663Stackerman To confirm the current setting: 292146663Stackerman 293146663Stackerman ifconfig <interface_num> 294146663Stackerman 295146663Stackerman Look for the presence or absence of the following line: 296146663Stackerman 297146663Stackerman options=3 <RXCSUM,TXCSUM> 298146663Stackerman 299146663Stackerman See the ifconfig man page for further information. 300146663Stackerman 301157566Sglebius 30297785SpdeuskarKnown Limitations 30397785Spdeuskar================= 304146663Stackerman 305157566Sglebius In FreeBSD version 4.x with Symmetric MultiProcessing (SMP), there is a known 306157566Sglebius issue on some newer hardware. The problem is generic kernel and only in SMP 307157566Sglebius mode. The workaround is to either use FreeBSD version 4.x in single processor 308157566Sglebius mode, or use FreeBSD 5.4 or later. 309157566Sglebius 310119509Spdeuskar There are known performance issues with this driver when running UDP traffic 311146663Stackerman with Jumbo Frames. 31297785Spdeuskar 313146663Stackerman There is a known compatibility issue where time to link is slow or link is not 314146663Stackerman established between 82541/82547 controllers and some switches. Known switches 315146663Stackerman include: 316119509Spdeuskar Planex FXG-08TE 317119509Spdeuskar I-O Data ETG-SH8 318119509Spdeuskar 319146663Stackerman The driver can be compiled with the following changes: 320119509Spdeuskar 321146663Stackerman Edit ./em.x.x.x/src/if_em.h to uncomment the #define EM_MASTER_SLAVE 322146663Stackerman from within the comments. For example, change from: 323119509Spdeuskar 324119509Spdeuskar /* #define EM_MASTER_SLAVE 2 */ 325146663Stackerman to: 326146663Stackerman #define EM_MASTER_SLAVE 2 327119509Spdeuskar 328146663Stackerman Use one of the following options: 329119509Spdeuskar 1 = Master mode 330119509Spdeuskar 2 = Slave mode 331119509Spdeuskar 3 = Auto master/slave 332146663Stackerman Setting 2 is recommended. 333119509Spdeuskar 334146663Stackerman Recompile the module: 335146663Stackerman a. To compile the module 336146663Stackerman cd em-x.x.x 337146663Stackerman make clean 338146663Stackerman make 339119509Spdeuskar 340119509Spdeuskar b. To install the compiled module in system directory: 341146663Stackerman make install 342119509Spdeuskar 343119509Spdeuskar 34497785SpdeuskarSupport 34597785Spdeuskar======= 34697785Spdeuskar 34797785SpdeuskarFor general information and support, go to the Intel support website at: 34897785Spdeuskar 34997785Spdeuskar http://support.intel.com 35097785Spdeuskar 351146663StackermanIf an issue is identified, support is through email only at: 352146663Stackermanfreebsdnic@mailbox.intel.com 35397785Spdeuskar 354157566Sglebius 35597785SpdeuskarLicense 35697785Spdeuskar======= 35797785Spdeuskar 358146663StackermanThis software program is released under the terms of a license agreement 359146663Stackermanbetween you ('Licensee') and Intel. Do not use or load this software or any 360146663Stackermanassociated materials (collectively, the 'Software') until you have carefully 361146663Stackermanread the full terms and conditions of the LICENSE located in this software 362146663Stackermanpackage. By loading or using the Software, you agree to the terms of this 363146663StackermanAgreement. If you do not agree with the terms of this Agreement, do not 36497785Spdeuskarinstall or use the Software. 36597785Spdeuskar 36697785Spdeuskar* Other names and brands may be claimed as the property of others. 367