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:
- Use of appropriate compile-time options- When using thexfOpenCVfunctions in HLS, the
-D__SDSVHLS__
and-std=c++0x
options need to be provided at the time of compilation: - 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), the
m_axi
Interface 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:
- TCL Script Mode
- GUI Mode
Tcl Script Mode
- In theVivado®HLS tcl script file, update thecflagsin all theadd_filessections.
- Append the path to thexfOpenCV/includedirectory, as it contains all the header files required by the library.
- Add the
-D__SDSVHLS__
and-std=c++0x
compiler flags.
-std=c++0x
flag only for C-Sim and Co-Sim. Do not include the flag when performing synthesis.
For example:
add_files xf_dilation_accel.cpp -cflags "-I -D__SDSVHLS__ -std=c++0x"
add_files -tb xf_dilation_tb.cpp -cflags "-I -D__SDSVHLS__ -std=c++0x"
GUI Mode
- OpenVivado®HLS in GUI mode and create a new project
- Specify the name of the project. For example -Dilation.
- ClickBrowseto enter a workspace folder used to store your projects.
- ClickNext.
- 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).
- ClickNext.
- Under the test bench section addtb.cpp.
- ClickNext.
- Select the clock period to the required value (10ns in example).
- Select the suitable part. For example,
xczu9eg-ffvb1156-2-i
. - ClickFinish.
- Right click on the created project and selectProject Settings.
- In the opened tab, selectSimulation.
- Files added under the Test Bench section will be displayed. Select a file and clickEdit CFLAGS.
- Enter
-I
.-D__SDSVHLS__ -std=c++0x Note:When using Vivado HLS in the Windows operating system, make sure to provide the-std=c++0x
flag only for C-Sim and Co-Sim. Do not include the flag when performing synthesis. - SelectSynthesisand repeat the above step for all the displayed files.
- ClickOK.
- Run the C Simulation, selectClean Buildand specify the required input arguments.
- ClickOK.
- All the generated output files/images will be present in thesolution1->csim->build.
- Run
C Synthesis
. - Run
Co-simulation
by specifying the proper input arguments. - 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:
- Functions with multiple accelerators are not supported.
- Compiler and simulator are default in HLS. (gcc, xsim).
- 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:
- 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
andAXIvideo2cvMatxf
are used on the host side.
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
TheAXIvideo2xfMat
function receives a sequence of images using the AXI4 Streaming Video and produces anxf::Mat
representation.
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.
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
TheMat2AXI
video 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.
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.
cvMat2AXIvideoxf
cvMat2Axivideoxf
function 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.
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
Axivideo2cvMatxf
function 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.
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. |