Bramble RP2040/RP2350 Emulator

A from-scratch emulator for Raspberry Pi RP2040 and RP2350 microcontrollers, supporting both ARM Cortex-M0+ (Thumb) and RISC-V Hazard3 (RV32IMAC) cores. Loads and executes UF2 and ELF firmware with accurate memory mapping and peripheral emulation.

Current Status: v0.42.0

300 tests passing (zero warnings). RP2040: Complete — boots MicroPython, CircuitPython, littleOS. RP2350 RISC-V: Complete Hazard3 emulation with picobin boot — MicroPython Pico 2 RISC-V loads and begins execution (416 instructions through boot code). RP2350 ARM: Complete Cortex-M33 mode (-arch m33). Tri-architecture: -arch m0+ / -arch m33 / -arch rv32 with automatic firmware detection via UF2 family ID and picobin IMAGE_DEF blocks.

Coverage

| Area | Status | Details | |------|--------|---------| | RP2040 CPU | 65+ instructions | Full Thumb-1 + BL/MSR/MRS/DSB/DMB/ISB, O(1) dispatch, NZCV flags | | RP2350 RV | Complete | Hazard3: 93 RV32IMAC, Hazard3 CSRs, CLINT, SDK bootrom, icache, GDB, semihosting, stack protection | | RP2350 ARM | Complete | Cortex-M33 (-arch m33): full Thumb-2 via existing engine, BASEPRI, M33 CPUID, UF2 auto-detect | | RP2350 Peripherals | Complete | TICKS, POWMAN, QMI, OTP+data, BOOTRAM, TIMER1, PIO2, GLITCH, CORESIGHT, ACCESSCTRL, 48 GPIO, SIO | | Dual-Core | Complete | RP2040: host-threaded, WFI, FIFO, spinlocks, auto-launch. RP2350: cooperative dual-hart with CLINT + SIO mailbox launch | | Memory Map | 100% | RP2040: Flash + XIP + SRAM + ROM (16KB) + all peripherals. RP2350: 520KB SRAM + 32KB ROM + CLINT + all RP2350 peripherals | | Boot | Complete | RP2040: vector table, boot2, ROM functions. RP2350: RISC-V bootrom (SP init, flash jump) | | Exceptions | 100% | ARM: tail-chaining, late-arriving, PRIMASK + FAULTMASK. RISC-V: mtvec direct/vectored, MRET, MIE/MPIE, Hazard3 ext IRQ routing | | Timing | Cycle-accurate | Configurable clock (-clock 125/-clock 150), ARMv6-M instruction costs, CLINT mtime, TIMER1 | | Debugging | GDB RSP | Breakpoints, watchpoints, conditional breakpoints, dual-core threads (-gdb) | | Flash | Write-through + FUSE | -flash <path> with sync; -mount <dir> for live host access (thread-safe) | | Storage | SD card + eMMC | SPI-attached file-backed block devices | | WiFi | CYW43 (Pico W) | gSPI-over-PIO, TAP bridge with auto IP/NAT (-wifi, -tap) | | Performance | ICache + JIT | 64K decoded cache by default, optional hot-block JIT (-jit) | | Privilege | Auto-sudo | -tap and -mount auto-escalate via sudo when needed | | Dev Tools | 18 tools | Semihosting, coverage, hotspots, profile, trace, callgraph, VCD, IRQ latency, stack check, bus logging, watch, expect, script, fault injection, heatmap, symbols, exit codes, timeouts | | Firmware Auto-Detect | UF2 + ELF | Auto-detects RP2040/RP2350-ARM/RP2350-RV from UF2 family ID or ELF machine type | | RV Performance | ICache | 64K-entry decoded instruction cache for flash/ROM fetches | | RV Semihosting | EBREAK | EBREAK with a0=0x20026 triggers SYS_EXIT | | Tests | 300 | CTest integrated, 57+ categories (20 RV + 4 M33 tests) |

