Getting Started with HLS

ThexfOpenCVlibrary can be used to build applications inVivado®HLS. This section provides details on how the xfOpenCV library components can be integrated into a design inVivado HLS 2019.1. This section of the document provides steps on how to run a single library component through theVivado HLS 2019.1use flow which includes, C-simulation, C-synthesis, C/RTL co-simulation, and exporting the RTL as an IP.

You are required to do the following changes to facilitate proper functioning of the use model inVivado HLS 2019.1:

  1. Use of appropriate compile-time options- When using thexfOpenCVfunctions in HLS, the-D__SDSVHLS__and-std=c++0xoptions need to be provided at the time of compilation:
  2. Specifying interface pragmas to the interface level arguments- For the functions with top level interface arguments as pointers (with more than one read/write access), them_axiInterface pragma must be specified. For example,
    void lut_accel(xf::Mat &imgInput, xf::Mat &imgOutput, unsigned char *lut_ptr) { #pragma HLS INTERFACE m_axi depth=256 port=lut_ptr offset=direct bundle=lut_ptr xf::LUT< TYPE, HEIGHT, WIDTH, NPC1> (imgInput,imgOutput,lut_ptr); }

HLS Standalone Mode

The HLS standalone mode can be operated using the following two modes:

  1. TCL Script Mode
  2. GUI Mode

Tcl Script Mode

Use the following steps to operate the HLS Standalone Mode using Tcl Script:
  1. In theVivado®HLS tcl script file, update thecflagsin all theadd_filessections.
  2. Append the path to thexfOpenCV/includedirectory, as it contains all the header files required by the library.
  3. Add the-D__SDSVHLS__and-std=c++0xcompiler flags.
Note:When using VivadoHLS in the Windows operating system, provide the -std=c++0xflag only for C-Sim and Co-Sim. Do not include the flag when performing synthesis.

For example:

Setting flags for source files: 
add_files xf_dilation_accel.cpp -cflags "-I -D__SDSVHLS__ -std=c++0x"
Setting flags for testbench files: 
add_files -tb xf_dilation_tb.cpp -cflags "-I -D__SDSVHLS__ -std=c++0x"

GUI Mode

Use the following steps to operate the HLS Standalone Mode using GUI:
  1. OpenVivado®HLS in GUI mode and create a new project
  2. Specify the name of the project. For example -Dilation.
  3. ClickBrowseto enter a workspace folder used to store your projects.
  4. ClickNext.
  5. Under the source files section, add theaccel.cppfile which can be found in theexamplesfolder. Also, fill the top function name (here it is dilation_accel).
  6. ClickNext.
  7. Under the test bench section addtb.cpp.
  8. ClickNext.
  9. Select the clock period to the required value (10ns in example).
  10. Select the suitable part. For example,xczu9eg-ffvb1156-2-i.
  11. ClickFinish.
  12. Right click on the created project and selectProject Settings.
  13. In the opened tab, selectSimulation.
  14. Files added under the Test Bench section will be displayed. Select a file and clickEdit CFLAGS.
  15. Enter-I -D__SDSVHLS__ -std=c++0x.
    Note:When using Vivado HLS in the Windows operating system, make sure to provide the -std=c++0xflag only for C-Sim and Co-Sim. Do not include the flag when performing synthesis.
  16. SelectSynthesisand repeat the above step for all the displayed files.
  17. ClickOK.
  18. Run the C Simulation, selectClean Buildand specify the required input arguments.
  19. ClickOK.
  20. All the generated output files/images will be present in thesolution1->csim->build.
  21. RunC Synthesis.
  22. RunCo-simulationby specifying the proper input arguments.
  23. The status of co-simulation can be observed on the console.

Constraints for Co-simulation

There are few limitations in performing co-simulation of thexfOpenCVfunctions. They are:

  1. Functions with multiple accelerators are not supported.
  2. Compiler and simulator are default in HLS. (gcc, xsim).
  3. Since HLS does not support multi-kernel integration, the current flow also does not support multi-kernel integration. Hence, the Pyramidal Optical flow and Canny Edge Detection functions and examples are not supported in this flow:
  4. The maximum image size (HEIGHT and WIDTH) set in config.h file should be equal to the actual input image size.

AXI Video Interface Functions

xfOpenCVhas functions that will transform the xf::Mat intoXilinx®Video Streaming interface and vice-versa.xf::AXIvideo2xfMat()andxf::xfMat2AXIVideo()act as video interfaces to the IPs of thexfOpenCVfunctions in theVivado®IP integrator.cvMat2AXIvideoxf andAXIvideo2cvMatxfare used on the host side.

Table 1.AXI Video Interface Functions
Video Library Function Description
AXIvideo2xfMat Converts data from an AXI4 video stream representation to xf::Mat format.
xfMat2AXIvideo Converts data stored as xf::Mat format to an AXI4 video stream.
cvMat2AXIvideoxf Converts data stored as cv::Mat format to an AXI4 video stream
AXIvideo2cvMatxf Converts data from an AXI4 video stream representation to cv::Mat format.

AXIvideo2xfMat

TheAXIvideo2xfMatfunction receives a sequence of images using the AXI4 Streaming Video and produces anxf::Matrepresentation.

API Syntax

template int AXIvideo2xfMat(hls::stream< ap_axiu >& AXI_video_strm, xf::Mat& img)

Parameter Descriptions

The following table describes the template and the function parameters.

Table 2.AXIvideo2cvMatxf Function Parameter Description
Parameter Description
W Data width ofAXI4-Stream. Recommended value is pixel depth.
T Pixel type of the image. 1 channel (XF_8UC1). Data width of pixel must be no greater thanW.
ROWS Maximum height of input image.
COLS Maximum width of input image.
NPC Number of pixels to be processed per cycle. Possible options are XF_NPPC1 and XF_NPPC8 for 1-pixel and 8-pixel operations respectively.
AXI_video_strm HLS stream of ap_axiu (axi protocol) type.
img Input image.

This function will return bit error of ERROR_IO_EOL_EARLY( 1 ) or ERROR_IO_EOL_LATE( 2 ) to indicate an unexpected line length, by detecting TLAST input.

For more information about AXI interface see UG761.

xfMat2AXIvideo

TheMat2AXIvideo function receives an xf::Mat representation of a sequence of images and encodes it correctly using the AXI4 Streaming video protocol.

API Syntax

template int xfMat2AXIvideo(xf::Mat& img,hls::stream >& AXI_video_strm)

Parameter Descriptions

The following table describes the template and the function parameters.

Table 3.xfMat2AXIvideo Function Parameter Description
Parameter Description
W Data width ofAXI4-Stream. Recommended value is pixel depth.
T Pixel type of the image. 1 channel (XF_8UC1). Data width of pixel must be no greater thanW.
ROWS Maximum height of input image.
COLS Maximum width of input image.
NPC Number of pixels to be processed per cycle. Possible options are XF_NPPC1 and XF_NPPC8 for 1-pixel and 8-pixel operations respectively.
AXI_video_strm HLS stream of ap_axiu (axi protocol) type.
img Output image.

This function returns the value 0.

Note:The NPC values across all the functions in a data flow must follow the same value. If there is mismatch it throws a compilation error in HLS.

cvMat2AXIvideoxf

The cvMat2Axivideoxffunction receives image as cv::Mat representation and produces the AXI4 streaming video of image.

API Syntax

template void cvMat2AXIvideoxf(cv::Mat& cv_mat, hls::stream >& AXI_video_strm)

Parameter Descriptions

The following table describes the template and the function parameters.

Table 4.AXIvideo2cvMatxf Function Parameter Description
Parameter Description
W Data width ofAXI4-Stream. Recommended value is pixel depth.
NPC Number of pixels to be processed per cycle. Possible options are XF_NPPC1 and XF_NPPC8 for 1-pixel and 8-pixel operations respectively.
AXI_video_strm HLS stream of ap_axiu (axi protocol) type.
cv_mat Input image.

AXIvideo2cvMatxf

The Axivideo2cvMatxffunction receives image as AXI4 streaming video and produces the cv::Mat representation of image

API Syntax

template void AXIvideo2cvMatxf(hls::stream >& AXI_video_strm, cv::Mat& cv_mat)

Parameter Descriptions

The following table describes the template and the function parameters.

Table 5.AXIvideo2cvMatxf Function Parameter Description
Parameter Description
W Data width ofAXI4-Stream. Recommended value is pixel depth.
NPC Number of pixels to be processed per cycle. Possible options are XF_NPPC1 and XF_NPPC8 for 1-pixel and 8-pixel operations respectively.
AXI_video_strm HLS stream of ap_axiu (axi protocol) type.
cv_mat Output image.