# Tutorial for setting up Microwatt chroot and running simulations
-TODO WIP integrate from <https://libre-soc.org/irclog/%23libre-soc.2022-01-26.log.html>
-
Useful Links (External):
* <https://codeconstruct.com.au/docs/microwatt-orangecrab/>
* 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.
$ 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
## Compiling hello world code
-We need some to actually run on the core, so...?
+We need some code to actually run on the core, so start with the 'hello world'.
Instructions assume you're still in the microwatt directory.
(microwatt):$ cd hello_world
`-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.
## 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:
+
+- The `sdram_init.bin`, which is easy to compile (no additional software
+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!)*
-### Building the kernel
On a POWER9 there is no need to install gcc-powerpc64le-linux-gnu,
you can omit CROSS_COMPILE and ARCH in this case
This will produce a file
microwatt/arch/powerpc/boot/dtbImage.microwatt
-### Building sdram_init.bin
-This needs gcc-powerpc64le-linux-gnu if cross compilation is used.
+### Building `sdram_init.bin`
+This needs gcc-powerpc64le-linux-gnu (already included in the setup step) if
+cross compilation is used. It is assumed you're already in `~/src/microwatt/`
+directory.
- cd microwatt
- cd litedram/gen-src/sdram_init/
- make
+ (microwatt):$ cd litedram/gen-src/sdram_init/
+ (microwatt):$ make
+
+The resulting binary will be in the `obj/` directory.
### Running the simulation
- cp microwatt/arch/powerpc/boot/dtbImage.microwatt
- ./microwatt-verilator sdram_init.bin dtbImage.microwatt
+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
+
+This will take some time...
+
+### Sysconn information
+
+TODO WIP integrate from <https://libre-soc.org/irclog/%23libre-soc.2022-01-26.log.html>
+
+Sysconn is a module which includes information about the SoC, and the info is
+printed at the start of the simulation.
+
+### Time benchmarks
+
+`microwatt-verilator` was compiled with 3 threads for faster simulation.
+
+- Time to finish printing Sysconn info: about 1min
+- Time to allocate bytes to kernel: ?
+- Time to login prompt: about 1 hour
+- Time to user shell: ?
### TODO: buildroot
projects / libreriscv.git / blobdiff