summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md24
1 files changed, 24 insertions, 0 deletions
diff --git a/README.md b/README.md
index 8ce505d..9f94bab 100644
--- a/README.md
+++ b/README.md
@@ -89,6 +89,30 @@ it back is 178 000 moments a second in order, a millisecond to any one.
Scattered writes and new bulk data are what cost: each chunk of 64 bytes
that changed is written at the next keyframe with its path in the tree.
+## Together
+
+The backends are not modes to choose between: they feed one sink. A
+program compiled by `ztrace cc`, with the agent preloaded, run under the
+debugger, gives one recording, in order: the stops and their registers
+(ptrace), the allocations (the agent), the lines, calls, stores and named
+variables (the pass).
+
+```sh
+ztrace cc -- clang -O0 targets/instr_list.c -o list
+ztrace record --by break -b push -b reverse --alloc --preload zig-out/lib/libztrace-agent.so -- ./list
+ztrace dbg --ring -- ./list # breakpoints and time travel over what the program says of itself
+ztrace show out.ztrace 40 # the thread's line and calls, the live heap, each variable's bytes
+zig build test-together
+```
+
+`--ring` (implied by `--preload` and `--alloc`) gives a target under
+ptrace the ring `ztrace run` gives it; the debugger drains it while the
+target runs and before it reports a stop. The agent's hooks and syscall
+tracing are signals, which a debugger takes first: under ptrace, use
+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.
+
## The debugger
`ztrace dbg -- PROGRAM` starts a program stopped and reads commands (from a