GT MAC test case description

The goal of this test case is to allow verification of GT transceivers on Alveo™ cards at 10GbE and 25GbE lane rates. Each GT transceiver supports 4 lanes.

This xbtest hardware IP (xbtIP) instantiates the 10G/25G High Speed Ethernet Subsystem IP core (see 10G/25G High speed ethernet subsystem product guide (PG210)) and allows the core to be configured from a Test JSON file. GT MAC traffic is layer 2 type traffic:

  • Ethertype: 0x88b5, local traffic only.

  • Source and Destination MAC addresses are inserted.

  • No IP address is present as there is no layer 3.

In case of multiple xbtIP, the rate can be select individually per xbtIP, but the selected rate applies to the 4 lanes of the xbtIP.

The xbtIP includes a packet generator, which allows a card with simple electrical or optical loopback cables to generate packets. The xbtIP also verify that the generated packets have been received back, error free. The packet generator can be configured for each lane individually.

The xbtIP also includes a sets of packet counters, which counts, per lane, the quantity of packets and bytes transmitted and received with the expected source and destination MAC addresses.

../../../../../_images/gt_mac-block_diagram.svg

GT MAC xbtest hardware IP block diagram

GT test set up

GT testing can be achieved by using one of the following methods.

  • Loopback electrical or optical:

    • The use of a QSFP passive electrical loopback module. The module must be compliant to 100GbE (25GbE per lane) and have 0 dB insertion loss. This is the preferred method, the GTs having been validated using a QSFP28 module provided by MultiLane (ML4002-28-C5).

      Note

      This module also has the capability of providing a QSFP temperature reading and a programmable power dissipation up to 5W. However, these are not required to pass the GT tests.

    • The use of a QSFP optical module with suitably connected fiber loopback. The module must be compatible with the traffic rate being tested.

      Note

      This is an active component the electrical interface between the GTs and the module will need to be validated to ensure optimum performance.

  • Connected to a switch

  • Connected to another GT MAC xbtest hardware IP (xbtIP) present on the same board

  • The use of a protocol analyzer with a compatible electrical or optical interface. This is the most complex method of connection as not only will the interfaces require validation with the GTs, the RX and TX paths will be independent. The test JSON file needs to be modified to reflect that the RX and TX packet/byte counts might not be the same.

Warning

The configuration of the GT MAC test case depends on the set up (see GT MAC test JSON members).

Switch set up

xbtest has been validated with the following Cisco hardware:

The following is the switch configuration:

  • port 1 - 16: 10GbE; no FEC.

  • port 17 - 32: 25GbE; clause 74 FEC.

The configuration can be obtained via the following command:

$ interface breakout module 1 port 1-16 map 10g-4x
$ interface breakout module 1 port 17-32 map 25g-4x
Example of switch port configuration

10GbE Port 1

25GbE Port 17

  • Interface Ethernet1/1/1:

    • Switchport.

    • Switchport access VLAN 3000.

    • Spanning-tree port type edge.

    • Spanning-tree bpduguard enable.

    • MTU 9216.

    • Speed 10000.

    • Duplex full.

    • No shutdown.

  • Interface Ethernet1/1/2: Identical to Ethernet1/1/1.

  • Interface Ethernet1/1/3: Identical to Ethernet1/1/1.

  • Interface Ethernet1/1/4: Identical to Ethernet1/1/1.

  • Interface Ethernet1/17/1:

    • Switchport.

    • Switchport access VLAN 3000.

    • Spanning-tree port type edge.

    • Spanning-tree bpduguard enable.

    • MTU 9216.

    • Speed 25000.

    • FEC FC-FEC

    • No shutdown.

  • Interface Ethernet1/17/2: Identical to Ethernet1/17/1.

  • Interface Ethernet1/17/3: Identical to Ethernet1/17/1.

  • Interface Ethernet1/17/4: Identical to Ethernet1/17/1.

Note

The switch port should be on their own VLAN to avoid traffic leak/broadcast.

Source MAC address

The GT MAC xbtest hardware IP (xbtIP) uses all valid source MAC addresses (one per lane). If multiple GT MAC xbtIP are present in Alveo Versal Example Design (AVED), they’ll split all valid MAC addresses in a round robin manner over all lanes of all GT MAC IPs.

Source MAC address round robin selection

MAC address index

GT/lane index

0

GT[0] Lane 0

1

GT[1] Lane 0

2

GT[0] Lane 1

3

GT[1] Lane 1

4

GT[0] Lane 2

If there are not enough valid MAC addresses, lanes will be disabled following the same round robin manner. In the table above, if MAC address index 4 is the last one available, GT[0] lane 3 and GT[1] lanes 2/3 will be disabled. It’s possible to re-organize the MAC address distribution of the GT via the source_addr option. Source MAC addresses are displayed with message ID ETH_031.

Destination MAC address - Lane mapping

