Test Engine FPGA IP User Guide: Agilex™ 3, Agilex™ 5, and Agilex™ 7 FPGAs

Download PDF
ID 817758
Date 3/31/2025
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents
Document Table of Contents x
1. About the Test Engine FPGA IP 2. Test Engine IP - Introduction 3. Parameterizing the Test Engine IP 4. Test Engine IP - Interface Signals 5. Test Engine IP - Software 6. Test Engine IP - Limitations 7. Document Revision History for the Test Engine FPGA IP User Guide
1. About the Test Engine FPGA IP x
1.1. Release Information
2. Test Engine IP - Introduction x
2.1. Test Engine IP Feature Support
3. Parameterizing the Test Engine IP x
3.1. Parameters 3.2. Drivers Parameters 3.3. Remote Access Parameters
3.2. Drivers Parameters x
3.2.1. CSR AXI4-Lite Driver Parameters 3.2.2. Memory AXI4 Driver Parameters 3.2.3. Memory Status Driver Parameters 3.2.4. Memory Reset Driver Parameters 3.2.5. CAM AXI4-Stream Driver Parameters
4. Test Engine IP - Interface Signals x
4.1. Remote Interface Signals 4.2. I/O PLL Interface Signals 4.3. Status Interface Signals 4.4. Global CSR interface Signals 4.5. Memory AXI4 Driver Interface Signals 4.6. CSR AXI-Lite Driver Interface Signals 4.7. Memory Status Driver Interface Signals 4.8. Memory Reset Driver Interface Signals 4.9. CAM AXI-Stream Driver Interface Signals 4.10. Registers
4.10. Registers x
4.10.1. Global Control Registers 4.10.2. Memory AXI4 Driver Registers 4.10.3. CSR AXI4-Lite Driver Registers 4.10.4. Memory Status Driver Registers 4.10.5. Memory Reset Driver Registers 4.10.6. CAM AXI4-Stream Driver Registers
4.10.1. Global Control Registers x
4.10.1.1. version_0 4.10.1.2. version_1 4.10.1.3. ctrl_status_0 4.10.1.4. driver_ctrl_status_1 4.10.1.5. driver_run_bitmask_0 4.10.1.6. driver_run_bitmask_1 4.10.1.7. driver_run_bitmask_2 4.10.1.8. driver_run_bitmask3 4.10.1.9. driver_done_bitmask_0 4.10.1.10. driver_done_bitmask_1 4.10.1.11. driver_done_bitmask_2 4.10.1.12. driver_done_bitmask_3 4.10.1.13. driver_error_bitmask_0 4.10.1.14. driver_error_bitmask_1 4.10.1.15. driver_error_bitmask_2 4.10.1.16. driver_error_bitmask_3
4.10.2. Memory AXI4 Driver Registers x
4.10.2.1. version_lo 4.10.2.2. version_hi 4.10.2.3. ctrl_stat_lo 4.10.2.4. ctrl_stat_hi 4.10.2.5. scratchpad_lo 4.10.2.6. scratchpad_hi 4.10.2.7. wr_log_ram_stat_lo 4.10.2.8. wr_log_ram_stat_hi 4.10.2.9. wr_log_ram_ctrl_lo 4.10.2.10. wr_log_ram_ctrl_hi 4.10.2.11. rd_log_ram_stat_lo 4.10.2.12. rd_log_ram_stat_hi 4.10.2.13. rd_log_ram_ctrl_lo 4.10.2.14. rd_log_ram_ctrl_hi 4.10.2.15. wr_err_counters_0_lo 4.10.2.16. wr_err_counters_0_hi 4.10.2.17. rd_err_counters_0_lo 4.10.2.18. rd_err_counters_0_hi 4.10.2.19. rd_err_counters_1_lo 4.10.2.20. rd_err_counters_1_hi 4.10.2.21. rd_pnf_0_lo 4.10.2.22. rd_pnf_0_hi 4.10.2.23. rd_pnf_1_lo 4.10.2.24. rd_pnf_1_hi 4.10.2.25. rd_pnf_2_lo 4.10.2.26. rd_pnf_2_hi 4.10.2.27. rd_pnf_3_lo 4.10.2.28. rd_pnf_3_hi 4.10.2.29. rd_pnf_4_lo 4.10.2.30. rd_pnf_4_hi 4.10.2.31. rd_pnf_5_lo 4.10.2.32. rd_pnf_5_hi 4.10.2.33. rd_pnf_6_lo 4.10.2.34. rd_pnf_6_hi 4.10.2.35. rd_pnf_7_lo 4.10.2.36. rd_pnf_7_hi 4.10.2.37. rd_pnf_8_lo 4.10.2.38. rd_pnf_8_hi 4.10.2.39. rd_pnf_9_lo 4.10.2.40. rd_pnf_9_hi 4.10.2.41. rd_pnf_10_lo 4.10.2.42. rd_pnf_10_hi 4.10.2.43. rd_pnf_11_lo 4.10.2.44. rd_pnf_11_hi 4.10.2.45. rd_pnf_12_lo 4.10.2.46. rd_pnf_12_hi 4.10.2.47. rd_pnf_13_lo 4.10.2.48. rd_pnf_13_hi 4.10.2.49. rd_pnf_14_lo 4.10.2.50. rd_pnf_14_hi 4.10.2.51. rd_pnf_15_lo 4.10.2.52. rd_pnf_15_hi 4.10.2.53. rd_pnf_16_lo 4.10.2.54. rd_pnf_16_hi 4.10.2.55. rd_pnf_17_lo 4.10.2.56. rd_pnf_17_hi 4.10.2.57. rd_pnf_18_lo 4.10.2.58. rd_pnf_18_hi 4.10.2.59. rd_pnf_19_lo 4.10.2.60. rd_pnf_19_hi 4.10.2.61. ter_dq_mask_0_lo 4.10.2.62. ter_dq_mask_0_hi 4.10.2.63. ter_dq_mask_1_lo 4.10.2.64. ter_dq_mask_1_hi 4.10.2.65. ter_lo 4.10.2.66. ter_hi
5. Test Engine IP - Software x
5.1. Overview 5.2. Python library 5.3. User programs 5.4. System Console library
5.2. Python library x
5.2.1. CSR AXI4-Lite Driver APIs 5.2.2. Memory AXI4 Driver APIs 5.2.3. General compiler APIs
5.2.1. CSR AXI4-Lite Driver APIs x
5.2.1.1. read_cmd 5.2.1.2. write_cmd
5.2.2. Memory AXI4 Driver APIs x
5.2.2.1. dq_alu_echo_op 5.2.2.2. dq_alu_invert_op 5.2.2.3. dq_alu_rotate_op 5.2.2.4. dq_alu_prbs_op 5.2.2.5. data_eq_dq_op 5.2.2.6. data_eq_raw_op 5.2.2.7. data_eq_addr_op 5.2.2.8. data_eq_id_op 5.2.2.9. dm_alu_echo_op 5.2.2.10. dm_alu_invert_op 5.2.2.11. dm_alu_rotate_op 5.2.2.12. dm_alu_prbs_op 5.2.2.13. strb_eq_dm_op 5.2.2.14. strb_eq_raw_op 5.2.2.15. addr_alu_echo_op 5.2.2.16. addr_alu_incr_op 5.2.2.17. addr_alu_rand_op 5.2.2.18. addr_op 5.2.2.19. write_worker_op 5.2.2.20. read_worker_op 5.2.2.21. write_cmd 5.2.2.22. read_cmd 5.2.2.23. wait_writes_cmd 5.2.2.24. wait_reads_cmd 5.2.2.25. sleep_cmd 5.2.2.26. driver_post_cmd 5.2.2.27. driver_wait_cmd 5.2.2.28. parallel_cmd 5.2.2.29. loop_cmd
5.2.3. General compiler APIs x
5.2.3.1. get_drivers 5.2.3.2. attach 5.2.3.3. dump
5.3. User programs x
5.3.1. Programs for Memory AXI4 Driver 5.3.2. Programs for CSR AXI4-Lite Driver
5.3.1. Programs for Memory AXI4 Driver x
5.3.1.1. Basic tutorials 5.3.1.2. Advanced tutorials 5.3.1.3. EMIF traffic patterns (for IO96B architecture) 5.3.1.4. HBM2E traffic patterns 5.3.1.5. MemSS traffic patterns (for IO96A architecture) 5.3.1.6. Traffic Program Builders 5.3.1.7. gencmd Usage Description Parameters Returns
5.3.1.1. Basic tutorials x
5.3.1.1.1. tut1_block_rw 5.3.1.1.2. tut2_byteen_test 5.3.1.1.3. tut3_instr_resume 5.3.1.1.4. tut4_parallel_rw 5.3.1.1.5. tut5_multi_id 5.3.1.1.6. tut6_custom_bw 5.3.1.1.7. tut7_driver_sync
5.3.1.2. Advanced tutorials x
5.3.1.2.1. adv1_basic_rw 5.3.1.2.2. adv2_addr_fields 5.3.1.2.3. adv3_instr_resume
5.3.1.3. EMIF traffic patterns (for IO96B architecture) x
5.3.1.3.1. emif_tg_emulation 5.3.1.3.2. emif_tg_emulation_lite 5.3.1.3.3. emif_tg_emulation_long 5.3.1.3.4. emif_tg_emulation_inf 5.3.1.3.5. emif_narrow_transfer
5.3.1.4. HBM2E traffic patterns x
5.3.1.4.1. hbm_simulation1 5.3.1.4.2. hbm_simulation 5.3.1.4.3. hbm_mem_traversal_seq 5.3.1.4.4. hbm_mem_traversal_rand
5.3.1.5. MemSS traffic patterns (for IO96A architecture) x
5.3.1.5.1. memss_default
5.3.1.6. Traffic Program Builders x
5.3.1.6.1. mem_traversal
5.3.2. Programs for CSR AXI4-Lite Driver x
5.3.2.1. HBM2E traffic patterns 5.3.2.2. MemSS traffic patterns (for IO96A architecture)
5.3.2.1. HBM2E traffic patterns x
5.3.2.1.1. hbm_simulation1
5.3.2.2. MemSS traffic patterns (for IO96A architecture) x
5.3.2.2.1. memss_default
5.4. System Console library x
5.4.1. testengine_num_drivers 5.4.2. testengine_driver_list 5.4.3. testengine_run 5.4.4. testengine_reset 5.4.5. testengine_get_errors 5.4.6. testengine_get_done 5.4.7. testengine_status 5.4.8. testengine_reprogram 5.4.9. testengine_axi4_parse_errors
1. About the Test Engine FPGA IP
2. Test Engine IP - Introduction
3. Parameterizing the Test Engine IP
4. Test Engine IP - Interface Signals
5. Test Engine IP - Software
6. Test Engine IP - Limitations
7. Document Revision History for the Test Engine FPGA IP User Guide

