README.md

   1 <p align="center">
   2 <img src="media/microwatt-title.png" alt="Microwatt">
   3 </p>
   4
   5 # Microwatt
   6
   7 A tiny Open POWER ISA softcore written in VHDL 2008. It aims to be simple and easy
   8 to understand.
   9
  10 ## Simulation using ghdl
  11 <p align="center">
  12 <img src="http://neuling.org/microwatt-micropython.gif" alt="MicroPython running on Microwatt"/>
  13 </p>
  14
  15 You can try out Microwatt/Micropython without hardware by using the ghdl simulator. If you want to build directly for a hardware target board, see below.
  16
  17 - Build micropython. If you aren't building on a ppc64le box you
  18   will need a cross compiler. If it isn't available on your distro
  19   grab the powerpc64le-power8 toolchain from https://toolchains.bootlin.com
  20
  21 ```
  22 git clone https://github.com/mikey/micropython
  23 cd micropython
  24 git checkout powerpc
  25 cd ports/powerpc
  26 make -j$(nproc)
  27 cd ../../../
  28 ```
  29
  30 - Microwatt uses ghdl for simulation. Either install this from your
  31   distro or build it. Next build microwatt:
  32
  33 ```
  34 git clone https://github.com/antonblanchard/microwatt
  35 cd microwatt
  36 make
  37 ```
  38
  39 - Link in the micropython image:
  40
  41 ```
  42 ln -s ../micropython/ports/powerpc/build/firmware.bin main_ram.bin
  43 ```
  44
  45 - Now run microwatt, sending debug output to /dev/null:
  46
  47 ```
  48 ./core_tb > /dev/null
  49 ```
  50
  51 ## Synthesis on Xilinx FPGAs using Vivado
  52
  53 - Install Vivado (I'm using the free 2019.1 webpack edition).
  54
  55 - Setup Vivado paths:
  56
  57 ```
  58 source /opt/Xilinx/Vivado/2019.1/settings64.sh
  59 ```
  60
  61 - Install FuseSoC:
  62
  63 ```
  64 pip3 install --user -U fusesoc
  65 ```
  66 Fedora users can get FuseSoC package via
  67 ```
  68 sudo dnf copr enable sharkcz/danny
  69 sudo dnf install fusesoc
  70 ```
  71
  72 - Create a working directory and point FuseSoC at microwatt:
  73
  74 ```
  75 mkdir microwatt-fusesoc
  76 cd microwatt-fusesoc
  77 fusesoc library add microwatt /path/to/microwatt/
  78 ```
  79
  80 - Build using FuseSoC. For hello world (Replace nexys_video with your FPGA board such as --target=arty_a7-100):
  81
  82 ```
  83 fusesoc run --target=nexys_video microwatt --memory_size=8192 --ram_init_file=/path/to/microwatt/fpga/hello_world.hex
  84 ```
  85 You should then be able to see output via the serial port of the board (/dev/ttyUSB1, 115200 for example assuming standard clock speeds). There is a know bug where initial output may not be sent - try the reset (not programming button on your board if you don't see anything.
  86
  87 - To build micropython (currently requires 1MB of BRAM eg an Artix-7 A200):
  88
  89 ```
  90 fusesoc run --target=nexys_video microwatt
  91 ```
  92
  93 ## Testing
  94
  95 - A simple test suite containing random execution test cases and a couple of
  96   micropython test cases can be run with:
  97
  98 ```
  99 make -j$(nproc) check
 100 ```
 101
 102 ## Issues
 103
 104 This is functional, but very simple. We still have quite a lot to do:
 105
 106 - There are a few instructions still to be implemented
 107 - Need to add caches and bypassing (in progress)
 108 - Need to add supervisor state (in progress)