diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-10 11:08:49 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-10 11:08:49 -0300 |
| commit | 0b29354e1ddf6cf75ac4c426a00dd3435ace5069 (patch) | |
| tree | 918e6f6810a9b8b5a8ed17e698085e92018333b9 /README.md | |
| download | computeranim-0b29354e1ddf6cf75ac4c426a00dd3435ace5069.tar.gz computeranim-0b29354e1ddf6cf75ac4c426a00dd3435ace5069.zip | |
ztrace: the event, the ring, the recording, a ptrace loop
One 64-byte Event for every backend; a shared-memory ring from target to
tracer with stop/resume; a Recorder that folds events into xitdb moments
(registers, memory in 64-byte chunks with known-byte masks, strings) and a
Trace that reads any moment back; a minimal ptrace Process; ztrace record,
run and dump. Per-area build files so the areas grow apart.
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 61 |
1 files changed, 61 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..07b0571 --- /dev/null +++ b/README.md @@ -0,0 +1,61 @@ +# computeranim + +Two things that meet at a file: + +- **ztrace**, a small tracer/debugger: many ways to watch a program run, one + event format, one recording. +- **canim**, animations of what was recorded (registers, memory, syscalls, + data structures, source), written as code, exported as frames for ffmpeg. + +```sh +zig build # zig-out/bin/ztrace +zig build test # everything; test-<area> for one +ztrace record -o fib.ztrace -- ./fib 10 # under ptrace, an instruction a moment +ztrace record --syscalls -- ls / # ... or a syscall a moment +ztrace run --preload libztrace-agent.so -- ./prog # in-process, no ptrace +ztrace dump fib.ztrace +``` + +## The pieces + +| Where | What | +| --- | --- | +| `src/trace/event.zig` | `Event` (64 bytes: time, thread, kind, six words) plus a payload; `Kind`; `Regs`; `Sink` | +| `src/trace/Ring.zig` | events from the target to the tracer through shared memory; a producer can be held at a kind (`stop_mask`) until `resumeAll` | +| `src/trace/client.zig`, `host.zig` | the ring's two ends: inside the target, inside the tracer | +| `src/trace/store.zig` | `Recorder` (a `Sink`) and `Trace`: the recording, in xitdb | +| `src/trace/ptrace.zig` | the out-of-process backend | +| `src/agent/` | the in-process backend: a library preloaded or linked into the target | +| `llvm/` | compiler instrumentation and its runtime | +| `src/trace/kernel*` | perf events and BPF | +| `src/anim/`, `scenes/` | the animation library and its scenes | +| `src/cli/` | the `ztrace` command, a file a subcommand | +| `targets/` | programs to trace | +| `build/` | each area's part of the build | + +Every backend produces `Event`s into a `Sink`. The recorder is one; the ring +is another, with the recorder at its far end. + +## A recording + +An xitdb file: a history of immutable **moments**. A moment is the state +then (registers per thread, every byte of memory seen so far, the strings +defined), sharing what did not change with the moment before, and the +events that led to it. `Trace.moment(i)` is any of them, in any order: time +travel is an index. + +The recorder ends a moment at the kinds in `Recorder.cut` (by default a +step, a breakpoint, a syscall's exit, a signal, a source line, a mark), so +the cost of time travel is chosen per recording. Measured (release, this +machine): a moment costs about 10 µs and 1 KB before its own data; an +instruction-level recording of `fib(12)`, 145 000 moments, is 245 MB at +56 000 moments a second; events inside a moment cost their own bytes only. + +## Depends on + +- [sketchbook](../sketchbook): window, drawing, shaders, hot reload, the + manim-style `anim` module, frame export. +- [pardes](../02-pardes-code): tree-sitter parsing, highlighting, themes. +- [xitdb](https://github.com/xit-vcs/xitdb): the recording. + +x86-64 Linux, Zig 0.17. |
