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
|
# ztrace GUI
A native, live Linux x86-64 debugger using **ztrace** for process control and
recordings and **canim / Sketchbook** for rendering. Continue, pause, instruction
step and source step operate on the running process. Each stop records a snapshot;
browsing that history does not rewind execution. There is no gdb subprocess,
browser frontend, or continuous instruction trace.
```sh
cd gui
zig build -Doptimize=ReleaseFast
zig build test -Doptimize=ReleaseFast
zig build run -Doptimize=ReleaseFast -- --fresh
```
Use the repository's Zig toolchain and existing sibling `sketchbook` and `pardes`
checkouts. Keep the installed `ztrace` beside `ztrace-gui`.
## Controls
Colon opens the debugger command bar; backtick opens the renderer console.
```text
launch /absolute/path/to/program arguments
break main
continue
break *0x12345678
clear 1
interrupt
stepi
nextline
goto code 0x12345678
goto stack 0x12345678
goto memory 0x12345678
source-map /remote/build/source /local/source
symbols /tmp/current-jit-object.o
origin 0x12345678
```
`break` accepts function, file:line and `*address` forms. `origin` retains the
recorded source location of an originating JS instruction during a native
transition. `source-map` resolves the longest matching directory prefix in the
shared symbol library, both for live control and offline GUI source loading.
Relative prefixes resolve against the debugger's working directory.
| Keys | Action |
| --- | --- |
| `s`, `n` | Instruction / next source line (enters calls) |
| `c`, `Esc` or `Ctrl-c` | Continue / pause |
| `Ctrl-+` / `Ctrl-=` / `Ctrl--`, `Ctrl-0` | Font scale in 10% steps, 60–200%; reset |
| `j` / `k`, `Ctrl-d` / `Ctrl-u`, `gg` / `G` | Scroll, half page, segment start / end |
| `PageUp` / `PageDown` | Scroll the stacked page |
| `h` / `l`, `Shift-h` / `Shift-l` | Source horizontal scroll / pane horizontal scroll |
| `Tab`, `Ctrl-w h/j/k/l` | Focus pane |
| `Ctrl-o` / `Ctrl-i`, Mouse4 / Mouse5 | Pane address history |
| `[` / `]`, `Shift-f` | Recorded stop history / latest live stop |
| `f` | Follow current live address in focused pane |
| `p` | Search mapping names, addresses and permissions for the active pane |
| `t`, `d` | Control-flow graph / unobserved opacity (25%, 50%, 75%, 100%) |
| `v`, `m`, `a` | Source, minimap, operand annotations |
| `b`, `z`, `?`, `:` | Break at PC, lens, help, command bar |
Wide windows keep code beside registers and memory beside stack. Smaller windows
stack these panes; wheel over a header/gutter or use PageUp/PageDown to reach them.
Font scaling recomputes geometry, visible rows and pointer hit regions. Every new
execution stop reveals PC and its source group. Manual scrolling lasts until the
next stop; an explicit address jump stays pinned until Follow is enabled.
Stack, memory and disassembly navigation span the **entire selected mapping**.
The thin right minimap rail maps its full address range. The adjacent content
minimap compresses source-only gaps and unknown memory rows. `p` selects any
mapping from the selected recording moment and adds the jump to that pane's
history. At a live stop, navigation fetches only a bounded window (128 instructions
or 2 KiB), without resuming the target or changing RIP. Historical views use
recorded bytes only: uncaptured data remains unknown. Arbitrary x86 address jumps
start decoding at the requested byte; instruction boundaries are only certain
when supplied by recorded code, symbols or a known entry point.
Click an address to open a connected lens. Further pointers keep their ancestors;
a different pointer in a parent replaces its descendants. Each close button closes
that lens and its children. Cycles, unreadable addresses and uncaptured historical
bytes are labeled. Long chains scroll within the overlay. Right-click routes an
address to disassembly, stack telescope or memory according to its mapping/value.
The graph uses recorded basic blocks and shared graph layout. It is scoped to
captured code, not a complete static analysis of an entire executable. Gold marks
PC; recent observed PCs are bright. Branch-target annotation is a prediction from
the current flags. Dimming means **unobserved**, not proof an instruction was
skipped: Continue does not record all intermediate execution.
## Natural V8 deoptimization
Use the existing debug build on `chaincli-box`; see [results and provenance](bench/RESULTS.md).
`targets/jit.js` warms `jitWork` with one object shape, then supplies another.
It uses no optimization intrinsics, traps, engine patches or tier-disabling flags.
```sh
# From the repository root, after building gui/:
python3 gui/bench/steps.py --d8 /tmp/computeranim-v8-debug-remote/d8 \
--source /tmp/computeranim-v8-source --out /tmp/ztrace-natural-bench
python3 gui/test/inspection.py --d8 /tmp/computeranim-v8-debug-remote/d8
```
The harness waits for natural TurboFan code, imports the matching V8 GDB JIT ELF,
stops at its wrong-map guard exit, verifies the originating return address at
`v8::internal::Deoptimizer::New`, continues to
`v8::internal::Runtime_NotifyDeoptimized`, and identifies the actual fallback by
stepping into its dispatch handler. This revision resumed Ignition; another build
may resume a different tier. The harness fails instead of relabeling it.
For the interactive session, run from `gui/targets` with the script basename
(V8 embeds that name in its JIT ELF dump filename):
```text
launch /tmp/computeranim-v8-debug-remote/d8 --trace-opt --trace-deopt --trace-deopt-verbose --print-opt-code --print-opt-code-filter=jitWork --gdbjit --gdbjit-dump --gdbjit-dump-filter=jitWork jit.js
break main
continue
clear 1
source-map ../../src /tmp/computeranim-v8-source/src
break v8::internal::Deoptimizer::New
break v8::internal::Runtime_NotifyDeoptimized
continue
```
Ignore unrelated outer-loop deoptimizations. Use the printed `jitWork` TurboFan
block containing the `wrong map` relocation to locate the generated exit and its
guard. Import the dumped ELF whose executable section covers that exact code
address using `symbols PATH` (multiple compilations produce multiple objects).
Break at the exit, inspect the guard's code, set `origin GUARD_ADDRESS`, and continue
to Deoptimizer::New. Its x86-64 `rdx` must equal that exit's recorded return PC.
The guard maps to JS property access line 3; the shared exit stub's own line table
can instead name the return statement. Addresses change each run. The harness
in `bench/control.py` is the executable version of these checks.
## Recording and boundaries
`open PATH.ztrace` opens history without launching a target. Live recordings stay
at `/tmp/ztrace-gui-PID-TIMESTAMP.ztrace` after closing. Closing the GUI terminates
its launched target. Target stdin is `/dev/null`; stdout/stderr go to GUI stderr.
Launch arguments are whitespace-separated, without shell quoting.
A single controller thread owns ptrace; a mailbox services commands while the
process runs. Stop replies follow recording flush; drawing reads committed
snapshots without blocking on ptrace. Mappings refresh at each stop, including
new non-code mappings. Inspection commits metadata/bytes without executing.
`capture_ns` measures stop capture and flush separately from total command time.
One launched process and selected stopped thread are supported. There is no
attach UI, thread picker, expression evaluator or reverse execution. JIT ELF
imports are explicit; breakpoints do not relocate when generated code moves.
Retrieved split DWARF artifacts are available, but complete split-DWARF C++ local
variable inspection is not implemented. The canvas has keyboard controls but
still lacks a native accessibility tree for debugger rows.
|