| FreeBSD* Driver for Intel(R) Ethernet |
| ===================================== |
| |
| August 7, 2019 |
| |
| Contents |
| ======== |
| |
| - Overview |
| - Identifying Your Adapter |
| - Building and Installation |
| - Additional Features and Configurations |
| - Known Issues/Troubleshooting |
| - Support |
| - License |
| |
| |
| Overview |
| ======== |
| This file describes the FreeBSD* driver for Intel(R) Ethernet. This driver has |
| been developed for use with all community-supported versions of FreeBSD. |
| |
| For questions related to hardware requirements, refer to the documentation |
| supplied with your Intel Ethernet Adapter. All hardware requirements listed |
| apply to use with FreeBSD. |
| |
| |
| Identifying Your Adapter |
| ======================== |
| This release includes two gigabit FreeBSD base Drivers for Intel(R) Ethernet. |
| These drivers are em and igb. |
| |
| - The igb driver supports all 82575 and 82576-based gigabit network connections. |
| - The em driver supports all other gigabit network connections. |
| - Gigabit devices base on the Intel(R) Ethernet Controller X722 are supported by |
| the ixl driver. |
| |
| NOTE: The Intel(R) 82562v 10/100 Network Connection only provides 10/100 |
| support. |
| |
| For information on how to identify your adapter, and for the latest Intel |
| network drivers, refer to the Intel Support website: |
| http://www.intel.com/support |
| |
| |
| Building and Installation |
| ========================= |
| NOTE: This driver package is to be used only as a standalone archive and the |
| user should not attempt to incorporate it into the kernel source tree. |
| |
| In the instructions below, x.x.x is the driver version as indicated in the name |
| of the driver tar file. |
| |
| 1. Move the base driver tar file to the directory of your choice. For |
| example, use /home/username/em or /usr/local/src/em. |
| |
| 2. Untar/unzip the archive: |
| |
| # tar xzf em-x.x.x.tar.gz |
| |
| This will create the em-x.x.x directory. |
| |
| 3. To install man page: |
| |
| # cd em-x.x.x |
| # gzip -c em.4 > /usr/share/man/man4/em.4.gz |
| |
| 4. To load the driver onto a running system: |
| |
| # cd em-x.x.x/src |
| # make |
| # kldload ./if_em.ko |
| |
| 5. To assign an IP address to the interface, enter the following: |
| |
| # ifconfig em<interface_num> <IP_address> |
| |
| 6. Verify that the interface works. Enter the following, where <IP_address> |
| is the IP address for another machine on the same subnet as the interface |
| that is being tested: |
| |
| # ping <IP_address> |
| |
| 7. If you want the driver to load automatically when the system is booted: |
| |
| # cd em-x.x.x/src |
| # make |
| # make install |
| |
| Edit /boot/loader.conf, and add the following line: |
| if_em_load="YES" |
| |
| Edit /etc/rc.conf, and create the appropriate ifconfig_em<interface_num> entry: |
| |
| ifconfig_em<interface_num>="<ifconfig_settings>" |
| |
| Example usage: |
| ifconfig_em0="inet 192.168.10.1 netmask 255.255.255.0" |
| |
| NOTE: For assistance, see the ifconfig man page. |
| |
| |
| Additional Features and Configurations |
| ====================================== |
| |
| Speed and Duplex Configuration |
| ------------------------------ |
| In addressing speed and duplex configuration issues, you need to distinguish |
| between copper-based adapters and fiber-based adapters. |
| |
| In the default mode, an Intel(R) Ethernet Network Adapter using copper |
| connections will attempt to auto-negotiate with its link partner to determine |
| the best setting. If the adapter cannot establish link with the link partner |
| using auto-negotiation, you may need to manually configure the adapter and link |
| partner to identical settings to establish link and pass packets. This should |
| only be needed when attempting to link with an older switch that does not |
| support auto-negotiation or one that has been forced to a specific speed or |
| duplex mode. Your link partner must match the setting you choose. 1 Gbps speeds |
| and higher cannot be forced. Use the autonegotiation advertising setting to |
| manually set devices for 1 Gbps and higher. |
| |
| Caution: Only experienced network administrators should force speed and duplex |
| or change autonegotiation advertising manually. The settings at the switch must |
| always match the adapter settings. Adapter performance may suffer or your |
| adapter may not operate if you configure the adapter differently from your |
| switch. |
| |
| An Intel(R) Ethernet Network Adapter using fiber-based connections, however, |
| will not attempt to auto-negotiate with its link partner since those adapters |
| operate only in full duplex and only at their native speed. |
| |
| By default, the adapter auto-negotiates the speed and duplex of the connection. |
| If there is a specific need, the ifconfig utility can be used to configure the |
| speed and duplex settings on the adapter. |
| |
| Example usage: |
| |
| # ifconfig emX <IP_address> media 100baseTX mediaopt full-duplex |
| |
| NOTE: Only use mediaopt to set the driver to full-duplex. If mediaopt is not |
| specified and you are not running at gigabit speed, the driver defaults to |
| half-duplex. |
| |
| If the interface is currently forced to 100 full duplex, you must use this |
| command to change to half duplex: |
| |
| # ifconfig emX <IP_address> media 100baseTX -mediaopt full-duplex |
| |
| This driver supports the following media type options: |
| |
| Media Type Description |
| ---------- ----------- |
| autoselect Enables auto-negotiation for speed and duplex. |
| 10baseT/UTP Sets speed to 10 Mbps. Use the ifconfig mediaopt |
| option to select full-duplex mode. |
| 100baseTX Sets speed to 100 Mbps. Use the ifconfig mediaopt |
| option to select full-duplex mode. |
| 1000baseTX Sets speed to 1000 Mbps. In this case, the driver |
| supports only full-duplex mode. |
| 1000baseSX Sets speed to 1000 Mbps. In this case, the driver |
| supports only full-duplex mode. |
| |
| For more information on the ifconfig utility, see the ifconfig man page. |
| |
| Jumbo Frames |
| ------------ |
| Jumbo Frames support is enabled by changing the Maximum Transmission Unit (MTU) |
| to a value larger than the default value of 1500. |
| |
| Use the ifconfig command to increase the MTU size. For example, enter the |
| following where X is the interface number: |
| |
| # ifconfig emX mtu 9000 |
| |
| To confirm an interface's MTU value, use the ifconfig command. |
| |
| To confirm the MTU used between two specific devices, use: |
| |
| # route get <destination_IP_address> |
| |
| NOTE: The maximum MTU setting for Jumbo Frames is 16110. This value coincides |
| with the maximum Jumbo Frames size of 16132 bytes. |
| |
| NOTE: Using Jumbo frames at 10 or 100 Mbps is not supported and may result in |
| poor performance or loss of link. |
| |
| NOTE: Packet loss may have a greater impact on throughput when you use jumbo |
| frames. If you observe a drop in performance after enabling jumbo frames, |
| enabling flow control may mitigate the issue. |
| |
| NOTE: Some Intel gigabit adapters that support Jumbo Frames have a frame size |
| limit of 9238 bytes, with a corresponding MTU size limit of 9216 bytes. The |
| adapters with this limitation are based on the Intel(R) 82571EB, 82572EI, |
| 82573L, 82566, 82562, and 80003ES2LAN controller. These correspond to the |
| following product names: |
| Intel(R) PRO/1000 PT Server Adapter |
| Intel(R) PRO/1000 PT Desktop Adapter |
| Intel(R) PRO/1000 PT Network Connection |
| Intel(R) PRO/1000 PT Dual Port Server Adapter |
| Intel(R) PRO/1000 PT Dual Port Network Connection |
| Intel(R) PRO/1000 PT Quad Port Server Adapter |
| Intel(R) PRO/1000 PF Quad Port Server Adapter |
| Intel(R) PRO/1000 PF Server Adapter |
| Intel(R) PRO/1000 PF Network Connection |
| Intel(R) PRO/1000 PF Dual Port Server Adapter |
| Intel(R) PRO/1000 PB Server Connection |
| Intel(R) PRO/1000 PL Network Connection |
| Intel(R) PRO/1000 EB Network Connection with I/O Acceleration |
| Intel(R) PRO/1000 EB Backplane Connection with I/O Acceleration |
| Intel(R) 82566DM-2 Gigabit Network Connection |
| Intel(R) 82574L Gigabit Network Connection |
| Intel(R) Gigabit CT Desktop Adapter |
| Intel(R) 82567LM-4 Gigabit Network Connection |
| Intel(R) 82567LM-3 Gigabit Network Connection |
| Intel(R) 82567LF-3 Gigabit Network Connection |
| |
| NOTE: The following adapters limit Jumbo Frames sized packets to a maximum of |
| 4088 bytes: |
| - Intel(R) 82578DM Gigabit Network Connection |
| - Intel(R) 82577LM Gigabit Network Connection |
| - The following adapters do not support Jumbo Frames: |
| - Intel(R) PRO/1000 Gigabit Server Adapter |
| - Intel(R) PRO/1000 PM Network Connection |
| - Intel(R) 82562G 10/100 Network Connection |
| - Intel(R) 82562G-2 10/100 Network Connection |
| - Intel(R) 82562GT 10/100 Network Connection |
| - Intel(R) 82562GT-2 10/100 Network Connection |
| - Intel(R) 82562V 10/100 Network Connection |
| - Intel(R) 82562V-2 10/100 Network Connection |
| - Intel(R) 82566DC Gigabit Network Connection |
| - Intel(R) 82566DC-2 Gigabit Network Connection |
| - Intel(R) 82566DM Gigabit Network Connection |
| - Intel(R) 82566MC Gigabit Network Connection |
| - Intel(R) 82566MM Gigabit Network Connection |
| - Intel(R) 82567V-3 Gigabit Network Connection |
| - Intel(R) 82577LC Gigabit Network Connection |
| - Intel(R) 82578DC Gigabit Network Connection |
| - Jumbo Frames cannot be configured on an 82579-based Network device if |
| MACSec is enabled on the system. |
| |
| |
| VLANS |
| ----- |
| To create a new VLAN interface: |
| |
| # ifconfig <vlan_name> create |
| |
| To associate the VLAN interface with a physical interface and assign a VLAN ID, |
| IP address, and netmask: |
| |
| # ifconfig <vlan_name> <ip_address> netmask <subnet_mask> vlan <vlan_id> |
| vlandev <physical_interface> |
| |
| Example: |
| |
| # ifconfig vlan10 10.0.0.1 netmask 255.255.255.0 vlan 10 vlandev em0 |
| |
| In this example, all packets will be marked on egress with 802.1Q VLAN tags, |
| specifying a VLAN ID of 10. |
| |
| To remove a VLAN interface: |
| |
| # ifconfig <vlan_name> destroy |
| |
| |
| Polling |
| ------- |
| NOTES: |
| - Device Polling is only valid for non-SMP kernels. |
| - The driver has to be built into the kernel for Device Polling to be |
| enabled in the driver. |
| |
| To enable polling in the driver, add the following options to the kernel |
| configuration, and then recompile the kernel: |
| |
| options DEVICE_POLLING |
| options HZ=1000 |
| |
| At runtime use: |
| ifconfig emX polling (to turn polling on) |
| and: |
| ifconfig emX -polling (to turn it off) |
| |
| |
| Checksum Offload |
| ---------------- |
| Checksum offloading is not supported on 82542 Gigabit adapters. |
| |
| Checksum offloading supports both TCP and UDP packets and is supported for both |
| transmit and receive. |
| |
| Checksum offloading can be enabled or disabled using ifconfig. Both transmit |
| and receive offloading will be either enabled or disabled together. You cannot |
| enable/disable one without the other. |
| |
| To enable checksum offloading: |
| |
| # ifconfig emX rxcsum |
| |
| To disable checksum offloading: |
| |
| # ifconfig emX -rxcsum |
| |
| To confirm the current setting: |
| |
| # ifconfig emX |
| |
| Look for the presence or absence of the following line: |
| options=3 <RXCSUM,TXCSUM> |
| |
| See the ifconfig man page for further information. |
| |
| |
| TSO |
| --- |
| TSO (TCP Segmentation Offload) supports both IPv4 and IPv6. TSO can be disabled |
| and enabled using the ifconfig utility or sysctl. |
| |
| NOTE: TSO requires Tx checksum, if Tx checksum is disabled, TSO will also be |
| disabled. |
| |
| NOTE: By default only PCI-Express adapters are ENABLED to do TSO. Others can be |
| enabled by the user at their own risk. TSO is not supported on 82547 or |
| 82544-based adapters, as well as older adapters. |
| |
| To enable/disable TSO in the stack: |
| |
| # sysctl net.inet.tcp.tso=0 (or 1 to enable it) |
| |
| Doing this disables/enables TSO in the stack and affects all installed adapters. |
| |
| To disable BOTH TSO IPv4 and IPv6: |
| |
| # ifconfig em<interface_num> -tso |
| |
| To enable BOTH TSO IPv4 and IPv6: |
| |
| # ifconfig em<interface_num> tso |
| |
| You can also enable/disable IPv4 TSO or IPv6 TSO individually. Simply replace |
| tso|-tso in the above command with tso4 or tso6. For example, to disable |
| TSO IPv4: |
| |
| # ifconfig em<interface_num> -tso4 |
| |
| To disable TSO IPv6: |
| |
| # ifconfig em<interface_num> -tso6 |
| |
| |
| MSI-X |
| ----- |
| MSI or MSI-X can be turned off by an entry in /etc/sysctl.conf |
| |
| hw.em.enable_msi=0 |
| |
| Unload and reload the driver. |
| |
| |
| Known Issues/Troubleshooting |
| ============================ |
| |
| Detected Tx Unit Hang in Quad Port Adapters |
| ------------------------------------------- |
| In some cases ports 3 and 4 don't pass traffic and report 'Detected Tx Unit |
| Hang' followed by 'NETDEV WATCHDOG: emX: transmit timed out' errors. Ports 1 |
| and 2 do not show any errors and will pass traffic. |
| |
| This issue may be resolved by updating to the latest kernel and BIOS. You |
| should use an OS that fully supports Message Signaled Interrupts (MSI) and make |
| sure that MSI is enabled in your system's BIOS. |
| |
| |
| There are known performance issues with this driver when running UDP traffic |
| with Jumbo Frames. |
| ---------------------------------------------------------------------------- |
| |
| |
| 82541/82547 can't link or is slow to link with some link partners |
| ----------------------------------------------------------------- |
| There is a known compatibility issue where time to link is slow or link is not |
| established between 82541/82547 controllers and some switches. Known switches |
| include: |
| Planex FXG-08TE |
| I-O Data ETG-SH8 |
| |
| The driver can be compiled with the following changes: |
| |
| Edit ./em.x.x.x/src/if_em.h to change the #define EM_MASTER_SLAVE |
| |
| For example, change from: |
| |
| #define EM_MASTER_SLAVE e1000_ms_hw_default |
| |
| to: |
| |
| #define EM_MASTER_SLAVE 2 |
| |
| Use one of the following options: |
| 1 = Master mode |
| 2 = Slave mode |
| 3 = Auto master/slave |
| Setting 2 is recommended. |
| |
| Recompile the module: |
| a. To compile the module |
| cd em-x.x.x |
| make clean |
| make |
| b. To install the compiled module in system directory: |
| make install |
| |
| |
| Support |
| ======= |
| For general information, go to the Intel support website at: |
| http://www.intel.com/support/ |
| |
| If an issue is identified with the released source code on a supported kernel |
| with a supported adapter, email the specific information related to the issue |
| to freebsd@intel.com |
| |
| |
| Copyright(c) 1999-2019 Intel Corporation. |
| |
| |
| Trademarks |
| ========== |
| Intel is a trademark or registered trademark of Intel Corporation or its |
| subsidiaries in the United States and/or other countries. |
| |
| * Other names and brands may be claimed as the property of others. |