Spike: the RISC-V ISA simulator whose C++ interface is not a public API
Spike, a RISC-V ISA Simulator
At a glance
- What is it?
- Spike is the reference RISC-V ISA simulator, written in C, and its own version policy is unusual: the public API is the instruction set, not the code. The feature list is a catalogue of extension spec versions rather than a release history, which is where most readers misread it.
- Who is it for?
- Spike is the right tool when correctness of the ISA model matters more than speed, when you are writing a new instruction and need a reference to compare against, or when you need a debug shell that can stop on a physical address or a register equality.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly C, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- riscv-software-src/riscv-isa-sim3,277 ★ · +43
| Repository | 2026-09-24 | 2026-11-15 |
|---|---|---|
| riscv-software-src/riscv-isa-sim | 3.2k | 3.3k |
43 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The extension list is a spec catalogue, not a version history
The feature list is the longest thing in this project and the easiest to misread. The numbers beside each extension are the version of that extension's specification, not versions of Spike. The RV32I and RV64I base ISAs sit at v2.1, the embedded RV32E and RV64E bases at v1.9, the A extension at v2.1, F, D and Q at v2.2, and the machine, supervisor and user modes at v1.11. Several entries are still at draft versions: the P extension is v0.9.2, Zfbfmin and its vector counterparts Zvfbfmin and Zvfbfwma are v0.6, Sscofpmf is v0.5.2, Zvabd is v0.9, and Zvzip and Zilx are v0.1. Two entries carry a different marker entirely, Sdext and Sdtrig reading v1.0-STABLE. One entry has a host requirement attached: the V extension needs a 64-bit host. The memory model line is worth reading closely too, since conformance to both RVWMO and RVTSO is stated in the same breath as the fact that Spike itself is sequentially consistent, which is a stricter behaviour than either model requires.
Tags stop in 2021 while the tree keeps moving
Spike follows SemVer, and the stated purpose of that versioning is narrow: projects are versioned primarily to indicate when the API has been extended or rendered incompatible, so major bumps mean backwards-incompatible API changes, minor bumps mean new APIs added, and patch bumps mean backwards-compatible bug fixes. Against that policy the release list looks thin. The newest tag is v1.1.0, dated 2021-12-17, and the one before it is v1.0.0 from 2019-04-01, while the repository itself was pushed on 2026-10-02. Anyone tracking releases to decide whether their simulator has the instruction they need will be reading a five year old number. The same page also points its homepage field at a single tracker entry, https://riscv.atlassian.net/browse/RVG-476, rather than at a documentation site, and the license metadata reports no assertion even though a LICENSE file sits at the root of the tree. Neither of those is resolved here.
Adding an instruction is announced as two steps and numbered four
The section on extending the simulator opens by saying two steps are required, then presents four numbered items. The first two are the ones the count refers to. Describe the instruction's functional behavior in the file `riscv/insns/<new_instruction_name>.h`, using the other files in that directory as a starting point. Then add the opcode and opcode mask, either to `riscv/opcodes.h` or to the riscv-opcodes package, which will write it for you:
$ cd ../riscv-opcodes
$ vi opcodes // add a line for the new instruction
$ make installThe two items the count skips are the ones that produce the most common failure. The instruction also has to be added to `riscv/riscv.mk.in`, and if that is missed it is not compiled in at all and is treated as an illegal instruction, which looks like a decoder bug rather than a build list omission. Then rebuild. Two steps to write the instruction, two more to make the build know it exists.
The C++ interface to the internals is explicitly not public
The versioning paragraph contains the sentence that decides how anyone should vendor this project. Spike's principal public API is the RISC-V ISA. The C++ interface to Spike's internals is not considered a public API at this time, and backwards-incompatible changes to that interface will be made without incrementing the major version number. That is a deliberate statement that the C++ surface can break at any commit while the version stays put, so a downstream tool linking against libvnt or the disassembler is tracking a moving target by choice. The tree shows what such a tool would be consuming: autotools inputs including `configure.ac`, `aclocal.m4`, `config.h.in` and `Makefile.in`, a `riscv/` core, `fesvr/` for the frontend server used by external debuggers, `softfloat/` for floating point behaviour, `disasm/` and `spike_dasm/`, plus `customext/`, `arch_test_target/`, `ci-tests/`, `debug_rom/` and `fdt/`. Three pkg-config templates, `riscv-disasm.pc.in`, `riscv-fesvr.pc.in` and `riscv-riscv.pc.in`, indicate the install produces three libraries rather than a single binary.
configure assumes RISCV already points at a toolchain prefix
The build starts from an assumption rather than an instruction: the RISCV environment variable is expected to be set to the RISC-V tools install path, and nothing in the build steps sets it for you. From there it is an out-of-tree autotools build.
$ apt-get install device-tree-compiler libboost-regex-dev libboost-system-dev
$ mkdir build
$ cd build
$ ../configure --prefix=$RISCV
$ make
$ [sudo] make installThe `mkdir build` followed by `cd build` and `../configure` is the out-of-tree pattern, which keeps object files away from the source checkout. The prefix being the toolchain install path is worth noticing: the simulator installs its libraries and pkg-config files into the same prefix a cross toolchain uses, so an environment can end up holding both. On a `yum` system the documented substitution is `yum install dtc` for the first step, which covers the device tree compiler but says nothing about the two Boost development packages, so those two remain unaccounted for on that path.
Running one program needs a second toolchain and a proxy kernel
After the simulator is built, nothing in this repository can execute a bare-metal program for you. Running even a hello world needs three separate pieces: spike itself, the riscv-gnu-toolchain, and riscv-pk, the proxy kernel, which is a different project. The compile step uses the bare metal target prefix:
$ riscv64-unknown-elf-gcc -o hello hello.cand the run step hands the resulting ELF to the proxy kernel rather than to the simulator directly:
$ spike pk helloThat indirection is the shape of the whole workflow. Spike models the machine, not the environment, so anything a program expects from an operating system has to come from the proxy kernel sitting on top of it. The debugging material makes the same point from another angle, because a program written for bare metal starts with no stack pointer, which is why the sample used later declares its wait variable `volatile` and carries a comment saying not to use the stack since sp is not set up.
The OpenBSD recipe builds with gmake and installs with make
OpenBSD gets its own page because the host toolchain differs. The requirements are bash, gmake, dtc and clang.
$ pkg_add bash gmake dtc
$ exec bash
$ export CC=cc; export CXX=c++
$ mkdir build
$ cd build
$ ../configure --prefix=$RISCV
$ gmake
$ [doas] make installThe `export CC=cc; export CXX=c++` line is worth pausing on. Spike is a host program that models the guest, so a native compiler is correct here, and the recipe forces the system compiler instead of leaving the choice open. The `exec bash` is there because the build needs a bash the default shell is not. What is inconsistent is the last line: the recipe builds with `gmake` and then installs with `make install`, on a platform where the reason for installing gmake in the first line is that the base system does not provide GNU make under that name. The privileged step is also spelled with `doas` here rather than the `sudo` used on Linux.
Debug mode reads memory in two address spaces and stops on equalities
Interactive debug mode is entered with `spike -d pk hello`, and its commands are mostly about looking at state. Registers take a core number first, so `: reg 0 a0` inspects a0 on core 0, and floating point registers come in single and double precision flavours, `: fregs 0 ft0` and `: fregd 0 ft0`, chosen by whether you want the register printed at that width. Memory is the part that catches people out, because there are two forms: `: mem 2020` reads a physical address in hex, while `: mem 0 2020` reads a virtual address and again leads with the core. Execution advances a single instruction on the enter key, and the stopping commands take the same address and register grammar: `: until pc 0 2020` stops when the program counter matches, `: until reg 0 mie a` when a register equals a value, and `: until mem` on a full 64-bit word. `: while mem ...` is the inverse, running as long as an equality holds, and `: r` continues without stopping. The mode is also reachable from a running simulation at any point with `<control>-<c>`, which doubles as the way to end the run, alongside `: q`.
Editorial conclusion
Spike is the right tool when correctness of the ISA model matters more than speed, when you are writing a new instruction and need a reference to compare against, or when you need a debug shell that can stop on a physical address or a register equality. It is the wrong tool for performance work, since a functional model is not a timing model, and its extension support tracks upstream spec versions, several of which are still at v0.x. Before depending on it, check three things. The newest release tag is v1.1.0 from 2021-12-17 while the tree has been pushed as recently as 2026-10-02, so pin a commit rather than a tag. The C++ interface to the internals is stated not to be a public API, and incompatible changes to it will land without a major version bump. And the license metadata reports no assertion even though a LICENSE file sits at the repository root, so resolve the terms yourself before shipping anything built on it.
Frequently asked questions
How do I build Spike from source on Linux?
Set RISCV to the RISC-V tools install path first, because the build assumes it exists. Install device-tree-compiler plus the Boost regex and system development packages, then create a build directory, run `../configure --prefix=$RISCV` from inside it, and finish with `make` and `make install`. The output goes into the same prefix a cross toolchain uses.
Is Spike's C++ interface a stable API?
No, and the project says so directly. The principal public API is the RISC-V ISA, and the C++ interface to the internals is not considered a public API at this time, with backwards-incompatible changes to it made without incrementing the major version number. Versioning follows SemVer otherwise, with major for incompatible API changes, minor for added APIs and patch for compatible fixes.
What do I need to run my own program on Spike?
Three separate pieces: spike, the riscv-gnu-toolchain, and riscv-pk, the proxy kernel, which lives in another project. Compile with `riscv64-unknown-elf-gcc -o hello hello.c` and then run `spike pk hello`. Spike models the machine rather than an operating system, so system services come from the proxy kernel layer.
What RISC-V extensions does Spike support?
The list runs from the RV32I and RV64I bases through the M, A, B, C, F, D and Q extensions, the vector V extension which needs a 64-bit host, the scalar and vector cryptography groups, the cache-block and control-bitfield extensions, and the supervisor and hypervisor extensions including Svnapot, Svpbmt, Svinval, Svadu, Svade, Smepmp and Smstateen. Several entries are still at draft versions such as v0.1 and v0.6.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/riscv-software-src-riscv-isa-sim)Star history chart for your README
[](https://hysenlabs.com/projects/riscv-software-src-riscv-isa-sim)Was this useful?