summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 13:36:32 -0300
committerGabriel Schneider <[email protected]>2026-11-10 14:12:08 -0300
commit02aa51a6f54235cf18e627dbbfe21f21e502eb0b (patch)
treea53416bdf0e5bb0ce80da63176fe13393c502a2c /README.md
parent16895292becf82f493aaced2b10f889bad436156 (diff)
downloadcomputeranim-02aa51a6f54235cf18e627dbbfe21f21e502eb0b.tar.gz
computeranim-02aa51a6f54235cf18e627dbbfe21f21e502eb0b.zip
context: disassembly, telescopes and names in every stop; strings as one table
For a viewer to show what pwndbg's context shows, the debugger records it while the memory is there: each register and the top of the stack followed as pointers three deep (--telescope), every code address met named, eight instructions from the pc disassembled by capstone (built from source for x86, into the command only; pinned as in 03-codenomicom). zt.telescope reads a chain back with the kind of memory each link points into, and ztrace show prints the context, coloured on a terminal as pwndbg colours. The thirty thousand strings of a small run showed that a string map in each keyframe costs 700 bytes of tree a string: strings are now one table for the recording, appended a batch and read whole at open. fib(12) by instruction with everything on: 9 MB, 71 000 moments/s.
Diffstat (limited to 'README.md')
-rw-r--r--README.md36
1 files changed, 36 insertions, 0 deletions
diff --git a/README.md b/README.md
index 7ffdf28..73d6a2a 100644
--- a/README.md
+++ b/README.md
@@ -173,6 +173,41 @@ breakpoints and the debugger's own syscall stops. Strings never collide:
the pass counts its from 1, a symbol's name has its address as its id, and
every other producer uses `event.stringId`, a hash with the top bit set.
+## Context
+
+A viewer of a recording should be able to show what pwndbg's context
+shows, so the debugger records what that takes while the memory is there
+to read. At every stop it follows each register and the top sixteen words
+of the stack as pointers, three deep (`--telescope N`; 0 for not at all):
+the memory they lead to is recorded, every code address met gets a name
+(the string whose id is the address: `fib+40`, `libc.so.6!write+18`), and
+eight instructions from the pc are disassembled by capstone (strings with
+id `event.codeId(addr)`). `zt.telescope` reads it back: `chase` gives a
+value's chain, each link with the kind of memory it points into (code,
+stack, heap, data, read-only, writable-and-executable: what a pointer is
+coloured by), a name for code and a string where the chain ends on one.
+
+```
+$ ztrace record --by break -b fib -- ./fib 5 && ztrace show out.ztrace 34
+ rbp 7ffc63068910 —▸ 7ffc63068930 —▸ 7ffc63068950 —▸ 7ffc63068970 —▸ 7ffc63068990
+ r12 7ffc63068ae8 —▸ 7ffc63069f22 ◂— "/tmp/..."
+ rip 1001794 (fib+4)
+
+ ► 000001001794 push r14
+ 000001001796 push rbx
+ 000001001797 mov ebx, edi
+
+ 00:0000│ rsp 7ffc63068910 —▸ 7ffc63068930 —▸ 7ffc63068950 —▸ ...
+ 01:0008│ 7ffc63068918 —▸ 10017b8 (fib+40)
+ 02:0010│ 7ffc63068920 ◂— 3
+```
+
+What it costs, on `fib(12)` by instruction (142 000 moments): 185 000
+moments a second and 55 bytes a moment with the disassembly alone, 71 000
+and 66 bytes with the telescope. Capstone is built from source for x86
+(`build/capstone.zig`), into the command only: the library takes a
+disassembler as a function (`Debugger.disasm`) and links none.
+
## The debugger
`ztrace dbg -- PROGRAM` starts a program stopped and reads commands (from a
@@ -448,5 +483,6 @@ runs them for real: this machine's kernel in QEMU, where we are root.
manim-style `anim` module, frame export.
- [pardes](../02-pardes-code): tree-sitter parsing, highlighting, themes.
- [xitdb](https://github.com/xit-vcs/xitdb): the recording.
+- [capstone](https://github.com/capstone-engine/capstone): disassembly, in the command.
x86-64 Linux, Zig 0.17.