Hiring, or looking for work? Employers: post a job on Far Reach, compare proposals, and fund a milestone that is released when you accept the work. Freelancers: join Far Reach and get hired for what you do best. Post a job on Far Reach →Join as a freelancer →

trsim › Manuals › Compiled Backend

trsim Compiled Backend

The Tuwa RTL Simulator, version 1.0

-native turns your design into C and lets a C compiler optimise it. On a large design that is the difference between a simulation you run overnight and one you run in a coffee break.


How it works

An ordinary run interprets the elaborated design: for every event, the engine walks a tree of statements and evaluates them. That is flexible but it pays an interpretation cost on every single operation.

-native instead generates C source for the whole elaborated design — every process, every assignment, the scheduler's fanout tables, the memories — and hands it to your C compiler. The result is a standalone executable that simulates the design and nothing else.

The front end is shared. Parsing, `include handling, parameter override, elaboration and hierarchy flattening are the same code either way, so a design that compiles for one back end compiles for the other.

Using it

Compiled simulation is the default. A plain run

trsim -top my_tb rtl\*.v tb\my_tb.v +SEED=7

elaborates the design, generates the C into %TEMP%\trsim-build, builds it with the Visual Studio C compiler (found through vswhere, linked against trsimrt.c from beside trsim.exe), and runs it. The program is cached under a hash of the generated C, so running an unchanged design again skips the C compiler. If the generator refuses a construct, or no C compiler is installed, trsim says so and runs the same command with the interpreter. -interpret asks for the interpreter directly, and -sdf always uses it.

To see or build the C yourself, -native writes it and stops. Generating the C does not simulate anything:

trsim -top my_tb -time 100000 -native build\my_tb.c rtl\*.v tb\my_tb.v

Then build it. With Microsoft's compiler:

cl /O2 /GL /Fe:my_tb.exe build\my_tb.c trsimrt.c /link /LTCG

/GL with /LTCG (whole-program optimisation) lets the compiler inline the runtime's small helpers into the generated code. On the RBT SoC (1659 signals, 9 ms simulated) it took the run from 8.1 s to 6.4 s; plain /O2 works too.

with gcc or clang (-flto is the equivalent of /GL):

gcc -O2 -o my_tb build/my_tb.c trsimrt.c

trsimrt.c is the runtime kernel — the event queue, the four-state value helpers, the format engine and the VCD writer. It is the only support file the generated code needs.

Then run it:

my_tb.exe

The program prints exactly what the interpreted run would print. -time sets the default end time; a number as the first argument overrides it.

Arguments that start with + are plusargs, read by $test$plusargs and $value$plusargs exactly as on the interpreter's command line:

my_tb.exe +HEX=prog.hex32 +VERBOSE
trsim -q -top my_tb rtl\*.v tb\my_tb.v +HEX=prog.hex32 +VERBOSE

That lets one build run many configurations: a testbench that reads its stimulus file name with $value$plusargs("HEX=%s", name) and loads it with $readmemh(name, mem) needs no regeneration per test.

Runtime controls

The generated program reads a few environment variables. These are useful precisely because they need no regeneration — you can get a waveform or a trace out of a binary you already built.

TRS_VCD=<file>

Dump every signal to a VCD, whether or not the design calls $dumpfile.

set TRS_VCD=run.vcd
my_tb.exe

TRS_TRACE=<substring>

Print every change of every signal whose hierarchical name contains the given text, with the time and the new value.

set TRS_TRACE=cpu.alu
my_tb.exe

The match is a plain substring, not a pattern. Signal names carry no brackets, so a filter like mem[ never matches anything &mdash; filter on the name and read the index from the output.

TRS_STATS=1

Print a summary when the run ends: events processed, signal updates, and where the time was spent.

TRS_PROGRESS=<n>

Print a line every n simulated time units, so a long run visibly moves.

What it will and will not compile

The compiled path covers a large subset of what the interpreter runs, not all of it. Where it meets something it cannot compile, it says so and stops &mdash; it does not generate code that would quietly be wrong:

native backend: unsupported construct 'empty right hand side' at source line 84
native backend: nothing generated - run this design with the interpreter
instead.

The most common thing to hit is a task call. Testbenches that factor their checks into tasks &mdash; which is good style, and which four of the six shipped examples do &mdash; are interpreter-only for now. The two examples without tasks, 04_fsm and 06_memory, build and run natively as they stand.

A practical arrangement is to keep the design itself free of constructs the compiled path rejects, and accept that a task-heavy testbench runs interpreted.

What it is worth

The compiled backend was built for, and is measured on, a real system-on-chip: 1361 signals and 598 processes, with a CPU, a cache, block RAM and a UART. It runs that design at roughly the speed of a commercial simulator and reproduces its output exactly &mdash; the same cache trace, the same bus traffic, the same bytes out of the UART.

For a small testbench the interpreter is quick enough and simpler to use. The compiled path earns its keep when the run is long: a design that takes minutes per simulated microsecond interpreted is a different proposition compiled.

Checking the two agree

Since both back ends share the front end, a difference between them is a bug in one of them and worth reporting. To compare:

trsim -q -top my_tb -time 100000 rtl\*.v tb\my_tb.v > interp.txt
trsim -q -top my_tb -time 100000 -native gen.c rtl\*.v tb\my_tb.v
cl /O2 /Fe:nat.exe gen.c trsimrt.c
nat.exe > native.txt
fc interp.txt native.txt

One caveat when you do: the interpreter and the compiled path can differ in what a signal reads before anything has driven it. The compiled path starts every variable at x, which is what the standard says; the interpreter is less strict about it in a few places. A difference confined to the first sample of an undriven signal is usually this, not a real divergence.

← All trsim manuals