MMIO test case description¶

The goal of this test case is to check communication and available bandwidth between host PCIe BARs available on the Alveo™ card through the PCIe. Data integrity and write/read bandwidths are measured.

The MMIO test case consists of writing and reading back data to and from the BAR range under test over and over during a certain period. A write-read-check cycle is never interrupted, meaning that:

Data is always fully sent and read back to and from the PCIe BAR and checked for data integrity.

If required, a test duration can be extended to perform all write-read-check cycle operations.

The data sent and read back to and from the PCIe BAR is:

Generated via an 8-bit counter that is randomly initialized at the beginning of each write-read-check cycle.

Split into buffers which are transferred to or from the Alveo card.

The test JSON parameter total_size can be used to override the quantity of data (in Bytes) sent and read back to and from the PCIe BAR available on the card. When not specified, total_size defaults to the size of xbtest configuration and status memory (the one in SLR0 for multi-SLR devices).

The write/read bandwidths are computed after all write/read data transfers in each write-read-check cycle and the values are averaged over the test duration.

Important

By default, the average read and write bandwidths are not checked against any pass/fail criteria, but this can be overruled by setting check_bw.

Test parameters¶

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

duration: The duration of the test (in seconds).

The following optional parameter may also be specified:

bar: PCIe BAR index.

offset: Start address offset in PCIe BAR of register to access.

buffer_size: Write/read buffer size.

Important

The different Alveo™ cards have different PCIe BAR layout, and each PCIe BAR registers are assigned for different functionalities of the card. Overwriting buffer_size, buffer_size and buffer_size may cause unexpected consequences.

Main test steps¶

For each test configuration, the following steps are repeated:

Allocate N host buffers aligned with memory page size.

The number of buffers N equals total_size divided by buffer_size.

The memory page size is detected automatically and displayed at the beginning of the MMIO test case in xbtest.log file.

Allocate and initialize the reference buffer used to check data integrity.

Write-read-check cycles are repeated for the duration of the test. One cycle consists of the following steps:

Set host buffers with reference data (8-bit counter).

Write host buffers to the card PCIe BAR, measure bandwidth.

Reset host buffers to 0.

Read from the card PCIe BAR, measure bandwidth.

Check that the host buffers contain the same data as the reference buffers (data integrity). Host buffers are set with reference data if data integrity fails.

Note

These steps constitute a write-read-check cycle which is always entirely executed. If stop_on_error is set, the MMIO test case aborts in case of write/read transfer or data integrity error.

Compute write and read minimum, maximum, and average bandwidths.

If enabled, compare the average read and write bandwidths against their thresholds.

Release all host buffers.

MMIO test JSON members¶

Definition¶

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

MMIO test case members¶
Member	Mandatory / Optional	Description
test_sequence	Mandatory	Describes the sequence of tests to perform.
check_bw	Optional	Enable bandwidth checking. Disabled by default.
stop_on_error	Optional	Enable stop test case on error. Disabled by default.
hi_thresh_wr hi_thresh_rd	Optional	Overwrite high threshold of the write/read bandwidth (kB/s).
lo_thresh_wr lo_thresh_rd	Optional	Overwrite low threshold of the write/read bandwidth (kB/s).
total_size	Optional	Total amount of data (Bytes) per bandwidth measurement.

Basic examples¶

The following is a basic example of a MMIO test case targeting default PCIe BAR range. By default, the entire xbtest configuration and status memory (the one in SLR0 for multi-SLR devices) is targeted.

"mmio": {
  "global_config": {
    "test_sequence": [
      { "duration": 10 }
    ]
  }
}

Following is an example of MMIO test case where some test JSON members are overwritten: PCIe BAR registers are selected and comparison of the average read and write bandwidths against thresholds is enabled.

"mmio": {
  "global_config": {
    "stop_on_error": true,
    "check_bw": true,
    "hi_thresh_wr": 13000,
    "hi_thresh_rd": 13000,
    "lo_thresh_wr": 9000,
    "lo_thresh_rd": 9000,
    "test_sequence": [
      { "duration": 10, "offset": 67108864 },
      { "duration": 10, "offset": 83886080, "buffer_size": 4096 }
    ]
  }
}

Note

By default, bandwidths are not checked, so check_bw is set to true.

`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 MMIO test sequence:

MMIO test sequence parameters¶
Member	Mandatory / Optional	Description
`duration`	Mandatory	The duration of the test in seconds; Range [1, 2³²-1].
`bar`	Optional	PCIe BAR index. Possible value depend on the Card definition. Default: specified in the Card definition.
`buffer_size`	Optional	Write/read buffer size in Bytes. Range [4, `max_buffer_size`] where `max_buffer_size` equals the PCIe BAR size. Default: specified in the Card definition. The number of buffers used in the test equals total_size divided by buffer_size.
`offset`	Optional	Start address offset in PCIe BAR. Range [0, `max_offset`] where `max_offset` equals the `max_total_size` minus buffer_size and max_total_size` is the PCIe BAR size. Default: specified in the Card definition.

For example:

Single test:

"test_sequence": [ { "duration": 50 } ]

"test_sequence": [ { "duration": 50, "offset": 67108864 } ]

"test_sequence": [ { "duration": 50, "offset": 83886080, "buffer_size": 4096 } ]

