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