The destination MAC addresses are defined via the lane mapping. By default, each lane is configured loop back to itself. So, per lane, the destination MAC address is identical to the Source MAC address. This default mapping is the one to use with loopback module as each lane is physically loopbacked to itself. Destination MAC addresses are displayed with message ID ETH_031.

When using a switch, lane traffic can’t be loopback to itself, source and destination MAC addresses must be different. xbtest only supports paired mapping lanes in order to compare RX status with TX status.

Supported lane mapping

Source

Loopback module

Switch

Default pairing

Pairing A

Pairing B

Pairing C

Lane[0]

Lane[0]

Lane[1]

Lane[2]

Lane[3]

Lane[1]

Lane[1]

Lane[0]

Lane[3]

Lane[2]

Lane[2]

Lane[2]

Lane[3]

Lane[0]

Lane[1]

Lane[3]

Lane[3]

Lane[2]

Lane[1]

Lane[0]

The mapping is defined using tx_mapping option. Here is how the switch pairing A is configured in the test JSON file:

"lane_config": {
  "0": {
    "tx_mapping": 1
  },
  "1": {
    "tx_mapping": 0
  },
  "2": {
    "tx_mapping": 3
  },
  "3": {
    "tx_mapping": 2
  }
}

Caution

When connected to switch, the lane mapping must be defined in pair in order to be able to cross check RX and TX status counters.

Although destination addresses are automatically selected based on tx_mapping, it’s possible to overwrite it with dest_addr member.

Lane enabling

For a lane to be used/enabled, it must have valid source and destination addresses:

  • When the lane is looped back to itself, this means that only one valid address is required.

  • When lanes are paired, both need to have a valid MAC Address, otherwise both will be disabled. So, if e.g. Lane[0] and Lane[3] are paired but only 1 lane gets a valid address, both lanes will be disabled.

You can overwrite lane MAC address via source_addr and dest_addr.

You can also disable a lane via disable_lane. If the disabled lane is paired, both lanes will be disabled.

Note

When you get un-expected disabled lanes, check MAC address reported by xbtest and their lane attribution (alongside the lane pairing).

GT MAC HW xbtIP to GT MAC HW xbtIP connection

When the same Alveo Versal Example Design (AVED) contains 2 GT MAC xbtIP, they can be connected via cable (or optical fibre). In this case, only one GT MAC xbtIP must have its test_sequence defined, while the other one must use mac_to_mac_connection and point it to other one index.

See GT MAC to GT MAC connection example for usage example.

GT settings

As there are multiple ways to connect to the GTs, two default configurations have been defined:

  • module: For loopback module and active optical cable. Loopback module is an electrical track from TX to RX. It’s the shortest path you can get between Tx and Rx (and still going out of the FPGA). An active optical cable terminates the electrical TX track at the optic module input. It also has the electric RX track from the optic module output. Resulting in electrical track length twice the size compared to the loopback module. From experience, it has no major impact and GT settings can be common for these 2 types (loopback module or active optical cable).

  • cable: For copper cable.

The selection is made using the gt_settings member, by default module settings are selected.

Each mode defines values for the following GT transceiver settings (see UltraScale Architecture GTY Transceivers User Guide (UG578)):

  • tx_differential_swing_control

  • tx_main_cursor

  • tx_pre_emphasis

  • tx_post_emphasis

  • gt_tx_polarity

  • gt_loopback

  • rx_equaliser

The actual values are defined in the Card definition JSON file and are also displayed in the xbtest.log file with message ID CMN_021. It’s possible to overwrite these settings for all lanes (included into global_config) or selectively for some lanes (part of lane_config).

Warning

When connected to switch, using a wrong setting for one single lane might result in traffic interruption on all lanes. The switch might try to reset its whole module because it sees that a link is down.

Main test steps

A test is generally composed of four steps and a definition of the hardware environment (see GT MAC test JSON members). The following are typical test steps:

  1. Configuration.

  2. Clear status.

  3. Run.

  4. Report/check status.

Note

Under some circumstances the packet generator might not be able to send packets at the requested rate. This is most likely to occur when operating at 25GbE and with small packets (for example < 128-bytes packet). Reducing the number of active MACs and/or increasing the packet size should allow the maximum rate to be achieved (see GT MAC test JSON members).

Warning

Test parameters

The mandatory test configuration parameters are listed below. For more information, see GT MAC test JSON members.

Status

GT MAC xbtest hardware IP (xbtIP) provides 3 kind of status/counters:

  • A subset of the status registers from the 10G/25G High Speed Ethernet Subsystem IP core (see 10G/25G High speed ethernet subsystem product guide (PG210)). Some status are reported as information (counter registers), others are checked against a null value (error register).

  • An indication that the quantity of bytes and packets transmitted is within a range based on the test duration and mode (lane rate), utilisation, and packet_cfg configurations.

  • A comparison between the quantity of packets and bytes sent by a lane and received by its destination lane. Per lane, the packet receiver checks the source and destination MAC address for each packet received. This is only enabled when match_tx_rx is set to true.

