From: Andrey Miroshnikov Date: Sun, 7 May 2023 14:19:36 +0000 (+0100) Subject: microwatt_tutorial: Added links, extra info, debugging X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=56c31f68f659d51e2c52b718e3291c8c50159145;p=libreriscv.git microwatt_tutorial: Added links, extra info, debugging Expanded on chroot, verilator model and example code compilation. Added instructions for viewing binary hex and symbol table. On running the sim (with args). Expected time to print hello world ascii bulb. Post sim results. --- diff --git a/HDL_workflow/microwatt_tutorial.mdwn b/HDL_workflow/microwatt_tutorial.mdwn index 85f989727..a100199d3 100644 --- a/HDL_workflow/microwatt_tutorial.mdwn +++ b/HDL_workflow/microwatt_tutorial.mdwn @@ -2,25 +2,62 @@ 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: @@ -35,33 +72,111 @@ don't redefine: ./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: