Subversion Repositories neorv32

## Introduction

## Introduction

download [pre-compiled toolchains](https://github.com/stnolting/riscv_gcc_prebuilt) for Linux.

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

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

This project is hosted on [GitHub](https://github.com/stnolting/neorv32) and [opencores.org](https://opencores.org/projects/neorv32).

This project is hosted on [GitHub](https://github.com/stnolting/neorv32) and [opencores.org](https://opencores.org/projects/neorv32).

- Detailed [datasheet](https://raw.githubusercontent.com/stnolting/neorv32/master/docs/NEORV32.pdf) (pdf)

- Detailed [datasheet](https://raw.githubusercontent.com/stnolting/neorv32/master/docs/NEORV32.pdf) (pdf)

- Completely described in behavioral, platform-independent VHDL – no primitives, macros, etc.

- Completely described in behavioral, platform-independent VHDL – no primitives, macros, etc.

- Fully synchronous design, no latches, no gated clocks

- Fully synchronous design, no latches, no gated clocks

- Small hardware footprint and high operating frequency

- Small hardware footprint and high operating frequency

- Highly configurable CPU and processor setup

- Highly configurable CPU and processor setup

### Design Principles

### Design Principles

 * From zero to main(): Completely open source and documented.

 * From zero to main(): Completely open source and documented.

 * Plain VHDL without technology-specific parts like attributes, macros or primitives.

 * Plain VHDL without technology-specific parts like attributes, macros or primitives.

 * The processor has to fit in a Lattice iCE40 UltraPlus 5k FPGA running at 20+ MHz.

 * The processor has to fit in a Lattice iCE40 UltraPlus 5k FPGA running at 20+ MHz.

### Status

### Status

all the [provided example programs](https://github.com/stnolting/neorv32/tree/master/sw/example) including the CoreMark benchmark.

all the [provided example programs](https://github.com/stnolting/neorv32/tree/master/sw/example) including the CoreMark benchmark.

The processor passes the official `rv32i`, `rv32im`, `rv32imc`, `rv32Zicsr` and `rv32Zifencei` [RISC-V compliance tests](https://github.com/riscv/riscv-compliance).

The processor passes the official `rv32i`, `rv32im`, `rv32imc`, `rv32Zicsr` and `rv32Zifencei` [RISC-V compliance tests](https://github.com/riscv/riscv-compliance).

| Project component                                                               | CI status | Note     |

| Project component                                                               | CI status | Note     |

* `mcause` CSR is read-only

* `mcause` CSR is read-only

* The `[m]cycleh` and `[m]instreth` CSR counters are only 20-bit wide (in contrast to original 32-bit)

* The `[m]cycleh` and `[m]instreth` CSR counters are only 20-bit wide (in contrast to original 32-bit)

* The physical memory protection (**PMP**) only supports `NAPOT` mode, a minimal granularity of 8 bytes and only up to 8 regions

* The physical memory protection (**PMP**) only supports `NAPOT` mode, a minimal granularity of 8 bytes and only up to 8 regions

* Four *fast interrupt* request channels with according control/status bits in `mie` and `mip` and custom exception codes in `mcause`

* Four *fast interrupt* request channels with according control/status bits in `mie` and `mip` and custom exception codes in `mcause`

### To-Do / Wish List

### To-Do / Wish List

- Add AXI(-Lite) bridges

- Add AXI(-Lite) bridges

## Features

## Features

### Processor Features

### Processor Features

**Privileged architecture / CSR access** (`Zicsr` extension):

**Privileged architecture / CSR access** (`Zicsr` extension):

  * Privilege levels: `M-mode` (Machine mode)

  * Privilege levels: `M-mode` (Machine mode)

  * CSR access instructions: `CSRRW` `CSRRS` `CSRRC` `CSRRWI` `CSRRSI` `CSRRCI`

  * CSR access instructions: `CSRRW` `CSRRS` `CSRRC` `CSRRWI` `CSRRSI` `CSRRCI`

  * System instructions: `MRET` `WFI`

  * System instructions: `MRET` `WFI`

  * Counter CSRs: `[m]cycle[h]` `[m]instret[h]` `time[h]`

  * Counter CSRs: `[m]cycle[h]` `[m]instret[h]` `time[h]`

  * Supported exceptions and interrupts:

  * Supported exceptions and interrupts:

    * Misaligned instruction address

    * Misaligned instruction address

    * Instruction access fault

    * Instruction access fault

    * Illegal instruction

    * Illegal instruction

    * Breakpoint (via `ebreak` instruction)

    * Breakpoint (via `ebreak` instruction)

Exemplary implementation results for different FPGA platforms. The processor setup uses *all provided peripherals*,

Exemplary implementation results for different FPGA platforms. The processor setup uses *all provided peripherals*,

no external memory interface, no PMP and only internal instruction and data memories. IMEM uses 16kB and DMEM uses 8kB memory space. The setup's top entity connects most of the

no external memory interface, no PMP and only internal instruction and data memories. IMEM uses 16kB and DMEM uses 8kB memory space. The setup's top entity connects most of the

processor's [top entity](https://github.com/stnolting/neorv32/blob/master/rtl/core/neorv32_top.vhd) signals

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 interrupt signals.

to FPGA pins - except for the Wishbone bus and the interrupt signals.

**Notes**

**Notes**

* The Lattice iCE40 UltraPlus setup uses the FPGA's SPRAM memory primitives for the internal IMEM and DMEM (each 64kb).

* The Lattice iCE40 UltraPlus setup uses the FPGA's SPRAM memory primitives for the internal IMEM and DMEM (each 64kb).

The FPGA-specific memory components can be found in [`rtl/fpga_specific`](https://github.com/stnolting/neorv32/blob/master/rtl/fpga_specific/lattice_ice40up).

The FPGA-specific memory components can be found in [`rtl/fpga_specific`](https://github.com/stnolting/neorv32/blob/master/rtl/fpga_specific/lattice_ice40up).

* 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 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

* 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).

bootloader to store and automatically boot an application program after reset (both tested successfully).

## Performance

## Performance

### CoreMark Benchmark

### CoreMark Benchmark

The [CoreMark CPU benchmark](https://www.eembc.org/coremark) was executed on the NEORV32 and is available in the

The [CoreMark CPU benchmark](https://www.eembc.org/coremark) was executed on the NEORV32 and is available in the

[sw/example/coremark](https://github.com/stnolting/neorv32/blob/master/sw/example/coremark) project folder. This benchmark

[sw/example/coremark](https://github.com/stnolting/neorv32/blob/master/sw/example/coremark) project folder. This benchmark

tests the capabilities of a CPU itself rather than the functions provided by the whole system / SoC.

tests the capabilities of a CPU itself rather than the functions provided by the whole system / SoC.

~~~

~~~

**Configuration**

**Configuration**

Hardware:    32kB IMEM, 16kB DMEM, 100MHz clock

Hardware:    32kB IMEM, 16kB DMEM, 100MHz clock

CoreMark:    2000 iterations, MEM_METHOD is MEM_STACK

CoreMark:    2000 iterations, MEM_METHOD is MEM_STACK

Compiler:    RISCV32-GCC 10.1.0

Compiler:    RISCV32-GCC 10.1.0

Peripherals: UART for printing the results

Peripherals: UART for printing the results

~~~

~~~

| CPU                  | Executable Size | Optimization | CoreMark Score | CoreMarks/MHz |

| CPU                  | Executable Size | Optimization | CoreMark Score | CoreMarks/MHz |

| `rv32i`              |    26 748 bytes |        `-O3` |          28.98 |        0.2898 |

| `rv32i`              |    26 748 bytes |        `-O3` |          28.98 |        0.2898 |

| `rv32im`             |    25 580 bytes |        `-O3` |          60.60 |        0.6060 |

| `rv32im`             |    25 580 bytes |        `-O3` |          60.60 |        0.6060 |

| `rv32imc`            |    19 636 bytes |        `-O3` |          62.50 |        0.6250 |

| `rv32imc`            |    19 636 bytes |        `-O3` |          62.50 |        0.6250 |

The _FAST_MUL_ configuration uses DSPs for the multiplier of the `M` extension (enabled via the `FAST_MUL_EN` generic).

The _FAST_MUL_ configuration uses DSPs for the multiplier of the `M` extension (enabled via the `FAST_MUL_EN` generic).

### Instruction Cycles

### Instruction Cycles

The NEORV32 CPU is based on a 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).

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

The average CPI (cycles per instruction) depends on the instruction mix of a specific applications and also on the available

The following table shows the performance results for successfully running 2000 CoreMark

The following table shows the performance results for successfully running 2000 CoreMark

iterations, which reflects a pretty good "real-life" work load. The average CPI is computed by

iterations, which reflects a pretty good "real-life" work load. The average CPI is computed by

dividing the total number of required clock cycles (only the timed core to avoid distortion due to IO wait cycles; sampled via the `cycle[h]` CSRs)

dividing the total number of required clock cycles (only the timed core to avoid distortion due to IO wait cycles; sampled via the `cycle[h]` CSRs)

by the number of executed instructions (`instret[h]` CSRs). The executables were generated using optimization `-O3`.

by the number of executed instructions (`instret[h]` CSRs). The executables were generated using optimization `-O3`.

| CPU                  | Required Clock Cycles | Executed Instructions | Average CPI |

| CPU                  | Required Clock Cycles | Executed Instructions | Average CPI |

| `rv32i`              |         6 955 817 507 |         1 468 927 290 |        4.73 |

| `rv32i`              |         6 955 817 507 |         1 468 927 290 |        4.73 |

| `rv32im`             |         3 376 961 507 |           601 565 750 |        5.61 |

| `rv32im`             |         3 376 961 507 |           601 565 750 |        5.61 |

| `rv32imc`            |         3 274 832 513 |           601 565 964 |        5.44 |

| `rv32imc`            |         3 274 832 513 |           601 565 964 |        5.44 |

The _FAST_MUL_ configuration uses DSPs for the multiplier of the `M` extension (enabled via the `FAST_MUL_EN` generic).

The _FAST_MUL_ configuration uses DSPs for the multiplier of the `M` extension (enabled via the `FAST_MUL_EN` generic).

## Top Entities

## Top Entities

The top entity of the **processor** is [**neorv32_top.vhd**](https://github.com/stnolting/neorv32/blob/master/rtl/core/neorv32_top.vhd) (from the `rtl/core` folder).

The top entity of the **processor** is [**neorv32_top.vhd**](https://github.com/stnolting/neorv32/blob/master/rtl/core/neorv32_top.vhd) (from the `rtl/core` folder).

Just instantiate this file in your project and you are ready to go! All signals of this top entity are of type *std_ulogic* or *std_ulogic_vector*, respectively

Just instantiate this file in your project and you are ready to go! All signals of this top entity are of type *std_ulogic* or *std_ulogic_vector*, respectively

(except for the TWI signals, which are of type *std_logic*).

(except for the TWI signals, which are of type *std_logic*).

Use the generics to configure the processor/CPU according to your needs. Each generic is initilized with the default configuration.

Use the generics to configure the processor/CPU according to your needs. Each generic is initilized with the default configuration.

Detailed information regarding the signals and configuration generics can be found in the [NEORV32 documentary](https://raw.githubusercontent.com/stnolting/neorv32/master/docs/NEORV32.pdf).

Detailed information regarding the signals and configuration generics can be found in the [NEORV32 documentary](https://raw.githubusercontent.com/stnolting/neorv32/master/docs/NEORV32.pdf).

Alternative top entities can be found in [`rtl/top_templates`](https://github.com/stnolting/neorv32/blob/master/rtl/top_templates) folder.

Alternative top entities can be found in [`rtl/top_templates`](https://github.com/stnolting/neorv32/blob/master/rtl/top_templates) folder.

### Processor

### Processor

```vhdl

```vhdl

entity neorv32_top is

entity neorv32_top is

  generic (

  generic (

    wb_err_i   : in  std_ulogic := '0'; -- transfer error

    wb_err_i   : in  std_ulogic := '0'; -- transfer error

    -- Advanced memory control signals (available if MEM_EXT_USE = true) --

    -- Advanced memory control signals (available if MEM_EXT_USE = true) --

    fence_o    : out std_ulogic; -- indicates an executed FENCE operation

    fence_o    : out std_ulogic; -- indicates an executed FENCE operation

    fencei_o   : out std_ulogic; -- indicates an executed FENCEI operation

    fencei_o   : out std_ulogic; -- indicates an executed FENCEI operation

    -- GPIO (available if IO_GPIO_USE = true) --

    -- GPIO (available if IO_GPIO_USE = true) --

    -- UART (available if IO_UART_USE = true) --

    -- UART (available if IO_UART_USE = true) --

    uart_txd_o : out std_ulogic; -- UART send data

    uart_txd_o : out std_ulogic; -- UART send data

    uart_rxd_i : in  std_ulogic := '0'; -- UART receive data

    uart_rxd_i : in  std_ulogic := '0'; -- UART receive data

    -- SPI (available if IO_SPI_USE = true) --

    -- SPI (available if IO_SPI_USE = true) --

    spi_sck_o  : out std_ulogic; -- SPI serial clock

    spi_sck_o  : out std_ulogic; -- SPI serial clock

    mext_irq_i : in  std_ulogic := '0'  -- machine external interrupt

    mext_irq_i : in  std_ulogic := '0'  -- machine external interrupt

  );

  );

end neorv32_top;

end neorv32_top;

```

```

### CPU

### CPU

```vhdl

```vhdl

entity neorv32_cpu is

entity neorv32_cpu is

  generic (

  generic (

were compiled on a 64-bit x86 Ubuntu 20.04 LTS (Ubuntu on Windows, actually). Download the toolchain of choice:

were compiled on a 64-bit x86 Ubuntu 20.04 LTS (Ubuntu on Windows, actually). Download the toolchain of choice:

[https://github.com/stnolting/riscv_gcc_prebuilt](https://github.com/stnolting/riscv_gcc_prebuilt)

[https://github.com/stnolting/riscv_gcc_prebuilt](https://github.com/stnolting/riscv_gcc_prebuilt)

Get the sources of the NEORV32 Processor project. You can either download a [release](https://github.com/stnolting/neorv32/releases)

Get the sources of the NEORV32 Processor project. You can either download a [release](https://github.com/stnolting/neorv32/releases)

or get the most recent version of this project as [`*.zip` file](https://github.com/stnolting/neorv32/archive/master.zip) or using `git clone` (suggested for easy project updates via `git pull`):

or get the most recent version of this project as [`*.zip` file](https://github.com/stnolting/neorv32/archive/master.zip) or using `git clone` (suggested for easy project updates via `git pull`):

    $ git clone https://github.com/stnolting/neorv32.git

    $ git clone https://github.com/stnolting/neorv32.git

Create a new project with your FPGA design tool of choice and add all the `*.vhd` files from the [`rtl/core`](https://github.com/stnolting/neorv32/blob/master/rtl)

Create a new project with your FPGA design tool of choice and add all the `*.vhd` files from the [`rtl/core`](https://github.com/stnolting/neorv32/blob/master/rtl)

folder to this project. Make sure to add them to a **new library** called `neorv32`.

folder to this project. Make sure to 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 your own project or you

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

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.

[`rtl/top_templates`](https://github.com/stnolting/neorv32/blob/master/rtl/top_templates) folder) as top entity.

This test setup instantiates the processor and implements most of the peripherals and some ISA extensions. Only the UART, clock, reset and some GPIO output sginals are

This test setup instantiates the processor and implements most of the peripherals and some ISA extensions. Only the UART, clock, reset and some GPIO output sginals are

propagated (basically, its a FPGA "hello world" example):

propagated (basically, its a FPGA "hello world" example):

## Contribute

## Contribute

I'm always thankful for help! So if you have any questions, bug reports, ideas or if you want to give some kind of feedback, feel free

I'm always thankful for help! So if you have any questions, bug reports, ideas or if you want to give some kind of feedback, feel free

Please also check out the project's [code of conduct](https://github.com/stnolting/neorv32/tree/master/CODE_OF_CONDUCT.md).

Please also check out the project's [code of conduct](https://github.com/stnolting/neorv32/tree/master/CODE_OF_CONDUCT.md).

## Legal

## Legal

"iCE40", "UltraPlus" and "Lattice Radiant" are trademarks of Lattice Semiconductor Corporation.

"iCE40", "UltraPlus" and "Lattice Radiant" are trademarks of Lattice Semiconductor Corporation.

"AXI" and "AXI-Lite" are trademarks of Arm Holdings plc.

"AXI" and "AXI-Lite" are trademarks of Arm Holdings plc.

## Acknowledgements

## Acknowledgements

[![RISC-V](https://raw.githubusercontent.com/stnolting/neorv32/master/docs/figures/riscv_logo.png)](https://riscv.org/)

[![RISC-V](https://raw.githubusercontent.com/stnolting/neorv32/master/docs/figures/riscv_logo.png)](https://riscv.org/)

[RISC-V](https://riscv.org/) - Instruction Sets Want To Be Free :heart:

[RISC-V](https://riscv.org/) - Instruction Sets Want To Be Free :heart: