| .. | ||
| docs | ||
| hdl | ||
| hds | ||
| rtl | ||
| setups | ||
| sw | ||
| LICENSE | ||
| README.md | ||
The NEORV32 RISC-V Processor
1. Overview
The NEORV32 Processor is a customizable microcontroller-like system on chip (SoC) that is based on the RISC-V NEORV32 CPU. The project is intended as auxiliary processor in larger SoC designs or as ready-to-go stand-alone custom microcontroller that even fits into a Lattice iCE40 UltraPlus 5k low-power FPGA running at 24 MHz.
Special focus is paid on execution safety to provide defined and predictable behavior at any time. Therefore, the CPU ensures that all memory access are acknowledged and no invalid/malformed instructions are executed. Whenever an unexpected situation occurs the application code is informed via precise and resumable hardware exceptions.
🤔 Want to know more? Check out the project's rationale.
📚 For detailed information take a look at the NEORV32 documentation (online at GitHub-pages).
🏷️ The project's change log is available in CHANGELOG.md.
To see the changes between official releases visit the project's release page.
📦 Exemplary setups targeting various FPGA boards and toolchains to get you started.
🪁 Supported by upstream Zephyr OS and FreeRTOS.
💡 Feel free to open a new issue or start a new discussion if you have questions, comments, ideas or if something is not working as expected. Or have a chat on our gitter channel. See how to contribute.
🚀 Check out the quick links below or directly jump to the User Guide to get started setting up your NEORV32 setup!
Project Key Features
- all-in-one package: CPU plus SoC plus Software Framework & Tooling
- completely described in behavioral, platform-independent VHDL - no primitives, macros, etc.
- be as small as possible while being as RISC-V-compliant as possible
- from zero to printf("hello world!"); - completely open source and documented
- easy to use even for FPGA/RISC-V starters – intended to work out of the box
Status
2. NEORV32 Processor Features
The NEORV32 Processor (top entity: rtl/core/neorv32_top.vhd)
provides a full-featured SoC build around the NEORV32 CPU. It is highly configurable via generics
to allow a flexible customization according to your needs. Note that all modules listed below are optional.
Memory
- processor-internal data and instruction memories (DMEM / IMEM) & cache (iCACHE)
- bootloader (BOOTLDROM) with serial user interface
- allows booting application code via UART or from external SPI flash
Timers
- machine system timer, 64-bit (MTIME), RISC-V spec. compatible
- general purpose 32-bit timer (GPTMR)
- watchdog timer (WDT)
Input/Output
- standard serial interfaces (UART, SPI, TWI / I²C)
- general purpose GPIO and PWM
- smart LED interface (NEOLED) to directly drive NeoPixel(TM) LEDs
SoC Connectivity
- 32-bit external bus interface, Wishbone b4 compatible (WISHBONE)
- 32-bit stream link interface with up to 8 independent RX and TX links
(SLINK)
- AXI4-Stream compatible
- external interrupt controller with up to 32 channels (XIRQ)
- custom functions subsystem (CFS) for tightly-coupled custom co-processor extensions
Advanced
- true random number generator (TRNG)
- on-chip debugger (OCD) accessible via JTAG interface - implementing the Minimal RISC-V Debug Specification Version 0.13.2 and compatible with OpenOCD and gdb
- bus keeper to monitor the CPU's bus transactions (BUSKEEPER)
FPGA Implementation Results - Processor
The hardware resources used by a specific processor setup is defined by the implemented CPU extensions, the configuration of the peripheral modules and some "glue logic". Section FPGA Implementation Results - Processor Modules of the online datasheet shows the resource utilization of each optional processor module to allow an estimation of the actual setup's hardware requirements.
The setups folder provides exemplary FPGA
setups targeting various FPGA boards and toolchains. These setups also provide resource utilization reports for different
SoC configurations. The latest utilization reports for those setups can be found in the report of the
Implementation Workflow.
3. NEORV32 CPU Features
The CPU (top entity: rtl/core/neorv32_cpu.vhd)
implements the RISC-V 32-bit rv32 ISA with optional extensions (see below). It is compatible to subsets of the
Unprivileged ISA Specification (Version 2.2)
and the Privileged Architecture Specification (Version 1.12-draft).
Compatibility is checked by passing the official RISC-V architecture tests
(see sim/README).
The core is a little-endian Von-Neumann machine implemented as multi-cycle architecture.
However, the CPU's front end (instruction fetch) and back end (instruction execution) can work independently to increase performance.
Currently, three privilege levels (machine and optional user and debug_mode) are supported. The CPU implements all three standard RISC-V machine
interrupts (MTI, MEI, MSI) plus 16 fast interrupt requests as custom extensions.
It also supports all standard RISC-V exceptions (instruction/load/store misaligned address & bus access fault, illegal
instruction, breakpoint, environment calls).
📚 In-depth detailed information regarding the CPU can be found in the Data Sheet: NEORV32 Central Processing Unit.
Available ISA Extensions
Currently, the following optional RISC-V-compatible ISA extensions are implemented (linked to the according
documentation section). Note that the X extension is always enabled.
RV32
[I/
E]
[A]
[B]
[C]
[M]
[U]
[X]
[Zfinx]
[Zicsr]
[Zicntr]
[Zihpm]
[Zifencei]
[Zmmul]
[PMP]
[DEBUG]
⚠️ The B, Zfinx and Zmmul RISC-V extensions are frozen but not officially ratified yet. Hence, there is no
upstream gcc support. To circumvent this, the NEORV32 software framework provides intrinsic libraries for these extensions.
FPGA Implementation Results - CPU
Implementation results for exemplary CPU configuration generated for an Intel Cyclone IV EP4CE22F17C6N FPGA using Intel Quartus Prime Lite 20.1 ("balanced implementation, Slow 1200mV 0C Model").
| CPU Configuration (version 1.5.7.10) | LEs | FFs | Memory bits | DSPs (9-bit) | f_max |
|---|---|---|---|---|---|
rv32i |
806 | 359 | 1024 | 0 | 125 MHz |
rv32i_Zicsr_Zicntr |
1729 | 813 | 1024 | 0 | 124 MHz |
rv32imac_Zicsr_Zicntr |
2511 | 1074 | 1024 | 0 | 124 MHz |
ℹ️ An incremental list of CPU extension's hardware utilization can found in the Data Sheet: FPGA Implementation Results - CPU.
ℹ️ The CPU and SoC provide advanced options to optimize for performance, area or energy. See User Guide: Application-Specific Processor Configuration for more information.
Performance
The NEORV32 CPU is based on a two-stages pipeline architecture (fetch and execute). The average CPI (cycles per instruction) depends on the instruction mix of a specific applications and also on the available CPU extensions.
The following table shows the performance results (scores and average CPI) for exemplary CPU configurations executing 2000 iterations of the CoreMark CPU benchmark.
| CPU Configuration (version 1.5.7.10) | CoreMark Score | CoreMarks/MHz | Average CPI |
|---|---|---|---|
small (rv32i_Zicsr) |
33.89 | 0.3389 | 4.04 |
medium (rv32imc_Zicsr) |
62.50 | 0.6250 | 5.34 |
performance (rv32imc_Zicsr + perf. options) |
95.23 | 0.9523 | 3.54 |
ℹ️ More information regarding the CPU performance can be found in the Data Sheet: CPU Performance.
4. Software Framework and Tooling
- core libraries for high-level usage of the provided functions and peripherals
- application compilation based on GNU makefiles
- gcc-based toolchain (pre-compiled toolchains available)
- SVD file for advanced debugging and IDE integration
- bootloader with UART interface console
- runtime environment for handling traps
- several example programs to get started including CoreMark, FreeRTOS and Conway's Game of Life
- doxygen-based documentation, available on GitHub pages
- supports implementation using open source tooling (GHDL, Yosys and nextpnr; in the future: "Verilog-to-Routing") - both, software and hardware can be developed and debugged with open source tooling
- continuous integration is available for:
- allowing users to see the expected execution/output of the tools
- ensuring specification compliance
- catching regressions
- providing ready-to-use and up-to-date bitstreams and documentation
📚 Want to know more? Check out Data Sheet: Software Framework.
5. Getting Started
This overview provides some quick links to the most important sections of the online Data Sheet and the online User Guide.
🔌 Hardware Overview
-
Rationale - NEORV32: why, how come, what for
-
NEORV32 Processor - the SoC
- Top Entity - Signals - how to connect to the processor
- Top Entity - Generics - configuration options
- Address Space - memory layout and boot configuration
- SoC Modules - available peripheral modules and memories
- On-Chip Debugger - online & in-system debugging of the processor via JTAG
-
NEORV32 CPU - the CPU
- RISC-V compatibility - what is compatible to the specs. and what is not
- Full Virtualization - hardware execution safety
- ISA and Extensions - available RISC-V ISA extensions
- CSRs - control and status registers
- Traps - interrupts and exceptions
💾 Software Overview
- Example Programs - test program execution on your setup
- Core Libraries - high-level functions for accessing the processor's peripherals
- Software Framework Documentation -
doxygen-based documentation
- Software Framework Documentation -
- Application Makefiles - turning your application into an executable
- Bootloader - the build-in NEORV32 bootloader
🚀 User Guide
- Toolchain Setup - install and setup RISC-V gcc
- General Hardware Setup - setup a new NEORV32 EDA project
- General Software Setup - configure the software framework
- Application Compilation - compile an application using
make - Upload via Bootloader - upload and execute executables
- Application-Specific Processor Configuration - tailor the processor to your needs
- Adding Custom Hardware Modules - add your custom hardware
- Debugging via the On-Chip Debugger - step through code online and in-system
- Simulation - simulate the whole SoC
- Hello World! - run a quick "hello world" simulation
©️ Legal
- Overview - license, disclaimer, limitation of liability for external links, proprietary notice, ...
- Citing - citing information
- Impressum - imprint
Acknowledgements
A big shout-out goes to the community and all the contributors, who helped improving this project! ❤️
RISC-V - Instruction Sets Want To Be Free!
Continuous integration provided by :octocat: GitHub Actions and powered by GHDL.