summaryrefslogtreecommitdiff
path: root/gui/README.md
blob: b77a5466c6c0217203b81350a1da009bfcd52cc1 (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
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
# 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 (Sketchbook `d307463` or newer for native profiling and upload fixes). 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
restart
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
lens 0x12345678
memory-format 8 hex
```

`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 |
| `Shift-r` | Restart the launched program at entry |
| `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 changes drawing scale, geometry, visible rows and pointer hit regions;
it never changes the native window dimensions or backing size. Every new
execution stop reveals PC and its source group. Nearby scrolling settles in
200 ms using elapsed time, including when the frame rate changes. 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. Executable mappings open disassembly lenses. Wheel over a
lens body to browse its segment; the original focus area stays bright while
surrounding rows dim. Shift-wheel, headers and gaps scroll the lens chain.
Right-click sends stack addresses to the stack pane and every other address to
memory. Matching addresses get staggered background highlights: the selected
occurrence appears first, followed by its peers. Lens ancestry keeps its connectors.
Stack offsets use the same hover/click behavior as their storage addresses.
Disassembly brackets also link simple 64-bit base/index/scale/displacement addresses,
including `lea`, using the selected stop's registers only at its PC. RIP-relative
and absolute addresses work on other rows too. Future/past register values,
segment overrides and 32-bit addressing are not inferred. Truncated brackets
have no hidden hit target. These links work in executable lenses too.
Address values in the right-hand register hints use the same hover and mouse
actions, at the displayed register width. Ordinary scalar hints stay inactive.

Memory's two header controls choose 8/16/32/64-bit groups and hexadecimal,
unsigned, signed or floating-point values (little endian). `memory-format SIZE
FORMAT` sets byte sizes 1/2/4/8 and `hex`, `unsigned`, `signed` or `float` directly;
floats require 4 or 8 bytes. Unknown bytes stay unknown; these controls only
change rendering. Recognized pointer fields are clickable across all their bytes,
including 8-bit view: left-click opens a lens; right-click opens stack or memory.
Wide values remain reachable with Shift-h/l.
Hex bytes have no persistent group background; hover and access highlights remain.

Lenses keep an opaque reading surface, with a native GPU backdrop shader for
edge refraction, subtle color separation and a cyan rim. A canvas-sized texture and one reusable lens snapshot
are independent of font zoom and lens count. Non-GPU rendering keeps an opaque
fallback. `set glass false` in the renderer console disables the effect.

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).
The local runtime, matching source and split DWARF now live in the ignored
`.ws/v8-debug/` cache, which survives reboot.
`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 .ws/v8-debug/runtime/d8 \
  --source .ws/v8-debug/source --out /tmp/ztrace-natural-bench
python3 gui/test/inspection.py --d8 .ws/v8-debug/runtime/d8 --source .ws/v8-debug/source
```

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 ../../.ws/v8-debug/runtime/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 ../../.ws/v8-debug/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.

The toolbar's circular arrow, `Shift-r`, or `restart` relaunches the same executable
and arguments, including after exit. It stops at entry with fresh breakpoints and
JIT symbols; source-prefix mappings and display preferences are retained. Old
recordings remain on disk, while pinned addresses, lenses and histories reset
because addresses may change in the new process.

## 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.

Native restart/zoom regression (requires a display):

```sh
python3 gui/test/restart.py --native
```

This checks the actual SDL window dimensions across zoom levels, in addition to
the headless checks included in `zig build test`.

## Frame profiling

Tracy is optional and shared with Sketchbook. A normal build has no Tracy client.
To measure native scrolling, lenses and live stepping:

```sh
cd gui
zig build -Doptimize=ReleaseFast -Dtracy=/absolute/path/to/tracy
cd ..
python3 gui/bench/frames.py --tracy /absolute/path/to/tracy --out /tmp/ztrace-frames
# Repeat with --size 1440x900 or --size 800x700 --zoom 200.
```

The checkout needs `build-capture/tracy-capture` and
`build-csvexport/tracy-csvexport`. The harness writes a reproducible input script,
`.tracy` capture, event CSV and percentile summary. It excludes the first two
seconds from warm interaction statistics. Host frame/presentation times include
VSync and driver waits; GUI `draw` measures construction of drawing commands.
Source loading and debugger transition capture have separate measurements in
[the benchmark results](bench/RESULTS.md). Rebuild without `-Dtracy` for ordinary use.