How to Use Burst Data Transfer Mode - 2022.1 English

Vitis Model Composer User Guide (UG1483)

Document ID
UG1483
Release Date
2022-05-26
Version
2022.1 English

The simplest way for you to start using burst data transfer mode is via an automatically generated test bench script. Advanced users can make use of the HWCosim API exposed via the MATLAB Hwcosim objects that are shipped with Model Composer.

Automatic Testbench Generation

Testbench generation is run alongside the hardware co-simulation compilation flow. Open the System Generator token in the Simulink model and wait for the dialog box to appear. The first tab shows the Compilation options. A drop-down list shows the available compilation targets. After selecting one of the two hardware co-simulation flows (depending on which one is available for the selected board), the Settings button will be enabled and when selected it will open a secondary dialog box where burst mode and the desired FIFO depth can be chosen. After burst mode has been turned on, you can enable the automatic creation of an M-HWCosim test bench script by enabling Create testbench at the bottom of the Compilation tab.

Figure 1. Create Test Bench

The test generator will produce this M-script file in the Target Directory:

<design_name>_<sub_system>_hwcosim_test.m

You can run this script from the MATLAB® console. The script will also run the Simulink model to determine the stimulus data driven to the Xilinx® Gateway In blocks (from the other Simulink source blocks or MATLAB variables), while also capturing the expected output produced by the Xilinx® Block Design (BD) and exporting the data to the Target directory as these separate data files:

<design_name>_<sub_system>_<port_name>.dat

To run the test bench, you can open the MATLAB console, change directory to the Target Directory, and run the script by name. If the test fails this will be printed on the console, and the failing comparisons will be listed in this file:

<design_name>_<sub_system>_hwcosim_test.result

Burst Mode Testbench Script

The following is a test bench generated for an example design as part of the compilation flow:

%% project3_burst_hwcosim_test
% project3_burst_hwcosim_test is an automatically generated example MCode
% function that can be used to open a hardware co-simulation (hwcosim) target,
% load the bitstream, write data to the hwcosim target's input blocks, fetch
% the returned data, and verify that the test passed. The returned value of
% the test is the amount of time required to run the test in seconds.
% Fail / Pass is indicated as an error or displayed in the command window.
 
%%
% PLEASE NOTE that this file is automatically generated and gets re-created
% every time the Hardware Co-Simulation flow is run. If you modify any part
% of this script, please make sure you save it under a new name or in a
% different location.
 
%%
% The following sections exist in the example test function:
% Initialize Bursts
% Initialize Input Data & Golden Vectors
% Open and Simulate Target
% Release Target on Error
% Test Pass / Fail
 
function eta = project3_burst_hwcosim_test
eta = 0;
 
%%
% ncycles is the number of cycles to simulate for and should be adjusted if
% the generated testbench simulation vectors are substituted by user data.
ncycles = 10;
 
%%
% Initialize Input Data & Golden Vectors
% xlHwcosimTestbench is a utility function that reformats fixed-point HDL Netlist
% testbench data vectors into a double-precision floating-point MATLAB binary
% data array.
xlHwcosimTestbench('.','project3_burst');
 
%%
% The testbench data vectors are both stimulus data for each input port, as
% well as expected (golden) data for each output port, recorded during the
% Simulink simulation portion of the Hardware Co-Simulation flow.
% Data gets loaded from the data file ('<name>_<port>_hwcosim_test.dat')
% into the corresponding 'testdata_<port>' workspace variables using
% 'getfield(load('<name>_<port>_hwcosim_test.dat' ... ' commands.
% 
% Alternatively, the workspace variables holding the stimulus and / or golden
% data can be assigned other data (including dynamically generated data) to
% test the design with. If using alternative data assignment, please make
% sure to adjust the "ncycles" variable to the proper number of cycles, as
% well as to disable the "Test Pass / Fail" section if unused.
testdata_noise_x0 = getfield(load('project3_burst_noise_x0_hwcosim_test.dat', '-mat'), 
'values');
testdata_scale = getfield(load('project3_burst_scale_hwcosim_test.dat', '-mat'), 'values');
testdata_wave = getfield(load('project3_burst_wave_hwcosim_test.dat', '-mat'), 'values');
testdata_intout = getfield(load('project3_burst_intout_hwcosim_test.dat', '-mat'), 'values');
testdata_sigout = getfield(load('project3_burst_sigout_hwcosim_test.dat', '-mat'), 'values');
 
%% 
% The 'result_<port>' workspace variables are arrays to receive the actual results
% of a Hardware Co-Simulation read from the FPGA. They will be compared to the
% expected (golden) data at the end of the Co-Simulation.
result_intout = zeros(size(testdata_intout));
result_sigout = zeros(size(testdata_sigout));
 
%%
% project3_burst.hwc is the data structure containing the Hardware Co-Simulation
% design information returned after netlisting the Simulink / System 
% Generator model.
% Hwcosim(project) instantiates and returns a handle to the API shared library object.
project = 'project3_burst.hwc';
h = Hwcosim(project);
try 
    %% Open the Hardware Co-Simulation target and co-simulate the design
    open(h); 
    cosim_t_start = tic;
    h('noise_x0') = testdata_noise_x0;
    h('scale') = testdata_scale;
    h('wave') = testdata_wave;
    run(h, ncycles);
    result_intout = h('intout');
    result_sigout = h('sigout');
    eta = toc(cosim_t_start);
    % Release the handle for the Hardware Co-Simulation target
    release(h);
 
%% Release Target on Error
catch err
    release(h); 
    rethrow(err); 
    error('Error running hardware co-simulation testbench. Please refer to hwcosim.log for 
details.'); 
end 
 
%% Test Pass / Fail
logfile = 'project3_burst_hwcosim_test.results';
logfd = fopen(logfile, 'w');
sim_ok = true;
sim_ok = sim_ok & xlHwcosimCheckResult(logfd, 'intout', testdata_intout, result_intout);
sim_ok = sim_ok & xlHwcosimCheckResult(logfd, 'sigout', testdata_sigout, result_sigout);
fclose(logfd);
if ~sim_ok
    error('Found errors in the simulation results. Please refer to 
project3_burst_hwcosim_test.results for details.');
end 
disp(['Hardware Co-Simulation successful. Data matches the Simulink simulation and completed in 
' num2str(eta) ' seconds.']) ;

This script first defines the number of cycles (ncycles) to run in the simulation, prepares the test bench, and loads the stimulus data and expected output into MATLAB arrays. Then it creates an Hwcosim object instance with a handle (h), which loads the HWCosim API shared library. Inside the try-catch block it opens the instance, initializes the FPGA, and opens a connection to it.

Once the setup phase is complete, the code between the tic and toc timing commands executes the write-run-read commands. Please note that unlike in previous versions of HWCosim, this test bench does not require a for-loop to cycle through every clock cycle. This is due to the new smart cache layer which can buffer up nearly arbitrary size write commands in host memory before issuing smaller cycles of write-run-read batches to the hardware (during execution of the user-visible run(h, ncycles) command).

At the end of the execution phase the HWCosim instance is released and the test bench compares actual to expected outputs.

Comments in the test bench code will help you understand the flow of the hardware co-simulation and help you develop customized test bench scripts for your design.