//! 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, /// glibc's heap, recorded at every stop as `heap.zig` reads it (`--heap`): null for not at all. heap: ?@import("heap.zig").Watch = null, 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 call frame information at each pc a recorded walk met, its /// function's frame recorded (null: none there); forgotten when the /// mappings change. unwound: std.AutoHashMapUnmanaged(u64, ?Symbols.Cfi) = .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(); try d.emitStart(); // 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); d.unwound.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; a call or jump into the vDSO runs to its return, as /// one (`stepOne`). pub fn stepi(d: *Debugger) !Stop { return d.report(try d.stepOne()); } /// One instruction, but one that enters the vDSO (the kernel's code mapped /// into the process: `clock_gettime`, `gettimeofday`) from outside runs it /// through to where it returns, the return address on top of the stack: /// its loops retry while the kernel's time data changes under them, which /// a stop at each instruction makes them do for as long as stops are slow. fn stepOne(d: *Debugger) !Stop { const from = d.regs.rip; const stop = try d.run(P.SINGLESTEP); if (stop != .step or !d.inVdso(d.regs.rip) or d.inVdso(from)) return stop; var word: [8]u8 = undefined; if (d.read(d.regs.rsp, &word) != 8) return stop; return d.runTo(std.mem.readInt(u64, &word, .little), d.regs.rsp); } fn inVdso(d: *const Debugger, addr: u64) bool { return if (d.syms.mappingAt(addr)) |m| std.mem.eql(u8, m.name, "[vdso]") else false; } /// 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.stepOne(); 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 or d.breakpointAt(d.regs.rip) != null) 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(); if (d.heap) |*h| try h.atStop(d); 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); // Through memory: the slot it reads, where it has a name ("open@got"). if (b.indirect != 0 and b.kind != 3) if (from) |slot| if (d.syms.symbolAt(slot) != null) try d.nameAddress(slot); 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, walked as a reader will walk it again (`Recorded`), // each return address named. var rec: Recorded = .{ .d = d }; var chain: [32]Frame = undefined; const at_entry = if (d.syms.symbolAt(r.rip)) |sym| sym.addr == r.rip else false; const found = frames(&rec, r, at_entry, &chain); if (rec.failed) |err| return err; for (found[@min(1, found.len)..]) |f| { try d.chase(f.pc); try d.emitCall(f.pc); } } /// The call that returns to `ret`, the instruction before it and the one /// at `ret`, recorded as instructions, once: a caller's rows in a descent, /// and 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 ((try d.described.getOrPut(d.gpa, event.codeId(ret))).found_existing) return; // Where its function begins: its symbol's, else its call frame information's (a stripped library's). const sym = d.syms.symbolAt(ret) orelse if (d.syms.functionAt(ret -% 1)) |f| Symbols.Symbol{ .name = "", .addr = f.start, .size = f.len } else 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; for (k -| 2..k + 1) |n| _ = try d.emitInstruction(insnAt, sym.addr + starts[n], if (n > 0) @intCast(starts[n] - starts[n - 1]) else 0); } /// 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. An /// address in a mapping not read yet (the syscalls that made it not /// followed) has its mappings read first, and one with no name is tried /// again the next time. fn nameAddress(d: *Debugger, addr: u64) !void { if (d.described.contains(addr)) return; d.know(addr); var buf: [256]u8 = undefined; var w: std.Io.Writer = .fixed(&buf); if (!(d.syms.label(&w, addr) catch false)) return; try d.described.put(d.gpa, addr, {}); 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); d.unwound.clearRetainingCapacity(); 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)]; try d.send(start, bytes); return bytes; } /// Sends the words of `bytes`, read at `start` (a word's address), that /// the sink was not sent before or that changed since. fn send(d: *Debugger, start: u64, bytes: []const u8) !void { 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. /// 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: 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. Where it also has `cfi(pc) ?Symbols.Cfi` /// (both do) a frame is walked through by its call frame information, /// which is right inside a function that keeps no frame and inside a /// prologue; where there is none for the pc (code without unwind tables, a /// JIT's, a PLT entry, a signal frame), by the frame pointer. `at_entry` /// says the pc is a function's first instruction, where its caller's /// address is still on top of the stack: the frame pointer's walk needs /// telling. 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); } /// A frame as the walk found it: where its function begins (0: not known) /// and the row of call frame information it was walked through by (null: /// by the frame pointer, its saved rbp at `high - 16`). pub const Unwound = struct { frame: Frame, function: u64 = 0, row: ?Symbols.Row = null }; /// `frames`, each with how it was walked: what tells which of its words /// are saved registers and its return address. pub fn unwind(mem: anytype, regs: *const Regs, at_entry: bool, out: []Unwound) []Unwound { return walk(Unwound, mem, regs, at_entry, out); } fn walk(comptime T: type, mem: anytype, regs: *const Regs, at_entry: bool, out: []T) []T { const Mem = switch (@typeInfo(@TypeOf(mem))) { .pointer => |p| p.child, else => @TypeOf(mem), }; // The registers known in the frame walked, by DWARF's number: rax rdx // rcx rbx rsi rdi rbp rsp, r8 to r15, the pc. In a caller only those a // call keeps are, and of them the ones its callee saved or left alone. var r: [17]?u64 = .{ regs.rax, regs.rdx, regs.rcx, regs.rbx, regs.rsi, regs.rdi, regs.rbp, regs.rsp, regs.r8, regs.r9, regs.r10, regs.r11, regs.r12, regs.r13, regs.r14, regs.r15, regs.rip }; var n: usize = 0; while (n < out.len) : (n += 1) { const pc = r[16] orelse break; if (pc == 0 and n > 0) break; const sp = r[7].?; var next: [17]?u64 = @splat(null); for ([_]u8{ 3, 6, 12, 13, 14, 15 }) |kept| next[kept] = r[kept]; // A caller's pc is a return address, which may be past the call's function. const info: ?Symbols.Cfi = if (@hasDecl(Mem, "cfi")) mem.cfi(if (n == 0) pc else pc -% 1) else null; by_cfi: { const c = info orelse break :by_cfi; const base = (if (c.row.cfa_reg < r.len) r[c.row.cfa_reg] else null) orelse break :by_cfi; const cfa = base +% @as(u64, @bitCast(@as(i64, c.row.cfa))); if (cfa <= sp or c.row.saved[6] == Symbols.lost) break :by_cfi; set(T, &out[n], .{ .frame = .{ .pc = pc, .low = sp, .high = cfa }, .function = c.function, .row = c.row }); next[7] = cfa; for (Symbols.saved_registers, c.row.saved) |reg, at| { if (at != 0) next[reg] = if (at == Symbols.lost) null else wordAt(mem, cfa +% @as(u64, @bitCast(@as(i64, at) * 8))); } r = next; continue; } if (n == 0 and at_entry) if (wordAt(mem, sp)) |ret| { // Its frame is the return address alone. set(T, &out[n], .{ .frame = .{ .pc = pc, .low = sp, .high = sp + 8 } }); next[7] = sp + 8; next[16] = ret; r = next; continue; }; // By the frame pointer: the caller's rbp and pc are at rbp, and // where its other registers are is not known. const fp = r[6] orelse 0; var frame: [16]u8 = undefined; const known = fp != 0 and mem.read(fp, &frame) == 16; set(T, &out[n], .{ .frame = .{ .pc = pc, .low = sp, .high = if (known and fp >= sp) fp + 16 else sp } }); if (!known) { n += 1; break; } const up = std.mem.readInt(u64, frame[0..8], .little); const ret = std.mem.readInt(u64, frame[8..16], .little); // Frames lie up the stack: one that does not is not a frame. if (ret == 0 or (up != 0 and up <= fp)) { n += 1; break; } next = @splat(null); next[6] = up; next[7] = @max(sp, fp + 16); next[16] = ret; r = next; } return out[0..n]; } fn set(comptime T: type, slot: *T, found: Unwound) void { slot.* = switch (T) { u64 => found.frame.pc, Frame => found.frame, else => found, }; } /// The word at `addr`, where `mem` has it. fn wordAt(mem: anytype, addr: u64) ?u64 { var bytes: [8]u8 = undefined; return if (mem.read(addr, &bytes) == 8) std.mem.readInt(u64, &bytes, .little) else null; } /// The call frame information at `pc`: what makes the debugger a `mem` the /// call chain is walked through by it. pub fn cfi(d: *Debugger, pc: u64) ?Symbols.Cfi { return d.syms.cfi(pc); } /// The target's memory as a walk of the call chain reads it, every word it /// reads recorded, and the frame of every function it goes through /// (`emitFunction`): so a reader walks the same chain from the recording. pub const Recorded = struct { d: *Debugger, failed: ?anyerror = null, /// The stack as last read, a page at a time: a walk goes up it. window: [4096]u8 = undefined, from: u64 = 0, len: usize = 0, pub fn read(rec: *Recorded, addr: u64, buf: []u8) usize { if (addr < rec.from or addr + buf.len > rec.from + rec.len) { rec.from = addr & ~@as(u64, 7); rec.len = rec.d.read(rec.from, &rec.window) & ~@as(usize, 7); if (addr + buf.len > rec.from + rec.len) return 0; } const start = addr & ~@as(u64, 7); const end = std.mem.alignForward(u64, addr + buf.len, 8); rec.d.send(start, rec.window[start - rec.from .. end - rec.from]) catch |err| { rec.failed = err; return 0; }; @memcpy(buf, rec.window[addr - rec.from ..][0..buf.len]); return buf.len; } pub fn cfi(rec: *Recorded, pc: u64) ?Symbols.Cfi { const d = rec.d; if (d.unwound.get(pc)) |known| return known; const found: ?Symbols.Cfi = if (d.syms.functionAt(pc)) |f| found: { d.emitFunction(f) catch |err| { rec.failed = err; return null; }; break :found .{ .function = f.start, .row = f.rowAt(pc) }; } else null; d.unwound.put(d.gpa, pc, found) catch |err| { rec.failed = err; }; return found; } }; /// A function's frame as a reader needs it to walk through it and to name /// its stack's words, recorded once as a string (`event.frameId` of where /// it begins): its length (4 bytes), what its locals are from (a byte, /// `Symbols.Function.base`), how many rows (2 bytes), the rows /// (`Symbols.Row`), then each local (`Symbols.Local`): its offset from the /// base, its size, the stretch of the function's code it is in, from and /// to (4 bytes each), its name and a zero. fn emitFunction(d: *Debugger, f: Symbols.Function) !void { if ((try d.described.getOrPut(d.gpa, event.frameId(f.start))).found_existing) return; var text: std.Io.Writer.Allocating = .init(d.gpa); defer text.deinit(); const w = &text.writer; try w.writeInt(u32, std.math.cast(u32, f.len) orelse 0, .little); try w.writeByte(f.base); try w.writeInt(u16, @intCast(@min(f.rows.len, std.math.maxInt(u16))), .little); try w.writeAll(std.mem.sliceAsBytes(f.rows[0..@min(f.rows.len, std.math.maxInt(u16))])); for (f.locals) |local| { try w.writeInt(i32, local.offset, .little); try w.writeInt(u32, local.size, .little); try w.writeInt(u32, local.from, .little); try w.writeInt(u32, local.to, .little); try w.writeAll(local.name); try w.writeByte(0); } try d.emit(.{ .kind = .string, .a = .{ event.frameId(f.start), 0, 0, 0, 0, 0 } }, text.written()); } /// Where the process's first stack is: the stack pointer at its exec, where /// argc is, then the `argc` pointers of argv and a zero, the `envc` of envp /// and a zero, and the `auxc` entries of the auxiliary vector (two words /// each) and the zero entry that ends it. Recorded as the string /// `event.frameId(0)`. pub const Start = extern struct { sp: u64, argc: u64, envc: u64, auxc: u64 }; fn emitStart(d: *Debugger) !void { if (d.sink == null) return; // The kernel keeps it, also for a process attached to: /proc/pid/stat's // 28th field, after the name in parentheses. var path_buf: [32]u8 = undefined; const path = std.fmt.bufPrint(&path_buf, "/proc/{d}/stat", .{d.proc.pid}) catch unreachable; const file = std.Io.Dir.cwd().openFile(d.syms.io, path, .{}) catch return; defer file.close(d.syms.io); var read_buf: [256]u8 = undefined; var reader = file.readerStreaming(d.syms.io, &read_buf); var text: [1024]u8 = undefined; const n = reader.interface.readSliceShort(&text) catch return; const name_end = std.mem.lastIndexOfScalar(u8, text[0..n], ')') orelse return; var fields = std.mem.tokenizeScalar(u8, text[name_end + 1 .. n], ' '); for (0..25) |_| _ = fields.next(); const sp = std.fmt.parseInt(u64, fields.next() orelse return, 10) catch return; var start: Start = .{ .sp = sp, .argc = wordAt(d, sp) orelse return, .envc = 0, .auxc = 0 }; const envp = sp + 8 * (start.argc + 2); while (start.envc < 1 << 16 and (wordAt(d, envp + 8 * start.envc) orelse 0) != 0) start.envc += 1; const auxv = envp + 8 * (start.envc + 1); while (start.auxc < 256 and (wordAt(d, auxv + 16 * start.auxc) orelse 0) != 0) start.auxc += 1; try d.emit(.{ .kind = .string, .a = .{ event.frameId(0), 0, 0, 0, 0, 0 } }, std.mem.asBytes(&start)); }