From 8beab959b633e6641d07aba053a55e6e8e61eb00 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 10 Nov 2026 11:58:00 -0300 Subject: 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 --- src/trace/debugger_test.zig | 396 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 396 insertions(+) create mode 100644 src/trace/debugger_test.zig (limited to 'src') 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(); +} -- cgit v1.3