Fill platform definition JSON

Platform definition JSON file: xbtest_pfm_def.json

Important

The steps Fill platform definition JSON, Build RPM and DEB packages and Complete checklist are part of an iterative process and are inter-linked.

  1. You need first to create an initial valid package by using the default pre-canned tests templates and Platform definition JSON file template: xbtest_pfm_def_template.json (along with the xclbin).

  2. You’ll use this initial package to fill the checklist. The checklist will guide you:

  3. Re-package your xclbin, Platform definition JSON file: xbtest_pfm_def.json (and potentially pre-canned test JSON files).

    • Finalize the last step of the checklist (actual results of the pre-canned tests).

xbtest SW is written in a generic way and can be used by any platform.

As each platform has its own characteristics and limits, xbtest uses a Platform definition JSON file: xbtest_pfm_def.json to limit and check user operation/settings.

For example:

  • Memory: DMA/P2P/CU bandwidth and latency limits and nominal configurations.

  • GT transceiver settings.

  • Power or temperature sensor sources to be monitored.

The rpm_generate workflow includes Platform definition JSON file: xbtest_pfm_def.json in the RPM/DEB packages with xclbin and pre-canned test JSON files.

Further down this page, you will find:

Platform definition JSON file template: xbtest_pfm_def_template.json

A Platform definition JSON file template: xbtest_pfm_def_template.json is automatically

You’ll have to update the generated template as it contains default values. This update is done while filling the checklist (see Complete checklist).

Steps to fill platform definition JSON file

The following sections describes the steps necessary to fill Platform definition JSON file: xbtest_pfm_def.json by updating the generated Platform definition JSON file template: xbtest_pfm_def_template.json.

Step 1: Generate RPM/DEB package with xbtest platform definition JSON file template

Follow the steps specified in Build RPM and DEB packages to generate an xbtest HW RPM or DEB package containing the Platform definition JSON file template: xbtest_pfm_def_template.json automatically generated and embedded in the xclbin.

Before generating the RPM or DEB, make sure the Platform definition JSON file: xbtest_pfm_def.json does not exists in the rpm_generate workflow configuration directory <xbtest_build>/rpm_generate/include/<deploy_platform>/xbtest_pfm_def.json.

  • <xbtest_build> represents the xbtest build source directory (e.g. path/to/your/xbtest/src/hw/build_source/xbtest_wizard_v6_0/).

  • <deploy_platform> is the deployment platform named <deploy_name>-<deploy_version> (e.g. xilinx-u55c-gen3x16-xdma-base-3).

Step 2: Complete checklist and update xbtest platform definition JSON file

Follow the steps specified in the checklist using the RPM or DEB package generated in previous step.

Dummy/low values are specified for each parameter in the generated Platform definition JSON file template: xbtest_pfm_def_template.json which must be replaced by actual values while following and completing a checklist.

Platform definition JSON file template: xbtest_pfm_def_template.json can be found in <xbtest_build>/xclbin_generate/output/<dev_platform>/<project_name>/u_ex/run/sw/test/xbtest_pfm_def_template.json where it was written by xclbin_generate workflow:

Where:

  • <xbtest_build> represents the xbtest build source directory (e.g. path/to/your/xbtest/src/hw/build_source/xbtest_wizard_v6_0/).

  • <dev_platform> is provided with command line option --xpfm. For example: If path/to/xilinx_u55c_gen3x16_xdma_3_202210_1.xpfm is provided, then <dev_platform> is set with xilinx_u55c_gen3x16_xdma_3_202210_1. If path/to/hw.xsa is provided, then <dev_platform> is set with hw. If path/to/your/xilinx-u250-gen3x16-xdma-4.1-202210-1-dev-1-3512975.noarch.rpm is provided, then <dev_platform> is set with xilinx-u250-gen3x16-xdma-4.1-202210-1-dev-1-3512975.noarch.

  • <project_name> is provided with command line option --project_name.

Step 3: Generate RPM/DEB package with updated xbtest platform definition JSON file

The updated Platform definition JSON file: xbtest_pfm_def.json must be saved in the rpm_generate workflow include directory <xbtest_build>/rpm_generate/include/<deploy_platform>/xbtest_pfm_def.json

  • <xbtest_build> represents the xbtest build source directory (e.g. path/to/your/xbtest/src/hw/build_source/xbtest_wizard_v6_0/).

  • <deploy_platform> is the deployment platform named <deploy_name>-<deploy_version> (e.g. xilinx-u55c-gen3x16-xdma-base-3).

