Skip to main content

Simulate

Every tutorial example runs on the fabric simulator, which executes a compiled machine image over a modelled fabric and records what each processing element did. You do not invoke it directly: a bench Makefile drives it through the flute build system, so a simulation is one make away from a program's sources.

Running one​

A bench's test target performs the compile, run, and verify steps in sequence, taking its settings from environment variables; it runs inside a per-configuration test-<N>/ directory, not from the bench directory itself. Configurations live one per line in test.rc, so make TEST=3 runs the third, make TEST=tutorial runs every line labelled tutorial, make check TEST="1 2 5" runs a selection, and make check TEST=* runs them all, stopping at the first failure unless you add -k. Verbose output for each run lands in test-<N>/make-log. After editing a kernel, run make clean first: an existing test directory is not rebuilt. The build and test framework reference covers the rest of the contract.

Two settings matter most while iterating:

  • cycles=N, set in the bench Makefile's SIMFLAGS (lesson 1 has SIMFLAGS=cycles=1000 $(SIMOPTS)), bounds the run. A kernel that deadlocks does not hang the simulator; it hits the cycle limit and fails, which is the usual first symptom of a routing or ordering mistake.
  • GOAL=debugx, as in make TEST=1 GOAL=debugx, reruns a configuration with tracing on and unpacks the traces the inspection tools read into its test directory. Run make clean first: an earlier simulation log has no traces.

What a run leaves behind​

A simulation produces a core dump of final fabric state and a log of what happened during the run. Those two artifacts are what the rest of the tooling reads: results come out of the core dump, and the log is the input to per-cycle reconstruction.

In this section​

  • miset and miget — read and write named symbols in a machine image or a core dump, by symbolic name via bench.map, as text or raw binary. miset seeds inputs before a run; miget extracts results afterwards. This is why both appear in nearly every example Makefile.
  • Pipeline traces — parse the simulator's log into per-cycle pipeline state, which is what drives the pipeline view in Portrait.

Then what​

When a run produces the wrong answer rather than no answer, move on to debug and inspect. The tutorial's debugging guide sequences the two.