HLS Print Function - 2023.2 English - UG1399

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.

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

The hls::print function can be used to:

• Trace the values of selected variables
• Trace the order in which code blocks are executed across complex control and concurrent execution (for example in dataflow)
  Tip: It cannot be used to trace the order in which individual statements are scheduled within a basic block of code, because the scheduler can 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:

• hls::print 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 uint (due to the argument promotion rules of C++).
• By adding an "observation" point, insertion of hls::print can 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, to minimize the above mentioned impact.
• The order of execution of different hls::print functions within a code block can change due to optimizations and scheduling.
• In RTL the current simulation time is printed out as well, to ease debugging.
• The amount of data that it produces can be significant, thus it should not be used to dump large arrays.