Software APIs¶

The AIE test harness includes software APIs to easily build SW applications to test an AIE graph on hardware board. The SW application is executing 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 and load the xclbin
Run the AIE graph
Configure the DMA channels and start the data transfers to the AIE graph
Wait for all the data to be received
Report performance for each channel, and optionally check correctness of results

The test harness APIs are included in include/vck190_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.

test_harness_mgr::test_harness_mgr(unsigned int device_index, std::string xclbin_file_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_file_path: The path and name of the xclbin file to be loaded and used for testing. By default, the name of the xclbin file generated by the test harness packaging script is vck190_test_harness.xclbin and it is placed in the same 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 specified number of iterations. To ensure accurate performance results, this function should be called before test_harness_mgr::runTestHarness().

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;
 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
delay: The start delay (in 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. 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 expected amount of data, then wait for the AIE graph to finish, then 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 block indefinitely if the DMA channels are configured to send or receive more data than what the AIE graph will 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. Can only be called after test_harness_mgr::waitForRes() returns.