summaryrefslogtreecommitdiff
path: root/gui/README.md
blob: 20fe29213391fc685e683c799b189f1b2efeb933 (plain) (blame)
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
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
# 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, dense view uses the animation library's source syntax colors, aligned
instruction cells, operand values, flag marks, pointer colors, telescope chains,
stack roles, frame spans, byte rows, and minimap strokes. Source runs line up with
their machine instructions; the gold thread connects the active run to the PC.
Changed registers, stack words and bytes strike, cool, and retain a corner mark.
Click an address for an animated memory lens; right-click to follow its meaning.

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.
Colon opens the debugger command bar; 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
goto memory 0x12345678
```

`break` accepts the library's function, file:line and `*address` forms. Its reply
includes the breakpoint ID. The icon buttons have hover labels and keys; pane
headers hold history, follow, minimap and interpretation controls.

| Keys | Action |
| --- | --- |
| `s`, `n` | One instruction / next source line (enters calls) |
| `c`, `Esc` or `Ctrl-c` | Continue / pause |
| `j` / `k`, `Ctrl-d` / `Ctrl-u`, `gg` / `G` | Smooth scroll, half page, first / last row |
| `h` / `l` | Inspect long source lines horizontally |
| `Ctrl-w h/j/k/l`, `Tab` | Focus a pane |
| `Ctrl-o` / `Ctrl-i`, Mouse4 / Mouse5 | Back / forward in the hovered or focused pane |
| `[` / `]`, `Shift-f` | Recorded stop history / latest live stop |
| `f` | Follow the live address in the focused pane |
| `v`, `m`, `a` | Source columns, minimap, operand annotations |
| `b`, `z`, `?`, `:` | Break at PC, address lens, help, command line |

Scrolling accepts fractional wheel deltas. Click or drag the actual-content
minimap to move its viewport. Each pane's bounded jump history remembers address
and scroll, and a new jump discards its forward branch. Browsing recorded state
never rewinds the process. Continuing returns the moment selection to live.
Source stepping may stay in a loop on one source line; pause with Esc / Ctrl-c.

A right-click follows executable memory (including RWX) into disassembly, stack
memory or a pointer-bearing word into the telescope, and other memory into the
hex view. Unknown bytes stay unknown. At a live stop this requests a bounded
read-only capture; it never writes RIP or resumes the target. `goto code|stack|memory
ADDRESS` selects a specific view. The first pass bounds views to 256 decoded
instructions, 128 stack slots, and 128 hex rows; jump to another address to inspect
further. A lens shows five real rows and follows further pointers when clicked.

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. `s` 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.


### JavaScript source beside JIT code

V8 can emit GDB JIT ELF objects containing actual line tables. Run the fixture
from its directory, using its **basename** (V8's dump filename embeds the script
name and cannot contain directory separators):

```text
launch /tmp/computeranim-v8-debug-remote/d8 --allow-natives-syntax --no-concurrent-recompilation --no-maglev --gdbjit --gdbjit-dump --gdbjit-dump-filter=jitWork --print-opt-code --print-opt-code-filter=jitWork jit.js
```

After reaching the generated-code breakpoint, import the emitted object:

```text
symbols /tmp/elfdumpjitWork jit.js:3:170.o
```

Use the actual emitted filename. The shared debugger validates its executable
sections against the stopped target and reuses the ELF/DWARF reader; inline
DWARF strings do not require `.debug_str`. The import is committed as an
inspection moment without moving the target. Source files are loaded with
`std.Io` and cached with owned syntax data. Missing source is explicitly labeled.

This is an explicit import of the current JIT object, not a watcher of the GDB
JIT registration protocol. Import a fresh object after code regeneration; it
must belong to the current process. No fabricated JS-to-instruction mapping is
used. Split native V8 `.dwo` files are still needed for complete C++ debug info.

Read-only capture and JIT source integration checks:

```sh
python3 gui/test/inspection.py --d8 /tmp/computeranim-v8-debug-remote/d8
python3 gui/bench/steps.py --d8 /tmp/computeranim-v8-debug-remote/d8 --jit-source --out /tmp/ztrace-step-bench-source
```