NEORV32 Documentation

The NEORV32 is an open-source, highly configurable RISC-V compatible processor system. It is designed to function either as an auxiliary processor within a larger SoC or as a standalone microcontroller.

Key Components:

• CPU Core: A 32-bit RISC-V CPU with support for base ISA, privileged ISA, and various optional extensions (e.g., M, F, Zicsr, Zicntr).
• SoC (Processor System): A microcontroller-like system including optional peripherals such as UART, SPI, TWI, PWM, GPIO, timers, DMA, and embedded memories.
• Software Framework: A C-based framework including a bootloader, HAL (Hardware Abstraction Layer), runtime environment, and example programs. It supports GCC, FreeRTOS, Zephyr, and MicroPython.
• On-Chip Debugger: An OpenOCD/GDB compatible debugger accessible via JTAG.

The NEORV32 software ecosystem is a complete C-language RISC-V GCC-based framework. It includes a compiler toolchain, core hardware abstraction layer (HAL) libraries, a runtime environment, and a bootloader.

Key components:

• Core Libraries (HAL): Located in sw/lib, these allow easy integration of processor features. They are automatically included by adding #include <neorv32.h> to your code.
• Example Programs: Annotated examples illustrating peripheral and IO usage are available in sw/example.
• API Documentation: Doxygen-generated documentation is available online at https://stnolting.github.io/neorv32/sw/files.html.

All figures in the NEORV32 documentation are the original work of the project and are subject to the project's license, unless otherwise stated.

Specific third-party assets used include:

• RISC-V logo: Sourced from https://riscv.org/risc-v-logo under the RISC-V branding guidelines.
• neorv32_logo_smcard.jpg: Background image sourced from Pixabay under the Pixabay license.

The General Purpose Timer (GPTMR) module provides up to 16 individual 32-bit timer slices. Each slice consists of a counter register (SLICE[i].CNT) and a threshold register (SLICE[i].THR).

Key Capabilities:

• Configurable Slices: The number of slices is determined by the hardware generic IO_GPTMR_NUM (0..16).
• Operation Modes: Each slice can operate in single-shot mode (stops at threshold) or continuous/interval mode (resets to zero after matching threshold).
• Global Prescaler: A single global clock prescaler (CSR1.PRSC) affects the increment frequency for all slices.
• Interrupts: A CPU interrupt is generated on the fast IRQ channel 12 when a slice's counter matches its threshold, provided the slice is enabled.

Hardware and Software Files:

• Hardware: neorv32_gptmr.vhd
• Software Driver: neorv32_gptmr.c and neorv32_gptmr.h

The Stream Link Interface (SLINK) provides independent RX and TX channels for high-bandwidth, low-latency streaming data. It is compatible with the AXI4-Stream standard and is ideal for coupling custom stream processors or streaming peripherals to the NEORV32 SoC.

Key Features:

• Independent RX and TX channels.
• Configurable internal data FIFOs (via IO_SLINK_RX_FIFO and IO_SLINK_TX_FIFO generics).
• Supports "last" (end-of-stream) and "source/destination" routing signals.
• Interrupt-based signaling based on FIFO status.
• AXI4-Stream compatibility (using dat, val, lst, rdy signals, with src/dst replacing AXI-specific routing names).

NEORV32 uses Control and Status Registers (CSRs) to manage CPU state, configuration, and status.

Key Access Rules:

• Privilege Modes: Access is restricted by mode: M (Machine), U (User), or D (Debug).
• Read/Write Capabilities: RW (Read-Write), RO (Read-Only).
• Unimplemented/Disabled CSRs: Any CSR or bit not listed, or disabled due to missing ISA extensions, is hardwired to zero. Accessing them raises an illegal instruction exception.
• WARL Behavior: All writable CSRs follow 'Write All, Read Legal' behavior. You should always read back a CSR after writing to verify that the targeted bits were actually modified.

The NEORV32 bootloader is an optional built-in firmware that allows uploading new application firmware without re-synthesizing the FPGA bitstream. It is automatically executed after reset if enabled via the BOOT_MODE_SELECT generic.

Key Features:

• Interactive user console via UART.
• Uploading executables via UART.
• Loading/storing executables from SPI flash, TWI flash, or SD cards.
• Automatic boot sequence from flash or SD card.

Minimal Hardware Requirements:

• ISA: rv32e_zicsr_zifencei configuration.
• RAM (DMEM): At least 256 bytes.
• Recommended Controllers: UART0, CLINT, and GPIO.

The Custom Functions Unit (CFU) is a NEORV32-specific ISA extension (Xcfu) that provides a generic hardware module for implementing custom RISC-V instructions.

When to use CFU vs. other customization options:

• Use CFU for: Custom instructions that are tightly coupled with the CPU (e.g., specialized arithmetic or bit manipulation).
• Do NOT use CFU for: Complex, CPU-independent accelerators (like full AES encryption blocks). These should be implemented as stream- or memory-mapped co-processors (e.g., CFS) to allow them to operate independently of the CPU.

The Custom Functions Subsystem (CFS) is a memory-mapped, processor-internal module template designed to simplify the implementation of hardware accelerators. It allows developers to focus on design logic rather than communication overhead.

• Mechanism: The CPU communicates with the CFS via load/store operations (memory-mapped).
• Data Access: The CFS does not have direct access to memory; all data and control instructions must be sent by the CPU.
• Use Cases: Medium-scale accelerators like DSP modules (e.g., CORDIC), cryptography accelerators, or custom interfaces (e.g., IIS).

The NEORV32 CPU is a 32-bit little-endian pipelined/multi-cycle modified-Harvard architecture RISC-V core. It is highly configurable via generics, allowing for single-core or SMP dual-core setups. You can customize the instruction set by enabling various RISC-V ISA extensions.

Supported extensions include:

• Standard: I, E, M, A, C, B, U, X
• Specialized/Custom: Sdext, Sdtrig, Smcntrpmf, Smpmp, Zaamo, Zalrsc, Zba, Zbb, Zbc, Zbkb, Zbkc, Zbkx, Zbs, Zcb, Zcmop, Zfinx, Zibi, Zicntr, Zicond, Zicsr, Zifencei, Zihpm, Zimop, Zmmul, Zkn, Zknd, Zkne, Zknh, Zkt, Zks, Zksed, Zksh, Xcfu (Custom Functions Unit).

The core supports machine and optional user privilege modes and implements all RISC-V machine-level exceptions/interrupts, plus a NEORV32-specific extension of 16 fast interrupt request channels.