xilinx/vitis-hls-introductory-examples

Introductory examples for Vitis HLS

Copyright 1986-2022 Xilinx, Inc. All Rights Reserved. Copyright 2022-2024 Advanced Micro Devices, Inc. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

C/C++ synthesizable examples

Each example comes with C/C++ source code, a README, and script or config file. The examples are organized in categories denoted by the directory names:

• Appnotes: A DSP design, a legacy digital up converter appnote.
• Array: Show how to partition memory arrays.
• Interface: Common examples for interface protocols.
• Misc.: Other examples such as the RTL blackbox flow and the LogiCore FFT from Vivado.
• Modelling: The essentials for loops, arbitrary precision types and vectors.
• Pipelining: Illustrating one of the most fundamental concept of HLS.
• Task_Level_Parallelism: Dataflow and free running streams with hls::task.
• Vitis: Kernel examples for the software acceleration flow.

Running the examples at the command line

• Using Vitis Unified IDE:
  • vitis-run --mode hls --tcl run_hls.tcl
• Using Vitis HLS (deprecated):
  • vitis_hls -f run_hls.tcl

Note that by default only C simulation and C synthesis will run. Change the value of hls_exec in the Tcl script to run co-simulation and Vivado implementation.

vitis-hls-introductory-examples's Issues

Examples in Data_driven don't work. I get a error when running the run_hls.tcl

 #include "hls_task.h"
                      ^
compilation terminated.
make: *** [obj/test_tb.o] Error 1
ERROR: [SIM 211-100] 'csim_design' failed: compilation error(s).
INFO: [SIM 211-3] *************** CSIM finish ***************
INFO: [HLS 200-111] Finished Command csim_design CPU user time: 1 seconds. CPU system time: 0 seconds. Elapsed time: 0.785 seconds; current allocated memory: 288.356 MB.
4
    while executing
"source run_hls.tcl"
    ("uplevel" body line 1)
    invoked from within
"uplevel \#0 [list source $arg] "

INFO: [Common 17-206] Exiting vitis_hls at Mon Nov 14 15:25:44 2022...

[ERROR] Issue with Bit Width Exceeding Limit in HLS Stream as Intermediate Variable

Hello,

I am encountering an issue while using hls::stream as an intermediate variable in my project. The compiler is indicating that the bit width is too large, exceeding the 4096 limit. Here's the context of my problem:

I created my own data structure, similar to hls::vector. Below is the relevant code snippet:

#ifdef __SYNTHESIS__
#define SYN_PRAGMA(PRAG) _Pragma(#PRAG)
#else
#define SYN_PRAGMA(PRAG)
#endif

template <typename T, unsigned N>
struct array {
    typedef T value_type;
    static const unsigned size = N;

    T data[N];

protected:
  INLINE void pragma() const {
    SYN_PRAGMA(HLS DISAGGREGATE variable=this)
  }

public:
    INLINE array() {
       pragma();
       SYN_PRAGMA(HLS ARRAY_PARTITION variable=this->data complete)
    }

    // ... [Additional member functions]
};

Then, I declared a data type as follows:

typedef array<ap_fixed<32,8>, 512> input_t;
hls::stream<input_t> data_recv;
#pragma HLS STREAM variable=data_recv

However, when I declare a data stream wrapped with the input_t type inside a function, I encounter the aforementioned error, From the log file, I noticed the message:
"INFO: [HLS 214-241] Aggregating fifo (hls::stream) variable 'data_recv' with compact=bit mode."It seems to perform an Aggregate operation.
Is there a way to perform Disaggregate? I have not encountered this error when using Vivado HLS previously.

truncate toward to zero

hamming_window.c

C++ on casting float to integer truncate toward to 0 here:
rom_array[i] = (int16_t)(WIN_COEFF_SCALE * real_val);

Guess that correct rounding should be applied instead.

the role of static int j in Dataflow/Bypassing/input_bypass/dut_sol.cpp ?

What is the objective of adding
static int j;
in functions add_kernel, Double_pass and pass?

Intuitively, it might be used as a global counter. If so, how to use it? Also, why not declare it as a global variable outside these functions.
What have I missed?

