diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-10 11:32:21 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-10 12:08:27 -0300 |
| commit | 4747ea70ac0d319c8c2f33a07aee4d3ef56ac87e (patch) | |
| tree | 92fe379555a4dcbb676b309ba109d75c8e7228c2 /README.md | |
| parent | b426a8a99bcad81ecbb41d1f2a2e83738c29d8e1 (diff) | |
| download | computeranim-4747ea70ac0d319c8c2f33a07aee4d3ef56ac87e.tar.gz computeranim-4747ea70ac0d319c8c2f33a07aee4d3ef56ac87e.zip | |
README: compiled in
Co-Authored-By: Claude Fable 5.2 <[email protected]>
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 58 |
1 files changed, 57 insertions, 1 deletions
@@ -16,6 +16,7 @@ ztrace record --by line -w dist -- ./graph # ... or a source line, a global wat ztrace record --syscalls --strace -- ls / # ... or a syscall, printed as strace does ztrace dbg -- ./fib 10 # step, break, look, and go back ztrace run --preload libztrace-agent.so -- ./prog # in-process, no ptrace +ztrace cc -- clang sort.c -o sort && ztrace run -- ./sort # compiled in: lines, calls, variables, stores ztrace dump fib.ztrace ``` @@ -31,7 +32,7 @@ ztrace dump fib.ztrace | `src/trace/Debugger.zig` | on top of it: continue, step, breakpoints, hooks, watches, every stop an event | | `src/trace/Symbols.zig`, `syscalls.zig` | what an address means (modules, ELF symbols, DWARF lines); syscalls by name and shape | | `src/agent/` | the in-process backend: a library preloaded or linked into the target | -| `llvm/` | compiler instrumentation and its runtime | +| `llvm/pass.cpp`, `src/instr/` | compiler instrumentation: the LLVM pass, the runtime it calls, the type descriptions | | `src/trace/kernel*` | perf events and BPF | | `anim/` | canim, a package of its own (it needs sketchbook and pardes; ztrace does not): the animation library and its scenes | | `design/` | the visual system the animations follow, with mock frames | @@ -161,6 +162,61 @@ caller. Threads are followed, each stop is one thread's and the others run on; stepping by line in a threaded program reports the other threads' instructions too. A target that execs is not followed into the new program. +## Compiled in + +For a program built from source, `ztrace cc` runs clang with a pass plugin +(`llvm/pass.cpp`, built against the system LLVM) and links a runtime +(`src/instr/rt.zig`, `libztrace-rt.a`). The program then tells its own +story at the level of its source, names and types included: no DWARF is +read at view time. + +```sh +ztrace cc -- clang -O0 targets/instr_sort.c -o sort && ztrace run -- ./sort +ztrace cc --only 'sqlite3Btree*,*/pager.c' --mem '*Insert*' -- clang -c sqlite3.c +zig build test-llvm # fib, sorts, a list, a BFS: asserted from their recordings +zig build bench-llvm -Doptimize=ReleaseFast # the tables these numbers come from +``` + +| `--instr` | event | bytes recorded | +| --- | --- | --- | +| `lines` | `line` (file, line, column) before each new line of a block: a moment each | 31 | +| `calls` | `call` (name, site, sp, type) at entry, `ret` (name, value) at exit | 14 | +| `vars` | `variable` (address, size, name, type) per local at entry, per global at start | 15 | +| `stores` | `mem_write` with the bytes after each store; a memset or memcpy is one write | 14 | +| `loads` | `mem_read` after each load | 12 | +| `edges`, `cmps`, `cyg` | stock clang, no plugin and no names: `edge`, `cmp`, `call`/`ret` by address | 12, 13, 19 | + +The default is the first four: 44 to 63 bytes a source line executed, of +which the stores are 9 to 14 and the moment a line is 22. Stores are what +grows, so they are what to select: `--only` is where anything is +instrumented (globs on function names, source paths, file names), `--mem` +where stores and loads are, within that. The compiler's own stack +temporaries are never recorded; a write records its first 64 KiB; a local +is declared, not dumped, and a global is written once, at the start. + +- **Names.** Every file, function, variable and type is a `string` event + before it is used. The runtime numbers them when the program starts, so + an id is a byte in the recording. +- **Types.** A variable's type is a description a viewer can draw from + (`src/instr/types.zig` has the grammar and its parser): `[8]i32`, + `` *`struct node` ``, and under `types.defId("struct node")` the string + `` struct(16){value@0:i32;next@8:*`struct node`;} ``. +- **Before the optimizer** by default: every local still has an address, + every source store exists, lines come in source order, and what the + calls made observable the optimizer must keep, so `-O2` records the same + events as `-O0`. `--late` instruments what the optimizer left: the real + stores and loads, few variables. +- **Stepping.** A `line` is an event like any other, so the ring's stop + mask holds the program at each (`host.Options.stop_mask`): source-level + step with no ptrace, 1.4 million stops a second with a tracer that + polls, 290 000 with one that sleeps in between. +- **Cost.** An event is 60 to 70 ns into the ring, whatever its kind + (nearly all of it the ring's two contended cache lines), and 1.5 ns when + nobody listens. A line of these targets is a few ns of work, so with + the default selection they run 7 to 12 times slower untraced and 250 to + 400 times slower traced at `-O0`. Recording at a moment a line takes + 1.9 million events a second. + ## Depends on - [sketchbook](../sketchbook): window, drawing, shaders, hot reload, the |