Matching TX RX

The optional parameter match_tx_rx causes comparison between some registers of the 10G/25G High Speed Ethernet Subsystem IP core:

  • RX_TOTAL_GOOD_PACKETS with TX_TOTAL_PACKETS.

  • RX_TOTAL_GOOD_BYTES with TX_TOTAL_BYTES.

The packet receiver also compares the quantity of packets and bytes sent (TX_TOTAL_PACKETS, TX_TOTAL_BYTES) with their respective received quantities when source and destination MAC addresses are matching. tx_mapping option defines which lane values are compared together.

In addition, if the RX_TOTAL_GOOD_PACKETS count is equal to 0, then an error message ID ETH_007 is reported to inform that no good packets were received, and the test will fail.

MAC_STAT status registers description

Each time the check_status command is executed, the following registers are read from the MAC hardware for each active MAC lane. All registers are stored in hardware using 48 bits and extended to 64 bits when read by software.

Note

The 48-bit counters RX_TOTAL_BYTES, RX_TOTAL_GOOD_BYTES and TX_TOTAL_BYTES could saturate after approximately 25 hours of maximum rate operation at 25GbE.

It is therefore recommended that the test duration does not exceed 24 hours between two check_status test mode.

In the table following table, the register type column represents how the register is verified:

  • Check: The content of the register must be null. Any other value will generate an error (message ID ETH_004).

  • Info: The content of the register is displayed as information (no verification performed).

MAC_STAT status description

Register name

Register type

Description

CYCLE_COUNT

Info

Number of transceiver clock domain cycles (approximately 1.5625e8 / sec at 10GbE and 3.90612e8 / sec at 25GbE).

Note

A value of 0 means that clocks were not active during the test and other registers should be ignored. Any non-zero result indicates the clocks were active.

FEC_INC_CANT_CORRECT_COUNT

Check

This count indicates how many uncorrected bit errors in the corresponding Clause 74 FEC Frame.

FEC_INC_CORRECT_COUNT

Check

This count indicates how many corrected bit errors in the corresponding Clause 74 FEC Frame.

RX_BAD_CODE

Check

This count indicates how many cycles the RX PCS receive state machine is in the RX_E state as defined by IEEE Std. 802.3.

RX_BAD_FCS

Check

The value of this count indicates packets received with a bad FCS, but not a stomped FCS. A stomped FCS is defined as the bitwise inverse of the expected good FCS.

RX_BROADCAST

Info

Increment for good broadcast packets.

RX_ERROR

Check

This count indicates a mismatch occurred for the test pattern in the RX core.

RX_FRAGMENT

Check

Increment for packets shorter than stat_rx_min_packet_len with bad FCS.

RX_FRAMING_ERR

Check

This count is used to keep track of sync header errors. The stat_rx_framing_err output indicates how many sync header errors were received.

RX_INRANGEERR

Check

Increment for packets with Length field error but with good FCS.

RX_JABBER

Check

Increment for packets longer than ctl_rx_max_packet_len with bad FCS.

RX_MULTICAST

Info

Increment for good multicast packets.

RX_OVERSIZE

Check

Increment for packets longer than ctl_rx_max_packet_len with good FCS.

RX_PACKET_64_BYTES

Info

Increment for good and bad packets received that contain 64 bytes.

RX_PACKET_65_127_BYTES

Info

Increment for good and bad packets received that contain 65 to 127 bytes.

RX_PACKET_128_255_BYTES

Info

Increment for good and bad packets received that contain 128 to 255 bytes.

RX_PACKET_256_511_BYTES

Info

Increment for good and bad packets received that contain 256 to 511 bytes.

RX_PACKET_512_1023_BYTES

Info

Increment for good and bad packets received that contain 512 to 1,023 bytes.

RX_PACKET_1024_1518_BYTES

Info

Increment for good and bad packets received that contain 1,024 to 1,518 bytes.

RX_PACKET_1519_1522_BYTES

Info

Increment for good and bad packets received that contain 1,519 to 1,522 bytes.

RX_PACKET_1523_1548_BYTES

Info

Increment for good and bad packets received that contain 1,523 to 1,548 bytes.

RX_PACKET_1549_2047_BYTES

Info

Increment for good and bad packets received that contain 1,549 to 2,047 bytes.

RX_PACKET_2048_4095_BYTES

Info

Increment for good and bad packets received that contain 2,048 to 4,095 bytes.

RX_PACKET_4096_8191_BYTES

Info

Increment for good and bad packets received that contain 4,096 to 8,191 bytes.

RX_PACKET_8192_9215_BYTES

Info

Increment for good and bad packets received that contain 8,192 to 9,215 bytes.

RX_PACKET_BAD_FCS

Check

Increment for packets between 64 and ctl_rx_max_packet_len bytes that have FCS errors.

RX_PACKET_LARGE