void add_kernel(int tmp1[128], int tmp2[128], int tmp3[128])
{
	static int j;

	int buff[127];
	for(int i=0;i<128;i++)
	{
		j++;
		tmp3[i] = tmp1[i] +tmp2[i];
	}

}


void Double_pass(int tmp2[128], int tmp1[128], int tmp4[128], int tmp5[128])
{
	static int j;

	int buff[127];
	for(int i=0;i<128;i++)
	{
		j++;
		tmp4[i] = tmp1[i];
		tmp5[i] = tmp2[i];
	}

}

void pass(int a[128], int b[128],int tmp1[128], int tmp2[128])
{
	static int j;
	for(int i=0;i<128;i++)
	{
		j++;
		tmp1[i]= a[i];
		tmp2[i] = b[i];
	}

}

void dut(int a[128], int b[128], int tmp3[128])
{
#pragma HLS DATAFLOW

int tmp1[128],tmp2[128], tmp4[128];
int tmp5[128];
	pass(a,b,tmp1,tmp2);
	Double_pass(tmp2,tmp1, tmp4, tmp5);
	add_kernel(tmp4,tmp5,tmp3);
}

RTL blackbox flow

Misc/rtl_as_blackbox/
I follow this flow for simulation, and everything is good.
However, when I try to move it to HW, I get the following error

Can we have an end-to-end example of RTL black-box flow to deploy on HW? Or can anybody tell me how to solve it?

Csim for manual_burst_inference_success example fails with link error

https://github.com/Xilinx/Vitis-HLS-Introductory-Examples/tree/master/Interface/Memory/manual_burst/manual_burst_example/manual_burst_inference_success/

CSim with Vitis HLS 2022.1 on Windows10 fails with:

INFO: [SIM 2] *************** CSIM start ***************
INFO: [SIM 4] CSIM will launch GCC as the compiler.
   Compiling ../../../example_tb.cpp in debug mode
   Compiling ../../../example.cpp in debug mode
   Generating csim.exe
Makefile.rules:392: recipe for target 'csim.exe' failed
In file included from C:/Xilinx/Vitis_HLS/2022.1/include/floating_point_v7_0_bitacc_cmodel.h:144:0,
                 from C:/Xilinx/Vitis_HLS/2022.1/include/hls_fpo.h:189,
                 from C:/Xilinx/Vitis_HLS/2022.1/include/hls_half_fpo.h:64,
                 from C:/Xilinx/Vitis_HLS/2022.1/include/hls_half.h:71,
                 from C:/Xilinx/Vitis_HLS/2022.1/include/etc/ap_private.h:98,
                 from C:/Xilinx/Vitis_HLS/2022.1/include/ap_common.h:710,
                 from C:/Xilinx/Vitis_HLS/2022.1/include/ap_int.h:56,
                 from ../../../example.h:1,
                 from ../../../example_tb.cpp:1:
C:/Xilinx/Vitis_HLS/2022.1/include/gmp.h:63:0: warning: "__GMP_LIBGMP_DLL" redefined
 #define __GMP_LIBGMP_DLL  0
 
In file included from C:/Xilinx/Vitis_HLS/2022.1/include/hls_fpo.h:189:0,
                 from C:/Xilinx/Vitis_HLS/2022.1/include/hls_half_fpo.h:64,
                 from C:/Xilinx/Vitis_HLS/2022.1/include/hls_half.h:71,
                 from C:/Xilinx/Vitis_HLS/2022.1/include/etc/ap_private.h:98,
                 from C:/Xilinx/Vitis_HLS/2022.1/include/ap_common.h:710,
                 from C:/Xilinx/Vitis_HLS/2022.1/include/ap_int.h:56,
                 from ../../../example.h:1,
                 from ../../../example_tb.cpp:1:
C:/Xilinx/Vitis_HLS/2022.1/include/floating_point_v7_0_bitacc_cmodel.h:136:0: note: this is the location of the previous definition
 #define __GMP_LIBGMP_DLL 1
 
