{"id":50189554,"url":"https://github.com/0x4d44/picoem","last_synced_at":"2026-05-25T12:03:36.851Z","repository":{"id":355479346,"uuid":"1208871458","full_name":"0x4D44/picoem","owner":"0x4D44","description":"Cycle-accurate Rust emulators for the Raspberry Pi RP2350/RP2354 and RP2040 (dual Cortex-M33 / Cortex-M0+ + PIO).","archived":false,"fork":false,"pushed_at":"2026-05-03T21:01:48.000Z","size":13449,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-03T21:25:26.484Z","etag":null,"topics":["cortex-m0plus","cortex-m33","embedded","emulator","pico","pio","rp2040","rp2350","rp2354","rust"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0x4D44.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-12T21:10:40.000Z","updated_at":"2026-05-03T21:22:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/0x4D44/picoem","commit_stats":null,"previous_names":["0x4d44/picoem"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/0x4D44/picoem","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0x4D44%2Fpicoem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0x4D44%2Fpicoem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0x4D44%2Fpicoem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0x4D44%2Fpicoem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0x4D44","download_url":"https://codeload.github.com/0x4D44/picoem/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0x4D44%2Fpicoem/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33473706,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-25T06:32:55.349Z","status":"ssl_error","status_checked_at":"2026-05-25T06:32:35.322Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cortex-m0plus","cortex-m33","embedded","emulator","pico","pio","rp2040","rp2350","rp2354","rust"],"created_at":"2026-05-25T12:03:35.130Z","updated_at":"2026-05-25T12:03:36.845Z","avatar_url":"https://github.com/0x4D44.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# picoem\n\nCycle-accurate emulators for the Raspberry Pi **RP2354 / RP2350** (dual Arm Cortex-M33 @ 150 MHz, 520 KB SRAM, FPU, coprocessors, PIO) and **RP2040** (dual Arm Cortex-M0+ @ 133 MHz, 264 KB SRAM, PIO), written in Rust.\n\nThe goal is a small, clean, verifiable emulator core that can boot the real Pi bootroms, run ARMv8-M (M33) or ARMv6-M (M0+) firmware with accurate cycle timing, and serve as a reusable library crate for downstream projects.\n\n```\npicoem (this repo)           — RP2350/RP2354 + RP2040 emulators, TUIs, test harness\n  ├─► rp2350-emu                 — RP2350 / RP2354 emulator library (Cortex-M33)\n  ├─► rp2040-emu                 — RP2040 emulator library (Cortex-M0+)\n  └─► onerom-emu               — OneROM firmware running on rp2350-emu\n        └─► mddosem            — DOS emulator, uses OneROM as BIOS\n```\n\n## Status\n\nA personal research project, published in case it's useful to others.\nI use these crates in my own work and will likely keep pushing fixes\nas I hit them, but I'm not committing to issue triage, PR review SLAs,\nor ongoing feature development. No promises — if you need certainty\naround a bugfix or feature, fork freely under MIT/Apache-2.0.\n\nFeature coverage as of the published versions — Arm-mode only; Hazard3\nRISC-V cores on RP2350 are out of scope:\n\n| Subsystem | RP2350 / RP2354 | RP2040 |\n|---|---|---|\n| CPU core ISA | Cortex-M33 (ARMv8-M Mainline); differential-tested vs QEMU | Cortex-M0+ (ARMv6-M); differential-tested vs QEMU `cortex-m0` |\n| FPU (VFPv5 single-precision) | Working; lazy context save | N/A |\n| Coprocessors (GPIO/CP0, DCP, RCP) | Working | N/A |\n| Dual-core + SIO (spinlocks, FIFOs, interpolators) | Working | Working (+ hardware divider) |\n| Bus fabric | Working; some timing edge cases open | Working; simplifications open (see `tech_debt.md`) |\n| Clock tree (ROSC / XOSC / PLL / dividers) | Working | Working |\n| Exceptions / NVIC / fault delivery | Working | Working |\n| Memory | 32 KB ROM, 520 KB SRAM, XIP flash | 16 KB ROM, 264 KB SRAM (no onboard flash) |\n| PIO blocks | Working | Working |\n| Pacer (wall-clock real-time pacing) | Working (`x86_64` only) | Type available; step cadence not yet quantum-based (see `tech_debt.md`) |\n| UART / SPI / I2C / DMA / timers | Stubs | Stubs |\n| GDB RSP debug server | Stub | Stub |\n| TrustZone (SAU / ACCESSCTRL) | Design seams only — v1 treats everything as Secure | N/A |\n\nOpen cycle-timing gaps and post-Phase-7 residuals are tracked in `tech_debt.md`.\n\n## Quick Start\n\nClone with submodules — the workspace member `epio-sys` references vendored\nupstream sources via git submodules. A normal clone works for everything else,\nbut `cargo build -p epio-sys` requires submodules to be initialised:\n\n```bash\ngit clone --recursive https://github.com/0x4D44/picoem.git\n# or, after a non-recursive clone:\ngit submodule update --init\n```\n\n`epio-sys` is excluded from the workspace's `default-members` and additionally\nrequires `clang` to be on `PATH`, so a plain `cargo build --release` at the\nworkspace root works on hosts without `clang` or initialised submodules — opt\nin explicitly with `cargo build -p epio-sys` once those prerequisites are in\nplace.\n\n```bash\n# Build everything (release profile is strongly recommended — debug is slow)\ncargo build --release\n\n# RP2350 / RP2354 interactive TUI (dual Cortex-M33)\ncargo run -p rp2350-emu-tui --release              # blinky (default)\ncargo run -p rp2350-emu-tui --release -- lcd       # LCD demo\ncargo run -p rp2350-emu-tui --release -- benchmark # throughput benchmark\ncargo run -p rp2350-emu-tui --release -- blinky    # (explicit)\n\n# RP2040 interactive TUI (dual Cortex-M0+)\ncargo run -p rp2040-emu-tui --release              # blinky (default)\n\n# Load your own firmware\ncargo run -p rp2350-emu-tui --release -- path/to/firmware.bin\ncargo run -p rp2040-emu-tui --release -- path/to/firmware.bin\n```\n\nThe RP2350 TUI has panels for CPU status, GPIO state, an LCD device emulator, an ISA trace view, and a live benchmark panel. The RP2040 TUI has the same shape minus the FPU / DCP / RCP / NS panels, and its ISA panel carries M0+-specific cycle numbers.\n\nBundled ROMs under `roms/rp2350/` (`blinky.bin`, `benchmark.bin`, `lcd_demo.bin`, `dualcore.bin`) and `roms/rp2040/` (`blinky.bin`) are generated from the `gen_*.py` scripts in the same directories. The real Pi bootroms are checked in as `roms/rp2350/bootrom-combined.bin` and `roms/rp2040/bootrom.bin`.\n\n## Workspace Layout\n\nSeven crates under `crates/`:\n\n- **`picoem-common`** — shared primitives: `Memory`, `ClockTree`, `Pacer`, PIO primitive types (`PioBlock` / `StateMachine`), divider/FIFO, `Peripheral` trait. Both chip crates depend on this.\n- **`rp2350-emu`** — the RP2350 / RP2354 emulator core library (CPUs, bus, memory, clocks, SIO, PIO, FPU, coprocessors, pacer).\n- **`rp2350-emu-tui`** — interactive TUI (ratatui + crossterm) for `rp2350-emu`, with panels and a device frontend (LCD, benchmark).\n- **`rp2040-emu`** — the RP2040 emulator core library (dual Cortex-M0+, bus, memory, clocks, SIO, PIO).\n- **`rp2040-emu-tui`** — interactive TUI for `rp2040-emu`.\n- **`picoem-harness`** — all differential and hardware-in-the-loop test binaries. Binaries are chip-suffixed (`qemu_diff_m33` / `qemu_diff_m0plus`, `probe_diff_rp2350` / `probe_diff_rp2040`, etc.).\n- **`picoem-debug`** — GDB RSP server and trace tooling. Stubbed.\n\nThe real UIs are `rp2350-emu-tui` and `rp2040-emu-tui`; run them with `cargo run -p rp2350-emu-tui` or `cargo run -p rp2040-emu-tui`. The workspace has no top-level binary.\n\n## Testing\n\nThe emulators are validated by independent oracles, each catching different bug classes.\n\n### 1. Unit tests\n\n```bash\ncargo test                      # all crates\ncargo test -p rp2350-emu          # RP2350 / RP2354 core only\ncargo test -p rp2040-emu          # RP2040 core only\ncargo test \u003cname_substring\u003e     # filtered\n```\n\nInstruction semantics, decode edge cases, exception mechanics, PIO, and clock-tree config live in each core crate's `tests.rs` / `pio_tests.rs` / `tests/firmware.rs`.\n\n### 2. QEMU differential harness (per chip)\n\nEach oracle spawns a QEMU reference CPU, connects over GDB, runs the same instruction in both QEMU and the emulator, then diffs R0–R15 + xPSR (masking architecturally unpredictable flag fields).\n\n```bash\n# RP2350 / Cortex-M33 oracle (GDB port 3333)\ncargo run -p picoem-harness --release --bin qemu_diff_m33                        # edge-case suite\ncargo run -p picoem-harness --release --bin qemu_diff_m33 -- --fuzz 100000       # random fuzz\ncargo run -p picoem-harness --release --bin qemu_diff_m33 -- --fuzz 100000 --seed \u003cS\u003e\n\n# RP2040 / Cortex-M0+ oracle (GDB port 3334, uses QEMU `cortex-m0` — see `tech_debt.md`)\ncargo run -p picoem-harness --release --bin qemu_diff_m0plus\ncargo run -p picoem-harness --release --bin qemu_diff_m0plus -- --fuzz 100000\ncargo run -p picoem-harness --release --bin qemu_diff_m0plus -- --fuzz 100000 --seed \u003cS\u003e\n```\n\nRequires `qemu-system-arm` on `PATH`.\n\nOn Windows, a running `.exe` is locked against overwrite, so a long fuzz session will block concurrent `cargo build --release` (or any build that relinks the harness). Copy the binary out before a long run — e.g. `cp target/release/qemu_diff_m33.exe /tmp/fuzzer.exe \u0026\u0026 /tmp/fuzzer.exe --fuzz 100000`. The overnight drivers under `fuzz-runs/` handle this automatically. See `CLAUDE.md` for the full note.\n\n### 3. Hardware-in-the-loop (real silicon)\n\nDrive a real RP2354 board over SWD via a Pi Pico debug probe, single-step it, and diff against the emulator. Catches behaviours QEMU doesn't model correctly — e.g. pipeline effects, peripheral timing. `bank_conflict_test_rp2350` characterises SRAM bank-contention timing on silicon for reference; the emulator itself does **not** model bank contention on RP2350 (see `CLAUDE.md` / `wrk_journals/2026.04.15 - JRN - Contention Modelling Declined.md` for rationale).\n\n```bash\n# Same instruction-level test suite as qemu_diff_m33 but against silicon\ncargo run -p picoem-harness --release --bin probe_diff_rp2350\n\n# Register / DWT cycle-counter sanity checks\ncargo run -p picoem-harness --release --bin probe_verify_rp2350\n\n# SRAM bank-conflict timing characterisation\ncargo run -p picoem-harness --release --bin bank_conflict_test_rp2350\n```\n\nRequires a Pi Pico configured as a `probe-rs`-compatible debug probe wired to an RP2354 target (for the `*_rp2350` binaries) or a Pico V1 / RP2040 target (for `probe_diff_rp2040`). On a host with both probes attached, disambiguate with `--probe \u003cVID:PID:SERIAL\u003e` — `probe-rs list` shows the available serials.\n\n### 4. Paced benchmark and full integration\n\n```bash\ncargo run -p picoem-harness --release --bin paced_bench_rp2350\ncargo run -p picoem-harness --release --bin full_test_rp2350\n```\n\nMeasures real-time throughput with wall-clock pacing and runs a larger integration smoke. Useful for regression-checking performance work.\n\n### Coverage\n\n```bash\ncargo llvm-cov\n```\n\n## Design Documents\n\nPhase HLDs live under `wrk_docs/`. Filenames follow `YYYY.MM.DD - HLD - \u003ctopic\u003e V\u003cN\u003e.md`. Start with `2026.04.12 - RP2350 Emulator HLD.md` for the original design (with an errata note at the top tracking the post-restructure crate renames), then the phase docs (bus fabric, interrupts, dual-core, PIO, coprocessors/FPU) for subsystem detail. Newer dated versions supersede earlier drafts of the same phase. The workspace restructure is documented in `2026.04.14 - HLD - mdpicoem Workspace Restructure.md`.\n\nPer-session journals (investigations, performance work, review cycles) live under `wrk_journals/`. Known cycle-timing gaps against real silicon and post-Phase-7 residuals are in `tech_debt.md`.\n\n## Requirements\n\n- Rust (edition 2024, stable)\n- `qemu-system-arm` for `qemu_diff_m33` / `qemu_diff_m0plus` (any reasonably recent release; the M0+ oracle uses `cortex-m0` because QEMU 10.2 doesn't ship a `cortex-m0plus` model — see `tech_debt.md`)\n- A Pi Pico debug probe + RP2354 target board for the `probe_*_rp2350` harnesses (optional)\n\nThe `pacer` module uses `x86_64`-only atomics; builds on other hosts will work as a library but won't get wall-clock pacing.\n\n## License\n\nLicensed under either of\n\n- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or \u003chttps://www.apache.org/licenses/LICENSE-2.0\u003e)\n- MIT license ([LICENSE-MIT](LICENSE-MIT) or \u003chttps://opensource.org/licenses/MIT\u003e)\n\nat your option.\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in the work by you, as defined in the Apache-2.0 license, shall\nbe dual licensed as above, without any additional terms or conditions.\n\nThis repository redistributes third-party content under their respective\nlicenses — Raspberry Pi RP2350 and RP2040 bootroms (BSD-3-Clause), the\nPicoGUS firmware (GPL-2.0-or-later), and a vendored fork of probe-rs\n(MIT OR Apache-2.0). See [NOTICE](NOTICE) for the full list and attribution.\n\n## Trademarks\n\n*Raspberry Pi*, *RP2350*, *RP2354*, *RP2040*, and *Pico* are trademarks\nof Raspberry Pi Ltd. *Arm*, *Cortex-M0+*, *Cortex-M33*, *Armv6-M*,\n*Armv8-M*, and *NEON* are trademarks or registered trademarks of Arm\nLimited (or its subsidiaries) in the US and/or elsewhere. *Sound\nBlaster* is a trademark of Creative Technology Ltd. *AdLib*, *Gravis\nUltrasound*, and *MT-32* are trademarks of their respective owners.\n*Monkey Island* is a trademark of Lucasfilm Entertainment Company Ltd.\nLLC.\n\nThis project is an independent emulator and is not affiliated with,\nendorsed by, or sponsored by any of the above trademark holders. All\ntrademarks are used for identification purposes only.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0x4d44%2Fpicoem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0x4d44%2Fpicoem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0x4d44%2Fpicoem/lists"}