# Simulation and the waveform `yanc` stops at the Verilog (see [The command line](command-line.md)). The output folder then holds everything a simulator needs: the processor `.v`, its memories, and the testbench `_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](install.md)): ```sh 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](images/gtkwave-source-trace.png) 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 `_tb.v` directly — `--timing` understands the testbench's clock and `#` delays, so no separate C++ driver is needed: ```sh # 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](install.md#to-simulate)); 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 `.vcd` and GTKWave detects the format). The trace deliberately carries only the ``-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 `.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: ```sh 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 `$finish`es — 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](install.md#to-simulate)). ## 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): ```bat 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__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.