Info

Increment for all packets that are more than 9,215 bytes long.

RX_PACKET_SMALL

Check

Increment for all packets that are less than 64 bytes long. Packets that are less than 4 bytes are dropped.

RX_PAUSE

Info

Increment for 802.3x Ethernet MAC Pause packet with good FCS.

RX_RSFEC_CORRECTED_CW_INC

Check

This count will increment if the RS-FEC decoder detected and corrected a bit errors in the corresponding frame.

RX_RSFEC_ERR_COUNT0_INC

Check

Increment for RS-FEC detected errors.

RX_RSFEC_UNCORRECTED_CW_INC

Check

This count will increment if the RS-FEC decoder detected uncorrectable bit errors in the corresponding frame.

RX_STOMPED_FCS

Check

The value of this count indicates packets were received with a stomped FCS. A stomped FCS is defined as the bitwise inverse of the expected good FCS.

RX_TEST_PATTERN_MISMATCH

Check

This count indicates how many mismatches occurred for the test pattern in the RX core.

RX_TOOLONG

Check

Increment for packets longer than ctl_rx_max_packet_len with good and bad FCS.

RX_TOTAL_BYTES

Info

Increment for the total number of bytes received.

RX_TOTAL_GOOD_BYTES

Info

Increment for the total number of good bytes received. This value is only non-zero when a packet is received completely and contains no errors.

RX_TOTAL_GOOD_PACKETS

Info

Increment for the total number of good packets received. This value is only non-zero when a packet is received completely and contains no errors.

RX_TOTAL_PACKETS

Info

Increment for the total number of packets received.

RX_TRUNCATED

Check

This count indicates that the number of packets truncated due to their length exceeding ctl_rx_max_packet_len[14:0].

RX_UNDERSIZE

Check

Increment for packets shorter than stat_rx_min_packet_len with good FCS.

RX_UNICAST

Info

Increment for good unicast packets.

RX_USER_PAUSE

Info

Increment for priority-based pause packets with good FCS.

RX_VLAN

Info

Increment for good 802.1Q tagged VLAN packets.

TX_TOTAL_BYTES

Info

Increment for the total number of bytes transmitted by the packet generator.

TX_TOTAL_PACKETS

Info

Increment for the total number of packets transmitted by the packet generator.

GT MAC test JSON members

Following are examples of GT MAC test cases. Some test JSON members can be overwritten for each lane using the test JSON member lane_config which child members are lane indexes.

Electrical/optical loopback example

Note

The default TX/RX lane mapping is used with loopback module.

"gt_mac": {
  "0": {
    "global_config": {
      "match_tx_rx": true,
      "test_sequence": [
        { "duration":  1, "mode": "conf_25gbe_no_fec" },
        { "duration":  1, "mode": "clear_status"      },
        { "duration": 60, "mode": "run"               },
        { "duration":  1, "mode": "check_status"      }
      ]
    }
  }
}

Switch example

Note

Lane pairing must be used when connected to a switch.

Here is an example of 2 GT xbtIP:

  • GT[0] is connected to a 10GbE port with a fixed packet size of 1024 bytes.

  • GT[1] is a 25GbE with the default sweep packet size.

"gt_mac": {
  "0": {
    "global_config": {
      "match_tx_rx": true,
      "packet_cfg": "1024",
      "test_sequence" : [
        { "duration":  1, "mode": "conf_10gbe_no_fec" },
        { "duration":  1, "mode": "clear_status"      },
        { "duration": 60, "mode": "run"               },
        { "duration":  1, "mode": "check_status"      }
      ]
    },
    "lane_config": {
      "0": {
        "tx_mapping": 1
      },
      "1": {
        "tx_mapping": 0
      },
      "2": {
        "tx_mapping": 3
      },
      "3": {
        "tx_mapping": 2
      }
    }
  },
  "1": {
    "global_config": {
      "match_tx_rx": true,
      "test_sequence": [
        { "duration":  1, "mode": "conf_25gbe_c74_fec" },
        { "duration":  1, "mode": "clear_status"       },
        { "duration": 60, "mode": "run"                },
        { "duration":  1, "mode": "check_status"       }
      ]
    },
    "lane_config": {
      "0": {
        "tx_mapping": 1
      },
      "1": {
        "tx_mapping": 0
      },
      "2": {
        "tx_mapping": 3
      },
      "3": {
        "tx_mapping": 2
      }
    }
  }
}

GT MAC to GT MAC connection example

Here is an example of GT MAC interconnection. Both xbtest hardware IP (xbtIP) must be in the same Alveo Versal Example Design (AVED). gt_mac[1] is connected linked to gt_mac[0] via mac_to_mac_connection.

In this example:

  • To avoid some lanes being automatically disabled by the SW (as there are not enough MAC address available), test_address is used for source_addr.

  • match_tx_rx is used, meaning that at the top of checking that sending and receiving traffic is errorless, each GT MAC xbtIP lane will also verify that it receives the expected quantity of packets and bytes based on the traffic definition and lane mapping of the other GT MAC xbtIP lane.

