Overview
Instruction-level simulators allow users to simulate the Coral NPU processor and test software without the need for physical hardware. The Coral NPU simulators can be used for system modeling, compiler validation, and software development.
There are two simulators for Coral NPU:
- Behavioral instruction simulator called MPACT-CoralNPU
- Cycle-accurate, Verilog-based simulator for exact hardware performance
emulation (
rvv_core_mini_axi_sim)
The Coral NPU simulators are housed in a separate GitHub repository located here.
Use the Verilog-based simulator to obtain precise, accurate results — exactly as would be seen on the Coral NPU hardware. You must model your system memories correctly to achieve this. This simulator is clock-cycle-accurate and so you are able to see what signals actually toggle by using the waveform generation option.
The Verilog-based simulator executes slowly, however, and so if all you need is functional equivalence then use the MPACT-CoralNPU simulator. The MPACT-CoralNPU simulator is much faster and so is ideal for early experimentation and software development.
Both tools facilitate simulation-based ML system testing, optimization, and
benchmarking. The rvv_core_mini_axi_sim cycle-accurate simulator is the tool
to use for hardware development and debugging.
MPACT-CoralNPU supports RISC-V scalar, floating-point, and vector instruction sets.
Google provides the simulator open-source files on GitHub so that users who are extending the Coral NPU hardware IP can also modify and build the simulators themselves.
Both Coral NPU simulators accept two input file formats: .elf (Executable
and Linkable Format) and .bin (binary). The .elf files contain extra
information that is helpful in debugging, while flattened .bin files are
smaller. Fully compiled .elf files are generally preferred for simulation
due to their flexibility with memory configurations and debugging data.
ELF file format for simulation
An .elf file is a standard binary file format used to load and execute
software
on embedded processors within a hardware simulator. It packages the compiled
code, data, and metadata needed for the simulation to function correctly.
The ELF format is the standard binary format used for executables, object code, and shared libraries in most Unix-based systems, including Linux and BSD.
An .elf file provides the initial state for the processor's memory. When the
simulation starts, the hardware's internal memory (block RAM) is loaded with
the code and data from the .elf file.
The ELF format allows the file to incorporate debugging information — specifically, symbol tables that map the machine code back to the original source code. This allows a debugger to help you troubleshoot your code during simulation by setting breakpoints and inspecting variables.
The common workflow when using .elf files in hardware simulation is:
- Software compilation: Write and compile the source code using a
cross-compiler that targets the specific processor in your hardware design.
The output is an
.elffile. - Adding the .elf to the project: Add the generated
.elffile to your hardware project, often within an integrated design environment (IDE). - Associating the .elf: Link the
.elffile to a specific processor instance in your hardware design. - Simulation: Run the hardware simulation. The simulator loads the contents
of the
.elffile into the simulated memory of the processor. - Debugging: Using the debugging tools in your IDE, you can interact with the running simulation, stepping through your software and hardware execution in a coordinated manner.
Using the MPACT-CoralNPU behavioral simulator
To get started using the MPACT-CoralNPU simulator, first complete the setup steps given in Software prerequisites and system setup.
To build the simulator executable from the source files, enter this command:
bazel build bazel build //sim:coralnpu_v2_sim
To start the simulator, enter:
bazel run //sim:coralnpu_v2_sim -- path/program.elf
To see a list of the command-line options (flags) available, use the --help
or --helpfull option:
bazel run //sim:coralnpu_v2_sim -- --help
--help Options |
Description |
|---|---|
--dtcm_length |
Set the length of the DTCM address range; default=32768. |
--dtcm_start_address |
Set the start address of the DTCM range; default=65536. |
--entry_point |
Optionally set the entry point of the program. |
--exit_on_ebreak |
Exit on ebreak instruction; default=false. |
--i or --interactive |
Interactive mode; default=false. |
--initial_misa_value |
Set initial value of the MISA (Machine ISA) register; default=1075843360. |
--itcm_length |
Set the length of the ITCM address range; default=8192. |
--itcm_start_address |
Set the start address of the ITCM range; default=0. |
--help |
Show these options. |
--helpfull |
Show additional options. |
--help=substring |
Show help for any options that contain this substring (in either name, description, or path). |
You can run the simulator in interactive mode by using the --i option:
bazel run //sim:coralnpu_v2_sim -- --i path/program.elf
This brings up a simple command shell in which you enter any of the following
commands (type help at the prompt to see this list):
| Interactive commands | Description |
|---|---|
quit |
Exit command shell. |
core [N] |
Direct subsequent commands to core N (default=0). |
run |
Run program from current PC until a breakpoint or exit. Wait until halted. |
run free |
Run program in background from current PC until breakpoint or exit. |
wait |
Wait for any free run to complete. |
step [N] |
Step N instructions (default=1). |
halt |
Halt a running program. |
reg get NAME [FORMAT] |
Get the value or register NAME. |
reg NAME [FORMAT] |
Get the value of register NAME. |
reg set NAME VALUE |
Set register NAME to VALUE. |
reg set NAME SYMBOL |
Set register NAME to value of SYMBOL. |
mem get VALUE [FORMAT] |
Get memory from location VALUE according to format. The format is a letter (o, d, u, x, or X) followed by bit width (8, 16, 32, 64). The default format is x32. |
mem get SYMBOL [FORMAT] |
Get memory from location SYMBOL and format according to FORMAT (see above). |
mem SYMBOL [FORMAT] |
Get memory from location SYMBOL and format according to FORMAT (see above). |
mem set VALUE [FORMAT] VALUE |
Set memory at location VALUE(1) to VALUE(2) according to FORMAT. Default format is x32. |
mem set SYMBOL [FORMAT] VALUE |
Set memory at location SYMBOL to VALUE according to FORMAT. Default format is x32. |
break set VALUE |
Set breakpoint at address VALUE. |
break set SYMBOL |
Set breakpoint at value of SYMBOL. |
break VALUE |
Set breakpoint at address VALUE. |
break SYMBOL |
Set breakpoint at value of SYMBOL. |
break clear VALUE |
Clear breakpoint at address VALUE. |
break clear SYMBOL |
Clear breakpoint at value of SYMBOL. |
break clear all |
Remove all breakpoints. |
help |
Display this help message. |
Using the cycle-exact RVV simulator
To get started using the cycle-exact rvv_core_mini_axi_sim simulator,
first complete the setup steps given in
Software prerequisites and system setup.
To build the RVV simulator executable from the source files, enter this command:
bazel build //tests/verilator_sim:rvv_core_mini_axi_sim
To start the simulator, enter:
bazel-bin/tests/verilator_sim/rvv_core_mini_axi_sim --binary program
To see a list of the command-line options (flags) available, use the –helpfull
option:
bazel-bin/tests/verilator_sim/rvv_core_mini_axi_sim --helpfull
| Option | Description |
|---|---|
--binary |
ELF or BIN binary program to execute |
--cycles |
Simulation cycles; default = 100000000 |
--debug_axi |
Enable AXI traffic debugging; default = false |
--instr_trace |
Log instructions to console; default = false |
--trace |
Dump VCD trace; default = false |
--helpfull |
Show these options |