got dia files to work, they're autoconverted to tex

[libreriscv.git] / HDL_workflow / microwatt.mdwn

diff --git a/HDL_workflow/microwatt.mdwn b/HDL_workflow/microwatt.mdwn
index eabb87df90fc820e279212c4c6094ae0d6cea14f..3b568763be16b178085a7a2edde37eb5c70d74ef 100644 (file)
--- a/HDL_workflow/microwatt.mdwn
+++ b/HDL_workflow/microwatt.mdwn
@@ -24,6 +24,11 @@ Other Tutorials (Libre-SOC):
 * First steps for working with PowerISA instructions Libre-SOC page:
 [[/docs/firststeps]]
 
+## Video Tutorial
+
+[43min tutorial](https://youtu.be/02LCl3ang8g) was made and uploaded to
+Youtube, covering some of the material you'll find on this page.
+
 ## Development environment scripts
 
 If you haven't already, clone Libre-SOC's development environment setup scripts.
@@ -40,13 +45,18 @@ 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.
+any of those scripts.
+This is your own legal responsibility (to not run
+arbitrary code off of the internet) and we take no responsibility or accept
+any liability whatsoever for your use or misuse of 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).
+It is expected for you to use Debian for the host OS (anything else
+is unsupported: many contributors have repeatedly gotten into trouble by not
+following this advice), while all the chroots - which are developed
+very specifically for "reproducible builds" - run Debian 10 (Buster).
 
 ## Setting up chroot
 
@@ -134,9 +144,12 @@ begin):
 `-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):
+and for associating the binary hex with actual instructions), you can view the
+automatically generated `hello_world.as` file.
+
+Command to generate the disassembly:
 
-    (microwatt):$ powerpc64le-linux-gnu-objdump -d hello_world.elf
+    (microwatt):$ powerpc64le-linux-gnu-objdump -D hello_world.elf
 
 For more information about `objdump` (common utility, not just for PowerISA),
 see the manual pages.
@@ -265,15 +278,23 @@ 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
 
-## Running Linux kernel - TODO: Need to check
+## Running Linux kernel
 
 To run Linux on Microwatt, you'll need two binaries:
 
@@ -283,7 +304,22 @@ required).
 - The `dtbImage.microwatt` device tree Linux kernel. This can be compiled (see
 below), or a copy can be downloaded from: <https://ftp.libre-soc.org/dtbImage.microwatt>.
 
+Like with the micropython example, you'll need to increase the RAM size in the
+makefile, and recompile the microwatt-verilator binary.
+
+Uncomment the following:
+
+    MEMORY_SIZE=536870912
+
+Which will change the RAM size to 512KiB.
+
+As there is no `dtbImage.microwatt.hex`, you can leave `RAM_INIT_FILE` unchanged.
+
 ### Building the kernel - TODO:
+
+*(Please don't build the kernel yourself, until you've tested with the existing kernel linked
+above!)*
+
 On a POWER9 there is no need to install gcc-powerpc64le-linux-gnu, 
 you can omit CROSS_COMPILE and ARCH in this case
 
@@ -306,7 +342,7 @@ cross compilation is used. It is assumed you're already in `~/src/microwatt/`
 directory.
 
     (microwatt):$ cd litedram/gen-src/sdram_init/
-       (microwatt):$ make
+    (microwatt):$ make
 
 The resulting binary will be in the `obj/` directory.
 
@@ -315,8 +351,8 @@ The resulting binary will be in the `obj/` directory.
 Make sure to return back to `src/microwatt/`.
 
     (microwatt):$ cd ~/src/microwatt/
-       (microwatt):$ cp microwatt/arch/powerpc/boot/dtbImage.microwatt
-       (microwatt):$ ./microwatt-verilator sdram_init.bin dtbImage.microwatt
+    (microwatt):$ cp microwatt/arch/powerpc/boot/dtbImage.microwatt
+    (microwatt):$ ./microwatt-verilator sdram_init.bin dtbImage.microwatt
 
 This will take some time...