Finally, generate both xbtest HW RPM and DEB packages containing the updated Platform definition JSON file: xbtest_pfm_def.json.

Platform definition JSON file examples

The following table provides example of Platform definition JSON file: xbtest_pfm_def.json for some platforms:

Platform definition JSON file examples

Platform

xbtest_pfm_def.json

xilinx-u55c-gen3x16-xdma-base-3

xbtest_pfm_def.json

xilinx-u250-gen3x16-xdma-shell-4.1

xbtest_pfm_def.json

xilinx-u50lv-gen3x4-xdma-base-2

xbtest_pfm_def.json

All platform definition JSON file parameters

The top-level node of the Platform definition JSON file: xbtest_pfm_def.json is named device.

The following sections describes the parameters supported in Platform definition JSON file: xbtest_pfm_def.json below the top-level node.

runtime parameters of platform definition JSON file

The following table describes the parameters supported under the runtime node of the Platform definition JSON file: xbtest_pfm_def.json.

runtime parameters of platform definition JSON file

Node name

Type

Example

Required / optional

Description

download_time

integer

20

Required

Expected maximum xclbin download time (specified in seconds).

sensor parameters of platform definition JSON file

The following table describes the parameters supported under the sensor node of the Platform definition JSON file: xbtest_pfm_def.json.

sensor parameters of platform definition JSON file

Node name

Type

Example

Required / optional

Description

Level 1

Level 2

0 / 1 / …

type

string

“thermal”

Optional

Specify sensor type. Supported values are electrical, thermal, mechanical.

Index must be starting at 0 and incrementing by 1: 0/1/…

For more details, see Add sensor to monitor.

id

string

“fpga_hbm”

Optional

Specify sensor ID to be monitored.

Add sensor to monitor

Each board has multiple power rails, which could be cascaded and not all are used by the FPGA (see xbutil examine). For example, the u50 has following rails:

  • 12v_aux.

  • 12v_pex.

  • 3v3_pex.

  • vccint (which comes from 12v_aux).

xbtest uses Xilinx® Runtime (XRT) native library C++ device APIs to gather sensor information.

Some sensors are always monitored by default. You can also define other sensors you want to monitor.

All sources listed under the sensor node of the Platform definition JSON file: xbtest_pfm_def.json will be monitored and values will be written in the CSV output files (see xbtest user guide).

Try the following command:

$ xbtest -d <bdf> -g device_mgmt

This command allows to identify:

  • Which type and id are monitored by default.

  • Which id are supported for each type.

    • This is also reported using the following command:

      $ xbutil examine --device <bdf>

INFO      :: ITF_077 :: INPUT_PARSER ::         * Supported "electrical" sensor IDs: "12v_aux", "12v_pex", "3v3_pex", "3v3_aux", "vccint", "vccint_io", "ddr_vpp_btm", "ddr_vpp_top", "5v5_system", "1v2_top", "vcc_1v2_btm", "1v8_top", "0v9_vcc", "12v_sw", "mgt_vtt", "3v3_vcc", "hbm_1v2", "vpp2v5", "12v_aux1", "vcc1v2_i", "v12_in_i", "v12_in_aux0_i", "v12_in_aux1_i", "vcc_aux", "vcc_aux_pmc", "vcc_ram", "0v9_vccint_vcu", "power_consumption"
INFO      :: ITF_077 :: INPUT_PARSER ::         * Supported "thermal" sensor IDs: "pcb_top_front", "pcb_top_rear", "fpga0", "int_vcc", "fpga_hbm"
INFO      :: ITF_077 :: INPUT_PARSER ::         * Supported "mechanical" sensor IDs: "fpga_fan_1"
INFO      :: ITF_077 :: INPUT_PARSER ::         * Here are the IDs of sensors recorded by default for each sensor type:
INFO      :: ITF_077 :: INPUT_PARSER ::             + "electrical": "12v_pex", "12v_aux", "3v3_pex", "vccint", "power_consumption"
INFO      :: ITF_077 :: INPUT_PARSER ::             + "thermal": "fpga0"
INFO      :: ITF_077 :: INPUT_PARSER ::             + "mechanical": "fpga_fan_1"