5.3.1.7. gencmd

Usage

def traffic_patterns.MemAxi4DriverPrograms.gencmd (self, str cmd, int iters=1, Union[int, List[int], str, List[str]] addr="seq", Union[None, Tuple[int, int]] addr_range=None, Union[None, int, List[int], str, List[str]] data="addr", Union[int, List[int], str, List[str]] strb=-1, Union[int, List[int]] bl=1, Union[float, List[float]] size=1.0, Union[int, List[int]] burst=axburst_incr, Union[int, List[int]] lock=0, Union[int, List[int]] cache=0, Union[int, List[int]] prot=0, Union[int, List[int]] qos=0, Union[int, List[int]] region=0, Union[int, List[int]] auser=0, Union[int, List[int]] resp=xresp_okay, Union[int, List[int]] id=0, Union[float, Tuple[int, int]] addr_bw=1.0, Union[float, Tuple[int, int]] data_bw=1.0, Union[float, Tuple[int, int]] resp_bw=1.0, Union[bool, List[bool]] resume=False, bool inspect=True)

Description

Helper function to construct a write or read instruction for the Memory AXI Driver.

By default, the write/read instruction generates a single AXI transaction that accesses sequential addresses with data matching the address. You can customize this default behavior by overriding the appropriate input arguments to this function.

