Ethernet Port Configuration Tool ========================================= July 12, 2022 Contents ======== - OVERVIEW - SUPPORTED OPERATING SYSTEMS - RUNNING THE UTILITY - OPTIONS - BASIC USAGE EXAMPLE - EXIT CODES - TROUBLESHOOTING - INSTALLATION - CUSTOMER SUPPORT - LEGAL OVERVIEW ======== The Ethernet Port Configuration Tool (EPCT) is a command line utility that allows users to change the link type of a device. The supported types are defined within the adapter's NVM. This utility displays only the devices that potentially support reconfiguration. NOTE: A reboot is required to apply configuration changes. On systems running Oracle* Solaris* 11, you must perform a full reboot, not a fast reboot. NOTE: You may lose link if you change the link type of your device from any port option that contains three to seven ports to a port option that enables multi-lane interfaces, such as 2x100G, 2x50G or 1x100G. One of the following methods may resolve the issue: - Use the utility to change the port option to 8x10G; reboot your system; change to your originally desired configuration. - Completely power cycle your system. NOTE: If the tool displays an error such as "Access error" or "Cannot initialize port" you may be using an outdated driver. Please download the latest driver from https://support.intel.com and try again. NOTE: If the tool displays the error: "Unable to load the driver. Please close all other applications and try again", you have a mix of old and new versions of the utility tool on your system. Quit all open applications and retry your operation. If the issue persists: 1. Download the latest version of the utility tools. 2. Run the uninstall script to remove the old version of the tool driver. 3. Run the install script from the downloaded tools package. 4. Retry your operation. You may also need to download and install the latest Intel Ethernet driver or Intel PROSet package for your device. Supported Operating Systems --------------------------- Microsoft Windows Server* Linux* Kernel Red Hat* Enterprise Linux* SUSE* Linux Enterprise Server UEFI Oracle* Solaris* VMWare* ESXi* FreeBSD Notes: - On systems running Linux, FreeBSD, Solaris, or ESXi, the base driver must be present for EPCT to function correctly. Intel(R) Scalable I/O Virtualization Support -------------------------------------------- Intel(R) Scalable I/O Virtualization (Intel(R) Scalable IOV) allows you to share a physical device across multiple virtual machines and applications. Intel Scalable IOV provides your system the ability to share device resources with different address domains using different abstractions. For example, application processes may access a device using system calls and VMs may access a device through virtual device interfaces. Intel Scalable IOV and SR-IOV (Single Root I/O Virtualization) are mutually exclusive. If both are enabled on your system, and all of the Intel Scalable IOV requirements are met, the PF driver will use Intel Scalable IOV. If the Intel Scalable IOV requirements are not met, the PF driver will use SR-IOV. For more information, please refer to the Intel Scalable I/O Virtualization Technical Specification (login required) Intel(R) Scalable IOV is not available in the kernel driver. Download and install the current Linux ice driver to use this feature. Refer to the SUPPORT section for where to download the current driver. Requirements ------------ * Your system platform must support Intel Scalable IOV * A network device based on an Intel(R) Ethernet 800 Series controller * The host operating system must be a Linux distro using kernel version 5.12 - 5.15 * The host PF driver must be version 1.9.0, or later * The guest operating system must be Linux * The guest iAVF driver must be version 4.5.0, or later Enabling Intel Scalable IOV --------------------------- You can use Intel's Ethernet Port Configuration Tool (EPCT) to enable Intel Scalable IOV. If the EPCT tool is not available, you can also enable Intel Scalable IOV through your system's HII interface (if it has one). The recommended method is to use the EPCT tool. To enable or disable Intel Scalable IOV using the EPCT tool, use one of these commands: #epct -nic=1 -set 'siov enable' #epct -nic=1 -set 'siov disable' Where -nic=1 specifies the Intel Ethernet device. See the EPCT tool documentation for instructions on how to determine the NIC number of your device. If the EPCT tool is not available, and your system has an HII interface, you can use the HII interface to enable/disable Intel Scalable IOV. Find the 'Intel Scalable IOV (Scalable IOV)' setting and select your desired value. RUNNING THE UTILITY =================== Using the "/?" option will display a list of supported command line options. OPTIONS ------- The Ethernet Port Configuration Tool can be run with any of the following command line options. NOTE: The slash '/' character can be used in place of the dash '-' character. NOTE: All options are case-sensitive. -h -help -? Displays command line help. -h (parameter) -help (parameter) -? (parameter) Displays help for the specified parameter. -devices [branding] (option) Displays supported devices present in the system. If 'branding' is specified, then the branding view is displayed. If an option is specified, the value for that setting is also displayed. Options for -devices are: * siov -- Displays the status of Intel Scalable IOV * tx_balancing -- Displays the device's transmit balancing setting -get (option) Displays the configuration for the specified option on the device specified by -nic. If an option is not specified, -get displays the port configuration for the specified device. "Active" indicates the currently used configuration. "Pending" indicates that the configuration the device will use after the system reboots. Options for -get are: * siov -- Displays the status of Intel Scalable IOV * tx_balancing -- Displays the device's transmit balancing setting -location Specify a device for this instance of the tool to update. SS is the PCI segment of the desired device. BBB is the PCI bus of the desired device. Do not specify -nic in the same command as -location. -nic=(device_index) Selects the device at the specified index. Do not specify -location in the same command as -nic. -set (option) Configures the selected device with the specified option. Options for -set are: * 'siov enable|disable' -- Enables or disables Intel Scalable IOV * 'tx_balancing enable|disable' -- Enables or disables the transmit balancing feature, to improve transmit performance * A port configuration string defined as: QxPxS - if all port speeds are the same across both quads and all lines, or P1xS1-P2xS2 - if each quad has a specific speed, or P11xS11+<...>+P1nxS1n-P21xS21+<...>+P2mxS2m Where: Q - The desired quad number P - The desired port number S - The desired port speed n - The desired port/speed combination for quad 0 m - The desired port/speed combination for quad 1 NOTE: A reboot is required after changing the port settings. Basic Usage Examples ==================== NOTE: Some configurations shown in the examples below may not apply to all adapters. The following examples show the tool's -devices option, the -get option, and the -set option. -devices -------- >epct -devices NIC Seg:Bus:Fun Ven-Dev Connector Ports Speed Quads Lanes per PF === ============= ========= ========= ===== ======== ====== ============ 1) 000:012 8086-1583 QSFP 2 50 Gbps Single 1 2) 000:015 8086-1584 QSFP 4 25 Gbps Single 1 3) 000:017 8086-1589 SFP 4 25 Gbps Single 1 4) 000:030:00-01 8086-1588 QSFP 2 25 Gbps Single 1 000:030:02-05 8086-1587 QSFP 4 10 Gbps Single 1 >epct -devices branding NIC Seg:Bus Ven-Dev Mode Adapter Name === ======= ========= =========== ============================================= 1) 000:012 8086-1583 N/A Intel(R) Ethernet Converged Network Adapter XL710 2) 000:029 8086-1583 4x10 Intel(R) Ethernet Converged Network Adapter XL710 3) 000:129 8086-1599 2x25,2x10- Intel(R) Ethernet Controller E810-XXV for 2x10 backplane 4) 000:132 8086-159A 2x50 Intel(R) Ethernet Controller E810-XXV for QSFP -get ---- >epct -nic=1 -get Available Port Options: ========================================================================== Port Quad 0 Quad 1 Option Option (Gbps) L0 L1 L2 L3 L4 L5 L6 L7 ======= ============================= ================ ================ 4x25 -> 25 25 25 25 - - - - 2x1x100 -> 100 - - - 100 - - - Active 2x2x25 -> 25 25 - - 25 25 - - 2x50 -> 50 - 50 - - - - - Pending 2x1x50 -> 50 - - - 50 - - - 2x4x10 -> 10 10 10 10 10 10 10 10 2x25+2x10-2x10 -> 25 25 10 10 10 10 - - 1x10+1x25+1x10+1x25-2x10 -> 10 25 10 25 10 10 - - To display the current setting for the transmit balancing feature on a specific device: >epct -nic=1 -get tx_balancing -set ---- To set two ports to 50 Gbps. First port starts with lane L0 in quad 0 and second with lane L4 in quad 1: >epct -nic=1 -set 2x1x50 To set 1st and 2nd ports to 25Gbps (respectively lanes L0 and L1 in quad 0), 3rd and 4th port to 10Gbps (respectively lanes L2 and L3 in quad 0), 5th and 6th port to 10Gbps (respectively lanes L4 and L5 in quad 1): >epct -nic=1 -set 2x25+2x10-2x10 To enable the transmit balancing feature on a specific device: >epct -nic=1 -set 'tx_balancing enable' NOTE: A reboot is required after changing the port settings. Exit Codes ========== Upon exit, when possible, the EPCT reports an overall status code to indicate the results of the operation. In general, a non-zero return code indicates an error occurred during processing. Value Description 0 Success. 1 No supported adapter found. 2 Insufficient privileges to run the tool. 3 No driver available. 4 Unsupported base driver version. 5 Bad command line parameter. 6 Invalid adapter selected. 7 Unsupported ports configuration selected. 8 Adapter does not support ports configuration. 9 Memory allocation error. 10 Adapter access error. 13 Cannot set new port option. Pending reboot detected. 14 The device is in recovery mode. 15 The requested feature is not supported on this device. You may get this error if your system/device/operating system combination does not support the option you tried to set. NOTE: EFI versions of this tool may report an incorrect error code when no adapter is installed. This is due to a known limitation in the UDK2015 UEFI Development Kit (UDK) build environment. TROUBLESHOOTING =============== Issues with breakout cables --------------------------- Use of the 4x25 quad breakout or 1x100 port option will only work on Port 2 of Intel(R) Ethernet Network Adapter E810-C-Q2 products. Unexpected PF mapping --------------------- Physical Function (PF) to physical lane mapping is dependent upon the hardware and may change across different MAC port options. This may be most noticeable when using a breakout cable, in which case the labeling on the cable may not align with the device port assignment. For example, inserting a 4-port breakout cable into either QSFP cage and configuring the device in 2x2x25 mode may result in the two active PFs being assigned to the third and fourth cables of the breakout connector. Possible misconfiguration of the Ethernet port ---------------------------------------------- You may see an informational message stating that a potential misconfiguration of the Ethernet port was detected. This is to alert you that your device is being underutilized. If this was intentional, you may ignore this message. For example, setting your Intel(R) Ethernet Network Adapter E810-C-Q2 to 2x2x25 is valid, but it does not use the full capabilities of the device. If you see this message, and the configuration was not intentional, you may use EPCT to correct the configuration. INSTALLATION ============= Installing the tool on Microsoft* Windows* ------------------------------------------ To install the tools' drivers on Windows, run install.bat from the appropriate directory of the install package. Although the tools are not installed with install.bat, the driver that the tool requires is copied into the local machine Windows driver directory. To run the tool, launch a Command Prompt window from the Windows Start Menu. Go to the media and directory where the tool is located and run the utility. The readme files for each tool are found in the same directory as the tool. These tools can be manually installed on the local hard drive in any directory. The tool uses its own driver file (not the same as the system network driver). If the driver sys file already exists in the drivers directory, install.bat may fail to copy. Using the /y switch with install.bat will override and copy the driver file regardless. However, this can be dangerous if an older version of the driver is being used by another application such as Intel(R) PROSet for Windows Device Manager. If a driver is already present in the drivers directory, try running the tool from the command prompt. If it runs, then the driver is fine. The tool will not run if the driver version present does not match the driver version expected. Note that you must have access to the %systemroot%\system32\drivers directory. Only the administrator account has these privileges. You must be logged in as administrator or the tools must be run as administrator. Note that on Windows, any device that is disabled in Device Manager will not be accessible by tools due to no memory resources. You would get an error code 0xC86A800E. To solve this problem, you can do one of the following: 1) Re-enable the device in Device Manager. Never disable this device when using tools. 2) Install an NDIS device driver for the device and make sure that it does not have a yellow or red bang by it in Device Manager. 3) Delete the device from Device Manager and restart the system. The install new hardware wizard should appear on next reboot. Do not cancel this. Just move the window aside and run the tool(s). Generally, you can click "cancel" on the wizard but there are some cases where Windows will disable the memory resources, causing you to get back into the same state. Installing the tool on EFI -------------------------- The EFI 1.x tools are not supported in this release. There is no installation required for EFI tools. The tools can simply be copied from the appropriate directory to the drive that they will run from. The EFI2 binaries are for use with the UEFI Shell 2.X with the UEFI 2.3 HII protocol. EFI2 tools will not run on the EFI Shell 1.X or if the UEFI 2.3 HII protocol is not present. Note that while EFI supports USB drives, there may be issues running tools from the USB drive. Whether or not there are issues are BIOS specific. If you experience issues, run the tool from hard disk instead. Installing the tool on Linux* ---------------------------- In order to run this tool on Linux*, the base driver must be installed on the system. INSTALLING THE TOOL ON VMWare* ESXi* ----------------------------------- In order to run this tool on VMWare* ESXi*, the base driver must be installed on the system. For security purposes, VMWare ESXi 8.0, and later, prevents you from running binaries that were not installed from a vib file. To run this tool, you must first run: vsish -e set /config/User/intOpts/ExecInstalledOnly 0 If you continue to get an error, you may need to set: esxcli system settings kernel set -s execInstalledOnly -v false We recommend that you change ExecInstalledOnly back to 1 when you are finished running this tool. INSTALLING THE TOOL ON FreeBSD* ------------------------------ In order to run this tool on FreeBSD*, the base driver must be installed on the system. CUSTOMER SUPPORT ================ - Main Intel web support site: http://support.intel.com - Network products information: http://www.intel.com/network Intel Wired Networking project hosted by Sourceforge: http://sourceforge.net/projects/e1000 LEGAL / DISCLAIMERS =================== Copyright (C) 2019 - 2022, Intel Corporation. All rights reserved. This software and the related documents are Intel copyrighted materials, and your use of them is governed by the express license under which they were provided to you ("License"). Unless the License provides otherwise, you may not use, modify, copy, publish, distribute, disclose or transmit this software or the related documents without Intel's prior written permission. This software and the related documents are provided as is, with no express or implied warranties, other than those that are expressly stated in the License. Intel technologies may require enabled hardware, software or service activation. No product or component can be absolutely secure. Your costs and results may vary. Intel, the Intel logo, and other Intel marks are trademarks of Intel Corporation or its subsidiaries. *Other names and brands may be claimed as the property of others.