summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 11:58:00 -0300
committerGabriel Schneider <[email protected]>2026-11-10 11:58:53 -0300
commit8beab959b633e6641d07aba053a55e6e8e61eb00 (patch)
tree0e5a91c0a00e121fe4094a333438ee90ccc5fdda
parent3fdb67c479dcc1ad0f1e51832bc086622692249c (diff)
downloadcomputeranim-8beab959b633e6641d07aba053a55e6e8e61eb00.tar.gz
computeranim-8beab959b633e6641d07aba053a55e6e8e61eb00.zip
targets, test-debugger, bench-debugger
A linked list, a graph search in Zig, the same C under glibc and musl, two threads. The tests drive the debugger over them: breakpoint counts, the lines a step walks (as gdb), a list snapshotted by a hook, a watch's words, the syscalls that tell glibc from musl, threads, attach, and scripted dbg and record sessions. The bench measures steps, stops and memory access from bare ptrace up to a recording. Co-Authored-By: Claude Fable 5.2 <[email protected]>
-rw-r--r--bench/debugger.zig217
-rw-r--r--build/debugger.zig128
-rw-r--r--src/trace/debugger_test.zig396
-rw-r--r--targets/graph.zig41
-rw-r--r--targets/libc.c19
-rw-r--r--targets/list.c42
-rw-r--r--targets/threads.c26
7 files changed, 868 insertions, 1 deletions
diff --git a/bench/debugger.zig b/bench/debugger.zig
new file mode 100644
index 0000000..f682dff
--- /dev/null
+++ b/bench/debugger.zig
@@ -0,0 +1,217 @@
+//! What the debugger costs, measured: `zig build bench-debugger`. Steps,
+//! syscall stops and memory access, each from the bare ptrace calls up to a
+//! recording, so the differences say where the time goes.
+const std = @import("std");
+const linux = std.os.linux;
+const zt = @import("ztrace");
+const Debugger = zt.Debugger;
+const now = zt.event.now;
+
+var out: *std.Io.Writer = undefined;
+
+fn row(what: []const u8, n: u64, ns: u64, unit: []const u8) !void {
+ const per = @as(f64, @floatFromInt(ns)) / @as(f64, @floatFromInt(@max(n, 1)));
+ try out.print(" {s:<46} {d:>9} {s:<6} {d:>9.0}/s {d:>8.2} us each\n", .{ what, n, unit, 1e9 / per, per / 1e3 });
+}
+
+/// A sink that only counts.
+const Count = struct {
+ events: u64 = 0,
+ bytes: u64 = 0,
+ fn sink(c: *Count) zt.Sink {
+ return .{ .ctx = c, .emitFn = emit };
+ }
+ fn emit(ctx: *anyopaque, _: *const zt.Event, payload: []const u8) anyerror!void {
+ const c: *Count = @ptrCast(@alignCast(ctx));
+ c.events += 1;
+ c.bytes += payload.len;
+ }
+};
+
+const Mode = enum { stepi, step, cont };
+
+/// Runs a target to its exit under the debugger, one way of stopping, and
+/// returns the stops and the time.
+fn drive(init: std.process.Init, argv: [:null]const ?[*:0]const u8, sink: ?zt.Sink, mode: Mode, stack: usize, syscalls: @FieldType(Debugger, "syscalls"), breakpoint: ?[]const u8) !struct { u64, u64 } {
+ var d = try Debugger.spawn(init.gpa, init.io, argv[0].?, argv.ptr, init.minimal.environ.block.slice.ptr, sink);
+ defer d.deinit();
+ d.stack_watch = stack;
+ d.syscalls = syscalls;
+ if (breakpoint) |where| _ = try d.breakAt(try d.resolve(where), null);
+ var stops: u64 = 0;
+ const start = now();
+ while (true) : (stops += 1) switch (try switch (mode) {
+ .stepi => d.stepi(),
+ .step => d.step(),
+ .cont => d.cont(),
+ }) {
+ .exited, .killed => break,
+ else => {},
+ };
+ return .{ stops, now() - start };
+}
+
+/// The same into a recording: its moments, how fast, and what each costs on disk.
+fn recorded(init: std.process.Init, what: []const u8, argv: [:null]const ?[*:0]const u8, mode: Mode, syscalls: @FieldType(Debugger, "syscalls"), breakpoint: ?[]const u8) !void {
+ const path = "bench.ztrace";
+ var rec = try zt.Recorder.create(init.gpa, init.io, path);
+ rec.cut &= ~zt.Kind.line.bit();
+ _, const ns = try drive(init, argv, rec.sink(), mode, 128, syscalls, breakpoint);
+ const start = now();
+ const moments = rec.moments;
+ try rec.close();
+ const size = (try std.Io.Dir.cwd().statFile(init.io, path, .{})).size;
+ try std.Io.Dir.cwd().deleteFile(init.io, path);
+ try row(what, moments, ns + (now() - start), "moments");
+ try out.print(" {s:<46} {d:>9} bytes {d:>9} a moment\n", .{ "", size, size / @max(moments, 1) });
+}
+
+pub fn main(init: std.process.Init) !void {
+ const args = try init.minimal.args.toSlice(init.arena.allocator());
+ if (args.len != 4) return error.Usage; // fib, graph, dd
+ // The numbers go to stderr, and stdout nowhere: it is the targets' too.
+ var buf: [4096]u8 = undefined;
+ var stderr = std.Io.File.stderr().writer(init.io, &buf);
+ out = &stderr.interface;
+ _ = linux.dup2(@intCast(linux.open("/dev/null", .{ .ACCMODE = .WRONLY }, 0)), 1);
+ const envp = init.minimal.environ.block.slice.ptr;
+ const fib = [_:null]?[*:0]const u8{ args[1].ptr, "12", null };
+ const graph = [_:null]?[*:0]const u8{ args[2].ptr, null };
+
+ try out.print("instruction steps ({s} 12)\n", .{std.fs.path.basename(args[1])});
+ {
+ var p = try zt.ptrace.Process.spawn(fib[0].?, &fib, envp);
+ defer p.close();
+ var n: u64 = 0;
+ const start = now();
+ while (try p.stepi() == .trap) n += 1;
+ try row("ptrace singlestep + wait", n, now() - start, "steps");
+ }
+ {
+ var p = try zt.ptrace.Process.spawn(fib[0].?, &fib, envp);
+ defer p.close();
+ var n: u64 = 0;
+ var sum: u64 = 0;
+ const start = now();
+ while (try p.stepi() == .trap) : (n += 1) sum +%= (try p.regs()).rip;
+ try row("... + registers", n, now() - start, "steps");
+ }
+ {
+ const n, const ns = try drive(init, &fib, null, .stepi, 0, .ignore, null);
+ try row("Debugger.stepi, no sink", n, ns, "steps");
+ }
+ var count: Count = .{};
+ {
+ const n, const ns = try drive(init, &fib, count.sink(), .stepi, 0, .ignore, null);
+ try row("... + events (the source line looked up)", n, ns, "steps");
+ }
+ {
+ const n, const ns = try drive(init, &fib, count.sink(), .stepi, 0, .record, null);
+ try row("... + syscalls told from the registers", n, ns, "steps");
+ }
+ {
+ const n, const ns = try drive(init, &fib, count.sink(), .stepi, 128, .record, null);
+ try row("... + 128 bytes of stack watched", n, ns, "steps");
+ }
+ {
+ const n, const ns = try drive(init, &fib, count.sink(), .stepi, 4096, .record, null);
+ try row("... or 4096 bytes of stack watched", n, ns, "steps");
+ }
+ try recorded(init, "recorded (`ztrace record`)", &fib, .stepi, .record, null);
+
+ try out.print("\nsource-line steps ({s})\n", .{std.fs.path.basename(args[2])});
+ {
+ const insns, _ = try drive(init, &graph, null, .stepi, 0, .ignore, null);
+ const n, const ns = try drive(init, &graph, null, .step, 0, .ignore, null);
+ try row("Debugger.step, no sink", n, ns, "lines");
+ try out.print(" {s:<46} {d:>9} instructions under them, {d:.2} us each\n", .{ "", insns, @as(f64, @floatFromInt(ns)) / @as(f64, @floatFromInt(insns)) / 1e3 });
+ }
+ try recorded(init, "recorded (`ztrace record --by line`)", &graph, .step, .record, null);
+ try out.print("\nbreakpoints ({s} 22: one at fib, 28657 calls)\n", .{std.fs.path.basename(args[1])});
+ const deep = [_:null]?[*:0]const u8{ args[1].ptr, "22", null };
+ {
+ const n, const ns = try drive(init, &deep, null, .cont, 0, .ignore, "fib");
+ try row("Debugger.cont to a breakpoint, no sink", n, ns, "hits");
+ }
+ try recorded(init, "recorded (`ztrace record --by break -b fib`)", &deep, .cont, .record, "fib");
+
+ const calls = 200_000;
+ const dd = [_:null]?[*:0]const u8{ args[3].ptr, "if=/dev/zero", "of=/dev/null", "bs=1", std.fmt.comptimePrint("count={d}", .{calls / 2}), "status=none", null };
+ try out.print("\nsyscall stops ({s} bs=1 count={d}: a read and a write each)\n", .{ std.fs.path.basename(args[3]), calls / 2 });
+ const native = native: {
+ const start = now();
+ const pid = linux.fork();
+ if (pid == 0) {
+ _ = linux.execve(dd[0].?, &dd, envp);
+ linux.exit_group(127);
+ }
+ var status: u32 = 0;
+ _ = linux.waitpid(@intCast(pid), @ptrCast(&status), 0);
+ break :native now() - start;
+ };
+ try row("native", calls, native, "calls");
+ {
+ var p = try zt.ptrace.Process.spawn(dd[0].?, &dd, envp);
+ defer p.close();
+ const start = now();
+ while (try p.syscall() == .syscall) {}
+ try row("ptrace syscall + wait, entry and exit", calls, now() - start - native, "calls");
+ }
+ {
+ _, const ns = try drive(init, &dd, null, .cont, 0, .stop, null);
+ try row("Debugger.cont stopping at both, no sink", calls, ns - native, "calls");
+ }
+ {
+ _, const ns = try drive(init, &dd, count.sink(), .cont, 0, .record, null);
+ try row("... as events with the bytes written", calls, ns - native, "calls");
+ }
+ try recorded(init, "recorded (`ztrace record --by syscall`)", &dd, .cont, .stop, null);
+
+ try out.print("\nmemory (1 MiB of {s}'s code; 64 bytes of its stack)\n", .{std.fs.path.basename(args[2])});
+ {
+ var d = try Debugger.spawn(init.gpa, init.io, graph[0].?, &graph, envp, null);
+ defer d.deinit();
+ const p = &d.proc;
+ const code = d.symbol("graph.main").?.addr & ~@as(u64, 0xfffff);
+ const block = try init.gpa.alloc(u8, 1 << 20);
+ defer init.gpa.free(block);
+ const rounds = 200;
+ var start = now();
+ for (0..rounds) |_| if (p.read(code + 0x1000, block) != block.len) return error.ShortRead;
+ var ns = now() - start;
+ try out.print(" {s:<46} {d:>9.0} MiB/s\n", .{ "process_vm_readv, one call", @as(f64, rounds) * 1e9 / @as(f64, @floatFromInt(ns)) });
+ start = now();
+ var at: usize = 0;
+ while (at < block.len) : (at += 8) {
+ const word = linux.ptrace(linux.PTRACE.PEEKDATA, p.pid, code + 0x1000 + at, @intFromPtr(block[at..].ptr), 0);
+ if (linux.errno(word) != .SUCCESS) return error.Peek;
+ }
+ ns = now() - start;
+ try out.print(" {s:<46} {d:>9.0} MiB/s\n", .{ "PTRACE_PEEKDATA, a word a call", 1e9 / @as(f64, @floatFromInt(ns)) });
+
+ var small: [64]u8 = undefined;
+ const n = 200_000;
+ start = now();
+ for (0..n) |_| _ = p.read(d.regs.rsp, &small);
+ try row("64 bytes: process_vm_readv", n, now() - start, "reads");
+ start = now();
+ for (0..n) |_| {
+ for (0..8) |i| _ = linux.ptrace(linux.PTRACE.PEEKDATA, p.pid, d.regs.rsp + i * 8, @intFromPtr(&small[i * 8]), 0);
+ }
+ try row("64 bytes: PTRACE_PEEKDATA x 8", n, now() - start, "reads");
+ start = now();
+ for (0..n) |_| try p.write(d.regs.rsp - 256, &small);
+ try row("64 bytes: process_vm_writev", n, now() - start, "writes");
+ // Code is read-only: the same call goes through /proc/pid/mem.
+ _ = p.read(code + 0x1000, &small);
+ start = now();
+ for (0..n) |_| try p.write(code + 0x1000, &small);
+ try row("64 bytes of code: writev fails, /proc/pid/mem", n, now() - start, "writes");
+ start = now();
+ for (0..n) |_| {
+ for (0..8) |i| _ = linux.ptrace(linux.PTRACE.POKEDATA, p.pid, code + 0x1000 + i * 8, std.mem.readInt(u64, small[i * 8 ..][0..8], .little), 0);
+ }
+ try row("64 bytes of code: PTRACE_POKEDATA x 8", n, now() - start, "writes");
+ }
+ try out.flush();
+}
diff --git a/build/debugger.zig b/build/debugger.zig
index d3c7eb3..a2611b2 100644
--- a/build/debugger.zig
+++ b/build/debugger.zig
@@ -1,5 +1,131 @@
+//! The debugger's part of the build: the small programs it is tried on, and
+//! its tests against them.
+const std = @import("std");
const Ctx = @import("../build.zig").Ctx;
pub fn add(ctx: Ctx) void {
- _ = ctx;
+ const b = ctx.b;
+
+ // Position-independent, so the load bias is exercised.
+ const fib = ctx.cTarget("fib", &.{"fib.c"});
+ fib.pie = true;
+ const list = ctx.cTarget("list", &.{"list.c"});
+ const threads = ctx.cTarget("threads", &.{"threads.c"});
+ const libc_glibc = ctx.cTarget("libc-glibc", &.{"libc.c"});
+ // The same source against musl, linked statically.
+ const musl = b.resolveTargetQuery(.{ .cpu_arch = .x86_64, .os_tag = .linux, .abi = .musl });
+ const musl_mod = b.createModule(.{ .target = musl, .optimize = .Debug, .link_libc = true, .omit_frame_pointer = false });
+ musl_mod.addCSourceFiles(.{ .root = b.path("targets"), .files = &.{"libc.c"}, .flags = &.{ "-O1", "-g", "-fno-omit-frame-pointer" } });
+ const libc_musl = b.addExecutable(.{ .name = "libc-musl", .root_module = musl_mod });
+ // Zig, no libc: always a debug build, so its lines are the source's.
+ const graph = b.addExecutable(.{ .name = "graph", .root_module = b.createModule(.{
+ .root_source_file = b.path("targets/graph.zig"),
+ .target = ctx.target,
+ .optimize = .Debug,
+ }) });
+
+ const targets = [_]*std.Build.Step.Compile{ fib, list, threads, libc_glibc, libc_musl, graph };
+ for (targets) |t| b.getInstallStep().dependOn(&b.addInstallArtifact(t, .{ .dest_dir = .{ .override = .{ .custom = "targets" } } }).step);
+
+ // The compiler's own checks (UBSan, on by default in a debug build) are
+ // not the program: without them its code is what its source says.
+ for (targets) |t| t.root_module.sanitize_c = .off;
+
+ const step = ctx.areaTest("test-debugger", "The debugger against real programs");
+
+ // The library, driven from Zig: the targets' paths come as options.
+ const paths = b.addOptions();
+ for (targets) |t| paths.addOptionPath(b.dupe(std.mem.replaceOwned(u8, b.allocator, t.name, "-", "_") catch @panic("OOM")), t.getEmittedBin());
+ const lib_tests = b.addTest(.{ .root_module = b.createModule(.{
+ .root_source_file = b.path("src/trace/debugger_test.zig"),
+ .target = ctx.target,
+ .optimize = ctx.optimize,
+ .imports = &.{ .{ .name = "ztrace", .module = ctx.ztrace }, .{ .name = "targets", .module = paths.createModule() } },
+ }) });
+ step.dependOn(&b.addRunArtifact(lib_tests).step);
+
+ // The commands. A scripted session: break, look, step, stop at syscalls, run out, go back.
+ const dbg = b.addRunArtifact(ctx.exe);
+ dbg.addArgs(&.{ "dbg", "-o" });
+ _ = dbg.addOutputFileArg("dbg.ztrace");
+ dbg.addArg("--");
+ dbg.addArtifactArg(fib);
+ dbg.addArg("1");
+ dbg.setStdIn(.{ .bytes = "b fib\nr\nbt\nx $rsp 16\nsi\ns\nsyscalls write\nc\nc\nsyscalls off\nc\ngoto 3\nregs\nbt\nback 2\nforward\nnope\nquit\n" });
+ for ([_][]const u8{
+ "breakpoint 1 at ",
+ "[1] breakpoint 1 at ",
+ " fib+4 (fib.c:4)\n#1 ",
+ " main+42 (fib.c:10)\n#2 ",
+ "[2] step at ",
+ // A source line on from line 4 is line 5.
+ "[3] step at ",
+ " (fib.c:5)\n(ztrace) syscalls write",
+ // The result is written when the program ends.
+ "] syscall write(1, \"fib(1) = 1\\n\", 11) at ",
+ "] syscall write = 11 at ",
+ "] exited 0\n(ztrace) goto 3",
+ // Back in the recording, at the step to line 5: the registers and the stack of then.
+ "goto 3\n[3] step at ",
+ " rip ",
+ " fib+12 (fib.c:5)\n#1 ",
+ "(ztrace) back 2\n[1] breakpoint 1 at ",
+ "(ztrace) forward\n[2] step at ",
+ "error: UnknownCommand",
+ "dbg.ztrace: ",
+ }) |expected| dbg.expectStdOutMatch(expected);
+ step.dependOn(&dbg.step);
+
+ // A recording of breakpoints only, and what `show` counts in it: fib(10) is 89 calls.
+ const record = b.addRunArtifact(ctx.exe);
+ record.addArgs(&.{ "record", "--by", "break", "-b", "fib", "-o" });
+ const recording = record.addOutputFileArg("fib.ztrace");
+ record.addArg("--");
+ record.addArtifactArg(fib);
+ record.addArg("10");
+ record.expectStdErrMatch("exit 0");
+ const show = b.addRunArtifact(ctx.exe);
+ show.addArg("show");
+ show.addFileArg(recording);
+ show.expectStdOutMatch(" 89 breakpoint\n");
+ step.dependOn(&show.step);
+
+ // A source line a moment, a watched global, to the exit code.
+ const lines = b.addRunArtifact(ctx.exe);
+ lines.addArgs(&.{ "record", "--by", "line", "-w", "dist", "-w", "queue,8", "-o" });
+ _ = lines.addOutputFileArg("graph.ztrace");
+ lines.addArg("--");
+ lines.addArtifactArg(graph);
+ lines.expectStdErrMatch("exit 18");
+ step.dependOn(&lines.step);
+
+ // A syscall a moment, printed the way strace does.
+ const strace = b.addRunArtifact(ctx.exe);
+ strace.addArgs(&.{ "record", "--syscalls", "--strace", "-o" });
+ _ = strace.addOutputFileArg("musl.ztrace");
+ strace.addArg("--");
+ strace.addArtifactArg(libc_musl);
+ strace.expectStdErrMatch("ioctl(1, 0x5413, ");
+ strace.expectStdErrMatch(") = -25 ENOTTY\nwritev(1, ");
+ strace.expectStdErrMatch("exit_group(0) = ?\n");
+ strace.expectStdErrMatch("exit 0");
+ step.dependOn(&strace.step);
+
+ // The numbers: always optimized, whatever the build is.
+ const fast = b.createModule(.{
+ .root_source_file = b.path("src/trace/root.zig"),
+ .target = ctx.target,
+ .optimize = .ReleaseFast,
+ .imports = &.{.{ .name = "xitdb", .module = ctx.ztrace.import_table.get("xitdb").? }},
+ });
+ const bench = b.addRunArtifact(b.addExecutable(.{ .name = "bench-debugger", .root_module = b.createModule(.{
+ .root_source_file = b.path("bench/debugger.zig"),
+ .target = ctx.target,
+ .optimize = .ReleaseFast,
+ .imports = &.{.{ .name = "ztrace", .module = fast }},
+ }) }));
+ bench.addArtifactArg(fib);
+ bench.addArtifactArg(graph);
+ bench.addArg("/usr/bin/dd");
+ b.step("bench-debugger", "Measure steps, syscall stops and memory access").dependOn(&bench.step);
}
diff --git a/src/trace/debugger_test.zig b/src/trace/debugger_test.zig
new file mode 100644
index 0000000..e1191a9
--- /dev/null
+++ b/src/trace/debugger_test.zig
@@ -0,0 +1,396 @@
+//! The debugger against the programs in `targets/`, built by
+//! `build/debugger.zig` and found through the `targets` options.
+const std = @import("std");
+const linux = std.os.linux;
+const zt = @import("ztrace");
+const targets = @import("targets");
+const Debugger = zt.Debugger;
+
+const gpa = std.testing.allocator;
+const io = std.testing.io;
+const no_env = [_:null]?[*:0]const u8{null};
+
+/// Starts a target with its stdout going nowhere: this process's own is the
+/// test runner's channel to the build.
+fn spawn(path: []const u8, arg: ?[*:0]const u8, sink: ?zt.Sink) !Debugger {
+ const exe = try gpa.dupeSentinel(u8, path, 0);
+ defer gpa.free(exe);
+ const argv = [_:null]?[*:0]const u8{ exe.ptr, arg, null };
+ const saved: linux.fd_t = @intCast(linux.dup(1));
+ const nowhere: linux.fd_t = @intCast(linux.open("/dev/null", .{ .ACCMODE = .WRONLY }, 0));
+ _ = linux.dup2(nowhere, 1);
+ defer {
+ _ = linux.dup2(saved, 1);
+ _ = linux.close(saved);
+ _ = linux.close(nowhere);
+ }
+ return Debugger.spawn(gpa, io, exe.ptr, &argv, &no_env, sink);
+}
+
+/// Runs to the exit and returns its code.
+fn finish(d: *Debugger) !u8 {
+ while (true) switch (try d.cont()) {
+ .exited => |code| return code,
+ .killed => return error.Killed,
+ else => {},
+ };
+}
+
+/// A sink that keeps every event.
+const Log = struct {
+ events: std.ArrayList(struct { ev: zt.Event, payload: []u8 }) = .empty,
+
+ fn sink(l: *Log) zt.Sink {
+ return .{ .ctx = l, .emitFn = emit };
+ }
+
+ fn emit(ctx: *anyopaque, ev: *const zt.Event, payload: []const u8) anyerror!void {
+ const l: *Log = @ptrCast(@alignCast(ctx));
+ try l.events.append(gpa, .{ .ev = ev.*, .payload = try gpa.dupe(u8, payload) });
+ }
+
+ fn deinit(l: *Log) void {
+ for (l.events.items) |e| gpa.free(e.payload);
+ l.events.deinit(gpa);
+ }
+
+ fn count(l: *const Log, kind: zt.Kind) usize {
+ var n: usize = 0;
+ for (l.events.items) |e| n += @intFromBool(e.ev.kind == kind);
+ return n;
+ }
+
+ /// The entries of one syscall.
+ fn calls(l: *const Log, nr: linux.SYS) usize {
+ var n: usize = 0;
+ for (l.events.items) |e| n += @intFromBool(e.ev.kind == .syscall_enter and e.ev.aux == @backingInt(nr));
+ return n;
+ }
+};
+
+test "a breakpoint on fib is hit once a call, in a position-independent executable" {
+ var d = try spawn(targets.fib, "10", null);
+ defer d.deinit();
+ // Loaded somewhere else than linked: the symbol's address has the bias in it.
+ try std.testing.expect(d.syms.modules.items[0].bias != 0);
+ const at = try d.resolve("fib");
+ try std.testing.expectEqualStrings("fib", d.syms.symbolAt(at).?.name);
+ try std.testing.expectEqual(@as(u32, 5), d.lineAt(try d.resolve("fib.c:5")).?.line);
+ const id = try d.breakAt(at, null);
+
+ // -O1 turns fib(n-2) into a loop, so fib(n) makes F(n+1) calls, not
+ // 2F(n+1)-1: 89 for n = 10. gdb counts the same.
+ var hits: usize = 0;
+ var first: u64 = 0;
+ const code = while (true) switch (try d.cont()) {
+ .breakpoint => |hit| {
+ try std.testing.expectEqual(id, hit);
+ try std.testing.expectEqual(at, d.regs.rip);
+ if (hits == 0) first = d.regs.rdi;
+ hits += 1;
+ },
+ .exited => |code| break code,
+ else => return error.UnexpectedStop,
+ };
+ try std.testing.expectEqual(@as(usize, 89), hits);
+ try std.testing.expectEqual(@as(u64, 10), first);
+ try std.testing.expectEqual(@as(u8, 0), code);
+}
+
+test "step walks the source lines, in and out of calls, as gdb does" {
+ var d = try spawn(targets.list, "2", null);
+ defer d.deinit();
+ _ = try d.breakAt(try d.resolve("reverse"), null);
+ try std.testing.expectEqual(Debugger.Stop{ .breakpoint = 1 }, try d.cont());
+ // The loop of `reverse` twice, back to main, through `list_done`, and
+ // printf run through as one line.
+ const expected = [_]u32{ 20, 21, 22, 20, 21, 22, 20, 26, 40, 31, 32, 40, 41 };
+ var lines: [expected.len]u32 = undefined;
+ lines[0] = d.lineAt(d.regs.rip).?.line;
+ for (lines[1..]) |*line| {
+ try std.testing.expectEqual(Debugger.Stop.step, try d.step());
+ line.* = d.lineAt(d.regs.rip).?.line;
+ }
+ try std.testing.expectEqualSlices(u32, &expected, &lines);
+ try std.testing.expectEqualStrings("main", d.syms.symbolAt(d.regs.rip).?.name);
+
+ // The call chain from inside `push`, on a second run.
+ var d2 = try spawn(targets.list, "2", null);
+ defer d2.deinit();
+ _ = try d2.breakAt(try d2.resolve("push"), null);
+ _ = try d2.cont();
+ var frames: [8]u64 = undefined;
+ const chain = Debugger.backtrace(&d2, &d2.regs, false, &frames);
+ try std.testing.expect(chain.len >= 3);
+ try std.testing.expectEqualStrings("push", d2.syms.symbolAt(chain[0]).?.name);
+ try std.testing.expectEqualStrings("main", d2.syms.symbolAt(chain[1]).?.name);
+}
+
+test "a hook snapshots the linked list; the recording's last moment has what the program built" {
+ var tmp = std.testing.tmpDir(.{});
+ defer tmp.cleanup();
+ var dir_buf: [std.Io.Dir.max_path_bytes]u8 = undefined;
+ const dir = dir_buf[0..try tmp.dir.realPath(io, &dir_buf)];
+ const path = try std.fs.path.join(gpa, &.{ dir, "list.ztrace" });
+ defer gpa.free(path);
+
+ var rec = try zt.Recorder.create(gpa, io, path);
+ var head: u64 = 0;
+ {
+ errdefer rec.close() catch {};
+ var d = try spawn(targets.list, "6", rec.sink());
+ defer d.deinit();
+ // At `list_done(head)`: record every node, and let the program go on.
+ const hook = struct {
+ fn run(ctx: ?*anyopaque, dbg: *Debugger, _: Debugger.Stop) anyerror!Debugger.Action {
+ const out: *u64 = @ptrCast(@alignCast(ctx.?));
+ out.* = dbg.regs.rdi;
+ var node = dbg.regs.rdi;
+ while (node != 0) {
+ try dbg.snapshot(node, 16);
+ var next: [8]u8 = undefined;
+ if (dbg.read(node + 8, &next) != 8) return error.BadAddress;
+ node = std.mem.readInt(u64, &next, .little);
+ }
+ return .go;
+ }
+ }.run;
+ _ = try d.breakAt(try d.resolve("list_done"), .{ .ctx = &head, .func = hook });
+ try std.testing.expectEqual(@as(u8, 0), try finish(&d));
+ }
+ try rec.close();
+
+ var trace = try zt.Trace.open(gpa, io, path);
+ defer trace.close();
+ const last = try trace.moment(trace.len - 1);
+ // 36, 25, ... 1 pushed, each before the last, and then reversed: 36 first again.
+ var node = head;
+ for ([_]u64{ 6, 5, 4, 3, 2, 1 }) |i| {
+ var bytes: [16]u8 = undefined;
+ var known: [16]bool = undefined;
+ try last.read(node, &bytes, &known);
+ try std.testing.expect(std.mem.allEqual(bool, &known, true));
+ try std.testing.expectEqual(@as(u64, i * i), std.mem.readInt(u64, bytes[0..8], .little));
+ node = std.mem.readInt(u64, bytes[8..16], .little);
+ }
+ try std.testing.expectEqual(@as(u64, 0), node);
+ // Nothing of them is in the first moment: they were not built yet.
+ var known: [16]bool = undefined;
+ var bytes: [16]u8 = undefined;
+ try (try trace.moment(0)).read(head, &bytes, &known);
+ try std.testing.expect(std.mem.allEqual(bool, &known, false));
+}
+
+test "a watch sends a word when it changes, and each moment keeps the region as it was" {
+ var tmp = std.testing.tmpDir(.{});
+ defer tmp.cleanup();
+ var dir_buf: [std.Io.Dir.max_path_bytes]u8 = undefined;
+ const dir = dir_buf[0..try tmp.dir.realPath(io, &dir_buf)];
+ const path = try std.fs.path.join(gpa, &.{ dir, "graph.ztrace" });
+ defer gpa.free(path);
+
+ var rec = try zt.Recorder.create(gpa, io, path);
+ rec.cut &= ~zt.Kind.line.bit();
+ var log: Log = .{};
+ defer log.deinit();
+ // Events to the log and to the recorder both.
+ const Tee = struct {
+ a: zt.Sink,
+ b: zt.Sink,
+ fn emit(ctx: *anyopaque, ev: *const zt.Event, payload: []const u8) anyerror!void {
+ const t: *@This() = @ptrCast(@alignCast(ctx));
+ try t.a.emit(ev.*, payload);
+ try t.b.emit(ev.*, payload);
+ }
+ };
+ var tee: Tee = .{ .a = log.sink(), .b = rec.sink() };
+ var dist: u64 = 0;
+ {
+ errdefer rec.close() catch {};
+ var d = try spawn(targets.graph, null, .{ .ctx = &tee, .emitFn = Tee.emit });
+ defer d.deinit();
+ const sym = d.symbol("dist").?;
+ try std.testing.expectEqual(@as(u64, 8), sym.size);
+ dist = sym.addr;
+ try d.watch(dist, 8);
+ _ = try d.breakAt(try d.resolve("graph.bfs"), null);
+ try std.testing.expectEqual(Debugger.Stop{ .breakpoint = 1 }, try d.cont());
+ // A source line a stop, to the exit: the sum of the distances.
+ const code = while (true) switch (try d.step()) {
+ .exited => |code| break code,
+ .step => {},
+ else => return error.UnexpectedStop,
+ };
+ try std.testing.expectEqual(@as(u8, 18), code);
+ }
+ try rec.close();
+
+ // `dist` is one word: sent whole at the first stop, then once for each
+ // of the 8 distances the search fills in, and at no other stop.
+ var writes: usize = 0;
+ for (log.events.items) |e| {
+ if (e.ev.kind != .mem_write or e.ev.a[0] != dist) continue;
+ try std.testing.expectEqual(@as(usize, 8), e.payload.len);
+ writes += 1;
+ }
+ try std.testing.expectEqual(@as(usize, 9), writes);
+ try std.testing.expect(log.count(.step) > 100);
+ // Lines come from one file here, defined once.
+ try std.testing.expect(log.count(.line) > 100);
+ for (log.events.items) |e| {
+ if (e.ev.kind == .string) try std.testing.expect(std.mem.endsWith(u8, e.payload, ".zig"));
+ }
+
+ var trace = try zt.Trace.open(gpa, io, path);
+ defer trace.close();
+ var bytes: [8]u8 = undefined;
+ try (try trace.moment(trace.len - 1)).read(dist, &bytes, null);
+ try std.testing.expectEqualSlices(u8, &.{ 0, 1, 1, 2, 3, 4, 5, 2 }, &bytes);
+ // Going back: the search half done, then not begun.
+ var seen_partial = false;
+ for (0..trace.len) |index| {
+ try (try trace.moment(index)).read(dist, &bytes, null);
+ if (std.mem.eql(u8, &bytes, &.{ 0, 1, 1, 2, 0xff, 0xff, 0xff, 2 })) seen_partial = true;
+ }
+ try std.testing.expect(seen_partial);
+ try (try trace.moment(1)).read(dist, &bytes, null);
+ try std.testing.expectEqualSlices(u8, &@as([8]u8, @splat(0xff)), &bytes);
+ // The last stop before the exit knows its line, in a file with a name.
+ const before_exit = try trace.moment(trace.len - 2);
+ var events = try before_exit.events(gpa);
+ defer events.deinit(gpa);
+ const line = (try before_exit.line(events.next().?.ev.tid)).?;
+ var name: [std.Io.Dir.max_path_bytes]u8 = undefined;
+ try std.testing.expect(std.mem.endsWith(u8, (try before_exit.string(line.file, &name)).?, ".zig"));
+}
+
+test "the same program under glibc and under musl: the syscalls tell them apart" {
+ var glibc: Log = .{};
+ defer glibc.deinit();
+ var musl: Log = .{};
+ defer musl.deinit();
+ for ([_][]const u8{ targets.libc_glibc, targets.libc_musl }, [_]*Log{ &glibc, &musl }) |path, log| {
+ var d = try spawn(path, null, log.sink());
+ defer d.deinit();
+ d.syscalls = .record;
+ try std.testing.expectEqual(@as(u8, 0), try finish(&d));
+ try std.testing.expectEqual(@as(usize, 1), log.count(.exit));
+ // Both give malloc(1 MiB) its own mapping, a page more for the header, and unmap it at free.
+ var mapped = false;
+ var unmapped = false;
+ for (log.events.items) |e| {
+ if (e.ev.kind != .syscall_enter) continue;
+ if (e.ev.aux == @backingInt(linux.SYS.mmap) and e.ev.a[1] == (1 << 20) + 4096) mapped = true;
+ if (e.ev.aux == @backingInt(linux.SYS.munmap) and e.ev.a[1] == (1 << 20) + 4096) unmapped = true;
+ }
+ try std.testing.expect(mapped and unmapped);
+ try std.testing.expectEqual(@as(usize, 1), log.calls(.exit_group));
+ }
+
+ // glibc, dynamic: the loader opens the library, the heap comes from brk,
+ // stdout is checked with fstat and written with write.
+ try std.testing.expect(glibc.calls(.openat) >= 1);
+ try std.testing.expect(glibc.calls(.brk) >= 2);
+ try std.testing.expectEqual(@as(usize, 1), glibc.calls(.write));
+ try std.testing.expectEqual(@as(usize, 0), glibc.calls(.writev));
+ var opened_libc = false;
+ for (glibc.events.items) |e| {
+ if (e.ev.kind != .syscall_enter) continue;
+ if (e.ev.aux == @backingInt(linux.SYS.openat) and std.mem.endsWith(u8, e.payload, "libc.so.6")) opened_libc = true;
+ if (e.ev.aux == @backingInt(linux.SYS.write)) try std.testing.expectEqualStrings("small b\n", e.payload);
+ }
+ try std.testing.expect(opened_libc);
+ // The library and its mappings are known as they appear.
+ var mapped_libc = false;
+ for (glibc.events.items) |e| {
+ if (e.ev.kind == .map and std.mem.endsWith(u8, e.payload, "libc.so.6") and e.ev.a[2] & 4 != 0) mapped_libc = true;
+ }
+ try std.testing.expect(mapped_libc);
+
+ // musl, static: no file is opened and brk is never called (its heap is
+ // mmap), stdout is asked whether it is a terminal with an ioctl and
+ // written with writev.
+ try std.testing.expectEqual(@as(usize, 0), musl.calls(.openat));
+ try std.testing.expectEqual(@as(usize, 0), musl.calls(.brk));
+ try std.testing.expectEqual(@as(usize, 0), musl.calls(.write));
+ try std.testing.expectEqual(@as(usize, 1), musl.calls(.writev));
+ try std.testing.expectEqual(@as(usize, 1), musl.calls(.ioctl));
+ // And it starts with a third of the syscalls or fewer.
+ try std.testing.expect(musl.count(.syscall_enter) * 3 <= glibc.count(.syscall_enter));
+}
+
+test "a syscall hook sees entries and exits, and can stop the target at one" {
+ var d = try spawn(targets.fib, "3", null);
+ defer d.deinit();
+ d.syscalls = .record;
+ var seen: struct { enters: usize = 0, exits: usize = 0 } = .{};
+ d.on_syscall = .{ .ctx = &seen, .func = struct {
+ fn run(ctx: ?*anyopaque, _: *Debugger, stop: Debugger.Stop) anyerror!Debugger.Action {
+ const s: *@TypeOf(seen) = @ptrCast(@alignCast(ctx.?));
+ switch (stop) {
+ .syscall_enter => |nr| {
+ s.enters += 1;
+ if (nr == @backingInt(linux.SYS.write)) return .stop;
+ },
+ else => s.exits += 1,
+ }
+ return .go;
+ }
+ }.run };
+ // Stopped at the write of the result: its bytes are the argument.
+ const stop = try d.cont();
+ try std.testing.expectEqual(Debugger.Stop{ .syscall_enter = @backingInt(linux.SYS.write) }, stop);
+ try std.testing.expectEqualStrings("fib(3) = 2\n", try d.decode(stop.syscall_enter));
+ try std.testing.expectEqualStrings("write", zt.syscalls.name(stop.syscall_enter).?);
+ try std.testing.expectEqual(@as(u8, 0), try finish(&d));
+ // exit_group is entered and never left.
+ try std.testing.expectEqual(seen.enters, seen.exits + 1);
+}
+
+test "the threads a target makes are followed" {
+ var log: Log = .{};
+ defer log.deinit();
+ var d = try spawn(targets.threads, null, log.sink());
+ defer d.deinit();
+ d.syscalls = .record;
+ _ = try d.breakAt(try d.resolve("work"), null);
+ // Each of the two threads reaches `work`, as itself.
+ var workers: [2]linux.pid_t = undefined;
+ for (&workers) |*tid| {
+ try std.testing.expectEqual(Debugger.Stop{ .breakpoint = 1 }, try d.cont());
+ tid.* = d.proc.tid;
+ try std.testing.expect(tid.* != d.proc.pid);
+ }
+ try std.testing.expect(workers[0] != workers[1]);
+ try std.testing.expectEqual(@as(u8, 0), try finish(&d));
+ try std.testing.expectEqual(@as(usize, 2), log.count(.thread_start));
+ try std.testing.expectEqual(@as(usize, 2), log.count(.thread_exit));
+ try std.testing.expectEqual(@as(usize, 2), log.count(.breakpoint));
+ // The result, 1000 * (1 + 2), is what main printed: no thread lost a step to the tracer.
+ for (log.events.items) |e| {
+ if (e.ev.kind == .syscall_enter and e.ev.aux == @backingInt(linux.SYS.write)) try std.testing.expectEqualStrings("total = 3000\n", e.payload);
+ }
+}
+
+test "a running process is attached to, looked at and let go" {
+ const rc = linux.fork();
+ if (rc == 0) {
+ while (true) _ = linux.pause();
+ }
+ const pid: linux.pid_t = @intCast(rc);
+ defer {
+ _ = linux.kill(pid, .KILL);
+ var status: u32 = 0;
+ _ = linux.waitpid(pid, @ptrCast(&status), 0);
+ }
+ var d = try Debugger.attach(gpa, io, pid, null);
+ // It is this test's own program, stopped in its pause.
+ try std.testing.expect(d.syms.moduleAt(d.regs.rip) != null);
+ try std.testing.expect(d.syms.mappingAt(d.regs.rsp) != null);
+ var word: [8]u8 = undefined;
+ try std.testing.expectEqual(@as(usize, 8), d.read(d.regs.rsp, &word));
+ d.deinit();
+ // Let go, it is alive and can be attached to again.
+ var again = try Debugger.attach(gpa, io, pid, null);
+ again.deinit();
+}
diff --git a/targets/graph.zig b/targets/graph.zig
new file mode 100644
index 0000000..987eaa5
--- /dev/null
+++ b/targets/graph.zig
@@ -0,0 +1,41 @@
+//! A small graph and a breadth-first search over it. `dist` and `queue` are
+//! exported globals, so a tracer finds them by name and watches them fill.
+//! Exits with the sum of the distances from node 0 (18).
+const n = 8;
+const unreached = 0xff;
+
+const edges = [_][2]u8{ .{ 0, 1 }, .{ 0, 2 }, .{ 1, 3 }, .{ 2, 3 }, .{ 3, 4 }, .{ 4, 5 }, .{ 5, 6 }, .{ 2, 7 } };
+
+/// Aligned so that it is one machine word to a watcher.
+export var dist: [n]u8 align(8) = @splat(unreached);
+export var queue: [n]u8 = @splat(0);
+
+fn linked(a: u8, b: u8) bool {
+ for (edges) |e| {
+ if ((e[0] == a and e[1] == b) or (e[0] == b and e[1] == a)) return true;
+ }
+ return false;
+}
+
+fn bfs(start: u8) void {
+ var head: usize = 0;
+ var tail: usize = 1;
+ queue[0] = start;
+ dist[start] = 0;
+ while (head < tail) : (head += 1) {
+ const at = queue[head];
+ for (0..n) |next| {
+ if (dist[next] != unreached or !linked(at, @intCast(next))) continue;
+ dist[next] = dist[at] + 1;
+ queue[tail] = @intCast(next);
+ tail += 1;
+ }
+ }
+}
+
+pub fn main() u8 {
+ bfs(0);
+ var sum: u8 = 0;
+ for (dist) |d| sum += d;
+ return sum;
+}
diff --git a/targets/libc.c b/targets/libc.c
new file mode 100644
index 0000000..2dad81b
--- /dev/null
+++ b/targets/libc.c
@@ -0,0 +1,19 @@
+// The same C under two C libraries (glibc linked dynamically, musl
+// statically): what startup, malloc and stdio turn into, seen as syscalls.
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+// Volatile, or the compiler proves the allocations away.
+static char *volatile small, *volatile big;
+
+int main(void) {
+ small = malloc(64);
+ big = malloc(1 << 20);
+ strcpy(small, "small");
+ memset(big, 'b', 1 << 20);
+ printf("%s %c\n", small, big[4096]);
+ free(big);
+ free(small);
+ return 0;
+}
diff --git a/targets/list.c b/targets/list.c
new file mode 100644
index 0000000..e09d301
--- /dev/null
+++ b/targets/list.c
@@ -0,0 +1,42 @@
+// A linked list on the heap: built, reversed, summed. `list_done` gets the
+// finished list, the place for a tracer to look at it.
+#include <stdio.h>
+#include <stdlib.h>
+
+struct node {
+ long value;
+ struct node *next;
+};
+
+__attribute__((noinline)) static struct node *push(struct node *head, long value) {
+ struct node *n = malloc(sizeof *n);
+ n->value = value;
+ n->next = head;
+ return n;
+}
+
+__attribute__((noinline)) static struct node *reverse(struct node *head) {
+ struct node *prev = NULL;
+ while (head) {
+ struct node *next = head->next;
+ head->next = prev;
+ prev = head;
+ head = next;
+ }
+ return prev;
+}
+
+__attribute__((noinline)) long list_done(struct node *head) {
+ long sum = 0;
+ for (; head; head = head->next) sum += head->value;
+ return sum;
+}
+
+int main(int argc, char **argv) {
+ int n = argc > 1 ? atoi(argv[1]) : 6;
+ struct node *head = NULL;
+ for (int i = n; i >= 1; i--) head = push(head, i * i);
+ head = reverse(head);
+ printf("sum = %ld\n", list_done(head));
+ return 0;
+}
diff --git a/targets/threads.c b/targets/threads.c
new file mode 100644
index 0000000..ab4d80d
--- /dev/null
+++ b/targets/threads.c
@@ -0,0 +1,26 @@
+// Two threads and a mutex: each adds its share to `total`, main joins them
+// and prints it. What clone, futex and a thread's exit look like to a tracer.
+#include <pthread.h>
+#include <stdio.h>
+
+static pthread_mutex_t lock = PTHREAD_MUTEX_INITIALIZER;
+long total;
+
+__attribute__((noinline)) static void *work(void *arg) {
+ for (long i = 0; i < 1000; i++) {
+ pthread_mutex_lock(&lock);
+ total += (long)arg;
+ pthread_mutex_unlock(&lock);
+ }
+ return NULL;
+}
+
+int main(void) {
+ pthread_t a, b;
+ pthread_create(&a, NULL, work, (void *)1);
+ pthread_create(&b, NULL, work, (void *)2);
+ pthread_join(a, NULL);
+ pthread_join(b, NULL);
+ printf("total = %ld\n", total);
+ return 0;
+}