Multiple tests:

"test_sequence": [
  { "duration": 50, "offset": 50331648 },
  { "duration": 20, "offset": 67108864 },
  { "duration": 10, "offset": 83886080 }
]

`check_bw`¶

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

By setting this member to true, average bandwidth measurements will be compared against defined thresholds. When set to false, no average bandwidth measurement will be checked.

Default bandwidth limits are defined in Card definition and are displayed at the beginning of the tests.

The bandwidth limits can be overwritten using the following parameters:

hi_thresh_wr, hi_thresh_rd.

lo_thresh_wr, lo_thresh_rd.

`stop_on_error`¶

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

By default, the write-read-check cycles are always executed during the entire test duration even if errors occurred during a cycle. By setting this member to true, the MMIO test case will stop in case of write / read transfer or data integrity error.

`hi_thresh_wr`, `hi_thresh_rd`¶

Optional; Type : integer; Possible values: from 1 to 2³²-1; Default : specified in the Card definition.

Overwrite high threshold of the write/read bandwidth (kB/s) specified in the Card definition. After all bandwidth measurements made during the test duration are complete, if the measured bandwidth is greater than this threshold, the test fails.

`lo_thresh_wr`, `lo_thresh_rd`¶

Optional; Type : integer; Range : [1, 2³²-1]; Default: specified in the Card definition.

Overwrite low threshold of the write/read bandwidth (kB/s) specified in the Card definition. After all bandwidth measurements made during the test duration are complete, if the measured bandwidth is lower than this threshold, the test fails. Low threshold must be lower than high threshold.

`total_size`¶

Optional; Type : integer; Possible values: from minimum buffer size to size of selected PCIe BAR; Range : [4, PCIe BAR size]; Default : specified in the Card definition.

Override the total amount of data (in Bytes) per transfer cycle. Default value defined in Card definition and is displayed at the beginning of the tests. This must be a multiple of the buffer_size parameter for all tests in the test_sequence.

Output files¶

All MMIO measurements are stored in output CSV files which are 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 the xbtest application software (xbtSW), no output file is generated.

In the MMIO test case, two different CSV files are used to store all test results. They are named with the following convention:

mmio_detail.csv

mmio_result.csv

`mmio_detail.csv` output file¶

This file contains all intermediate bandwidth measurements. There is one line of result for every write-read-check cycle of each test of the test_sequence containing following results.

Test: Index of current test within the test_sequence. Index of first test is 1.

bar: Tested PCIe BAR index.

offset: Start address offset in BAR of tested PCIe BAR range.

buffer size (Bytes): Size of buffers transferred during the test.

Cycle ID: Index of the write-read-check cycle: the number of cycles depends on test duration and quantity of data transferred.

Data integrity: Data integrity result for the current write-read-check cycle.

write results: This group contains the following columns:

live write BW (kBps): MMIO write BW measurements for the current write-read-check cycle.

minimum write BW (kBps): Minimum of MMIO write BW measurements.

average write BW (kBps): Average of MMIO write BW measurements.

maximum write BW (kBps): Maximum of MMIO write BW measurements.

read results: This group contains the following columns:

live read BW (kBps): MMIO read BW measurements for the current write-read-check cycle.

minimum read BW (kBps): Minimum of MMIO read BW measurements.

average read BW (kBps): Average of MMIO read BW measurements.

maximum read BW (kBps): Maximum of MMIO read BW measurements.

`mmio_result.csv` output file¶

For each test of the test_sequence, a new row containing the test configuration and results computed is present in this file:

Test: Index of current test within the test_sequence. Index of first test is 1.

duration (s): Test duration.

configuration: This group contains the following columns:

bar: Tested PCIe BAR index.

offset: Start address offset in BAR of tested PCIe BAR range.

buffer size (Bytes): Size of buffers transferred during the test.

number of buffers: Quantity of buffers transferred in each write-read-check cycle.

total size (Bytes): Total quantity of data transferred in each write-read-check cycle.

Number of cycles: Total number of write-read-check cycles performed: the number of cycles depends on test duration and quantity of data transferred.

Data integrity: Data integrity result.

write results: This group contains the following columns:

minimum write BW (kBps): Minimum of MMIO write BW measurements.

average write BW (kBps): Average of MMIO write BW measurements.

maximum write BW (kBps): Maximum of MMIO write BW measurements.

read results: This group contains the following columns:

minimum read BW (kBps): Minimum of MMIO read BW measurements.

average read BW (kBps): Average of MMIO read BW measurements.

maximum read BW (kBps): Maximum of MMIO read BW measurements.

MMIO test case description¶

Test parameters¶

Main test steps¶

MMIO test JSON members¶

Definition¶

Basic examples¶

test_sequence¶

check_bw¶

stop_on_error¶

hi_thresh_wr, hi_thresh_rd¶

lo_thresh_wr, lo_thresh_rd¶

total_size¶

Output files¶

mmio_detail.csv output file¶

mmio_result.csv output file¶

`test_sequence`¶

`check_bw`¶

`stop_on_error`¶

`hi_thresh_wr`, `hi_thresh_rd`¶

`lo_thresh_wr`, `lo_thresh_rd`¶

`total_size`¶

`mmio_detail.csv` output file¶

`mmio_result.csv` output file¶