Software Emulator

Sparsr Software Emulator

There are two software devices, and they run different instruction sets. This page is the Software Emulator (SPARSR_BACKEND=softemu), which runs Sparsr Assembly and matches what the FPGA hardware decodes. If you wrote your kernel in C, you want the Sparsr VM instead — it runs RV32I, and the same kernel image will not work on both.

The Sparsr SDK includes a built-in Instruction Set Simulator (ISS) or Functional Simulator. This emulator allows developers to run, test, and debug their Sparsr Kernels entirely in software on the host CPU, without requiring access to an actual Sparsr hardware deployment (such as AWS EC2 F2 FPGA instances or dedicated silicon).

While executing your sparse matrix routines on the CPU emulator will be significantly slower than running them on the production hardware, it is the ideal environment for checking kernel functionality, validating algorithms, and rapidly iterating on both your Host Application and Kernel code during early development phases.

Key Characteristics

When designing and testing your applications with the Sparsr Software Emulator, please keep the following architectural details in mind:

  • Pure Software Execution: The emulator runs 100% on your host x64/amd64 CPU. No PCIe connection to an FPGA is required.
  • Instruction & Register Accurate: The emulator perfectly replicates the behavior of the Sparsr Instruction Set Architecture (ISA). It faithfully simulates standard 32-bit instructions as well as the custom wide instructions acting on the 4096-bit wA and wB wide registers. Your Sparsr Assembly code will yield the exact same mathematical and logical results as it would on hardware.
  • NOT Cycle-Accurate: The software emulator does not simulate the physical clock cycles of the processor. It evaluates instructions sequentially for functional correctness, meaning you cannot use it for exact microarchitectural profiling or precise timing analysis.
  • Emulated PCIe Latency: Data transfer functions (e.g.: sparsr_read_cmem(), sparsr_write_cmem()) will move data between your standard system RAM and the emulated CMEM space. The latency of these operations does not accurately reflect physical PCIe bus transfers.

How It Works

Typically, a Sparsr application consists of two parts:

  1. A Kernel, written in Sparsr Assembly Language and assembled into machine code using the Sparsr Cross-Assembler (spasms).
  2. A Host Application, written in C, which uses the Sparsr Host Library (libsparsr_host.so) to load the kernel (sparsr_load_kernel()), transfer data to/from CMEM, and trigger execution (sparsr_run_kernel()).

The Software Emulator integrates seamlessly into this existing workflow. You do not need to recompile your Kernel or rewrite your Host Application to switch between hardware and the emulator.

Usage

To use the Software Emulator, ensure you have downloaded the latest SDK package from the Sparsr Developer Zone.

Compile your C host application as you normally would, dynamically linking it against libsparsr_host.so.

When you are ready to execute the application in simulation mode, simply pass the SPARSR_BACKEND environment variable at runtime with the value softemu.

Example:

# Standard execution on PC
./my_host_app

# Simulated execution (runs entirely on CPU)
SPARSR_BACKEND=softemu ./my_host_app

Under the Hood

When the SPARSR_BACKEND=softemu environment variable is detected, the Sparsr Host Library (libsparsr_host.so) will dynamically and automatically load the Software Emulation Library (libsparsr_softemu.so) included in your SDK.

All standard API calls (sparsr_load_kernel, sparsr_run_kernel, etc.) will be intercepted and routed to the Sparsr Software Emulator instead of attempting a physical PCIe transaction with the Sparsr Hardware Platform.

Tracing what the emulator does

The emulator can print every instruction it executes and every memory access it makes. This is off by default. Set the SPARSR_TRACE environment variable to turn it on:

SPARSR_BACKEND=softemu SPARSR_TRACE=1 ./my_host_app

Any value except 0 and the empty string turns it on.

Trace lines go to standard error, not standard output, so you can keep them apart from what your own program prints:

SPARSR_TRACE=1 ./my_host_app 2> trace.log

Two kinds of line appear. [SoftEmu] lines come from the emulator itself and show instructions, register writes and memory accesses. [HostCommon] lines show how each CMEM row is compressed on its way to the device.

Leave it off unless you are debugging. Formatting and writing a line per instruction makes the emulator hundreds of times slower. One [SoftEmu] line always prints, whatever you set: the notice telling you that your kernel is running on the emulator rather than on Sparsr hardware.

Developer Note: The Software Emulator was designed to drastically lower the barrier to entry for Sparsr development. By developing locally and only deploying to AWS F2 instances when your kernel logic is finalized, you can significantly reduce your cloud compute costs and iteration times.