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