Runtime Flags
This page covers environment variables and host executable flags that control TAPA behavior at runtime. These apply after compilation, during software simulation or fast hardware cosimulation.
Environment Variables
These variables are read by the host executable at startup.
| Variable | Default | Description |
|---|---|---|
TAPA_CONCURRENCY | Number of CPU cores | Number of parallel coroutine threads used by software simulation. Set to 1 for single-threaded, more reproducible simulation runs. Has no effect on HLS compilation parallelism (-j). |
TAPA_STREAM_LOG_DIR | (unset — logging disabled) | Directory for stream transfer logs. When set, TAPA writes one log file per named stream recording each value written to that stream. Useful for tracing data corruption during software simulation. |
FRT_STREAM_DEBUG | (unset) | When set, log every successful stream read and write in the DPI layer. Produces high-volume output; use only for targeted debugging. |
FRT_COSIM_YIELD | 1 (enabled) | When enabled, the DPI layer calls thread::yield_now() on empty reads or full writes. Disable with 0 to busy-wait instead. |
FRT_XSIM_LEGACY | 0 | Set to 1 to use the legacy xelab command-line format for older Vivado versions. |
FRT_XOCL_BDF | (unset) | PCIe Bus:Device:Function for XRT/OpenCL device selection. Equivalent to the -xocl_bdf gflag. |
Example: reproducible single-threaded simulation
TAPA_CONCURRENCY=1 ./vadd
Example: enable stream logging
TAPA_STREAM_LOG_DIR=/tmp/stream-logs ./vadd
See Software Simulation for more on stream logging and debugging.
Host Executable Flags (Fast Cosim)
When the host executable is invoked with --bitstream=vadd.xo, it runs fast hardware cosimulation instead of software simulation. The following flags control cosim behavior. They are passed directly on the host executable command line.
These flags use single-dash prefix (e.g., -cosim_work_dir) because they are parsed by the host executable via gflags.
| Flag | Description |
|---|---|
-cosim_executable <path> | Deprecated. Fast cosim now runs in-process via libfrt; this flag is ignored. |
-xsim_part_num <part> | Target FPGA part number for simulation (e.g., xcu280-fsvh2892-2L-e). |
-cosim_work_dir <dir> | Persistent working directory for simulation artifacts. Without this flag, a temporary directory is used and deleted after the run. |
-xsim_save_waveform | Save simulation waveforms to a .wdb file in the work directory. Pair with -cosim_work_dir; without it, the temporary directory and all waveforms are deleted after the run. |
-xsim_start_gui | Open the Vivado GUI for interactive debugging during simulation. |
-cosim_simulator <backend> | Simulator backend: xsim (default, Linux only, requires Vivado) or verilator (cross-platform, no Vivado required). |
-cosim_setup_only | Run simulation setup only, then stop before executing the simulation. Useful for inspecting generated simulation files before committing to a full run. |
-cosim_resume_from_post_sim | Skip re-running the simulation and jump directly to post-simulation checks. Use after a completed simulation to re-run checks without re-simulating. |
-cosim_work_dir_parallel | Create a unique subdirectory per instance when running multiple concurrent simulations, preventing work directory collisions. |
Example: save waveforms from a named work directory
./vadd --bitstream vadd.xo \
-cosim_work_dir ./cosim_work \
-xsim_save_waveform \
1000
Example: staged workflow (setup then resume)
# Step 1: set up and inspect the simulation environment
./vadd --bitstream vadd.xo -cosim_work_dir ./cosim_work -cosim_setup_only 1000
# Step 2: run post-simulation checks without re-simulating
./vadd --bitstream vadd.xo -cosim_work_dir ./cosim_work -cosim_resume_from_post_sim 1000
For a full walkthrough of fast cosim workflows, see Fast Hardware Simulation.