From 5195c239fd6b37e6cb10ac0c4e0c1299ec494885 Mon Sep 17 00:00:00 2001
From: Andrey Miroshnikov <andrey@technepisteme.xyz>
Date: Thu, 3 Aug 2023 13:01:08 +0000
Subject: [PATCH] microwatt.mdwn: Added to using Libre-SOC core.
 gen_core_with_svp64.mdwn: New file explaining how to add SVP64 to LS core.

---
 HDL_workflow/gen_core_with_svp64.mdwn | 83 +++++++++++++++++++++++++++
 HDL_workflow/microwatt.mdwn           | 10 +++-
 2 files changed, 92 insertions(+), 1 deletion(-)
 create mode 100644 HDL_workflow/gen_core_with_svp64.mdwn

diff --git a/HDL_workflow/gen_core_with_svp64.mdwn b/HDL_workflow/gen_core_with_svp64.mdwn
new file mode 100644
index 000000000..4ffee9ca0
--- /dev/null
+++ b/HDL_workflow/gen_core_with_svp64.mdwn
@@ -0,0 +1,83 @@
+# Tutorial for generating a Microwatt-compatible Libre-SOC core with SVP64
+functionality
+
+Useful links (Libre-SOC):
+
+* Libre-SOC page covering our workflow: [[HDL_workflow]]
+* Devscripts Libre-SOC page: [[devscripts]]
+* Microwatt tutorial Libre-SOC page: [[microwatt]]
+* ls2 tutorial Libre-SOC page: [[ls2]]
+* [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)
+* [Bug #1127](https://bugs.libre-soc.org/show_bug.cgi?id=1126)
+
+Other Tutorials (Libre-SOC):
+
+* 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.
+
+## Setting up chroot for core generation
+
+Scripts we will be using for the setup are:
+
+* `mk-deb-chroot`, `cp-scripts-to-chroot` for chroot setup
+* `install-hdl-apt-reqs`, `verilator-install`, `hdl-tools-yosys` for working
+with Microwatt
+
+(*Current limitation for `mk-deb-chroot`, is that you must be the first user on
+the host machine, having user ID 1000.*)
+
+Commands to run in terminal to setup a new chroot environment for microwatt
+simulations.
+
+    $ cd dev-env-setup
+    $ sudo bash
+    # ./mk-deb-chroot gen_cores
+    # ./cp-scripts-to-chroot gen_cores
+    # exit
+    $ schroot -c gen_cores
+    (gen_cores):$ cd dev-env-setup
+    (gen_cores):$ sudo bash
+    (gen_cores):# ./install-hdl-apt-reqs
+    (gen_cores):# ./hdl-tools-yosys
+    (gen_cores):# ./hdl-dev-repos
+    (gen_cores):# exit
+    (gen_cores):$ cd ~/src/openpower-isa/
+    (gen_cores):$ git checkout 1bbfcce929c9a1d6b1dc0fc68c84296bcc58eea1
+    (gen_cores):$ sudo python3 setup.py develop
+    (gen_cores):$ make svanalysis
+    (gen_cores):$ make pywriter
+    (gen_cores):$ make pyfnwriter
+    (gen_cores):$ cd ../soc/
+    (gen_cores):$ make microwatt_external_core
+
+At this point you should end up with `external_core_top.v` verilog file, which
+contains the Libre-SOC core (with Microwatt-compatible interfaces).
+
+## Setting up chroot for simulation in Microwatt SoC
+
+Using the microwatt repo's soc for verilator simulation works well, so this
+is a good option if you just need to run/test programs compiled for POWER SFFS.
+
+Please see [[microwatt]] page for details how to setup a microwatt chroot.
+
+## Setting up chroot for FPGA synthesis with ls2 SoC peripheral fabric
+
+At the moment this is not working yet. TODO:
+
+Please see [[ls2]] page for details how to setup a ls2 chroot.
+
diff --git a/HDL_workflow/microwatt.mdwn b/HDL_workflow/microwatt.mdwn
index a203971c7..fa0d35183 100644
--- a/HDL_workflow/microwatt.mdwn
+++ b/HDL_workflow/microwatt.mdwn
@@ -270,10 +270,18 @@ A few examples:
 
 ## Building `microwatt-verilator` using the Libre-SOC core
 
+In the Makefile, you need to set `EXTERNAL_CORE` to true, and copy the
+generated core from soc repo to microwatt. *(If you use a separate chroot to
+generate Libre-SOC cores, then you'll need to copy from that chroot to
+microwatt chroot from host.*
+
 	cd /path/to/soc
 	make microwatt_external_core
 	cp external_core_top.v /path/to/microwatt
-	cd /path/to/microwatt
+
+Then compile verilator sim binary as before:
+
+	cd ~/src/microwatt/
 	export FPGA_TARGET=verilator
 	export GHDLSYNTH=ghdl
 	make microwatt-verilator
-- 
2.30.2