summaryrefslogtreecommitdiff
path: root/gui/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'gui/README.md')
-rw-r--r--gui/README.md241
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.