diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-12 13:19:32 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-13 00:41:47 -0300 |
| commit | 4b4113a0217ee27c78e7efddb66ff5a455d49083 (patch) | |
| tree | b848dc1e92c3126dec11da8547e8033ff3990140 /gui/README.md | |
| parent | eab50d1c040774351f332a1568fa332c377860bd (diff) | |
| download | computeranim-4b4113a0217ee27c78e7efddb66ff5a455d49083.tar.gz computeranim-4b4113a0217ee27c78e7efddb66ff5a455d49083.zip | |
debugger: add a native GUI with live V8 JIT debugging
Diffstat (limited to 'gui/README.md')
| -rw-r--r-- | gui/README.md | 124 |
1 files changed, 124 insertions, 0 deletions
diff --git a/gui/README.md b/gui/README.md new file mode 100644 index 0000000..3bd7d3f --- /dev/null +++ b/gui/README.md @@ -0,0 +1,124 @@ +# ztrace GUI + +A separate native application using **ztrace** for control and recordings and +**canim / Sketchbook** for the view. The libraries stay where they are. It launches +a real Linux x86-64 process, stops at breakpoints, steps, and browses recorded +machine state. No gdb subprocess or browser frontend. + +The fixed view uses the animation library's instruction cells, operand values, +flag marks, pointer colors, telescope chains, stack roles and frame spans. +The current-instruction marker moves between rows; changed registers and stack +words strike in vermilion, cool, then retain a corner marker. Those changes are +computed from adjacent recorded moments. + +Build with the same Zig toolchain as the rest of computeranim; the sibling +`sketchbook` and `pardes` checkouts are the existing renderer dependencies: + +```sh +cd gui +zig build -Doptimize=ReleaseFast +zig build test -Doptimize=ReleaseFast +zig build run -Doptimize=ReleaseFast -- --fresh +``` + +The build installs `ztrace` alongside `ztrace-gui`; keep the two together. +Backtick opens the renderer's console: + +```text +launch /absolute/path/to/program arguments +break main +continue +break *0x12345678 +clear 1 +signal 0 +interrupt +stepi +nextline +``` + +`break` accepts the library's function, file:line and `*address` forms. Its reply +includes the breakpoint ID. F5 toggles continue/pause, F10 steps one instruction, +F11 steps to another source line (one instruction when source is unavailable). +The corresponding buttons work with the mouse. Left/right browse recorded +moments; End returns to the latest stop. Browsing history does not rewind the +process. Continuing returns the view to live state. Source stepping can stay in +a loop on one source line; F5 interrupts it. + +The renderer already uses `pause` and `step` for its own timeline. The debugger's +console names are `interrupt` and `nextline` to keep those separate. Do not use +renderer playback to replay debugger commands. + +Without a launched target, `open /path/to/file.ztrace` views an existing recording. +Live recordings remain at `/tmp/ztrace-gui-PID-TIMESTAMP.ztrace` after closing. +Closing the GUI terminates the target it launched. Target stdin is `/dev/null`; +its stdout and stderr go to the GUI's stderr. There is no terminal emulation. + +## How it fits + +The GUI starts `ztrace serve RECORDING -- PROGRAM [ARGS]` with private pipes. +A single controller thread owns every ptrace operation. A `std.Io.concurrent` +reader feeds a bounded `std.Io.Queue`; `Debugger.on_wait` services that mailbox +while the target runs. `Debugger.interrupt` requests SIGSTOP and suppresses its +redelivery. Idle waits use `std.Io.sleep`, while fast steps briefly poll. +Existing synchronous debugger callers retain their blocking wait. + +Replies are small newline-delimited JSON values (`src/trace/control.zig`). A +`std.Io` task in the GUI reads replies into one mutex-protected latest snapshot. +The draw loop never waits for ptrace. Each completed command flushes the existing +recorder before publishing its stop; the GUI reopens that committed snapshot and +queries `Trace.moment`. File I/O, subprocesses, queues, tasks, locks and timing use +`std.Io`. Raw Linux calls remain at the ptrace/signal and descriptor boundaries. + +New executable mappings are refreshed when a stop's PC is previously unknown, +so code produced by a JIT is recorded without tracing every syscall. Entering +code without source lines clears the previous source location in the recording. The GUI +uses bounded moment queries rather than indexing an entire animation recording. +It draws the existing canim components without requiring an animation timeline. + +## Debug V8 + +Build V8 on `chaincli-box`, using the `v8-remote-build` skill. Copy d8 together +with its shared libraries, data/snapshots and build flags to the workstation. +See [the measured run](bench/RESULTS.md) for the exact revision and limitations. + +For the deterministic JIT fixture: + +```sh +./zig-out/bin/ztrace-gui --fresh \ + --console 'launch /tmp/computeranim-v8-debug-remote/d8 --allow-natives-syntax --no-concurrent-recompilation --no-maglev --print-opt-code --print-opt-code-filter=jitWork /absolute/path/to/computeranim/gui/targets/jit.js' \ + --console continue 2>/tmp/ztrace-jit.log +``` + +`%SystemBreak()` first stops in V8's native runtime after optimizing `jitWork`. +Find the address of `addl r8,r11` in its printed TurboFan loop body. In the GUI +console, enter `signal 0`, `break *ADDRESS`, then `continue`. This second stop is +a software breakpoint inside the generated JavaScript code, not the runtime +trap. F10 steps through that machine code. Addresses change on each launch. +The benchmark checks both RIP and that it belongs to an anonymous executable map. + +```sh +# From the repository root, after building gui/: +python3 gui/bench/steps.py --d8 /tmp/computeranim-v8-debug-remote/d8 +``` + +The script builds a small C control, tests the JIT breakpoint, steps each target +1,000 times with identical capture settings, and writes recordings, target logs +and `results.json` under `/tmp/ztrace-step-bench`. `capture` includes ptrace, +register/stack/telescope/disassembly capture and recording flush; `roundtrip` +also includes pipe transport and the Python driver. Neither measures display +presentation latency. First-break timing includes target startup and initial +symbol work. Debugger builds use ReleaseFast; target builds remain Debug. + +## First-pass boundaries + +Fixed layout, one launched target, selected stopped thread, address/function +breakpoints, and machine-state history. There is no attach UI, thread picker, +expression evaluator, reverse execution or JavaScript source-map integration. +Launch arguments are whitespace-separated (no shell quoting). V8 JIT names/code +movement are not registered automatically: this fixture obtains the address from +V8's own disassembly and stops before using it. Breakpoints are not relocated if +V8 moves or discards generated code. + +Split DWARF files and V8 source must be retrieved separately for full C++ local +inspection. The current renderer is a canvas with keyboard controls; it does not +yet expose debugger rows through a native accessibility tree. |