Note

only one test_sequence is defined

"gt_mac": {
  "0": {
    "global_config": {
      "match_tx_rx": true,
      "test_sequence" : [
        {"duration": 1, "mode": "conf_25gbe_c74_fec" },
        {"duration": 1, "mode": "clear_status"       },
        {"duration": 10, "mode": "run"               },
        {"duration": 1, "mode": "check_status"       },

        {"duration": 1, "mode": "conf_10gbe_no_fec"  },
        {"duration": 1, "mode": "clear_status"       },
        {"duration": 10, "mode": "run"               },
        {"duration": 1, "mode": "check_status"       }
      ]
    },
    "lane_config": {
      "0": {
        "tx_mapping" : 0
      },
      "1": {
        "tx_mapping" : 1,
        "source_addr": "test_address"
      },
      "2": {
        "tx_mapping" : 2,
        "source_addr": "test_address"
      },
      "3": {
        "tx_mapping" : 3,
        "source_addr": "test_address"
      }
    }
  },
  "1": {
    "global_config": {
      "mac_to_mac_connection": 0
    },
    "lane_config": {
      "1": {
        "source_addr": "test_address"
      },
      "2": {
        "source_addr": "test_address"
      },
      "3": {
        "source_addr": "test_address"
      }
    }
  }
}

Cross connection even works through a switch. The traffic is sent to a different GT (thus different mac address), so even with default tx_mapping (lane 0 to lane 0, as per example above), the traffic will be flow (as the switch will see different source and destination addresses).

You can still change the default lane pairing configuration. Compared to pre-canned switch test, you’re not limited to the 3 pairing A/B/C. As you target another GT, you can freely pair lanes.

"lane_config": {
    "0": {
        "tx_mapping" : 1
    },
    "1": {
        "tx_mapping" : 3
    },
    "2": {
        "tx_mapping" : 0
    },
    "3": {
        "tx_mapping" : 2
    }
}

Definition

The following table shows all members available for this test case. More details are provided for each member in the subsequent sections.

GT MAC Test JSON members

Member

Lane override

Mandatory / Optional

Description

test_sequence

No

Mandatory

Describes the sequence of tests to perform.

tx_mapping

Only

Optional

Specify lane mapping. It defines:

  • Destination MAC address.

  • TX lane index which will be checked against RX status.

disable_lane

Only

Optional

Disable a lane.

source_addr

Only

Optional

Overwrite default source MAC address - lane mapping.

dest_addr

Only

Optional

Overwrite default destination MAC address.

utilisation

Yes

Optional

Transmit utilisation.

traffic_type

Yes

Optional

Define the content of the payload area of the packets.

packet_cfg

Yes

Optional

Define the packet length.

match_tx_rx

Yes

Optional

Enable RX and TX packet count match when loopback is present.

mac_to_mac_connection

Yes

Optional

Enable GT MAC xbtest hardware IP (xbtIP) connections.

gt_settings

No

Optional

Selects the GT default configuration. See GT JSON Member.

gt_tx_diffctrl

Yes

Optional

Select the Driver Swing Control. See GT JSON Member.

gt_tx_main_cursor

Yes

Optional

Select Transmitter pre-cursor TX main control. See GT JSON Member.

gt_tx_pre_emph

Yes

Optional

Select Transmitter pre-cursor TX pre-emphasis control. See GT JSON Member.

gt_tx_post_emph

Yes

Optional

Select Transmitter post-cursor TX pre-emphasis control. See GT JSON Member.

gt_tx_polarity

Yes

Optional

Select TX Polarity. See GT JSON Member.

gt_rx_use_lpm

Yes

Optional

Select RX Equalizer. See GT JSON Member.

test_sequence

Mandatory. Describes the sequence of tests to perform. Tests are performed serially, and a failure in one test does not stop the sequence (the next test will be launched). There is no limitation to the length of the test sequence.

This field contains a list of tests, each test being defined by an object of key–value parameters pairs: [ {}, {}, {} ].

The following table defines the parameters supported in the GT MAC test sequence:

GT MAC test sequence parameters

Member

Mandatory / Optional

Description

duration

Mandatory

The duration of the test in seconds; Range [1, 232-1].

mode

Mandatory

Mode of the xbtIP. See the following table.

mode possible values

Possible value

Description

conf_<mode>

Apply the settings specified in the configuration parameters to the MAC hardware. Part of the configuration process is to issue a reset to the MAC hardware, so the conf_<mode> operation will always result in the Ethernet link dropping and restarting, even if the configuration is identical to the previous test.

