//! 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 "DWARF says how many parameters a function takes" { var d = try spawn(targets.list, "2", null); defer d.deinit(); for ([_][]const u8{ "push", "reverse", "list_done", "main" }, [_]u8{ 2, 1, 1, 2 }) |name, n| { try std.testing.expectEqual(@as(?u8, n), d.syms.parameters(d.symbol(name).?.addr)); } // Only where a function begins; nor in a library without debug info. try std.testing.expectEqual(@as(?u8, null), d.syms.parameters(d.symbol("push").?.addr + 1)); try std.testing.expectEqual(@as(?u8, null), d.syms.parameters(d.regs.rip)); } test "a recording by `ztrace record` has the line of each instruction round the pc, and a call's parameters" { var trace = try zt.Trace.open(gpa, io, targets.fib_recording); defer trace.close(); // The first stop at the breakpoint on fib, and the instructions from there. const m, const pc = find: for (0..trace.len) |i| { const m = try trace.moment(i); var events = try m.events(gpa); defer events.deinit(gpa); while (events.next()) |item| if (item.ev.kind == .breakpoint) break :find .{ m, item.ev.a[0] }; } else return error.NoBreakpoint; var text: [256]u8 = undefined; const here = (try zt.telescope.instruction(m, pc, &text)).?; try std.testing.expectEqual(@as(u32, 4), here.line.?.line); var name: [std.Io.Dir.max_path_bytes]u8 = undefined; try std.testing.expect(std.mem.endsWith(u8, (try m.string(here.line.?.file, &name)).?, "fib.c")); // fib calls itself once (-O1 made the other call a loop): with its one parameter. var at = pc; const call = while (try zt.telescope.instruction(m, at, &text)) |insn| : (at += insn.len) { if (std.mem.startsWith(u8, insn.text, "call")) break insn; } else return error.NoCall; try std.testing.expectEqual(@as(?u8, 1), call.params); try std.testing.expectEqual(@as(u32, 5), call.line.?.line); // The frame that called fib is on its call's line: the call is recorded, `back` from where it returns. const tids = try m.threads(gpa); defer gpa.free(tids); const regs = (try m.regs(tids[0])).?; var chain: [4]u64 = undefined; const frames = try zt.telescope.backtrace(m, ®s, &chain); try std.testing.expect(frames.len >= 2); const after = (try zt.telescope.instruction(m, frames[1], &text)).?; try std.testing.expect(after.back != 0); const caller = (try zt.telescope.instruction(m, frames[1] - after.back, &text)).?; try std.testing.expect(std.mem.startsWith(u8, caller.text, "call")); try std.testing.expect(caller.line != null); } 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 "the telescope records the region round what a pointer leads to" { var log: Log = .{}; defer log.deinit(); var d = try spawn(targets.list, "3", log.sink()); defer d.deinit(); d.telescope = 1; d.telescope_around = 16; // The heap is a mapping the debugger learns of from the program's brk. d.syscalls = .record; // At `list_done(head)`: rdi leads to a node on the heap, malloc's header before it. _ = try d.breakAt(try d.resolve("list_done"), null); _ = try d.cont(); const node = d.regs.rdi; // Sixteen bytes before it to sixteen past its 32, in however many writes. var seen: u64 = 0; for (log.events.items) |e| { if (e.ev.kind != .mem_write) continue; for (0..64) |i| { const at = node - 16 + i; if (at >= e.ev.a[0] and at < e.ev.a[0] + e.payload.len) seen |= @as(u64, 1) << @intCast(i); } } try std.testing.expectEqual(~@as(u64, 0), seen); } 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; var buffer: u64 = 0; 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); buffer = e.ev.a[1]; } } try std.testing.expect(opened_libc); // What is written is memory too, as it was when the kernel took it. var in_memory = false; for (glibc.events.items) |e| { if (e.ev.kind != .mem_write or e.ev.a[0] > buffer or buffer + 8 > e.ev.a[0] + e.payload.len) continue; in_memory = std.mem.eql(u8, "small b\n", e.payload[buffer - e.ev.a[0] ..][0..8]); } try std.testing.expect(in_memory); // 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(); }