Ethernet Port Configuration Tool (EPCT)
***************************************

July 02, 2024


Contents
^^^^^^^^

* Ethernet Port Configuration Tool (EPCT)

  * Overview

    * Supported Operating Systems

    * Intel® Scalable I/O Virtualization Support

  * Installation

  * Running the Utility

    * Basic Usage Examples

    * Options

    * Detailed Usage Examples

  * Exit Codes

  * Troubleshooting

    * Issues with breakout cables

    * Unexpected PF mapping

    * Possible misconfiguration of the Ethernet port


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.

  * 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.

  * 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.


Supported Operating Systems
---------------------------

* Microsoft Windows Server*

* Linux* Kernel

* Red Hat* Enterprise Linux*

* SUSE* Linux Enterprise Server

* UEFI

* VMware* ESXi*

* FreeBSD

Note:

  On systems running Linux, FreeBSD, or ESXi, the base driver must be
  present for EPCT to function correctly.


Intel® Scalable I/O Virtualization Support
------------------------------------------

Intel® Scalable I/O Virtualization (Intel® Scalable IOV) allows you to
share a physical device across multiple virtual machines and
applications. See Intel® Scalable I/O Virtualization Support in the
user guide for an explanation of this feature.

You can use this Ethernet Port Configuration Tool (EPCT) to enable
Intel Scalable IOV. If EPCT 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'

or:

   epct -nic=1 -set 'siov disable'

Where "-nic=1" specifies the Intel Ethernet device.


Installation
============

See Installing and Uninstalling Intel® Network Connection Tools for
installation instructions.


Running the Utility
===================

Use the following syntax to run EPCT:

   epct [options]

Using the "/?" option will display a list of supported command line
options.

See Options below for this tool's supported parameters.

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.


Basic Usage Examples
--------------------

The following show some basic usage examples for EPCT:

   epct -devices

   epct -devices branding

   epct -nic=1 -get

   epct -nic=1 -set 2x1x50

   epct -help

See Detailed Usage Examples below for additional examples.


Options
-------

The Ethernet Port Configuration Tool can be run with any of the
following command line options.

Note:

  * You can use the slash "/" character in place of the dash "-"
    character.

  * All options are case-sensitive.

-h, -help, -?
   Displays help for the command or the parameter.

   You can also use the following to display help for the specified
   parameter:

      -h <parameter name>
      -help <parameter name>
      -? <parameter name>

-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.

   Possible values for "<option>" 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 the configuration the device will use after
     the system reboots.

   Possible values for "<option>" are:

      siov:
         Displays the status of Intel Scalable IOV.

      tx_balancing:
         Displays the device's transmit balancing setting.

      max_pwr:
         Displays the maximum power options of the QSFP/SFP cages.

   See -get Examples below for example usage of this option.

-location <SS:BBB>
   Specify a device for this instance of the tool to update, where
   "<SS:BB>" means:

      SS:
         The PCI segment of the desired device.

      BBB:
         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. Valid
   values for "<option>" 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.

      max_pwr X:
         Sets the maximum allowed power to "X" for the QSFP/SFP cage.

      <port configuration string>:
         Specifies the configuration to set for the desired quad,
         port, or speed.

         A port configuration string is 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.

           For example:

              epct -nic=1 -set 2x25+2x10-2x10

   See -set Examples below for example usage of these options.

   Note:

     A reboot is required after changing the port settings.


Detailed 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 Examples
~~~~~~~~~~~~~~~~~

Typing the following at the prompt:

   epct -devices

Will display:

   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

The following shows how to use the "branding" option:

   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 Examples
~~~~~~~~~~~~~

Typing the following at the prompt:

   epct -nic=1 -get

Will display:

   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

To display the minimum and maximum power allowed for the QSFP/SFP cage
on a specific device:

   epct -nic=1 -get max_pwr

For example, the above will display:

   Seg:Bus:Fun    Ven-Dev      MIN PWR ALLOWED    MAX PWR ALLOWED    MAX PWR SET
   ===========    =======      ===============    ===============    ===========
   000:012        8086-1583    1                  5.5                3.5


-set Examples
~~~~~~~~~~~~~

To set two ports to 50Gbps (first port starts with lane L0 in quad 0
and second with lane L4 in quad 1):

   epct -nic=1 -set 2x1x50

To set the first and second ports to 25Gbps (respectively lanes L0 and
L1 in quad 0), the third and fourth port to 10Gbps (respectively lanes
L2 and L3 in quad 0), and the fifth and sixth 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'

To set the maximum allowed power for a QSFP cage:

   epct -nic=1 -cage=2 -set 'max_pwr 2.5'

Note:

  * A reboot is required after changing the port settings.

  * In Windows, you must use double quotation marks instead of single
    quotation marks. For example:

       epct -nic=1 -set "tx_balancing enable"
       epct -nic=1 -cage=2 -set "max_pwr 2.5"


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.                                   |
+------------+------------------------------------------------------------------------+
| 25         | Setting value is out of range                                          |
+------------+------------------------------------------------------------------------+

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® 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® 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.


Legal / Disclaimers
===================

Copyright (C) 2019 - 2024, Intel Corporation. All rights reserved.

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.

Performance varies by use, configuration, and other factors. Learn
more at https://www.Intel.com/PerformanceIndex.

The products described may contain design defects or errors known as
errata which may cause the product to deviate from published
specifications. Current characterized errata are available on request.

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.