//! 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, the live allocations a ring tells of 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 Ring = @import("Ring.zig"); const notes = @import("usdt.zig"); const Symbols = @import("Symbols.zig"); const syscalls_table = @import("syscalls.zig"); const Line = @import("store.zig").Line; const P = linux.PTRACE; gpa: std.mem.Allocator, proc: ptrace.Process, syms: Symbols, sink: ?event.Sink, /// The target's ring, when it carries a producer too (instrumentation, the /// agent): drained into the sink while the target runs and before a stop /// is reported, so its events and the stops are one recording, in order. ring: ?*Ring = null, /// 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, /// The variables the target declared through its ring, watched like them. declared: std.ArrayList(Watch) = .empty, /// The live allocations the target tells of through its ring (`--alloc`), /// by address: watched too, each with the allocator's header before it. allocations: std.ArrayList(Watch) = .empty, /// The most read of them at a stop, in bytes: a stop's cost must not grow /// with the target's heap. allocation_watch: usize = 256 << 10, 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, /// Decodes one instruction into `text`; null where there is none. Whoever /// has a disassembler sets it (the ztrace command links capstone): the /// library has none of its own. disasm: ?*const fn (code: []const u8, addr: u64, text: []u8, regs: ?*const Regs, touches: []Touch) ?Insn = null, /// What the instruction of the last stop was about to write, to be read /// back at the next: an instruction's writes, with no region watched. written: [2]Touch = undefined, written_count: usize = 0, /// The instructions above and below the pc whose text a stop records. disasm_around: usize = 8, /// Each function met, as where its instructions begin (`instructions`). functions: std.AutoHashMapUnmanaged(u64, []const u32) = .empty, /// How far a stop follows pointers, from each register and from each of /// the first `telescope_words` words of the stack: the memory they lead to /// is recorded, and each that leads into code is named. 0, the library's /// default: not at all (the commands ask for 3). telescope: u8 = 0, telescope_words: usize = 16, /// The bytes recorded each side of a place the telescope reaches (beside /// the 32 at it) or an instruction touches, no further than its mapping: /// the region a viewer shows round what a pointer leads to. telescope_around: usize = 0, /// The addresses already named, and the instructions already recorded /// with the length of each. described: std.AutoHashMapUnmanaged(u64, void) = .empty, code_len: std.AutoHashMapUnmanaged(u64, u8) = .empty, /// The static probes armed (`usdt`): what each one's hook reads. sites: std.ArrayList(*Site) = .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 }; /// An instruction decoded: its length, its text ("mov rbp, rsp"), and with /// the registers given, the memory it is about to touch. pub const Insn = struct { len: u8, text: []const u8, touches: []const Touch = &.{}, branch: Branch = .{} }; /// Where a call, a jump or a return goes. `kind`: 0 not one, 1 call, 2 /// jump, 3 return. With `indirect` the target is read from the /// instruction's memory operand; a return's is on the stack. pub const Branch = extern struct { target: u64 = 0, kind: u8 = 0, taken: u8 = 1, indirect: u8 = 0 }; /// Memory an instruction touches: `how` is 1 for a read, 2 a write, 3 both. pub const Touch = extern struct { addr: u64, size: u8, how: u8 }; 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.declared.deinit(d.gpa); d.allocations.deinit(d.gpa); d.breakpoints.deinit(d.gpa); for (d.sites.items) |site| d.gpa.destroy(site); d.sites.deinit(d.gpa); d.described.deinit(d.gpa); d.code_len.deinit(d.gpa); var decoded = d.functions.valueIterator(); while (decoded.next()) |starts| d.gpa.free(starts.*); d.functions.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.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.waitAny(); } fn waitAny(d: *Debugger) !ptrace.Stop { return d.wait(if (d.proc.threads > 1) -1 else d.proc.pid); } /// The next stop. With a ring it is polled for and the ring drained /// meanwhile: a target waiting for room in a full ring would never stop. fn wait(d: *Debugger, tid: linux.pid_t) !ptrace.Stop { const ring = d.ring orelse return d.proc.wait(tid); const tapped: event.Sink = .{ .ctx = d, .emitFn = tap }; var idle: u32 = 0; while (true) { if (try d.proc.poll(tid)) |stop| { _ = try ring.drain(tapped); return stop; } // A step is back in microseconds: look again before sleeping. idle = if (try ring.drain(tapped) > 0) 0 else idle + 1; if (idle > 64) ring.wait(200 * std.time.ns_per_us); } } /// What the target says of itself goes to the sink as it is; and a /// variable it declares (`ztrace cc --instr vars`, the agent's /// `ztrace_watch`) is watched from then on, so its bytes are recorded at /// every stop with no store instrumented: names and types from the /// compiler, values from the debugger. fn tap(ctx: *anyopaque, ev: *const Event, payload: []const u8) anyerror!void { const d: *Debugger = @ptrCast(@alignCast(ctx)); if (ev.kind == .variable and ev.a[1] > 0) declared: { const w: Watch = .{ .addr = ev.a[0], .len = @intCast(@min(ev.a[1], 4096)) }; for (d.declared.items) |have| if (have.addr == w.addr and have.len == w.len) break :declared; // A stack's addresses come round again: the oldest make room. if (d.declared.items.len >= 256) _ = d.declared.orderedRemove(0); try d.declared.append(d.gpa, w); } // An allocation is watched from its birth to its free, kept in address order. if (ev.kind == .alloc or ev.kind == .free) { const items = d.allocations.items; const at = std.sort.lowerBound(Watch, items, ev.a[0], struct { fn order(want: u64, have: Watch) std.math.Order { return std.math.order(want, have.addr); } }.order); const found = at < items.len and items[at].addr == ev.a[0]; if (ev.kind == .free) { if (found) _ = d.allocations.orderedRemove(at); } else if (found) items[at].len = @intCast(ev.a[1]) else try d.allocations.insert(d.gpa, at, .{ .addr = ev.a[0], .len = @intCast(ev.a[1]) }); } return d.sink.?.emit(ev.*, payload); } /// The live allocations as they are now, each with the 16 bytes before it /// (glibc's chunk header, musl's), and of a large one its first 4 KiB, as /// a declared variable: neighbours are read as one region, and what is /// sent of them is what changed. fn snapshotAllocations(d: *Debugger) !void { var from: u64 = 0; var to: u64 = 0; var room = d.allocation_watch; for (d.allocations.items) |a| { const start = a.addr -| 16; const end = a.addr + @min(a.len, 4096); // shortcut: past `allocation_watch` the allocations highest in memory go unread, upgrade by reading only what the instructions' `touch`es wrote. if (end - start > room) break; room -= end - start; if (start <= to) { to = @max(to, end); continue; } if (to > from) try d.snapshot(from, to - from); from = start; to = end; } if (to > from) try d.snapshot(from, to - from); } /// 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.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 (stop == .syscall_enter) switch (std.enums.fromInt(linux.SYS, stop.syscall_enter) orelse .close) { // What the kernel is given is the target's memory as it is now: whatever was sent of it before may be stale. .write, .pwrite64 => try d.snapshot(d.regs.rsi, @min(d.regs.rdx, 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(); // With the 128 bytes under the stack pointer: the red zone, a leaf's locals. if (d.stack_watch > 0) try d.snapshot(d.regs.rsp -| 128, d.stack_watch + 128); for (d.watches.items) |w| try d.snapshot(w.addr, w.len); for (d.declared.items) |w| try d.snapshot(w.addr, w.len); try d.snapshotAllocations(); try d.emitCode(); try d.emitTelescope(); } try d.emitStop(stop); return stop; } /// `snapshot` of what an instruction touches, with the region round it /// (`telescope_around`) as far as its mapping goes. fn snapshotRound(d: *Debugger, addr: u64, size: usize) !void { const m = d.syms.mappingAt(addr) orelse return d.snapshot(addr, size); const lo = @max(m.start, addr -| d.telescope_around); try d.snapshot(lo, @min(m.end, addr + size + d.telescope_around) - lo); } /// The instructions at the pc and after it, each a string (`event.codeId`) /// recorded once: what a viewer shows as the disassembly. fn emitCode(d: *Debugger) !void { const insnAt = d.disasm orelse return; // What the instruction before wrote is there to read now. for (d.written[0..d.written_count]) |t| try d.snapshotRound(t.addr, t.size); d.written_count = 0; var code: [256]u8 = undefined; var text: [192]u8 = undefined; // The instruction at the pc, against the registers it will run with: // what it reads is recorded as it is, what it writes is kept for the // stop after. if (d.read(d.regs.rip, code[0..15]) > 0) { var touches: [2]Touch = undefined; if (insnAt(code[0..15], d.regs.rip, text[1..], &d.regs, &touches)) |insn| { for (insn.touches) |t| { try d.snapshotRound(t.addr, t.size); try d.emit(.{ .kind = .touch, .aux = t.how, .a = .{ t.addr, t.size, d.regs.rip, 0, 0, 0 } }, ""); if (t.how & 2 != 0) { d.written[d.written_count] = t; d.written_count += 1; } } // Where a call, a jump or a return goes, and whether it will. const b = insn.branch; const from: ?u64 = if (b.kind == 3) d.regs.rsp else if (b.indirect != 0 and insn.touches.len > 0) insn.touches[0].addr else null; var word: [8]u8 = undefined; const target: ?u64 = if (from) |addr| (if (d.read(addr, &word) == 8) std.mem.readInt(u64, &word, .little) else null) else b.target; if (b.kind != 0) if (target) |to| { try d.nameAddress(to); try d.emit(.{ .kind = .branch, .aux = b.kind, .a = .{ to, b.taken, d.regs.rip, 0, 0, 0 } }, ""); }; } } // The instructions round the pc, in address order. Inside a function // they are known both ways, the function decoded once from its start; // elsewhere (no symbol: stripped code, a JIT's) only from the pc on. const around = d.disasm_around; if (d.syms.symbolAt(d.regs.rip)) |sym| if (sym.size > 0 and sym.size <= 1 << 16) { const starts = try d.instructions(sym, insnAt); const here: u32 = @intCast(d.regs.rip - sym.addr); const at = std.sort.binarySearch(u32, starts, here, struct { fn order(want: u32, have: u32) std.math.Order { return std.math.order(want, have); } }.order); if (at) |k| { for (k -| around..@min(starts.len, k + around + 1)) |n| { _ = try d.emitInstruction(insnAt, sym.addr + starts[n], if (n > 0) @intCast(starts[n] - starts[n - 1]) else 0); } return; } }; var addr = d.regs.rip; var back: u8 = 0; for (0..around + 1) |_| { back = (try d.emitInstruction(insnAt, addr, back)) orelse break; addr += back; } } /// Records the instruction at `addr` as a string (`event.codeId`), once: a /// byte for its length, a byte for the length of the one before it (0: /// not known), then its text; and when either is known, a zero, its source /// line (`store.Line`) and a byte for how many parameters a direct call's /// callee takes, plus one (0: not known). Returns its length; null for no /// instruction. fn emitInstruction(d: *Debugger, insnAt: @typeInfo(@TypeOf(d.disasm)).optional.child, addr: u64, back: u8) !?u8 { if (d.code_len.get(addr)) |len| return len; var code: [15]u8 = undefined; var text: [2 + 192 + 2 + @sizeOf(Line)]u8 = undefined; const n = d.read(addr, &code); const insn = insnAt(code[0..n], addr, text[2..][0..192], null, &.{}) orelse return null; text[0] = insn.len; text[1] = back; var len = 2 + insn.text.len; const b = insn.branch; const params: u8 = if (b.kind == 1 and b.indirect == 0 and b.target != 0) (if (d.syms.parameters(b.target)) |p| p +| 1 else 0) else 0; const line: Line = if (d.lineAt(addr)) |l| .{ .file = try d.fileId(l), .line = l.line, .column = l.column } else .{}; if (line.line != 0 or params != 0) { text[len] = 0; @memcpy(text[len + 1 ..][0..@sizeOf(Line)], std.mem.asBytes(&line)); text[len + 1 + @sizeOf(Line)] = params; len += 2 + @sizeOf(Line); } try d.emit(.{ .kind = .string, .a = .{ event.codeId(addr), 0, 0, 0, 0, 0 } }, text[0..len]); try d.code_len.put(d.gpa, addr, insn.len); return insn.len; } /// Where each instruction of a function begins, as offsets from its start: /// decoded once, from the first byte on, which is the only way to know /// where the instruction before another begins. fn instructions(d: *Debugger, sym: Symbols.Symbol, insnAt: @typeInfo(@TypeOf(d.disasm)).optional.child) ![]const u32 { const entry = try d.functions.getOrPut(d.gpa, sym.addr); if (entry.found_existing) return entry.value_ptr.*; errdefer d.functions.removeByPtr(entry.key_ptr); const code = try d.gpa.alloc(u8, sym.size); defer d.gpa.free(code); const n = d.read(sym.addr, code); var starts: std.ArrayList(u32) = .empty; errdefer starts.deinit(d.gpa); var text: [192]u8 = undefined; var off: usize = 0; while (off < n) { try starts.append(d.gpa, @intCast(off)); // Bytes that are no instruction (padding, a table) are stepped over one at a time. off += if (insnAt(code[off..n], sym.addr + off, &text, null, &.{})) |insn| insn.len else 1; } entry.value_ptr.* = try starts.toOwnedSlice(d.gpa); return entry.value_ptr.*; } /// What a viewer follows from the registers and the top of the stack, as /// pwndbg's telescope does: recorded here, while the memory is there to read. fn emitTelescope(d: *Debugger) !void { if (d.telescope == 0) return; const r = &d.regs; for ([_]u64{ r.rip, r.rax, r.rbx, r.rcx, r.rdx, r.rsi, r.rdi, r.rbp, r.rsp, r.r8, r.r9, r.r10, r.r11, r.r12, r.r13, r.r14, r.r15 }) |value| try d.chase(value); var words: [256]u64 = undefined; const n = d.read(r.rsp, std.mem.sliceAsBytes(words[0..@min(words.len, d.telescope_words)])) / 8; for (words[0..n]) |value| try d.chase(value); // The call chain: each frame's saved pointer and return address // recorded, the return addresses named, so a viewer walks it again. var fp = r.rbp; for (0..16) |_| { if (fp == 0 or fp & 7 != 0) break; const frame = try d.snap(fp, 16); if (frame.len < 16) break; const next = std.mem.readInt(u64, frame[0..8], .little); const ret = std.mem.readInt(u64, frame[8..16], .little); try d.chase(ret); try d.emitCall(ret); if (next <= fp) break; fp = next; } } /// The call that returns to `ret`, and the instruction there, recorded as /// instructions: an outer frame is on its call's line, `back` from `ret`. fn emitCall(d: *Debugger, ret: u64) !void { const insnAt = d.disasm orelse return; if (d.code_len.contains(ret)) return; const sym = d.syms.symbolAt(ret) orelse return; if (sym.size == 0 or sym.size > 1 << 16 or ret == sym.addr) return; const starts = try d.instructions(sym, insnAt); const k = std.sort.binarySearch(u32, starts, @as(u32, @intCast(ret - sym.addr)), struct { fn order(want: u32, have: u32) std.math.Order { return std.math.order(want, have); } }.order) orelse return; if (k == 0) return; _ = try d.emitInstruction(insnAt, sym.addr + starts[k - 1], if (k > 1) @intCast(starts[k - 1] - starts[k - 2]) else 0); _ = try d.emitInstruction(insnAt, ret, @intCast(starts[k] - starts[k - 1])); } /// Follows `value` as a pointer: a pointer into code gets its name and /// ends the chain, any other readable target is recorded (32 bytes: a word /// to follow, and enough to tell a string) and followed. fn chase(d: *Debugger, value: u64) !void { var v = value; for (0..d.telescope) |_| { const m = d.syms.mappingAt(v) orelse return; if (m.prot & 1 == 0) return; if (m.prot & 4 != 0) return d.nameAddress(v); const lo = @max(m.start, v -| d.telescope_around) & ~@as(u64, 7); const bytes = try d.snap(lo, @min(m.end, v + 32 + d.telescope_around) - lo); const off: usize = @intCast(v - lo); if (bytes.len < off + 8) return; v = std.mem.readInt(u64, bytes[off..][0..8], .little); } } /// The string whose id is `addr`: its name ("main+4"), recorded once. fn nameAddress(d: *Debugger, addr: u64) !void { if ((try d.described.getOrPut(d.gpa, addr)).found_existing) return; var buf: [256]u8 = undefined; var w: std.Io.Writer = .fixed(&buf); if (d.syms.label(&w, addr) catch false) try d.emit(.{ .kind = .string, .a = .{ addr, 0, 0, 0, 0, 0 } }, w.buffered()); } 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. /// What a vector of buffers holds (writev's), end to end, as far as `buf` goes. fn gather(d: *Debugger, vec: u64, count: u64, buf: []u8) []u8 { var len: usize = 0; for (0..@min(count, 64)) |i| { var iov: [2]u64 = undefined; if (d.proc.read(vec + i * 16, std.mem.asBytes(&iov)) != 16) break; len += d.proc.read(iov[0], buf[len..][0..@min(buf.len - len, iov[1])]); if (len == buf.len) break; } return buf[0..len]; } 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])])], 'v' => break d.gather(args[i], args[i + 1], buf), 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))]; } /// The string id of a line's file: its path, recorded the first time. fn fileId(d: *Debugger, l: Symbols.Line) !u64 { if (d.file_ids.get(l.key)) |id| return id; // A file compiled by its full path names itself whole. const path = if (std.fs.path.isAbsolute(l.name)) try d.gpa.dupe(u8, l.name) else 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.* = event.stringId(path); 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.*); return named.value_ptr.*; } fn emitLine(d: *Debugger) !void { const l = d.lineAt(d.regs.rip) orelse return; const file = try d.fileId(l); 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 { _ = try d.snap(addr, len); } /// `snapshot`, returning what was read: from `addr` rounded down to a word, /// valid until the next read. fn snap(d: *Debugger, addr: u64, len: usize) ![]const u8 { 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..]); return bytes; } 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. /// Runs the loader through to the program's entry point, where its /// libraries are mapped: their symbols and probes can be found from there. pub fn toEntry(d: *Debugger) !void { const at = d.syms.entryPoint() orelse return; if (at == d.regs.rip) return; const id = try d.breakAt(at, null); defer d.clear(id); while (true) switch (try d.cont()) { .breakpoint => |hit| if (hit == id) return, .exited, .killed => return error.Exited, else => {}, }; } const Site = struct { name: u64, args: [5]?notes.Arg }; /// Arms the static probes (USDT, DTrace's) that `spec` names, "provider:name" /// with "*" for any of either, in every module mapped now. Each hit is a /// `probe` event with its first five arguments and the registers, and the /// program runs on: what `ztrace probe` does with a uprobe and root, done /// with a breakpoint and neither. Returns how many places were armed. pub fn usdt(d: *Debugger, spec: []const u8) !usize { const colon = std.mem.indexOfScalar(u8, spec, ':') orelse return error.BadLocation; var armed: usize = 0; for (d.syms.modules.items) |m| { const path = try d.gpa.dupeSentinel(u8, m.path, 0); defer d.gpa.free(path); const elf = notes.Elf.open(path) catch continue; defer elf.close(); const found = try notes.probes(d.gpa, elf, m.bias); defer d.gpa.free(found); for (found) |p| { if (!probeNamed(spec[0..colon], p.provider) or !probeNamed(spec[colon + 1 ..], p.name)) continue; var buf: [256]u8 = undefined; const label = std.fmt.bufPrint(&buf, "{s}:{s}", .{ p.provider, p.name }) catch continue; const site = try d.gpa.create(Site); site.* = .{ .name = event.stringId(label), .args = @splat(null) }; try d.sites.append(d.gpa, site); var specs = std.mem.tokenizeScalar(u8, p.args, ' '); for (&site.args) |*arg| arg.* = notes.Arg.parse(specs.next() orelse break) catch null; try d.emit(.{ .kind = .string, .a = .{ site.name, 0, 0, 0, 0, 0 } }, label); // A program may test the semaphore before working out a probe's arguments. if (p.semaphore != 0) try d.write(p.semaphore, &.{ 1, 0 }); _ = try d.breakAt(p.pc, .{ .ctx = site, .func = atProbe }); armed += 1; } } return armed; } fn probeNamed(want: []const u8, have: []const u8) bool { return std.mem.eql(u8, want, "*") or std.mem.eql(u8, want, have); } fn atProbe(ctx: ?*anyopaque, d: *Debugger, _: Stop) anyerror!Action { const site: *const Site = @ptrCast(@alignCast(ctx.?)); var ev: Event = .{ .kind = .probe, .a = .{ site.name, 0, 0, 0, 0, 0 } }; for (site.args, ev.a[1..]) |arg, *slot| slot.* = if (arg) |a| a.fetch(&d.regs, &d.proc) orelse 0 else 0; try d.emit(ev, std.mem.asBytes(&d.regs)); return .go; } 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 { return walk(u64, mem, regs, at_entry, out); } /// A frame of the call chain: its pc, and the stack it holds, from `low` /// (the stack pointer, for the newest) up to `high`, just past its return /// address: where the caller's stack pointer was before the call (the /// CFA). `high` is `low` where the frame's end is not known. pub const Frame = struct { pc: u64, low: u64, high: u64 }; /// `backtrace`, each frame with its extent on the stack. pub fn frames(mem: anytype, regs: *const Regs, at_entry: bool, out: []Frame) []Frame { return walk(Frame, mem, regs, at_entry, out); } fn walk(comptime T: type, mem: anytype, regs: *const Regs, at_entry: bool, out: []T) []T { var n: usize = 0; var pc = regs.rip; var fp = regs.rbp; var low = regs.rsp; var frame: [16]u8 = undefined; if (at_entry and out.len > 1 and mem.read(regs.rsp, frame[0..8]) == 8) { // Its frame is the return address alone. out[0] = if (T == u64) pc else .{ .pc = pc, .low = low, .high = low + 8 }; n = 1; low += 8; pc = std.mem.readInt(u64, frame[0..8], .little); } while (n < out.len) { const known = fp != 0 and mem.read(fp, &frame) == 16; out[n] = if (T == u64) pc else .{ .pc = pc, .low = low, .high = if (known and fp >= low) fp + 16 else low }; n += 1; if (!known) break; low = @max(low, fp + 16); 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]; }