microwatt is an OpenPOWER softcore small enough to read

Simulate first, and no board required

Microwatt is a tiny Open POWER ISA softcore written in VHDL 2008, and it aims to be simple and easy to understand. That aim is visible in the source tree, which is a long list of small files with obvious names: core.vhdl, control.vhdl, decode1.vhdl, decode2.vhdl, execute1.vhdl, fetch1.vhdl, loadstore1.vhdl, icache.vhdl, dcache.vhdl, mmu.vhdl, fpu.vhdl, divider.vhdl and multiply.vhdl, with a matching set of testbenches carrying the _tb suffix. The design splits the pipeline across separate decode and execute units, which is the kind of structure a reader can follow. The simulation path is the one to start with, and the project demonstrates it by running MicroPython on Microwatt under the GHDL simulator. The core is built with make, and the resulting testbench is run while sending the debug output to /dev/null:

./core_tb > /dev/null

The Makefile shows the same project can be built through Docker or Podman with make DOCKER=1 or make PODMAN=1, and the GHDL invocation there uses a ghdl image with the LLVM backend.

GHDL needs the LLVM or gcc backend, which is the first hurdle

The simulator requirement is the first practical obstacle, and the documentation is direct about it. Microwatt uses ghdl for simulation, either installed from your distro or built. It requires ghdl to be built with the LLVM or gcc backend, which not all distros do, and the note is that Fedora does while Debian and Ubuntu appear not to, and that ghdl with the LLVM backend is likely easier to build. If building ghdl from scratch is too much, the microwatt Makefile supports using Docker or Podman, and the Makefile hard-codes the container images accordingly, with ghdl/ghdl:buster-llvm-7 for simulation and synthesis, hdlc/ghdl:yosys for yosys, hdlc/nextpnr:ecp5 for the place and route step and hdlc/prog for openocd. Behind the container names is a real dependency chain, since the flow is ghdl for analysis, yosys for synthesis, nextpnr-ecp5 for the ECP5 place and route, ecppack to produce the bitstream and openocd to program the board. A reader trying this on a modern machine is installing a small FPGA toolchain, and the container path exists precisely because that chain is painful to assemble by hand.

MicroPython gives you something real to run

The choice of MicroPython as the demonstration payload is a good one, because it is a real program rather than a test vector. Building it means cloning MicroPython, moving to the powerpc port and building it:

git clone https://github.com/micropython/micropython.git
cd micropython
cd ports/powerpc
make -j$(nproc)
cd ../../..

If you are not on a ppc64le machine you need a cross compiler, and the documentation points at the powerpc64le-power8 toolchain from the Bootlin toolchain collection, noting that you may need to set the CROSS_COMPILE environment variable to the prefix, with the default being powerpc64le-linux-gnu-. A prebuilt MicroPython image is also available in the micropython/ directory, which removes the cross compilation step entirely for a quick try. The image is then linked into the core as the contents of the main RAM:

ln -s ../micropython/ports/powerpc/build/firmware.bin main_ram.bin

or, with the prebuilt image, ln -s micropython/firmware.bin main_ram.bin. The whole simulation loop, cross compile, link and run, is therefore reachable from a fresh machine with no hardware.

Linux on the core, and the glibc patch that comes with it

Mainline Linux supports Microwatt as of v5.14, and the Arty A7 is the best tested platform, with the OrangeCrab and ButterStick also tested. The userspace comes from buildroot, and the documentation is honest that a small change is required in glibc to support the VMX and AltiVec-less Microwatt, because float128 support is mandatory and GCC requires VSX and AltiVec for that. The change is included in a buildroot fork along with a defconfig, so the userspace build is:

git clone -b microwatt https://github.com/shenki/buildroot
cd buildroot
make ppc64le_microwatt_defconfig
make

with the output at output/images/rootfs.cpio. The kernel then needs the microwatt defconfig and the initramfs pointed at that cpio, with the result being a dtbImage.microwatt.elf. The gateware is built with FuseSoC, and the flash programming step uses a script in the microwatt/openocd directory with the flash address depending on the board, 0x400000 for the Arty A7 A100 and 0x300000 for the A35. The firmware in the gateware looks at the flash address and attempts to parse an ELF there, loading it to the address in the ELF header and jumping to it.

FuseSoC and Vivado for the FPGA path

The FPGA flow uses Vivado and FuseSoC, and the documentation targets a specific free edition, the 2019.1 webpack edition, with the setup step being the sourcing of the settings script:

source /opt/Xilinx/Vivado/2019.1/settings64.sh

FuseSoC is then installed with pip3 install --user -U fusesoc, and Fedora users are pointed at a copr repository that packages it. If it is your first time using FuseSoC you need to initialise it, and the documentation explains this is required to pull down the library components referenced by microwatt:

fusesoc init
fusesoc fetch uart16550
fusesoc library add microwatt /path/to/microwatt

The hello world build runs the microwatt target with a memory size and a RAM initialisation file, and it notes that for your own board you replace the target name, for example with a target of arty_a7-100, and that Digilent board files need to be installed first. Output is visible on the board serial port, and there is a known bug where the initial output may not be sent, in which case you press the reset rather than the programming button. Building MicroPython needs 1MB of BRAM, with an Artix-7 A200 given as an example.

What is not implemented, and the test suite that is

The issues section is short and honest. There are a few instructions still to be implemented, and they are listed as Vector, VMX and VSX. That is the same gap that forces the glibc patch in the Linux build, so the two facts in the documentation are the same fact seen from two sides, and it is the first thing to check if you are evaluating this for anything involving floating point work. The testing story is a simple test suite containing random execution test cases and a couple of MicroPython test cases, run with:

make -j$(nproc) check

The VUnit runner is python3 ./run.py with a parallelism argument of -p10, and the same file is used in the container path with the ghdl/vunit:llvm image. The repository also carries a GPL-style custom licence that GitHub cannot classify, with a LICENSE file at the root, so read it before reusing any of the design. The last push was on 2026-08-12 and there are no GitHub releases, so the commit history is the version marker. Overall this is a project whose value is legibility. A reader can read the VHDL, understand the pipeline, and run the thing in a simulator before touching hardware, and that is a rare combination in processor design.

Editorial conclusion

Adopt Microwatt when you want to study a complete processor design in a language you can read, or when you want to bring up Linux on a small FPGA and need a softcore you can debug at the RTL level. Do not adopt it for floating point vector work, because the vector, VMX and VSX instructions are still to be implemented and the Linux build needs a patched glibc for a core without AltiVec. Verify first that your GHDL is built with the LLVM or gcc backend, that your FPGA toolchain supports the target board files, and that you accept a software model that is explicitly unfinished in the instruction set.

Frequently asked questions

Official sources

1. antonblanchard/microwatt on GitHub
2. Issues
3. README