FreeRTOS for NEORV32

• Requirements
• How To Run
• Porting Details

This repository provides a full-featured port of FreeRTOS for the NEORV32 RISC-V Processor. It implements a simple demo derived from the FreeRTOS "blinky" demo applications that is extended with some processor-specific features.

Requirements

Tools and framework

• NEORV32 submodule
• FreeRTOS kernel-only submodule
• Prebuilt RISC-V GCC toolchain
• GHDL for simulating the processor, optional

Minimal processor configuration

• CPU architecture and ISA extensions: rv32i_zicsr_zifencei
• Memory
  • IMEM (instruction memory): 16kB
  • DMEM (data memory): 8kB
• Peripherals
  • RISC-V machine timer (MTIME)
  • general-purpose timer (GPTMR), optional
  • UART0 as interface console
  • general purpose IO controller (GPIO); high-active LED connected to bits 1:0, LED at pin 0 is used as "heart beat"

Tip

For more information regarding the processor configuration options see the NEORV32's online data sheet.

How To Run

1. Clone this repository recursively (to include the submodules):

$ git clone --recurse-submodules https://github.com/stnolting/neorv32-freertos.git

2. Install a RISC-V GCC toolchain that is able to emit code for a 32-bit architecture. Make sure that (at least) the required ISA extensions are supported. An exemplary prebuilt toolchain for x86 Linux can be download from:

github.com/stnolting/riscv-gcc-prebuilt

3. Navigate to the demo folder and compile the application:

neorv32-freertos/demo$ make clean_all exe

Tip

You can check the RISC-V GCC installation by running make check.

4. Upload the generated neorv32_exe.bin file via the NEORV32 bootloader:

<< NEORV32 Bootloader >>

BLDV: Jul 28 2023
HWV:  0x01090003
CLK:  0x05f5e100
MISA: 0x40901105
XISA: 0xc0000fbb
SOC:  0xfffff06f
IMEM: 0x00008000
DMEM: 0x00002000

Autoboot in 8s. Press any key to abort.
Aborted.

Available CMDs:
 h: Help
 r: Restart
 u: Upload
 s: Store to flash
 l: Load from flash
 x: Boot from flash (XIP)
 e: Execute
CMD:> u
Awaiting neorv32_exe.bin... OK
CMD:> e
Booting from 0x00000000...

<<< NEORV32 running FreeRTOS V10.4.4+ >>>

GPTMR IRQ Tick
GPTMR IRQ Tick
GPTMR IRQ Tick

Tip

Alternatively, you can also use the processor's on-chip debugger to upload the application via the generated main.elf file.

5. If you have GHDL installed you can also run the demo in simulation using the processor's default testbench / simulation mode:

neorv32-freertos/demo$ sh sim.sh

Porting Details

The processor-specific FreeRTOS parts are configured by two files:

• FreeRTOSConfig.h (customize according to your needs)
• freertos_risc_v_chip_specific_extensions.h (do not change!)

The NEORV32-specific parts are configured right inside the main.c file and the according makefile. The hardware abstraction layer (HAL) is provided by the NEORV32 software framework, which also provides the start-up code and linker script.

As the linker script is also responsible for configuring application- and setup-specific memory layout the actual configuration has to be overridden according to the application setup. For example the heap size is configured by configTOTAL_HEAP_SIZE in FreeRTOSConfig.h. This size also needs to be configured for the linker script, which is done inside the makefile:

override USER_FLAGS += "-Wl,--defsym,__neorv32_heap_size=3500"

Tip

More information regarding the NEORV32 software framework can be found in the online data sheet.

The NEORV32 supports all RISC-V exceptions and interrupts plus additional platform-specific interrupts. As FreeRTOS only supports the MTIME timer interrupt and the "environment call" exception two additional functions are provided to handle platform-specific exceptions and interrupts:

void freertos_risc_v_application_interrupt_handler(void);
void freertos_risc_v_application_exception_handler(void);

These functions are populated in the main.c file to showcase how to attach handlers for these traps.