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 one 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 the block size) every time a cache miss is detected. Each cached word from this block provides a single status bit that indicates if the according bus access was successful or caused a bus error. Hence, the whole cache block remains valid even if certain addresses inside caused a bus error. If the CPU accesses any of the faulty cache words, an instruction access error exception is raised.

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 Traps, Exceptions and Interrupts for all available CPU traps):

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 a "bark and bite" concept. The timeout counter first triggers an optional CPU interrupt ("bark") when reaching half of the programmed interval to inform the application of the imminent timeout. When the full timeout value is reached a system-wide hardware reset is generated ("bite"). The internal counter has to be reset explicitly by the application program every now and then to prevent a timeout.

Configuration

The watchdog is enabled by setting the control register’s `WDT_CTRL_EN_ bit. When this bit is cleared, the internal timeout counter is reset to zero and no interrupt and no system reset can be triggered.

The internal 32-bit timeout counter is clocked at 1/4096th of the processor’s main clock (f_WDT[Hz] = f_main[Hz] / 4096). Whenever this counter reaches the programmed timeout value (WDT_CTRL_TIMEOUT bits in the control register) a hardware reset is triggered. In order to inform the application of an imminent timeout, an optional CPU interrupt is triggered when the timeout counter reaches half of the programmed timeout value.

The watchdog is "fed" by writing 1 to the WDT_CTRL_RESET control register bit, which will reset the internal timeout counter back to zero.

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 is entirely ignored (see table below, "writable if locked"). Read accesses to the control register as well as watchdog resets (by setting the WDT_CTRL_RESET flag) are not affected.

The lock bit can only be set if the WDT is already enabled (WDT_CTRL_EN is set). The lock bit can only be cleared again by a system-wide hardware reset.

Cause of last Hardware Reset

The cause of the last system hardware 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.

Register Map

The MTIME module implements a memory-mapped MTIME machine system timer that is compatible to the RISC-V privileged specifications. The 64-bit system time is accessed via the memory-mapped TIME_LO and TIME_HI`registers. A 64-bit time compare register, which is accessible via the memory-mapped `TIMECMP_LO and TIMECMP_HI registers, can be 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 remains active (=pending) until TIME becomes less TIMECMP again (either by modifying TIME or TIMECMP).

Register Map

The UART is a standard serial interface mainly used to establish a communication channel between a host computer computer/user and an application running on the embedded processor.

The NEORV32 UARTs feature independent transmitter and receiver with a fixed frame configuration of 8 data bits, an optional parity bit (even or odd) and a fixed stop bit. The actual transmission rate - the Baudrate - is programmable via software. Optional FIFOs with custom sizes can be configured for the transmitter and receiver independently.

The UART features two memory-mapped registers CTRL and DATA, which are used for configuration, status check and data transfer.

Theory of Operation

UART0 is enabled by setting the UART_CTRL_EN bit in the UART0 control register CTRL. The Baud rate is configured via a 12-bit UART_CTRL_BAUDxx baud prescaler (baud_prsc) and a 3-bit UART_CTRL_PRSCx clock prescaler (clock_prescaler) that scales the processor’s primary clock (f_main).

Baud rate = (f_main[Hz] / clock_prescaler) / (baud_prsc + 1)

A new transmission is started by writing the data byte to be send to the lowest byte of the DATA register. The transfer is completed when the UART_CTRL_TX_BUSY control register flag returns to zero. A new received byte is available when the UART_DATA_AVAIL flag of the DATA register is set. A "frame error" in a received byte (invalid stop bit) is indicated via the UART_DATA_FERR flag in the DATA register. The flag is cleared by reading the DATA register.

RX and TX FIFOs

UART0 provides optional FIFO buffers for the transmitter and the receiver. The UART0_RX_FIFO generic defines the depth of the RX FIFO (for receiving data) while the UART0_TX_FIFO defines the depth of the TX FIFO (for sending data). Both generics have to be a power of two with a minimal allowed value of 1. This minimal value will implement simple "double-buffering" instead of full-featured FIFOs. Both FIFOs are cleared whenever UART0 is disabled (clearing UART_CTRL_EN in CTRL).

The state of both FIFO (empty, at lest half-full, full) is available via the UART_CTRL?X_EMPTY_, UART_CTRL?X_HALF_ and UART_CTRL*X_FULL_ flags in the CTRL register.

If the RX FIFO is already full and new data is received by the receiver unit, the UART_DATA_OVERR flag in the DATA register is set indicating an "overrun". This flag is cleared by reading the DATA register.