For example, to monitor thermal sensor fpga_hbm:

"sensor": {
  "0": {
    "type": "thermal",
    "id": "fpga_hbm"
  }
}

gt parameters of platform definition JSON file

The following table describes the parameters supported under the gt node of the Platform definition JSON file: xbtest_pfm_def.json.

gt parameters of platform definition JSON file

Node name

Type

Example

Required / optional

Description

Level 1

Level 2

Level 3

name

string

“top”

Optional

GT name. Typically: top or bottom. Index must be starting at 0 and incrementing by 1: 0/1/….

transceiver_settings

module / cable

tx_differential_swing_control

integer

0

Required

Configure the GTY Transceiver TXDIFFCTRL input to all transmitters. Possible values: from 0 to 31.

This is the default value of gt_tx_diffctrl test JSON parameter (when gt_settings test JSON parameter is set to module/cable). See UltraScale architecture GTY transceivers user guide (UG578) for details.

tx_pre_emphasis

integer

0

Required

Configure the GTY Transceiver TXPRECURSOR input to all transmitters. Possible values: from 0 to 31.

This is the default value of gt_tx_pre_emph test JSON parameter (when gt_settings test JSON parameter is set to module/cable). See UltraScale architecture GTY transceivers user guide (UG578) for details.

tx_post_emphasis

integer

0

Required

Configure the GTY Transceiver TXPOSTCURSOR input to all transmitters. Possible values: from 0 to 31.

This is the default value of gt_tx_pre_emph test JSON parameter (when gt_settings test JSON parameter is set to module/cable). See UltraScale architecture GTY transceivers user guide (UG578) for details.

rx_equaliser

string

“DFE”

Required

Configure the GTY Transceiver RXLPMEN input to all transmitters. Possible values: DFE or LPM.

When set to LPM, the default value of gt_rx_use_lpm test JSON parameter is set to true (when gt_settings test JSON parameter is set to module/cable). See UltraScale architecture GTY transceivers user guide (UG578) for details.

memory parameters of platform definition JSON file

The following table describes the parameters supported under the memory node of the Platform definition JSON file: xbtest_pfm_def.json.

memory parameters of platform definition JSON file

Node name

Type

Example

Required / optional

Description

Level 1

Level 2

0 / 1 / …

name

string

“HBM”

Required

Memory type name. Used to identify a CU based on the CU name (not case sensitive). The same memory type names are defined in the wizard configuration JSON file. See memory: Configure memory CU.

Index must be starting at 0 and incrementing by 1: 0/1/…

DMA parameters of platform definition JSON file

The following table describes the DMA parameters supported under the memory node of the Platform definition JSON file: xbtest_pfm_def.json.

These are not applicable for host memory and for NoDMA platforms.

DMA Parameters of Platform Definition JSON file

Node name

Type

Example

Required / optional

Description

Level 1

Level 2

Level 3

Level 4

0 / 1 / …

dma_bw

write / read

average

integer

5000

Optional

Average write/read DMA BW threshold (in MBps).

If specified, high and low thresholds default to:

  • high = average + 25%

  • low = average - 25%

high

integer

16384

Optional

High write/read DMA BW threshold (in MBps).

If high and average thresholds are not specified, default: based on PCIe speed/width = 256MBps * (2^(speed-1)) * width.

low

integer

9830

Optional

Low write/read DMA BW threshold (in MBps).

If low and average thresholds are not specified, default: high -40%

dma_config

buffer_size

integer

1

Optional

Define default DMA buffer size (in MB). If not defined the default buffer size is 256 MB (or equals memory size if it is below 256 MB).

Recommendation therefore is to use more than one buffer for DMA accesses to HBM on Gen3x4 platforms (e.g. set to 128MB for HBM on Gen3x4).

total_size

integer

256

Optional

Define default DMA total size (in MB). If not defined the default total size is equal to the memory size.

P2P CARD parameters of platform definition JSON file

The following table describes the P2P CARD parameters supported under the memory node of the Platform definition JSON file: xbtest_pfm_def.json.

These are not applicable for host memory and if platform does not support P2P.

P2P CARD parameters of platform definition JSON file

