tartelette / documentation demossource ↗

The RP2040 model

This page goes through the chip block by block: what tartelette models, and what it leaves out. The source for each block is in crates/core/rp2040-core/src/periph/, and each file's header comment has the full detail.

The general approach is to model a peripheral at the level the firmware sees it: registers, FIFOs, interrupts and DMA requests behave as in the datasheet, and data takes the time it would take on the wire. Electrical detail and internal timing that firmware can't observe are skipped.

Time

Everything runs on one clock: core 0's cycle counter, at a fixed 125 MHz. The timer counts 1 µs per 125 cycles, UART and SPI frames take as many cycles as their baud rate says, PIO state machines step on their divided clocks, and board devices schedule their own events in cycles. Nothing depends on the host's wall clock (except the network and a real Bluetooth adapter, which are outside the emulator), so a run is reproducible to the cycle.

The clock tree's registers are there, and the *_SELECTED status bits follow the mux settings since start-up code waits on them, but changing clocks doesn't change the emulation speed. The exception is clk_peri, whose frequency (125 MHz from clk_sys, or 48 MHz from the USB PLL as pico-sdk 2 and MicroPython set it up) is computed from the PLL and mux registers and used to time the UARTs and SPI.

Cores

Both Cortex-M0+ cores run the full ARMv6-M Thumb instruction set, with their own NVIC, SysTick and SCB. Instructions take their Cortex-M0+ cycle counts; there are no flash wait states and no bus contention between cores or with DMA.

Faults are precise: an unaligned access, an undefined instruction, a branch to an ARM-state address or an invalid EXC_RETURN raises a HardFault and is reported (see running.md).

The CPU is tested instruction by instruction against Unicorn in tools/cpu-difftest.

Not modelled: NMI, the VECTPENDING/ISRPENDING fields of ICSR, SHCSR, and the MPU.

Boot

The real B2 bootrom is mapped at address 0, so the ROM function table and the floating-point and memory routines work. Core 1 runs the bootrom from reset and waits there for the launch handshake over the FIFOs, exactly as on the chip. Core 0 skips the bootrom and boot2: the firmware is loaded into flash and SRAM directly and core 0 starts from its vector table.

Memory

RegionAddress
ROM0x0000_0000the B2 bootrom
Flash (XIP)0x1000_00002 MiB, read directly; all the XIP aliases behave the same
SRAM0x2000_0000264 KiB
APB peripherals0x4000_0000
AHB peripherals0x5000_0000DMA, USB, PIO
SIO0xD000_0000
PPB0xE000_0000NVIC, SysTick, SCB

The XIP cache is not modelled: flash reads take no extra time, and the cache can't be used as 16 KiB of extra SRAM at 0x1500_0000. The set/clear/XOR register aliases work for every peripheral, and a block held in reset by RESETS ignores writes as on the chip.

Peripherals

GPIO, pads and IO_BANK0

All 30 pins, with function select, the input/output/OE/IRQ overrides, pull-ups and pull-downs, input enable, and edge and level interrupts for both cores. SIO and both PIO blocks drive pins directly; the UART, SPI and I2C models handle their own data and leave their pins to the board, though the overrides still apply. A pin that nothing drives floats unless it has a pull.

Not modelled: drive strength, slew rate, Schmitt trigger settings (stored only), and the QSPI pins apart from the flash chip select override.

SIO

The inter-core FIFOs with their interrupts, the 32 hardware spinlocks, the per-core integer dividers and CPUID. GPIO_OUT/OE/IN live with the GPIO model.

Not modelled: the interpolators (their registers read as zero).

PIO

Both blocks, all four state machines each, with the complete instruction set: side-set, delays, autopush/autopull, FIFO joins, MOV/OUT EXEC, WAIT on pins, GPIOs and IRQs, wrap, and fractional clock dividers. State machines are stepped cycle by cycle, so pin edges come out at the exact cycle they would on the chip. When every machine is stalled on something outside (an empty FIFO, a pin, an IRQ), the emulator skips ahead.

Inputs pass through the two-cycle synchronizer unless bypassed, and when two machines drive the same pin in the same cycle the highest-numbered one wins.

Not modelled: OUT_STICKY and INLINE_OUT_EN (stored only), and the routing of PIO IRQ flags to the system interrupt lines (state machines see the flags; the NVIC doesn't).

DMA

All 12 channels, with the four register aliases per channel and their trigger semantics, chaining, address wrap rings, byte swapping, the pacing timers and both interrupt lines. DREQs come from the UARTs, SPI, PIO and I2C. One transfer moves one item per cycle.

Not modelled: the sniffer (registers stored) and the error flags.

UART

Both PL011 UARTs. Characters take the time the baud rate and line format give them, on the TX and RX side alike, so a firmware that doesn't empty its RX FIFO in time overruns, as on the chip. Interrupts follow the PL011: RX at the trigger level, TX when the FIFO drains past its level, receive timeout and overrun.

Until the firmware programs a divisor, the UART is untimed and transfers are instantaneous.

Not modelled: framing, parity and break errors, the modem lines and loopback.

SPI

Both PL022 controllers in master mode, Motorola frames of 4 to 16 bits. Frames go out back to back at the programmed bit rate: BSY stays set and the RX FIFO fills as they would on the chip. DMA works in both directions.

Not modelled: clock polarity and phase (stored only), the receive timeout interrupt, slave mode, and the TI and Microwire frame formats.

I2C

Both DesignWare I2C controllers in master mode. Transfers work a byte at a time and are instantaneous: each entry in the TX FIFO is done before the next instruction runs, so SCL timing settings have no effect. Restart, stop, reads and NAKs from missing devices are handled.

Not modelled: slave mode, general calls, SMBus features.

USB

USBCTRL in device mode, with the dual-port RAM and the buffer control words the way the hardware uses them. tartelette also provides the host on the other end of the cable. See usb.md.

Not modelled: host mode, the PHY and line states, suspend/resume.

Timer

The 64-bit microsecond counter and its four alarms, with their interrupts. The 1 MHz tick is assumed to be running.

RTC

The calendar: set it through SETUP_0/1 and CTRL.LOAD, enable it, and RTC_0/1 count from there in emulated time.

Not modelled: alarms (registers stored).

Flash (XIP SSI)

The SSI and a W25Q-style flash chip behind it, as the bootrom and pico-sdk drive them: unique ID, JEDEC ID, status register polling, page program and sector/block erase. That is enough for MicroPython's and littlefs's filesystems and for flash_range_program and friends. The flash can be kept in a file between runs with --flash.

Not modelled: DMA on the SSI, its interrupts, and erase/program timing (they're instantaneous).

PSM and RESETS

RESETS holds blocks in reset and reports them done; a block in reset ignores writes. In PSM, only core 1's bit does anything: turning it off and on restarts core 1 in the bootrom, which is how multicore_reset_core1 and Embassy's spawn_core1 get a clean core.

Clocks, PLLs and oscillators

Registers only, with the status bits start-up code polls (XOSC stable, PLL lock, clock selected) reading as expected. See Time.

Not modelled

ADC, PWM, the watchdog, VREG, TBMAN, SYSCFG and the other blocks not listed above are plain register files: writes are stored and read back, nothing happens. Firmware that only configures them will run; firmware that depends on them (reading an analog pin, waiting for a PWM wrap interrupt, relying on the watchdog to reset) will not behave as on hardware.