From 3fdb67c479dcc1ad0f1e51832bc086622692249c Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 10 Nov 2026 11:43:24 -0300 Subject: debugger: steps by instruction and line, breakpoints, hooks, watches, threads; ztrace dbg ptrace.zig follows the threads a target makes, attaches, tells a step from a breakpoint, and writes memory in one call (through /proc/pid/mem where the page is read-only). Debugger.zig is the layer above: cont, stepi, step (a source line, through std.debug's DWARF), breakpoints with hooks, syscall stops and hooks with the path or buffer captured, watched regions sent as the words that changed, and every stop an event. Symbols.zig is modules, ELF symbols and line tables; syscalls.zig their names and shapes. ztrace dbg is a small REPL on it that records as it goes and looks back into the recording; ztrace record stops by instruction, line, syscall or breakpoint, prints syscalls as strace does, and ends cleanly when the recording is full. Co-Authored-By: Claude Fable 5.2 --- src/cli/dbg.zig | 320 ++++++++++++++++++++++++++ src/cli/main.zig | 2 + src/cli/record.zig | 158 ++++++++----- src/trace/Debugger.zig | 608 +++++++++++++++++++++++++++++++++++++++++++++++++ src/trace/Symbols.zig | 365 +++++++++++++++++++++++++++++ src/trace/ptrace.zig | 232 ++++++++++++++----- src/trace/root.zig | 6 + src/trace/syscalls.zig | 141 ++++++++++++ 8 files changed, 1723 insertions(+), 109 deletions(-) create mode 100644 src/cli/dbg.zig create mode 100644 src/trace/Debugger.zig create mode 100644 src/trace/Symbols.zig create mode 100644 src/trace/syscalls.zig diff --git a/src/cli/dbg.zig b/src/cli/dbg.zig new file mode 100644 index 0000000..007b790 --- /dev/null +++ b/src/cli/dbg.zig @@ -0,0 +1,320 @@ +//! ztrace dbg: a program under the debugger, a command a line, every stop a +//! moment of a recording that the same commands can look back into. +const std = @import("std"); +const zt = @import("ztrace"); +const util = @import("util.zig"); +const fail = util.fail; +const Moment = zt.store.Moment; + +pub const usage = + \\usage: ztrace dbg [-o FILE] [--stack BYTES] [-s BYTES] [--max-size BYTES] -- PROGRAM [ARGS] + \\ ztrace dbg [-o FILE] [--stack BYTES] [-s BYTES] [--max-size BYTES] -p PID + \\ + \\Starts PROGRAM stopped at its first instruction (or attaches to PID) + \\and reads commands, from a script when stdin is no terminal: + \\ + \\ run, r, continue, c run to a breakpoint, a signal or the exit + \\ step, s run to the next source line + \\ stepi, si run one instruction + \\ break, b WHERE stop at a function, file:line or *address + \\ syscalls on|off|NAME stop at each syscall's entry and exit, or at one's + \\ watch WHAT [LEN] record a region at every stop: an address or a symbol + \\ regs the registers + \\ x WHAT [LEN] memory at an address, a symbol or $register (64 bytes) + \\ bt the call chain, by frame pointer + \\ back [N] look N moments back in the recording: regs, x + \\ forward [N] and bt then show the program as it was. The + \\ goto MOMENT program itself stays where it stopped last + \\ quit, q + \\ + \\Every stop is a moment of the recording (default out.ztrace), its + \\number in brackets where it is printed. A moment has the registers, + \\the words that changed in the --stack bytes above the stack pointer + \\(default 4K, what bt needs) and in the watched regions, and at most -s + \\bytes (default 256) of what a syscall points at. The session ends when + \\the file reaches --max-size (default 1G). + \\ +; + +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 pid: ?std.os.linux.pid_t = null; + // Enough of the stack in every moment for `bt` to work there. + var stack_bytes: usize = 4096; + var capture: ?usize = null; + var max_bytes: ?u64 = null; + var i: usize = 0; + while (i < args.len) : (i += 1) { + const arg = args[i]; + 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, "-p") and i + 1 < args.len) { + i += 1; + pid = std.fmt.parseInt(std.os.linux.pid_t, args[i], 10) catch fail("-p needs a process id\n", .{}); + } else if ((std.mem.eql(u8, arg, "--stack") or std.mem.eql(u8, arg, "-s") or std.mem.eql(u8, arg, "--max-size")) and i + 1 < args.len) { + i += 1; + const size = std.fmt.parseIntSizeSuffix(args[i], 10) catch fail("{s} needs a size\n", .{arg}); + if (std.mem.eql(u8, arg, "-s")) capture = size else if (std.mem.eql(u8, arg, "--stack")) stack_bytes = size else max_bytes = size; + } else fail(usage, .{}); + } + if ((pid == null) == (i >= args.len)) fail(usage, .{}); + + var out_buf: [4096]u8 = undefined; + var stdout = std.Io.File.stdout().writer(init.io, &out_buf); + var s: Session = .{ .gpa = init.gpa, .io = init.io, .out = out, .w = &stdout.interface, .rec = try .create(init.gpa, init.io, out), .d = undefined }; + // A moment a stop, syscall entries too: their line comes with them. + s.rec.cut = (s.rec.cut | zt.Kind.syscall_enter.bit()) & ~zt.Kind.line.bit(); + if (max_bytes) |n| s.rec.max_bytes = n; + const sink: zt.Sink = .{ .ctx = &s, .emitFn = Session.emit }; + s.d = if (pid) |p| + zt.Debugger.attach(init.gpa, init.io, p, sink) catch |err| fail("cannot attach to {d}: {t}\n", .{ p, err }) + else + try zt.Debugger.spawn(init.gpa, init.io, try util.resolve(init, args[i]), try util.targetArgv(arena, args[i..]), init.minimal.environ.block.slice.ptr, sink); + defer s.d.deinit(); + defer s.stop_payload.deinit(init.gpa); + s.d.stack_watch = stack_bytes; + if (capture) |n| s.d.capture = n; + try s.showStop(); + + var in_buf: [4096]u8 = undefined; + var stdin = std.Io.File.stdin().reader(init.io, &in_buf); + const interactive = std.Io.File.stdin().isTty(init.io) catch false; + while (true) { + try s.w.writeAll("(ztrace) "); + try s.w.flush(); + const line = (stdin.interface.takeDelimiter('\n') catch break) orelse break; + // A script's commands show in its transcript, as a terminal echoes them. + if (!interactive) try s.w.print("{s}\n", .{line}); + try s.w.flush(); + const more = s.command(line) catch |err| switch (err) { + error.WriteFailed => return, + // Nothing more can be recorded, so nothing more is run. + error.RecordingFull => { + try s.w.print("{s} is full, the program stops here: record less (fewer stops and watches, a smaller --stack or -s) or raise --max-size\n", .{out}); + break; + }, + else => more: { + try s.w.print("error: {t}\n", .{err}); + break :more true; + }, + }; + if (!more) break; + } + if (s.trace) |*t| t.close(); + const moments = s.rec.moments; + try s.rec.close(); + try s.w.print("{s}: {d} moments\n", .{ out, moments }); + try s.w.flush(); +} + +const Session = struct { + gpa: std.mem.Allocator, + io: std.Io, + out: []const u8, + w: *std.Io.Writer, + rec: zt.Recorder, + d: zt.Debugger, + /// The moment looked at. Null is the last: the program as it is now. + view: ?u64 = null, + /// The recording, opened to look into it. + trace: ?zt.Trace = null, + /// The one syscall to stop at, when `syscalls NAME` asked. + only_syscall: u16 = 0, + /// The last stop as the debugger sent it: showing it reads no recording. + stop: zt.Event = .{ .kind = .step }, + stop_payload: std.ArrayList(u8) = .empty, + + /// The debugger's sink: the recorder, with the last stop kept on the way. + fn emit(ctx: *anyopaque, ev: *const zt.Event, payload: []const u8) anyerror!void { + const s: *Session = @ptrCast(@alignCast(ctx)); + if (s.rec.cut & ev.kind.bit() != 0) { + s.stop = ev.*; + s.stop_payload.clearRetainingCapacity(); + try s.stop_payload.appendSlice(s.gpa, payload); + } + return s.rec.emit(ev.*, payload); + } + + /// The syscall hook of `syscalls NAME`: the others are recorded and run through. + fn onlySyscall(ctx: ?*anyopaque, _: *zt.Debugger, stop: zt.Debugger.Stop) anyerror!zt.Debugger.Action { + const only: *const u16 = @ptrCast(@alignCast(ctx.?)); + return switch (stop) { + .syscall_enter, .syscall_exit => |nr| if (nr == only.*) .stop else .go, + else => .go, + }; + } + + /// Runs a command. False to quit. + fn command(s: *Session, line: []const u8) !bool { + var words = std.mem.tokenizeAny(u8, line, " \t\r"); + const cmd = words.next() orelse return true; + const arg = words.next(); + if (is(cmd, "quit", "q")) return false; + if (is(cmd, "run", "r") or is(cmd, "continue", "c") or is(cmd, "step", "s") or is(cmd, "stepi", "si")) { + if (s.d.done) return error.Exited; + // Running leaves the past: the program goes on from where it is. + s.view = null; + _ = try if (is(cmd, "step", "s")) s.d.step() else if (is(cmd, "stepi", "si")) s.d.stepi() else s.d.cont(); + try s.showStop(); + } else if (is(cmd, "break", "b")) { + const addr = try s.d.resolve(arg orelse return error.MissingArgument); + try s.w.print("breakpoint {d} at ", .{try s.d.breakAt(addr, null)}); + try s.d.describe(s.w, addr); + try s.w.writeAll("\n"); + } else if (is(cmd, "syscalls", "sys")) { + const which = arg orelse "on"; + s.d.syscalls = if (std.mem.eql(u8, which, "off")) .ignore else .stop; + s.d.on_syscall = null; + if (s.d.syscalls == .stop and !std.mem.eql(u8, which, "on")) { + s.only_syscall = @intCast(@backingInt(std.meta.stringToEnum(std.os.linux.SYS, which) orelse return error.NoSuchSyscall)); + s.d.on_syscall = .{ .ctx = &s.only_syscall, .func = onlySyscall }; + } + } else if (is(cmd, "watch", "w")) { + const what = s.d.place(arg orelse return error.MissingArgument) orelse return error.NoSuchSymbol; + const len = if (words.next()) |n| try std.fmt.parseInt(usize, n, 0) else @max(what.size, 8); + try s.d.watch(what.addr, len); + try s.w.print("watching {d} bytes at {x}\n", .{ len, what.addr }); + } else if (is(cmd, "regs", "reg")) { + const r = try s.regs(try s.moment()); + inline for (zt.Regs.names, 0..) |name, n| { + try s.w.print(" {s:<6} {x:0>16}{s}", .{ name, @field(r, name), if (n % 3 == 2) "\n" else "" }); + } + } else if (is(cmd, "x", "x")) { + const m = try s.moment(); + const text = arg orelse return error.MissingArgument; + const addr = if (text[0] == '$') + (try s.regs(m)).named(text[1..]) orelse return error.NoSuchRegister + else + (s.d.place(text) orelse return error.NoSuchSymbol).addr; + const len = if (words.next()) |n| try std.fmt.parseInt(usize, n, 0) else 64; + var at: usize = 0; + while (at < len) : (at += 16) { + var bytes: [16]u8 = undefined; + var known: [16]bool = undefined; + const n = @min(16, len - at); + try s.fetch(m, addr + at, bytes[0..n], known[0..n]); + try s.w.print("{x:0>12} ", .{addr + at}); + for (bytes[0..n], known[0..n]) |byte, k| { + if (k) try s.w.print(" {x:0>2}", .{byte}) else try s.w.writeAll(" ??"); + } + try s.w.splatByteAll(' ', (16 - n) * 3 + 2); + for (bytes[0..n], known[0..n]) |byte, k| try s.w.writeByte(if (k and std.ascii.isPrint(byte)) byte else '.'); + try s.w.writeAll("\n"); + } + } else if (is(cmd, "bt", "backtrace")) { + const m = try s.moment(); + const r = try s.regs(m); + const at_entry = if (s.d.syms.symbolAt(r.rip)) |sym| sym.addr == r.rip else false; + var frames: [64]u64 = undefined; + for (zt.Debugger.backtrace(Memory{ .s = s, .m = m }, &r, at_entry, &frames), 0..) |pc, n| { + try s.w.print("#{d} ", .{n}); + try s.d.describe(s.w, pc); + try s.w.writeAll("\n"); + } + } else if (is(cmd, "back", "forward") or is(cmd, "goto", "goto")) { + const t = try s.recording(); + const n = if (arg) |a| try std.fmt.parseInt(u64, a, 10) else if (is(cmd, "goto", "goto")) return error.MissingArgument else 1; + const now = s.view orelse t.len - 1; + const to = if (std.mem.eql(u8, cmd, "back")) now -| n else if (std.mem.eql(u8, cmd, "forward")) @min(now +| n, t.len - 1) else n; + if (to >= t.len) return error.NoSuchMoment; + s.view = if (to == t.len - 1) null else to; + try s.show(to); + } else return error.UnknownCommand; + return true; + } + + fn is(cmd: []const u8, long: []const u8, short: []const u8) bool { + return std.mem.eql(u8, cmd, long) or std.mem.eql(u8, cmd, short); + } + + /// The recording with everything so far in it. + fn recording(s: *Session) !*zt.Trace { + try s.rec.flush(); + if (s.trace) |*t| t.close(); + s.trace = null; + s.trace = try zt.Trace.open(s.gpa, s.io, s.out); + return &s.trace.?; + } + + /// The moment commands look at: null for the running program itself. + fn moment(s: *Session) !?Moment { + if (s.view == null and !s.d.done) return null; + const t = try s.recording(); + return try t.moment(s.view orelse t.len - 1); + } + + /// The thread a moment stopped in, and its registers then. + fn regs(s: *Session, m: ?Moment) !zt.Regs { + const past = m orelse return s.d.regs; + var events = try past.events(s.gpa); + defer events.deinit(s.gpa); + var tid: u32 = @intCast(s.d.proc.pid); + while (events.next()) |item| tid = item.ev.tid; + return (try past.regs(tid)) orelse error.NoRegisters; + } + + /// Memory as of a moment, or the program's: `known` tells the bytes there are. + fn fetch(s: *Session, m: ?Moment, addr: u64, buf: []u8, known: []bool) !void { + if (m) |past| return past.read(addr, buf, known); + const n = s.d.read(addr, buf); + @memset(known[0..n], true); + @memset(known[n..], false); + } + + /// What `Debugger.backtrace` reads frames from. + const Memory = struct { + s: *Session, + m: ?Moment, + + pub fn read(mem: Memory, addr: u64, buf: []u8) usize { + var known: [16]bool = undefined; + mem.s.fetch(mem.m, addr, buf, known[0..buf.len]) catch return 0; + return std.mem.indexOfScalar(bool, known[0..buf.len], false) orelse buf.len; + } + }; + + /// The stop the program is at now. + fn showStop(s: *Session) !void { + return s.print(s.rec.moments - 1, &s.stop, s.stop_payload.items, if (s.d.done) null else s.d.regs.rip); + } + + /// The stop that ended a moment of the recording. + fn show(s: *Session, index: u64) !void { + const m = try (try s.recording()).moment(index); + var events = try m.events(s.gpa); + defer events.deinit(s.gpa); + var last: ?zt.store.Events.Item = null; + while (events.next()) |item| last = item; + const stop = last orelse return; + return s.print(index, &stop.ev, stop.payload, if (try m.regs(stop.ev.tid)) |r| r.rip else null); + } + + /// A stop's line: its moment, what it was, and where. + fn print(s: *Session, index: u64, ev: *const zt.Event, payload: []const u8, pc: ?u64) !void { + try s.w.print("[{d}] ", .{index}); + switch (ev.kind) { + .exit => return s.w.print("exited {d}\n", .{ev.a[0]}), + .breakpoint => try s.w.print("breakpoint {d}", .{ev.a[1]}), + .signal => try s.w.print("signal {t}", .{@as(std.os.linux.SIG, @fromBackingInt(@intCast(ev.aux)))}), + .syscall_enter => { + try s.w.writeAll("syscall "); + try zt.syscalls.formatEnter(s.w, ev, payload); + }, + .syscall_exit => { + try s.w.print("syscall {s}", .{zt.syscalls.name(ev.aux) orelse "?"}); + try zt.syscalls.formatExit(s.w, ev); + }, + else => try s.w.print("{t}", .{ev.kind}), + } + if (pc) |at| { + try s.w.writeAll(" at "); + try s.d.describe(s.w, at); + } + try s.w.writeAll("\n"); + } +}; diff --git a/src/cli/main.zig b/src/cli/main.zig index 3abea6e..72b894a 100644 --- a/src/cli/main.zig +++ b/src/cli/main.zig @@ -5,6 +5,7 @@ const util = @import("util.zig"); /// A command is a file with `usage` and `run(init, args)`. const commands = .{ .record = @import("record.zig"), + .dbg = @import("dbg.zig"), .run = @import("run.zig"), .dump = @import("dump.zig"), .show = @import("show.zig"), @@ -14,6 +15,7 @@ const usage = \\usage: ztrace COMMAND ... \\ \\ record run a program under ptrace into a recording + \\ dbg debug a program, recording it: step, break, look, go back \\ run record a program that carries a ring producer (agent, instrumentation) \\ dump print a recording's events \\ show print a recording's summary, or the program's state at a moment diff --git a/src/cli/record.zig b/src/cli/record.zig index ab617d4..7b44522 100644 --- a/src/cli/record.zig +++ b/src/cli/record.zig @@ -1,16 +1,31 @@ -//! ztrace record: a program under ptrace, every stop a moment. +//! ztrace record: a program under the debugger, left to run, every stop a +//! moment of the recording. const std = @import("std"); const zt = @import("ztrace"); const util = @import("util.zig"); const fail = util.fail; pub const usage = - \\usage: ztrace record [-o FILE] [--steps N] [--syscalls] [--stack BYTES] -- PROGRAM [ARGS] + \\usage: ztrace record [-o FILE] [--by insn|line|syscall|break] [-b WHERE]... [-w WHAT[,LEN]]... + \\ [--stack BYTES] [-s BYTES] [--steps N] [--max-size BYTES] [--strace] + \\ -- PROGRAM [ARGS] \\ - \\Runs PROGRAM under ptrace into a recording (default out.ztrace): every - \\instruction, or with --syscalls every syscall. --steps stops after N - \\moments. --stack records that many bytes above the stack pointer at each - \\stop (default 128). + \\Runs PROGRAM under ptrace into a recording (default out.ztrace). --by + \\says where it stops, each stop a moment: + \\ insn every instruction (the default) + \\ line every source line, from the program's entry (its loader is run through) + \\ syscall every syscall (--syscalls is the same) + \\ break the breakpoints only + \\-b adds a breakpoint, in any of them: a function, file:line or *address. + \\Syscalls are recorded whatever the stops are, with at most -s bytes + \\(default 256) of the path or the buffer each points at; --strace also + \\prints them, a line each. + \\Of memory, only what is asked for is recorded, and of that the words + \\that changed since the stop before: the --stack bytes above the stack + \\pointer (default 128) and each -w region, an address or a symbol, as + \\long as the symbol unless LEN says. + \\--steps ends the recording after N moments, and --max-size when the + \\file is that large (default 1G). Sizes take a suffix: 64K, 4G. \\ ; @@ -18,95 +33,122 @@ 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 max_moments: u64 = std.math.maxInt(u64); - var by_syscall = false; + var by: enum { insn, line, syscall, @"break" } = .insn; var stack_bytes: usize = 128; + var capture: ?usize = null; + var max_bytes: ?u64 = null; + var strace = false; + var breaks: std.ArrayList([]const u8) = .empty; + var watches: std.ArrayList([]const u8) = .empty; var i: usize = 0; while (i < args.len) : (i += 1) { const arg = args[i]; + const value: ?[]const u8 = if (i + 1 < args.len) args[i + 1] else null; if (std.mem.eql(u8, arg, "--")) { i += 1; break; - } else if (std.mem.eql(u8, arg, "-o") and i + 1 < args.len) { + } else if (std.mem.eql(u8, arg, "--syscalls")) { + by = .syscall; + } else if (std.mem.eql(u8, arg, "--strace")) { + strace = true; + } else if (value == null) { + fail(usage, .{}); + } else if (std.mem.eql(u8, arg, "-o")) { + out = value.?; i += 1; - out = args[i]; - } else if (std.mem.eql(u8, arg, "--steps") and i + 1 < args.len) { + } else if (std.mem.eql(u8, arg, "--by")) { + by = std.meta.stringToEnum(@TypeOf(by), value.?) orelse fail("--by needs insn, line, syscall or break\n", .{}); i += 1; - max_moments = std.fmt.parseInt(u64, args[i], 0) catch fail("--steps needs a number\n", .{}); - } else if (std.mem.eql(u8, arg, "--stack") and i + 1 < args.len) { + } else if (std.mem.eql(u8, arg, "-b")) { + try breaks.append(arena, value.?); + i += 1; + } else if (std.mem.eql(u8, arg, "-w")) { + try watches.append(arena, value.?); + i += 1; + } else if (std.mem.eql(u8, arg, "--steps")) { + max_moments = std.fmt.parseInt(u64, value.?, 0) catch fail("--steps needs a number\n", .{}); + i += 1; + } else if (std.mem.eql(u8, arg, "--stack") or std.mem.eql(u8, arg, "-s") or std.mem.eql(u8, arg, "--max-size")) { + const size = std.fmt.parseIntSizeSuffix(value.?, 10) catch fail("{s} needs a size\n", .{arg}); + if (std.mem.eql(u8, arg, "-s")) capture = size else if (std.mem.eql(u8, arg, "--stack")) stack_bytes = size else max_bytes = size; i += 1; - stack_bytes = std.fmt.parseInt(usize, args[i], 0) catch fail("--stack needs a number\n", .{}); - } else if (std.mem.eql(u8, arg, "--syscalls")) { - by_syscall = true; } else fail(usage, .{}); } if (i >= args.len) fail(usage, .{}); const path = try util.resolve(init, args[i]); const argv = try util.targetArgv(arena, args[i..]); - var proc = try zt.ptrace.Process.spawn(path, argv, init.minimal.environ.block.slice.ptr); - errdefer proc.kill(); - var rec = try zt.Recorder.create(init.gpa, init.io, out); - const tid: u32 = @intCast(proc.pid); - const stack = try arena.alloc(u8, stack_bytes); - const stack_seen = try arena.alloc(u8, stack_bytes); - var stack_at: u64 = 0; + // A stop is a moment: the line it is at comes with it, not as one more. + rec.cut &= ~zt.Kind.line.bit(); + if (max_bytes) |n| rec.max_bytes = n; + var stderr_buf: [4096]u8 = undefined; + var stderr = std.Io.File.stderr().writer(init.io, &stderr_buf); + var printer: zt.syscalls.Printer = .{ .w = &stderr.interface, .next = rec.sink() }; + + var d = try zt.Debugger.spawn(init.gpa, init.io, path, argv, init.minimal.environ.block.slice.ptr, if (strace) printer.sink() else rec.sink()); + defer d.deinit(); + d.syscalls = if (by == .syscall) .stop else .record; + d.stack_watch = stack_bytes; + if (capture) |n| d.capture = n; + for (breaks.items) |where| _ = try d.breakAt(d.resolve(where) catch fail("{s}: no such place in the program\n", .{where}), null); + for (watches.items) |spec| { + const comma = std.mem.indexOfScalar(u8, spec, ',') orelse spec.len; + const what = d.place(spec[0..comma]) orelse fail("{s}: no such symbol\n", .{spec[0..comma]}); + const len = if (comma < spec.len) std.fmt.parseInt(usize, spec[comma + 1 ..], 0) catch fail("{s}: the length is no number\n", .{spec}) else @max(what.size, 8); + try d.watch(what.addr, len); + } + + // By line, the loader's hundred thousand instructions are run through + // to a breakpoint at the entry: there are no lines in them. + var entry: ?u32 = null; + if (by == .line) if (d.syms.entryPoint()) |at| if (at != d.regs.rip) { + entry = try d.breakAt(at, null); + }; var timer = zt.event.now(); var exit_code: u64 = 0; + var full = false; while (rec.moments < max_moments) { - const stop = if (by_syscall) try proc.syscall() else try proc.stepi(); + const stop = (if (entry) |id| stop: { + defer d.clear(id); + entry = null; + break :stop d.cont(); + } else switch (by) { + .insn => d.stepi(), + .line => d.step(), + .syscall, .@"break" => d.cont(), + }) catch |err| switch (err) { + error.RecordingFull => { + full = true; + break; + }, + else => |e| return e, + }; switch (stop) { .exited => |code| { exit_code = code; - try rec.emit(.{ .ts = zt.event.now(), .tid = tid, .kind = .exit, .a = .{ code, 0, 0, 0, 0, 0 } }, ""); break; }, .killed => |sig| { - exit_code = 128 + @as(u64, @intFromEnum(sig)); - try rec.emit(.{ .ts = zt.event.now(), .tid = tid, .kind = .exit, .a = .{ exit_code, 0, 0, 0, 0, 0 } }, ""); + exit_code = 128 + @as(u64, @backingInt(sig)); break; }, - .signal => |sig| try rec.emit(.{ .ts = zt.event.now(), .tid = tid, .kind = .signal, .aux = @intCast(@intFromEnum(sig)) }, ""), - .trap, .syscall => { - const regs = try proc.regs(); - // The stack above rsp: only the bytes that changed since the last stop. - const n = proc.read(regs.rsp, stack); - if (regs.rsp != stack_at) @memset(stack_seen, 0); - var from: usize = 0; - while (from < n) { - if (regs.rsp == stack_at and stack[from] == stack_seen[from]) { - from += 1; - continue; - } - var to = from + 1; - while (to < n and (regs.rsp != stack_at or stack[to] != stack_seen[to])) to += 1; - try rec.emit(.{ .ts = zt.event.now(), .tid = tid, .kind = .mem_write, .a = .{ regs.rsp + from, to - from, regs.rip, 0, 0, 0 } }, stack[from..to]); - from = to; - } - @memcpy(stack_seen[0..n], stack[0..n]); - stack_at = regs.rsp; - - const ev: zt.Event = if (stop == .trap) - .{ .ts = zt.event.now(), .tid = tid, .kind = .step, .a = .{ regs.rip, 0, 0, 0, 0, 0 } } - else if (proc.in_syscall) - .{ .ts = zt.event.now(), .tid = tid, .kind = .syscall_enter, .aux = @truncate(regs.orig_rax), .a = .{ regs.rdi, regs.rsi, regs.rdx, regs.r10, regs.r8, regs.r9 } } - else - .{ .ts = zt.event.now(), .tid = tid, .kind = .syscall_exit, .aux = @truncate(regs.orig_rax), .a = .{ regs.rax, 0, 0, 0, 0, 0 } }; - try rec.emit(ev, std.mem.asBytes(®s)); - }, + // A signal is delivered by the next resume. + else => {}, } - } else proc.kill(); + } timer = zt.event.now() - timer; const moments = rec.moments + @intFromBool(rec.delta.items.len > 0); const events = rec.count; try rec.close(); const size = (try std.Io.Dir.cwd().statFile(init.io, out, .{})).size; + if (full) std.debug.print("{s}: full at {d} bytes, the program stopped there: record less (--by line, syscall or break; fewer -w; a smaller --stack or -s) or raise --max-size\n", .{ out, size }); std.debug.print("{s}: {d} moments, {d} events, {d} bytes ({d} bytes/moment), {d:.1} ms, {d:.0} moments/s, exit {d}\n", .{ - out, moments, - events, size, - size / @max(moments, 1), @as(f64, @floatFromInt(timer)) / 1e6, + out, moments, + events, size, + size / @max(moments, 1), @as(f64, @floatFromInt(timer)) / 1e6, @as(f64, @floatFromInt(moments)) / (@as(f64, @floatFromInt(timer)) / 1e9), exit_code, }); } diff --git a/src/trace/Debugger.zig b/src/trace/Debugger.zig new file mode 100644 index 0000000..b2cdd5e --- /dev/null +++ b/src/trace/Debugger.zig @@ -0,0 +1,608 @@ +//! A debugger over `ptrace.Process`, for a program to drive (the `dbg` and +//! `record` commands are two): continue, step an instruction or a source +//! line, breakpoints, hooks at addresses and at syscalls, watched memory. +//! What it stops at goes to a `Sink`: +//! +//! at a stop `line` when the source line changed (its file a `string` +//! first), a `mem_write` for each run of watched words that +//! changed, then the stop itself with the registers: `step`, +//! `breakpoint`, `syscall_enter`, `syscall_exit`, `signal` +//! in between `syscall_enter` and `syscall_exit` when syscalls are +//! recorded but not stopped at, `thread_start`, +//! `thread_exit`, `map` and `unmap` +//! at the end `exit` +//! +//! A syscall's entry carries the argument it points at (a path, the bytes +//! written) in place of the registers when it has one: they come with its +//! exit, after a `mem_write` of what a read put in its buffer. A `map`'s +//! payload is the region's name, also the kernel's own for a region that is +//! no file ("[stack]"). +//! +//! Memory is never recorded wholesale: only the watched regions, the stack +//! window and what syscalls point at, cut at `capture`, and of those only +//! the words that changed since they were last sent. +const Debugger = @This(); + +const std = @import("std"); +const linux = std.os.linux; +const event = @import("event.zig"); +const Event = event.Event; +const Regs = event.Regs; +const ptrace = @import("ptrace.zig"); +const Symbols = @import("Symbols.zig"); +const syscalls_table = @import("syscalls.zig"); +const P = linux.PTRACE; + +gpa: std.mem.Allocator, +proc: ptrace.Process, +syms: Symbols, +sink: ?event.Sink, +/// What a syscall does to the running target: nothing (the fastest), an +/// event, or a stop as well. +syscalls: enum { ignore, record, stop } = .ignore, +/// Called at each syscall's entry and exit unless they are ignored; it +/// decides whether the target stops there. +on_syscall: ?Hook = null, +/// Bytes above the stack pointer watched at every stop. +stack_watch: usize = 0, +/// The most captured of what a syscall points at: a path, the buffer of a +/// write or a read (strace's -s). +capture: usize = 256, +captured: std.ArrayList(u8) = .empty, +watches: std.ArrayList(Watch) = .empty, +breakpoints: std.ArrayList(Breakpoint) = .empty, +/// The current thread's registers at its last stop. +regs: Regs = .{}, +/// The target has exited. +done: bool = false, +next_id: u32 = 1, +/// What the sink was sent of the target's memory, by page. +shadow: std.AutoHashMapUnmanaged(u64, *Page) = .empty, +scratch: std.ArrayList(u8) = .empty, +/// The threads that have stopped before: a first stop is a thread's birth. +threads: std.AutoHashMapUnmanaged(linux.pid_t, void) = .empty, +/// String ids of source files: by path, and by line-table entry. +files: std.StringHashMapUnmanaged(u64) = .empty, +file_ids: std.AutoHashMapUnmanaged(usize, u64) = .empty, +last_line: struct { file: u64 = 0, line: u32 = 0 } = .{}, + +pub const Stop = union(enum) { + /// `stepi` or `step` finished. + step, + /// The breakpoint with this id was reached, and not yet run. + breakpoint: u32, + /// At a syscall, by number: its arguments are in rdi, rsi, rdx, r10, r8, r9. + syscall_enter: u16, + /// Its result is in rax. + syscall_exit: u16, + /// A signal the next resume delivers (`proc.resume_signal`: clear it to swallow the signal). + signal: linux.SIG, + exited: u8, + killed: linux.SIG, +}; + +/// A callback at a breakpoint or a syscall. It may look at the target and +/// change it (`regs`, `setRegs`, `read`, `write`), and says whether the +/// target stops there or goes on. +pub const Hook = struct { + ctx: ?*anyopaque = null, + func: *const fn (ctx: ?*anyopaque, d: *Debugger, stop: Stop) anyerror!Action, +}; +pub const Action = enum { go, stop }; + +pub const Breakpoint = struct { id: u32, addr: u64, saved: u8, hook: ?Hook }; +pub const Watch = struct { addr: u64, len: usize }; + +const Page = struct { + /// Bit i set: word i was sent. + known: [8]u64 = @splat(0), + words: [512]u64 = undefined, +}; + +/// The longest `mem_write` sent: longer runs go out in pieces. +const write_max = 1 << 16; + +/// Runs `argv` stopped at its first instruction. `path` is the executable. +pub fn spawn(gpa: std.mem.Allocator, io: std.Io, path: [*:0]const u8, argv: [*:null]const ?[*:0]const u8, envp: [*:null]const ?[*:0]const u8, sink: ?event.Sink) !Debugger { + return begin(gpa, io, try .spawn(path, argv, envp), sink); +} + +/// Stops a running process and debugs it from there. `deinit` lets it run on. +pub fn attach(gpa: std.mem.Allocator, io: std.Io, pid: linux.pid_t, sink: ?event.Sink) !Debugger { + return begin(gpa, io, try .attach(pid), sink); +} + +fn begin(gpa: std.mem.Allocator, io: std.Io, proc: ptrace.Process, sink: ?event.Sink) !Debugger { + var d: Debugger = .{ .gpa = gpa, .proc = proc, .syms = .{ .gpa = gpa, .io = io }, .sink = sink }; + errdefer d.deinit(); + try d.threads.put(gpa, proc.pid, {}); + d.regs = try d.proc.regs(); + try d.refreshMaps(); + // Where the target is now: the first stop. + _ = try d.report(.step); + return d; +} + +pub fn deinit(d: *Debugger) void { + // An attached target runs on, without our breakpoints. + if (d.proc.attached and !d.proc.gone) for (d.breakpoints.items) |bp| d.proc.write(bp.addr, &.{bp.saved}) catch {}; + d.proc.close(); + d.syms.deinit(); + d.watches.deinit(d.gpa); + d.breakpoints.deinit(d.gpa); + var pages = d.shadow.valueIterator(); + while (pages.next()) |page| d.gpa.destroy(page.*); + d.shadow.deinit(d.gpa); + d.scratch.deinit(d.gpa); + d.captured.deinit(d.gpa); + d.threads.deinit(d.gpa); + var paths = d.files.keyIterator(); + while (paths.next()) |path| d.gpa.free(path.*); + d.files.deinit(d.gpa); + d.file_ids.deinit(d.gpa); +} + +// Running. + +/// Until the next breakpoint, signal or exit, or syscall when they stop. +pub fn cont(d: *Debugger) !Stop { + return d.report(try d.run(d.free())); +} + +/// One instruction. +pub fn stepi(d: *Debugger) !Stop { + return d.report(try d.run(P.SINGLESTEP)); +} + +/// To the next source line: instructions until the line is another, a call +/// into code without lines (a library) run through as one. +pub fn step(d: *Debugger) !Stop { + const from = d.lineAt(d.regs.rip); + const tid = d.proc.tid; + while (true) { + const before = d.regs; + var stop = try d.run(P.SINGLESTEP); + if (stop == .step and d.proc.tid == tid) { + if (d.lineAt(d.regs.rip)) |here| { + if (from == null or from.?.key != here.key or from.?.line != here.line) return d.report(.step); + continue; + } + // In code without lines. A call there from code with lines + // pushed the address to run to: the one after the call. + var word: [8]u8 = undefined; + if (d.regs.rsp != before.rsp -% 8 or d.read(d.regs.rsp, &word) != 8) continue; + const back = std.mem.readInt(u64, &word, .little); + if (back <= before.rip or back - before.rip > 15 or d.lineAt(before.rip) == null) continue; + stop = try d.runTo(back, d.regs.rsp); + if (stop == .step) continue; + } + return d.report(stop); + } +} + +/// Until the current thread is at `addr` with its stack above `sp` (the +/// call returned, not a deeper one), or something else stops the target. +fn runTo(d: *Debugger, addr: u64, sp: u64) !Stop { + // A breakpoint of the caller's already there stops the target by itself. + const mine = d.breakpointAt(addr) == null; + if (mine) try d.insert(.{ .id = 0, .addr = addr, .saved = 0, .hook = null }); + defer if (mine) d.clear(0); + const tid = d.proc.tid; + while (true) { + const stop = try d.run(d.free()); + if (stop != .breakpoint or stop.breakpoint != 0) return stop; + if (d.proc.tid == tid and d.regs.rsp > sp) return .step; + } +} + +/// The request that lets the target run: syscalls are stops to ptrace only when wanted. +fn free(d: *const Debugger) u32 { + return if (d.syscalls == .ignore) P.CONT else P.SYSCALL; +} + +/// Resumes the current thread and waits for the next stop of any. A +/// breakpoint under its pc is lifted for one instruction first. +// shortcut: the other threads run while it is lifted and can pass it, upgrade by stopping them or by stepping a copy of the instruction. +fn resumeThread(d: *Debugger, request: u32) !ptrace.Stop { + if (d.breakpointAt(d.regs.rip)) |bp| { + try d.proc.write(bp.addr, &.{bp.saved}); + try d.proc.run(P.SINGLESTEP); + const stop = try d.proc.wait(d.proc.tid); + if (!d.proc.gone) try d.proc.write(bp.addr, &.{0xcc}); + if (request == P.SINGLESTEP or stop != .trap) return stop; + } + try d.proc.run(request); + return d.proc.waitAny(); +} + +/// Runs the target with `request` until something stops it for the caller. +/// What does not (a recorded syscall, a thread's birth, a hook that says +/// go) is sent as an event here; the stop itself is for `report`. +fn run(d: *Debugger, request: u32) !Stop { + if (d.done) return error.Exited; + var resumes = true; + while (true) { + const before = d.regs; + const tid = d.proc.tid; + const raw = if (resumes) try d.resumeThread(request) else try d.proc.waitAny(); + resumes = true; + switch (raw) { + .exited, .killed => { + _ = d.threads.remove(d.proc.tid); + if (d.proc.gone) { + d.done = true; + return if (raw == .exited) .{ .exited = raw.exited } else .{ .killed = raw.killed }; + } + // A thread ended: there is nothing of it to resume. + try d.emit(.{ .kind = .thread_exit }, ""); + resumes = false; + continue; + }, + else => {}, + } + d.regs = try d.proc.regs(); + const born = !(try d.threads.getOrPut(d.gpa, d.proc.tid)).found_existing; + switch (raw) { + .exited, .killed => unreachable, + .clone => |child| try d.emit(.{ .kind = .thread_start, .a = .{ @intCast(child), 0, 0, 0, 0, 0 } }, std.mem.asBytes(&d.regs)), + .signal => |sig| { + // A thread's first stop is the SIGSTOP it is born with under tracing. + if (!born or sig != .STOP) return .{ .signal = sig }; + d.proc.resume_signal = 0; + }, + .syscall => { + const nr: u16 = @truncate(d.regs.orig_rax); + const stop: Stop = if (try d.proc.inSyscall()) .{ .syscall_enter = nr } else .{ .syscall_exit = nr }; + if (try d.atSyscall(stop)) return stop; + try d.emitStop(stop); + }, + .trap => { + if (request == P.SINGLESTEP and d.proc.tid == tid) { + if (d.syscalls != .ignore) try d.steppedSyscall(before); + return .step; + } + // Not the step just asked for: another thread's that ended, or a breakpoint instruction. + if (!d.proc.atBreakpoint()) return .step; + const at = d.regs.rip -% 1; + const bp = d.breakpointAt(at) orelse { + var byte: [1]u8 = undefined; + if (d.proc.read(at, &byte) == 1 and byte[0] == 0xcc) { + // The program's own breakpoint instruction: its signal to take. + d.proc.resume_signal = @backingInt(linux.SIG.TRAP); + return .{ .signal = .TRAP }; + } + // One of ours, removed after this thread ran into it: back + // onto the instruction it stood for. + d.regs.rip = at; + try d.proc.setRegs(&d.regs); + continue; + }; + d.regs.rip = at; + try d.proc.setRegs(&d.regs); + if (bp.hook) |hook| if (try hook.func(hook.ctx, d, .{ .breakpoint = bp.id }) == .go) continue; + return .{ .breakpoint = bp.id }; + }, + } + } +} + +/// A single step is no syscall stop to ptrace. When it went over a +/// `syscall` instruction (which leaves its return address in rcx), the +/// entry and the exit are told from the registers on either side. +// shortcut: the hook sees the entry after the call ran, and exit_group never returns to be seen; upgrade by reading the instruction before each step. +fn steppedSyscall(d: *Debugger, before: Regs) !void { + const after = d.regs; + var insn: [2]u8 = undefined; + if (after.rip != before.rip +% 2 or after.rcx != after.rip or d.read(before.rip, &insn) != 2 or insn[0] != 0x0f or insn[1] != 0x05) return; + const nr: u16 = @truncate(before.rax); + d.regs = before; + d.regs.orig_rax = nr; + _ = try d.atSyscall(.{ .syscall_enter = nr }); + try d.emitStop(.{ .syscall_enter = nr }); + d.regs = after; + d.regs.orig_rax = nr; + _ = try d.atSyscall(.{ .syscall_exit = nr }); + try d.emitStop(.{ .syscall_exit = nr }); + d.regs = after; +} + +/// A syscall's entry or exit: true when the target stops there. +fn atSyscall(d: *Debugger, stop: Stop) !bool { + // What the mappings are is known as they change, when syscalls are seen at all. + // shortcut: all of /proc/pid/maps is read at each of these, upgrade by applying the syscall's own arguments. + if (stop == .syscall_exit) switch (std.enums.fromInt(linux.SYS, stop.syscall_exit) orelse .close) { + .mmap, .munmap, .mremap, .mprotect, .brk => try d.refreshMaps(), + // What the kernel put in the buffer is a write to the target's memory. + .read, .pread64 => if (@as(i64, @bitCast(d.regs.rax)) > 0) try d.snapshot(d.regs.rsi, @min(d.regs.rax, d.capture)), + else => {}, + }; + if (d.on_syscall) |hook| return try hook.func(hook.ctx, d, stop) == .stop; + return d.syscalls == .stop; +} + +// Events. + +fn emit(d: *Debugger, ev: Event, payload: []const u8) !void { + const sink = d.sink orelse return; + var e = ev; + e.ts = event.now(); + e.tid = @intCast(d.proc.tid); + try sink.emit(e, payload); +} + +/// A stop the caller is about to see, as events: the line if it changed, +/// the watched memory that changed, then the stop. +fn report(d: *Debugger, stop: Stop) !Stop { + if (d.sink == null) return stop; + if (!d.done) { + try d.emitLine(); + if (d.stack_watch > 0) try d.snapshot(d.regs.rsp, d.stack_watch); + for (d.watches.items) |w| try d.snapshot(w.addr, w.len); + } + try d.emitStop(stop); + return stop; +} + +fn emitStop(d: *Debugger, stop: Stop) !void { + const r = &d.regs; + const regs = std.mem.asBytes(r); + switch (stop) { + .step => try d.emit(.{ .kind = .step, .a = .{ r.rip, 0, 0, 0, 0, 0 } }, regs), + .breakpoint => |id| try d.emit(.{ .kind = .breakpoint, .a = .{ r.rip, id, 0, 0, 0, 0 } }, regs), + .syscall_enter => |nr| { + const text = try d.decode(nr); + try d.emit(.{ .kind = .syscall_enter, .aux = nr, .a = .{ r.rdi, r.rsi, r.rdx, r.r10, r.r8, r.r9 } }, if (text.len > 0) text else regs); + }, + .syscall_exit => |nr| try d.emit(.{ .kind = .syscall_exit, .aux = nr, .a = .{ r.rax, 0, 0, 0, 0, 0 } }, regs), + .signal => |sig| try d.emit(.{ .kind = .signal, .aux = @intCast(@backingInt(sig)), .a = .{ d.proc.faultAddress(), r.rip, 0, 0, 0, 0 } }, regs), + .exited => |code| try d.emit(.{ .kind = .exit, .a = .{ code, 0, 0, 0, 0, 0 } }, ""), + .killed => |sig| try d.emit(.{ .kind = .exit, .a = .{ 128 + @as(u64, @backingInt(sig)), 0, 0, 0, 0, 0 } }, ""), + } +} + +/// At the entry of syscall `nr`: the string or the buffer its arguments +/// point at, cut at `capture`. Empty when it takes none. Good until the +/// next call. +// shortcut: the first such argument only (rename has two), upgrade when a consumer wants the second. +pub fn decode(d: *Debugger, nr: u16) ![]const u8 { + const args = [_]u64{ d.regs.rdi, d.regs.rsi, d.regs.rdx, d.regs.r10, d.regs.r8, d.regs.r9 }; + try d.captured.resize(d.gpa, d.capture); + const buf = d.captured.items; + const text = for (syscalls_table.signature(nr), 0..) |kind, i| switch (kind) { + 's' => break d.proc.readString(args[i], buf), + 'b' => break buf[0..d.proc.read(args[i], buf[0..@min(buf.len, args[i + 1])])], + else => {}, + } else return ""; + // A payload as long as the registers is taken for them: a byte less is not. + return text[0 .. text.len - @intFromBool(text.len == @sizeOf(Regs))]; +} + +fn emitLine(d: *Debugger) !void { + const l = d.lineAt(d.regs.rip) orelse return; + const file = d.file_ids.get(l.key) orelse id: { + const path = try std.fs.path.join(d.gpa, &.{ l.dir, l.name }); + const named = d.files.getOrPut(d.gpa, path) catch |err| { + d.gpa.free(path); + return err; + }; + if (named.found_existing) d.gpa.free(path) else { + named.value_ptr.* = d.files.count(); + try d.emit(.{ .kind = .string, .a = .{ named.value_ptr.*, 0, 0, 0, 0, 0 } }, path); + } + try d.file_ids.put(d.gpa, l.key, named.value_ptr.*); + break :id named.value_ptr.*; + }; + if (file == d.last_line.file and l.line == d.last_line.line) return; + d.last_line = .{ .file = file, .line = l.line }; + try d.emit(.{ .kind = .line, .a = .{ file, l.line, l.column, d.regs.rip, 0, 0 } }, ""); +} + +/// Reads the target's mappings again: what changed goes out as `map` and +/// `unmap`, and the modules that are new are loaded. +pub fn refreshMaps(d: *Debugger) !void { + const old = try d.syms.refresh(d.proc.pid); + defer d.syms.free(old); + if (d.sink == null) return; + const now = d.syms.maps.list; + for (old.list) |o| { + for (now) |m| { + if (m.start == o.start) break; + } else try d.emit(.{ .kind = .unmap, .a = .{ o.start, o.end - o.start, 0, 0, 0, 0 } }, ""); + } + for (now) |m| { + for (old.list) |o| { + if (m.start == o.start and m.end == o.end and m.prot == o.prot and m.offset == o.offset and std.mem.eql(u8, m.name, o.name)) break; + } else try d.emit(.{ .kind = .map, .a = .{ m.start, m.end - m.start, m.prot, m.offset, 0, 0 } }, m.name); + } +} + +// Memory. + +/// The target's memory as the program has it: breakpoints do not show. +pub fn read(d: *Debugger, addr: u64, buf: []u8) usize { + const n = d.proc.read(addr, buf); + for (d.breakpoints.items) |bp| { + if (bp.addr >= addr and bp.addr - addr < n) buf[bp.addr - addr] = bp.saved; + } + return n; +} + +pub fn write(d: *Debugger, addr: u64, bytes: []const u8) !void { + return d.proc.write(addr, bytes); +} + +pub fn setRegs(d: *Debugger, regs: Regs) !void { + try d.proc.setRegs(®s); + d.regs = regs; +} + +/// Watches a region: from now on, each stop sends the words of it that changed. +pub fn watch(d: *Debugger, addr: u64, len: usize) !void { + try d.watches.append(d.gpa, .{ .addr = addr, .len = len }); +} + +/// Sends a region as it is now, in `mem_write` events: one read of the +/// target, then only the words (8 bytes, aligned) the sink was not sent +/// before or that changed since. +pub fn snapshot(d: *Debugger, addr: u64, len: usize) !void { + const start = addr & ~@as(u64, 7); + try d.scratch.resize(d.gpa, std.mem.alignForward(usize, len + (addr - start), 8)); + const bytes = d.scratch.items[0 .. d.read(start, d.scratch.items) & ~@as(usize, 7)]; + var page: *Page = undefined; + var page_index: u64 = std.math.maxInt(u64); + // Where the run of changed words being gathered began. + var run_from: ?usize = null; + var at: usize = 0; + while (at < bytes.len) : (at += 8) { + const a = start + at; + if (a / 4096 != page_index) { + page_index = a / 4096; + const entry = try d.shadow.getOrPut(d.gpa, page_index); + if (!entry.found_existing) { + errdefer d.shadow.removeByPtr(entry.key_ptr); + entry.value_ptr.* = try d.gpa.create(Page); + entry.value_ptr.*.* = .{}; + } + page = entry.value_ptr.*; + } + const slot = a % 4096 / 8; + const bit = @as(u64, 1) << @intCast(slot % 64); + const word = std.mem.readInt(u64, bytes[at..][0..8], .little); + if (page.known[slot / 64] & bit == 0 or page.words[slot] != word) { + page.known[slot / 64] |= bit; + page.words[slot] = word; + if (run_from == null) run_from = at; + } else if (run_from) |from| { + try d.emitWrite(start + from, bytes[from..at]); + run_from = null; + } + } + if (run_from) |from| try d.emitWrite(start + from, bytes[from..]); +} + +fn emitWrite(d: *Debugger, addr: u64, bytes: []const u8) !void { + var at: usize = 0; + while (at < bytes.len) : (at += write_max) { + const n = @min(write_max, bytes.len - at); + try d.emit(.{ .kind = .mem_write, .a = .{ addr + at, n, 0, 0, 0, 0 } }, bytes[at..][0..n]); + } +} + +// Breakpoints. + +/// A breakpoint at `addr`. With a hook, the hook decides whether the +/// target stops there. Returns its id: the one already at `addr` if any. +pub fn breakAt(d: *Debugger, addr: u64, hook: ?Hook) !u32 { + if (d.breakpointAt(addr)) |bp| return bp.id; + try d.insert(.{ .id = d.next_id, .addr = addr, .saved = 0, .hook = hook }); + d.next_id += 1; + return d.next_id - 1; +} + +fn insert(d: *Debugger, breakpoint: Breakpoint) !void { + var bp = breakpoint; + if (d.proc.read(bp.addr, (&bp.saved)[0..1]) != 1) return error.BadAddress; + try d.breakpoints.ensureUnusedCapacity(d.gpa, 1); + try d.proc.write(bp.addr, &.{0xcc}); + d.breakpoints.appendAssumeCapacity(bp); +} + +/// Removes a breakpoint by id. +pub fn clear(d: *Debugger, id: u32) void { + for (d.breakpoints.items, 0..) |bp, i| { + if (bp.id != id) continue; + if (!d.proc.gone) d.proc.write(bp.addr, &.{bp.saved}) catch {}; + _ = d.breakpoints.orderedRemove(i); + return; + } +} + +fn breakpointAt(d: *const Debugger, addr: u64) ?Breakpoint { + for (d.breakpoints.items) |bp| { + if (bp.addr == addr) return bp; + } + return null; +} + +// Addresses. + +/// An address from "*0x401000", "file.c:12" (the line's first code, or the +/// next line's that has any) or a function's name: past `push rbp; mov rbp, +/// rsp` when it begins so, where its frame is set up for `backtrace` and +/// its arguments are still in their registers. +pub fn resolve(d: *Debugger, spec: []const u8) !u64 { + if (std.mem.startsWith(u8, spec, "*")) return std.fmt.parseInt(u64, spec[1..], 0) catch error.BadLocation; + if (std.mem.lastIndexOfScalar(u8, spec, ':')) |colon| { + if (std.fmt.parseInt(u32, spec[colon + 1 ..], 10)) |line| { + return d.syms.lineAddress(spec[0..colon], line) orelse error.NoSuchLine; + } else |_| {} + } + const sym = d.symbol(spec) orelse return error.NoSuchSymbol; + var code: [8]u8 = @splat(0); + _ = d.read(sym.addr, &code); + // endbr64 may come first. + const at: usize = if (std.mem.eql(u8, code[0..4], &.{ 0xf3, 0x0f, 0x1e, 0xfa })) 4 else 0; + return sym.addr + if (std.mem.eql(u8, code[at..][0..4], &.{ 0x55, 0x48, 0x89, 0xe5 })) at + 4 else 0; +} + +/// A symbol by name. The mappings are read again when it is not found: a +/// library may have been loaded since. +pub fn symbol(d: *Debugger, name: []const u8) ?Symbols.Symbol { + if (d.syms.find(name)) |sym| return sym; + if (!d.done) d.refreshMaps() catch {}; + return d.syms.find(name); +} + +/// A place in memory from a number or a symbol's name: `size` is the +/// symbol's, 0 for a number. +pub fn place(d: *Debugger, text: []const u8) ?Symbols.Symbol { + if (std.fmt.parseInt(u64, text, 0)) |addr| return .{ .name = "", .addr = addr, .size = 0 } else |_| {} + return d.symbol(text); +} + +/// The source line of the code at `addr`. +pub fn lineAt(d: *Debugger, addr: u64) ?Symbols.Line { + d.know(addr); + return d.syms.lineAt(addr); +} + +/// `addr` for a reader: see `Symbols.describe`. +pub fn describe(d: *Debugger, w: *std.Io.Writer, addr: u64) !void { + d.know(addr); + return d.syms.describe(w, addr); +} + +/// An address in no mapping known is in one made since. +fn know(d: *Debugger, addr: u64) void { + if (d.done or d.syms.moduleAt(addr) != null or d.syms.mappingAt(addr) != null) return; + d.refreshMaps() catch {}; +} + +/// The call chain by frame pointer: the pc, then each return address +/// outwards. `mem` is what has the stack: anything with +/// `read(addr, buf) usize`, the debugger or a moment of a recording. +/// `at_entry` says the pc is a function's first instruction, where its +/// caller's address is still on top of the stack. +// shortcut: a function that keeps no frame hides its caller (a leaf, or one stopped inside its prologue), upgrade with the unwind tables (`std.debug.Dwarf.Unwind`). +pub fn backtrace(mem: anytype, regs: *const Regs, at_entry: bool, out: []u64) []u64 { + var n: usize = 0; + var pc = regs.rip; + var fp = regs.rbp; + var frame: [16]u8 = undefined; + if (at_entry and out.len > 1 and mem.read(regs.rsp, frame[0..8]) == 8) { + out[0] = pc; + n = 1; + pc = std.mem.readInt(u64, frame[0..8], .little); + } + while (n < out.len) { + out[n] = pc; + n += 1; + if (fp == 0 or mem.read(fp, &frame) != 16) break; + const next = std.mem.readInt(u64, frame[0..8], .little); + pc = std.mem.readInt(u64, frame[8..16], .little); + // Frames lie up the stack: one that does not is not a frame. + if (pc == 0 or (next != 0 and next <= fp)) break; + fp = next; + } + return out[0..n]; +} diff --git a/src/trace/Symbols.zig b/src/trace/Symbols.zig new file mode 100644 index 0000000..7c1e345 --- /dev/null +++ b/src/trace/Symbols.zig @@ -0,0 +1,365 @@ +//! What an address in a target means: the regions mapped into it (from +//! /proc/pid/maps), the ELF files behind them with their symbols, and their +//! DWARF line tables through `std.debug`. Addresses in and out are the +//! target's: a module's load bias is applied here. +const Symbols = @This(); + +const std = @import("std"); +const elf = std.elf; +const Dwarf = std.debug.Dwarf; + +gpa: std.mem.Allocator, +io: std.Io, +maps: Maps = .{}, +modules: std.ArrayList(Module) = .empty, +/// The line-table row `lineAt` answered from last, as target addresses. +row: struct { start: u64 = 0, len: u64 = 0, line: ?Line = null } = .{}, + +pub const Mapping = struct { + start: u64, + end: u64, + /// PROT_READ | PROT_WRITE | PROT_EXEC bits. + prot: u8, + offset: u64, + /// The file mapped, or the kernel's name for the region ("[stack]"); empty when anonymous. + name: []const u8, +}; + +/// /proc/pid/maps as last read. +pub const Maps = struct { + /// The file's text: the names in `list` point into it. + text: []u8 = &.{}, + list: []Mapping = &.{}, +}; + +pub const Symbol = struct { name: []const u8, addr: u64, size: u64 }; + +/// A row of a line table. `key` is the same for the same file of the same +/// compilation unit, and `dir` and `name` together are its path. +pub const Line = struct { key: usize, dir: []const u8, name: []const u8, line: u32, column: u32 }; + +pub const Module = struct { + path: []const u8, + /// The lowest address it is mapped at, and the end of the highest. + start: u64 = 0, + end: u64 = 0, + /// A target address minus this is the address in the file. + bias: u64 = 0, + /// Where the file says it starts running (an address in the file). + entry: u64 = 0, + /// Null when the file could not be read as ELF. + file: ?std.debug.ElfFile = null, + /// Functions and objects by address in the file. + symbols: []Symbol = &.{}, + dwarf_tried: bool = false, + + /// The line tables, opened on first use. Null without debug info. + fn dwarf(m: *Module, gpa: std.mem.Allocator) ?*Dwarf { + const file = &(m.file orelse return null); + const d = &(file.dwarf orelse return null); + if (m.dwarf_tried) return d; + m.dwarf_tried = true; + open: { + d.open(gpa, file.endian) catch break :open; + d.populateRanges(gpa, file.endian) catch break :open; + return d; + } + d.deinit(gpa); + file.dwarf = null; + return null; + } + + /// The line table of the compilation unit that holds `pc`, an address in the file. + fn lineTable(m: *Module, gpa: std.mem.Allocator, pc: u64) ?*const Dwarf.CompileUnit.SrcLocCache { + const d = m.dwarf(gpa) orelse return null; + // The ranges are sorted by start: the last that starts at or before pc. + const after = std.sort.partitionPoint(Dwarf.Range, d.ranges.items, pc, struct { + fn startsBefore(at: u64, r: Dwarf.Range) bool { + return r.start <= at; + } + }.startsBefore); + if (after == 0 or pc >= d.ranges.items[after - 1].end) return null; + const cu = &d.compile_unit_list.items[d.ranges.items[after - 1].compile_unit_index]; + d.populateSrcLocCache(gpa, m.file.?.endian, cu) catch return null; + return &cu.src_loc_cache.?; + } +}; + +fn line(table: *const Dwarf.CompileUnit.SrcLocCache, entry: Dwarf.CompileUnit.SrcLocCache.LineEntry) ?Line { + // File numbers start at 1 before DWARF 5. + const index = std.math.sub(u32, entry.file, @intFromBool(table.version < 5)) catch return null; + if (index >= table.files.len) return null; + const file = &table.files[index]; + if (file.dir_index >= table.directories.len) return null; + return .{ .key = @intFromPtr(file), .dir = table.directories[file.dir_index].path, .name = file.path, .line = entry.line, .column = entry.column }; +} + +pub fn deinit(s: *Symbols) void { + for (s.modules.items) |*m| { + if (m.file) |*f| f.deinit(s.gpa); + s.gpa.free(m.symbols); + s.gpa.free(m.path); + } + s.modules.deinit(s.gpa); + s.free(s.maps); +} + +/// Reads the process's mappings again and loads the modules that are new. +/// Returns the mappings as they were, for the caller to compare and `free`. +pub fn refresh(s: *Symbols, pid: std.os.linux.pid_t) !Maps { + var path_buf: [32]u8 = undefined; + const path = std.fmt.bufPrint(&path_buf, "/proc/{d}/maps", .{pid}) catch unreachable; + const file = try std.Io.Dir.cwd().openFile(s.io, path, .{}); + defer file.close(s.io); + var read_buf: [4096]u8 = undefined; + var reader = file.readerStreaming(s.io, &read_buf); + const new: Maps = new: { + const text = try reader.interface.allocRemaining(s.gpa, .unlimited); + errdefer s.gpa.free(text); + var list: std.ArrayList(Mapping) = .empty; + errdefer list.deinit(s.gpa); + var lines = std.mem.tokenizeScalar(u8, text, '\n'); + // 7f0000000000-7f0000001000 r-xp 00002000 08:01 1234 /usr/lib/libc.so.6 + while (lines.next()) |l| { + var fields = std.mem.tokenizeScalar(u8, l, ' '); + const range = fields.next() orelse continue; + const perms = fields.next() orelse continue; + const offset = fields.next() orelse continue; + _ = fields.next(); // device + _ = fields.next(); // inode + const dash = std.mem.indexOfScalar(u8, range, '-') orelse continue; + try list.append(s.gpa, .{ + .start = std.fmt.parseInt(u64, range[0..dash], 16) catch continue, + .end = std.fmt.parseInt(u64, range[dash + 1 ..], 16) catch continue, + .prot = @as(u8, @intFromBool(perms[0] == 'r')) | @as(u8, @intFromBool(perms[1] == 'w')) << 1 | @as(u8, @intFromBool(perms[2] == 'x')) << 2, + .offset = std.fmt.parseInt(u64, offset, 16) catch continue, + .name = fields.rest(), + }); + } + break :new .{ .text = text, .list = try list.toOwnedSlice(s.gpa) }; + }; + const old = s.maps; + s.maps = new; + s.row = .{}; + // Failing below, the mappings are as they were. + errdefer { + s.free(new); + s.maps = old; + } + + // A module is a file with code mapped from it. + for (s.maps.list) |m| { + if (m.prot & 4 == 0 or !std.mem.startsWith(u8, m.name, "/")) continue; + if (s.module(m.name) == null) try s.load(m.name); + } + for (s.modules.items) |*mod| { + mod.start = std.math.maxInt(u64); + mod.end = 0; + for (s.maps.list) |m| { + if (!std.mem.eql(u8, m.name, mod.path)) continue; + mod.start = @min(mod.start, m.start); + mod.end = @max(mod.end, m.end); + } + if (mod.end == 0) mod.start = 0; // unmapped since + } + return old; +} + +pub fn free(s: *Symbols, maps: Maps) void { + s.gpa.free(maps.list); + s.gpa.free(maps.text); +} + +fn module(s: *Symbols, path: []const u8) ?*Module { + for (s.modules.items) |*m| { + if (std.mem.eql(u8, m.path, path)) return m; + } + return null; +} + +fn load(s: *Symbols, path: []const u8) !void { + try s.modules.ensureUnusedCapacity(s.gpa, 1); + var m: Module = .{ .path = try s.gpa.dupe(u8, path) }; + errdefer s.gpa.free(m.path); + // A file that is gone or is no ELF stays a module, with nothing known about it. + if (std.Io.Dir.cwd().openFile(s.io, path, .{})) |file| { + defer file.close(s.io); + m.file = std.debug.ElfFile.load(s.gpa, s.io, file, null, &.none) catch null; + } else |_| {} + if (m.file) |*f| { + errdefer f.deinit(s.gpa); + m.symbols = readSymbols(s.gpa, f.mapped_file) catch |err| switch (err) { + error.OutOfMemory => |e| return e, + else => &.{}, + }; + if (firstLoad(f.mapped_file)) |first| { + m.entry = first.entry; + // Where the file's first segment landed tells where all of it did. + for (s.maps.list) |map| { + if (std.mem.eql(u8, map.name, path) and map.offset == first.load.offset & ~@as(u64, 4095)) { + m.bias = map.start -% (first.load.vaddr & ~@as(u64, 4095)); + break; + } + } + } + } + s.modules.appendAssumeCapacity(m); +} + +/// The file's entry point and its first loaded segment. +fn firstLoad(bytes: []const u8) ?struct { entry: u64, load: elf.Elf64.Phdr } { + var r: std.Io.Reader = .fixed(bytes); + const header = elf.Header.read(&r) catch return null; + var it = header.iterateProgramHeadersBuffer(bytes); + while (it.next() catch return null) |ph| { + if (ph.type == .LOAD) return .{ .entry = header.entry, .load = ph }; + } + return null; +} + +/// The functions and objects of .symtab, or of .dynsym in a stripped file, sorted by address. +fn readSymbols(gpa: std.mem.Allocator, bytes: []const u8) ![]Symbol { + var r: std.Io.Reader = .fixed(bytes); + const header = try elf.Header.read(&r); + if (!header.is_64 or header.endian != .little) return &.{}; + var table: ?elf.Elf64_Shdr = null; + var it = header.iterateSectionHeadersBuffer(bytes); + while (try it.next()) |sh| { + if (sh.sh_type == elf.SHT_SYMTAB or (sh.sh_type == elf.SHT_DYNSYM and table == null)) table = sh; + } + const sh = table orelse return &.{}; + const names_at = header.shoff + @as(u64, sh.sh_link) * header.shentsize; + if (names_at + @sizeOf(elf.Elf64_Shdr) > bytes.len or sh.sh_offset + sh.sh_size > bytes.len) return error.TruncatedElfFile; + const names_sh = std.mem.bytesToValue(elf.Elf64_Shdr, bytes[names_at..][0..@sizeOf(elf.Elf64_Shdr)]); + if (names_sh.sh_offset + names_sh.sh_size > bytes.len) return error.TruncatedElfFile; + const names = bytes[names_sh.sh_offset..][0..names_sh.sh_size]; + + var out: std.ArrayList(Symbol) = .empty; + errdefer out.deinit(gpa); + const count = sh.sh_size / @sizeOf(elf.Elf64.Sym); + for (std.mem.bytesAsSlice(elf.Elf64.Sym, bytes[sh.sh_offset..][0 .. count * @sizeOf(elf.Elf64.Sym)])) |sym| { + if (sym.shndx == elf.SHN_UNDEF or sym.name == 0 or sym.name >= names.len) continue; + switch (sym.info.type) { + .FUNC, .OBJECT, .GNU_IFUNC, .NOTYPE => {}, + else => continue, + } + try out.append(gpa, .{ .name = std.mem.sliceTo(names[sym.name..], 0), .addr = sym.value, .size = sym.size }); + } + std.mem.sortUnstable(Symbol, out.items, {}, struct { + fn lessThan(_: void, a: Symbol, b: Symbol) bool { + return a.addr < b.addr; + } + }.lessThan); + return out.toOwnedSlice(gpa); +} + +/// Where the program itself starts running, after its loader: the +/// executable is the first module, mapped lowest. +pub fn entryPoint(s: *const Symbols) ?u64 { + if (s.modules.items.len == 0 or s.modules.items[0].file == null) return null; + return s.modules.items[0].entry + s.modules.items[0].bias; +} + +pub fn mappingAt(s: *const Symbols, addr: u64) ?Mapping { + for (s.maps.list) |m| { + if (addr >= m.start and addr < m.end) return m; + } + return null; +} + +pub fn moduleAt(s: *Symbols, addr: u64) ?*Module { + for (s.modules.items) |*m| { + if (addr >= m.start and addr < m.end) return m; + } + return null; +} + +/// The symbol that holds `addr`. +pub fn symbolAt(s: *Symbols, addr: u64) ?Symbol { + const m = s.moduleAt(addr) orelse return null; + const pc = addr - m.bias; + const after = std.sort.partitionPoint(Symbol, m.symbols, pc, struct { + fn startsBefore(at: u64, sym: Symbol) bool { + return sym.addr <= at; + } + }.startsBefore); + // The nearest below may be a label inside the function, or an alias of it: look a few back. + var i = after; + while (i > 0 and after - i < 8) : (i -= 1) { + const sym = m.symbols[i - 1]; + if (pc - sym.addr < @max(sym.size, 1)) return .{ .name = sym.name, .addr = sym.addr + m.bias, .size = sym.size }; + } + return null; +} + +/// A symbol by name: the executable's first, then the libraries'. +pub fn find(s: *Symbols, name: []const u8) ?Symbol { + for (s.modules.items) |*m| { + if (m.end == 0) continue; + for (m.symbols) |sym| { + if (std.mem.eql(u8, sym.name, name)) return .{ .name = sym.name, .addr = sym.addr + m.bias, .size = sym.size }; + } + } + return null; +} + +/// The source line of the code at `addr`. +pub fn lineAt(s: *Symbols, addr: u64) ?Line { + // Code runs along a row for a few instructions: the last answer is often this one's too. + if (addr -% s.row.start < s.row.len) return s.row.line; + const m = s.moduleAt(addr) orelse return null; + const pc = addr - m.bias; + const table = m.lineTable(s.gpa, pc) orelse return null; + const rows = table.line_table.keys(); + const after = std.sort.partitionPoint(u64, rows, pc, struct { + fn startsBefore(at: u64, row: u64) bool { + return row <= at; + } + }.startsBefore); + if (after == 0) return null; + s.row = .{ + .start = rows[after - 1] + m.bias, + .len = if (after < rows.len) rows[after] - rows[after - 1] else pc - rows[after - 1] + 1, + .line = line(table, table.line_table.values()[after - 1]), + }; + return s.row.line; +} + +/// The first code of `file`:`wanted`, or of the next line that has any. +/// `file` matches by its last component. +// shortcut: runs every compilation unit's line program, upgrade with an index by file name when a target is large (V8). +pub fn lineAddress(s: *Symbols, file: []const u8, wanted: u32) ?u64 { + var best: ?struct { line: u32, addr: u64 } = null; + for (s.modules.items) |*m| { + const d = m.dwarf(s.gpa) orelse continue; + for (d.compile_unit_list.items) |*cu| { + d.populateSrcLocCache(s.gpa, m.file.?.endian, cu) catch continue; + const table = &cu.src_loc_cache.?; + for (table.line_table.keys(), table.line_table.values()) |pc, entry| { + if (entry.line < wanted) continue; + const addr = pc + m.bias; + if (best) |b| if (entry.line > b.line or (entry.line == b.line and addr >= b.addr)) continue; + const l = line(table, entry) orelse continue; + if (!std.mem.eql(u8, std.fs.path.basename(l.name), std.fs.path.basename(file))) continue; + best = .{ .line = entry.line, .addr = addr }; + } + } + } + return if (best) |b| b.addr else null; +} + +/// `addr` for a reader: "fib+12 (fib.c:5)", "libc.so.6!write+18", +/// "libc.so.6!27781" where no symbol covers it, "[stack]+1f40". +pub fn describe(s: *Symbols, w: *std.Io.Writer, addr: u64) !void { + try w.print("{x}", .{addr}); + if (s.moduleAt(addr)) |m| { + const sym = s.symbolAt(addr); + try w.writeAll(" "); + // The executable is the first module mapped: its symbols need no prefix. + if (sym == null or m != &s.modules.items[0]) try w.print("{s}!", .{std.fs.path.basename(m.path)}); + if (sym) |found| try w.print("{s}+{d}", .{ found.name, addr - found.addr }) else try w.print("{x}", .{addr - m.bias}); + } else if (s.mappingAt(addr)) |m| { + if (m.name.len > 0) try w.print(" {s}+{x}", .{ m.name, addr - m.start }); + } + if (s.lineAt(addr)) |l| try w.print(" ({s}:{d})", .{ std.fs.path.basename(l.name), l.line }); +} diff --git a/src/trace/ptrace.zig b/src/trace/ptrace.zig index 40a9a7a..fd7ebd1 100644 --- a/src/trace/ptrace.zig +++ b/src/trace/ptrace.zig @@ -1,28 +1,44 @@ -//! The out-of-process backend: a target run under ptrace. Start it, stop it -//! at instructions, syscalls and breakpoints, read its registers and memory. -//! x86-64 Linux. +//! The out-of-process backend: a target under ptrace. Start it or attach to +//! it, run it to its next instruction, syscall, breakpoint or signal, read +//! and write its registers and memory. The threads it makes are traced too: +//! `tid` is the one the last stop came from, and what registers and resumes +//! act on. x86-64 Linux. `Debugger` is the layer above. const std = @import("std"); const linux = std.os.linux; const event = @import("event.zig"); const Regs = event.Regs; const P = linux.PTRACE; +const WALL = 0x40000000; + pub const Stop = union(enum) { - /// A single step finished, or a breakpoint was hit. + /// A single step finished, or a breakpoint instruction ran. trap, - /// At a syscall's entry or exit (they alternate). + /// At a syscall's entry or exit: `inSyscall` tells which. syscall, + /// The thread made this new one, traced from its first instruction. + clone: linux.pid_t, /// A signal is about to be delivered; `resume_signal` holds it. signal: linux.SIG, + /// The thread is gone, and the process with it when it is the first. exited: u8, killed: linux.SIG, }; pub const Process = struct { pid: linux.pid_t, + /// The thread the last stop came from. + tid: linux.pid_t, /// The signal the next resume delivers. resume_signal: u32 = 0, - in_syscall: bool = false, + /// Traced threads alive. + threads: u32 = 1, + /// Attached to, not started: `close` lets it go on instead of killing it. + attached: bool = false, + /// The process has exited and was reaped. + gone: bool = false, + /// /proc/pid/mem, opened by the first write that needs it. + mem_fd: linux.fd_t = -1, /// Runs `argv` stopped at its first instruction. `path` is the /// executable; `argv` and `envp` are what it gets. @@ -34,61 +50,130 @@ pub const Process = struct { _ = linux.execve(path, argv, envp); linux.exit_group(127); } - var p: Process = .{ .pid = @intCast(pid) }; - switch (try p.wait()) { + var p: Process = .{ .pid = @intCast(pid), .tid = @intCast(pid) }; + switch (try p.wait(p.pid)) { // The stop exec makes under PTRACE_TRACEME. .signal, .trap => {}, else => return error.ExecFailed, } p.resume_signal = 0; - _ = try check(linux.ptrace(P.SETOPTIONS, p.pid, 0, P.O.TRACESYSGOOD | P.O.EXITKILL, 0)); + _ = try check(linux.ptrace(P.SETOPTIONS, p.pid, 0, P.O.TRACESYSGOOD | P.O.TRACECLONE | P.O.EXITKILL, 0)); + return p; + } + + /// Stops a running process and traces it from there. + // shortcut: only the thread `pid` names is attached, upgrade by walking /proc/pid/task when a threaded target needs it. + pub fn attach(pid: linux.pid_t) !Process { + _ = try check(linux.ptrace(P.ATTACH, pid, 0, 0, 0)); + var p: Process = .{ .pid = pid, .tid = pid, .attached = true }; + errdefer _ = linux.ptrace(P.DETACH, pid, 0, 0, 0); + // The SIGSTOP attaching sends. + _ = try p.wait(pid); + p.resume_signal = 0; + _ = try check(linux.ptrace(P.SETOPTIONS, pid, 0, P.O.TRACESYSGOOD | P.O.TRACECLONE, 0)); return p; } - /// One instruction. + /// Ends the session: an attached process runs on, a spawned one is killed. + pub fn close(p: *Process) void { + if (p.mem_fd >= 0) _ = linux.close(p.mem_fd); + if (p.gone) return; + if (p.attached) { + _ = linux.ptrace(P.DETACH, p.tid, 0, 0, 0); + return; + } + _ = linux.kill(p.pid, .KILL); + // Each traced thread is reaped before the process itself can be. + while (!p.gone) _ = p.waitAny() catch return; + } + + /// One instruction of the current thread. pub fn stepi(p: *Process) !Stop { - return p.run(P.SINGLESTEP); + try p.run(P.SINGLESTEP); + return p.wait(p.tid); } - /// Until the next breakpoint, signal or exit. + /// The current thread until its next breakpoint, signal or exit. pub fn cont(p: *Process) !Stop { - return p.run(P.CONT); + try p.run(P.CONT); + return p.wait(p.tid); } - /// Until the next syscall entry or exit. + /// The current thread until its next syscall entry or exit. pub fn syscall(p: *Process) !Stop { - return p.run(P.SYSCALL); + try p.run(P.SYSCALL); + return p.wait(p.tid); } - fn run(p: *Process, request: u32) !Stop { - _ = try check(linux.ptrace(request, p.pid, 0, p.resume_signal, 0)); + /// Resumes the current thread: `request` is PTRACE_CONT, SYSCALL or SINGLESTEP. + pub fn run(p: *Process, request: u32) !void { + _ = try check(linux.ptrace(request, p.tid, 0, p.resume_signal, 0)); p.resume_signal = 0; - return p.wait(); } - fn wait(p: *Process) !Stop { + /// The next stop of any traced thread. + // shortcut: with threads this waits for any child of the tracer, so one threaded target a tracer process; upgrade with a wait per known tid. + pub fn waitAny(p: *Process) !Stop { + return p.wait(if (p.threads > 1) -1 else p.pid); + } + + /// The next stop of one thread (-1: of any child), which becomes the current one. + pub fn wait(p: *Process, tid: linux.pid_t) !Stop { var status: u32 = 0; - _ = try check(linux.waitpid(p.pid, @ptrCast(&status), linux.W.UNTRACED)); - if (linux.W.IFEXITED(status)) return .{ .exited = linux.W.EXITSTATUS(status) }; - if (linux.W.IFSIGNALED(status)) return .{ .killed = linux.W.TERMSIG(status) }; + p.tid = @intCast(try check(linux.waitpid(tid, @ptrCast(&status), WALL))); + if (linux.W.IFEXITED(status) or linux.W.IFSIGNALED(status)) { + if (p.tid == p.pid) p.gone = true else p.threads -= 1; + return if (linux.W.IFEXITED(status)) .{ .exited = linux.W.EXITSTATUS(status) } else .{ .killed = linux.W.TERMSIG(status) }; + } const sig: u32 = (status >> 8) & 0xff; - if (sig == @intFromEnum(linux.SIG.TRAP) | 0x80) { - p.in_syscall = !p.in_syscall; - return .syscall; + if (sig == @backingInt(linux.SIG.TRAP) | 0x80) return .syscall; + if (sig == @backingInt(linux.SIG.TRAP)) { + if (status >> 16 != P.EVENT.CLONE) return .trap; + var child: usize = 0; + _ = try check(linux.ptrace(P.GETEVENTMSG, p.tid, 0, @intFromPtr(&child), 0)); + p.threads += 1; + return .{ .clone = @intCast(child) }; } - if (sig == @intFromEnum(linux.SIG.TRAP)) return .trap; p.resume_signal = sig; - return .{ .signal = @enumFromInt(sig) }; + return .{ .signal = @fromBackingInt(@intCast(sig)) }; + } + + /// At a `syscall` stop: true at the entry, false at the exit. + pub fn inSyscall(p: *const Process) !bool { + // The head of the kernel's `ptrace_syscall_info`: op (1 entry, 2 exit), then the instruction and stack pointers. + var info: extern struct { op: u8, pad: [3]u8, arch: u32, ip: u64, sp: u64 } = undefined; + _ = try check(linux.ptrace(P.GET_SYSCALL_INFO, p.tid, @sizeOf(@TypeOf(info)), @intFromPtr(&info), 0)); + return info.op == 1; + } + + fn siginfo(p: *const Process) ?linux.siginfo_t { + var info: linux.siginfo_t = undefined; + return if (linux.errno(linux.ptrace(P.GETSIGINFO, p.tid, 0, @intFromPtr(&info), 0)) == .SUCCESS) info else null; + } + + /// At a `signal` stop: the address a fault is about, 0 for another signal. + pub fn faultAddress(p: *const Process) u64 { + const info = p.siginfo() orelse return 0; + return switch (info.signo) { + .SEGV, .BUS, .ILL, .FPE => @intFromPtr(info.fields.sigfault.addr), + else => 0, + }; + } + + /// At a `trap` stop: true when a breakpoint instruction ran, false when a single step finished. + pub fn atBreakpoint(p: *const Process) bool { + // SI_KERNEL is x86's code for int3. Not TRAP_BRKPT: a step that ends in a syscall says that. + return if (p.siginfo()) |info| info.code == 0x80 else false; } pub fn regs(p: *const Process) !Regs { var out: Regs = undefined; - _ = try check(linux.ptrace(P.GETREGS, p.pid, 0, @intFromPtr(&out), 0)); + _ = try check(linux.ptrace(P.GETREGS, p.tid, 0, @intFromPtr(&out), 0)); return out; } pub fn setRegs(p: *const Process, r: *const Regs) !void { - _ = try check(linux.ptrace(P.SETREGS, p.pid, 0, @intFromPtr(r), 0)); + _ = try check(linux.ptrace(P.SETREGS, p.tid, 0, @intFromPtr(r), 0)); } /// The target's memory in one syscall, however long. Returns the bytes @@ -100,23 +185,28 @@ pub const Process = struct { return if (linux.errno(rc) == .SUCCESS) rc else 0; } - /// Writes through ptrace, so read-only pages (code) can be patched. - pub fn write(p: *const Process, addr: u64, bytes: []const u8) !void { - var at: usize = 0; - while (at < bytes.len) { - var word: [8]u8 = undefined; - const n = @min(8, bytes.len - at); - if (n < 8 and p.read(addr + at, &word) != 8) return error.BadAddress; - @memcpy(word[0..n], bytes[at..][0..n]); - _ = try check(linux.ptrace(P.POKEDATA, p.pid, addr + at, @bitCast(word), 0)); - at += n; - } + /// The NUL-terminated string at `addr`, cut at `buf.len`. + pub fn readString(p: *const Process, addr: u64, buf: []u8) []u8 { + // To the end of the page first: the string may end right before an unmapped one. + const first = @min(buf.len, 4096 - addr % 4096); + var n = p.read(addr, buf[0..first]); + if (n == first and std.mem.indexOfScalar(u8, buf[0..n], 0) == null) n += p.read(addr + n, buf[n..]); + return buf[0 .. std.mem.indexOfScalar(u8, buf[0..n], 0) orelse n]; } - pub fn kill(p: *Process) void { - _ = linux.kill(p.pid, .KILL); - var status: u32 = 0; - _ = linux.waitpid(p.pid, @ptrCast(&status), 0); + /// Into the target's memory in one syscall. Where the page is not + /// writable (code, for a breakpoint) through /proc/pid/mem, which a + /// tracer may write whatever the protection. + pub fn write(p: *Process, addr: u64, bytes: []const u8) !void { + const local = [1]std.posix.iovec_const{.{ .base = bytes.ptr, .len = bytes.len }}; + const remote = [1]std.posix.iovec_const{.{ .base = @ptrFromInt(addr), .len = bytes.len }}; + if (linux.process_vm_writev(p.pid, &local, &remote, 0) == bytes.len) return; + if (p.mem_fd < 0) { + var path: [32]u8 = undefined; + const name = std.fmt.bufPrintSentinel(&path, "/proc/{d}/mem", .{p.pid}, 0) catch unreachable; + p.mem_fd = @intCast(try check(linux.open(name, .{ .ACCMODE = .RDWR, .CLOEXEC = true }, 0))); + } + if (linux.pwrite(p.mem_fd, bytes.ptr, bytes.len, @intCast(addr)) != bytes.len) return error.BadAddress; } }; @@ -130,29 +220,69 @@ fn check(rc: usize) !usize { }; } +const test_argv = [_:null]?[*:0]const u8{ "/bin/true", null }; +const test_envp = [_:null]?[*:0]const u8{null}; + test "a child is stepped, read, patched and run to its exit" { - const argv = [_:null]?[*:0]const u8{ "/bin/true", null }; - const envp = [_:null]?[*:0]const u8{null}; - var p = try Process.spawn("/bin/true", &argv, &envp); - errdefer p.kill(); + var p = try Process.spawn("/bin/true", &test_argv, &test_envp); + defer p.close(); const before = try p.regs(); try std.testing.expect(before.rip != 0); try std.testing.expectEqual(Stop.trap, try p.stepi()); + try std.testing.expect(!p.atBreakpoint()); try std.testing.expect((try p.regs()).rip != before.rip); // The stack is writable and reads back. var buf: [16]u8 = undefined; - try p.write(before.rsp - 64, "0123456789abcdef"[0..11]); + try p.write(before.rsp - 64, "0123456789a\x00"); try std.testing.expectEqual(@as(usize, 16), p.read(before.rsp - 64, &buf)); try std.testing.expectEqualStrings("0123456789a", buf[0..11]); + try std.testing.expectEqualStrings("0123456789a", p.readString(before.rsp - 64, &buf)); try std.testing.expectEqual(@as(usize, 0), p.read(8, &buf)); + // Code is not writable, and is written all the same. + var code: [4]u8 = undefined; + try std.testing.expectEqual(@as(usize, 4), p.read(before.rip, &code)); + try p.write(before.rip, &.{ 0xcc, 0xcc }); + try std.testing.expectEqual(@as(usize, 16), p.read(before.rip, &buf)); + try std.testing.expectEqualSlices(u8, &.{ 0xcc, 0xcc, code[2], code[3] }, buf[0..4]); + // ... and runs: a breakpoint, told from a step. + try p.setRegs(&before); + try std.testing.expectEqual(Stop.trap, try p.cont()); + try std.testing.expect(p.atBreakpoint()); + try std.testing.expectEqual(before.rip + 1, (try p.regs()).rip); + try p.write(before.rip, &code); + try p.setRegs(&before); + try std.testing.expectEqual(Stop.syscall, try p.syscall()); + try std.testing.expect(try p.inSyscall()); + try std.testing.expectEqual(Stop.syscall, try p.syscall()); + try std.testing.expect(!try p.inSyscall()); while (true) switch (try p.cont()) { - .exited => |code| { - try std.testing.expectEqual(@as(u8, 0), code); + .exited => |code_| { + try std.testing.expectEqual(@as(u8, 0), code_); break; }, else => {}, }; + try std.testing.expect(p.gone); +} + +test "a running child is attached to and let go" { + // A child that waits to be killed: attaching is allowed to a parent whatever ptrace_scope says below 2. + const pid: linux.pid_t = @intCast(try check(linux.fork())); + if (pid == 0) { + while (true) _ = linux.pause(); + } + defer { + _ = linux.kill(pid, .KILL); + var status: u32 = 0; + _ = linux.waitpid(pid, @ptrCast(&status), 0); + } + var p = try Process.attach(pid); + try std.testing.expect((try p.regs()).rip != 0); + p.close(); + // Detached, it runs on: a second attach finds it alive. + p = try Process.attach(pid); + p.close(); } diff --git a/src/trace/root.zig b/src/trace/root.zig index 62a9fa7..fd91d9a 100644 --- a/src/trace/root.zig +++ b/src/trace/root.zig @@ -9,6 +9,9 @@ pub const store = @import("store.zig"); pub const Recorder = store.Recorder; pub const Trace = store.Trace; pub const ptrace = @import("ptrace.zig"); +pub const Debugger = @import("Debugger.zig"); +pub const Symbols = @import("Symbols.zig"); +pub const syscalls = @import("syscalls.zig"); /// Inside the target: the ring it was handed. pub const client = @import("client.zig"); /// Inside the tracer: a target running with a ring. @@ -19,6 +22,9 @@ test { _ = Ring; _ = store; _ = ptrace; + _ = Debugger; + _ = Symbols; + _ = syscalls; _ = client; _ = host; } diff --git a/src/trace/syscalls.zig b/src/trace/syscalls.zig new file mode 100644 index 0000000..2bf32b5 --- /dev/null +++ b/src/trace/syscalls.zig @@ -0,0 +1,141 @@ +//! x86-64 syscalls by number: their names from `std.os.linux.SYS`, and for +//! the common ones the shape of their arguments, enough to capture the +//! string one points at and to print a call the way strace does. +const std = @import("std"); +const linux = std.os.linux; +const event = @import("event.zig"); +const Event = event.Event; + +pub fn name(nr: u64) ?[]const u8 { + return @tagName(std.enums.fromInt(linux.SYS, nr) orelse return null); +} + +/// A letter an argument: i an int (a descriptor, a pid, a signal), d a +/// size, x a pointer or flags, s a NUL-terminated string, b a buffer as long +/// as the next argument says. Six x for a syscall not listed. +pub fn signature(nr: u64) []const u8 { + return switch (std.enums.fromInt(linux.SYS, nr) orelse return "xxxxxx") { + .getpid, .gettid, .getppid, .getuid, .geteuid, .getgid, .getegid, .sched_yield, .pause, .fork, .vfork => "", + .close, .exit, .exit_group, .dup, .fsync => "i", + .brk, .set_tid_address, .uname, .pipe, .time => "x", + .chdir, .rmdir, .unlink => "s", + .read, .readv, .writev, .getdents64 => "ixd", + .write => "ibd", + .pread64 => "ixdd", + .pwrite64 => "ibdd", + .open => "sxx", + .stat, .lstat, .access, .chmod, .mkdir => "sx", + .execve => "sxx", + .fstat => "ix", + .lseek => "idi", + .mmap => "xdxxid", + .mprotect => "xdx", + .munmap, .set_robust_list, .getcwd => "xd", + .mremap => "xddxx", + .madvise => "xdi", + .rt_sigaction, .rt_sigprocmask => "ixxd", + .ioctl, .fcntl => "ixx", + .dup2, .kill => "ii", + .tgkill => "iii", + .rename => "ss", + .readlink => "sxd", + .arch_prctl, .nanosleep, .sigaltstack => "xx", + .futex => "xiixxi", + .clock_gettime, .clock_getres => "ix", + .clock_nanosleep => "iixx", + .openat, .newfstatat, .faccessat2 => "isxx", + .unlinkat, .faccessat, .mkdirat => "isx", + .readlinkat => "isxd", + .statx => "isxxx", + .prlimit64 => "iixx", + .getrandom => "xdx", + .rseq => "xdxx", + .clone => "xxxxx", + .clone3 => "xd", + .wait4 => "ixxx", + .sched_getaffinity => "idx", + else => "xxxxxx", + }; +} + +/// A call the way strace prints it, from a `syscall_enter` event and its +/// payload: `openat(-100, "/etc/passwd", 0x80000, 0x0)`. +pub fn formatEnter(w: *std.Io.Writer, ev: *const Event, payload: []const u8) !void { + if (name(ev.aux)) |n| try w.writeAll(n) else try w.print("syscall_{d}", .{ev.aux}); + try w.writeAll("("); + // The payload is the first string or buffer, decoded; the registers when there was none to read. + var decoded: ?[]const u8 = if (payload.len == @sizeOf(event.Regs)) null else payload; + for (signature(ev.aux), 0..) |kind, i| { + if (i > 0) try w.writeAll(", "); + switch (kind) { + 'i' => try w.print("{d}", .{@as(i32, @bitCast(@as(u32, @truncate(ev.a[i]))))}), + 'd' => try w.print("{d}", .{ev.a[i]}), + 's', 'b' => if (decoded) |text| { + // Dots, as strace has them, when the buffer was longer than what was captured. + try w.print("\"{f}\"{s}", .{ std.zig.fmtString(text), if (kind == 'b' and text.len < ev.a[i + 1]) "..." else "" }); + decoded = null; + } else try w.print("0x{x}", .{ev.a[i]}), + else => try w.print("0x{x}", .{ev.a[i]}), + } + } + try w.writeAll(")"); +} + +/// A `syscall_exit` event's result: " = 3", " = 0x7f0000001000", " = -2 ENOENT". +pub fn formatExit(w: *std.Io.Writer, ev: *const Event) !void { + const ret: i64 = @bitCast(ev.a[0]); + if (ret < 0 and ret > -4096) { + try w.print(" = {d}", .{ret}); + if (std.enums.fromInt(linux.E, -ret)) |e| try w.print(" E{t}", .{e}); + } else if (ret < 0 or ret > 0xffffff) try w.print(" = 0x{x}", .{ev.a[0]}) else try w.print(" = {d}", .{ret}); +} + +/// A sink that prints each syscall a line and passes every event on. +pub const Printer = struct { + w: *std.Io.Writer, + next: ?event.Sink = null, + /// A call is printed and its result is not. + open: bool = false, + + pub fn sink(p: *Printer) event.Sink { + return .{ .ctx = p, .emitFn = emit }; + } + + fn emit(ctx: *anyopaque, ev: *const Event, payload: []const u8) anyerror!void { + const p: *Printer = @ptrCast(@alignCast(ctx)); + switch (ev.kind) { + .syscall_enter => { + // Another thread's call, or one that never returned (exit). + if (p.open) try p.w.writeAll(" ...\n"); + try formatEnter(p.w, ev, payload); + p.open = true; + }, + .syscall_exit, .exit => if (p.open) { + if (ev.kind == .exit) try p.w.writeAll(" = ?") else try formatExit(p.w, ev); + try p.w.writeAll("\n"); + try p.w.flush(); + p.open = false; + }, + else => {}, + } + if (p.next) |next| try next.emit(ev.*, payload); + } +}; + +test "a call prints the way strace prints it" { + var buf: [256]u8 = undefined; + var w: std.Io.Writer = .fixed(&buf); + var p: Printer = .{ .w = &w }; + const at_fdcwd: u64 = @as(u32, @bitCast(@as(i32, -100))); + try p.sink().emit(.{ .kind = .syscall_enter, .aux = @backingInt(linux.SYS.openat), .a = .{ at_fdcwd, 0x1000, 0x80000, 0, 0, 0 } }, "/etc/passwd"); + try p.sink().emit(.{ .kind = .syscall_exit, .aux = @backingInt(linux.SYS.openat), .a = .{ @bitCast(@as(i64, -2)), 0, 0, 0, 0, 0 } }, ""); + try p.sink().emit(.{ .kind = .syscall_enter, .aux = @backingInt(linux.SYS.write), .a = .{ 1, 0x2000, 3, 0, 0, 0 } }, "hi\n"); + try p.sink().emit(.{ .kind = .syscall_exit, .aux = @backingInt(linux.SYS.write), .a = .{ 3, 0, 0, 0, 0, 0 } }, ""); + try std.testing.expectEqualStrings( + \\openat(-100, "/etc/passwd", 0x80000, 0x0) = -2 ENOENT + \\write(1, "hi\n", 3) = 3 + \\ + , w.buffered()); + try std.testing.expectEqualStrings("exit_group", name(231).?); + try std.testing.expect(name(100_000) == null); +} -- cgit v1.3