updated documentation

This commit is contained in:
stnolting 2020-07-09 16:53:28 +02:00
parent 54489ae6c0
commit 6125732b33
2 changed files with 83 additions and 74 deletions

157
README.md
View file

@ -1,4 +1,4 @@
# [The NEORV32 Processor](https://github.com/stnolting/neorv32)
# [The NEORV32 Processor](https://github.com/stnolting/neorv32) (RISC-V-compliant)
[![Build Status](https://travis-ci.com/stnolting/neorv32.svg?branch=master)](https://travis-ci.com/stnolting/neorv32)
[![license](https://img.shields.io/github/license/stnolting/neorv32)](https://github.com/stnolting/neorv32/blob/master/LICENSE)
@ -20,23 +20,24 @@
## Introduction
The NEORV32 is a customizable mikrocontroller-like processor system based on a RISC-V `rv32i` or `rv32e` CPU with optional
`M`, `C`, `Zicsr` and `Zifencei` extensions. The CPU was built from scratch and is compliant to the **Unprivileged
ISA Specification Version 2.1** and a subset of the **Privileged Architecture Specification Version 1.12**. The NEORV32 is intended
as auxiliary processor within a larger SoC designs or as stand-alone custom microcontroller.
The NEORV32 is a customizable full-scale mikrocontroller-like processor system based on a [RISC-V-compliant](https://github.com/stnolting/neorv32_riscv_compliance)
`rv32i` CPU with optional `E`, `C`, `M`, `Zicsr` and `Zifencei` extensions. The CPU was built from scratch and is compliant to the **Unprivileged
ISA Specification Version 2.1** and a subset of the **Privileged Architecture Specification Version 1.12-draft**.
The NEORV32 is intended as auxiliary processor within a larger SoC designs or as stand-alone custom microcontroller.
Its top entity can be directly synthesized for any FPGA without modifications and provides a full-scale RISC-V based microcontroller.
The processor provides common peripherals and interfaces like input and output ports, serial interfaces for UART, I²C and SPI,
interrupt controller, timers and embedded memories. External memories, peripherals and custom IP can be attached via a
Wishbone-based external memory interface. All optional features beyond the base CPU can be enabled and configured via VHDL generics.
This project comes with a complete software ecosystem that features core libraries for high-level usage of the
provided functions and peripherals, application makefiles and example programs. All software source files
provide a doxygen-based documentary. The deployed doxygen-based software documentation can be found on the
project's [Github pages](https://stnolting.github.io/neorv32/files.html).
provided functions and peripherals, application makefiles, a runtime environment and several example programs. All software source files
provide a doxygen-based [documentary](https://stnolting.github.io/neorv32/files.html).
The project is intended to work "out of the box". Just synthesize the test setup from this project, upload
it to your FPGA board of choice and start playing with the NEORV32. If you do not want to [compile the GCC toolchains](https://github.com/riscv/riscv-gnu-toolchain)
by yourself, you can also download [pre-compiled toolchain](https://github.com/stnolting/riscv_gcc_prebuilt) for Linux.
by yourself, you can also download [pre-compiled toolchains](https://github.com/stnolting/riscv_gcc_prebuilt) for Linux.
For more information take a look a the [![NEORV32 datasheet](https://raw.githubusercontent.com/stnolting/neorv32/master/docs/figures/PDF_32.png) NEORV32 datasheet](https://raw.githubusercontent.com/stnolting/neorv32/master/docs/NEORV32.pdf).
@ -57,16 +58,17 @@ all the [provided example programs](https://github.com/stnolting/neorv32/tree/ma
The processor passes the official `rv32i`, `rv32im`, `rv32imc`, `rv32Zicsr` and `rv32Zifencei` [RISC-V compliance tests](https://github.com/riscv/riscv-compliance).
| Project | Status | Misc |
|:--------------------------------------------------------------------------------|:-------|:---------|
| [NEORV32 processor](https://github.com/stnolting/neorv32) | [![Test](https://img.shields.io/travis/stnolting/neorv32/master.svg?label=HW-test)](https://travis-ci.com/stnolting/neorv32) | [![sw doc](https://img.shields.io/badge/SW%20documentation-gh--pages-blue)](https://stnolting.github.io/neorv32/files.html) |
| [Pre-build toolchain](https://github.com/stnolting/riscv_gcc_prebuilt) | [![Test](https://img.shields.io/travis/stnolting/riscv_gcc_prebuilt/master.svg?label=compliance)](https://travis-ci.com/stnolting/riscv_gcc_prebuilt) | |
| [RISC-V compliance test](https://github.com/stnolting/neorv32_riscv_compliance) | [![Test](https://img.shields.io/travis/stnolting/neorv32_riscv_compliance/master.svg?label=test)](https://travis-ci.com/stnolting/neorv32_riscv_compliance) | |
| Project component | CI status | Note |
|:--------------------------------------------------------------------------------|:----------|:---------|
| [NEORV32 processor](https://github.com/stnolting/neorv32) | [![Test](https://img.shields.io/travis/stnolting/neorv32/master.svg?label=test)](https://travis-ci.com/stnolting/neorv32) | [![sw doc](https://img.shields.io/badge/SW%20documentation-gh--pages-blue)](https://stnolting.github.io/neorv32/files.html) |
| [Pre-build toolchain](https://github.com/stnolting/riscv_gcc_prebuilt) | [![Test](https://img.shields.io/travis/stnolting/riscv_gcc_prebuilt/master.svg?label=test)](https://travis-ci.com/stnolting/riscv_gcc_prebuilt) | |
| [RISC-V compliance test](https://github.com/stnolting/neorv32_riscv_compliance) | [![Test](https://img.shields.io/travis/stnolting/neorv32_riscv_compliance/master.svg?label=compliance)](https://travis-ci.com/stnolting/neorv32_riscv_compliance) | |
### Limitations to be fixed
* No exception is triggered in `E`-mode when using registers above `x15` yet
* `misa` CSR is read-only; no dynamic enabling/disabling of implemented CPU extensions during runtime
### To-Do / Wish List
@ -83,14 +85,15 @@ The processor passes the official `rv32i`, `rv32im`, `rv32imc`, `rv32Zicsr` and
## Features
![neorv32 Overview](https://raw.githubusercontent.com/stnolting/neorv32/master/docs/figures/neorv32_overview.png)
### Processor Features
![neorv32 Overview](https://raw.githubusercontent.com/stnolting/neorv32/master/docs/figures/neorv32_processor.png)
- RISC-V-compliant `rv32i` or `rv32e` CPU with optional `C`, `E`, `M`, `Zicsr` and `rv32Zifencei` extensions
- GCC-based toolchain ([pre-compiled rv32i and rv32 etoolchains available](https://github.com/stnolting/riscv_gcc_prebuilt))
- Application compilation based on [GNU makefiles](https://github.com/stnolting/neorv32/blob/master/sw/example/blink_led/makefile)
- [Doxygen-based](https://github.com/stnolting/neorv32/blob/master/docs/doxygen_makefile_sw) documentation of the software framework: available [@Github pages](https://stnolting.github.io/neorv32/files.html)
- [Doxygen-based](https://github.com/stnolting/neorv32/blob/master/docs/doxygen_makefile_sw) documentation of the software framework: available on [GitHub pages](https://stnolting.github.io/neorv32/files.html)
- Detailed [datasheet](https://raw.githubusercontent.com/stnolting/neorv32/master/docs/NEORV32.pdf) (pdf)
- Completely described in behavioral, platform-independent VHDL no primitives, macros, etc.
- Fully synchronous design, no latches, no gated clocks
- Small hardware footprint and high operating frequency
@ -109,12 +112,23 @@ The processor passes the official `rv32i`, `rv32im`, `rv32imc`, `rv32Zicsr` and
- _Optional_ core-local interrupt controller with 8 channels (CLIC)
- _Optional_ dummy device (DEVNULL) (can be used for *fast* simulation console output)
### CPU Features
The CPU is compliant to the [official RISC-V specifications](https://raw.githubusercontent.com/stnolting/neorv32/master/docs/riscv-spec.pdf) including a subset of the
![neorv32 Overview](https://raw.githubusercontent.com/stnolting/neorv32/master/docs/figures/neorv32_cpu.png)
The CPU is [compliant](https://github.com/stnolting/neorv32_riscv_compliance) to the
[official RISC-V specifications](https://raw.githubusercontent.com/stnolting/neorv32/master/docs/riscv-spec.pdf) including a subset of the
[RISC-V privileged architecture specifications](https://raw.githubusercontent.com/stnolting/neorv32/master/docs/riscv-spec.pdf).
More information regarding the CPU including a detailed list of the instruction set and the available CSRs can be found in
the [![NEORV32 datasheet](https://raw.githubusercontent.com/stnolting/neorv32/master/docs/figures/PDF_32.png) NEORV32 datasheet](https://raw.githubusercontent.com/stnolting/neorv32/master/docs/NEORV32.pdf).
**General**:
* No hardware support of unaligned accesses - they will trigger and exception
* Two stages in-order pipeline (FETCH, EXECUTE); each stage uses a multi-cycle processing scheme
**RV32I base instruction set** (`I` extension):
* ALU instructions: `LUI` `AUIPC` `ADDI` `SLTI` `SLTIU` `XORI` `ORI` `ANDI` `SLLI` `SRLI` `SRAI` `ADD` `SUB` `SLL` `SLT` `SLTU` `XOR` `SRL` `SRA` `OR` `AND`
* Jump and branch instructions: `JAL` `JALR` `BEQ` `BNE` `BLT` `BGE` `BLTU` `BGEU`
@ -140,7 +154,7 @@ The CPU is compliant to the [official RISC-V specifications](https://raw.githubu
* CSR access instructions: `CSRRW` `CSRRS` `CSRRC` `CSRRWI` `CSRRSI` `CSRRCI`
* System instructions: `MRET` `WFI`
* Counter CSRs: `cycle` `cycleh` `time` `timeh` `instret` `instreth` `mcycle` `mcycleh` `minstret` `minstreth`
* Machine CSRs: `mstatus` `misa` `mie` `mtvec` `mscratch` `mepc` `mcause` `mtval` `mip` `mimpid` `mhartid`
* Machine CSRs: `mstatus` `misa`(read-only!) `mie` `mtvec` `mscratch` `mepc` `mcause` `mtval` `mip` `mimpid` `mhartid`
* Custom CSRs: `mfeatures` `mclock` `mispacebase` `mdspacebase` `mispacesize` `mdspacesize`
* Supported exceptions and interrupts:
* Misaligned instruction address
@ -152,21 +166,13 @@ The CPU is compliant to the [official RISC-V specifications](https://raw.githubu
* Store address misaligned
* Store access fault
* Environment call from M-mode (via `ecall` instruction)
* Machine software instrrupt `msi`
* Machine software interrupt `msi`
* Machine timer interrupt `mti` (via MTIME unit)
* Machine external interrupt `mei` (via CLIC unit)
**Privileged architecture / FENCE.I** (`Zifencei` extension):
* System instructions: `FENCE.I`
**General**:
* No hardware support of unaligned accesses - they will trigger and exception
* Two stages in-order pipeline (FETCH, EXECUTE); each stage uses a multi-cycle execution
More information including a detailed list of the available CSRs can be found in
the [![NEORV32 datasheet](https://raw.githubusercontent.com/stnolting/neorv32/master/docs/figures/PDF_32.png) NEORV32 datasheet](https://raw.githubusercontent.com/stnolting/neorv32/master/docs/NEORV32.pdf).
## FPGA Implementation Results
@ -175,10 +181,10 @@ a DE0-nano board. The design was synthesized using **Intel Quartus Prime Lite 19
information is derived from the Timing Analyzer / Slow 1200mV 0C Model. If not otherwise specified, the default configuration
of the processor's generics is assumed. No constraints were used.
Results generated for hardware version: `1.0.0.0`
### CPU
Results generated for hardware version: `1.0.0.0`
| CPU Configuration | LEs | FFs | Memory bits | DSPs | f_max |
|:--------------------|:----------:|:--------:|:-----------:|:------:|:-------:|
| `rv32i` | 1027 | 474 | 2048 | 0 (0%) | 111 MHz |
@ -189,6 +195,8 @@ Results generated for hardware version: `1.0.0.0`
### Processor-Internal Peripherals and Memories
Results generated for hardware version: `1.0.5.0`
| Module | Description | LEs | FFs | Memory bits | DSPs |
|:---------|:------------------------------------------------|:---:|:---:|:-----------:|:----:|
| BOOT ROM | Bootloader ROM (4kB) | 3 | 1 | 32 768 | 0 |
@ -196,7 +204,7 @@ Results generated for hardware version: `1.0.0.0`
| DMEM | Processor-internal data memory (8kB) | 12 | 2 | 65 536 | 0 |
| GPIO | General purpose input/output ports | 38 | 33 | 0 | 0 |
| IMEM | Processor-internal instruction memory (16kb) | 7 | 2 | 131 072 | 0 |
| MTIME | Machine system timer | 270 | 167 | 0 | 0 |
| MTIME | Machine system timer | 269 | 166 | 0 | 0 |
| PWM | Pulse-width modulation controller | 76 | 69 | 0 | 0 |
| SPI | Serial peripheral interface | 206 | 125 | 0 | 0 |
| TRNG | True random number generator | 104 | 93 | 0 | 0 |
@ -204,31 +212,29 @@ Results generated for hardware version: `1.0.0.0`
| UART | Universal asynchronous receiver/transmitter | 151 | 108 | 0 | 0 |
| WDT | Watchdog timer | 57 | 45 | 0 | 0 |
### CPU + Peripheral
The following table shows the implementation results for an _Intel Cyclone IV EP4CE22F17C6N_ FPGA.
The design was synthesized using Intel Quartus Prime Lite 19.1 (“balanced implementation”).
IMEM uses 16kB and DMEM uses 8kB memory space.
### Exemplary FPGA Setups
| CPU Configuration | LEs | REGs | DSPs | Memory Bits | f_max |
|:--------------------|:----------:|:---------:|:------:|:------------:|:-------:|
| `rv32imc` + `Zicsr` | 3724 (17%) | 1899 (9%) | 0 (0%) | 231424 (38%) | 103 MHz |
Exemplary implementation results for different FPGA platforms. The processor setup uses *all provided peripherals*,
all CPU extensions (`rv32imc` + `Zicsr` + `Zifencei`, no `E` extension), no external memory interface and only internal
instruction and data memories. IMEM uses 16kB and DMEM uses 8kB memory space. The setup top entity connects most of the
processor's [top entity](https://github.com/stnolting/neorv32/blob/master/rtl/core/neorv32_top.vhd) signals
to FPGA pins - except for the Wishbone bus and the external interrupt signals.
Results generated for hardware version: `1.0.1.1`
### Lattice iCE40 UltraPlus 5k
The following table shows the hardware utilization for a [iCE40 UP5K](http://www.latticesemi.com/en/Products/FPGAandCPLD/iCE40UltraPlus) FPGA.
The setup uses all provided peripherals, all CPU extensions (except for the `E` extension), no external memory interface and internal
instruction and data memories (each 64kB) based on SPRAM primitives. The FPGA-specific memory components can be found in the
[`rtl/fpga_specific`](https://github.com/stnolting/neorv32/blob/master/rtl/fpga_specific/lattice_ice40up) folder.
Place & route reports generated with **Lattice Radiant 2.1** using Lattice LSE. The clock frequency
is constrained and generated via the PLL from the internal HF oscillator running at 12 MHz.
| CPU Configuration | LUTs | REGs | DSPs | SPRAM | EBR | f |
|:--------------------|:----------:|:----------:|:------:|:--------:|:--------:|:---------:|
| `rv32imc` + `Zicsr` | 4985 (94%) | 1982 (38%) | 0 (0%) | 4 (100%) | 12 (40%) | 20.25 MHz |
| Vendor | FPGA | Board | Toolchain | Impl. strategy | LUT / LE | FF / REG | DSP | Memory Bits | BRAM / EBR | SPRAM | Frequency |
|:--------|:----------------------------------|:-----------------|:------------------------|:---------------|:-----------|:-----------|:-------|:-------------|:-----------|:---------|------------:|
| Intel | Cyclone IV `EP4CE22F17C6N` | Terasic DE0-Nano | Quartus Prime Lite 19.1 | balanced | 3841 (17%) | 1866 (8%) | 0 (0%) | 231424 (38%) | - | - | 103 MHz |
| Lattice | iCE40 UltraPlus `iCE40UP5K-SG48I` | Upduino v2.0 | Radiant 2.1 (LSE) | default | 5014 (95%) | 1952 (37%) | 0 (0%) | - | 12 (40%) | 4 (100%) | c 20.25 MHz |
| Xilinx | Artix-7 `XC7A35TICSG324-1L` | Arty A7-35T | Vivado 2019.2 | default | 2312 (11%) | 1924 (5%) | 0 (0%) | - | 8 (16%) | - | c 100 MHz |
**Notes**
* The Lattice iCE40 UltraPlus setup uses the FPGA's SPRAM memory primitives for the internal IMEM and DEMEM (each 64kb).
The FPGA-specific memory components can be found in the [`rtl/fpga_specific`](https://github.com/stnolting/neorv32/blob/master/rtl/fpga_specific/lattice_ice40up) folder.
* The clock frequencies marked with a "c" are constrained clocks. The remaining ones are `f_max` results from the place and route timing reports.
* The Upduino and the Arty board have on-board SPI flash memories for storing the FPGA configuration. These device can also be used by the default NEORV32
bootloader to store and automatically boot an application program after reset (both tested successfully).
## Performance
@ -245,7 +251,7 @@ Results generated for hardware version: `1.0.0.0`
Hardware: 32kB IMEM, 16kb DMEM, 100MHz clock
CoreMark: 2000 iterations, MEM_METHOD is MEM_STACK
CPU extensions: `rv32i` or `rv32im` or `rv32imc`
Used peripherals: MTIME for time measurement, UART for printing the results
Used peripherals: UART for printing the results
~~~
| __Configuration__ | __Optimization__ | __Executable Size__ | __CoreMark Score__ | __CoreMarks/MHz__ |
@ -260,7 +266,7 @@ Used peripherals: MTIME for time measurement, UART for printing the results
### Instruction Cycles
The NEORV32 CPU is based on two-stages pipelined architecutre. Each stage uses a multi-cycle processing scheme. Hence,
The NEORV32 CPU is based on a two-stages pipelined architecutre. Each stage uses a multi-cycle processing scheme. Hence,
each instruction requires several clock cycles to execute (2 cycles for ALU operations, ..., 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.
@ -411,20 +417,21 @@ has been compiled on a 64-bit x86 Ubuntu (Ubuntu on Windows). Download the toolc
[https://github.com/stnolting/riscv_gcc_prebuilt](https://github.com/stnolting/riscv_gcc_prebuilt)
### Dowload the NEORV32 Project and Create a Hardware Project
### Dowload the NEORV32 and Create a Hardware Project
Now its time to get the most recent version the NEORV32 Processor project from GitHub. Clone the NEORV32 repository using
`git` from the command line (suggested for easy project updates via `git pull`):
$ git clone https://github.com/stnolting/neorv32.git
Create a new HW project with your FPGA design tool of choice. Add all files from the [`rtl/core`](https://github.com/stnolting/neorv32/blob/master/rtl)
Create a new project with your FPGA design tool of choice. Add all the `*.vhd` files from the [`rtl/core`](https://github.com/stnolting/neorv32/blob/master/rtl)
folder to this project and add them to a **new library** called `neorv32`.
You can either instantiate the [processor's top entity](https://github.com/stnolting/neorv32#top-entity) in you own project, or you
can use a simple [test setup](https://github.com/stnolting/neorv32/blob/master/rtl/top_templates/neorv32_test_setup.vhd) as top entity. This test
setup instantiates the processor, implements most of the peripherals and the basic ISA. Only the UART, clock, reset and some GPIO output sginals are
propagated:
You can either instantiate the [processor's top entity](https://github.com/stnolting/neorv32#top-entity) in your own project or you
can use a simple [test setup](https://github.com/stnolting/neorv32/blob/master/rtl/top_templates/neorv32_test_setup.vhd) (from the project's
[`rtl/top_templates`](https://github.com/stnolting/neorv32/blob/master/rtl/top_templates) folder) as top entity.
This test setup instantiates the processor, implements most of the peripherals and the basic ISA. Only the UART, clock, reset and some GPIO output sginals are
propagated (basically, its a FPGA "hello world" example):
```vhdl
entity neorv32_test_setup is
@ -441,12 +448,10 @@ propagated:
end neorv32_test_setup;
```
This test setup is intended as quick and easy "hello world" test setup to get into the NEORV32.
### Compiling and Uploading One of the Example Projects
Make sure `GNU Make` and a native `GCC` compiler are installed. To test the installation of the RISC-V toolchain, navigate to an example project like
Make sure `GNU Make` and a native `GCC` compiler are installed. To test the installation of the RISC-V toolchain navigate to an example project like
`sw/example/blink_led` and run:
neorv32/sw/example/blink_led$ make check
@ -513,19 +518,17 @@ Please also check out the project's [code of conduct](https://github.com/stnolti
## Citation
## Legal
This is project is released under the BSD 3-Clause license. No copyright infringement intended.
Other implied or used projects might have different licensing - see their documentation to get more information.
#### Citation
If you are using the NEORV32 Processor in some kind of publication, please cite it as follows:
> S. Nolting, "The NEORV32 Processor", github.com/stnolting/neorv32
## Legal
This is a hobby project released under the BSD 3-Clause license. No copyright infringement intended.
Other implied/used projects might have different licensing - see their documentation to get more information.
#### BSD 3-Clause License
Copyright (c) 2020, Stephan Nolting. All rights reserved.
@ -564,20 +567,24 @@ as an infringement of the law becomes known to us, we will immediately remove th
link in question.
#### Propretary Notice
#### Proprietary Notice
"Windows" is a trademark of Microsoft Corporation.
"Artix" and "Vivado" are trademarks of Xilinx Inc.
"Cyclone", "Quartus Prime" and "Avalon Bus" are trademarks of Intel Corporation.
"Cyclone", "Quartus Prime", "Quartus Prime Lite" and "Avalon Bus" are trademarks of Intel Corporation.
"Artix" and "Vivado" are trademarks of Xilinx, Inc.
"iCE40", "UltraPlus" and "Lattice Radiant" are trademarks of Lattice Semiconductor Corporation.
"AXI4" and "AXI4-Lite" are trademarks of Arm Holdings plc.
#### Misc
## Acknowledgement
[RISC-V](https://riscv.org/) - Instruction Sets Want To Be Free :heart:
[![Continous Integration provided by Travis CI](https://travis-ci.com/images/logos/TravisCI-Full-Color.png)](https://travis-ci.com/stnolting/neorv32)
@ -588,5 +595,7 @@ Continous integration provided by [Travis CI](https://travis-ci.com/stnolting/ne
This project is not affiliated with or endorsed by the Open Source Initiative (https://www.oshwa.org / https://opensource.org).
\
\
Made with :coffee: in Hannover, Germany.

Binary file not shown.