Node name

Type

Example

Required / optional

Description

Level 1

Level 2

Level 3

Level 4

0 / 1 / …

p2p_card_bw

write / read

average

integer

5000

Optional

Average write/read P2P CARD BW threshold (in MBps).

If specified, high and low thresholds default to:

  • high = average + 25 %

  • low = average - 25 %

high

integer

16384

Optional

High write/read P2P CARD BW threshold (in MBps).

If high and average thresholds are not specified, default: based on PCIe speed/width = 256 MBps * (2^(speed-1)) * width.

low

integer

1

Optional

Low write/read P2P CARD BW threshold (in MBps).

If low and average thresholds are not specified, Default: 1

p2p_card_config

buffer_size

integer

1

Optional

Define default P2P CARD buffer size (in MB). If not defined the default buffer size is 256 MB (or equals memory size if it is below 256 MB).

total_size

integer

256

Optional

Define default P2P CARD total size (in MB). If not defined the default total size is equal to the memory size.

P2P NVME parameters of platform definition JSON file

The following table describes the P2P NVME parameters supported under the memory node of the Platform definition JSON file: xbtest_pfm_def.json.

These are not applicable for host memory and if platform does not support P2P.

P2P NVME parameters of platform definition JSON file

Node name

Type

Example

Required / optionaL

Description

Level 1

Level 2

Level 3

Level 4

0 / 1 / …

p2p_nvme_bw

write / read

average

integer

5000

Optional

Average write/read P2P NVME BW threshold (in MBps).

If specified, high and low thresholds default to:

  • high = average + 25 %

  • low = average - 25 %

high

integer

16384

Optional

High write/read P2P NVME BW threshold (in MBps).

If high and average thresholds are not specified, default: based on PCIe speed/width = 256 MBps * (2^(speed-1)) * width.

low

integer

1

Optional

Low write/read P2P NVME BW threshold (in MBps).

If low and average thresholds are not specified, Default: 1

p2p_nvme_config

buffer_size

integer

1

Optional

Define default P2P NVME buffer size (in MB). If not defined the default buffer size is 256 MB (or equals memory size if it is below 256 MB).

total_size

integer

256

Optional

Define default P2P NVME total size (in MB). If not defined the default total size is equal to the memory size.

CU parameters of platform definition JSON file

The following table describes the CU parameters supported under the memory node of the Platform definition JSON file: xbtest_pfm_def.json.

CU parameters of platform definition JSON file

Node name

Type

Example

Required / optional

Description

Level 1

Level 2

Level 3

Level 4

Level 5

0 / 1 / …

cu_bw

only_wr

write

average

integer

1000

Required

  • if high and low not specified

Average write BW threshold (in MBps) in only_wr test mode.

If specified, high and low thresholds default to:

  • high = average + 10 %

  • low = average - 10 %

high

integer

1100

Required if average not specified

High write BW threshold (in MBps) in only_wr test mode.

low

integer

900

Required

  • if average not specified

Low write BW threshold (in MBps) in only_wr test mode.

only_rd

read

average

integer

1000

Required if high and low not specified

Average write BW threshold (in MBps) in only_rd test mode.

If specified, high and low thresholds default to:

  • high = average + 10 %

  • low = average - 10 %

high

integer

1100

Required

  • if average not specified

High write BW threshold (in MBps) in only_rd test mode.

low

integer

900

Required

  • if average not specified

Low write BW threshold (in MBps) in only_rd test mode.

alt_wr_rd

write / read

average

integer

1000

Optional

Average write/read BW threshold (in MBps) in alternate_wr_rd test mode.

  • Default: (cu_bw.only_wr. write/read.average + cu_bw.only_rd. write/read.average)/4.

If specified, high and low thresholds default to:

  • high = average + 10 %

  • low = average - 10 %

high

integer

1100

Optional

High write/read BW threshold (in MBps) in alternate_wr_rd test mode.

  • Default: (cu_bw.only_wr. write/read.high + cu_bw.only_rd. write/read.high )/4.

low

integer

900

Optional

Low write/read BW threshold (in MBps) in alternate_wr_rd test mode.

  • Default: (cu_bw.only_wr. write/read.low+ cu_bw.only_rd. write/read.low )/4.

simul_wr_rd

write / read

average

integer

