diff options
Diffstat (limited to 'gui/README.md')
| -rw-r--r-- | gui/README.md | 86 |
1 files changed, 73 insertions, 13 deletions
diff --git a/gui/README.md b/gui/README.md index 3bd7d3f..20fe292 100644 --- a/gui/README.md +++ b/gui/README.md @@ -5,11 +5,12 @@ A separate native application using **ztrace** for control and recordings and a real Linux x86-64 process, stops at breakpoints, steps, and browses recorded machine state. No gdb subprocess or browser frontend. -The fixed view uses the animation library's instruction cells, operand values, -flag marks, pointer colors, telescope chains, stack roles and frame spans. -The current-instruction marker moves between rows; changed registers and stack -words strike in vermilion, cool, then retain a corner marker. Those changes are -computed from adjacent recorded moments. +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: @@ -22,7 +23,7 @@ zig build run -Doptimize=ReleaseFast -- --fresh ``` The build installs `ztrace` alongside `ztrace-gui`; keep the two together. -Backtick opens the renderer's console: +Colon opens the debugger command bar; backtick opens the renderer's console: ```text launch /absolute/path/to/program arguments @@ -34,15 +35,39 @@ 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. F5 toggles continue/pause, F10 steps one instruction, -F11 steps to another source line (one instruction when source is unavailable). -The corresponding buttons work with the mouse. Left/right browse recorded -moments; End returns to the latest stop. Browsing history does not rewind the -process. Continuing returns the view to live state. Source stepping can stay in -a loop on one source line; F5 interrupts it. +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 @@ -93,7 +118,7 @@ For the deterministic JIT fixture: 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. F10 steps through that machine code. Addresses change on each launch. +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 @@ -122,3 +147,38 @@ 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 +``` |