Parameters

cmd
Supported values are:

  • "wr": Generate AXI write transactions

  • "rd": Generate AXI read transactions

iters

Number of AXI write/read transactions to generate.

addr
The data-type of the value determines how the value is parsed:

  • Integer: AxADDR value

  • String: Preset for AxADDR pattern. Supported values are:
    • "seq[_strideX][_echoX]": Sequential access. Optional modifiers:

      • _strideX: X must be an integer, and will be multiplied to address increment. Ex: _stride2 multiplies increment by 2.

      • _echoX: X must be an integer, indicating number of times to repeat each address. Ex: _echo1 repeats each address once, i.e. addr_0, addr_0, addr_1, addr_1, addr_2, addr_2, ...

    • "rand[_echoX]": Random access. Optional modifiers:

      • _echoX: X must be an integer, indicating number of times to repeat each address. Ex: _echo1 repeats each address once, i.e. addr_0, addr_0, addr_1, addr_1, addr_2, addr_2, ...

addr_range

Address range formatted as a tuple (lo_addr, hi_addr), where lo_addr <= AxADDR <= hi_addr. Ex: (0x0000, 0x0FFF). By default the address range matches the full address space derived based on address port width. addr_range is only applicable if addr preset is used.

data
The data-type of the value determines how the value is parsed:

  • None: Skip error checking for RDATA (only applicable for 'read' command)

  • Integer: WDATA value for 'write' transaction, expected RDATA value for 'read' transaction

  • String: Preset for xDATA pattern. Supported values are:

    • "addr": xDATA matches the address of the corresponding command

    • "id": xDATA matches the AxID of the corresponding command

    • "clock": Every DQ pin toggles between 1 and 0 on every clock cycle

    • "pulse0": Every DQ pin outputs a long train of 1s with a single intermittent 0

    • "pulse1": Every DQ pin outputs a long train of 0s with a single intermittent 1

    • "walking0": Each DQ pin within a byte lane takes turns outputting a single 0. Useful for finding crosstalk issues and normally used for simultaneous switching noise (SSN) testing. The data bit (DQ pin) that has a different value from the rest will be more likely to be affected by the rest of the data bits, especially the adjacent bits.

    • "walking1": Each DQ pin within a byte lane takes turns outputting a single 1. Useful for finding crosstalk issues and normally used for simultaneous switching noise (SSN) testing. The data bit (DQ pin) that has a different value from the rest will be more likely to be affected by the rest of the data bits, especially the adjacent bits.

    • "prbs7[_echoX]": Every DQ pin outputs a PRBS7 pattern initialized with a unique seed. Optional modifiers:

      • _echoX: X must be an integer, indicating number of times to repeat each data value. Ex: _echo1 repeats each data once, i.e. data_0, data_0, data_1, data_1, data_2, data_2, ...

    • "prbs15[_echoX]": Every DQ pin outputs a PRBS15 pattern initialized with a unique seed. Optional modifiers:

      • _echoX: X must be an integer, indicating number of times to repeat each data value. Ex: _echo1 repeats each data once, i.e. data_0, data_0, data_1, data_1, data_2, data_2, ...

    • "prbs23[_echoX]": Every DQ pin outputs a PRBS23 pattern initialized with a unique seed. Optional modifiers:

      • _echoX: X must be an integer, indicating number of times to repeat each data value. Ex: _echo1 repeats each data once, i.e. data_0, data_0, data_1, data_1, data_2, data_2, ...

    • "prbs31[_echoX]": Every DQ pin outputs a PRBS31 pattern initialized with a unique seed. Optional modifiers:

      • _echoX: X must be an integer, indicating number of times to repeat each data value. Ex: _echo1 repeats each data once, i.e. data_0, data_0, data_1, data_1, data_2, data_2, ...

