The NEORV32 RISC-V Processor: Datasheet

Processor and CPU architecture designs are fascinating things: they are the magic frontier where software meets hardware. This project started as something like a journey into this magic realm to understand how things actually work down on this very low level and evolved over time to a capable system on chip.

But there is more: when I started to dive into the emerging RISC-V ecosystem I felt overwhelmed by the complexity. As a beginner it is hard to get an overview - especially when you want to setup a minimal platform to tinker with…​ Which core to use? How to get the right toolchain? What features do I need? How does booting work? How do I create an actual executable? How to get that into the hardware? How to customize things? Where to start???

This project aims to provide a simple to understand and easy to use yet powerful and flexible platform that targets FPGA and RISC-V beginners as well as advanced users.

As a matter of fact soft-core processors cannot compete with discrete (like FPGA hard-macro) processors in terms of performance, energy efficiency and size. But they do fill a niche in FPGA design space: for example, soft-core processors allow to implement the control flow part of certain applications (e.g. communication protocol handling) using software like plain C. This provides high flexibility as software can be easily changed, re-compiled and re-uploaded again.

Furthermore, the concept of flexibility applies to all aspects of a soft-core processor. The user can add exactly the features that are required by the application: additional memories, custom interfaces, specialized co-processors and even user-defined instructions.

Open-source is a great thing! While open-source has already become quite popular in software, hardware-focused projects still need to catch up. Admittedly, there has been quite a development, but mainly in terms of platforms and applications (so schematics, PCBs, etc.). Although processors and CPUs are the heart of almost every digital system, having a true open-source silicon is still a rarity. RISC-V aims to change that - and even it is just one approach, it helps paving the road for future development.

Furthermore, I highly appreciate the community aspect of RISC-V. The ISA and everything beyond is developed in direct contact with the community: this includes businesses and professionals but also hobbyist, amateurs and people that are just curious. Everyone can join discussions and contribute to RISC-V in their very own way.

Finally, I really like the RISC-V ISA itself. It aims to be a clean, orthogonal and "intuitive" ISA that resembles with the basic concepts of RISC: simple yet effective.

The NEORV32 is not based on another RISC-V core. It was build entirely from ground up (just following the official ISA specs). The project does not intend to replace certain RISC-V cores or just beat existing ones like VexRISC in terms of performance or SERV in terms of size. It was build having a different design goal in mind.

The project aims to provide another option in the RISC-V / soft-core design space with a different performance vs. size trade-off and a different focus: embrace concepts like documentation, platform-independence / portability, RISC-V compatibility, extensibility & customization and ease of use (see the Project Key Features below).

Furthermore, the NEORV32 pays special focus on execution safety using Full Virtualization. The CPU aims to provide fall-backs for everything that could go wrong. This includes malformed instruction words, privilege escalations and even memory accesses that are checked for address space holes and deterministic response times of memory-mapped devices. Precise exceptions allow a defined and fully-synchronized state of the CPU at every time an in every situation.

Most mainstream CPUs out there are pipelined architectures to increase throughput. In contrast, most CPUs used for teaching are single-cycle designs since they are probably the most easiest to understand. But what about the multi-cycle architectures?

In terms of energy, throughput, area and maximal clock frequency multi-cycle architectures are somewhere in between single-cycle and fully-pipelined designs: they provide higher throughput and clock speed when compared to their single-cycle counterparts while having less hardware complexity (= area) then a fully-pipelined designs. I decided to use the multi-cycle approach because of the following reasons:

To counteract the loss of performance implied by a pure multi-cycle architecture, the NEORV32 CPU uses a mixed approach: instruction fetch (front-end) and instruction execution (back-end) are de-coupled to operate independently of each other. Data is interchanged via a queue building a simple 2-stage pipeline. Each "pipeline" stage in terms is implemented as multi-cycle architecture to simplify the hardware and to provide precise state control (e.g. during exceptions).

The processor setup features the standard machine-level RISC-V interrupt lines for "machine timer interrupt", "machine software interrupt" and "machine external interrupt". Their usage is defined by the RISC-V privileged architecture specifications. However, bare-metal system can also repurpose these interrupts. See CPU section Traps, Exceptions and Interrupts for more information.

As part of the NEORV32-specific CPU extensions, the CPU core features 16 fast interrupt request signals (FIRQ0 - FIRQ15) with dedicated bits in the mip and mie CSRs and custom mcause trap codes. The FIRQ signals are reserved for processor-internal modules only (for example for the communication interfaces to signal "available incoming data" or "ready to send new data").