Peripherals

| Peripheral | Address | Emulation Level | |------------|---------|-----------------| | GPIO | 0x40014000 / 0xD0000000 | Full (30 pins, SIO, IO_BANK0, PADS, edge/level interrupts) | | UART | 0x40034000 / 0x40038000 | Full (dual PL011, Tx+Rx, 16-deep FIFO, active-console stdin routing) | | SPI | 0x4003C000 / 0x40040000 | Full (dual PL022, 8-deep TX/RX FIFOs, device callbacks) | | I2C | 0x40044000 / 0x40048000 | Full (dual DW_apb_i2c, 16-deep RX FIFO, device callbacks) | | Timer | 0x40054000 | Full (64-bit counter, 4 alarms, interrupts) | | PWM | 0x40050000 | Full (8 slices, CSR/DIV/CTR/CC/TOP, interrupts) | | ADC | 0x4004C000 | Full (5 channels, temp sensor, FIFO, round-robin) | | DMA | 0x50000000 | Full (12 channels, chaining, 4 alias layouts) | | PIO | 0x50200000 / 0x50300000 | Full (2 blocks, all 9 opcodes, FIFOs, clock divider) | | SysTick | 0xE000E010 | Full (CSR/RVR/CVR/CALIB, TICKINT, COUNTFLAG) | | NVIC | 0xE000E100 | Full (priority preemption, 4 levels, SCB_SHPR) | | Resets | 0x4000C000 | Full (reset/unreset, RESET_DONE tracking) | | Clocks | 0x40008000 | Full (10 generators, FC0 dynamic freq, SELECTED) | | XOSC/PLLs | 0x40024000 | Full (STATUS.STABLE, CS.LOCK) | | Watchdog | 0x40058000 | Full (CTRL, TICK, SCRATCH[0-7], reboot with full multicore state reset) | | SIO | 0xD0000000 | Full (GPIO, FIFO, spinlocks, hardware divider, interpolators) | | ROM | 0x00000000 | Full (16KB, function table, soft-float/double, flash write) | | USB | 0x50110000 | Full (host enumeration, CDC data bridge, stdio_usb, multi-packet IN) | | SYSINFO | 0x40000000 | Stub (CHIP_ID=RP2040-B2, PLATFORM=ASIC) | | SYSCFG | 0x40004000 | Full (NMI mask, proc config, debug force, mem power-down) | | TBMAN | 0x4006C000 | Full (PLATFORM=ASIC, testbench manager) | | VREG | 0x40064000 | Full (VREG EN/VSEL/ROK, BOD EN/VSEL, CHIP_RESET W1C flags) | | IO_QSPI | 0x40018000 | Stub (6 QSPI GPIO pins, STATUS/CTRL) | | PADS_QSPI | 0x40020000 | Stub (QSPI pad electrical control) | | ROSC | 0x40060000 | Full (STATUS, RANDOMBIT LFSR, CTRL enable) | | RTC | 0x4005C000 | Full (LOAD strobe, calendar rollover, leap year, ticking) | | XIP Cache | 0x14000000 | Stub (always ready) + 16KB XIP SRAM | | CYW43 | Pico W via PIO/SPI | Functional (scan/connect path, WLAN framing, TAP bridge) |

Storage Devices

| Device | Interface | Details | |----------------|--------------------|------------------------------------------------------------------------| | SD Card (SDHC) | SPI (default SPI1) | Full SPI-mode protocol, CSD v2.0, single/multi-block R/W, file-backed | | eMMC | SPI (default SPI0) | CMD1 init, EXT_CSD, sector addressing, file-backed |

Both devices attach via spi_attach_device() callbacks with periodic flush and flush-on-exit.

All peripherals support RP2040 atomic register aliases (SET/CLR/XOR).

Known Limitations