Configurations are available for various lane rates and Forward Error Correction (FEC) modes:

  • Lane rates:

    • 10GbE: 10.3125 Gb/s.

    • 25GbE: 25.78125 Gb/s.

  • FEC modes:

    • none: Disables FEC and uses 66-b words with 2-bit sync headers.

    • clause_74: Enables the FEC specified in IEEE 802.3 Clause 74. It can be used for both 10GbE and 25GbE lane rates.

    • rs_fec: Enables the FEC specified in IEEE 802.3by Clause 91. It can only be used in 25GbE mode.

Possible values of conf_<mode> are:

  • conf_10gbe_no_fec: Lane rate: 10GbE, FEC mode: none.

  • conf_10gbe_c74_fec: Lane rate: 10GbE, FEC mode: clause_74.

  • conf_25gbe_no_fec : Lane rate: 25GbE, FEC mode: none.

  • conf_25gbe_c74_fec: Lane rate: 25GbE, FEC mode: clause_74.

  • conf_25gbe_rs_fec: Lane rate: 25GbE, FEC mode: rs_fec.

Warning

Most of the Alveo Versal Example Design (AVED) don’t include the rs_fec, as it takes a lot of resources. The SW detects the presence of the rs_fec and will let you aware if it’s not supported.

Warning

The switch only supports conf_10gbe_no_fec or conf_25gbe_c74_fec (see GT test set up)

clear_status

Read and clear the MAC status registers, but ignore the values returned in the counters. It is intended to be used after a conf_<mode> operation to clear the status errors caused by the link dropping and restarting.

run

Enable the packet generator. Any test sequence entry without a run will disable the packet generator. If the final test_sequence entry contains a run then packet generation will continue after execution of xbtest has terminated.

check_status

Read the MAC status registers, and for any MAC instances that have not been disabled (disable_lane) Check for any counter values that indicate an error has occurred, or the received number of packets indicates a fault on the link. If an error is detected the overall test will be flagged as a fail.

<dir>_rst

Initiate a reset of the MAC TX and/or RX path. Possible values of <dir>_rst are:

  • tx_rst: MAC TX reset.

  • rx_rst: MAC RX reset.

  • tx_rx_rst: MAC TX followed by MAC RX reset 10ms after.

An example of a test_sequence is:

"test_sequence": [
  { "duration":  1, "mode": "conf_10gbe_no_fec" },
  { "duration":  1, "mode": "clear_status"      },
  { "duration": 60, "mode": "run"               },
  { "duration":  1, "mode": "check_status"      }
]

This will:

  • Apply the configuration to the MACs, reset them and wait for 1 second.

  • Wait for 1 second then clear the status registers.

  • Start the packet generators for any active MACs and wait for 60 seconds.

  • Wait for 1 second before reading the status registers and check the results. Then, clear the status registers, stop the packet generator and exit.

tx_mapping

Optional; Type : integer; Possible values: 0 to 3; Default : n where n represents the lane index within the lane_config (so the default is equivalent to a lane loopback to itself).

Specifies the lane index of the nth TX which will be checked against RX status.

This configuration can only be applied individually to one or more of the four lanes connected to the individual transceivers at the lane_config level.

disable_lane

Optional; Type : boolean; Possible values: true or false; Default : false

This configuration can only be applied individually to one or more of the four lanes connected to the individual transceivers at the lane_config level.

  • When false, the packet generator of the selected lane will be enabled, and receiver statistics will be gathered and used to determine the overall pass/fail result of the test.

  • When true, no packets are generated by the selected lane, and receiver statistics from that instance are ignored.

source_addr

Optional; Type : string; Possible values: board_mac_addr_<i> where <i> represents the index of an available board MAC address.

This configuration can only be applied individually to one or more of the four lanes connected to the individual transceivers at the lane_config level.

This option allows the overwrite of the default round robin MAC address vs. lane mapping.

All available MAC addresses are listed in summary.log (or in xbtest.log) file via the message ID ETH_036:

INFO :: ETH_030 :: GT_MAC[0] :: Board MAC address list:
INFO :: ETH_036 :: GT_MAC[0] :: -board_mac_addr_0: 00:0A:35:06:9F:D2
INFO :: ETH_036 :: GT_MAC[0] :: -board_mac_addr_1: 00:0A:35:06:9F:D3
INFO :: ETH_036 :: GT_MAC[0] :: -board_mac_addr_2: 00:0A:35:06:9F:D4
INFO :: ETH_036 :: GT_MAC[0] :: -board_mac_addr_3: 00:0A:35:06:9F:D5

In this case, there are 4 addresses listed, so the possible values for source_addr are board_mac_addr_0/1/2/3.

Tip

Using board_mac_addr_<i> addresses keeps the test generic across different cards as the actual value of the address is not used in the test JSON file.

Other values of source_addr are supported:

There is no mechanism to insert any MAC address (spoofing protection). These modes allow to re-enable a lane normally disabled to due missing or invalid MAC addresses.

test_address

