Isle Software Build

Published 22 Jan 2026 (DRAFT), Updated 20 May 2026 (DRAFT)

This appendix explains how to build Isle software with a RISC-V toolchain.

If you're new to the project, read Isle FPGA Computer for an introduction. See Isle Index for more pages.

Programming Language

Isle software is currently written in RISC-V assembler and needs to be assembled and linked on a PC before programming Isle. Assembler might seem overly low-level, but RISC-V assembler is surprisingly readable, and it lets us directly interact with our hardware. We'll introduce higher-level languages, such as Lua, as Isle evolves and we gain access to more memory.

See the relevant blog page for details of the software, for example Chapter 5 Software.

Install RISC-V Toolchain

You currently need to compile Isle software on an external computer. Cross-compiling to RISC-V is straightforward, with pre-built packages available for most OS.

Isle needs a RISC-V assembler and linker with RV32 (32-bit support). Isle doesn't use libc or newlib.

Building Isle Software

Before building, ensure BIN_PREFIX is correct in the relevant Makefile. For example, for chapter 5 software this is isle/software/book/ch05/Makefile.

The default BIN_PREFIX of riscv64-elf is correct for Arch Linux and macOS as installed above, but Fedora and Debian/Ubuntu/Pop!_OS users need to change or override it.

To build all the software for a specific chapter, change to that directory and run make. For example:

cd isle/software/book/ch05
make all

The software is assembled and turned into .mem files suitable for loading into memory at design time. We will add support for loading software at runtime from storage in future.

To change the software loaded at design time, amend FILE_SOFT in your dev board's top file. For example, to amend chapter 5 to run blink, edit top_ch05.v:

localparam FILE_SOFT = {SW, "/book/ch05/blink.mem"};

To create a disassembled version of the linked software, which is handy for debugging, run make with the program name and the `.dis` extension; for example:

cd isle/software/book/ch05
make hello.dis

Further Reading