From 3ef11219d51b322172aa0734672a1f7037117292 Mon Sep 17 00:00:00 2001
From: Andrey Miroshnikov <andrey@technepisteme.xyz>
Date: Thu, 27 Apr 2023 15:01:26 +0000
Subject: [PATCH] microwatt_tutorial: New page for documenting chroot setup for
 Microwatt sim

---
 HDL_workflow/microwatt_tutorial.mdwn | 59 ++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)
 create mode 100644 HDL_workflow/microwatt_tutorial.mdwn

diff --git a/HDL_workflow/microwatt_tutorial.mdwn b/HDL_workflow/microwatt_tutorial.mdwn
new file mode 100644
index 000000000..ddfbfd955
--- /dev/null
+++ b/HDL_workflow/microwatt_tutorial.mdwn
@@ -0,0 +1,59 @@
+# New tutorial for setting up Microwatt chroot and running simulations
+
+useful links:
+
+* [Original Microwatt Libre-SOC wiki](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)
+
+## Setting up chroot
+
+    # ./mk-deb-chroot microwatt
+    # ./cp-scripts-to-chroot microwatt
+    $ schroot -c 
+    (microwatt):$ cd dev-env-scripts
+    (microwatt):$ sudo bash
+    (microwatt):# ./install-hdl-apt-reqs
+    (microwatt):# ./verilator-install
+    (microwatt):# ./hdl-tools-yosys
+    (microwatt):$ cd ~/src/
+    (microwatt):$ git clone https://git.libre-soc.org/git/microwatt.git
+    (microwatt):$ git checkout verilator_trace
+    
+Make sure verilator binaries in $PATH: 
+
+    (microwatt):$ export PATH=/usr/local/verilator/bin:$PATH
+    (microwatt):$ export GHDLSYNTH=ghdl
+
+(GHDLSYNTH needs to be redefined because the Makefile has default `ghdl.so`,
+but somewhere else '.so' gets appended. You may see the following error if you
+don't redefine: `ERROR: Can't load module `./ghdl.so':
+/usr/local/bin/../share/yosys/plugins/**ghdl.so.so**`)
+
+To run the Verilator simulation, set verilator as the target:
+
+    (microwatt):$ export FPGA_TARGET=verilator
+
+Compile the verilator simulation binary
+
+    (microwatt):$ make microwatt-verilator
+
+The Libre-SOC microwatt tutorial then shows the following command to time how
+long the sim takes to run:
+
+    (microwatt):$ time ./microwatt-verilator
+
+No additional arguments to the binary are specified.
+
+* [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)
+
+In the Makefile, I can see that `RAM_INIT_FILE` (line #144) is specified as
+`helloworld.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).
+
+That's good, means that the verilator sim binary *should already have the
+compiled binary in RAM*.
+
-- 
2.30.2