The mapping of the 16 FIRQ channels and the according processor-internal modules is shown in the following table (the channel number also corresponds to the according FIRQ priority: 0 = highest, 15 = lowest):

The processor provides an optional interrupt controller for up to 32 user-defined external interrupts (see section External Interrupt Controller (XIRQ)). These external IRQs are mapped to a single CPU fast interrupt request so a software handler is required to differentiate / prioritize these interrupts.

Each default region of the NEORV32 address space provides specific physical memory attributes that define the allowed access types to each of these regions. These "access permission" are enforced by the hardware and cannot be changed. If an access violates the PMA’s permissions an exception is raised. The access permissions can be further constrained using the CPU’s PMP Physical Memory Protection.

The following access types are checked by the hardware (if an access type is present in a region’s PMA the access is permitted):

The CPU can access all of the 32-bit address space from the instruction fetch interface (I) and also from the data access interface (D). These two CPU interfaces are multiplexed by a simple bus switch (rtl/core/neorv32_busswitch.vhd) into a single processor-internal bus. All processor-internal memories, peripherals and also the external memory interface are connected to this bus. Hence, both CPU interfaces (instruction fetch & data access) have access to the same (identical!) address space making the setup a modified von-Neumann architecture.

The general address space layout consists of two main configuration constants: ispace_base_c defining the base address of the instruction memory address space and dspace_base_c defining the base address of the data memory address space. Both constants are defined in the NEORV32 VHDL package file rtl/core/neorv32_package.vhd:

The default configuration assumes the instruction memory address space starting at address 0x00000000 and the data memory address space starting at 0x80000000. Both values can be modified for a specific setup and the address space may overlap or can be completely identical. Make sure that both base addresses are aligned to a 4-byte boundary.

The NEORV32 Processor was designed to provide maximum flexibility for the memory configuration. The processor can populate the instruction address space and/or the data address space with internal memories for instructions (IMEM) and data (DMEM). Processor external memories can be used as an alternative or even in combination with the internal ones. The figure below show some exemplary memory configurations.

Due to the flexible memory configuration concept, the NEORV32 Processor provides several different boot concepts. The figure below shows the exemplary concepts for the two most common boot scenarios.

There are two general boot scenarios: Indirect Boot (1a and 1b) and Direct Boot (2a and 2b) configured via the INT_BOOTLOADER_EN generic. If this generic is set true the indirect boot scenario is used. This is also the default boot configuration of the processor. If INT_BOOTLOADER_EN is set false the direct boot scenario is used.

Implementation of the processor-internal instruction memory is enabled via the processor’s MEM_INT_IMEM_EN generic. The size in bytes is defined via the MEM_INT_IMEM_SIZE generic. If the IMEM is implemented, the memory is mapped into the instruction memory space and located right at the beginning of the instruction memory space (default ispace_base_c = 0x00000000).

By default the IMEM is implemented as true RAM so the content can be modified during run time. This is required when using a bootloader that can update the content of the IMEM at any time. If you do not need the bootloader anymore - since your application development has completed and you want the program to permanently reside in the internal instruction memory - the IMEM is automatically implemented as pre-intialized ROM when the processor-internal bootloader is disabled (INT_BOOTLOADER_EN = false).

When the IMEM is implemented as ROM, it will be initialized during synthesis (actually, by the bitstream) with the actual application program image. The compiler toolchain will generate a VHDL initialization file rtl/core/neorv32_application_image.vhd, which is automatically inserted into the IMEM. If the IMEM is implemented as RAM (default), the memory will not be initialized at all.

Implementation of the processor-internal data memory is enabled via the processor’s MEM_INT_DMEM_EN generic. The size in bytes is defined via the MEM_INT_DMEM_SIZE generic. If the DMEM is implemented, the memory is mapped into the data memory space and located right at the beginning of the data memory space (default dspace_base_c = 0x80000000). The DMEM is always implemented as true RAM.

This HDL modules provides a read-only memory that contain the executable code image of the bootloader. If the INT_BOOTLOADER_EN generic is true this module will be implemented and the CPU boot address is modified to directly execute the code from the bootloader ROM after reset.

The bootloader ROM is located at address 0xFFFF0000 and can occupy a address space of up to 32kB. The base address as well as the maximum address space size are fixed and cannot (should not!) be modified as this might address collision with other processor modules.

