hls::print Function - 2022.1 English

Vitis High-Level Synthesis User Guide (UG1399)

Document ID
UG1399
Release Date
2022-06-07
Version
2022.1 English

The hls::print function is similar to printf in C, because it prints a format string and a single optional int or double argument to standard output, and to the simulation log in C simulation, RTL co-simulation and HW emulation in Vitis™ .

However, it is limited to printing at most one argument, with a restricted set of datatypes, as mentioned below. It may also change the initiation interval and latency of a pipeline, so it must used very sparingly.

hls::print Function Uses:

  • Trace the values of some selected variables.
  • Trace the order in which code blocks are executed across complex control and concurrent execution (for example in dataflow). It cannot be used to trace the order in which individual statements are scheduled within a basic block of code, because the scheduler may significantly change that order.

When used in this simple example:

#include "hls_print.h"
...
  for (int i=0; i<N; i++) {
#pragma HLS pipeline ii=1
   hls::print("loop %d\n", i);
...

It prints the value of "i" at each iteration of the loop in both C simulation, SW emulation, RTL co-simulation, and HW emulation (it is currently ignored when the target is a HW implementation).

Note the following:

  • For now the functionality is supported only in Verilog RTL.
  • The only supported format specifiers are:
    • %d for integer or unsigned
    • %f for float or double
  • Values of type long and long long, and the unsigned variants, must be cast to int or unsigned int (due to the argument promotion rules of C++).
  • By adding an "observation" point, insertion of hls::print may alter the optimizations performed by HLS. Thus it can change the behavior of the RTL (just like a printf in SW can alter the behavior of the binary, but much more dramatically due to the nature of HLS).
  • Only a single int or double value can be passed, in order to minimize the above mentioned impact.
  • The order of execution of different hls::print functions within a code block may change due to optimizations and scheduling.
  • In RTL the current simulation time is printed out as well, in order to ease debugging.
  • The amount of data that it may produce may be huge, thus it should not be used to dump large arrays.