summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md58
1 files changed, 57 insertions, 1 deletions
diff --git a/README.md b/README.md
index 2d94ed2..7a7c622 100644
--- a/README.md
+++ b/README.md
@@ -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