The bootloader memory is read-only and is automatically initialized with the bootloader executable image rtl/core/neorv32_bootloader_image.vhd during synthesis. The actual physical size of the ROM is also determined via synthesis and expanded to the next power of two. For example, if the bootloader code requires 10kB of storage, a ROM with 16kB will be generated. The maximum size must not exceed 32kB.

The processor features an optional cache for instructions to improve performance when using memories with high access latencies. The cache is directly connected to the CPU’s instruction fetch interface and provides full-transparent buffering of instruction fetch accesses to the entire address space.

The cache is implemented if the ICACHE_EN generic is true. The size of the cache memory is defined via ICACHE_BLOCK_SIZE (the size of a single cache block/page/line in bytes; has to be a power of two and >= 4 bytes), ICACHE_NUM_BLOCKS (the total amount of cache blocks; has to be a power of two and >= 1) and the actual cache associativity ICACHE_ASSOCIATIVITY (number of sets; 1 = direct-mapped, 2 = 2-way set-associative, has to be a power of two and >= 1).

If the cache associativity (ICACHE_ASSOCIATIVITY) is greater than 1 the LRU replacement policy (least recently used) is used.

Bus Access Fault Handling

The cache always loads a complete cache block (ICACHE_BLOCK_SIZE bytes) aligned to it’s size every time a cache miss is detected. If any of the accessed addresses within a single block do not successfully acknowledge the transfer (i.e. issuing an error signal or timing out) the whole cache block is invalidated and any access to an address within this cache block will raise an instruction fetch bus error exception.

The external memory interface provides a Wishbone b4-compatible on-chip bus interface. The bus interface is implemented if the MEM_EXT_EN generic is true. This interface can be used to attach external memories, custom hardware accelerators, additional IO devices or all other kinds of IP blocks to the processor.

The external interface is not mapped to a specific address space region. Instead, all CPU memory accesses that do not target a processor-internal module are delegated to the external memory interface. In summary, a CPU load/store access is delegated via the external bus interface if…​

Wishbone Bus Protocol

The external memory interface either uses the standard (also called "classic") Wishbone protocol (default) or pipelined Wishbone protocol. The protocol to be used is configured via the MEM_EXT_PIPE_MODE generic:

Bus Access

The NEORV32 Wishbone gateway does not support burst transfer yet, so there is always just a single transfer in "in fly". Hence, the Wishbone STALL signal is not implemented. An accessed Wishbone device does not have to respond immediately to a bus request by sending an ACK. Instead, there is a time window where the device has to acknowledge the transfer. This time window id configured by the MEM_EXT_TIMEOUT top generic that defines the maximum time (in clock cycles) a bus access can be pending before it is automatically terminated with an error condition. If MEM_EXT_TIMEOUT is set to zero, the timeout disabled an a bus access can take an arbitrary number of cycles to complete (this is not recommended!).

When MEM_EXT_TIMEOUT is greater than zero, the Wishbone gateway starts an internal countdown whenever the CPU accesses an address via the external memory interface. If the accessed device does not acknowledge (via wb_ack_i) or terminate (via wb_err_i) the transfer within MEM_EXT_TIMEOUT clock cycles, the bus access is automatically canceled setting wb_cyc_o low again and a CPU load/store/instruction fetch bus access fault exception is raised.

Wishbone Tag

The 3-bit wishbone wb_tag_o signal provides additional information regarding the access type. This signal is compatible to the AXI4 AxPROT signal.

Endianness

The NEORV32 CPU and the Processor setup are little-endian architectures. To allow direct connection to a big-endian memory system the external bus interface provides an Endianness configuration. The Endianness of the external memory interface can be configured via the MEM_EXT_BIG_ENDIAN generic. By default, the external memory interface uses little-endian byte-order.

Application software can check the Endianness configuration of the external bus interface via the SYSINFO module (see section System Configuration Information Memory (SYSINFO) for more information).

Access Latency

By default, the Wishbone gateway introduces two additional latency cycles: processor-outgoing (*_o) and processor-incoming (*_i) signals are fully registered. Thus, any access from the CPU to a processor-external devices via Wishbone requires 2 additional clock cycles. This can ease timing closure when using large (combinatorial) Wishbone interconnection networks.

Optionally, the latency of the Wishbone gateway can be reduced by removing the input and output register stages. Enabling the MEM_EXT_ASYNC_RX option will remove the input register stage; enabling MEM_EXT_ASYNC_TX option will remove the output register stages. Each enabled option reduces access latency by 1 cycle.

