NEORV32 (RISC-V) by zerogravity

A customizable, lightweight and open-source 32-bit RISC-V soft-core microcontroller written in platform-independent VHDL.

GitHub Pages Documentation
riscv-arch-test Processor Implementation Windows

NEORV32

The NEORV32 RISC-V Processor

license release DOI

datasheet (pdf) datasheet (html) userguide (pdf) userguide (html) doxygen

  1. Overview
    1. Key Features
  2. Processor/SoC Features
    1. FPGA Implementation Results
  3. CPU Features
    1. Available ISA Extensions
    2. FPGA Implementation Results
    3. Performance
  4. Software Framework & Tooling
  5. Getting Started :rocket:

1. Overview

neorv32 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 / customizable microcontroller.

:information_source: Want to know more? Check out the project's rationale.

:books: For detailed information take a look at the NEORV32 documentation (online at GitHub-pages). The doxygen-based documentation of the software framework is also available online at GitHub-pages.

:label: The project's change log is available in CHANGELOG.md. To see the changes between official releases visit the project's release page.

:package: The setups folder provides exemplary setups targeting various FPGA boards and toolchains to get you started. Several example programs to be run on your setup can be found in sw/example.

:spiral_notepad: Check out the project boards for a list of current ideas, TODOs, features being planned and work-in-progress.

:bulb: 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. Check out how to contribute in CONTRIBUTE.md.

:rocket: Check out the quick links below or directly jump to the User Guide to get started setting up your NEORV32 setup!

Project Key Features

  • [x] all-in-one: CPU plus Processor/SoC plus Software Framework & Tooling
  • [x] completely described in behavioral, platform-independent VHDL - no primitives, macros, etc.
  • [x] fully synchronous design, no latches, no gated clocks
  • [x] be as small as possible (while being as RISC-V-compliant as possible) – but with a reasonable size-performance trade-off: the processor (CPU including privileged architecture) fits innto a Lattice iCE40 UltraPlus 5k low-power FPGA running at 24 MHz
  • [x] from zero to printf("hello world!"); - completely open source and documented
  • [x] easy to use even for FPGA/RISC-V starters – intended to work out of the box

[back to top]

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. In-depth detailed information regarding the processor/SoC can be found in the :books: online documentation - "NEORV32 Processors (SoC)".

Memory

  • processor-internal data and instruction memories (DMEM / IMEM) & cache (iCACHE)
  • bootloader (BOOTLDROM) with serial user interface
    • supports boot via UART or from external SPI flash

Timers

  • machine system timer (MTIME), RISC-V spec. compatible
  • watchdog timer (WDT)

IO

SoC Connectivity and Integration

  • 32-bit external bus interface, Wishbone b4 compatible (WISHBONE)
    • wrapper for AXI4-Lite master interface
  • 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

:information_source: It is recommended to use the processor setup even if you want to use the CPU in stand-alone mode. Just disable all optional processor-internal modules via the according generics and you will get a "CPU wrapper" that provides a minimal CPU environment and an external memory interface (like AXI4). This minimal setup allows to further use the default bootloader and software framework. From this base you can start building your own processor system.

[back to top]

FPGA Implementation Results - Processor

The hardware resources used by a specific processor setup is defined by the implemented CPU extensions (see below), 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.

:information_source: The setups folder provides exemplary FPGA setups targeting various FPGA boards and toolchains. These setups also provide resource utilization reports for different SoC configurations

[back to top]

3. NEORV32 CPU Features

:books: In-depth detailed information regarding the CPU can be found in the online documentation - "NEORV32 Central Processing Unit".

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 implements a little-endian Von-Neumann architecture using two pipeline stages, where each stage can operate in a multi-cycle processing scheme. The CPU supports three privilege levels (machine and optional user and debug_mode), the 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). See :books: "Full Virtualization" for more information.

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] [C] [M] [U] [X] [Zbb] [Zfinx] [Zicsr] [Zifencei] [Zmmul] [PMP] [HPM] [DEBUG]

:warning: The Zbb, 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.

[back to top]

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"). The timing information is derived from the Timing Analyzer / Slow 1200mV 0C Model. No constraints were used at all.

Results generated for hardware version 1.5.7.10.

CPU Configuration LEs FFs Memory bits DSPs (9-bit) f_max
rv32i 806 359 1024 0 125 MHz
rv32i_Zicsr 1729 813 1024 0 124 MHz
rv32imac_Zicsr 2511 1074 1024 0 124 MHz

:information_source: An incremental list of CPU extension's hardware utilization can found in online documentation - "FPGA Implementation Results - CPU".

:information_source: The CPU provides options to further reduce the footprint (for example by constraining the CPU-internal counters). See the online data sheet for more information.

[back to top]

Performance

