From 4b4113a0217ee27c78e7efddb66ff5a455d49083 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Thu, 12 Nov 2026 13:19:32 -0300 Subject: debugger: add a native GUI with live V8 JIT debugging --- src/cli/main.zig | 2 + src/cli/serve.zig | 136 ++++++++++++++++++++++++++++++++++++++++++++ src/trace/Debugger.zig | 45 +++++++++++---- src/trace/control.zig | 29 ++++++++++ src/trace/debugger_test.zig | 32 +++++++++++ src/trace/event.zig | 2 +- src/trace/root.zig | 2 + src/trace/store.zig | 23 +++++++- 8 files changed, 257 insertions(+), 14 deletions(-) create mode 100644 src/cli/serve.zig create mode 100644 src/trace/control.zig (limited to 'src') diff --git a/src/cli/main.zig b/src/cli/main.zig index 554efde..635bc25 100644 --- a/src/cli/main.zig +++ b/src/cli/main.zig @@ -6,6 +6,7 @@ const util = @import("util.zig"); const commands = .{ .record = @import("record.zig"), .dbg = @import("dbg.zig"), + .serve = @import("serve.zig"), .run = @import("run.zig"), .perf = @import("perf.zig"), .probe = @import("probe.zig"), @@ -19,6 +20,7 @@ const usage = \\ \\ record run a program under ptrace into a recording \\ dbg debug a program, recording it: step, break, look, go back + \\ serve debugger controller for the native GUI (JSON replies) \\ run record a program that carries a ring producer (agent, instrumentation) \\ perf record what the kernel sees of a program at full speed (perf events) \\ probe ... with BPF programs on syscalls, scheduling, kprobes, uprobes, USDT (root) diff --git a/src/cli/serve.zig b/src/cli/serve.zig new file mode 100644 index 0000000..2361a2f --- /dev/null +++ b/src/cli/serve.zig @@ -0,0 +1,136 @@ +//! A single ptrace owner; std.Io reads commands concurrently into a bounded mailbox. +const std = @import("std"); +const zt = @import("ztrace"); +const util = @import("util.zig"); +const linux = std.os.linux; +pub const usage = "usage: ztrace serve OUTPUT -- PROGRAM [ARGS]\n"; + +const Server = struct { + io: std.Io, + gpa: std.mem.Allocator, + input: std.Io.File, + queue: std.Io.Queue([]u8), + writer: *std.Io.Writer, + rec: *zt.Recorder, + closing: bool = false, + + fn read(s: *Server) void { + defer s.queue.close(s.io); + var buf: [4096]u8 = undefined; + var reader = s.input.readerStreaming(s.io, &buf); + while (true) { + const line = (reader.interface.takeDelimiter('\n') catch return) orelse return; + const owned = s.gpa.dupe(u8, line) catch return; + s.queue.putOne(s.io, owned) catch { + s.gpa.free(owned); + return; + }; + } + } + + fn reply(s: *Server, d: *zt.Debugger, status: zt.control.Status, reason: []const u8, elapsed: u64) !void { + try zt.control.send(s.writer, .{ .status = status, .pid = d.proc.pid, .tid = @intCast(d.proc.tid), .moments = s.rec.moments, .pc = d.regs.rip, .reason = reason, .elapsed_ns = elapsed }); + } + + fn waiting(ctx: *anyopaque, d: *zt.Debugger) !void { + const s: *Server = @ptrCast(@alignCast(ctx)); + var lines: [1][]u8 = undefined; + const n = s.queue.get(s.io, &lines, 0) catch |err| switch (err) { + error.Closed => { + s.closing = true; + try d.interrupt(); + return; + }, + else => return err, + }; + if (n == 0) return; + defer s.gpa.free(lines[0]); + const line = std.mem.trim(u8, lines[0], " \r\t"); + if (std.mem.eql(u8, line, "pause") or std.mem.eql(u8, line, "quit")) { + s.closing = std.mem.eql(u8, line, "quit"); + try d.interrupt(); + } else try s.reply(d, .running, "pause before changing the target", 0); + } +}; + +pub fn run(init: std.process.Init, args: []const [:0]const u8) !void { + if (args.len < 3 or !std.mem.eql(u8, args[1], "--")) util.fail(usage, .{}); + // Keep the protocol off the target's stdio, and close its copies on exec. + const input = try duplicate(0); + defer input.close(init.io); + const output = try duplicate(1); + defer output.close(init.io); + const null_file = try std.Io.Dir.cwd().openFile(init.io, "/dev/null", .{}); + defer null_file.close(init.io); + if (linux.errno(linux.dup2(null_file.handle, 0)) != .SUCCESS or linux.errno(linux.dup2(2, 1)) != .SUCCESS) return error.RedirectFailed; + var outbuf: [4096]u8 = undefined; + var writer = output.writerStreaming(init.io, &outbuf); + var rec = try zt.Recorder.create(init.gpa, init.io, args[0]); + defer rec.close() catch {}; + rec.cut &= ~zt.Kind.line.bit(); + var d = try zt.Debugger.spawn(init.gpa, init.io, try util.resolve(init, args[2]), try util.targetArgv(init.arena.allocator(), args[2..]), init.minimal.environ.block.slice.ptr, rec.sink()); + defer d.deinit(); + d.disasm = @import("disasm.zig").one; + d.syms.demangle = util.demangle; + d.stack_watch = 512; + d.disasm_around = 24; + d.telescope = 2; + var storage: [16][]u8 = undefined; + var server: Server = .{ .io = init.io, .gpa = init.gpa, .input = input, .queue = .init(&storage), .writer = &writer.interface, .rec = &rec }; + var reader = try std.Io.concurrent(init.io, Server.read, .{&server}); + defer { + reader.cancel(init.io); + var remaining: [16][]u8 = undefined; + const n = server.queue.get(init.io, &remaining, 0) catch 0; + for (remaining[0..n]) |line| init.gpa.free(line); + } + d.on_wait = .{ .ctx = &server, .func = Server.waiting }; + try rec.flush(); + try server.reply(&d, .stopped, "entry; set a breakpoint or continue", 0); + while (!server.closing) { + const line = server.queue.getOne(init.io) catch break; + defer init.gpa.free(line); + var words = std.mem.tokenizeAny(u8, line, " \t\r"); + const cmd = words.next() orelse continue; + if (std.mem.eql(u8, cmd, "quit")) break; + const started = std.Io.Clock.awake.now(init.io); + var reason_buf: [128]u8 = undefined; + const reason = execute(&d, &server, cmd, std.mem.trim(u8, words.rest(), " \t\r"), &reason_buf) catch |err| { + try server.reply(&d, if (d.done) .exited else .failed, @errorName(err), 0); + continue; + }; + try rec.flush(); + const elapsed: u64 = @intCast(started.durationTo(std.Io.Clock.awake.now(init.io)).toNanoseconds()); + try server.reply(&d, if (d.done) .exited else .stopped, reason, elapsed); + } +} + +fn execute(d: *zt.Debugger, s: *Server, cmd: []const u8, arg: []const u8, buf: []u8) ![]const u8 { + if (std.mem.eql(u8, cmd, "break")) { + const id = try d.breakAt(try d.resolve(arg), null); + return std.fmt.bufPrint(buf, "breakpoint {d} set", .{id}); + } else if (std.mem.eql(u8, cmd, "clear")) { + d.clear(try std.fmt.parseInt(u32, arg, 0)); + } else if (std.mem.eql(u8, cmd, "signal")) { + const sig = try std.fmt.parseInt(u32, arg, 0); + if (sig > 64) return error.InvalidSignal; + d.proc.resume_signal = sig; + } else if (std.mem.eql(u8, cmd, "continue") or std.mem.eql(u8, cmd, "stepi") or std.mem.eql(u8, cmd, "step")) { + try s.reply(d, .running, cmd, 0); + const stop = if (std.mem.eql(u8, cmd, "continue")) try d.cont() else if (std.mem.eql(u8, cmd, "stepi")) try d.stepi() else try d.step(); + return switch (stop) { + .breakpoint => |id| std.fmt.bufPrint(buf, "breakpoint {d}", .{id}), + .signal => |sig| std.fmt.bufPrint(buf, "signal {t} ({d})", .{ sig, @backingInt(sig) }), + .exited => |code| std.fmt.bufPrint(buf, "exited {d}", .{code}), + .killed => |sig| std.fmt.bufPrint(buf, "killed {t}", .{sig}), + else => @tagName(stop), + }; + } else if (!std.mem.eql(u8, cmd, "pause")) return error.UnknownCommand; + return cmd; +} + +fn duplicate(fd: linux.fd_t) !std.Io.File { + const rc = linux.fcntl(fd, linux.F.DUPFD_CLOEXEC, 3); + if (linux.errno(rc) != .SUCCESS) return error.DuplicateFailed; + return .{ .handle = @intCast(rc), .flags = .{ .nonblocking = false } }; +} diff --git a/src/trace/Debugger.zig b/src/trace/Debugger.zig index 729b93a..9368a42 100644 --- a/src/trace/Debugger.zig +++ b/src/trace/Debugger.zig @@ -51,6 +51,9 @@ 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, +/// A controller's mailbox, serviced while waiting without moving ptrace to another thread. +on_wait: ?struct { ctx: *anyopaque, func: *const fn (*anyopaque, *Debugger) anyerror!void } = null, +interrupt_sent: bool = false, /// 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 @@ -122,7 +125,7 @@ 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 } = .{}, +last_line: struct { file: u64 = 0, line: u32 = 0, tid: linux.pid_t = 0 } = .{}, pub const Stop = union(enum) { /// `stepi` or `step` finished. @@ -259,14 +262,14 @@ fn inVdso(d: *const Debugger, addr: u64) bool { /// 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 from = d.lineAt(d.regs.rip) orelse return d.stepi(); 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); + if (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 @@ -324,20 +327,29 @@ fn waitAny(d: *Debugger) !ptrace.Stop { /// 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); + if (d.ring == null and d.on_wait == null) return d.proc.wait(tid); const tapped: event.Sink = .{ .ctx = d, .emitFn = tap }; var idle: u32 = 0; while (true) { + if (d.on_wait) |hook| try hook.func(hook.ctx, d); if (try d.proc.poll(tid)) |stop| { - _ = try ring.drain(tapped); + if (d.ring) |ring| _ = 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); + const drained = if (d.ring) |ring| try ring.drain(tapped) else 0; + idle = if (drained > 0) 0 else idle +| 1; + if (idle > 64) try std.Io.sleep(d.syms.io, .fromMicroseconds(200), .awake); } } +/// Request a stop from the owning controller's wait hook. Our SIGSTOP is not redelivered. +pub fn interrupt(d: *Debugger) !void { + if (d.done or d.interrupt_sent) return; + if (linux.errno(linux.tgkill(d.proc.pid, d.proc.tid, .STOP)) != .SUCCESS) return error.InterruptFailed; + d.interrupt_sent = true; +} + /// 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 @@ -424,6 +436,11 @@ fn run(d: *Debugger, request: u32) !Stop { .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| { + if (sig == .STOP and d.interrupt_sent) { + d.interrupt_sent = false; + d.proc.resume_signal = 0; + return .{ .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; @@ -518,6 +535,8 @@ fn emit(d: *Debugger, ev: Event, payload: []const u8) !void { fn report(d: *Debugger, stop: Stop) !Stop { if (d.sink == null) return stop; if (!d.done) { + // Code loaded or JIT-compiled while running without syscall stops. + if (d.syms.mappingAt(d.regs.rip) == null) try d.refreshMaps(); try d.emitLine(); if (d.asan and d.asan_shadow == null) try d.findShadow(); // With the 128 bytes under the stack pointer: the red zone, a leaf's locals. @@ -955,11 +974,13 @@ fn fileId(d: *Debugger, l: Symbols.Line) !u64 { } 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 } }, ""); + const l = d.lineAt(d.regs.rip); + const file = if (l) |loc| try d.fileId(loc) else 0; + const line = if (l) |loc| loc.line else 0; + if (file == d.last_line.file and line == d.last_line.line and (d.proc.tid == d.last_line.tid or d.last_line.tid == 0)) return; + d.last_line = .{ .file = file, .line = line, .tid = d.proc.tid }; + // File zero clears a native source location when entering code without lines (including JIT code). + try d.emit(.{ .kind = .line, .a = .{ file, line, if (l) |loc| loc.column else 0, d.regs.rip, 0, 0 } }, ""); } /// Reads the target's mappings again: what changed goes out as `map` and diff --git a/src/trace/control.zig b/src/trace/control.zig new file mode 100644 index 0000000..1bfad4c --- /dev/null +++ b/src/trace/control.zig @@ -0,0 +1,29 @@ +//! Small control messages shared by a debugger controller and its clients. +const std = @import("std"); + +pub const Status = enum { stopped, running, exited, failed }; +pub const Reply = struct { + status: Status, + pid: i32, + tid: u32, + moments: u64, + pc: u64, + elapsed_ns: u64 = 0, + reason: []const u8 = "", +}; + +pub fn send(w: *std.Io.Writer, reply: Reply) !void { + try std.json.Stringify.value(reply, .{}, w); + try w.writeByte('\n'); + try w.flush(); +} + +test "control messages preserve 64-bit addresses" { + var buf: [512]u8 = undefined; + var w: std.Io.Writer = .fixed(&buf); + const value: Reply = .{ .status = .stopped, .pid = 1, .tid = 2, .moments = 3, .pc = 0xffffffffffffffff }; + try send(&w, value); + const parsed = try std.json.parseFromSlice(Reply, std.testing.allocator, w.buffered(), .{}); + defer parsed.deinit(); + try std.testing.expectEqual(value.pc, parsed.value.pc); +} diff --git a/src/trace/debugger_test.zig b/src/trace/debugger_test.zig index 66174fc..22b9718 100644 --- a/src/trace/debugger_test.zig +++ b/src/trace/debugger_test.zig @@ -10,6 +10,38 @@ const gpa = std.testing.allocator; const io = std.testing.io; const no_env = [_:null]?[*:0]const u8{null}; +test "source step without a source location advances one instruction" { + var d = try spawn(targets.fib_nolines, "10", null); + defer d.deinit(); + const id = try d.breakAt(try d.resolve("fib"), null); + try std.testing.expectEqual(id, (try d.cont()).breakpoint); + try std.testing.expect(d.lineAt(d.regs.rip) == null); + const before = d.regs.rip; + try std.testing.expectEqual(Debugger.Stop.step, try d.step()); + try std.testing.expect(d.regs.rip != before); +} + +test "a controller can interrupt a running target and step without redelivering SIGSTOP" { + var d = try spawn(targets.fib, "40", null); + defer d.deinit(); + const id = try d.breakAt(try d.resolve("fib"), null); + try std.testing.expectEqual(id, (try d.cont()).breakpoint); + d.clear(id); + var called = false; + d.on_wait = .{ .ctx = &called, .func = struct { + fn interrupt(ctx: *anyopaque, target: *Debugger) !void { + const flag: *bool = @ptrCast(@alignCast(ctx)); + flag.* = true; + try target.interrupt(); + } + }.interrupt }; + try std.testing.expectEqual(linux.SIG.STOP, (try d.cont()).signal); + try std.testing.expect(called); + try std.testing.expectEqual(@as(u32, 0), d.proc.resume_signal); + d.on_wait = null; + try std.testing.expectEqual(Debugger.Stop.step, try d.stepi()); +} + /// Starts a target with its stdout going nowhere: this process's own is the /// test runner's channel to the build. fn spawn(path: []const u8, arg: ?[*:0]const u8, sink: ?zt.Sink) !Debugger { diff --git a/src/trace/event.zig b/src/trace/event.zig index 2900be7..f56d0f5 100644 --- a/src/trace/event.zig +++ b/src/trace/event.zig @@ -59,7 +59,7 @@ pub const Kind = enum(u16) { /// a0=callee a1=return value. aux: how many bytes of a1 are the value /// (0: none, or not known) ret = 33, - /// a0=file string id a1=line a2=column a3=pc (0: not given) + /// a0=file string id (0 clears the location) a1=line a2=column a3=pc (0: not given) line = 34, /// a0=pc (a coverage edge) edge = 35, diff --git a/src/trace/root.zig b/src/trace/root.zig index ef684db..a64f173 100644 --- a/src/trace/root.zig +++ b/src/trace/root.zig @@ -14,6 +14,7 @@ pub const telescope = @import("telescope.zig"); /// glibc's malloc at a moment: chunks, tcache, bins, the top. pub const heap = @import("heap.zig"); pub const Debugger = @import("Debugger.zig"); +pub const control = @import("control.zig"); pub const Symbols = @import("Symbols.zig"); pub const syscalls = @import("syscalls.zig"); /// Inside the target: the ring it was handed. @@ -35,6 +36,7 @@ test { _ = telescope; _ = heap; _ = Debugger; + _ = control; _ = Symbols; _ = syscalls; _ = client; diff --git a/src/trace/store.zig b/src/trace/store.zig index e4546c2..b40a1fc 100644 --- a/src/trace/store.zig +++ b/src/trace/store.zig @@ -803,7 +803,9 @@ pub const Moment = struct { } pub fn line(m: Moment, tid: u32) !?Line { - return if ((try m.state()).threads.get(tid)) |t| t.line else null; + const t = (try m.state()).threads.get(tid) orelse return null; + const loc = t.line orelse return null; + return if (loc.file == 0) null else loc; } /// The calls a thread is inside, outermost first. @@ -1174,3 +1176,22 @@ test "a region written again costs what changed in it" { try (try trace.moment(1000)).read(0x10000, &back, null); try std.testing.expectEqualSlices(u8, &page, &back); } + +test "a cleared source line stays cleared across keyframes" { + const gpa = std.testing.allocator; + var tmp = std.testing.tmpDir(.{}); + defer tmp.cleanup(); + const path = try testPath(gpa, &tmp); + defer gpa.free(path); + var rec = try Recorder.create(gpa, std.testing.io, path); + rec.batch = 1; + try rec.emit(testEvent(.line, 1, .{ 9, 12, 5, 0, 0, 0 }), ""); + try rec.emit(testEvent(.line, 1, @splat(0)), ""); + try rec.emit(testEvent(.mark, 1, @splat(0)), ""); + try rec.close(); + var trace = try Trace.open(gpa, std.testing.io, path); + defer trace.close(); + try std.testing.expect((try (try trace.moment(2)).line(1)) == null); + try std.testing.expect((try (try trace.moment(1)).line(1)) == null); + try std.testing.expectEqual(Line{ .file = 9, .line = 12, .column = 5 }, (try (try trace.moment(0)).line(1)).?); +} -- cgit v1.3