HLS Print Function - 2023.2 English

Vitis High-Level Synthesis User Guide (UG1399)

Document ID
Release Date
2023.2 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.

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.