Files

T

evan 6e0e65218a feat(xteink): report and dump guest RAM usage

Adds a 'memory' subcommand and matching web tab that show how much of each
ESP32-C3 RAM window the guest has written, plus raw region dumps via QMP
pmemsave.

2026-07-27 12:39:55 -04:00

3.0 KiB

Raw Permalink Blame History

xteink QEMU fork

Espressif's QEMU fork carrying the xteink X3/X4 (ESP32-C3) machine model and a wasm32 TCG backend (ported from ktock/qemu-wasm), used by xteink-web-emulator to run CrossPoint firmware in the browser.

Branch

main — the working branch. Base is Espressif's esp-develop-9.2.2-20260417 (40edccac).

Remotes

origin — https://ssh.gitea.va.reichard.io/evan/qemu-xteink
upstream — https://github.com/espressif/qemu
qemu-wasm — https://github.com/ktock/qemu-wasm (source of the wasm32 backend)

Building

Native (parity check — authoritative)

nix develop
./configure --target-list=riscv32-softmmu --with-devices-riscv32=xteink --enable-gcrypt
ninja -C build qemu-system-riscv32

Or build the native xteink target into dist/qemu-native for direct script use:

make xteink
uv run --script scripts/xteink-emu.py --help

Agent emulator

nix run .#xteink-emu -- start --firmware firmware.bin --sdcard sdcard.img
nix run .#xteink-emu -- interactive --firmware firmware.bin --sdcard sdcard.img
nix run .#xteink-emu -- wait --timeout 30 --match 'ready'
nix run .#xteink-emu -- button bottom-2 --hold-ms 100
nix run .#xteink-emu -- screenshot --output screen.png
nix run .#xteink-emu -- memory
nix run .#xteink-emu -- memory --region iram --dump iram.bin
nix run .#xteink-emu -- stop
nix run .#xteink-emu -- web --host 127.0.0.1 --port 8080

The code lives in scripts/xteink/ (emu.py drives QEMU, cli.py is the command line, web/ is the browser UI); scripts/xteink-emu.py is the entry point. web serves a page that uploads firmware and an SD image, boots them, drives the buttons, streams the panel and serial log, and browses or edits the SD card through mtools. Card edits stop the emulator first, since QEMU caches the image; use Apply & Reboot to bring it back. memory reports how much of each RAM window the guest has written and dumps a region to a file; the web UI shows the same table under its Memory tab. QEMU zeroes RAM at reset, so the number is a high-water mark, not live heap — the firmware's own heap logging is authoritative for that. The screen redraws off the panel's frame-generation counter, so it updates on each real e-ink refresh rather than on a timer.

State defaults to /tmp/xteink-emu-$UID; pass --state-dir to any subcommand for parallel instances. interactive opens the display and maps Left/Right, 1–4, and P to the matching device buttons. Hold P for a long power press and close the window to stop. wait advances a persistent log cursor after each match. The emulator exposes the open Wi-Fi network qemu; guest traffic uses QEMU's user-mode NAT.

WebAssembly

Driven by the parent repo, not here:

cd ../xteink-web-emulator
make web-dev     # incremental build straight from this tree

The parent's scripts/build-qemu-wasm.sh compiles this checkout inside the emsdk Docker image defined in xteink-web-emulator/qemu/wasm/Dockerfile.

3.0 KiB Raw Permalink Blame History Unescape Escape