summaryrefslogtreecommitdiff
path: root/gui/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'gui/README.md')
-rw-r--r--gui/README.md32
1 files changed, 26 insertions, 6 deletions
diff --git a/gui/README.md b/gui/README.md
index 83e4678..b01c1aa 100644
--- a/gui/README.md
+++ b/gui/README.md
@@ -24,6 +24,7 @@ Colon opens the debugger command bar; backtick opens the renderer console.
launch /absolute/path/to/program arguments
break main
continue
+restart
break *0x12345678
clear 1
interrupt
@@ -47,6 +48,7 @@ Relative prefixes resolve against the debugger's working directory.
| --- | --- |
| `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 |
@@ -62,7 +64,8 @@ Relative prefixes resolve against the debugger's working directory.
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
+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. Manual scrolling lasts until the
next stop; an explicit address jump stays pinned until Follow is enabled.
@@ -91,14 +94,16 @@ 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 /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
+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,
@@ -112,11 +117,11 @@ 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 --trace-opt --trace-deopt --trace-deopt-verbose --print-opt-code --print-opt-code-filter=jitWork --gdbjit --gdbjit-dump --gdbjit-dump-filter=jitWork jit.js
+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 /tmp/computeranim-v8-source/src
+source-map ../../src ../../.ws/v8-debug/source/src
break v8::internal::Deoptimizer::New
break v8::internal::Runtime_NotifyDeoptimized
continue
@@ -132,6 +137,12 @@ The guard maps to JS property access line 3; the shared exit stub's own line tab
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
@@ -151,3 +162,12 @@ 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`.