Simulation and the waveform

yanc stops at the Verilog (see The command line). The output folder then holds everything a simulator needs: the processor <name>.v, its memories, and the testbench <name>_tb.v, which feeds each input port from input_N.txt beside the source and writes what the program outputs to output_N.txt. This page runs it with Icarus Verilog or Verilator and opens the waveform in GTKWave.

Simulating with Icarus

From the output folder, with SAPHO the SAPHO/ folder that comes with YANC (on Windows, in the MSYS2 UCRT64 terminal, written /c/path/to/SAPHO for C:\path\to\SAPHO; see Installing YANC):

export SAPHO=/path/to/yanc/SAPHO
cd my_program
iverilog -s my_program_tb -o sim.vvp -y "$SAPHO" my_program_tb.v my_program.v
vvp sim.vvp
cat output_0.txt

-y "$SAPHO" makes the simulator look in SAPHO/ for each module it is missing, in the file of the same name: processor in processor.v, and from there core.v, ula.v, addr_dec.v, instr_dec.v, and myFIFO.v or myDCFIFO.v when a project uses them. Listing the files instead works too.

The testbench simulates as many clocks as yanc -c said (10000 by default) at the clock of yanc -f (100 MHz by default), and writes the waveform to my_program_tb.vcd.

Run the simulation from the output folder. The generated Verilog names every file relative to it: the memories (my_program_inst.mif, my_program_data.mif), the PC table, the outputs (output_N.txt, toma_k.txt) and the waveform by their bare names, and the inputs (input_N.txt, cade_k.txt) by the way from the output folder to the source, ../input_0.txt when the output folder is the default one beside the source. No absolute path is written, so the folder can be moved or copied to another machine along with the source, and a folder name with accents or spaces costs nothing: the YANC tools work in UTF-8 on Windows, Linux and macOS alike. To synthesize, give the synthesis tool the .mif files in its project folder, or their full path in the DFILE/IFILE parameters.

What you see in GTKWave

Because the toolchain emits a side-table mapping each PC value to its originating C± source line, GTKWave shows the executing C± line, the assembly opcode, and every declared variable evolving in lockstep with the simulated clock — not just raw bus toggles:

GTKWave showing the executing C± line, the assembly opcode, and live variable values in lockstep with the clock

The example above is proc_fft mid-run: the C± track shows the fout(0, 1000.0*real(data[2])); statement, the assembly track shows the matching LOD / F_MLT+ / F2I / OUT 0 sequence, and the declared variables (N, ind, istep, j, k, m, mmax, sind, comp temp) carry their live values.

Simulating with Verilator

Verilator 5 compiles the same generated <proc>_tb.v directly — --timing understands the testbench’s clock and # delays, so no separate C++ driver is needed:

# from the output folder, my_program/
cd my_program
verilator --binary --timing --trace +define+YANC_TRACE --timescale 1ns/1ps \
          --top-module my_program_tb -Wno-lint -Wno-MULTIDRIVEN -Wno-BLKANDNBLK \
          -Wno-COMBDLY -Wno-STMTDLY -Wno-INFINITELOOP -Wno-UNOPTFLAT --Mdir vl \
          -y "$SAPHO" my_program_tb.v my_program.v
./vl/Vmy_program_tb     # runs the sim, writes my_program_tb.vcd here
gtkwave my_program_tb.vcd

On Windows, MSYS2’s gcc 16 needs -CFLAGS -D_GLIBCXX_ASSERTIONS added to the verilator line, or the link fails (see Installing YANC); the scripts below add it themselves.

