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