summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--build/agent.zig119
-rw-r--r--include/ztrace.h37
-rw-r--r--src/agent/agent.zig164
-rw-r--r--src/agent/check.zig263
-rw-r--r--src/agent/hook.zig150
-rw-r--r--src/agent/lib.zig212
-rw-r--r--src/agent/signal.zig116
-rw-r--r--src/agent/sud.zig129
-rw-r--r--src/agent/symbols.zig158
-rw-r--r--src/agent/watch.zig130
-rw-r--r--src/cli/run.zig208
-rw-r--r--targets/agent_api.c22
-rw-r--r--targets/agent_fib.c15
-rw-r--r--targets/agent_list.c46
-rw-r--r--targets/agent_sort.c22
-rw-r--r--targets/agent_sys.c57
-rw-r--r--targets/agent_zig.zig20
17 files changed, 1850 insertions, 18 deletions
diff --git a/build/agent.zig b/build/agent.zig
index d3c7eb3..bdb9317 100644
--- a/build/agent.zig
+++ b/build/agent.zig
@@ -1,5 +1,122 @@
+//! The in-process agent: the library in its two forms, the header, and
+//! real targets recorded through it.
+const std = @import("std");
const Ctx = @import("../build.zig").Ctx;
+const Compile = std.Build.Step.Compile;
pub fn add(ctx: Ctx) void {
- _ = ctx;
+ const b = ctx.b;
+ const imports: []const std.Build.Module.Import = &.{.{ .name = "ztrace", .module = ctx.ztrace }};
+
+ // For Zig programs: the agent compiled in.
+ const module = b.addModule("ztrace-agent", .{ .root_source_file = b.path("src/agent/agent.zig"), .target = ctx.target, .optimize = ctx.optimize, .imports = imports });
+ // `ztrace run` reads its child with the code the agent reads itself with.
+ ctx.exe.root_module.addImport("ztrace-agent", module);
+
+ // For everything else: libztrace-agent.so to preload, libztrace-agent.a to link in.
+ var libs: [2]*Compile = undefined;
+ for (&libs, [_]std.builtin.LinkMode{ .dynamic, .static }) |*lib, linkage| {
+ // LLVM always: the agent has inline assembly the self-hosted backend does not take.
+ lib.* = b.addLibrary(.{ .name = "ztrace-agent", .linkage = linkage, .use_llvm = true, .root_module = b.createModule(.{
+ .root_source_file = b.path("src/agent/lib.zig"),
+ .target = ctx.target,
+ .optimize = ctx.optimize,
+ .imports = imports,
+ .pic = true,
+ }) });
+ b.installArtifact(lib.*);
+ }
+ b.getInstallStep().dependOn(&b.addInstallHeaderFile(b.path("include/ztrace.h"), "ztrace.h").step);
+
+ const t: Tests = .{
+ .ctx = ctx,
+ .step = ctx.areaTest("test-agent", "The in-process agent on real targets"),
+ .preload = libs[0],
+ .check = b.addExecutable(.{ .name = "agent-check", .root_module = b.createModule(.{ .root_source_file = b.path("src/agent/check.zig"), .target = ctx.target, .optimize = ctx.optimize, .imports = imports }) }),
+ };
+ t.step.dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = module, .use_llvm = true })).step);
+
+ // Programs that know nothing of the tracer, with the agent preloaded.
+ const list = ctx.cTarget("agent_list", &.{"agent_list.c"});
+ const fib = ctx.cTarget("agent_fib", &.{"agent_fib.c"});
+ const sort = ctx.cTarget("agent_sort", &.{"agent_sort.c"});
+ const sys = ctx.cTarget("agent_sys", &.{"agent_sys.c"});
+ for ([_]*Compile{ list, fib, sort, sys }) |exe| b.installArtifact(exe);
+ t.expect("list", "100", t.record(list, true, &.{"--alloc"}, &.{"100"}));
+ t.expect("fib", "10", t.record(fib, true, &.{ "--hook", "fib" }, &.{"10"}));
+ t.expect("sort", "numbers", t.record(sort, true, &.{ "--hook", "swap", "--watch", "numbers" }, &.{}));
+ t.expect("syscalls", "", t.record(sys, true, &.{"--syscalls"}, &.{}));
+ // Everything at once.
+ t.expect("list", "100", t.record(list, true, &.{ "--alloc", "--syscalls", "--hook", "main", "--watch", "stdout" }, &.{"100"}));
+
+ // Stops: the target held at each return of swap while the tracer reads the array from outside.
+ t.expect("sort", "numbers", t.record(sort, true, &.{ "--hook", "swap", "--stop-at", "ret", "--read", "numbers" }, &.{}));
+ const asked = t.record(fib, true, &.{ "--hook", "fib", "--stop-at", "call", "-i" }, &.{"3"}).run;
+ asked.setStdIn(.{ .bytes = "s\n\nx 8 4\nc\n" });
+ asked.expectStdOutMatch("call tid=");
+ asked.expectStdOutMatch("not readable");
+ asked.expectStdOutMatch("fib(3) = 2");
+
+ // With no tracer the preloaded agent is not there.
+ const alone = b.addSystemCommand(&.{"env"});
+ alone.addPrefixedArtifactArg("LD_PRELOAD=", libs[0]);
+ alone.addArtifactArg(list);
+ alone.expectStdOutEqual("sum 4950 of 100\n");
+ t.step.dependOn(&alone.step);
+
+ // Programs that annotate themselves, with the agent linked in: against
+ // glibc, statically against musl, and as a module of a Zig program.
+ const api = ctx.cTarget("agent_api", &.{"agent_api.c"});
+ const musl = b.resolveTargetQuery(.{ .cpu_arch = ctx.target.result.cpu.arch, .os_tag = .linux, .abi = .musl });
+ const api_static_module = b.createModule(.{ .target = musl, .optimize = .Debug, .link_libc = true });
+ api_static_module.addCSourceFiles(.{ .root = b.path("targets"), .files = &.{"agent_api.c"}, .flags = &.{ "-O1", "-g" } });
+ const api_static = b.addExecutable(.{ .name = "agent_api_static", .root_module = api_static_module, .linkage = .static });
+ for ([_]*Compile{ api, api_static }) |exe| {
+ exe.root_module.addIncludePath(b.path("include"));
+ exe.root_module.linkLibrary(libs[1]);
+ t.expect("api", "", t.record(exe, false, &.{}, &.{}));
+ }
+ const api_zig = ctx.zigTarget("agent_zig", "targets/agent_zig.zig");
+ api_zig.root_module.addImport("ztrace-agent", module);
+ api_zig.use_llvm = true;
+ t.expect("api", "", t.record(api_zig, false, &.{}, &.{}));
+ for ([_]*Compile{ api, api_static, api_zig }) |exe| b.installArtifact(exe);
}
+
+const Recording = struct { run: *std.Build.Step.Run, file: std.Build.LazyPath };
+
+const Tests = struct {
+ ctx: Ctx,
+ step: *std.Build.Step,
+ preload: *Compile,
+ check: *Compile,
+
+ /// `ztrace run OPTIONS -- TARGET ARGS`, which has to end with the target's exit 0.
+ fn record(t: Tests, target: *Compile, preload: bool, options: []const []const u8, args: []const []const u8) Recording {
+ const run = t.ctx.b.addRunArtifact(t.ctx.exe);
+ run.addArgs(&.{ "run", "-o" });
+ const file = run.addOutputFileArg("agent.ztrace");
+ if (preload) {
+ run.addArg("--preload");
+ run.addArtifactArg(t.preload);
+ }
+ run.addArgs(options);
+ run.addArg("--");
+ run.addArtifactArg(target);
+ run.addArgs(args);
+ run.expectStdErrMatch("(0 dropped)");
+ run.expectStdErrMatch("exit 0");
+ t.step.dependOn(&run.step);
+ return .{ .run = run, .file = file };
+ }
+
+ /// The recording `run` made holds what `scenario` says (src/agent/check.zig).
+ fn expect(t: Tests, scenario: []const u8, argument: []const u8, recording: Recording) void {
+ const check = t.ctx.b.addRunArtifact(t.check);
+ check.addArg(scenario);
+ check.addFileArg(recording.file);
+ check.addArg(argument);
+ check.expectExitCode(0);
+ t.step.dependOn(&check.step);
+ }
+};
diff --git a/include/ztrace.h b/include/ztrace.h
new file mode 100644
index 0000000..d507809
--- /dev/null
+++ b/include/ztrace.h
@@ -0,0 +1,37 @@
+/* ztrace: what a traced program can say about itself.
+ *
+ * Link libztrace-agent.a (or libztrace-agent.so) and run the program under
+ * `ztrace run`. Run without a tracer, these do nothing.
+ *
+ * A statically linked agent sees the allocator and thread creation when the
+ * program is linked with:
+ * -Wl,--wrap=malloc,--wrap=calloc,--wrap=realloc,--wrap=free
+ * -Wl,--wrap=posix_memalign,--wrap=aligned_alloc,--wrap=memalign
+ * -Wl,--wrap=pthread_create,--wrap=fork
+ */
+#ifndef ZTRACE_H
+#define ZTRACE_H
+
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* A point in the run worth a moment of the recording: a `mark` event. */
+void ztrace_mark(const char *label, uint64_t value);
+
+/* Names `len` bytes at `ptr` (a `variable` event), records them, and keeps
+ * recording what changes in them: only the bytes that changed, at each event
+ * that ends a moment. The memory must stay mapped. */
+void ztrace_watch(const void *ptr, size_t len, const char *name);
+
+/* Records `len` bytes at `ptr` as they are now, once. */
+void ztrace_snapshot(const void *ptr, size_t len);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif
diff --git a/src/agent/agent.zig b/src/agent/agent.zig
new file mode 100644
index 0000000..ecf2768
--- /dev/null
+++ b/src/agent/agent.zig
@@ -0,0 +1,164 @@
+//! The in-process backend: code that lives inside the target, preloaded
+//! (libztrace-agent.so), linked in (libztrace-agent.a), or imported by a Zig
+//! program (this module). When the process starts it attaches the ring its
+//! tracer handed it and turns on what `ztrace run` asked for through
+//! ZTRACE_* variables; with no ring it does nothing.
+//!
+//! Raw syscalls only, no libc, no allocation: this code runs inside malloc
+//! and inside signal handlers.
+const std = @import("std");
+const linux = std.os.linux;
+const zt = @import("ztrace");
+const client = zt.client;
+const Kind = zt.Kind;
+pub const symbols = @import("symbols.zig");
+pub const signal = @import("signal.zig");
+pub const sud = @import("sud.zig");
+pub const hook = @import("hook.zig");
+pub const regions = @import("watch.zig");
+
+/// Null when nothing traces the process: every entry point returns at once.
+pub var ring: ?*zt.Ring = null;
+/// `alloc` and `free` events wanted (the library's interposed malloc asks).
+pub var allocations = false;
+/// The kinds that end a moment in the recording (ZTRACE_CUT): watched memory
+/// is brought up to date before each.
+var cut: u64 = 0;
+/// 0 not started, 1 starting, 2 started.
+var state: std.atomic.Value(u8) = .init(0);
+threadlocal var started = false;
+
+/// The most bytes an event of ours carries; more is cut short, or split.
+pub const max_payload = 1024;
+
+/// Every entry point comes through here first. A Zig program that wants its
+/// hooks and syscalls from the start calls it at the top of main; for the
+/// rest the library has a constructor.
+pub fn init() void {
+ if (state.load(.acquire) != 0 or state.cmpxchgStrong(0, 1, .acquire, .monotonic) != null) return;
+ defer state.store(2, .release);
+ const r = client.get() orelse return;
+ var buf: [1 << 16]u8 = undefined;
+ const env = client.environ(&buf);
+ cut = if (client.getenv(env, "ZTRACE_CUT")) |v| std.fmt.parseInt(u64, v, 0) catch 0 else 0;
+ ring = r;
+
+ var maps = symbols.Maps.open(null) orelse return;
+ while (maps.next()) |m| emit(.map, 0, .{ m.start, m.end - m.start, m.prot, m.offset, 0, 0 }, text(m.path));
+ maps.close();
+ threadStart();
+
+ if (client.getenv(env, "ZTRACE_WATCH")) |list| {
+ var specs = std.mem.tokenizeScalar(u8, list, ',');
+ while (specs.next()) |spec| {
+ const region = symbols.find(null, spec) orelse symbols.Symbol{ .addr = 0, .size = 0 };
+ if (region.size != 0) watch(@as([*]const u8, @ptrFromInt(region.addr))[0..region.size], spec) else unknown(spec);
+ }
+ }
+ if (client.getenv(env, "ZTRACE_HOOKS")) |list| {
+ var specs = std.mem.tokenizeScalar(u8, list, ',');
+ while (specs.next()) |spec| {
+ if (symbols.find(null, spec)) |function| hook.add(function.addr) else unknown(spec);
+ }
+ }
+ allocations = client.getenv(env, "ZTRACE_ALLOC") != null;
+ if (client.getenv(env, "ZTRACE_SYSCALLS") != null) {
+ sud.enable();
+ sud.selector = sud.block;
+ }
+}
+
+/// The user asked for something that is not there: say so where they will see it.
+fn unknown(spec: []const u8) void {
+ for ([_][]const u8{ "ztrace agent: nothing called ", spec, "\n" }) |part| _ = linux.write(2, part.ptr, part.len);
+}
+
+pub fn threadId() u32 {
+ return client.threadId();
+}
+
+/// The calling thread's first sign of life. Once per thread, whoever notices it first.
+pub fn threadStart() void {
+ if (started) return;
+ started = true;
+ emit(.thread_start, 0, .{ threadId(), 0, 0, 0, 0, 0 }, "");
+ sud.arm();
+}
+
+/// In a forked child, which remembers being its parent.
+pub fn forked() void {
+ const tid: u32 = @intCast(linux.gettid());
+ if (tid == client.tid) return;
+ client.tid = tid;
+ started = false;
+ threadStart();
+}
+
+pub fn emit(kind: Kind, aux: u16, a: [6]u64, payload: []const u8) void {
+ const r = ring orelse return;
+ // What the agent does to get an event out (a futex when the ring is
+ // full, or to wake the tracer) is not the target's doing.
+ const was = sud.selector;
+ sud.selector = sud.allow;
+ defer sud.selector = was;
+ if (cut & kind.bit() != 0) regions.diff();
+ r.emit(.{ .ts = zt.event.now(), .tid = threadId(), .kind = kind, .aux = aux, .a = a }, payload);
+}
+
+/// A string's id is its hash: no backend needs to ask another which are taken.
+pub fn stringId(string: []const u8) u64 {
+ return std.hash.Wyhash.hash(0, string);
+}
+
+/// `bytes` as a payload: cut to `max_payload`, and never the length of
+/// `Regs`, which the recorder would take for registers.
+pub fn text(bytes: []const u8) []const u8 {
+ const len = @min(bytes.len, max_payload);
+ return bytes[0 .. len - @intFromBool(len == @sizeOf(zt.Regs))];
+}
+
+/// `mem_write` events: `bytes` is what is at `addr` now.
+pub fn write(addr: u64, bytes: []const u8) void {
+ var at: usize = 0;
+ while (at < bytes.len) : (at += max_payload) {
+ const part = bytes[at..@min(bytes.len, at + max_payload)];
+ emit(.mem_write, 0, .{ addr + at, part.len, 0, 0, 0, 0 }, part);
+ }
+}
+
+// The target's side: what a program that links the agent calls. The same
+// three are in include/ztrace.h for C.
+
+/// A point in the run worth a moment: a `mark` event with a text and a value.
+pub fn mark(label: []const u8, value: u64) void {
+ init();
+ emit(.mark, 0, .{ value, 0, 0, 0, 0, 0 }, text(label));
+}
+
+/// Names `memory` (a `variable` event), records it, and keeps recording what
+/// changes in it: only the bytes that changed, before each event that ends a
+/// moment. It must stay mapped. Watched from inside a hooked call, it is
+/// forgotten when that call returns.
+pub fn watch(memory: []const u8, name: []const u8) void {
+ init();
+ if (ring == null) return;
+ const was = sud.selector;
+ sud.selector = sud.allow;
+ defer sud.selector = was;
+ const id = stringId(name);
+ emit(.string, 0, .{ id, 0, 0, 0, 0, 0 }, text(name));
+ emit(.variable, 0, .{ @intFromPtr(memory.ptr), memory.len, id, 0, 0, 0 }, "");
+ write(@intFromPtr(memory.ptr), memory);
+ regions.add(memory, threadId(), hook.open());
+}
+
+/// Records `memory` as it is now, once.
+pub fn snapshot(memory: []const u8) void {
+ init();
+ write(@intFromPtr(memory.ptr), memory);
+}
+
+test {
+ _ = symbols;
+ _ = regions;
+}
diff --git a/src/agent/check.zig b/src/agent/check.zig
new file mode 100644
index 0000000..1a972f0
--- /dev/null
+++ b/src/agent/check.zig
@@ -0,0 +1,263 @@
+//! The agent's tests: what a recording made through it has to contain.
+//! `zig build test-agent` records real targets under `ztrace run` and runs
+//! this on each recording: `check SCENARIO FILE [ARGUMENT]`.
+const std = @import("std");
+const zt = @import("ztrace");
+const expect = std.testing.expect;
+const expectEqual = std.testing.expectEqual;
+const expectEqualStrings = std.testing.expectEqualStrings;
+
+const Item = struct { moment: u64, ev: zt.Event, payload: []const u8 };
+
+const Recording = struct {
+ arena: std.mem.Allocator,
+ trace: *zt.Trace,
+ items: []const Item,
+
+ fn count(r: Recording, kind: zt.Kind) usize {
+ var n: usize = 0;
+ for (r.items) |item| n += @intFromBool(item.ev.kind == kind);
+ return n;
+ }
+
+ /// The address ranges of the file whose path ends in `name`.
+ fn mapped(r: Recording, name: []const u8) ![]const [2]u64 {
+ var ranges: std.ArrayList([2]u64) = .empty;
+ for (r.items) |item| {
+ if (item.ev.kind == .map and std.mem.endsWith(u8, item.payload, name)) try ranges.append(r.arena, .{ item.ev.a[0], item.ev.a[0] + item.ev.a[1] });
+ }
+ return ranges.items;
+ }
+
+ /// The `variable` event of the variable called `name`.
+ fn variable(r: Recording, name: []const u8) !Item {
+ var id: ?u64 = null;
+ for (r.items) |item| {
+ if (item.ev.kind == .string and std.mem.eql(u8, item.payload, name)) id = item.ev.a[0];
+ if (item.ev.kind == .variable and item.ev.a[2] == id) return item;
+ }
+ return error.NoSuchVariable;
+ }
+
+ /// The 16 numbers the sorting targets sort, as recorded at `moment`.
+ fn numbers(r: Recording, moment: u64, addr: u64) ![16]i32 {
+ var out: [16]i32 = undefined;
+ var known: [64]bool = undefined;
+ try (try r.trace.moment(moment)).read(addr, std.mem.asBytes(&out), &known);
+ try expect(std.mem.allEqual(bool, &known, true));
+ return out;
+ }
+};
+
+fn within(ranges: []const [2]u64, addr: u64) bool {
+ for (ranges) |range| {
+ if (addr >= range[0] and addr < range[1]) return true;
+ }
+ return false;
+}
+
+fn fib(n: u64) u64 {
+ return if (n < 2) n else fib(n - 1) + fib(n - 2);
+}
+
+pub fn main(init: std.process.Init) !void {
+ const arena = init.arena.allocator();
+ const args = try init.minimal.args.toSlice(arena);
+ if (args.len < 3) return error.Usage;
+ var trace = try zt.Trace.open(init.gpa, init.io, args[2]);
+ defer trace.close();
+ var items: std.ArrayList(Item) = .empty;
+ for (0..trace.len) |index| {
+ var events = try (try trace.moment(index)).events(arena);
+ while (events.next()) |item| try items.append(arena, .{ .moment = index, .ev = item.ev, .payload = item.payload });
+ }
+ const r: Recording = .{ .arena = arena, .trace = &trace, .items = items.items };
+ const argument: []const u8 = if (args.len > 3) args[3] else "";
+
+ // Whatever was asked for, the agent says where things are and who runs.
+ try expect(r.count(.map) >= 3);
+ try expect(r.count(.thread_start) >= 1);
+
+ const scenario = args[1];
+ if (std.mem.eql(u8, scenario, "list")) {
+ try list(r, try std.fmt.parseInt(usize, argument, 10));
+ } else if (std.mem.eql(u8, scenario, "fib")) {
+ try calls(r, try std.fmt.parseInt(u64, argument, 10));
+ } else if (std.mem.eql(u8, scenario, "sort")) {
+ try sorted(r, argument);
+ } else if (std.mem.eql(u8, scenario, "api")) {
+ try annotated(r);
+ } else if (std.mem.eql(u8, scenario, "syscalls")) {
+ try syscalls(r);
+ } else return error.NoSuchScenario;
+}
+
+/// agent_list N: N nodes allocated and freed, and nothing the program
+/// allocated left alive.
+fn list(r: Recording, n: usize) !void {
+ const program = try r.mapped("agent_list");
+ try expect(program.len > 0);
+ const Block = struct { size: u64, pc: u64 };
+ var live: std.AutoHashMapUnmanaged(u64, Block) = .empty;
+ var nodes: usize = 0;
+ var own: usize = 0;
+ var resized: usize = 0;
+ for (r.items) |item| switch (item.ev.kind) {
+ .alloc => {
+ const ptr = item.ev.a[0];
+ const pc = item.ev.a[2];
+ const how: zt.event.Alloc = @enumFromInt(item.ev.aux);
+ // Only a realloc in place may name a pointer that is alive.
+ if (live.contains(ptr)) {
+ try expectEqual(zt.event.Alloc.realloc, how);
+ resized += 1;
+ }
+ try live.put(r.arena, ptr, .{ .size = item.ev.a[1], .pc = pc });
+ if (!within(program, pc)) continue;
+ own += 1;
+ if (how == .malloc and item.ev.a[1] == 16) nodes += 1;
+ },
+ .free => {
+ // What was allocated before the agent attached is not ours to know.
+ const block = live.fetchRemove(item.ev.a[0]) orelse continue;
+ if (within(program, block.value.pc)) try expect(within(program, item.ev.a[1]));
+ },
+ else => {},
+ };
+ try expectEqual(n, nodes);
+ // The nodes, the vector, the two aligned blocks, and the vector again each time it grew.
+ try expect(own >= n + 3 + resized);
+ var left = live.valueIterator();
+ while (left.next()) |block| try expect(!within(program, block.pc));
+}
+
+/// agent_fib N hooked at fib: every call with its argument, every return
+/// with fib of that argument, each a moment.
+fn calls(r: Recording, n: u64) !void {
+ var stack: std.ArrayList(u64) = .empty;
+ var seen: u64 = 0;
+ var last_moment: ?u64 = null;
+ for (r.items) |item| switch (item.ev.kind) {
+ .call => {
+ const regs = std.mem.bytesToValue(zt.Regs, item.payload);
+ try expectEqual(item.ev.a[0], regs.rip);
+ try expectEqual(item.ev.a[2], regs.rsp);
+ if (stack.items.len == 0) try expectEqual(n, regs.rdi) else try expect(regs.rdi + 1 == stack.getLast() or regs.rdi + 2 == stack.getLast());
+ try stack.append(r.arena, regs.rdi);
+ seen += 1;
+ try expect(last_moment == null or item.moment > last_moment.?);
+ last_moment = item.moment;
+ // The recorder folded the registers into the moment the call ends.
+ try expectEqual(regs.rdi, (try (try r.trace.moment(item.moment)).regs(item.ev.tid)).?.rdi);
+ },
+ .ret => {
+ try expectEqual(fib(stack.pop().?), item.ev.a[1]);
+ try expect(item.moment > last_moment.?);
+ last_moment = item.moment;
+ },
+ else => {},
+ };
+ try expectEqual(@as(usize, 0), stack.items.len);
+ try expectEqual(2 * fib(n + 1) - 1, seen);
+}
+
+/// A sorting target: the variable `name` is a permutation of 0..15 at every
+/// moment, changes along the way, and ends sorted.
+fn sorted(r: Recording, name: []const u8) !void {
+ const variable = try r.variable(name);
+ try expectEqual(@as(u64, 64), variable.ev.a[1]);
+ var before = try r.numbers(variable.moment, variable.ev.a[0]);
+ var states: usize = 1;
+ for (variable.moment..r.trace.len) |moment| {
+ const now = try r.numbers(moment, variable.ev.a[0]);
+ var present: u16 = 0;
+ for (now) |v| present |= @as(u16, 1) << @intCast(v);
+ try expectEqual(@as(u16, 0xffff), present);
+ states += @intFromBool(!std.mem.eql(i32, &now, &before));
+ before = now;
+ }
+ try expect(states >= 8);
+ try expect(std.sort.isSorted(i32, &before, {}, std.sort.asc(i32)));
+}
+
+/// agent_api: a mark after each insertion, by when the prefix up to it is
+/// sorted in the recording; the snapshot of the checksum; the array sorted
+/// at the end.
+fn annotated(r: Recording) !void {
+ const variable = try r.variable("numbers");
+ var next: u64 = 1;
+ var checksum: ?u64 = null;
+ for (r.items) |item| switch (item.ev.kind) {
+ .mark => if (std.mem.eql(u8, item.payload, "inserted")) {
+ try expectEqual(next, item.ev.a[0]);
+ const now = try r.numbers(item.moment, variable.ev.a[0]);
+ try expect(std.sort.isSorted(i32, now[0 .. next + 1], {}, std.sort.asc(i32)));
+ next += 1;
+ } else {
+ try expectEqualStrings("done", item.payload);
+ try expectEqual(checksum.?, item.ev.a[0]);
+ },
+ // The snapshot: 8 bytes that are not in the array.
+ .mem_write => if (item.ev.a[1] == 8 and item.ev.a[0] -% variable.ev.a[0] >= 64) {
+ checksum = std.mem.readInt(u64, item.payload[0..8], .little);
+ },
+ else => {},
+ };
+ try expectEqual(@as(u64, 16), next);
+ try sorted(r, "numbers");
+}
+
+/// agent_sys: what it wrote, from which thread, and every syscall entered
+/// is left, innermost first.
+fn syscalls(r: Recording) !void {
+ const main_tid = for (r.items) |item| {
+ if (item.ev.kind == .thread_start) break item.ev.tid;
+ } else unreachable;
+ var open: std.AutoHashMapUnmanaged(u32, std.ArrayList(Item)) = .empty;
+ var written: std.AutoArrayHashMapUnmanaged(u32, std.ArrayList(u8)) = .empty;
+ var fd: ?u64 = null;
+ for (r.items) |item| switch (item.ev.kind) {
+ .thread_start => try expectEqual(@as(u64, item.ev.tid), item.ev.a[0]),
+ .syscall_enter => {
+ const stack = try open.getOrPutValue(r.arena, item.ev.tid, .empty);
+ try stack.value_ptr.append(r.arena, item);
+ },
+ .syscall_exit => {
+ const result = item.ev.a[0];
+ const enter = (if (open.getPtr(item.ev.tid)) |stack| stack.pop() else null) orelse {
+ // A forked child's first event is its side of the parent's clone.
+ try expectEqual(@intFromEnum(std.os.linux.SYS.clone), item.ev.aux);
+ try expectEqual(@as(u64, 0), result);
+ continue;
+ };
+ try expectEqual(enter.ev.aux, item.ev.aux);
+ switch (@as(std.os.linux.SYS, @enumFromInt(item.ev.aux))) {
+ .openat => if (std.mem.eql(u8, enter.payload, "/dev/null")) {
+ fd = result;
+ },
+ .write => if (enter.ev.a[0] == fd) {
+ try expectEqual(enter.ev.a[2], result);
+ try expectEqual(result, enter.payload.len);
+ const text = try written.getOrPutValue(r.arena, item.ev.tid, .empty);
+ try text.value_ptr.appendSlice(r.arena, enter.payload);
+ },
+ .getpid => try expectEqual(@as(u64, main_tid), result),
+ else => {},
+ }
+ },
+ else => {},
+ };
+ // Only a thread's last syscall has no exit.
+ var stacks = open.valueIterator();
+ while (stacks.next()) |stack| {
+ if (stack.items.len == 0) continue;
+ try expectEqual(@as(usize, 1), stack.items.len);
+ const last: std.os.linux.SYS = @enumFromInt(stack.items[0].ev.aux);
+ try expect(last == .exit or last == .exit_group);
+ }
+ try expectEqual(@as(usize, 3), r.count(.thread_start));
+ try expectEqual(@as(usize, 3), written.count());
+ try expectEqualStrings("hello from main\nmasked\nsignal\nchild exited 3\n", written.get(main_tid).?.items);
+ try expectEqualStrings("thread\n", written.values()[1].items);
+ try expectEqualStrings("child\n", written.values()[2].items);
+}
diff --git a/src/agent/hook.zig b/src/agent/hook.zig
new file mode 100644
index 0000000..d11ddbd
--- /dev/null
+++ b/src/agent/hook.zig
@@ -0,0 +1,150 @@
+//! Function hooks: `call` and `ret` events for chosen functions, with the
+//! registers at entry (the first six integer arguments among them) and the
+//! return value.
+//!
+//! Entry is a breakpoint: the function's first byte becomes int3, and the
+//! SIGTRAP handler runs here, in the target, with every register in hand. It
+//! needs no instruction decoding, so it works on any function, whatever its
+//! prologue. The handler then lets the replaced instruction run: emulated
+//! when it is `push %rbp` or `endbr64` (how compiled functions start), else
+//! the byte is put back for a single step. Return needs no trap: the entry
+//! handler swaps the return address on the stack for `returned`, which emits
+//! the event and jumps to the real one.
+//!
+//! shortcut: a signal per call, about a microsecond. For hooks on hot
+//! functions, copy the prologue to a trampoline and patch a jump in (this
+//! needs an x86-64 instruction-length decoder, to move whole instructions and
+//! fix their rip-relative operands).
+const std = @import("std");
+const linux = std.os.linux;
+const agent = @import("agent.zig");
+const signal = @import("signal.zig");
+const sud = @import("sud.zig");
+const watch = @import("watch.zig");
+
+const Hook = struct { addr: usize, first: [4]u8 };
+var hooks: [64]Hook = undefined;
+var count: usize = 0;
+
+/// A hooked call that has not returned: where its return address lives, and
+/// the real one.
+const Frame = struct { slot: usize, ret: usize, callee: usize };
+// shortcut: calls nested deeper than this are not reported; grow the stack on demand if a target recurses further.
+threadlocal var frames: [1024]Frame = @splat(.{ .slot = 0, .ret = 0, .callee = 0 });
+threadlocal var depth: u32 = 0;
+
+/// Hooked calls the calling thread has open.
+pub fn open() u32 {
+ return depth;
+}
+
+/// `addr` must be a function's first instruction, and nothing may jump back
+/// to it from inside the function.
+pub fn add(addr: usize) void {
+ if (count == hooks.len) return;
+ for (hooks[0..count]) |h| {
+ if (h.addr == addr) return;
+ }
+ listen();
+ // Left writable: a single step puts the first byte back for a moment.
+ const page = addr & ~@as(usize, 4095);
+ if (linux.errno(linux.mprotect(@ptrFromInt(page), 4096, .{ .READ = true, .WRITE = true, .EXEC = true })) != .SUCCESS) return;
+ const code: *[4]u8 = @ptrFromInt(addr);
+ hooks[count] = .{ .addr = addr, .first = code.* };
+ count += 1;
+ code[0] = 0xcc;
+}
+
+var listening = false;
+
+/// SIGTRAP is the agent's from here on: breakpoints, and single steps (its own and sud.zig's).
+pub fn listen() void {
+ if (!listening) signal.install(.TRAP, onTrap);
+ listening = true;
+}
+
+fn onTrap(_: i32, info: *const linux.siginfo_t, uc: *signal.Ucontext) callconv(.c) void {
+ const TRAP_TRACE = 2;
+ if (info.code == TRAP_TRACE) {
+ // A single step ended: over a hooked function's first instruction,
+ // or over a syscall the dispatcher let through.
+ for (hooks[0..count]) |h| @as(*u8, @ptrFromInt(h.addr)).* = 0xcc;
+ uc.eflags &= ~@as(u64, signal.trap_flag);
+ sud.stepped(uc);
+ return;
+ }
+ const hook = for (hooks[0..count]) |*h| {
+ if (h.addr == uc.rip - 1) break h;
+ } else {
+ // A breakpoint of the target's own: again, without us.
+ signal.install(.TRAP, null);
+ uc.rip -= 1;
+ return;
+ };
+ uc.rip = hook.addr;
+ if (depth < frames.len) {
+ const slot: *usize = @ptrFromInt(uc.rsp);
+ agent.emit(.call, 0, .{ hook.addr, slot.*, uc.rsp, 0, 0, 0 }, std.mem.asBytes(&uc.regs()));
+ frames[depth] = .{ .slot = uc.rsp, .ret = slot.*, .callee = hook.addr };
+ depth += 1;
+ slot.* = @intFromPtr(&returned);
+ }
+ if (hook.first[0] == 0x55) {
+ // push %rbp
+ uc.rsp -= 8;
+ @as(*u64, @ptrFromInt(uc.rsp)).* = uc.rbp;
+ uc.rip += 1;
+ } else if (std.mem.eql(u8, &hook.first, &.{ 0xf3, 0x0f, 0x1e, 0xfa })) {
+ // endbr64: nothing to do while indirect-branch tracking is off, as it is in user space.
+ uc.rip += 4;
+ } else {
+ // shortcut: while the byte is back another thread can enter unseen; a relocated copy of the instruction would close that.
+ @as(*u8, @ptrFromInt(hook.addr)).* = hook.first[0];
+ uc.eflags |= signal.trap_flag;
+ }
+}
+
+/// Where a hooked function returns to, in place of its caller. rax and rdx
+/// and xmm0 and xmm1 hold what it returns: kept. (A 256-bit return value
+/// would lose its upper half to the code called here.)
+fn returned() callconv(.naked) void {
+ asm volatile (
+ \\ pushq %%rax
+ \\ pushq %%rax
+ \\ pushq %%rdx
+ \\ subq $40, %%rsp
+ \\ movdqu %%xmm0, (%%rsp)
+ \\ movdqu %%xmm1, 16(%%rsp)
+ \\ movq %%rax, %%rdi
+ \\ leaq 64(%%rsp), %%rsi
+ \\ callq %[onReturn:P]
+ \\ movq %%rax, 56(%%rsp)
+ \\ movdqu (%%rsp), %%xmm0
+ \\ movdqu 16(%%rsp), %%xmm1
+ \\ addq $40, %%rsp
+ \\ popq %%rdx
+ \\ popq %%rax
+ \\ retq
+ :
+ : [onReturn] "X" (&onReturn),
+ );
+}
+
+/// `sp` is the stack pointer the function returned with. Returns where it
+/// meant to return to.
+fn onReturn(value: u64, sp: usize) callconv(.c) usize {
+ const was = sud.selector;
+ sud.selector = sud.allow;
+ defer sud.selector = was;
+ while (true) {
+ depth -= 1;
+ const frame = frames[depth];
+ // Frames below `sp` were left without returning (longjmp): they end here too.
+ const ours = frame.slot + 8 == sp or depth == 0;
+ agent.emit(.ret, 0, .{ frame.callee, if (ours) value else 0, 0, 0, 0, 0 }, "");
+ if (ours) {
+ watch.drop(agent.threadId(), depth);
+ return frame.ret;
+ }
+ }
+}
diff --git a/src/agent/lib.zig b/src/agent/lib.zig
new file mode 100644
index 0000000..c497cf4
--- /dev/null
+++ b/src/agent/lib.zig
@@ -0,0 +1,212 @@
+//! The agent as a library for programs that have a libc: the C side of the
+//! target's API (include/ztrace.h), and the libc functions it stands in
+//! front of: the allocator (`alloc` and `free` events with the caller's pc),
+//! pthread_create (`thread_start`, `thread_exit`) and fork.
+//!
+//! Preloaded, the library's `malloc` shadows libc's and finds it with
+//! dlsym(RTLD_NEXT). Linked in statically nothing can shadow libc, so the
+//! target is linked with `-Wl,--wrap=malloc` (and so on): its calls then go
+//! to `__wrap_malloc` here, which calls `__real_malloc`.
+const std = @import("std");
+const builtin = @import("builtin");
+const zt = @import("ztrace");
+const agent = @import("agent.zig");
+
+const preloaded = builtin.link_mode == .dynamic;
+
+/// A failed check says so and ends the process: no stack traces, no std I/O,
+/// from inside somebody else's program.
+pub const panic = std.debug.FullPanic(struct {
+ fn panic(message: []const u8, _: ?usize) noreturn {
+ @branchHint(.cold);
+ const linux = std.os.linux;
+ _ = linux.write(2, "ztrace agent: ", 14);
+ _ = linux.write(2, message.ptr, message.len);
+ _ = linux.write(2, "\n", 1);
+ linux.exit_group(134);
+ }
+}.panic);
+
+/// Runs when the program is loaded, before main.
+export const ztrace_agent_init linksection(".init_array") = [1]*const fn () callconv(.c) void{loaded};
+
+fn loaded() callconv(.c) void {
+ agent.init();
+}
+
+export fn ztrace_mark(label: [*:0]const u8, value: u64) void {
+ agent.mark(std.mem.span(label), value);
+}
+
+export fn ztrace_watch(ptr: [*]const u8, len: usize, name: [*:0]const u8) void {
+ agent.watch(ptr[0..len], std.mem.span(name));
+}
+
+export fn ztrace_snapshot(ptr: [*]const u8, len: usize) void {
+ agent.snapshot(ptr[0..len]);
+}
+
+const Start = *const fn (?*anyopaque) callconv(.c) ?*anyopaque;
+
+/// libc's own, by name.
+const Real = struct {
+ malloc: ?*const fn (usize) callconv(.c) ?*anyopaque,
+ calloc: ?*const fn (usize, usize) callconv(.c) ?*anyopaque,
+ realloc: ?*const fn (?*anyopaque, usize) callconv(.c) ?*anyopaque,
+ free: ?*const fn (?*anyopaque) callconv(.c) void,
+ posix_memalign: ?*const fn (*?*anyopaque, usize, usize) callconv(.c) c_int,
+ aligned_alloc: ?*const fn (usize, usize) callconv(.c) ?*anyopaque,
+ memalign: ?*const fn (usize, usize) callconv(.c) ?*anyopaque,
+ pthread_create: ?*const fn (*anyopaque, ?*const anyopaque, Start, ?*anyopaque) callconv(.c) c_int,
+ fork: ?*const fn () callconv(.c) c_int,
+};
+var real: Real = undefined;
+/// 0 not looked up, 1 looking up, 2 found.
+var found: std.atomic.Value(u8) = .init(0);
+
+/// False while the lookup itself is running: dlsym allocates, and lands here.
+fn ready() bool {
+ if (found.load(.acquire) == 2) return true;
+ if (found.cmpxchgStrong(0, 1, .acquire, .monotonic) != null) return false;
+ inline for (@typeInfo(Real).@"struct".field_names) |name| {
+ const T = @FieldType(Real, name);
+ @field(real, name) = if (preloaded) real: {
+ const dlsym = @extern(?*const fn (?*anyopaque, [*:0]const u8) callconv(.c) ?*anyopaque, .{ .name = "dlsym", .linkage = .weak }) orelse break :real null;
+ const RTLD_NEXT: ?*anyopaque = @ptrFromInt(std.math.maxInt(usize));
+ break :real @ptrCast(dlsym(RTLD_NEXT, name));
+ } else @extern(T, .{ .name = "__real_" ++ name, .linkage = .weak });
+ }
+ found.store(2, .release);
+ // The first call into libc that comes through us may come before the constructor.
+ agent.init();
+ return true;
+}
+
+/// Memory for the allocations made while the lookup runs. Never reused, so
+/// always zero; each block is preceded by its size.
+var early: [1 << 16]u8 align(16) = @splat(0);
+var early_used: std.atomic.Value(usize) = .init(0);
+
+fn earlyAlloc(size: usize, alignment: usize) ?*anyopaque {
+ const step = @max(alignment, 16);
+ const need = step + 16 + std.mem.alignForward(usize, size, 16);
+ const at = early_used.fetchAdd(need, .monotonic);
+ if (at + need > early.len) return null;
+ const block = std.mem.alignForward(usize, @intFromPtr(&early) + at + 16, step);
+ @as(*usize, @ptrFromInt(block - 16)).* = size;
+ return @ptrFromInt(block);
+}
+
+fn isEarly(p: ?*anyopaque) bool {
+ return @intFromPtr(p) -% @intFromPtr(&early) < early.len;
+}
+
+fn allocated(how: zt.event.Alloc, p: ?*anyopaque, size: usize, pc: usize) void {
+ if (agent.allocations and p != null) agent.emit(.alloc, @intFromEnum(how), .{ @intFromPtr(p), size, pc, 0, 0, 0 }, "");
+}
+
+fn freed(p: ?*anyopaque, pc: usize) void {
+ if (agent.allocations) agent.emit(.free, 0, .{ @intFromPtr(p), pc, 0, 0, 0, 0 }, "");
+}
+
+const interposed = struct {
+ fn malloc(size: usize) callconv(.c) ?*anyopaque {
+ if (!ready()) return earlyAlloc(size, 16);
+ const p = real.malloc.?(size);
+ allocated(.malloc, p, size, @returnAddress());
+ return p;
+ }
+
+ fn calloc(n: usize, size: usize) callconv(.c) ?*anyopaque {
+ if (!ready()) return earlyAlloc(n *| size, 16);
+ const p = real.calloc.?(n, size);
+ allocated(.calloc, p, n *| size, @returnAddress());
+ return p;
+ }
+
+ fn realloc(old: ?*anyopaque, size: usize) callconv(.c) ?*anyopaque {
+ if (!ready() or isEarly(old)) {
+ // An early block cannot grow in place: a new one, with its bytes.
+ const p: [*]u8 = @ptrCast((if (ready()) real.malloc.?(size) else earlyAlloc(size, 16)) orelse return null);
+ if (old) |o| {
+ const had = @as(*const usize, @ptrFromInt(@intFromPtr(o) - 16)).*;
+ @memcpy(p[0..@min(had, size)], @as([*]const u8, @ptrCast(o)));
+ }
+ return p;
+ }
+ const p = real.realloc.?(old, size);
+ // One that moved is a free and an alloc; one in place, an alloc at the same pointer.
+ if (old != null and p != old and (p != null or size == 0)) freed(old, @returnAddress());
+ allocated(.realloc, p, size, @returnAddress());
+ return p;
+ }
+
+ fn free(p: ?*anyopaque) callconv(.c) void {
+ if (p == null or isEarly(p) or !ready()) return;
+ // Before it is free: once it is, another thread's alloc may be given the same pointer.
+ freed(p, @returnAddress());
+ real.free.?(p);
+ }
+
+ fn posix_memalign(out: *?*anyopaque, alignment: usize, size: usize) callconv(.c) c_int {
+ if (!ready()) {
+ out.* = earlyAlloc(size, alignment) orelse return @intFromEnum(std.os.linux.E.NOMEM);
+ return 0;
+ }
+ const rc = real.posix_memalign.?(out, alignment, size);
+ if (rc == 0) allocated(.memalign, out.*, size, @returnAddress());
+ return rc;
+ }
+
+ fn aligned_alloc(alignment: usize, size: usize) callconv(.c) ?*anyopaque {
+ if (!ready()) return earlyAlloc(size, alignment);
+ const p = real.aligned_alloc.?(alignment, size);
+ allocated(.memalign, p, size, @returnAddress());
+ return p;
+ }
+
+ fn memalign(alignment: usize, size: usize) callconv(.c) ?*anyopaque {
+ if (!ready()) return earlyAlloc(size, alignment);
+ const p = real.memalign.?(alignment, size);
+ allocated(.memalign, p, size, @returnAddress());
+ return p;
+ }
+
+ fn pthread_create(thread: *anyopaque, attr: ?*const anyopaque, start: Start, arg: ?*anyopaque) callconv(.c) c_int {
+ _ = ready();
+ if (agent.ring == null) return real.pthread_create.?(thread, attr, start, arg);
+ // The new thread runs `threadMain`, which needs to know what it was meant to run.
+ const box: *Box = @ptrCast(@alignCast(real.malloc.?(@sizeOf(Box)) orelse return @intFromEnum(std.os.linux.E.AGAIN)));
+ box.* = .{ .start = start, .arg = arg };
+ const rc = real.pthread_create.?(thread, attr, threadMain, box);
+ if (rc != 0) real.free.?(box);
+ return rc;
+ }
+
+ fn fork() callconv(.c) c_int {
+ _ = ready();
+ const pid = real.fork.?();
+ if (pid == 0 and agent.ring != null) agent.forked();
+ return pid;
+ }
+};
+
+const Box = struct { start: Start, arg: ?*anyopaque };
+
+fn threadMain(arg: ?*anyopaque) callconv(.c) ?*anyopaque {
+ const box: *Box = @ptrCast(@alignCast(arg));
+ const run = box.*;
+ real.free.?(box);
+ agent.threadStart();
+ agent.sud.selector = agent.sud.resting;
+ const result = run.start(run.arg);
+ // shortcut: a thread that ends in pthread_exit or is cancelled does not come back here; hook the exit path if a target's threads end that way.
+ agent.emit(.thread_exit, 0, @splat(0), "");
+ return result;
+}
+
+comptime {
+ for (@typeInfo(Real).@"struct".field_names) |name| {
+ @export(&@field(interposed, name), .{ .name = (if (preloaded) "" else "__wrap_") ++ name });
+ }
+}
diff --git a/src/agent/signal.zig b/src/agent/signal.zig
new file mode 100644
index 0000000..99aead0
--- /dev/null
+++ b/src/agent/signal.zig
@@ -0,0 +1,116 @@
+//! What the agent's signal handlers share: the frame the kernel pushes on
+//! x86-64, and handlers installed with the raw syscall, behind libc's back.
+const std = @import("std");
+const linux = std.os.linux;
+const zt = @import("ztrace");
+
+/// The kernel's `struct ucontext`: the interrupted thread's registers, which
+/// a handler may change before they are restored.
+pub const Ucontext = extern struct {
+ flags: u64,
+ link: ?*Ucontext,
+ stack: extern struct { sp: usize, flags: i32, size: usize },
+ r8: u64,
+ r9: u64,
+ r10: u64,
+ r11: u64,
+ r12: u64,
+ r13: u64,
+ r14: u64,
+ r15: u64,
+ rdi: u64,
+ rsi: u64,
+ rbp: u64,
+ rbx: u64,
+ rdx: u64,
+ rax: u64,
+ rcx: u64,
+ rsp: u64,
+ rip: u64,
+ eflags: u64,
+ cs: u16,
+ gs: u16,
+ fs: u16,
+ ss: u16,
+ err: u64,
+ trapno: u64,
+ oldmask: u64,
+ cr2: u64,
+ fpstate: usize,
+ reserved: [8]u64,
+ sigmask: u64,
+
+ comptime {
+ std.debug.assert(@offsetOf(Ucontext, "sigmask") == 296);
+ }
+
+ pub fn regs(uc: *const Ucontext) zt.Regs {
+ var out: zt.Regs = .{ .orig_rax = uc.rax, .cs = uc.cs, .ss = uc.ss, .fs = uc.fs, .gs = uc.gs };
+ inline for (zt.Regs.names) |name| @field(out, name) = @field(uc, name);
+ return out;
+ }
+};
+
+/// The trap flag: one instruction, then SIGTRAP.
+pub const trap_flag = 0x100;
+
+/// The bit of a signal in a kernel signal set.
+pub fn bit(sig: linux.SIG) u64 {
+ return @as(u64, 1) << @intCast(@intFromEnum(sig) - 1);
+}
+
+// The gate: the only syscall instructions the dispatcher (sud.zig) lets
+// through whatever the selector says. One symbol after the other, so that
+// the range between the first and the last is these and nothing else.
+comptime {
+ asm (
+ \\ .pushsection .text.ztrace_gate, "ax", @progbits
+ \\ .globl ztrace_gate_sigreturn, ztrace_gate_restorer, ztrace_gate_syscall, ztrace_gate_end
+ \\ .hidden ztrace_gate_sigreturn, ztrace_gate_restorer, ztrace_gate_syscall, ztrace_gate_end
+ \\ ztrace_gate_sigreturn:
+ \\ movq %rdi, %rsp
+ \\ ztrace_gate_restorer:
+ \\ movl $15, %eax
+ \\ syscall
+ \\ ztrace_gate_syscall:
+ \\ movq %rdi, %rax
+ \\ movq %rsi, %rdi
+ \\ movq %rdx, %rsi
+ \\ movq %rcx, %rdx
+ \\ movq %r8, %r10
+ \\ movq %r9, %r8
+ \\ movq 8(%rsp), %r9
+ \\ syscall
+ \\ retq
+ \\ ztrace_gate_end:
+ \\ .popsection
+ );
+}
+
+/// rt_sigreturn from the signal frame whose `Ucontext` is at `uc`.
+pub extern fn ztrace_gate_sigreturn(uc: u64) callconv(.c) noreturn;
+/// The same for a handler that returns: its stack pointer is there already.
+extern fn ztrace_gate_restorer() callconv(.c) void;
+/// Any syscall, by number.
+pub extern fn ztrace_gate_syscall(number: u64, a0: u64, a1: u64, a2: u64, a3: u64, a4: u64, a5: u64) callconv(.c) u64;
+extern const ztrace_gate_end: u8;
+
+/// Where the gate is: start and length.
+pub fn gate() [2]usize {
+ return .{ @intFromPtr(&ztrace_gate_sigreturn), @intFromPtr(&ztrace_gate_end) - @intFromPtr(&ztrace_gate_sigreturn) };
+}
+
+pub const Handler = *const fn (i32, *const linux.siginfo_t, *Ucontext) callconv(.c) void;
+
+/// Null puts the default action back. The handler runs with no signal
+/// blocked, its own included: inside it the thread is still the target, with
+/// the target's mask.
+pub fn install(sig: linux.SIG, handler: ?Handler) void {
+ const act: linux.k_sigaction = .{
+ .handler = @ptrCast(handler),
+ .flags = linux.SA.SIGINFO | linux.SA.RESTORER | linux.SA.NODEFER,
+ .restorer = @ptrCast(&ztrace_gate_restorer),
+ .mask = linux.sigemptyset(),
+ };
+ _ = linux.syscall4(.rt_sigaction, @intFromEnum(sig), @intFromPtr(&act), 0, @sizeOf(linux.sigset_t));
+}
diff --git a/src/agent/sud.zig b/src/agent/sud.zig
new file mode 100644
index 0000000..e556df3
--- /dev/null
+++ b/src/agent/sud.zig
@@ -0,0 +1,129 @@
+//! Syscalls without ptrace: Syscall User Dispatch. The kernel turns every
+//! syscall the thread makes into SIGSYS; the handler runs here, in the
+//! target, emits `syscall_enter` (with the path or the bytes written, read
+//! straight from memory), makes the syscall itself, emits `syscall_exit`
+//! and returns the result. No context switch to a tracer: two signal frames
+//! a syscall.
+//!
+//! The agent's own syscalls pass because the selector byte says so while its
+//! code runs. The target's syscall itself is made with the selector back on
+//! `block`, through the gate (signal.zig), the range of code the kernel
+//! always lets through: a signal that interrupts it runs the target's handler
+//! as the target's code, its syscalls seen like any other.
+const std = @import("std");
+const linux = std.os.linux;
+const zt = @import("ztrace");
+const agent = @import("agent.zig");
+const signal = @import("signal.zig");
+
+pub const allow: u8 = 0;
+pub const block: u8 = 1;
+/// The kernel reads this at each of the thread's syscalls: `block` while the
+/// target's code runs, `allow` while the agent's does.
+pub threadlocal var selector: u8 = allow;
+/// What the target's code runs with: `block` once syscalls are traced.
+pub var resting: u8 = allow;
+/// 1 + the syscall this thread is making natively, under a single step.
+threadlocal var passing: u64 = 0;
+
+/// Signals the target may neither block nor take over: the kernel kills a
+/// process whose forced signal is blocked.
+const ours = signal.bit(.SYS) | signal.bit(.TRAP);
+
+fn nr(comptime name: linux.SYS) u64 {
+ return @intFromEnum(name);
+}
+
+pub fn enable() void {
+ signal.install(.SYS, onSyscall);
+ // Syscalls let through natively are stepped over: hook.zig's handler calls `stepped`.
+ @import("hook.zig").listen();
+ resting = block;
+ arm();
+}
+
+/// Dispatch on for the calling thread: the kernel keeps it per thread, and a
+/// clone starts without it.
+pub fn arm() void {
+ if (resting == allow) return;
+ const PR_SET_SYSCALL_USER_DISPATCH = 59;
+ const PR_SYS_DISPATCH_ON = 1;
+ const gate = signal.gate();
+ _ = linux.prctl(PR_SET_SYSCALL_USER_DISPATCH, PR_SYS_DISPATCH_ON, gate[0], gate[1], @intFromPtr(&selector));
+}
+
+fn onSyscall(_: i32, _: *const linux.siginfo_t, uc: *signal.Ucontext) callconv(.c) void {
+ selector = allow;
+ const number = uc.rax;
+ var a = [6]u64{ uc.rdi, uc.rsi, uc.rdx, uc.r10, uc.r8, uc.r9 };
+ if (number == nr(.rt_sigreturn)) {
+ // The target leaves a handler of its own: its frame is where its
+ // stack pointer is, and ours, pushed below, goes with it.
+ selector = block;
+ signal.ztrace_gate_sigreturn(uc.rsp);
+ }
+ agent.emit(.syscall_enter, @truncate(number), a, argument(number, a));
+ if (number == nr(.clone3) or number == nr(.vfork) or (number == nr(.clone) and a[0] & linux.CLONE.VM != 0)) {
+ // The child starts on another stack, or shares this one: not from
+ // inside a handler. Back onto the syscall instruction with dispatch
+ // off and one step to go; `stepped` turns it on again.
+ passing = number + 1;
+ uc.rip -= 2;
+ uc.eflags |= signal.trap_flag;
+ return;
+ }
+ var act: linux.k_sigaction = undefined;
+ var faked = false;
+ if (number == nr(.rt_sigaction) and a[1] != 0) {
+ // shortcut: the target is told its handler for one of our signals is installed, and it is not; chain to it when a target needs SIGTRAP or SIGSYS itself.
+ faked = a[0] == @intFromEnum(linux.SIG.SYS) or a[0] == @intFromEnum(linux.SIG.TRAP);
+ act = @as(*const linux.k_sigaction, @ptrFromInt(a[1])).*;
+ act.mask[0] &= ~ours;
+ a[1] = @intFromPtr(&act);
+ }
+ selector = block;
+ const result = if (faked) 0 else signal.ztrace_gate_syscall(number, a[0], a[1], a[2], a[3], a[4], a[5]);
+ selector = allow;
+ if (number == nr(.rt_sigprocmask)) {
+ // The mask it set is this handler's; the target's is the one the frame restores.
+ _ = linux.sigprocmask(linux.SIG.BLOCK, null, @ptrCast(&uc.sigmask));
+ uc.sigmask &= ~ours;
+ }
+ // A forked child.
+ if (result == 0 and (number == nr(.fork) or number == nr(.clone))) agent.forked();
+ agent.emit(.syscall_exit, @truncate(number), .{ result, 0, 0, 0, 0, 0 }, "");
+ uc.rax = result;
+ selector = block;
+}
+
+/// A single step ended (hook.zig's SIGTRAP handler): if it was over a syscall
+/// let through, here is its exit, in the parent and in a new thread both.
+pub fn stepped(uc: *const signal.Ucontext) void {
+ if (resting == allow) return;
+ agent.threadStart();
+ if (passing != 0) {
+ // shortcut: the step may end one instruction after the syscall, which could have changed rax; none of libc's do.
+ agent.emit(.syscall_exit, @truncate(passing - 1), .{ uc.rax, 0, 0, 0, 0, 0 }, "");
+ passing = 0;
+ }
+ selector = block;
+}
+
+/// What a syscall's pointer argument points at, for the event's payload.
+// shortcut: read without checking; a pointer the kernel would refuse with EFAULT faults here instead.
+fn argument(number: u64, a: [6]u64) []const u8 {
+ return switch (number) {
+ nr(.open), nr(.stat), nr(.lstat), nr(.access), nr(.execve), nr(.chdir), nr(.unlink), nr(.readlink), nr(.mkdir), nr(.rmdir), nr(.truncate), nr(.chmod) => string(a[0]),
+ nr(.openat), nr(.newfstatat), nr(.unlinkat), nr(.readlinkat), nr(.faccessat), nr(.faccessat2), nr(.statx), nr(.mkdirat), nr(.execveat) => string(a[1]),
+ nr(.write), nr(.pwrite64), nr(.sendto) => if (a[1] == 0) "" else agent.text(@as([*]const u8, @ptrFromInt(a[1]))[0..a[2]]),
+ else => "",
+ };
+}
+
+fn string(addr: u64) []const u8 {
+ if (addr == 0) return "";
+ const s: [*]const u8 = @ptrFromInt(addr);
+ var len: usize = 0;
+ while (len < agent.max_payload and s[len] != 0) len += 1;
+ return agent.text(s[0..len]);
+}
diff --git a/src/agent/symbols.zig b/src/agent/symbols.zig
new file mode 100644
index 0000000..6504ff6
--- /dev/null
+++ b/src/agent/symbols.zig
@@ -0,0 +1,158 @@
+//! Where things are in a process: its mappings (/proc/PID/maps) and the
+//! symbols of the ELF files mapped there. Raw syscalls and no allocation:
+//! the agent runs this on itself at startup, the tracer on its child.
+const std = @import("std");
+const linux = std.os.linux;
+const Elf = std.elf.Elf64;
+
+pub const Map = struct {
+ start: u64,
+ end: u64,
+ /// PROT_READ 1, PROT_WRITE 2, PROT_EXEC 4.
+ prot: u32,
+ offset: u64,
+ /// Empty for anonymous memory. Valid until the next `next`.
+ path: []const u8,
+};
+
+pub const Maps = struct {
+ fd: linux.fd_t,
+ buf: [8192]u8 = undefined,
+ len: usize = 0,
+ at: usize = 0,
+
+ /// `pid` null: this process.
+ pub fn open(pid: ?linux.pid_t) ?Maps {
+ var name: [32]u8 = undefined;
+ const path: [*:0]const u8 = if (pid) |p| @ptrCast(std.fmt.bufPrint(&name, "/proc/{d}/maps\x00", .{p}) catch unreachable) else "/proc/self/maps";
+ const rc = linux.open(path, .{}, 0);
+ return if (linux.errno(rc) == .SUCCESS) .{ .fd = @intCast(rc) } else null;
+ }
+
+ pub fn close(m: *Maps) void {
+ _ = linux.close(m.fd);
+ }
+
+ pub fn next(m: *Maps) ?Map {
+ while (true) {
+ if (std.mem.indexOfScalarPos(u8, m.buf[0..m.len], m.at, '\n')) |end| {
+ const line = m.buf[m.at..end];
+ m.at = end + 1;
+ return parse(line) orelse continue;
+ }
+ // No whole line left: keep the rest and read more.
+ std.mem.copyForwards(u8, &m.buf, m.buf[m.at..m.len]);
+ m.len -= m.at;
+ m.at = 0;
+ const n = linux.read(m.fd, m.buf[m.len..].ptr, m.buf.len - m.len);
+ if (linux.errno(n) != .SUCCESS or n == 0) return null;
+ m.len += n;
+ }
+ }
+
+ /// "55d0c0a00000-55d0c0a01000 r-xp 00001000 08:02 1234 /usr/bin/true"
+ fn parse(line: []const u8) ?Map {
+ var it = std.mem.tokenizeScalar(u8, line, ' ');
+ const range = it.next() orelse return null;
+ const perms = it.next() orelse return null;
+ const offset = it.next() orelse return null;
+ _ = it.next(); // device
+ _ = it.next(); // inode
+ const dash = std.mem.indexOfScalar(u8, range, '-') orelse return null;
+ if (perms.len < 3) return null;
+ return .{
+ .start = std.fmt.parseInt(u64, range[0..dash], 16) catch return null,
+ .end = std.fmt.parseInt(u64, range[dash + 1 ..], 16) catch return null,
+ .prot = @as(u32, @intFromBool(perms[0] == 'r')) | @as(u32, @intFromBool(perms[1] == 'w')) << 1 | @as(u32, @intFromBool(perms[2] == 'x')) << 2,
+ .offset = std.fmt.parseInt(u64, offset, 16) catch return null,
+ .path = it.rest(),
+ };
+ }
+};
+
+pub const Symbol = struct { addr: u64, size: u64 };
+
+/// The function or object called `name` in the first file mapped in `pid`
+/// (null: this process) that has one, lowest address first: the executable
+/// before its libraries. Static symbols count when the file is not stripped.
+pub fn lookup(pid: ?linux.pid_t, name: []const u8) ?Symbol {
+ var maps = Maps.open(pid) orelse return null;
+ defer maps.close();
+ while (maps.next()) |m| {
+ // A file's first mapping starts at its ELF header.
+ if (m.offset != 0 or m.path.len == 0 or m.path[0] != '/') continue;
+ if (inFile(m.path, m.start, name)) |symbol| return symbol;
+ }
+ return null;
+}
+
+/// What "ADDR", "ADDR:LEN" or a symbol's name stands for in `pid`.
+pub fn find(pid: ?linux.pid_t, spec: []const u8) ?Symbol {
+ if (spec.len == 0 or !std.ascii.isDigit(spec[0])) return lookup(pid, spec);
+ const colon = std.mem.indexOfScalar(u8, spec, ':') orelse spec.len;
+ return .{
+ .addr = std.fmt.parseInt(u64, spec[0..colon], 0) catch return null,
+ .size = if (colon == spec.len) 0 else std.fmt.parseInt(u64, spec[colon + 1 ..], 0) catch return null,
+ };
+}
+
+fn inFile(path: []const u8, base: u64, name: []const u8) ?Symbol {
+ var path_z: [4097]u8 = undefined;
+ if (path.len >= path_z.len) return null;
+ @memcpy(path_z[0..path.len], path);
+ path_z[path.len] = 0;
+ const rc = linux.open(@ptrCast(&path_z), .{}, 0);
+ if (linux.errno(rc) != .SUCCESS) return null;
+ const fd: linux.fd_t = @intCast(rc);
+ const size: usize = @intCast(linux.lseek(fd, 0, linux.SEEK.END));
+ const mapped = linux.mmap(null, size, .{ .READ = true }, .{ .TYPE = .PRIVATE }, fd, 0);
+ _ = linux.close(fd);
+ if (linux.errno(mapped) != .SUCCESS) return null;
+ defer _ = linux.munmap(@ptrFromInt(mapped), size);
+ const file = @as([*]const u8, @ptrFromInt(mapped))[0..size];
+
+ if (size < @sizeOf(Elf.Ehdr) or !std.mem.eql(u8, file[0..5], "\x7fELF\x02")) return null;
+ const ehdr: *align(1) const Elf.Ehdr = @ptrCast(file.ptr);
+ const phdrs = table(Elf.Phdr, file, ehdr.phoff, ehdr.phnum) orelse return null;
+ const shdrs = table(Elf.Shdr, file, ehdr.shoff, ehdr.shnum) orelse return null;
+
+ // `base` is where the lowest loaded page of the file went.
+ var low: u64 = std.math.maxInt(u64);
+ for (phdrs) |ph| {
+ if (ph.type == .LOAD) low = @min(low, ph.vaddr & ~@as(u64, 4095));
+ }
+ for (shdrs) |sh| {
+ if (sh.type != .SYMTAB and sh.type != .DYNSYM) continue;
+ if (sh.link >= shdrs.len) continue;
+ const syms = table(Elf.Sym, file, sh.offset, sh.size / @sizeOf(Elf.Sym)) orelse continue;
+ const names = table(u8, file, shdrs[sh.link].offset, shdrs[sh.link].size) orelse continue;
+ for (syms) |sym| {
+ if (sym.shndx == 0 or sym.name >= names.len) continue;
+ switch (sym.info.type) {
+ .FUNC, .OBJECT, .NOTYPE => {},
+ else => continue,
+ }
+ const rest = names[sym.name..];
+ if (rest.len > name.len and rest[name.len] == 0 and std.mem.startsWith(u8, rest, name)) return .{ .addr = sym.value -% low +% base, .size = sym.size };
+ }
+ }
+ return null;
+}
+
+fn table(comptime T: type, file: []const u8, offset: u64, count: u64) ?[]align(1) const T {
+ if (offset > file.len or count > (file.len - offset) / @sizeOf(T)) return null;
+ return @as([*]align(1) const T, @ptrCast(file.ptr + offset))[0..count];
+}
+
+test "this process's mappings and a symbol of its executable" {
+ var maps = Maps.open(null).?;
+ defer maps.close();
+ const here = @intFromPtr(&inFile);
+ var found = false;
+ while (maps.next()) |m| {
+ if (here >= m.start and here < m.end) found = m.prot & 4 != 0 and m.path.len > 0;
+ }
+ try std.testing.expect(found);
+ try std.testing.expect(lookup(null, "no such symbol anywhere") == null);
+ try std.testing.expectEqual(Symbol{ .addr = 0x1000, .size = 64 }, find(null, "0x1000:64").?);
+}
diff --git a/src/agent/watch.zig b/src/agent/watch.zig
new file mode 100644
index 0000000..356dac8
--- /dev/null
+++ b/src/agent/watch.zig
@@ -0,0 +1,130 @@
+//! Watched memory: regions whose changes become `mem_write` events. Each
+//! region has a shadow copy in the agent's own memory; `diff` compares the
+//! two and emits the runs that changed. Plain memory compares in the target's
+//! own address space: no syscall, no page protection, any granularity. The
+//! agent calls `diff` before every event that ends a moment, so a moment's
+//! memory is what the target had when that event happened.
+const std = @import("std");
+const linux = std.os.linux;
+const agent = @import("agent.zig");
+
+const Region = struct {
+ addr: usize,
+ len: usize,
+ shadow: [*]u8,
+ /// The thread that asked, and how many hooked calls it had open: the
+ /// region is forgotten when that call returns, as the recorder forgets
+ /// its `variable`. Depth 0 lives forever.
+ tid: u32,
+ depth: u32,
+};
+
+// shortcut: 64 regions, each compared whole at every moment; when a target
+// watches megabytes, find the dirty pages first (PAGEMAP_SCAN) and compare those.
+var table: [64]Region = undefined;
+var count: usize = 0;
+var busy: std.atomic.Value(bool) = .init(false);
+
+/// The memory must stay mapped for as long as it is watched.
+pub fn add(memory: []const u8, tid: u32, depth: u32) void {
+ if (memory.len == 0) return;
+ const shadow = linux.mmap(null, memory.len, .{ .READ = true, .WRITE = true }, .{ .TYPE = .PRIVATE, .ANONYMOUS = true }, -1, 0);
+ if (linux.errno(shadow) != .SUCCESS) return;
+ while (busy.swap(true, .acquire)) std.atomic.spinLoopHint();
+ defer busy.store(false, .release);
+ if (count == table.len) {
+ _ = linux.munmap(@ptrFromInt(shadow), memory.len);
+ return;
+ }
+ table[count] = .{ .addr = @intFromPtr(memory.ptr), .len = memory.len, .shadow = @ptrFromInt(shadow), .tid = tid, .depth = depth };
+ @memcpy(table[count].shadow, memory);
+ count += 1;
+}
+
+/// Forgets what `tid` watched from inside calls deeper than `depth`.
+pub fn drop(tid: u32, depth: u32) void {
+ if (count == 0) return;
+ while (busy.swap(true, .acquire)) std.atomic.spinLoopHint();
+ defer busy.store(false, .release);
+ var i: usize = 0;
+ while (i < count) {
+ const r = table[i];
+ if (r.tid != tid or r.depth <= depth) {
+ i += 1;
+ continue;
+ }
+ _ = linux.munmap(r.shadow, r.len);
+ count -= 1;
+ table[i] = table[count];
+ }
+}
+
+/// Emits what changed in every region since the last time.
+pub fn diff() void {
+ if (count == 0) return;
+ // Busy: another thread is at it, or this one is, below this frame.
+ if (busy.swap(true, .acquire)) return;
+ defer busy.store(false, .release);
+ for (table[0..count]) |r| {
+ var changes: Changes = .{ .old = r.shadow[0..r.len], .new = @as([*]const u8, @ptrFromInt(r.addr))[0..r.len] };
+ while (changes.next()) |run| agent.write(r.addr + run.at, run.bytes);
+ }
+}
+
+/// The runs of bytes where `new` differs from `old`, each brought into `old`
+/// as it is returned. Changes less than 8 bytes apart travel as one run.
+pub const Changes = struct {
+ old: []u8,
+ new: []const u8,
+ at: usize = 0,
+
+ pub const Run = struct { at: usize, bytes: []const u8 };
+
+ pub fn next(c: *Changes) ?Run {
+ const from = c.at + same(c.old[c.at..], c.new[c.at..]);
+ if (from == c.new.len) {
+ c.at = from;
+ return null;
+ }
+ var to = from + 1;
+ var i = to;
+ while (i < c.new.len and i - to < 8) : (i += 1) {
+ if (c.old[i] != c.new[i]) to = i + 1;
+ }
+ @memcpy(c.old[from..to], c.new[from..to]);
+ c.at = to;
+ // From the copy: the target may be writing there right now.
+ return .{ .at = from, .bytes = c.old[from..to] };
+ }
+
+ /// How many bytes at the start of `a` and `b` are equal.
+ fn same(a: []const u8, b: []const u8) usize {
+ const V = @Vector(32, u8);
+ var i: usize = 0;
+ while (i + 32 <= a.len) : (i += 32) {
+ const differ: u32 = @bitCast(@as(V, a[i..][0..32].*) != @as(V, b[i..][0..32].*));
+ if (differ != 0) return i + @ctz(differ);
+ }
+ while (i < a.len and a[i] == b[i]) i += 1;
+ return i;
+ }
+};
+
+test "changes are found as runs and folded into the old copy" {
+ var old: [200]u8 = @splat(0);
+ var new: [200]u8 = @splat(0);
+ new[3] = 1;
+ new[9] = 2; // 5 equal bytes after the first: one run
+ new[100] = 3;
+ new[199] = 4;
+ var changes: Changes = .{ .old = &old, .new = &new };
+ const a = changes.next().?;
+ try std.testing.expectEqual(@as(usize, 3), a.at);
+ try std.testing.expectEqualSlices(u8, &.{ 1, 0, 0, 0, 0, 0, 2 }, a.bytes);
+ try std.testing.expectEqual(@as(usize, 100), changes.next().?.at);
+ try std.testing.expectEqual(@as(usize, 199), changes.next().?.at);
+ try std.testing.expect(changes.next() == null);
+ try std.testing.expectEqualSlices(u8, &new, &old);
+ changes.at = 0;
+ try std.testing.expect(changes.next() == null);
+}
diff --git a/src/cli/run.zig b/src/cli/run.zig
index c4f1b25..2483a21 100644
--- a/src/cli/run.zig
+++ b/src/cli/run.zig
@@ -1,17 +1,42 @@
//! ztrace run: a program that carries a ring producer (the preloaded agent,
-//! or instrumentation linked in), recorded at full speed, no ptrace.
+//! or instrumentation linked in), recorded at full speed, no ptrace. The
+//! agent's capabilities are chosen here and reach it through ZTRACE_*
+//! variables; stops are the ring's (`stop_mask`), not the kernel's.
const std = @import("std");
+const linux = std.os.linux;
const zt = @import("ztrace");
+const agent = @import("ztrace-agent");
const util = @import("util.zig");
const fail = util.fail;
pub const usage =
- \\usage: ztrace run [-o FILE] [--preload LIB] [--ring BYTES] -- PROGRAM [ARGS]
+ \\usage: ztrace run [-o FILE] [--preload LIB] [--ring BYTES] [OPTIONS] -- PROGRAM [ARGS]
\\
\\Runs PROGRAM with a shared-memory ring in its environment and records
- \\what it emits (default out.ztrace). --preload puts a library (the agent)
- \\into it with LD_PRELOAD. --ring sizes the ring (a power of two, default
- \\16 MiB).
+ \\what it emits (default out.ztrace). --preload puts a library (the agent,
+ \\libztrace-agent.so) into it with LD_PRELOAD. --ring sizes the ring (a
+ \\power of two, default 16 MiB).
+ \\
+ \\What the agent records, preloaded or linked into PROGRAM:
+ \\ --alloc malloc, free and their family: alloc, free
+ \\ --syscalls every syscall, with paths and written bytes:
+ \\ syscall_enter, syscall_exit
+ \\ --hook SYM|ADDR a function's entry (with registers) and return
+ \\ (with its value): call, ret
+ \\ --watch SYM|ADDR:LEN memory: the bytes that changed in it, before each
+ \\ event that ends a moment
+ \\--hook and --watch repeat, or take a comma-separated list.
+ \\
+ \\ --cut KIND,... the kinds that end a moment (default: the
+ \\ recorder's, and call and ret)
+ \\
+ \\Stops, with the target otherwise at full speed:
+ \\ --stop-at KIND,... hold the target at each event of these kinds
+ \\ until the tracer is done with it
+ \\ --read SYM|ADDR:LEN at each stop read this memory from outside and
+ \\ record what changed (repeats)
+ \\ -i at each stop ask what next: s (step to the next
+ \\ stop), c (continue to the end), x ADDR [LEN], q
\\
;
@@ -19,34 +44,76 @@ pub fn run(init: std.process.Init, args: []const [:0]const u8) !void {
const arena = init.arena.allocator();
var out: []const u8 = "out.ztrace";
var options: zt.host.Options = .{};
+ var env: std.ArrayList(?[*:0]const u8) = .empty;
+ var hooks: []const u8 = "";
+ var watches: []const u8 = "";
+ var cut: ?u64 = null;
+ var stops: Stops = .{ .io = init.io, .arena = arena };
var i: usize = 0;
while (i < args.len) : (i += 1) {
const arg = args[i];
+ const value: [:0]const u8 = if (i + 1 < args.len) args[i + 1] else "";
if (std.mem.eql(u8, arg, "--")) {
i += 1;
break;
- } else if (std.mem.eql(u8, arg, "-o") and i + 1 < args.len) {
- i += 1;
- out = args[i];
- } else if (std.mem.eql(u8, arg, "--preload") and i + 1 < args.len) {
- i += 1;
- options.preload = args[i];
- } else if (std.mem.eql(u8, arg, "--ring") and i + 1 < args.len) {
- i += 1;
- options.ring_bytes = std.fmt.parseInt(usize, args[i], 0) catch 0;
+ } else if (std.mem.eql(u8, arg, "--alloc")) {
+ try env.append(arena, "ZTRACE_ALLOC=1");
+ continue;
+ } else if (std.mem.eql(u8, arg, "--syscalls")) {
+ try env.append(arena, "ZTRACE_SYSCALLS=1");
+ continue;
+ } else if (std.mem.eql(u8, arg, "-i")) {
+ stops.interactive = true;
+ continue;
+ } else if (i + 1 == args.len) {
+ fail(usage, .{});
+ } else if (std.mem.eql(u8, arg, "-o")) {
+ out = value;
+ } else if (std.mem.eql(u8, arg, "--preload")) {
+ options.preload = value;
+ } else if (std.mem.eql(u8, arg, "--ring")) {
+ options.ring_bytes = std.fmt.parseInt(usize, value, 0) catch 0;
if (!std.math.isPowerOfTwo(options.ring_bytes) or options.ring_bytes < 4096) fail("--ring needs a power of two, 4096 or more\n", .{});
+ } else if (std.mem.eql(u8, arg, "--hook")) {
+ hooks = try std.mem.concat(arena, u8, &.{ hooks, ",", value });
+ } else if (std.mem.eql(u8, arg, "--watch")) {
+ watches = try std.mem.concat(arena, u8, &.{ watches, ",", value });
+ } else if (std.mem.eql(u8, arg, "--read")) {
+ try stops.reads.append(arena, .{ .spec = value });
+ } else if (std.mem.eql(u8, arg, "--cut")) {
+ cut = kinds(value);
+ } else if (std.mem.eql(u8, arg, "--stop-at")) {
+ stops.mask = kinds(value);
} else fail(usage, .{});
+ i += 1;
}
if (i >= args.len) fail(usage, .{});
+ var rec = try zt.Recorder.create(init.gpa, init.io, out);
+ // A hooked call and its return are the steps of a run recorded from inside.
+ rec.cut = cut orelse rec.cut | zt.Kind.call.bit() | zt.Kind.ret.bit();
+ stops.rec = &rec;
+ if (hooks.len > 0) try env.append(arena, try std.fmt.allocPrintSentinel(arena, "ZTRACE_HOOKS={s}", .{hooks}, 0));
+ if (watches.len > 0) try env.append(arena, try std.fmt.allocPrintSentinel(arena, "ZTRACE_WATCH={s}", .{watches}, 0));
+ try env.append(arena, try std.fmt.allocPrintSentinel(arena, "ZTRACE_CUT=0x{x}", .{rec.cut}, 0));
+ for (init.minimal.environ.block.slice) |v| {
+ if (!std.mem.startsWith(u8, std.mem.span(v.?), "ZTRACE_")) try env.append(arena, v);
+ }
+
const path = try util.resolve(init, args[i]);
const argv = try util.targetArgv(arena, args[i..]);
- var session = try zt.host.Session.spawn(arena, path, argv, init.minimal.environ.block.slice, options);
+ var session = try zt.host.Session.spawn(arena, path, argv, try env.toOwnedSliceSentinel(arena, null), options);
defer session.close();
- var rec = try zt.Recorder.create(init.gpa, init.io, out);
+ // Set before the target has had time to load, let alone emit.
+ session.ring.hdr.stop_mask.store(stops.mask, .release);
+ stops.session = &session;
const start = zt.event.now();
- while (try session.pump(rec.sink(), 10 * std.time.ns_per_ms)) {}
+ while (try session.pump(stops.sink(), 10 * std.time.ns_per_ms)) {
+ // Everything pumped is recorded and read: whoever waits at it may go on.
+ if (stops.held) session.ring.resumeAll();
+ stops.held = false;
+ }
const ns = zt.event.now() - start;
const events = rec.count;
@@ -61,3 +128,110 @@ pub fn run(init: std.process.Init, args: []const [:0]const u8) !void {
@as(f64, @floatFromInt(events)) / (@as(f64, @floatFromInt(ns)) / 1e9), session.exit_code.?,
});
}
+
+/// "call,ret" as a set of `Kind.bit`s.
+fn kinds(list: []const u8) u64 {
+ var set: u64 = 0;
+ var names = std.mem.tokenizeScalar(u8, list, ',');
+ while (names.next()) |name| {
+ const kind = std.meta.stringToEnum(zt.Kind, name) orelse fail("{s}: not an event kind\n", .{name});
+ set |= kind.bit();
+ }
+ return set;
+}
+
+/// Between the ring and the recorder: at an event of a kind in `mask` the
+/// thread that emitted it waits inside the target, so the tracer can take its
+/// time: read memory from outside, ask the user.
+const Stops = struct {
+ io: std.Io,
+ arena: std.mem.Allocator,
+ rec: *zt.Recorder = undefined,
+ session: *zt.host.Session = undefined,
+ mask: u64 = 0,
+ reads: std.ArrayList(Read) = .empty,
+ interactive: bool = false,
+ /// Some thread waits at an event already pumped.
+ held: bool = false,
+ stdin: ?std.Io.File.Reader = null,
+ stdin_buf: [256]u8 = undefined,
+
+ /// Memory read from outside at each stop: `old` is what the recording has.
+ const Read = struct { spec: []const u8, addr: u64 = 0, old: []u8 = &.{}, new: []u8 = &.{} };
+
+ fn sink(s: *Stops) zt.Sink {
+ return .{ .ctx = s, .emitFn = emit };
+ }
+
+ fn emit(ctx: *anyopaque, ev: *const zt.Event, payload: []const u8) anyerror!void {
+ const s: *Stops = @ptrCast(@alignCast(ctx));
+ if (s.mask & ev.kind.bit() == 0) return s.rec.emit(ev.*, payload);
+ s.held = true;
+ for (s.reads.items) |*r| try s.read(r, ev);
+ try s.rec.emit(ev.*, payload);
+ if (s.interactive) try s.ask(ev, payload);
+ }
+
+ /// The memory first (it belongs to the moment the event ends), and only what changed.
+ fn read(s: *Stops, r: *Read, ev: *const zt.Event) !void {
+ if (r.old.len == 0) {
+ // The first stop: by now the target's libraries are mapped, and a name means something.
+ const found = agent.symbols.find(s.session.pid, r.spec) orelse fail("{s}: nothing called that in the target\n", .{r.spec});
+ if (found.size == 0) fail("{s}: how many bytes? (ADDR:LEN)\n", .{r.spec});
+ r.addr = found.addr;
+ r.old = try s.arena.alloc(u8, found.size);
+ r.new = try s.arena.alloc(u8, found.size);
+ const id = agent.stringId(r.spec);
+ try s.rec.emit(.{ .ts = ev.ts, .tid = ev.tid, .kind = .string, .a = .{ id, 0, 0, 0, 0, 0 } }, r.spec);
+ try s.rec.emit(.{ .ts = ev.ts, .tid = ev.tid, .kind = .variable, .a = .{ r.addr, found.size, id, 0, 0, 0 } }, "");
+ try s.rec.emit(.{ .ts = ev.ts, .tid = ev.tid, .kind = .mem_write, .a = .{ r.addr, found.size, 0, 0, 0, 0 } }, r.old[0..s.peek(r.addr, r.old)]);
+ return;
+ }
+ var changes: agent.regions.Changes = .{ .old = r.old, .new = r.new[0..s.peek(r.addr, r.new)] };
+ while (changes.next()) |change| try s.rec.emit(.{ .ts = ev.ts, .tid = ev.tid, .kind = .mem_write, .a = .{ r.addr + change.at, change.bytes.len, 0, 0, 0, 0 } }, change.bytes);
+ }
+
+ /// The target's memory: it is our child, so no ptrace is needed to read it.
+ fn peek(s: *Stops, addr: u64, buf: []u8) usize {
+ const local = [1]std.posix.iovec{.{ .base = buf.ptr, .len = buf.len }};
+ const remote = [1]std.posix.iovec_const{.{ .base = @ptrFromInt(addr), .len = buf.len }};
+ const rc = linux.process_vm_readv(s.session.pid, &local, &remote, 0);
+ return if (linux.errno(rc) == .SUCCESS) rc else 0;
+ }
+
+ fn ask(s: *Stops, ev: *const zt.Event, payload: []const u8) !void {
+ var out_buf: [4096]u8 = undefined;
+ var stdout = std.Io.File.stdout().writer(s.io, &out_buf);
+ // One reader for the whole run: it holds the lines read ahead.
+ if (s.stdin == null) s.stdin = std.Io.File.stdin().reader(s.io, &s.stdin_buf);
+ const w = &stdout.interface;
+ try w.print("{t} tid={d} aux={d} a={x} {x} {x} {x} {x} {x} +{d}\n", .{ ev.kind, ev.tid, ev.aux, ev.a[0], ev.a[1], ev.a[2], ev.a[3], ev.a[4], ev.a[5], payload.len });
+ while (true) {
+ try w.writeAll("> ");
+ try w.flush();
+ // The end of input ends the asking, not the run.
+ const line = try s.stdin.?.interface.takeDelimiter('\n') orelse "c";
+ var words = std.mem.tokenizeAny(u8, line, " \t\r");
+ const command = words.next() orelse "s";
+ if (std.mem.eql(u8, command, "s")) {
+ return;
+ } else if (std.mem.eql(u8, command, "c")) {
+ s.mask = 0;
+ s.session.ring.hdr.stop_mask.store(0, .release);
+ return;
+ } else if (std.mem.eql(u8, command, "q")) {
+ try s.rec.close();
+ s.session.close();
+ std.process.exit(0);
+ } else if (std.mem.eql(u8, command, "x")) {
+ var bytes: [256]u8 = undefined;
+ const addr = std.fmt.parseInt(u64, words.next() orelse "", 0) catch 0;
+ const len = @min(bytes.len, std.fmt.parseInt(usize, words.next() orelse "64", 0) catch 64);
+ const got = bytes[0..s.peek(addr, bytes[0..len])];
+ var at: usize = 0;
+ while (at < got.len) : (at += 16) try w.print("{x:0>12} {x}\n", .{ addr + at, got[at..@min(got.len, at + 16)] });
+ if (got.len < len) try w.print("{x:0>12} not readable\n", .{addr + got.len});
+ } else try w.writeAll("s: step to the next stop c: continue to the end x ADDR [LEN]: memory q: quit\n");
+ }
+ }
+};
diff --git a/targets/agent_api.c b/targets/agent_api.c
new file mode 100644
index 0000000..1c954cf
--- /dev/null
+++ b/targets/agent_api.c
@@ -0,0 +1,22 @@
+// A program that annotates itself: the agent linked in, an array on its
+// stack watched, a mark after every step of an insertion sort.
+#include <stdio.h>
+#include <ztrace.h>
+
+int main(void) {
+ int numbers[16] = {9, 3, 14, 0, 7, 12, 5, 1, 15, 8, 2, 11, 6, 13, 4, 10};
+ int n = sizeof numbers / sizeof *numbers;
+ ztrace_watch(numbers, sizeof numbers, "numbers");
+ for (int i = 1; i < n; i++) {
+ int value = numbers[i], j = i;
+ for (; j > 0 && numbers[j - 1] > value; j--) numbers[j] = numbers[j - 1];
+ numbers[j] = value;
+ ztrace_mark("inserted", i);
+ }
+ unsigned long checksum = 0;
+ for (int i = 0; i < n; i++) checksum = checksum * 31 + numbers[i];
+ ztrace_snapshot(&checksum, sizeof checksum);
+ ztrace_mark("done", checksum);
+ printf("%lu\n", checksum);
+ return 0;
+}
diff --git a/targets/agent_fib.c b/targets/agent_fib.c
new file mode 100644
index 0000000..33ae856
--- /dev/null
+++ b/targets/agent_fib.c
@@ -0,0 +1,15 @@
+// A function to hook: fib(n) the slow way, kept from being turned into a
+// loop so that it makes the 2 fib(n+1) - 1 calls the definition says.
+#include <stdio.h>
+#include <stdlib.h>
+
+__attribute__((noinline, optnone)) static unsigned long fib(unsigned long n) {
+ if (n < 2) return n;
+ return fib(n - 1) + fib(n - 2);
+}
+
+int main(int argc, char **argv) {
+ unsigned long n = argc > 1 ? strtoul(argv[1], NULL, 10) : 10;
+ printf("fib(%lu) = %lu\n", n, fib(n));
+ return 0;
+}
diff --git a/targets/agent_list.c b/targets/agent_list.c
new file mode 100644
index 0000000..8787638
--- /dev/null
+++ b/targets/agent_list.c
@@ -0,0 +1,46 @@
+// What the allocation tracker is for: a linked list of N nodes built and
+// torn down, beside one of each other way to allocate.
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+struct node {
+ struct node *next;
+ long value;
+};
+
+int main(int argc, char **argv) {
+ long n = argc > 1 ? atol(argv[1]) : 100;
+ struct node *head = NULL;
+ for (long i = 0; i < n; i++) {
+ struct node *node = malloc(sizeof *node);
+ node->value = i;
+ node->next = head;
+ head = node;
+ }
+
+ // A vector that grows: realloc in place and realloc that moves.
+ size_t cap = 4, len = 0;
+ long *values = calloc(cap, sizeof *values);
+ for (struct node *node = head; node; node = node->next) {
+ if (len == cap) values = realloc(values, (cap *= 2) * sizeof *values);
+ values[len++] = node->value;
+ }
+ void *aligned = NULL;
+ if (posix_memalign(&aligned, 64, 100)) return 1;
+ void *page = aligned_alloc(4096, 4096);
+ memset(page, 1, 4096);
+
+ long sum = ((char *)page)[100] - 1;
+ while (head) {
+ struct node *node = head;
+ head = node->next;
+ sum += node->value;
+ free(node);
+ }
+ free(values);
+ free(aligned);
+ free(page);
+ printf("sum %ld of %zu\n", sum, len);
+ return 0;
+}
diff --git a/targets/agent_sort.c b/targets/agent_sort.c
new file mode 100644
index 0000000..7e29a9d
--- /dev/null
+++ b/targets/agent_sort.c
@@ -0,0 +1,22 @@
+// A program that knows nothing of the tracer: a global array sorted by
+// swaps. Hooked at `swap` and watched at `numbers` from outside, each moment
+// of its recording is the array one swap later.
+#include <stdio.h>
+
+int numbers[16] = {9, 3, 14, 0, 7, 12, 5, 1, 15, 8, 2, 11, 6, 13, 4, 10};
+
+__attribute__((noinline)) void swap(int *a, int *b) {
+ int t = *a;
+ *a = *b;
+ *b = t;
+}
+
+int main(void) {
+ int n = sizeof numbers / sizeof *numbers;
+ for (int i = 0; i < n; i++)
+ for (int j = 0; j + 1 < n - i; j++)
+ if (numbers[j] > numbers[j + 1]) swap(&numbers[j], &numbers[j + 1]);
+ for (int i = 0; i < n; i++) printf("%d ", numbers[i]);
+ printf("\n");
+ return 0;
+}
diff --git a/targets/agent_sys.c b/targets/agent_sys.c
new file mode 100644
index 0000000..12a6ada
--- /dev/null
+++ b/targets/agent_sys.c
@@ -0,0 +1,57 @@
+// Syscalls to find again in a recording: a file opened, written and closed,
+// from the main thread, from a second thread, from a forked child, and from
+// a signal handler (which has to return through the dispatcher too).
+#include <fcntl.h>
+#include <pthread.h>
+#include <signal.h>
+#include <string.h>
+#include <sys/wait.h>
+#include <unistd.h>
+
+static int fd;
+
+static void say(const char *text) {
+ if (write(fd, text, strlen(text)) < 0) _exit(1);
+}
+
+static void on_signal(int signo) {
+ (void)signo;
+ say("signal\n");
+}
+
+static void *thread(void *arg) {
+ say(arg);
+ return NULL;
+}
+
+int main(void) {
+ fd = open("/dev/null", O_WRONLY);
+ say("hello from main\n");
+
+ // Every signal blocked around a syscall: the agent must keep its own deliverable.
+ sigset_t all, old;
+ sigfillset(&all);
+ sigprocmask(SIG_BLOCK, &all, &old);
+ say("masked\n");
+ sigprocmask(SIG_SETMASK, &old, NULL);
+
+ struct sigaction action = {.sa_handler = on_signal};
+ sigfillset(&action.sa_mask);
+ sigaction(SIGUSR1, &action, NULL);
+ raise(SIGUSR1);
+
+ pthread_t t;
+ pthread_create(&t, NULL, thread, "thread\n");
+ pthread_join(t, NULL);
+
+ pid_t child = fork();
+ if (child == 0) {
+ say("child\n");
+ _exit(3);
+ }
+ int status = 0;
+ waitpid(child, &status, 0);
+ say(WEXITSTATUS(status) == 3 ? "child exited 3\n" : "child lost\n");
+ close(fd);
+ return getpid() == getppid();
+}
diff --git a/targets/agent_zig.zig b/targets/agent_zig.zig
new file mode 100644
index 0000000..bfb2f5d
--- /dev/null
+++ b/targets/agent_zig.zig
@@ -0,0 +1,20 @@
+//! A Zig program that annotates itself: agent_api.c again, with the agent
+//! compiled in as a module instead of linked as a library.
+const std = @import("std");
+const agent = @import("ztrace-agent");
+
+pub fn main() void {
+ var numbers = [16]i32{ 9, 3, 14, 0, 7, 12, 5, 1, 15, 8, 2, 11, 6, 13, 4, 10 };
+ agent.watch(std.mem.asBytes(&numbers), "numbers");
+ for (1..numbers.len) |i| {
+ const value = numbers[i];
+ var j = i;
+ while (j > 0 and numbers[j - 1] > value) : (j -= 1) numbers[j] = numbers[j - 1];
+ numbers[j] = value;
+ agent.mark("inserted", i);
+ }
+ var checksum: u64 = 0;
+ for (numbers) |v| checksum = checksum *% 31 +% @as(u64, @intCast(v));
+ agent.snapshot(std.mem.asBytes(&checksum));
+ agent.mark("done", checksum);
+}