1000

Optional

Average write/read BW threshold (in MBps) in simultaneous_wr_rd test mode.

  • Default: (cu_bw.only_wr. write/read.average + cu_bw.only_rd. write/read.average)/4.

If specified, high and low thresholds default to:

  • high = average + 10 %

  • low = average - 10 %

high

integer

1100

Optional

High write/read BW threshold (in MBps) in simultaneous_wr_rd test mode.

  • Default: (cu_bw.only_wr. write/read.high + cu_bw.only_rd. write/read.high )/4.

low

integer

900

Optional

Low write/read BW threshold (in MBps) in simultaneous_wr_rd test mode.

  • Default: (cu_bw.only_wr. write/read.low+ cu_bw.only_rd. write/read.low )/4.

cu_latency

only_wr

write

average

integer

100

Required

  • if high and low not specified

Average write Latency threshold (in ns) in only_wr test mode.

If specified, high and low thresholds default to:

  • high = average + 10 %

  • low = average - 10 %

high

integer

110

Required

  • if average not specified

High write Latency threshold (in ns) in only_wr test mode.

low

integer

90

Required

  • if average not specified

Low write Latency threshold (in ns) in only_wr test mode.

only_rd

read

average

integer

100

Required

  • if high and low not specified

Average read Latency threshold (in ns) in only_rd test mode.

If specified, high and low thresholds default to:

  • high = average + 10 %

  • low = average - 10 %

high

integer

110

Required

  • if average not specified

High read Latency threshold (in ns) in only_rd test mode.

low

integer

90

Required

  • if average not specified

Low read Latency threshold (in ns) in only_rd test mode.

alt_wr_rd

write / read

average

integer

100

Optional

Average write/read Latency threshold (in ns) in alternate_wr_rd test mode.

  • Default: cu_latency.only_wr/rd. write/read.average

If specified, high and low thresholds default to:

  • high = average + 10 %

  • low = average - 10 %

high

integer

110

Optional

High write/read Latency threshold (in ns) in alternate_wr_rd test mode.

  • Default: cu_latency.only_wr/rd. write/read.high

low

integer

90

Optional

Low write/read Latency threshold (in ns) in alternate_wr_rd test mode.

  • Default: cu_latency.only_wr/rd. write/read.low

simul_wr_rd

write / read

average

integer

100

Optional

Average write/read Latency threshold (in ns) in simultaneous_wr_rd test mode.

  • Default: cu_latency.only_wr/rd. write/read.high

If specified, high and low thresholds are computed as:

  • high = average + 10 %

  • low = average - 10 %

high

integer

110

Optional

High write/read Latency threshold (in ns) in simultaneous_wr_rd test mode.

  • Default: cu_latency.only_wr/rd. write/read.high

low

integer

90

Optional

Low write/read Latency threshold (in ns) in simultaneous_wr_rd test mode.

  • Default: cu_latency.only_wr/rd. write/read.low

cu_rate

only_wr

write

nominal

integer

47

Optional

Nominal write CU rate (in %) in only_wr test mode.

  • Default: 100.

only_rd

read

nominal

integer

40

Optional

Nominal read CU rate (in %) in only_rd test mode.

  • Default: 100.

alt_wr_rd

write / read

nominal

integer

40

Optional

Nominal write/read CU rate (in %) in alternate_wr_rd test mode.

  • Default: cu_rate.only_wr/rd. write/read.nominal

simul_wr_rd

write / read

nominal

integer

23

Optional

Nominal write/read CU rate (in %) in simultaneous_wr_rd test mode.

  • Default: cu_rate.only_wr/rd. write/read.nominal

cu_burst_size

only_wr

write

nominal

integer

2048

Optional

Nominal write burst size (in Bytes) in only_wr test mode.

  • Default: 64*AXI data size if AXI data size = 512 bits, else 128*AXI data size

  • Possible values: 128, 256, 512, 1024, 2048, 4096

only_rd

read

nominal

integer

2048

Optional

Nominal read burst size (in Bytes) in only_rd test mode.

  • Default: 64*AXI data size if AXI data size = 512 bits, else 128*AXI data size

  • Possible values: 128, 256, 512, 1024, 2048, 4096

alt_wr_rd

write / read

nominal

integer

2048

Optional