In file included from C:/Xilinx/Vitis_HLS/2022.1/include/floating_point_v7_0_bitacc_cmodel.h:144:0,
                 from C:/Xilinx/Vitis_HLS/2022.1/include/hls_fpo.h:189,
                 from C:/Xilinx/Vitis_HLS/2022.1/include/hls_half_fpo.h:64,
                 from C:/Xilinx/Vitis_HLS/2022.1/include/hls_half.h:71,
                 from C:/Xilinx/Vitis_HLS/2022.1/include/etc/ap_private.h:98,
                 from C:/Xilinx/Vitis_HLS/2022.1/include/ap_common.h:710,
                 from C:/Xilinx/Vitis_HLS/2022.1/include/ap_int.h:56,
                 from ../../../example.h:1,
                 from ../../../example.cpp:1:
C:/Xilinx/Vitis_HLS/2022.1/include/gmp.h:63:0: warning: "__GMP_LIBGMP_DLL" redefined
 #define __GMP_LIBGMP_DLL  0
 
In file included from C:/Xilinx/Vitis_HLS/2022.1/include/hls_fpo.h:189:0,
                 from C:/Xilinx/Vitis_HLS/2022.1/include/hls_half_fpo.h:64,
                 from C:/Xilinx/Vitis_HLS/2022.1/include/hls_half.h:71,
                 from C:/Xilinx/Vitis_HLS/2022.1/include/etc/ap_private.h:98,
                 from C:/Xilinx/Vitis_HLS/2022.1/include/ap_common.h:710,
                 from C:/Xilinx/Vitis_HLS/2022.1/include/ap_int.h:56,
                 from ../../../example.h:1,
                 from ../../../example.cpp:1:
C:/Xilinx/Vitis_HLS/2022.1/include/floating_point_v7_0_bitacc_cmodel.h:136:0: note: this is the location of the previous definition
 #define __GMP_LIBGMP_DLL 1
 