When setting source_addr to test_address, the source MAC address is always 06-bbcc-dd-ee-<X><Y> where:

  • <X> represents the index of the GT. Possible values: from 0 to n, where n is the number of GT defined in the Card definition.

  • <Y> represents the index of the lane. Possible values: from 0 to 3.

In the test_address mode, the MAC addresses are fixed whatever the card is. The address only depends on the GT and the lane used. If multiple instances of xbtest are running simultaneously with test_address, the switch will detect multiple lanes with identical MAC addresses and won’t be able to route the traffic correctly.

As the addresses are predictable, it may help to debug traffic issues at the switch.

Note

MAC addresses beginning with 02, 06, 0A or 0E are locally administered.

alveo_random_address

Alveo cards MAC addresses are taken from 2 pools of addresses when setting source_addr to alveo_random_address:

  1. 00-0A-35-xx-xx-xx

  2. 00-5d-03-xx-xx-xx

In this mode, xbtest creates randomly, at runtime, an address from the first pool (00-0A-35-xx-xx-xx). Each xbtest run will result in different addresses. This mode allows to run multiple cards/lanes without having to worry about conflicting MAC addresses. This overcomes the limitation of the test_address mode.

dest_addr

Optional; Type : string; Possible values: board_mac_addr_<i> where <i> represents the index of an available board MAC address, or any valid six-octet value (for example: 01:0A:BC:DE:F0:20).

This configuration can only be applied individually to one or more of the four lanes connected to the individual transceivers at the lane_config level.

Although the destination address is automatically selected defining tx_mapping, it is possible to overwrite the selection and use another board address or any valid MAC address.

All available MAC addresses are listed in summary.log (or in xbtest.log) file via the message ID ETH_036:

INFO :: ETH_030 :: GT_MAC[0] :: Board MAC address list:
INFO :: ETH_036 :: GT_MAC[0] :: -board_mac_addr_0: 00:0A:35:06:9F:D2
INFO :: ETH_036 :: GT_MAC[0] :: -board_mac_addr_1: 00:0A:35:06:9F:D3
INFO :: ETH_036 :: GT_MAC[0] :: -board_mac_addr_2: 00:0A:35:06:9F:D4
INFO :: ETH_036 :: GT_MAC[0] :: -board_mac_addr_3: 00:0A:35:06:9F:D5

In this case, there are 4 addresses listed, so the possible values for dest_addr are board_mac_addr_0/1/2/3.

Tip

Using board_mac_addr_<i> addresses keeps the test generic across different cards as the actual value of the address is not used in the test JSON file.

The dest_addr overwrite also supports any valid MAC address. The address must be composed of 6 octets separated by columns “:”. Only hexadecimal characters are supported. For example: 01:0A:BC:DE:F0:20.

When setting dest_addr to test_address, the destination MAC address is always 06-bbcc-dd-ee-<X><Y> where:

  • <X> represents the index of the GT. Possible values: from 0 to 1.

  • <Y> represents the index of the lane. Possible values: from 0 to 3.

In this mode, the MAC addresses are fixed whatever the card is. The address only depends on the GT and the lane used. If multiple instances of xbtest are running simultaneously with test_address, the switch will detect multiple lanes with identical MAC addresses and it won’t be able to route the traffic correctly.

As the addresses are predictable, it may help to debug traffic issues at the switch.

utilisation

Optional; Type : integer; Possible values: from 0 to 100; Default : 50.

This sets the transmit utilisation of the link in the range 0 to 100 (percent). The parameter is used to set the approximate link utilisation for the packet generator, by adjusting the delay between packets.

  • Setting the utilisation to 100 causes packets to be generated at the maximum achievable rate.

  • Setting the utilisation to 0 disables the packet generator completely.

Caution

Never use a utilisation of 100 when connected to the switch. The switch also sends some maintenance packets which will take priority over any traffic, resulting in lost packets.

traffic_type

Optional; Type : string; Possible values: 0x00, 0xff, count or pattern; Default : count.

The test packets produced by the traffic generator consist of a statically configured destination address (48 bits), source address (48 bits) and ethertype (16 bits) followed by a payload area and a CRC (32 bits).

The content of the payload area is controlled by this parameter:

  • 0x00: The whole payload area will be filled with bytes of value 0x00.

  • count: The payload area will be filled with a byte count sequence. The byte following Ethertype will be 0x00, the next 0x01, with each successive byte incrementing to 0xff and rolling over to 0x00 and repeating to the end of the payload area.

  • pattern: The payload area will be filled with the pattern (0x00, 0x55, 0xaa, 0xff) repeating for the number of bytes in the payload area.

  • 0xff: The whole payload area will be filled with bytes of value 0xff.

packet_cfg

Optional; Type : string; Possible values: sweep or value from 64 to 1535 or from 9000 to 10000; Default : sweep.

  • When sweep is used, a sequence of 1455 packets will be generated continuously with sizes between 64 and 1518 bytes.

If a single numeric value is used (in the range 64 to 1535 or in the range 9000 to 10000) is supplied, then all generated packets shall be this size.

