HDL_workflow/microwatt_tutorial.mdwn

   1 # New tutorial for setting up Microwatt chroot and running simulations
   2
   3 useful links:
   4
   5 * Libre-SOC page covering our workflow: [[HDL_workflow]]
   6 * Devscripts Libre-SOC page: [[devscripts]]
   7 * Original Microwatt Libre-SOC page: [[microwatt]]
   8 * [Libre-SOC Microwatt repo branch](https://git.libre-soc.org/?p=microwatt.git;a=tree;hb=refs/heads/verilator_trace)
   9 * [Libre-SOC devscripts repo](https://git.libre-soc.org/?p=dev-env-setup.git;a=tree)
  10 * [Verilator docs, commands](https://verilator.org/guide/latest/exe_verilator.html)
  11 * [Verilator runtime command documentation](https://verilator.org/guide/latest/exe_sim.html)
  12 * First steps for working with PowerISA instructions Libre-SOC page:
  13 [[/docs/firststeps]]
  14
  15 ## Development environment scripts
  16
  17 If you haven't already, clone Libre-SOC's development environment setup scripts.
  18 These are bash scripts, and greatly simplify the time it takes to create a:
  19
  20 - Stable environment
  21 - With all software and libraries at specific versions
  22 (which are known to work).
  23
  24 These attributes are absolutely critical, and no support will be
  25 provided, unless you use these scripts to setup a development environment. This
  26 helps us fix any bugs in the scripts, and make sure everyone runs on the same
  27 page.
  28
  29     $ git clone https://git.libre-soc.org/git/dev-env-setup.git
  30
  31 Do *look through* the
  32 [code](https://git.libre-soc.org/?p=dev-env-setup.git;a=tree) before running
  33 any of those scripts. They may be confusing, however after reading a few you'll
  34 start to become more familiar with them.
  35
  36 It is expected for you to use Debian, we mostly use 11 (Bullseye) for the host
  37 OS, while all the chroots run Debian 10 (Buster).
  38
  39
  40 ## Setting up chroot
  41
  42 Commands to run in terminal to setup a new chroot environment for microwatt
  43 simulations.
  44
  45     $ cd dev-env-setup
  46     $ sudo bash
  47     # ./mk-deb-chroot microwatt
  48     # ./cp-scripts-to-chroot microwatt
  49     # exit
  50     $ schroot -c
  51     (microwatt):$ cd dev-env-setup
  52     (microwatt):$ sudo bash
  53     (microwatt):# ./install-hdl-apt-reqs
  54     (microwatt):# ./verilator-install
  55     (microwatt):# ./hdl-tools-yosys
  56     (microwatt):# apt install gtkwave -y
  57     (microwatt):# exit
  58     (microwatt):$ cd ~/src/
  59     (microwatt):$ git clone https://git.libre-soc.org/git/microwatt.git
  60     (microwatt):$ cd microwatt
  61     (microwatt):$ git checkout verilator_trace
  62
  63 Make sure verilator binaries in $PATH:
  64
  65     (microwatt):$ export PATH=/usr/local/verilator/bin:$PATH
  66     (microwatt):$ export GHDLSYNTH=ghdl
  67
  68 (GHDLSYNTH needs to be redefined because the Makefile has default `ghdl.so`,
  69 but somewhere else '.so' gets appended. You may see the following error if you
  70 don't redefine:
  71 `ERROR: Can't load module
  72 ./ghdl.so':/usr/local/bin/../share/yosys/plugins/**ghdl.so.so**`)
  73 [IRC](https://libre-soc.org/irclog/%23libre-soc.2023-01-25.log.html#t2023-01-25T11:10:47)
  74
  75 ## Compiling the verilator sim for Microwatt
  76
  77 * [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)
  78
  79 Verilator creates a fairly fast simulation by converting the HDL design to C++,
  80 and then compiling a binary which the user runs.
  81
  82 To compile the verilator simulation, first set verilator as the target for the
  83 makefile:
  84
  85     (microwatt):$ export FPGA_TARGET=verilator
  86
  87 Before compiling, you can change the `THREADS` variable in the makefile, which
  88 will allow the compiled verilator simulation binary to use more than 1 thread
  89 (*make sure to check how many CPU threads you have before changing this!*)
  90
  91 To compile the verilator simulation binary, call make with the
  92 `microwatt-verilator` rule.
  93
  94     (microwatt):$ make microwatt-verilator
  95
  96
  97
  98 ## Compiling hello world code
  99
 100 We need some to actually run on the core, so...?
 101 Instructions assume you're still in the microwatt directory.
 102
 103     (microwatt):$ cd hello_world
 104     (microwatt):$ make
 105
 106 A `hello_world.bin` should be generated (the final binary to be loaded), as
 107 well as an [.elf file](https://en.wikipedia.org/wiki/Executable_and_Linkable_Format),
 108 and .hex (representing the binary data as hex text strings).
 109
 110 To view the symbol table (useful to see where various sections of the binary
 111 begin):
 112
 113     (microwatt):$ powerpc64le-linux-gnu-objdump -h hello_world.elf
 114     (microwatt):$ powerpc64le-linux-gnu-objdump -x hello_world.elf
 115
 116 `-h` shows just the section headers, `-x` shows all headers.
 117
 118 And to view the disassembly (great for learning about the PowerISA instructions,
 119 and for associating the binary hex with actual instructions):
 120
 121     (microwatt):$ powerpc64le-linux-gnu-objdump -d hello_world.elf
 122
 123 For more information about `objdump` (common utility, not just for PowerISA),
 124 see the manual pages.
 125
 126     (microwatt):$ man powerpc64le-linux-gnu-objdump
 127
 128 The binary is ready to go, now it can be loaded into the simulation.
 129
 130 ## Running the simulation
 131
 132 Run the `microwatt-verilator` binary, with `hello_world/hello_world.bin` as an
 133 argument:
 134
 135     (microwatt):$ time ./microwatt-verilator hello_world/hello_world.bin
 136
 137 `time` is a utility you can use to measure how long it takes to run the sim.
 138
 139 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.
 140
 141 If no characters are appearing after about 20 seconds, stop the simulation,
 142 as there might be other issues.
 143
 144 Single-threaded verilator sim binary, on a 2nd gen intel i5 (sandybridge)
 145 takes 53 seconds to print the ASCII lightbulb.
 146
 147 ## Analysing results after simulation
 148
 149 The following files will be generated during the sim:
 150
 151 - `bram.dump` - Shows the PC address and instruction being executed. If the sim
 152 hangs without any printing, view this file, as the processor may have hit an
 153 exception etc. Grows in size as the sim runs.
 154
 155 - `bram.snapshot.[NUMBER]` - Snapshot files of the contents of bram, can be
 156 used to resume the simulation. The number on the end corresponds to the tick
 157 time (i.e. 'bram.snapshot.1999990'). Pass the tick number on the end of the
 158 filename with the '-s' flag:
 159
 160     (microwatt):$ time ./microwatt-verilator hello_world/hello_world.bin -s 1999990
 161
 162 You'll get a message like this:
 163
 164     loading hello_world/hello_world.bin at 0x0 size 0x1888
 165     loading bram.snapshot.1999990 at 0x0 size 0x10000000
 166     restored at 1999990
 167
 168 These snapshots are generated at intervals of every 2,000,000 ticks.
 169
 170 - `verilator.save.[NUMBER]` - (TODO: Need to check) - Verilator model snapshot
 171 files.
 172
 173 - `microwatt-verilator.vcd` - (TODO: Need to check) - GTKWave waveform file,
 174 allowing you to look at processor signals and transitions during simulation.
 175 *Needs to be converted to fst file first*:
 176
 177     (microwatt):$ vcd2fst --vcdname=microwatt-verilator.vcd --fstname=microwatt-verilator.fst
 178     (microwatt):$ gtkwave microwatt-verilator.fst
 179
 180
 181 ## Verilator runtime commands
 182 A few examples:
 183
 184     # Show the version of verilator being used
 185     (microwatt):$ ./microwatt-verilator +verilator+version
 186