1FreeBSD* Driver for Intel(R) Ethernet 2===================================== 3 4August 7, 2019 5 6Contents 7======== 8 9- Overview 10- Identifying Your Adapter 11- Building and Installation 12- Additional Features and Configurations 13- Known Issues/Troubleshooting 14- Support 15- License 16 17 18Overview 19======== 20This file describes the FreeBSD* driver for Intel(R) Ethernet. This driver has 21been developed for use with all community-supported versions of FreeBSD. 22 23For questions related to hardware requirements, refer to the documentation 24supplied with your Intel Ethernet Adapter. All hardware requirements listed 25apply to use with FreeBSD. 26 27 28Identifying Your Adapter 29======================== 30This release includes two gigabit FreeBSD base Drivers for Intel(R) Ethernet. 31These drivers are em and igb. 32 33- The igb driver supports all 82575 and 82576-based gigabit network connections. 34- The em driver supports all other gigabit network connections. 35- Gigabit devices base on the Intel(R) Ethernet Controller X722 are supported by 36 the ixl driver. 37 38NOTE: The Intel(R) 82562v 10/100 Network Connection only provides 10/100 39support. 40 41For information on how to identify your adapter, and for the latest Intel 42network drivers, refer to the Intel Support website: 43http://www.intel.com/support 44 45 46Building and Installation 47========================= 48NOTE: This driver package is to be used only as a standalone archive and the 49user should not attempt to incorporate it into the kernel source tree. 50 51In the instructions below, x.x.x is the driver version as indicated in the name 52of the driver tar file. 53 541. Move the base driver tar file to the directory of your choice. For 55 example, use /home/username/em or /usr/local/src/em. 56 572. Untar/unzip the archive: 58 59 # tar xzf em-x.x.x.tar.gz 60 61This will create the em-x.x.x directory. 62 633. To install man page: 64 65 # cd em-x.x.x 66 # gzip -c em.4 > /usr/share/man/man4/em.4.gz 67 684. To load the driver onto a running system: 69 70 # cd em-x.x.x/src 71 # make 72 # kldload ./if_em.ko 73 745. To assign an IP address to the interface, enter the following: 75 76 # ifconfig em<interface_num> <IP_address> 77 786. Verify that the interface works. Enter the following, where <IP_address> 79 is the IP address for another machine on the same subnet as the interface 80 that is being tested: 81 82 # ping <IP_address> 83 847. If you want the driver to load automatically when the system is booted: 85 86 # cd em-x.x.x/src 87 # make 88 # make install 89 90Edit /boot/loader.conf, and add the following line: 91 if_em_load="YES" 92 93Edit /etc/rc.conf, and create the appropriate ifconfig_em<interface_num> entry: 94 95 ifconfig_em<interface_num>="<ifconfig_settings>" 96 97Example usage: 98 ifconfig_em0="inet 192.168.10.1 netmask 255.255.255.0" 99 100 NOTE: For assistance, see the ifconfig man page. 101 102 103Additional Features and Configurations 104====================================== 105 106Speed and Duplex Configuration 107------------------------------ 108In addressing speed and duplex configuration issues, you need to distinguish 109between copper-based adapters and fiber-based adapters. 110 111In the default mode, an Intel(R) Ethernet Network Adapter using copper 112connections will attempt to auto-negotiate with its link partner to determine 113the best setting. If the adapter cannot establish link with the link partner 114using auto-negotiation, you may need to manually configure the adapter and link 115partner to identical settings to establish link and pass packets. This should 116only be needed when attempting to link with an older switch that does not 117support auto-negotiation or one that has been forced to a specific speed or 118duplex mode. Your link partner must match the setting you choose. 1 Gbps speeds 119and higher cannot be forced. Use the autonegotiation advertising setting to 120manually set devices for 1 Gbps and higher. 121 122Caution: Only experienced network administrators should force speed and duplex 123or change autonegotiation advertising manually. The settings at the switch must 124always match the adapter settings. Adapter performance may suffer or your 125adapter may not operate if you configure the adapter differently from your 126switch. 127 128An Intel(R) Ethernet Network Adapter using fiber-based connections, however, 129will not attempt to auto-negotiate with its link partner since those adapters 130operate only in full duplex and only at their native speed. 131 132By default, the adapter auto-negotiates the speed and duplex of the connection. 133If there is a specific need, the ifconfig utility can be used to configure the 134speed and duplex settings on the adapter. 135 136Example usage: 137 138# ifconfig emX <IP_address> media 100baseTX mediaopt full-duplex 139 140NOTE: Only use mediaopt to set the driver to full-duplex. If mediaopt is not 141specified and you are not running at gigabit speed, the driver defaults to 142half-duplex. 143 144If the interface is currently forced to 100 full duplex, you must use this 145command to change to half duplex: 146 147# ifconfig emX <IP_address> media 100baseTX -mediaopt full-duplex 148 149This driver supports the following media type options: 150 151Media Type Description 152---------- ----------- 153autoselect Enables auto-negotiation for speed and duplex. 15410baseT/UTP Sets speed to 10 Mbps. Use the ifconfig mediaopt 155 option to select full-duplex mode. 156100baseTX Sets speed to 100 Mbps. Use the ifconfig mediaopt 157 option to select full-duplex mode. 1581000baseTX Sets speed to 1000 Mbps. In this case, the driver 159 supports only full-duplex mode. 1601000baseSX Sets speed to 1000 Mbps. In this case, the driver 161 supports only full-duplex mode. 162 163For more information on the ifconfig utility, see the ifconfig man page. 164 165Jumbo Frames 166------------ 167Jumbo Frames support is enabled by changing the Maximum Transmission Unit (MTU) 168to a value larger than the default value of 1500. 169 170Use the ifconfig command to increase the MTU size. For example, enter the 171following where X is the interface number: 172 173# ifconfig emX mtu 9000 174 175To confirm an interface's MTU value, use the ifconfig command. 176 177To confirm the MTU used between two specific devices, use: 178 179# route get <destination_IP_address> 180 181NOTE: The maximum MTU setting for Jumbo Frames is 16110. This value coincides 182with the maximum Jumbo Frames size of 16132 bytes. 183 184NOTE: Using Jumbo frames at 10 or 100 Mbps is not supported and may result in 185poor performance or loss of link. 186 187NOTE: Packet loss may have a greater impact on throughput when you use jumbo 188frames. If you observe a drop in performance after enabling jumbo frames, 189enabling flow control may mitigate the issue. 190 191NOTE: Some Intel gigabit adapters that support Jumbo Frames have a frame size 192limit of 9238 bytes, with a corresponding MTU size limit of 9216 bytes. The 193adapters with this limitation are based on the Intel(R) 82571EB, 82572EI, 19482573L, 82566, 82562, and 80003ES2LAN controller. These correspond to the 195following product names: 196 Intel(R) PRO/1000 PT Server Adapter 197 Intel(R) PRO/1000 PT Desktop Adapter 198 Intel(R) PRO/1000 PT Network Connection 199 Intel(R) PRO/1000 PT Dual Port Server Adapter 200 Intel(R) PRO/1000 PT Dual Port Network Connection 201 Intel(R) PRO/1000 PT Quad Port Server Adapter 202 Intel(R) PRO/1000 PF Quad Port Server Adapter 203 Intel(R) PRO/1000 PF Server Adapter 204 Intel(R) PRO/1000 PF Network Connection 205 Intel(R) PRO/1000 PF Dual Port Server Adapter 206 Intel(R) PRO/1000 PB Server Connection 207 Intel(R) PRO/1000 PL Network Connection 208 Intel(R) PRO/1000 EB Network Connection with I/O Acceleration 209 Intel(R) PRO/1000 EB Backplane Connection with I/O Acceleration 210 Intel(R) 82566DM-2 Gigabit Network Connection 211 Intel(R) 82574L Gigabit Network Connection 212 Intel(R) Gigabit CT Desktop Adapter 213 Intel(R) 82567LM-4 Gigabit Network Connection 214 Intel(R) 82567LM-3 Gigabit Network Connection 215 Intel(R) 82567LF-3 Gigabit Network Connection 216 217NOTE: The following adapters limit Jumbo Frames sized packets to a maximum of 2184088 bytes: 219 - Intel(R) 82578DM Gigabit Network Connection 220 - Intel(R) 82577LM Gigabit Network Connection 221- The following adapters do not support Jumbo Frames: 222 - Intel(R) PRO/1000 Gigabit Server Adapter 223 - Intel(R) PRO/1000 PM Network Connection 224 - Intel(R) 82562G 10/100 Network Connection 225 - Intel(R) 82562G-2 10/100 Network Connection 226 - Intel(R) 82562GT 10/100 Network Connection 227 - Intel(R) 82562GT-2 10/100 Network Connection 228 - Intel(R) 82562V 10/100 Network Connection 229 - Intel(R) 82562V-2 10/100 Network Connection 230 - Intel(R) 82566DC Gigabit Network Connection 231 - Intel(R) 82566DC-2 Gigabit Network Connection 232 - Intel(R) 82566DM Gigabit Network Connection 233 - Intel(R) 82566MC Gigabit Network Connection 234 - Intel(R) 82566MM Gigabit Network Connection 235 - Intel(R) 82567V-3 Gigabit Network Connection 236 - Intel(R) 82577LC Gigabit Network Connection 237 - Intel(R) 82578DC Gigabit Network Connection 238- Jumbo Frames cannot be configured on an 82579-based Network device if 239 MACSec is enabled on the system. 240 241 242VLANS 243----- 244To create a new VLAN interface: 245 246# ifconfig <vlan_name> create 247 248To associate the VLAN interface with a physical interface and assign a VLAN ID, 249IP address, and netmask: 250 251# ifconfig <vlan_name> <ip_address> netmask <subnet_mask> vlan <vlan_id> 252vlandev <physical_interface> 253 254Example: 255 256# ifconfig vlan10 10.0.0.1 netmask 255.255.255.0 vlan 10 vlandev em0 257 258In this example, all packets will be marked on egress with 802.1Q VLAN tags, 259specifying a VLAN ID of 10. 260 261To remove a VLAN interface: 262 263# ifconfig <vlan_name> destroy 264 265 266Polling 267------- 268NOTES: 269- Device Polling is only valid for non-SMP kernels. 270- The driver has to be built into the kernel for Device Polling to be 271 enabled in the driver. 272 273To enable polling in the driver, add the following options to the kernel 274configuration, and then recompile the kernel: 275 276 options DEVICE_POLLING 277 options HZ=1000 278 279At runtime use: 280 ifconfig emX polling (to turn polling on) 281and: 282 ifconfig emX -polling (to turn it off) 283 284 285Checksum Offload 286---------------- 287Checksum offloading is not supported on 82542 Gigabit adapters. 288 289Checksum offloading supports both TCP and UDP packets and is supported for both 290transmit and receive. 291 292Checksum offloading can be enabled or disabled using ifconfig. Both transmit 293and receive offloading will be either enabled or disabled together. You cannot 294enable/disable one without the other. 295 296To enable checksum offloading: 297 298# ifconfig emX rxcsum 299 300To disable checksum offloading: 301 302# ifconfig emX -rxcsum 303 304To confirm the current setting: 305 306# ifconfig emX 307 308Look for the presence or absence of the following line: 309 options=3 <RXCSUM,TXCSUM> 310 311See the ifconfig man page for further information. 312 313 314TSO 315--- 316TSO (TCP Segmentation Offload) supports both IPv4 and IPv6. TSO can be disabled 317and enabled using the ifconfig utility or sysctl. 318 319NOTE: TSO requires Tx checksum, if Tx checksum is disabled, TSO will also be 320disabled. 321 322NOTE: By default only PCI-Express adapters are ENABLED to do TSO. Others can be 323enabled by the user at their own risk. TSO is not supported on 82547 or 32482544-based adapters, as well as older adapters. 325 326To enable/disable TSO in the stack: 327 328# sysctl net.inet.tcp.tso=0 (or 1 to enable it) 329 330Doing this disables/enables TSO in the stack and affects all installed adapters. 331 332To disable BOTH TSO IPv4 and IPv6: 333 334# ifconfig em<interface_num> -tso 335 336To enable BOTH TSO IPv4 and IPv6: 337 338# ifconfig em<interface_num> tso 339 340You can also enable/disable IPv4 TSO or IPv6 TSO individually. Simply replace 341tso|-tso in the above command with tso4 or tso6. For example, to disable 342TSO IPv4: 343 344# ifconfig em<interface_num> -tso4 345 346To disable TSO IPv6: 347 348# ifconfig em<interface_num> -tso6 349 350 351MSI-X 352----- 353MSI or MSI-X can be turned off by an entry in /etc/sysctl.conf 354 355 hw.em.enable_msi=0 356 357Unload and reload the driver. 358 359 360Known Issues/Troubleshooting 361============================ 362 363Detected Tx Unit Hang in Quad Port Adapters 364------------------------------------------- 365In some cases ports 3 and 4 don't pass traffic and report 'Detected Tx Unit 366Hang' followed by 'NETDEV WATCHDOG: emX: transmit timed out' errors. Ports 1 367and 2 do not show any errors and will pass traffic. 368 369This issue may be resolved by updating to the latest kernel and BIOS. You 370should use an OS that fully supports Message Signaled Interrupts (MSI) and make 371sure that MSI is enabled in your system's BIOS. 372 373 374There are known performance issues with this driver when running UDP traffic 375with Jumbo Frames. 376---------------------------------------------------------------------------- 377 378 37982541/82547 can't link or is slow to link with some link partners 380----------------------------------------------------------------- 381There is a known compatibility issue where time to link is slow or link is not 382established between 82541/82547 controllers and some switches. Known switches 383include: 384 Planex FXG-08TE 385 I-O Data ETG-SH8 386 387The driver can be compiled with the following changes: 388 389 Edit ./em.x.x.x/src/if_em.h to change the #define EM_MASTER_SLAVE 390 391For example, change from: 392 393 #define EM_MASTER_SLAVE e1000_ms_hw_default 394 395to: 396 397 #define EM_MASTER_SLAVE 2 398 399Use one of the following options: 400 1 = Master mode 401 2 = Slave mode 402 3 = Auto master/slave 403Setting 2 is recommended. 404 405Recompile the module: 406 a. To compile the module 407 cd em-x.x.x 408 make clean 409 make 410 b. To install the compiled module in system directory: 411 make install 412 413 414Support 415======= 416For general information, go to the Intel support website at: 417http://www.intel.com/support/ 418 419If an issue is identified with the released source code on a supported kernel 420with a supported adapter, email the specific information related to the issue 421to freebsd@intel.com 422 423 424Copyright(c) 1999-2019 Intel Corporation. 425 426 427Trademarks 428========== 429Intel is a trademark or registered trademark of Intel Corporation or its 430subsidiaries in the United States and/or other countries. 431 432* Other names and brands may be claimed as the property of others. 433