Warning

  • Only even values are supported for packet sizes between 9000 and 10000 (jumbo frame).

  • The switch only supports jumbo frames up to 9216 bytes (see GT test set up).

Note

Note that the receive MTU is adjusted to match the configured transmit packet size.

If the transmit size is:

  • Lower than or equal to 1518, then the receive MTU is set to 1518.

  • Greater than 1518 but lower than or equal to 9600, then the receive MTU is set to 9600.

  • Greater than 9600, then the receive MTU is set to 10000.

match_tx_rx

Optional; Type : boolean; Possible values: true or false; Default : false.

Specifies if RX is checked against TX.

If the transmit and receive interfaces of each active MAC instance are is looped back, then the transmitted packet and byte counts are expected to exactly match the equivalent received good packet and byte counters.

  • Setting this parameter to true enables this comparison to be made and included in the overall pass/fail assessment of the link.

When set to false, the comparison of TX and RX counters is not included in the overall pass/fail assessment of the link.

mac_to_mac_connection

Optional; Type: integer; Possible values: from 0 to 31;

Enable GT MAC cross connections. Contains the index of the GT MAC xbtest hardware IP (xbtIP) to which is connected the xbtIP.

See GT MAC to GT MAC connection example for syntax example.

GT settings test JSON members

For the 3 types of GT test cases, the GT settings can be defined in a similar manner

  • For the 4 lanes simultaneously: part of the global_config

    • Select one of the pre-defined configurations (gt_settings). The various configurations are stored in the Card definition JSON file (see Card definition).

    • Overwrite any settings of the selected configuration.

  • For each lane individually: overwrite any settings of the selected configuration. Part of the lane_config

If required, these settings are simply added to your test JSON file within your test case definition. Here is an example with global selection, but it also includes global and per-lane specific overwrites.

"gt_mac": {
  "0": {
    "global_config": {
      "gt_settings": "module",
      "gt_rx_use_lpm": true
    },
    "lane_config": {
      "0": {
        "gt_rx_use_lpm": false,
        "gt_tx_diffctrl": 11
      },
      "1": {
        "gt_tx_main_cursor": 80
      },
      "2": {
        "gt_tx_pre_emph": 2,
      },
      "3": {
        "gt_tx_post_emph": 3,
      }
    }
  }
}

More info can be found here: GT Settings. Further details on each of settings can be found in UltraScale architecture GTY transceivers user guide (UG578).

gt_settings

Optional; Type : string; Possible values: module or cable; Default : module.

It selects the GT configuration from the Card definition JSON file (see Card definition). This configuration applies to all lanes of the GT.

gt_tx_diffctrl

Optional; Type : integer; Possible values: from 0 to 31; Default : defined in the Card definition JSON file (see Card definition).

This parameter sets the TXDIFFCTRL input to transmitter.

gt_tx_main_cursor

Optional; Type : integer; Possible values: from 0 to 127; Default : defined in the Card definition JSON file (see Card definition).

This parameter sets the TXMAINCURSOR input to transmitter.

gt_tx_pre_emph

Optional; Type : integer; Possible values: from 0 to 31 (GTF & GTYp) or 63 (GTM); Default : defined in the Card definition JSON file (see Card definition).

This parameter sets the TXPRECURSOR inputs to transmitter. It also set TXPRECURSOR2 and TXPRECURSOR3 of the GTM.

gt_tx_post_emph

Optional; Type : integer; Possible values: from 0 to 31 (GTF & GTYp) or 63 (GTM); Default : defined in the Card definition JSON file (see Card definition).

This parameter sets the TXPOSTCURSOR input to transmitter.

gt_tx_polarity

Optional; Type : string; Possible values: normal or inverted; Default : normal.

When set to normal, TXP is positive, and TXN is negative.

When set to inverted, TXP is negative, and TXN is positive.

gt_rx_use_lpm

Optional; Type : boolean; Possible values: false or true; Default : defined in the Card definition JSON file (see Card definition).

When set to false, the GTY transceiver to use the DFE receive equalizer.

When set to true, the GTY transceiver to use the LPM receive equalizer.

Output files

All GT measurements are stored in an output CSV file generated in xbtest logging directory. The values are stored in CSV type format with one column for each information type.

Important

If the command line option -L is used while calling xbtest application software (xbtSW), no output file is generated.

For each GT MAC xbtIP, one file is generated per lane with the suffix/extension _gt<gt_index>_<lane_index>.csv where:

  • <gt_index> is the index of the GT MAC xbtIP.

  • <lane_index> is the index of the lane.

For each test of the test_sequence, a new row containing the test results and status is present in this file. All columns present in the file are defined as:

  • Overall result: Set to FAIL as soon as one test fails, otherwise set to PASS.

  • Test result: Set to FAIL if the current test fails, otherwise set to PASS.

  • Status: This group of columns is composed of one column for each status registers (see Status).