Software APIs¶

The AIE test harness includes software APIs for user to easily build SW applications to test an AIE graph on hardware board. The SW application is executed on the embedded ARM processor of the Versal device. The APIs are designed to structure the test applications following these simple steps:

Initialize the device, load the xclbin, and inferring the testing mode
Run the AIE graph as well as the PL data mover
Configure the DMA channels and start the data transfers between the PL and AIE graph
Wait for all the data to be sent/received
Report performance for each channel on performance testing mode, and optionally check correctness of results on functional testing mode or performance testing mode with limited data size

The test harness APIs are included in include/test_harness_mgr.hpp.

Initialization¶

class test_harness_mgr¶: The test harness manager class. This class encapsulates the necessary runtime objects to interact with the hardware DMA channels and the AIE graph. All test harness APIs belong to this class.

Template Parameters

unsigned int N: Maximal number of PLIOs (for input/output respectively). Must be set to 36 for VCK190 or to 16 for VEK280.
unsigned int W: PLIO port-width in bytes. Must be set to 16 for VCK190 or VEK280.
unsigned int D: Depth of the 128-bit width cache in each PLIO channel. Must be set to 4096 for VCK190 or to 8192 for VEK280.

test_harness_mgr::test_harness_mgr(unsigned int device_index, std::string xclbin_path, std::vector<std::string> graph_name)¶: The test harness manager class constructor. Loads the xclbin to the device and initializes the various test harness runtime objects.

Parameters

unsigned int device_index: The device ID of the testing board, typically it should be zero
std::string xclbin_path: The path and name of the xclbin file to be loaded and used for testing. The name of the xclbin file must match one of 3 supported values: vck190_test_harness_func.xclbin for functional testing on VCK190, vck190_test_harness_perf.xclbin for performance testing on VCK190, vek280_test_harness.xclbin for performance testing on VEK280. By default, the xclbin file(s) are generated by the corresponding test harness packaging script and placed in the pkg.hw.<shell name>. folder of the test application.
std::vector<std::string> graph_name: The vector of graph names in the libadf.a packaged in the xclbin file

Running the AIE Graph¶

void test_harness_mgr::runAIEGraph(unsigned int g_idx, unsigned int iters)¶: Run the specified AI Engine graph for a specific number of iterations. To ensure accurate performance results, this function should be called before test_harness_mgr::runTestHarness() when user wants to profile a valid performance after the HW board-run.

Parameters

unsigned int g_idx: The index of the graph in the vector of graph names passed to the class constructor. For designs with a single graph, this argument is zero.
unsigned int iters: The number of graph iterations to run

Running the Test Harness¶

enum channel_index¶: Enumerated type listing the index of each DMA channel. The enumerated values corresponding to the names of the predefined PLIOs: PLIO_01_TO_AIE, PLIO_02_TO_AIE, etc…

Definition

struct test_harness_args {
 channel_index idx;
 unsigned int size_in_byte;
 unsigned int replay;
 uint64_t delay;
 char* data;
}

Members

idx: The index of the DMA channel to be used, specified using the channel_index enum. The index corresponds to the name of the targeted AIE PLIO, and implicitly specifies the direction of the data transfer.
size_in_byte: The size (in bytes) of one data frame to be transferred to or from the AIE
replay: Number of replays used for test harness to perform the data transfer between PL and AIE multiple times
delay: The start delay (in PL clock cycles) for this channel
data: Pointer to the data that you want read or receive

void test_harness_mgr::runTestHarness(std::vector<test_harness_args> args)¶: Run the test harness using the specified DMA channel arguments. In performance testing mode, to ensure accurate performance results, this function should be called after test_harness_mgr::runAIEGraph().

Parameters

std::vector<test_harness_args> args: A vector of DMA channel arguments

Waiting for Completion¶

void test_harness_mgr::waitForRes(int graph_timeout_millisec)¶: Wait for all DMA engines to send and receive the required amount of data, then wait for the AIE graph to finish and get back the results to the host application.

Parameters

int graph_timeout_millisec: Timeout limit in milliseconds for AIE graph to finish. The timeout only applies to the completion of the AIE graph iterations. This function can be blocked permanently if the DMA channels are configured to send or receive more data than what the AIE graph will actually consume or produce.

Reporting Performance¶

void test_harness_mgr::printPerf()¶: Print the total number of cycles elapsed between the start and the end of the data transfer for each DMA channel. Must be called once the test_harness_mgr::waitForRes() is returned. It is important to note that valid profiling numbers are only provided when running in the performance testing mode.