obj/example.o:example.cpp:(.bss+0x0): multiple definition of `.weak._ZN3hls27MAXIPointer2AccessRecordMapE._ZnwyPv'
obj/example_tb.o:example_tb.cpp:(.bss+0x0): first defined here
obj/example.o: In function `std::_Tuple_impl<0ull, void*&&>::_Tuple_impl<void*>(void*&&)':
C:/Xilinx/Vitis_HLS/2022.1/tps/win64/msys64/mingw64/include/c++/6.2.0/bits/stl_tree.h:1912: multiple definition of `.weak._ZGVN3hls27MAXIPointer2AccessRecordMapE._ZnwyPv'
obj/example_tb.o:C:\Users\username\AppData\Roaming\Xilinx\Vitis\manualburst\solution1\csim\build/../../../example_tb.cpp:9: first defined here
collect2.exe: error: ld returned 1 exit status
make: *** [csim.exe] Error 1
ERR: [SIM 100] 'csim_design' failed: compilation error(s).
INFO: [SIM 3] *************** CSIM finish ***************

Also see https://support.xilinx.com/s/question/0D54U00005ZO4WuSAL/c-simulation-error-for-vitis-hls?language=en_US.

This works in Linux (specifically Ubuntu 20.04).
...

The DATAFLOW does not work wih BURST transfer on m_axi interface (no outstanding writes)

The approach shown in the https://github.com/Xilinx/Vitis-HLS-Introductory-Examples/blob/master/Interface/Streaming/axi_stream_to_master/example.cpp does not generate properly outstanding write transactions in case if the underlaying AXI interface has higher latency. Preparing the next burst is delayed until BVALID for the previous one is received. The problem is described in https://support.xilinx.com/s/question/0D52E00006w0CxZSAU/hls-maxi-interface-does-not-generate-outstanding-write-transactions

What is the expected result of example "Dataflow/Bypassing/input_bypass" ?

I don't see any performance degradation in terms of latency and II when compared the synthesis reports of problem and solution. What do you mean by "performance degradation" stated in ReadMe?

predecessor and read issue in dataflow

When compiling convolution kernel following warning is reported, how to overcome this ?

Process Loop_HConvH_proc5 has both a predecessor and reads an input from its caller (see the GUI dataflow viewer). This may lead to lower throughput. Consider copying this input via a predecessor process.

In doing any dataflow design this warning is coming although it was not in 2019.1.

Test_delay = [email protected] ns
#define TEST_IMG_ROWS 135
#define TEST_IMG_COLS 240
reports timing violations, how to improve it.

Can we update Readme file in vitis-hls-introductory repository to Readme.md

I feel readme.md is more readable.
Example :
https://gitenterprise.xilinx.com/SDxGitExamples/Vitis_Accel_Examples/blob/master/host/README.md

Mixed indentation may cause user guide(s) to be less readable

Hey, thanks for creating this repo!

I noticed that some examples use a mix of tabs and spaces for indentation. While this is okay-ish for most text editors, it causes some trouble with your user guides (e.g. the PDF of UG1399 2023.1, page 138 - the fprintf calls are not aligned). I guess your text processor is confused due to the mix of tabs and spaces on the same line. Source:

Vitis-HLS-Introductory-Examples/Modeling/Pointers/stream_good/pointer_stream_good_test.c

Lines 126 to 131 in d234d0e

	fprintf(fp, "Din Dout\n");
	for (i=0;i<4;i++) {
	if (i<2)
	fprintf(fp, "%d %d\n", d_i[i], d_o[i]);
	else
	fprintf(fp, "%d \n", d_i[i]);

(Github also renders it differently here vs when you open the full file.)

I could just provide a pull request for the entire repository to use either tab or space indentation if you like. Feel free to close if you don't want this fixed.

Working with objects and hls::task

Hi everyone,
I have a question regarding the usage of hls::task when using an OOP structure for the design.
Suppose to have the following design in main.cc:

#include <hls_task.h>

class Counter {
  unsigned int _cnt=0; 

  public:
  Counter(void) = default; 

  void stream(
    hls::stream<bool>& inStream, 
    hls::stream<unsigned int>& outStream
    ) {
    if (inStream.read()) {
      outStream.write(_cnt++); 
    }
  }
};

void dut(
  hls::stream<bool>& inStream, 
  hls::stream<unsigned int>& outStream
  ) {
#pragma HLS dataflow
  hls_thread_local Counter cnt; 
  hls_thread_local hls::task t(cnt.stream, inStream, outStream); 
}

Using the following Makefile:

VITIS_ROOT := /eda/xilinx/Vitis_HLS/2022.2/include
CXX := /usr/bin/g++

all:
	$(CXX) main.cc -o main.out -I$(VITIS_ROOT)

When compiling the design:

fab@fedora: $ make
/usr/bin/g++ main.cc -o main.out -I/eda/xilinx/Vitis_HLS/2022.2/include
main.cc: In function ‘void dut(hls::stream<bool>&, hls::stream<unsigned int>&)’:
main.cc:25:36: error: invalid use of non-static member function ‘void Counter::stream(hls::stream<bool>&, hls::stream<unsigned int>&)’
   25 |   hls_thread_local hls::task t(cnt.stream, inStream, outStream);

If we try in Vitis HLS:

vitis_hls> csynth_design 
INFO: [HLS 200-1510] Running: csynth_design 
INFO: [HLS 200-111] Finished File checks and directory preparation: CPU user time: 0.01 seconds. CPU system time: 0.01 seconds. Elapsed time: 0.01 seconds; current allocated memory: 772.094 MB.
INFO: [HLS 200-10] Analyzing design file 'main.cc' ... 
ERROR: [HLS 207-2295] reference to non-static member function must be called (main.cc:25:36)

Since when compiling this design I get the error ERROR: Invalid use of non-static member function from the compiler, what is the best solution to wrap the method of a class so that it can be used in an hls::task? With exposed objects like the one I posted here, I can define some helper functions and use the objects as global variables, but now I am starting to call the tasks inside the class itself and this is not feasible anymore. I tried a lambda but it doesn't work. This is the error I get in execution of the C simulation:

terminate called after throwing an instance of 'std::system_error'
  what(): Resource temporarily unavailable.

Thanks in advance :)