Nominal write/read burst size (in Bytes) in alternate_wr_rd test mode.

  • Default: cu_burst_size.only_wr/rd. write/read.nominal

  • Possible values: 128, 256, 512, 1024, 2048, 4096

simul_wr_rd

write / read

nominal

integer

1024

Optional

Nominal write/read burst size (in Bytes) in simultaneous_wr_rd test mode.

  • Default: cu_burst_size.only_wr/rd. write/read.nominal

  • Possible values: 128, 256, 512, 1024, 2048, 4096

cu_outstanding

only_wr

write

nominal

integer

4

Optional

Nominal maximum number of outstanding writes in only_wr test mode.

  • Default: 0 (not limited)

  • Possible values: 0 to 255

only_rd

read

nominal

integer

4

Optional

Nominal maximum number of outstanding reads in only_rd test mode.

  • Default: 0 (not limited)

  • Possible values: 0 to 255

alt_wr_rd

write / read

nominal

integer

4

Optional

Nominal maximum number of outstanding writes/reads in alternate_wr_rd test mode.

  • Default: cu_outstanding.only_wr/rd. write/read.nominal

  • Possible values: 0 to 255

simul_wr_rd

write / read

nominal

integer

4

Optional

Nominal maximum number of outstanding writes/reads in simultaneous_wr_rd test mode.

  • Default: cu_outstanding.only_wr/rd. write/read.nominal

  • Possible values: 0 to 255

Platform definition JSON file template

Here is a template/view of Platform definition JSON file: xbtest_pfm_def.json containing all the parameters listed above:

{
  "device" : {
    "runtime" : {
      "download_time" : <download_time>
    },
    "sensor": {
      "<sensor_idx>": {
        "type": "<type>",
        "id": "<id>"
      }
    },
    "gt" : {
      "<gt_idx>" : {
        "transceiver_settings" : {
          "<module/cable>" : {
            "tx_differential_swing_control" : <tx_differential_swing_control>,
            "tx_pre_emphasis" : <tx_pre_emphasis>,
            "tx_post_emphasis" : <tx_post_emphasis>,
            "rx_equaliser" : "<rx_equaliser>"
          }
        }
      }
    },
    "memory" : {
      "<mem_idx>": {
        "name": "<name>",
        "dma_bw": {
          "write": {
            "average": <average>
          },
          "read": {
            "average": <average>
          }
        },
        "dma_config": {
          "buffer_size": <buffer_size>,
          "total_size": <total_size>
        },
        "p2p_card_bw": {
          "write": {
            "average": <average>
          },
          "read": {
            "average": <average>
          }
        },
        "p2p_card_config": {
          "buffer_size": <buffer_size>,
          "total_size": <total_size>
        },
        "p2p_nvme_bw": {
          "write": {
            "average": <average>
          },
          "read": {
            "average": <average>
          }
        },
        "p2p_nvme_config": {
          "buffer_size": <buffer_size>,
          "total_size": <total_size>
        },
        "cu_rate": {
          "only_wr": {
            "write": {
              "nominal": <nominal>
            }
          },
          "only_rd": {
            "read": {
              "nominal": <nominal>
            }
          },
          "simul_wr_rd": {
            "write": {
              "nominal": <nominal>
            },
            "read": {
              "nominal": <nominal>
            }
          }
        },
        "cu_outstanding": {
          "only_wr": {
            "write": {
              "nominal": <nominal>
            }
          },
          "only_rd": {
            "read": {
              "nominal": <nominal>
            }
          },
          "simul_wr_rd": {
            "write": {
              "nominal": <nominal>
            },
            "read": {
              "nominal": <nominal>
            }
          }
        },
        "cu_bw": {
          "only_wr": {
            "write": {
              "average": <average>
            }
          },
          "only_rd": {
            "read": {
              "average": <average>
            }
          },
          "simul_wr_rd": {
            "write": {
              "average": <average>
            },
            "read": {
              "average": <average>
            }
          }
        },
        "cu_latency": {
          "only_wr": {
            "write": {
              "average": <average>
            }
          },
          "only_rd": {
            "read": {
              "average": <average>
            }
          },
          "simul_wr_rd": {
            "write": {
              "average": <average>
            },
            "read": {
              "average": <average>
            }
          }
        }
      }
    }
  }
}