strb
The data-type of the value determines how the value is parsed:

  • Integer: WSTRB value for 'write' transaction, bytemask for error checking RDATA for 'read' transaction

  • String: Preset for xSTRB pattern. Supported values are:

    • "prbs7": Every DM pin outputs a PRBS7 pattern initialized with a unique seed.

    • "prbs15": Every DM pin outputs a PRBS15 pattern initialized with a unique seed.

    • "prbs23": Every DM pin outputs a PRBS23 pattern initialized with a unique seed.

    • "prbs31": Every DM pin outputs a PRBS31 pattern initialized with a unique seed.

    • "byteen_test": Continually generate a random xSTRB (held constant within a burst) followed by its inverse (held constant within a burst). This option can be used for byte-enable testing.

bl

Burst length value. AxLEN is derived based on this parameter (AxLEN = bl - 1)

size

Fraction of data width to transfer. Ex: 1, 0.5, 0.25, 0.125, ... AxSIZE is derived based on this parameter.

burst

AxBURST value

lock

AxLOCK value

cache

AxCACHE value

prot

AxPROT value

qos

AxQOS value

region

AxREGION value

auser

AxUSER value

resp
The data-type of the value determines how the value is parsed:

  • None: Skip error checking for xRESP

  • Integer: Expected xRESP value. If expected value is an error response RDATA checking will be disabled.