AXI4-Lite Connectivity

The AXI4-Lite wrapper (rtl/system_integration/neorv32_SystemTop_axi4lite.vhd) provides a Wishbone-to- AXI4-Lite bridge, compatible with Xilinx Vivado (IP packager and block design editor). All entity signals of this wrapper are of type std_logic or std_logic_vector, respectively. See The USer Guide for more information: https://stnolting.github.io/neorv32/ug/#_packaging_the_processor_as_ip_block_for_xilinx_vivado_block_designer

Theory of Operation

The Bus Keeper is a fundamental component of the processor’s internal bus system that ensures correct bus operations to maintain execution safety. The Bus Keeper monitors every single bus transactions that is intimated by the CPU. If an accessed device responds with an error condition or do not respond within a specific access time window, the according bus access fault exception is raised. The following exceptions can be raised by the Bus Keeper (see section NEORV32 Trap Listing for all CPU exceptions):

The access time window, in which an accessed device has to respond, is defined by the max_proc_int_response_time_c constant from the processor’s VHDL package file (rtl/neorv32_package.vhd). The default value is 15 clock cycles.

In case of a bus access fault exception application software can evaluate the Bus Keeper’s control register NEORV32_BUSKEEPER.CTRL to retrieve further details of the bus exception. The BUSKEEPER_ERR_FLAG bit indicates that an actual bus access fault has occurred. The bit is sticky once set and is automatically cleared when reading or writing the NEORV32_BUSKEEPER.CTRL register. The BUSKEEPER_ERR_TYPE bit defines the type of the bus fault:

Register Map

Overview

The SLINK component provides up to 8 independent RX (receiving) and TX (sending) links for moving stream data. The interface provides higher bandwidth and less latency than the external memory bus interface, which makes it ideally suited to couple custom stream processing units.

Each link provides an individual internal FIFO for data buffering. The FIFO depth is globally defined for all TX links via the SLINK_TX_FIFO generic and for all RX links via the SLINK_RX_FIFO generic. The FIFO depth has to be at least 1, which will implement a simple input/output register. The maximum value is limited to 32768 entries. Note that the FIFO depth has to be a power of two.

The actual number of implemented RX/TX links is configured by the SLINK_NUM_RX and SLINK_NUM_TX generics, respectively. The SLINK module will be synthesized only if at least one of these generics is greater than zero. All unimplemented links are internally terminated and their according output signals are set to zero.

Theory of Operation

The SLINK provides eight data registers (DATA[i]) to access the links (read accesses will access the RX link FIFOs, write accesses will access the TX link FIFOs), one control register (CTRL), one interrupt configuration register (IRQ) and two status registers - one for the RX links (RX_STATUS) and one for the TX links (TX_STATUS).

The SLINK is globally activated by setting the control register’s enable bit SLINK_CTRL_EN. Clearing this bit will reset all internal logic and will also clear all FIFOs. The actual data links are accessed by reading or writing the according link data registers DATA[0] to DATA[7]. For example, writing to DATA[0] will put the according data into the FIFO of TX link 0. Accordingly, reading from DATA[0] will return one data word from the FIFO of RX link 0.

The current link status of each RX and TX channel is accessible via the *X_STATUS registers. The FIFO’s status signals that represent the fill level (empty, at least half full, full) are exposed as read-only flags via those two registers.

The TX link’s "end of packet" signal slink_tx_lst_o is controlled by the TX_STATUS register’s SLINK_TX_STATUS_LAST bits. Note that these bits are also buffered by the internal TX FIFOs, so setting one of these bits before writing data to DATA will set the slink_tx_lst_o signal when the written data word is actually send from the FIFO. Vice versa, the SLINK_RX_STATUS_LAST bits in RX_STATUS represent the level of the according slink_rx_lst_i input when a new data word was samples. These bits are also buffered in the internal RX FIFOs.

Data Transmission

To send (TX) data the program should ensure there is at least one left in the according link’s FIFO by checking SLINK_CTRL_TX_FREE. To mark the current data word to-be-send as "end of packet" the according SLINK_TX_STATUS_LAST bit has to be set before writing DATA.

Received data (RX) is available when the according link’s SLINK_RX_STATUS_EMPTY bit is cleared. To check if the received data is marked as "end of packet" the according SLINK_RX_STATUS_LAST bit has to be examined before reading DATA.

Interface & Protocol