--timescale 1ns/1ps gives the SAPHO modules the testbench’s time unit: the files -y finds are read on their own, so they do not inherit the testbench’s `timescale as files listed after it do, and Verilator stops at the difference.

Verilator builds with GNU make, which refuses a build folder whose path has a space. If the output folder’s has one, point --Mdir somewhere without spaces and still run the binary from the output folder.

The one thing to remember: +define+YANC_TRACE is what makes your variables, arrays, the PC→C± line table and the assembly opcode appear in the waveform. Icarus gets them for free (it predefines __ICARUS__); Verilator only compiles that visibility harness when you pass the define. For big multi-millisecond project dumps, use --trace-fst instead of --trace (compact FST; the file is still named <tb>.vcd and GTKWave detects the format). The trace deliberately carries only the <proc>-level user signals — the CPU internals below each processor are fenced out with /* verilator tracing_off */. In particular the stack-monitoring flags and the ULA rounding-error taps (fl_max, fl_full, pointeri, delta_int, delta_float) are intentionally not in the Verilator VCD: keeping them would force Verilator to evaluate the expensive real-valued ULA monitoring logic every cycle, which defeats the whole point of using Verilator (speed). Those debug signals remain available under the Icarus flow (Scripts\single_proc.bat / multi_proc.bat), where raw speed is not the goal.

Formatting the waveform — gen_gtkw (optional)

After simulating with either Icarus or Verilator you have a raw <tb>.vcd / .fst: every signal, in scope order, unformatted. If you want the curated view instead — the input/output ports, the Assembly and C± instruction tracks (disassembled through their translate files), and the internal variables and arrays grouped per processor — run gen_gtkw (it is in the release’s bin/), then open the waveform with it applied via -a. From the Quick start’s output folder:

gen_gtkw my_program_tb.vcd my_program_tb.gtkw ..
gtkwave my_program_tb.vcd -a my_program_tb.gtkw

gen_gtkw reads only the VCD header (the signal list), classifies each harness signal by name, and writes a formatted .gtkw save file: the right data format / colour / alias per signal, the trad_opcode.txt / src_lines.txt translators on the Assembly / C± tracks, comp2gtkw.exe on complex signals, and one section per processor — any scope that owns both valr2 and linetabs — so the same tool handles single- and multi-processor dumps. Its third argument is the folder that holds each processor’s output folder, where its translate files are (.. from inside my_program/ in the Quick start, the folder that holds my_program/). When the output folder is not named after the processor (yanc -o build, an .asm in a folder of another name), give the output folder itself: . from inside it.

Because only the header is needed, the big project FST dumps don’t have to be written in full first: run the sim once with the +HEADER_ONLY plusarg and the testbench dumps the header, advances one tick, flushes and $finishes — a tiny header VCD in milliseconds (Verilator’s header FST is converted with fst2vcd -f). The runner scripts wire this whole sequence up correctly (header pass → gen_gtkw → gtkwave -a), so they are the reference for using it in practice. They also open GTKWave with --dark, and with --zoom-fit (the whole trace in the window) and --left-justify when that GTKWave lists them, as the nipscernlab build does (see Installing YANC).

Pre-wired scripts

Three scripts in the repository’s Scripts/ folder run the whole way, from a test program to GTKWave, with sensible defaults. Each has a Windows (.bat) and a Linux (.sh) version, and picks the simulator from a --sim iverilog|verilator flag (default Icarus):

Scripts\single_proc      .bat / .sh   one C± processor    (edit PROC / FNAM at the top)
Scripts\multi_proc       .bat / .sh   C± multi-proc project
Scripts\single_proc_cpp  .bat / .sh   one C++ processor   (front end: cppcomp)

  ... default (no flag)        -> Icarus Verilog (iverilog + vvp)
  ... --sim verilator          -> Verilator (--binary --timing, +define+YANC_TRACE)
  ... --no-view                -> (single_proc_cpp) run the pipeline, skip GTKWave

In the UCRT64 terminal on Windows, as on Linux, run Scripts/single_proc.sh (or Scripts/single_proc.sh --sim verilator); on Linux make them executable once (chmod +x Scripts/*.sh). The .bat versions do the same from cmd.

The C++ runner (single_proc_cpp) feeds a .cpp program — the bundled Compilers/CPPComp/Tests/proc_cpp demo — through cppcomp instead of cmmcomp, then the same assemble / simulate / view back end. cppcomp now emits the same files cmmcomp does (the .asm, prog_log.txt, the pc_<proc>_mem.txt PC→source line table and src_lines.txt), so the waveform looks just like the C± flow — with one rule: GTKWave only shows C++ variables that live at a fixed data-memory address, because the dump snoops a constant write address (if (mem_addr_wr == X)). That covers globals, the locals/params of non-recursive functions, and static locals — int shown as a raw word, float decoded, arrays element-by-element, exactly as in C±. Stack-frame locals of recursive functions (no fixed address), pointers (an address, not a value) and structs (a multi-word aggregate) are deliberately not traced. This mirrors C±, which — for optimization reasons — only ever allocates fixed-address variables anyway, so both flows show the same kind of thing.