VexRiscv
Awesome RISC-V

VexRiscv

RISC-V ecosystem

VexRiscv is a 32-bit core written in SpinalHDL. Plugins decide which pipeline stages, caches and extensions a build includes. Charles Papon created it, and LiteX uses it as its default CPU for FPGA systems on chip.

Overview

SpecificationValue
ISA supportRV32IMAFDC
MicroarchitecturePlugin-assembled pipeline of two to more than five stages; caches, MMU and FPU are optional plugins
Performance density0.52–1.44 DMIPS/MHz and up to 2.57 CoreMark/MHz depending on plugins
Resource footprint504 LUTs for the smallest build to 2,883 LUTs for the Linux-capable build on Artix-7
Clock domain151–243 MHz on Artix-7 depending on configuration

VexRiscv is a configurable 32-bit RISC-V processor core developed using SpinalHDL, a hardware description language built on Scala. Designed primarily for FPGA implementations, it provides a vendor-independent architecture that can be synthesized for programmable logic devices from different manufacturers. Its modular design allows processor features and pipeline components to be selected or customized for different hardware targets, without relying on proprietary FPGA-specific blocks.

VexRiscv uses a plugin-based architecture in which individual processor features are implemented as independent, configurable components. These plugins can add functionality such as instruction and data caches, hardware multiplication, floating-point operations and memory management. The pipeline structure is equally configurable, supporting implementations ranging from two stages to more than five, depending on the selected components and performance requirements. This flexibility allows the core to be tailored to different resource and performance constraints. Minimal configurations can occupy approximately 500 FPGA lookup tables (LUTs), while more extensive implementations equipped with a memory management unit (MMU) provide the virtual memory support required to run operating systems such as Linux. VexiiRiscv is a variant optimized for iCE40 FPGAs.

Microarchitecture

VexRiscv builds its pipeline from plugins, so the stages and their contents change with the configuration.
VexRiscv builds its pipeline from plugins, so the stages and their contents change with the configuration.
The floating point unit is one plugin among several.
The floating point unit is one plugin among several. VexRiscv repository (MIT)

VexRiscv follows a modular architecture in which processor functionality is assembled through independently configurable plugins. Each plugin contributes a specific feature to the core, such as caching, multiplication, floating-point operations, memory management or hardware debugging. These components integrate with the processor pipeline, whose depth can vary from two stages to more than five depending on the selected configuration. This modularity supports implementations ranging from minimal designs to more complex configurations with caches and an MMU capable of running Linux.

BuildLUTs on Artix-7MHzDMIPS/MHzCoreMark/MHz
small, RV32I5042430.52not listed
full1,8401991.212.30
full + MMU2,0211511.242.35
Linux balanced, RV32IMA2,8831801.212.27
PluginEffect when enabled
Instruction and data cachesRaise performance, consume block RAM
MMUEnables Linux, adds area and latency
FPUAdds floating point instructions
Debug pluginExposes the debug module over JTAG
Branch predictionImproves control flow at some area cost

Memory and register map

In VexRiscv, addresses are assigned by the surrounding SoC. LiteX, a commonly used system-on-chip framework for VexRiscv, generates this map during SoC construction and exports the resulting peripheral and register definitions as build artifacts. It can also generate a device tree describing the platform's memory regions, peripherals and hardware configuration for use by the operating system.

Finding the map in a LiteX build
ls build/*/csr.* build/*/analyzer.*
litex_json2dts_linux build/*/csr.json > soc.dts
grep -n "reg = <" soc.dts
ℹ

A LiteX build writes the generated bus and register descriptions to the build directory alongside the map.

RegionOwner
RAM and ROMGenerated by LiteX for the target board
UART, timer, GPIOLiteX peripherals at generated addresses
Debug modulePresent when the debug plugin is enabled
External memoryBoard specific, described in the generated map

Physical implementation

VexRiscv provides implementation figures for different configurations across several FPGA families, illustrating the trade-off between resource consumption and operating frequency. The smallest build on iCE40 achieves 92 MHz in 1,130 logic cells.

MetricValue
Smallest build504 LUTs at 243 MHz on Artix-7 (smallest iCE40 build: 92 MHz in 1,130 logic cells, see VexiiRiscv)
Linux-capable build2,883 LUTs at 180 MHz on Artix-7
Performance0.52 to 1.44 DMIPS/MHz depending on plugins

Identifying the part

VexRiscv is synthesized into FPGA logic rather than supplied as a standalone processor chip. It is commonly used as the default CPU in LiteX-generated systems, although LiteX supports other processor architectures as well. To identify a VexRiscv implementation, examine the LiteX build configuration, generated SoC source files and synthesis reports. The generated device tree and CPU configuration can provide additional information about the processor architecture, ISA extensions and available hardware features.

⚠

LiteX boards do not label the core. The plugin set is recorded in the build artifacts or visible through the debug port.

Where it appearsHow to confirm
LiteX systemsGenerated map and CSRs in the build directory
FPGA boardsBoard files and the bitstream source
Linux on LiteXDevice tree and the presence of an MMU

Disassembly and debugging

Disassembly provides a way to inspect the instructions generated for a particular VexRiscv configuration. The supported instruction set depends on the plugins enabled during hardware generation. When examining firmware, the disassembler must account for the extensions available in the target configuration to correctly interpret the generated instructions. Compiler flags must likewise match the implemented ISA to avoid illegal instruction exceptions at runtime.

Tools
riscv32-unknown-elf-readelf -A firmware.elf
riscv32-unknown-elf-objdump -d -M no-aliases firmware.elf

# debug, when the classic debug plugin is enabled
# requires SpinalHDL's openocd_riscv fork with cpu0.yaml and a VexRiscv target config
openocd -f interface/ftdi/arty.cfg -f target/riscv.cfg
ItemValue
ISARV32IMAFDC in a full build, plugin dependent
Compiler flags-march=rv32ima -mabi=ilp32, or the subset the build enables; -march=rv32imafdc -mabi=ilp32d for full builds
Debug transportDebug plugin over JTAG, driven by LiteX
ResetSet by the generated SoC
misa (0x301)ISA and enabled extensions
mvendorid (0xF11)JEDEC vendor ID, read-only
marchid (0xF12)microarchitecture ID, read-only
mimpid (0xF13)implementation version, read-only
mhartid (0xF14)hart that runs the code, read-only

History

VexRiscv was started in 2017 by Charles Papon, the creator of SpinalHDL. The project established a plugin-based approach to processor design that Papon later carried into NaxRiscv, a more advanced RISC-V core featuring out-of-order execution. Both projects use SpinalHDL and share a modular design philosophy, allowing processor features to be assembled and customized through independent components.

Where it is used

LiteX, a widely used framework for building FPGA systems on chip, uses VexRiscv as its default CPU. The Linux on LiteX VexRiscv project boots Linux on low-cost FPGA boards, and the core also runs Zephyr and FreeRTOS, two operating systems for embedded devices.

Sources

  1. VexRiscv README
  2. LiteX
  3. Linux on LiteX VexRiscv
  4. LiteX documentation
  5. RISC-V Debug Specification