Verified case · OpenHW on ALINX · Episode 06

FreeRTOS minimal system: 1 kHz tick, five tasks, queue and mutex on CVE2

Episode 06 still leaves the CVE2 CPU core untouched. The RTL gains a standard CLINT (mtime / mtimecmp) and a 64-entry interrupt vector table, and FreeRTOS Kernel V11.1.0 runs as a five-task system at a 1 kHz tick: pulse, producer, consumer, monitor and heartbeat, plus idle. Queue delivery, mutex-protected counters, stack high-water marks and heap headroom are all checked from the serial console, with a PASS verdict at 8 seconds.

Verified on board · 2026-11-20 CVE2 / RV32IM 50 MHz · 1 kHz tick FreeRTOS V11.1.0 Episode 06 / 12

What this proves is that the scheduler really runs, not that the code compiles. At 8.000 s: tick=8000, queue 81 sent / 81 received, qerr=0, mutex-protected shared=expected=971, and all four measured task stacks report a high-water mark. Two independent downloads produce byte-identical SUMMARY and STACK lines.

BoardALINX PI-AR035-F1-1Engineering board, not yet in the board selector; link will be added when listed
SiliconAMD Artix-7 · XC7A35TDevice data and sister boards → ProjectOpenHW CVE2 / CV32E20Upstream repository and commit →
Tick
8,000 @ 8.000 s
Queue
81 sent / 81 recv · qerr 0
Mutex counter
971 / 971
Heap left
15,280 / 24,576 B
Smallest stack margin
pulse 177 / 256 words
Resources
LUT 4,332 / FF 3,815
BRAM
32 / 50 · 64.0%
Timing
WNS 1.563 / WHS 0.032 ns

1. Board result

After the JTAG download, the console prints from the boot banner through the 8-second verdict. Key lines from the raw log (the complete file is in the project files):

EP06 FreeRTOS minimal system on CVE2
configCPU_CLOCK_HZ=50000000 configTICK_RATE_HZ=1000
tasks created, starting scheduler
[mon] tick=0 heap=15280 idle=0 pulse=1 hb=0 q=1/1 sh=11/11
[pulse] n=20 tick=950
[mon] tick=1000 heap=15280 idle=2739634 pulse=21 hb=2 q=11/11 sh=131/131
[hb] n=4 tick=1501
[prod] sent=20 tick=1900
[cons] recv=20 tick=1902
...
[mon] tick=7000 heap=15280 idle=19102201 pulse=141 hb=14 q=71/71 sh=851/851
[hb] n=16 tick=7501
[prod] sent=80 tick=7900
[cons] recv=80 tick=7902
[pulse] n=160 tick=7950
[mon] tick=8000 heap=15280 idle=21820112 pulse=161 hb=16 q=81/81 sh=971/971
[mon] tick=8000 heap=15280 idle=21820112 pulse=161 hb=17 q=81/81 sh=971/971
EP06 SUMMARY tick=8000 heap_free=15280 idle=21820112 pulse=161 heartbeat=17 sent=81 recv=81 qerr=0 shared=971 expected=971
EP06 STACK pulse=177 producer=309 consumer=309 monitor=421 words
EP06 RESULT: PASS

A second download reproduces the SUMMARY and STACK lines character for character: tick=8000, heap_free=15280, idle=21820112, pulse=161, heartbeat=17, sent=recv=81, qerr=0, shared=expected=971. This is not a one-off pass; it is the same firmware, same board and the same counters, repeated.

2. System structure

CLINT64-bit mtime / mtimecmp
0x2000_0000–0x2000_FFFF
→
CVE2 / CV32E20RV32IM · M-mode · 50 MHz
64-entry table @ 0x100
→
FreeRTOS V11.1.0tasks / queue / list / heap_4
five tasks + idle
TaskPriorityPeriod / triggerStack wordsWork
pulse450 ms256Toggle LED0, shared counter +1
producer3100 ms384Queue a sequence number, shared counter +10
consumer2blocks on queue384Receive and check sequence continuity
monitor11000 ms512Print watermarks; at 8 s print summary and verdict
heartbeat1500 ms256Toggle LED1
idle0idle256Idle hook increments the spin counter

3. Scheduling and synchronisation checks

The verdict is not “there is output”; every counter has to reconcile:

CounterValue at 8.000 sVerdict
FreeRTOS tick8,0001 kHz timer interrupt is stable; tick tracks real time
Queue sent / received81 / 81100 ms period, first send at t=0, 81 sends in 8 s
Queue errors0No send failure, no sequence mismatch
Shared / expected971 / 971producer 81×10 + pulse 161 = 971; mutex lost no update
pulse / heartbeat161 / 1750 ms and 500 ms periodic tasks both keep their cadence
Idle spin count21,820,112When no task is runnable, idle really consumes the CPU
Heap left15,280 B9,296 B used of the 24 KiB heap (37.8%)

