evan
6e0e65218a
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.
65 lines
3.0 KiB
Markdown
65 lines
3.0 KiB
Markdown
# 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](https://github.com/ktock/qemu-wasm)),
|
||
used by [xteink-web-emulator](../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)
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
make xteink
|
||
uv run --script scripts/xteink-emu.py --help
|
||
```
|
||
|
||
### Agent emulator
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
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`.
|