useful links:
+* Libre-SOC page covering our workflow: [[HDL_workflow]]
+* Devscripts Libre-SOC page: [[devscripts]]
* Original Microwatt Libre-SOC page: [[microwatt]]
* [Libre-SOC Microwatt repo branch](https://git.libre-soc.org/?p=microwatt.git;a=tree;hb=refs/heads/verilator_trace)
* [Libre-SOC devscripts repo](https://git.libre-soc.org/?p=dev-env-setup.git;a=tree)
* [Verilator docs, commands](https://verilator.org/guide/latest/exe_verilator.html)
* [Verilator runtime command documentation](https://verilator.org/guide/latest/exe_sim.html)
+* First steps for working with PowerISA instructions Libre-SOC page:
+[[/docs/firststeps]]
+
+## Development environment scripts
+
+If you haven't already, clone Libre-SOC's development environment setup scripts.
+These are bash scripts, and greatly simplify the time it takes to create a:
+
+- Stable environment
+- With all software and libraries at specific versions
+(which are known to work).
+
+These attributes are absolutely critical, and no support will be
+provided, unless you use these scripts to setup a development environment. This
+helps us fix any bugs in the scripts, and make sure everyone runs on the same
+page.
+
+ $ git clone https://git.libre-soc.org/git/dev-env-setup.git
+
+Do *look through* the
+[code](https://git.libre-soc.org/?p=dev-env-setup.git;a=tree) before running
+any of those scripts. They may be confusing, however after reading a few you'll
+start to become more familiar with them.
+
+It is expected for you to use Debian, we mostly use 11 (Bullseye) for the host
+OS, while all the chroots run Debian 10 (Buster).
+
## Setting up chroot
+Commands to run in terminal to setup a new chroot environment for microwatt
+simulations.
+
+ $ cd dev-env-setup
+ $ sudo bash
# ./mk-deb-chroot microwatt
# ./cp-scripts-to-chroot microwatt
+ # exit
$ schroot -c
- (microwatt):$ cd dev-env-scripts
+ (microwatt):$ cd dev-env-setup
(microwatt):$ sudo bash
(microwatt):# ./install-hdl-apt-reqs
(microwatt):# ./verilator-install
(microwatt):# ./hdl-tools-yosys
(microwatt):# apt install gtkwave -y
+ (microwatt):# exit
(microwatt):$ cd ~/src/
(microwatt):$ git clone https://git.libre-soc.org/git/microwatt.git
+ (microwatt):$ cd microwatt
(microwatt):$ git checkout verilator_trace
Make sure verilator binaries in $PATH:
./ghdl.so':/usr/local/bin/../share/yosys/plugins/**ghdl.so.so**`)
[IRC](https://libre-soc.org/irclog/%23libre-soc.2023-01-25.log.html#t2023-01-25T11:10:47)
-## Running Verilator sim
+## Compiling the verilator sim for Microwatt
+
+* [Libre-SOC Microwatt repo branch, Makefile](https://git.libre-soc.org/?p=microwatt.git;a=blob;f=Makefile;h=b764793fcdf5409be33a01f2440cea3717cb2a32;hb=refs/heads/verilator_trace)
-To run the Verilator simulation, set verilator as the target:
+Verilator creates a fairly fast simulation by converting the HDL design to C++,
+and then compiling a binary which the user runs.
+
+To compile the verilator simulation, first set verilator as the target for the
+makefile:
(microwatt):$ export FPGA_TARGET=verilator
-Compile the verilator simulation binary
+Before compiling, you can change the `THREADS` variable in the makefile, which
+will allow the compiled verilator simulation binary to use more than 1 thread
+(*make sure to check how many CPU threads you have before changing this!*)
+
+To compile the verilator simulation binary, call make with the
+`microwatt-verilator` rule.
(microwatt):$ make microwatt-verilator
-The Libre-SOC microwatt tutorial then shows the following command to time how
-long the sim takes to run (TODO: Find which args needed exactly):
- (microwatt):$ time ./microwatt-verilator +verilator+[SOME ARGS]
+## Compiling hello world code
+
+We need some to actually run on the core, so...?
+Instructions assume you're still in the microwatt directory.
+
+ (microwatt):$ cd hello_world
+ (microwatt):$ make
+
+A `hello_world.bin` should be generated (the final binary to be loaded), as
+well as an [.elf file](https://en.wikipedia.org/wiki/Executable_and_Linkable_Format),
+and .hex (representing the binary data as hex text strings).
+
+To view the symbol table (useful to see where various sections of the binary
+begin):
+
+ (microwatt):$ powerpc64le-linux-gnu-objdump -h hello_world.elf
+ (microwatt):$ powerpc64le-linux-gnu-objdump -x hello_world.elf
+
+`-h` shows just the section headers, `-x` shows all headers.
+
+And to view the disassembly (great for learning about the PowerISA instructions,
+and for associating the binary hex with actual instructions):
+
+ (microwatt):$ powerpc64le-linux-gnu-objdump -d hello_world.elf
+
+For more information about `objdump` (common utility, not just for PowerISA),
+see the manual pages.
+
+ (microwatt):$ man powerpc64le-linux-gnu-objdump
+
+The binary is ready to go, now it can be loaded into the simulation.
+
+## Running the simulation
+
+Run the `microwatt-verilator` binary, with `hello_world/hello_world.bin` as an
+argument:
+
+ (microwatt):$ time ./microwatt-verilator hello_world/hello_world.bin
+
+`time` is a utility you can use to measure how long it takes to run the sim.
+
+A pretty ASCII art of a lightbulb should be printed, and then the user can type any characters, which will be echoed back. To end the simulation press Ctrl+c.
+
+If no characters are appearing after about 20 seconds, stop the simulation,
+as there might be other issues.
+
+Single-threaded verilator sim binary, on a 2nd gen intel i5 (sandybridge)
+takes 53 seconds to print the ASCII lightbulb.
+
+## Analysing results after simulation
+
+The following files will be generated during the sim:
+
+- `bram.dump` - Shows the PC address and instruction being executed. If the sim
+hangs without any printing, view this file, as the processor may have hit an
+exception etc. Grows in size as the sim runs.
+
+- `bram.snapshot.[NUMBER]` - Snapshot files of the contents of bram, can be
+used to resume the simulation. The number on the end corresponds to the tick
+time (i.e. 'bram.snapshot.1999990'). Pass the tick number on the end of the
+filename with the '-s' flag:
+
+ (microwatt):$ time ./microwatt-verilator hello_world/hello_world.bin -s 1999990
+
+You'll get a message like this:
+
+ loading hello_world/hello_world.bin at 0x0 size 0x1888
+ loading bram.snapshot.1999990 at 0x0 size 0x10000000
+ restored at 1999990
+
+These snapshots are generated at intervals of every 2,000,000 ticks.
-* [Libre-SOC Microwatt repo branch, Makefile](https://git.libre-soc.org/?p=microwatt.git;a=blob;f=Makefile;h=610f48d8c89be6d5b9902d7f1bf61f8b6d98ffc0;hb=refs/heads/verilator_trace)
+- `verilator.save.[NUMBER]` - (TODO: Need to check) - Verilator model snapshot
+files.
-In the Makefile, the `RAM_INIT_FILE` (line #144) is specified as
-`hello_world.hex` (the Microwatt 'lightbulb' example code).
-The Makefile uses this `RAM_INIT_FILE` argument for generating the
-`microwatt.v` verilog file (line #249).
-Finally, to generate the `microwatt-verilator` binary, `microwatt.v` is pulled
-in as a dependency (line #254).
+- `microwatt-verilator.vcd` - (TODO: Need to check) - GTKWave waveform file,
+allowing you to look at processor signals and transitions during simulation.
+*Needs to be converted to fst file first*:
+
+ (microwatt):$ vcd2fst --vcdname=microwatt-verilator.vcd --fstname=microwatt-verilator.fst
+ (microwatt):$ gtkwave microwatt-verilator.fst
-That's good, means that the verilator sim binary *should already have the
-compiled binary in RAM*.
## Verilator runtime commands
A few examples:
projects / libreriscv.git / commitdiff