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
| Region | Address | |
|---|---|---|
| ROM | 0x0000_0000 | the B2 bootrom |
| Flash (XIP) | 0x1000_0000 | 2 MiB, read directly; all the XIP aliases behave the same |
| SRAM | 0x2000_0000 | 264 KiB |
| APB peripherals | 0x4000_0000 | |
| AHB peripherals | 0x5000_0000 | DMA, USB, PIO |
| SIO | 0xD000_0000 | |
| PPB | 0xE000_0000 | NVIC, 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.