id
The data-type of the value determines how the value is parsed:

  • Integer: AxID value

  • List: Number of unique AxIDs in this list determines number of workers. And the list itself represents the AxID sequence. NOTE: Each AxID is represented by a unique "worker", which can generate a distinct traffic pattern for that specific AxID. The address range is evenly split among all workers. Ex: addr_range 0x00000000-0x3fffffff split among 4 workers is 0x00000000-0x0fffffff, 0x10000000-0x1fffffff, 0x20000000-0x2fffffff, 0x30000000-0x3fffffff You can customize the traffic stream for each worker by providing a list of values (for supported parameters listed below). Ex: bl=4 will use burst length 4 for all workers, bl=[2, 4] will use burst lengths 2 and 4 for the first and second workers respectively. The following parameters can be customized per worker by providing a list: addr, data, strb, bl, size, burst, lock, cache, prot, qos, region, auser, resp, resume

addr_bw
AW/AR channel bandwidth specified using duty-cycle. The data-type of the value determines how the value is parsed:

  • Float: Duty-cycle specified as percentage. Ex: 0.5 for 50% duty-cycle. Minimum supported value is 0.125.

  • Tuple: Duty-cycle specified as (pulse width, period). Ex: (1, 2) or (4, 8). Minimum supported value is (1, 8).

data_bw
W channel bandwidth specified using duty-cycle. The data-type of the value determines how the value is parsed:

  • Float: Duty-cycle specified as percentage. Ex: 0.5 for 50% duty-cycle. Minimum supported value is 0.125.

  • Tuple: Duty-cycle specified as (pulse width, period). Ex: (1, 2) or (4, 8). Minimum supported value is (1, 8).

resp_bw
B/R channel bandwidth specified using duty-cycle. The data-type of the value determines how the value is parsed:

  • Float: Duty-cycle specified as percentage. Ex: 0.5 for 50% duty-cycle. Minimum supported value is 0.02.

  • Tuple: Duty-cycle specified as (pulse width, period). Ex: (1, 2) or (4, 8). Minimum supported value is (1, 64).

resume

Continue the addr, data, and strbl pattern preset from previous command. If resume=True, addr, data, and strb values must match the previous command.

inspect

Scan the traffic pattern for potential issues and throw errors. Set inspect=False to print warnings instead.

Returns

List of write or read instruction(s) for the Memory AXI Driver's kernel. NOTE: you can use Python's splat operator (*) to unpack the list for insertion into a larger list. Ex: my_prog = [*gencmd(...), *gencmd(...), ...]

Level Two Title