• Cycle timing: Default 1 MHz (fast-forward). Use -clock 125 for real RP2040 timing.
• Fidelity tradeoffs: DMA pacing, very high-speed PIO timing, and non-CDC USB device behavior are still functional models rather than fully cycle-perfect hardware.
• See ROADMAP for detailed status.

Building and Running

Prerequisites

• CMake 3.10+
• Standard C library (host)
• arm-none-eabi-gcc and Python 3 if you want to build the sample/test firmware

Build the Emulator

./build.sh

This builds the bramble executable in the project root.

You can also build explicitly with CMake:

cmake -S . -B build
cmake --build build -j

Choose Core Mode

Bramble builds with dual-core support enabled by default. Select the active cores at runtime:

./bramble firmware.uf2 -cores 1
./bramble firmware.uf2 -cores 2
./bramble firmware.uf2 -cores auto

Build Test Firmware

Hello World (prints "Hello from ASM!"):

cd test-firmware
chmod +x build.sh
./build.sh hello_world

GPIO Test (toggles LED on GPIO 25):

cd test-firmware
./build.sh gpio

Timer Test (measures elapsed time):

cd test-firmware
./build.sh timer

Alarm Test (tests timer alarms):

cd test-firmware
./build.sh alarm

Interactive UART Prompt Test (reads host stdin via -stdin and prints a greeting):

cd test-firmware
./build.sh name_prompt

Build All Tests:

cd test-firmware
./build.sh all

Run

UF2 Firmware:

./bramble hello_world.uf2
./bramble gpio_test.uf2
./bramble timer_test.uf2
./bramble alarm_test.uf2
./bramble name_prompt.uf2 -stdin
printf 'Ada\n' | ./bramble name_prompt.uf2 -stdin

ELF Firmware (auto-detected by extension):

./bramble firmware.elf

Run Tests

ctest --test-dir build --output-on-failure

Debug Modes

Bramble now supports flexible debug output modes:

Single-Core CPU Step Tracing (verbose CPU and peripheral logging):

./bramble -debug timer_test.uf2

Assembly Instruction Tracing (detailed POP/BX/branch operations):

./bramble -asm alarm_test.uf2

Combined Debug + Assembly Tracing:

./bramble -debug -asm alarm_test.uf2

No Debug Output:

./bramble hello_world.uf2

Dual-Core Specific:

./bramble firmware.uf2 -debug           # Core 0 debug output
./bramble firmware.uf2 -debug -debug1   # Both cores debug
./bramble firmware.uf2 -status          # Periodic status updates
./bramble firmware.uf2 -debug -status   # Debug + status combined
./bramble firmware.uf2 -stdin           # Route stdin to USB CDC when active, else UART0
./bramble firmware.uf2 -gdb            # Start GDB server on port 3333
./bramble firmware.uf2 -gdb 4444       # GDB server on custom port
./bramble firmware.uf2 -clock 125      # Real RP2040 timing (125 MHz)
./bramble firmware.uf2 -flash fs.bin   # Persistent flash storage
./bramble firmware.uf2 -debug-mem      # Log unmapped peripheral access
./bramble firmware.uf2 -jit            # Enable JIT for hot flash/ROM loops
./bramble firmware.uf2 -cores 2 -thread-quantum 128  # Tune threaded timeslice

RP2350 RISC-V Mode:

# Explicit architecture selection
./bramble firmware_rv.uf2 -arch rv32

# Auto-detected from UF2 family ID (0xE48BFF5A) or ELF machine type
./bramble pico2_rv_firmware.uf2

# With clock speed and flash persistence
./bramble firmware_rv.uf2 -arch rv32 -clock 150 -flash rv_flash.bin -stdin

Networking (UART-to-TCP bridge):

# Bridge UART0 to TCP port (connect with nc, minicom, etc.)
./bramble firmware.uf2 -net-uart0 9999 -stdin
# In another terminal: nc localhost 9999

# Connect UART0 to a remote host
./bramble firmware.uf2 -net-uart0-connect 192.168.1.10:9999

**Multi-De