The key is that shared and expected advance together. producer and pulse both take g_shared_mtx before modifying the shared counter, and inside that critical section they execute g_shared++ and g_expected++. If the mutex failed, the critical section were preempted, or an update were lost, the two would diverge. They remain exactly equal after 8 seconds, so the mstatus.MIE save/restore path of the mutex works on this core.

4. Stack and heap watermarks

configCHECK_FOR_STACK_OVERFLOW=2 is enabled. uxTaskGetStackHighWaterMark returns the historical minimum free space in words (4 B). A larger number means more headroom:

TaskAllocated wordsPeak used wordsMin free wordsFree bytes
pulse25679177708 B
producer384753091,236 B
consumer384753091,236 B
monitor512914211,684 B

The smallest absolute margin is pulse (177 words / 708 B), although it only uses 79 words. monitor uses the most stack (91 words) because it has to assemble several log_printf varargs and multiple 32-bit counters; the 512-word allocation still leaves it 421 words. That sets the budget for the next episode: adding formatted output or floating point means raising monitor from 512 to 640 words, or splitting the print.

The ISR stack is a separate static 256-word (1 KiB) array in .bss. Its boundary with the 24 KiB heap is exactly at 0x63E0: the ISR stack grows down, the heap grows up from 0x63E0, and the two directions do not overlap. This layout was confirmed with nm after linking, not estimated.

5. Resources and timing

ItemEP05EP06Change
Slice LUTs4,2664,332+66
Slice Registers3,6873,815+128
Block RAM Tile32 / 5032 / 50unchanged (64.0%)
DSPs1111unchanged
Bonded IOB2525unchanged
WNS / WHS1.239 / 0.053 ns1.563 / 0.032 ns0 failing endpoints
bitstream2,192,137 B2,192,137 Bsame device, same layout footprint

The new CLINT is a 64-bit counter plus a 64-bit comparator, and the vector table is 64 4-byte instructions. The cost is only +66 LUT / +128 FF, with no extra BRAM. Timing is actually better than EP05 (WNS 1.563 ns); the added logic is not on the critical path, and this is normal place-and-route variation, not evidence that “FreeRTOS is faster than CoreMark”.

The bitstream is exactly the same size as EP05 (2,192,137 B) because both use the same XC7A35T and the same 64 KiB dual-RAM configuration; only the BRAM contents and a small amount of control logic differ, not the fixed bitstream overhead. SHA-256: 02cfb84a5b3cf95096e317c564b753978f64c27f3ef259584ae48399989c406a.

6. Pitfalls

7. Reproduction

  1. Prepare Vivado 2025.2, riscv-nuclei-elf-gcc 10.2, JTAG and a USB serial cable; serial is /dev/ttyUSB1, 115200 8N1.
  2. Build the firmware: cd sw && make clean && make; confirm firmware.hex (6,079 words).
  3. Synthesise and implement: vivado -mode batch -source build_ep06.tcl. The script runs synth_1, impl_1, phys_opt_design -hold_fix and route_design, then writes final timing/util/drc reports and the bitstream.
  4. Start capture first: python3 cap_serial.py 22 /tmp/ep06.bin &, then vivado -mode batch -source program_ep06.tcl.
  5. Wait about 8 seconds; the console should print EP06 RESULT: PASS. Split the log at the boot banner and compare it with metrics/ep06_metrics.json.
cd sw && make clean && make
cd ..
vivado -mode batch -source build_ep06.tcl
python3 cap_serial.py 22 /tmp/ep06.bin &   # start before programming
vivado -mode batch -source program_ep06.tcl
The BRAM init path in the build script is absolute: /media/alinx/nvme4t/fpga-love/pi_ar035_f1_1_cve2_ep06/sw/firmware.hex. On another machine or directory, update INIT_FILE in the RTL too, otherwise synthesis “succeeds” with an all-zero RAM.

8. Project files

The files below are taken directly from this verified project. FreeRTOS kernel sources are provided under the MIT licence; this page includes the port and project files, and the complete kernel should be taken from FreeRTOS upstream.

This episode verifies the FreeRTOS minimal kernel, 1 kHz tick, five-task preemptive scheduling, queue and mutex behaviour, and stack/heap watermarks on a single CVE2 core. Not verified: timers / event groups / stream buffers, SMP, FPU context, scheduling jitter with cache or DDR, long-duration soak, temperature/voltage corners, or scheduling-latency comparisons against other RISC-V cores.

9. Related links

Subscribe to fpga.love

Daily Briefing · Weekly Digest · Monthly Deep Dive