diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-13 09:28:38 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-13 09:28:38 -0300 |
| commit | 5c0230ea5a77f85de77ad4354788cd6c27aa1ef6 (patch) | |
| tree | e01a903bdee092965b86e118dfaab85c3bd60004 /gui/README.md | |
| parent | 5a40dca5adb6e9e650f55f3ec6f254a13bf50493 (diff) | |
| download | computeranim-5c0230ea5a77f85de77ad4354788cd6c27aa1ef6.tar.gz computeranim-5c0230ea5a77f85de77ad4354788cd6c27aa1ef6.zip | |
debugger: follow natural V8 deoptimization with adaptive live views
Diffstat (limited to 'gui/README.md')
| -rw-r--r-- | gui/README.md | 241 |
1 files changed, 105 insertions, 136 deletions
diff --git a/gui/README.md b/gui/README.md index 20fe292..83e4678 100644 --- a/gui/README.md +++ b/gui/README.md @@ -1,19 +1,10 @@ # 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: +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 @@ -22,8 +13,12 @@ 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: +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 @@ -31,154 +26,128 @@ break main continue break *0x12345678 clear 1 -signal 0 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 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. +`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` | One instruction / next source line (enters calls) | +| `s`, `n` | 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 | +| `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 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. +| `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 | -## How it fits +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. -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. +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. -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. +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. -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. +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. -## Debug V8 +## Natural V8 deoptimization -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. +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 +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 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 +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. -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): +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 --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 +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 ``` -After reaching the generated-code breakpoint, import the emitted object: - -```text -symbols /tmp/elfdumpjitWork jit.js:3:170.o -``` +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. -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. +## Recording and boundaries -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. +`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. -Read-only capture and JIT source integration checks: +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. -```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 -``` +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. |