The NEORV32 CPU is based on a two-stages pipelined architecture. Since both stage use a multi-cycle processing scheme, each instruction requires several clock cycles to execute (2 cycles for ALU operations, up to 40 cycles for divisions). 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 (relative CoreMark score and average cycles per instruction) for exemplary CPU configuration running 2000 iterations of the CoreMark CPU benchmark. The source files are available in sw/example/coremark.

:information_source: A simple port of the Dhrystone benchmark is also available: sw/example/dhrystone

**CoreMark Setup**
Hardware:       32kB IMEM, 8kB DMEM, no caches, 100MHz clock
CoreMark:       2000 iterations, MEM_METHOD is MEM_STACK
Compiler:       RISCV32-GCC 10.1.0 (rv32i toolchain)
Compiler flags: default, see makefile; optimization -O3

Results generated for hardware version 1.5.7.10.

CPU Configuration 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

:information_source: More information regarding the CPU performance can be found in the online documentation - "CPU Performance".

[back to top]

4. Software Framework and Tooling

:books: In-depth detailed information regarding the software framework can be found in the online documentation - "Software Framework".

  • 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)
  • 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

[back to top]

5. Getting Started

This overview provides some quick links to the most important sections of the online Data Sheet and the online User Guide.

:electric_plug: Hardware Overview

:floppy_disk: Software Overview

:rocket: User Guides (see full User Guide)

:copyright: Legal

  • Overview - license, disclaimer, proprietary notice, ...
  • Citing - citing information (DOI)
  • Impressum - imprint (:de:)

[back to top]

Acknowledgements

A big shoutout to all contributors, who helped improving this project! :heart:

RISC-V - Instruction Sets Want To Be Free!

Continous integration provided by :octocat: GitHub Actions and powered by GHDL.

Made with :coffee: in Hanover, Germany :eu:

BSD 3-Clause License

Copyright (c) 2021, Stephan Nolting
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this
   list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its
   contributors may be used to endorse or promote products derived from
   this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Project Meta

  • Registered on LibreCores 1 year ago
  • Project started 1 year ago
  • Last commit 15 days ago

Commits

{"labels":[2020,2021],"series":[[818,1746]]}

Commits per year

Contributors

{"labels":[2020,2021],"series":[[1,14]]}

Unique contributors per year

Releases

v1.6.1 is is the latest of 23 releases.

  • v1.6.1
    Sep 28, 2021 c938c6c
  • v1.6.0
    Sep 11, 2021 eb4ba9f
  • v1.5.9
    Aug 13, 2021 8bf4b70
  • v1.5.8
    Jul 22, 2021 984966c
  • v1.5.7
    Jun 23, 2021 569e8d7
  • v1.5.6.0
    Jun 1, 2021 2723525
  • v1.5.5.0
    May 10, 2021 a2e306e
  • v1.5.4.0
    Apr 17, 2021 e4036f6
  • v1.5.3.0
    Mar 24, 2021 9254366
  • v1.5.2.0
    Mar 1, 2021 9a2919d
  • v1.5.1.0
    Feb 7, 2021 0a21b7c
  • v1.5.0.0
    Jan 11, 2021 085fa53
  • v1.4.9.0
    Dec 20, 2020 9a96ee4
  • v1.4.8.0
    Dec 1, 2020 9240306
  • v1.4.7.0
    Nov 11, 2020 d27150c
  • v1.4.6.0
    Oct 24, 2020 c9d213b
  • v1.4.5.0
    Oct 13, 2020 cd48d5a
  • v1.4.4.0
    Oct 5, 2020 e203f1f
  • v1.4.3.0
    Sep 17, 2020 284c5a9
  • v1.4.0.0
    Aug 29, 2020 1f85fe4
  • v1.3.7.0
    Aug 14, 2020 54283c1
  • v1.3.6.0
    Aug 3, 2020 7a760cc
  • v1.2.0.5
    Jul 20, 2020 4a2f859

Languages

{"labels":["Others","VHDL","C","make","AsciiDoc","Markdown","C\/C++ Header","YAML","Bourne Shell","Tcl\/Tk","XML","Assembly"],"series":[6,76,42,35,33,32,25,7,6,5,4,4]}

Share of languages used

Data Sheet
Project Web Site
https://github.com/stnolting/neorv32.git
Issue Tracker
Last activity 15 days ago
v1.6.1 released 28 days ago
Primary language: VHDL
14 open issues
4 open pull requests
74 forks
37 watchers
581 stars
2564 commits by 14 contributors
Stephan umarcor Lars Asplund Henrik Brix Andersen zipotron
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,6,20,11,18,21,38,51,26,40,12,0,16,89,48,27,48,19,33,55,40,31,19,21,64,52,20,38,22,84,9,48,89,65,120,96,61,30,58,49,38,14,8,28,38,47,2,15,39,51,30,25,54,6,0,0

activity over the last year

LibreCores data updated 15 days ago