The SLINK interface consists of four signals dat, val, rdy and lst for each RX and TX link. Each signal is constructed as an "array" with eight entries - one for each link. Note that an entry in slink_*x_dat is 32-bit wide while entries in slink_*x_val, slink_*x_rdy and slink_*x_lst are are just 1-bit wide.

SLINK Interrupts

The stream interface provides two independent CPU interrupt channels - one for RX conditions and one for TX conditions. These IRQs can be used to signal specific FIFO conditions (e.g. "data available") to the CPU. The specific interrupt conditions are programmed per-link via the IRQ register. A 2-bit-coded value is used to enable the according link’s interrupt and to specify the actual condition.

For the TX links (in IRQ SLINK_IRQ_TX) the following interrupt conditions are supported:

For the RX links (in IRQ SLINK_IRQ_RX) the following interrupt conditions are supported:

Once the SLINK’s RX or TX CPU interrupt has become pending, it has to be explicitly cleared again by writing zero to the according mip CSR bit(s).

Register Map

The general purpose parallel IO port unit provides a simple 64-bit parallel input port and a 64-bit parallel output port. These ports can be used chip-externally (for example to drive status LEDs, connect buttons, etc.) or chip-internally to provide control signals for other IP modules. The component is disabled for implementation when the IO_GPIO_EN generic is set false. In this case the GPIO output port gpio_o is tied to all-zero.

Register Map

Theory of Operation

The watchdog (WDT) provides a last resort for safety-critical applications. The WDT provides an internal 20-bit wide counter that needs to be reset every now and then by the user program. If the counter overflows, either a system reset or an interrupt is generated depending on the configured operation mode.

Access Password

Whenever the watchdog control register NEORV32_WDT.CTRL shall be written the upper-most (MSB-aligned) 16 bit of the write data have to contain the "watchdog access password". If the password is incorrect the write access is entirely ignored and the watchdog hardware module will not acknowledge the bus write access leading to a store access fault exception. Read accesses are not affected by the access password at all.

Timeout Configuration

The watchdog is enabled by setting the control register’s `WDT_CTRL_EN_ bit. The clock used to increment the internal counter is selected via the 3-bit WDT_CTRL_CLK_SELx prescaler:

The WDT_CTRL_HALF flag of the control register CTRL indicates that at least half of the maximum timeout value has already been reached. The watchdog is "fed" by setting the WDT_CTRL_RESET control register bit, which will reset the timeout counter.

Watchdog Action

Whenever the internal counter overflows the watchdog executes one of two possible actions: either a hard processor reset is triggered or an interrupt is requested via the CPU’s fast interrupt channel #0. The WDT_CTRL_MODE bit defines the action to be taken on an overflow: when cleared, the watchdog will assert an IRQ, when set the WDT will cause a system wide reset. The configured action can also be triggered manually at any time by setting the WDT_CTRL_FORCE bit.

The cause of the last system reset can be determined via the WDT_CTRL_RCAUSE flag. If this flag is zero, the processor has been reset via the external reset signal (or the on-chip debugger). If this flag is set the last system reset was caused by the watchdog itself.

Configuration Lock

The watchdog control register can be locked to protect the current configuration from being modified. The lock is activated by setting the WDT_CTRL_LOCK bit. In the locked state any write access to the control register’s configuration flags is ignored (see table below, "writable if locked"). Read accesses to the control register as well as watchdog resets (WDT_CTRL_RESET) and forced watchdog actions (WDT_CTRL_FORCE) are not affected.

The lock is removed by a system reset, which can be triggered via the external hardware reset signal, the on-chip debugger or the watchdog itself (if WDT_CTRL_MODE is set).

Register Map

The MTIME module implements the memory-mapped MTIME machine timer from the official RISC-V specifications. This module features a 64-bit system timer incrementing with the primary processor clock. Besides accessing the MTIME register via memory operation the current system time can also be obtained using the time[h] CSRs. Furthermore, the current system time is made available for processor-external usage via the top’s mtime_o signal.

The 64-bit system time can be accessed via the TIME_LO and TIME_HI memory-mapped registers (read/write) and also via the CPU’s time[h] CSRs (read-only). A 64-bit time compare register - accessible via the memory-mapped TIMECMP_LO and TIMECMP_HI registers - is used to configure the CPU’s MTI (machine timer interrupt). The interrupt is triggered whenever TIME (high & low part) is greater than or equal to TIMECMP (high & low part). The interrupt remain active (=pending) until TIME becomes less TIMECMP again (either by modifying TIME or TIMECMP).

Register Map