1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
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.
|