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/record.zig | 158 +++++++++++++++++++++++++++++++++-------------------- 1 file changed, 100 insertions(+), 58 deletions(-) (limited to 'src/cli/record.zig') 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, }); } -- cgit v1.3