debugging faq
Here you will found a limited list of common errors and issues you may run into when using Spatial. If your issue is not listed here, feel free to visit the forum to get more help.
+ Result with --sim does not match result with --synth
--sim does not match result with --synthThis is likely the most common issue you will run into when developing in Spatial, and we understand that it is frustrating and confusing. However, here we will discuss a few go-to strategies for trying to solve these kinds of issues and possible root causes for this.
1. Remove all coarse-grain pipelining and parallelization from the app and see if the most basic, vanilla version of the app passes. If the app still takes a long time to simulate, consider testing on a smaller subset of the input data or number of iterations for the sake of comparison between --sim and --synth. It is often useful to add ArgIns solely for the purpose of testing subsets of the app or input data. If this works, then slowly add the parallelization and pipelining back into the app to see which loop or parallelization factor is causing it to break.
The --sim simulator is using Scala to sequentially execute all of the hardware in the Accel. This means that it does not truly simulate situations where there could be loop-carry dependencies, race conditions, incoherency between memory buffers, etc. The VCS backend will simulate the behavior of the hardware in a cycle-accurate manner and will expose things that Scala will not.
If the Scala simulation still does not match the VCS simulation with every optimization turned off, consider posting a bug report or asking for help on the forum.
DRAMs or ArgOuts to inspect exactly what is going on with the problematic loops. This will often make it obvious what the issue is, and will reveal a non-safe parallelization or pipelining strategy. Unfortunately, there are no printlns for the --synth backend, so you must resort to this technique for manually planning your own debugging interface. You can also consider using exit() in your Accel to immediately quit when a certain condition is met, and future versions of Spatial will also contain breakpoint() to help you step through and debug your code.
3. As a last resort, you can inspect the waveforms generated by VCS by turning on the appropriate value in vcs.sw-resources/Top-harness.sv. You can generate either .VPD or .VCD waveforms with the vpd_on and vcd_on regs in this file, followed by make clean && make. You will likely want to pull up the html/controller_tree.html when inspecting the waveform to identify the skeleton of the controller hierarchy. Most of the memories should include their appropriate names as pulled from the original Spatial application source code.
+ What are these 'X' values in my results when running --sim?
In --sim, the X's refer to values that were derived from uninitialized memory. If you create an SRAM and read from an address before anything was written to that address, you will see an X. If this X is used for arithmetic with other numbers that actually have defined values, the result will still be X. When running --synth, you won't see X's. Depending on the board or simulator, you could see garbage data that doesn't make sense, or the uninitialized values could default to 0.
+ Does declaring a Reg in a loop initialize the Reg for each iteration?
No. Creating a Reg, or any other memory, is simply an instantiation of the backing hardware. In the following code, x will contain N at the end of the execution.
Foreach(N by 1){i =>
val x = Reg[Int](0);
x :+= 1;
}
If you want the register to reset for each iteration and have the final value in the register be 1, write:
Foreach(N by 1){i =>
val x = Reg[Int](0);
x.reset;
x :+= 1;
}
+ Error about "No package 'isl' found"
Be sure that you have libisl installed on your system and to gcc. You can run sudo apt-get install libisl-dev if you have apt.
+ Error about "GC overhead limit exceeded"
Compiling Spatial is a little memory intensive for now. The only fix for this error right now is to increase some of the default java options. For example:
export _JAVA_OPTIONS="-Xmx4g -Xss1024k -Xms1g"
+ Error from sbt about "Symbol '_' is missing from the classpath"
If you recently did git pull, it is possible that there is some messiness happening with your sbt cache. Running make clean should hopefully fix any errors that take on this form.
+ Error when trying to make generated code, usually about "key not found"
This error is generally due to a dirty generated folder that contains stray code from old builds of this app. SBT will recursively try to compile everything in your current directory, which may include old files. You should make a habit of running make generated code, usually about "key not found"rm -rf on the generated directory every time before you compile a Spatial app.