diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-10 12:09:27 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-10 12:15:20 -0300 |
| commit | a7504c6bb2ec9e906891e42bc3df28b276e67143 (patch) | |
| tree | c13e680499badf341b17960341386b8199637671 | |
| parent | 937b6314c4cd6fa73daeac308fbfcf69b89add56 (diff) | |
| download | computeranim-a7504c6bb2ec9e906891e42bc3df28b276e67143.tar.gz computeranim-a7504c6bb2ec9e906891e42bc3df28b276e67143.zip | |
the backends together: a ring under the debugger, strings that do not collide
ztrace record and dbg take --ring, --preload and --alloc: the target gets
the ring ztrace run gives it, and the debugger drains it while the target
runs (polling for the stop, so a full ring cannot hold both) and before it
reports a stop. A program compiled by ztrace cc, with the agent preloaded,
stopped at breakpoints, is one recording in order; test-together checks it.
Recording such a program showed the debugger's file names and the pass's
strings both counted from 1: event.stringId (a hash, top bit set) is now
what every producer without a table of its own uses.
| -rw-r--r-- | README.md | 24 | ||||
| -rw-r--r-- | build.zig | 21 | ||||
| -rw-r--r-- | build/agent.zig | 4 | ||||
| -rw-r--r-- | build/llvm.zig | 6 | ||||
| -rw-r--r-- | src/agent/agent.zig | 5 | ||||
| -rw-r--r-- | src/cli/dbg.zig | 12 | ||||
| -rw-r--r-- | src/cli/record.zig | 11 | ||||
| -rw-r--r-- | src/cli/util.zig | 43 | ||||
| -rw-r--r-- | src/trace/Debugger.zig | 33 | ||||
| -rw-r--r-- | src/trace/event.zig | 9 | ||||
| -rw-r--r-- | src/trace/host.zig | 27 | ||||
| -rw-r--r-- | src/trace/ptrace.zig | 13 |
12 files changed, 179 insertions, 29 deletions
@@ -89,6 +89,30 @@ it back is 178 000 moments a second in order, a millisecond to any one. Scattered writes and new bulk data are what cost: each chunk of 64 bytes that changed is written at the next keyframe with its path in the tree. +## Together + +The backends are not modes to choose between: they feed one sink. A +program compiled by `ztrace cc`, with the agent preloaded, run under the +debugger, gives one recording, in order: the stops and their registers +(ptrace), the allocations (the agent), the lines, calls, stores and named +variables (the pass). + +```sh +ztrace cc -- clang -O0 targets/instr_list.c -o list +ztrace record --by break -b push -b reverse --alloc --preload zig-out/lib/libztrace-agent.so -- ./list +ztrace dbg --ring -- ./list # breakpoints and time travel over what the program says of itself +ztrace show out.ztrace 40 # the thread's line and calls, the live heap, each variable's bytes +zig build test-together +``` + +`--ring` (implied by `--preload` and `--alloc`) gives a target under +ptrace the ring `ztrace run` gives it; the debugger drains it while the +target runs and before it reports a stop. The agent's hooks and syscall +tracing are signals, which a debugger takes first: under ptrace, use +breakpoints and the debugger's own syscall stops. Strings never collide: +the pass counts its from 1, a symbol's name has its address as its id, and +every other producer uses `event.stringId`, a hash with the top bit set. + ## The debugger `ztrace dbg -- PROGRAM` starts a program stopped and reads commands (from a @@ -91,7 +91,24 @@ pub fn build(b: *std.Build) void { // Each area adds its own artifacts, targets and test step. @import("build/debugger.zig").add(ctx); - @import("build/agent.zig").add(ctx); - @import("build/llvm.zig").add(ctx); + const agent = @import("build/agent.zig").add(ctx); + const instrumented_list = @import("build/llvm.zig").add(ctx); + + // The backends at once: a program compiled by `ztrace cc`, the agent + // preloaded into it, the debugger stopping it at breakpoints. One + // recording holds the stops, the allocations and the program's own calls. + const together = b.addRunArtifact(exe); + together.addArgs(&.{ "record", "--by", "break", "-b", "push", "-b", "reverse", "--alloc", "--preload" }); + together.addArtifactArg(agent); + together.addArg("-o"); + const recording = together.addOutputFileArg("together.ztrace"); + together.addArg("--"); + together.addFileArg(instrumented_list); + together.expectStdErrMatch("exit 55"); + const shown = b.addRunArtifact(exe); + shown.addArg("show"); + shown.addFileArg(recording); + inline for (.{ "6 breakpoint", "5 alloc", "7 call", "7 ret", " variable", " line" }) |part| shown.expectStdOutMatch(part); + ctx.areaTest("test-together", "A debugger, the agent and instrumentation on one program").dependOn(&shown.step); @import("build/kernel.zig").add(ctx); } diff --git a/build/agent.zig b/build/agent.zig index 3fea2e2..c1e1dcc 100644 --- a/build/agent.zig +++ b/build/agent.zig @@ -4,7 +4,8 @@ const std = @import("std"); const Ctx = @import("../build.zig").Ctx; const Compile = std.Build.Step.Compile; -pub fn add(ctx: Ctx) void { +/// Returns the library to preload, for what tests it with other backends. +pub fn add(ctx: Ctx) *Compile { const b = ctx.b; const imports: []const std.Build.Module.Import = &.{.{ .name = "ztrace", .module = ctx.ztrace }}; @@ -163,6 +164,7 @@ pub fn add(ctx: Ctx) void { } bench_step.dependOn(before.?); for ([_]*Compile{ api, api_static, api_zig }) |exe| b.installArtifact(exe); + return libs[0]; } const Recording = struct { run: *std.Build.Step.Run, file: std.Build.LazyPath }; diff --git a/build/llvm.zig b/build/llvm.zig index a3e93cc..b346f13 100644 --- a/build/llvm.zig +++ b/build/llvm.zig @@ -4,7 +4,8 @@ const std = @import("std"); const Ctx = @import("../build.zig").Ctx; -pub fn add(ctx: Ctx) void { +/// Returns the instrumented list program, for what tests it with other backends. +pub fn add(ctx: Ctx) std.Build.LazyPath { const b = ctx.b; // The runtime runs inside the target at every event: optimized whatever @@ -33,6 +34,7 @@ pub fn add(ctx: Ctx) void { // A recording by name: its source, how clang optimizes it (-O2 is the // optimizer going over what the pass put in), what `ztrace cc` is told. const Target = struct { []const u8, []const u8, []const u8, []const []const u8 }; + var list: std.Build.LazyPath = undefined; for ([_]Target{ .{ "fib", "fib", "-O0", &.{} }, .{ "sort", "sort", "-O0", &.{} }, @@ -57,6 +59,7 @@ pub fn add(ctx: Ctx) void { cc.addArg("-o"); const program = cc.addOutputFileArg(b.fmt("instr_{s}", .{name})); options.addOptionPath(b.fmt("{s}_program", .{name}), program); + if (std.mem.eql(u8, name, "list")) list = program; const run = b.addRunArtifact(ctx.exe); run.addArgs(&.{ "run", "-o" }); @@ -95,4 +98,5 @@ pub fn add(ctx: Ctx) void { bench.addArtifactArg(rt); bench.addDirectoryArg(b.path("targets")); b.step("bench-llvm", "Measure the cost of compiler instrumentation").dependOn(&bench.step); + return list; } diff --git a/src/agent/agent.zig b/src/agent/agent.zig index bc53336..2a32a05 100644 --- a/src/agent/agent.zig +++ b/src/agent/agent.zig @@ -132,10 +132,7 @@ pub fn emit(kind: Kind, aux: u16, a: [6]u64, payload: []const u8) void { r.emit(.{ .ts = zt.event.now(), .tid = threadId(), .kind = kind, .aux = aux, .a = a }, payload); } -/// A string's id is its hash: no backend needs to ask another which are taken. -pub fn stringId(string: []const u8) u64 { - return std.hash.Wyhash.hash(0, string); -} +pub const stringId = zt.event.stringId; /// `bytes` as a payload: cut to `max`, and never the length of `Regs`, which /// the recorder would take for registers. diff --git a/src/cli/dbg.zig b/src/cli/dbg.zig index 007b790..6876f84 100644 --- a/src/cli/dbg.zig +++ b/src/cli/dbg.zig @@ -7,7 +7,8 @@ const fail = util.fail; const Moment = zt.store.Moment; pub const usage = - \\usage: ztrace dbg [-o FILE] [--stack BYTES] [-s BYTES] [--max-size BYTES] -- PROGRAM [ARGS] + \\usage: ztrace dbg [-o FILE] [--stack BYTES] [-s BYTES] [--max-size BYTES] + \\ [--ring] [--preload LIB] [--alloc] -- PROGRAM [ARGS] \\ ztrace dbg [-o FILE] [--stack BYTES] [-s BYTES] [--max-size BYTES] -p PID \\ \\Starts PROGRAM stopped at its first instruction (or attaches to PID) @@ -34,7 +35,7 @@ pub const usage = \\bytes (default 256) of what a syscall points at. The session ends when \\the file reaches --max-size (default 1G). \\ -; +++ util.Producer.usage; pub fn run(init: std.process.Init, args: []const [:0]const u8) !void { const arena = init.arena.allocator(); @@ -44,12 +45,15 @@ pub fn run(init: std.process.Init, args: []const [:0]const u8) !void { var stack_bytes: usize = 4096; var capture: ?usize = null; var max_bytes: ?u64 = null; + var producer: util.Producer = .{}; var i: usize = 0; while (i < args.len) : (i += 1) { const arg = args[i]; if (std.mem.eql(u8, arg, "--")) { i += 1; break; + } else if (producer.take(args, &i)) { + // Its own argument, when it has one, is taken. } else if (std.mem.eql(u8, arg, "-o") and i + 1 < args.len) { i += 1; out = args[i]; @@ -71,11 +75,13 @@ pub fn run(init: std.process.Init, args: []const [:0]const u8) !void { s.rec.cut = (s.rec.cut | zt.Kind.syscall_enter.bit()) & ~zt.Kind.line.bit(); if (max_bytes) |n| s.rec.max_bytes = n; const sink: zt.Sink = .{ .ctx = &s, .emitFn = Session.emit }; + const produced = if (pid == null) try producer.start(arena, init.minimal.environ.block.slice) else null; s.d = if (pid) |p| zt.Debugger.attach(init.gpa, init.io, p, sink) catch |err| fail("cannot attach to {d}: {t}\n", .{ p, err }) else - try zt.Debugger.spawn(init.gpa, init.io, try util.resolve(init, args[i]), try util.targetArgv(arena, args[i..]), init.minimal.environ.block.slice.ptr, sink); + try zt.Debugger.spawn(init.gpa, init.io, try util.resolve(init, args[i]), try util.targetArgv(arena, args[i..]), if (produced) |p| p.envp.ptr else init.minimal.environ.block.slice.ptr, sink); defer s.d.deinit(); + if (produced) |p| s.d.ring = p.ring; defer s.stop_payload.deinit(init.gpa); s.d.stack_watch = stack_bytes; if (capture) |n| s.d.capture = n; diff --git a/src/cli/record.zig b/src/cli/record.zig index 7b44522..8a30761 100644 --- a/src/cli/record.zig +++ b/src/cli/record.zig @@ -8,7 +8,7 @@ const fail = util.fail; pub const usage = \\usage: ztrace record [-o FILE] [--by insn|line|syscall|break] [-b WHERE]... [-w WHAT[,LEN]]... \\ [--stack BYTES] [-s BYTES] [--steps N] [--max-size BYTES] [--strace] - \\ -- PROGRAM [ARGS] + \\ [--ring] [--preload LIB] [--alloc] -- PROGRAM [ARGS] \\ \\Runs PROGRAM under ptrace into a recording (default out.ztrace). --by \\says where it stops, each stop a moment: @@ -27,7 +27,7 @@ pub const usage = \\--steps ends the recording after N moments, and --max-size when the \\file is that large (default 1G). Sizes take a suffix: 64K, 4G. \\ -; +++ util.Producer.usage; pub fn run(init: std.process.Init, args: []const [:0]const u8) !void { const arena = init.arena.allocator(); @@ -40,6 +40,7 @@ pub fn run(init: std.process.Init, args: []const [:0]const u8) !void { var strace = false; var breaks: std.ArrayList([]const u8) = .empty; var watches: std.ArrayList([]const u8) = .empty; + var producer: util.Producer = .{}; var i: usize = 0; while (i < args.len) : (i += 1) { const arg = args[i]; @@ -51,6 +52,8 @@ pub fn run(init: std.process.Init, args: []const [:0]const u8) !void { by = .syscall; } else if (std.mem.eql(u8, arg, "--strace")) { strace = true; + } else if (producer.take(args, &i)) { + // Its own argument, when it has one, is taken. } else if (value == null) { fail(usage, .{}); } else if (std.mem.eql(u8, arg, "-o")) { @@ -86,8 +89,10 @@ pub fn run(init: std.process.Init, args: []const [:0]const u8) !void { var stderr = std.Io.File.stderr().writer(init.io, &stderr_buf); var printer: zt.syscalls.Printer = .{ .w = &stderr.interface, .next = rec.sink() }; - var d = try zt.Debugger.spawn(init.gpa, init.io, path, argv, init.minimal.environ.block.slice.ptr, if (strace) printer.sink() else rec.sink()); + const produced = try producer.start(arena, init.minimal.environ.block.slice); + var d = try zt.Debugger.spawn(init.gpa, init.io, path, argv, if (produced) |p| p.envp.ptr else init.minimal.environ.block.slice.ptr, if (strace) printer.sink() else rec.sink()); defer d.deinit(); + if (produced) |p| d.ring = p.ring; d.syscalls = if (by == .syscall) .stop else .record; d.stack_watch = stack_bytes; if (capture) |n| d.capture = n; diff --git a/src/cli/util.zig b/src/cli/util.zig index abdedd1..1d7ee4c 100644 --- a/src/cli/util.zig +++ b/src/cli/util.zig @@ -1,5 +1,6 @@ //! What every command needs. const std = @import("std"); +const zt = @import("ztrace"); pub fn fail(comptime fmt: []const u8, args: anytype) noreturn { std.debug.print(fmt, args); @@ -19,6 +20,48 @@ pub fn resolve(init: std.process.Init, name: [:0]const u8) ![*:0]const u8 { fail("{s}: not found in PATH\n", .{name}); } +/// A ring for a target run under the debugger: for one that carries a +/// producer too, so what it emits and the debugger's stops are one recording. +pub const Producer = struct { + wanted: bool = false, + preload: ?[]const u8 = null, + alloc: bool = false, + + pub const usage = + \\--ring gives PROGRAM a shared-memory ring, as `ztrace run` does: for a + \\program compiled by `ztrace cc` or linked with the agent, whose own + \\events are then recorded between the stops. --preload LIB puts the + \\agent into it, and --alloc has the agent record allocations. (The + \\agent's hooks and syscalls are signals, which a debugger takes first: + \\under ptrace use breakpoints and the debugger's own syscall stops.) + \\ + ; + + /// Takes `args[i.*]` when it is one of these options. + pub fn take(p: *Producer, args: []const [:0]const u8, i: *usize) bool { + const arg = args[i.*]; + if (std.mem.eql(u8, arg, "--ring")) { + p.wanted = true; + } else if (std.mem.eql(u8, arg, "--alloc")) { + p.wanted = true; + p.alloc = true; + } else if (std.mem.eql(u8, arg, "--preload") and i.* + 1 < args.len) { + i.* += 1; + p.wanted = true; + p.preload = args[i.*]; + } else return false; + return true; + } + + /// The ring and the environment that hands it to the target. + pub fn start(p: Producer, arena: std.mem.Allocator, env: [:null]const ?[*:0]const u8) !?struct { ring: *zt.Ring, envp: [:null]const ?[*:0]const u8 } { + if (!p.wanted) return null; + const ring = try arena.create(zt.Ring); + ring.* = try zt.Ring.create(1 << 24); + return .{ .ring = ring, .envp = try zt.host.environment(arena, env, ring, p.preload, if (p.alloc) &.{"ZTRACE_ALLOC=1"} else &.{}) }; + } +}; + /// The arguments after a command's own, as the target's argv. pub fn targetArgv(arena: std.mem.Allocator, args: []const [:0]const u8) ![:null]?[*:0]const u8 { const argv = try arena.allocSentinel(?[*:0]const u8, args.len, null); diff --git a/src/trace/Debugger.zig b/src/trace/Debugger.zig index b2cdd5e..d69adcc 100644 --- a/src/trace/Debugger.zig +++ b/src/trace/Debugger.zig @@ -29,6 +29,7 @@ const event = @import("event.zig"); const Event = event.Event; const Regs = event.Regs; const ptrace = @import("ptrace.zig"); +const Ring = @import("Ring.zig"); const Symbols = @import("Symbols.zig"); const syscalls_table = @import("syscalls.zig"); const P = linux.PTRACE; @@ -37,6 +38,10 @@ 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, @@ -207,12 +212,32 @@ fn resumeThread(d: *Debugger, request: u32) !ptrace.Stop { if (d.breakpointAt(d.regs.rip)) |bp| { try d.proc.write(bp.addr, &.{bp.saved}); try d.proc.run(P.SINGLESTEP); - const stop = try d.proc.wait(d.proc.tid); + 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.proc.waitAny(); + 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); + var idle: u32 = 0; + while (true) { + if (try d.proc.poll(tid)) |stop| { + _ = try ring.drain(d.sink.?); + return stop; + } + // A step is back in microseconds: look again before sleeping. + idle = if (try ring.drain(d.sink.?) > 0) 0 else idle + 1; + if (idle > 64) ring.wait(200 * std.time.ns_per_us); + } } /// Runs the target with `request` until something stops it for the caller. @@ -224,7 +249,7 @@ fn run(d: *Debugger, request: u32) !Stop { while (true) { const before = d.regs; const tid = d.proc.tid; - const raw = if (resumes) try d.resumeThread(request) else try d.proc.waitAny(); + const raw = if (resumes) try d.resumeThread(request) else try d.waitAny(); resumes = true; switch (raw) { .exited, .killed => { @@ -386,7 +411,7 @@ fn emitLine(d: *Debugger) !void { return err; }; if (named.found_existing) d.gpa.free(path) else { - named.value_ptr.* = d.files.count(); + 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.*); diff --git a/src/trace/event.zig b/src/trace/event.zig index 4a9f6f7..9ce8e94 100644 --- a/src/trace/event.zig +++ b/src/trace/event.zig @@ -159,6 +159,15 @@ pub const Regs = extern struct { } }; +/// The id of a string, for a producer that keeps no table: its text's +/// hash, with the top bit set. The instrumentation counts its strings from +/// 1, and a symbol's name is the string whose id is its address; a hash up +/// here meets neither, so the producers of one recording (a debugger, an +/// agent and instrumentation at once) never define an id twice. +pub fn stringId(text: []const u8) u64 { + return std.hash.Wyhash.hash(0, text) | 1 << 63; +} + pub fn now() u64 { var ts: std.os.linux.timespec = undefined; _ = std.os.linux.clock_gettime(.MONOTONIC, &ts); diff --git a/src/trace/host.zig b/src/trace/host.zig index df2f845..7c43663 100644 --- a/src/trace/host.zig +++ b/src/trace/host.zig @@ -16,6 +16,22 @@ pub const Options = struct { stop_mask: u64 = 0, }; +/// `env` with the ring in it, the agent preloaded when there is one, and +/// `extra` (settings for the agent) after them. +pub fn environment(arena: std.mem.Allocator, env: [:null]const ?[*:0]const u8, ring: *const Ring, preload: ?[]const u8, extra: []const [*:0]const u8) ![:null]const ?[*:0]const u8 { + var envp: std.ArrayList(?[*:0]const u8) = .empty; + for (env) |v| { + const s = std.mem.span(v.?); + if (std.mem.startsWith(u8, s, client.env_fd ++ "=")) continue; + if (preload != null and std.mem.startsWith(u8, s, "LD_PRELOAD=")) continue; + try envp.append(arena, v); + } + try envp.append(arena, try std.fmt.allocPrintSentinel(arena, client.env_fd ++ "={d}", .{ring.fd}, 0)); + if (preload) |lib| try envp.append(arena, try std.fmt.allocPrintSentinel(arena, "LD_PRELOAD={s}", .{lib}, 0)); + for (extra) |v| try envp.append(arena, v); + return envp.toOwnedSliceSentinel(arena, null); +} + pub const Session = struct { ring: Ring, pid: linux.pid_t, @@ -27,16 +43,7 @@ pub const Session = struct { var ring = try Ring.create(options.ring_bytes); errdefer ring.close(); ring.hdr.stop_mask.store(options.stop_mask, .monotonic); - var envp: std.ArrayList(?[*:0]const u8) = .empty; - for (env) |v| { - const s = std.mem.span(v.?); - if (std.mem.startsWith(u8, s, client.env_fd ++ "=")) continue; - if (options.preload != null and std.mem.startsWith(u8, s, "LD_PRELOAD=")) continue; - try envp.append(arena, v); - } - try envp.append(arena, try std.fmt.allocPrintSentinel(arena, client.env_fd ++ "={d}", .{ring.fd}, 0)); - if (options.preload) |lib| try envp.append(arena, try std.fmt.allocPrintSentinel(arena, "LD_PRELOAD={s}", .{lib}, 0)); - const block = try envp.toOwnedSliceSentinel(arena, null); + const block = try environment(arena, env, &ring, options.preload, &.{}); const rc = linux.fork(); if (linux.errno(rc) != .SUCCESS) return error.Fork; diff --git a/src/trace/ptrace.zig b/src/trace/ptrace.zig index fd7ebd1..ca3dc39 100644 --- a/src/trace/ptrace.zig +++ b/src/trace/ptrace.zig @@ -119,8 +119,19 @@ pub const Process = struct { /// The next stop of one thread (-1: of any child), which becomes the current one. pub fn wait(p: *Process, tid: linux.pid_t) !Stop { + return (try p.next(tid, WALL)).?; + } + + /// The same without waiting: null while nothing has stopped. + pub fn poll(p: *Process, tid: linux.pid_t) !?Stop { + return p.next(tid, WALL | linux.W.NOHANG); + } + + fn next(p: *Process, tid: linux.pid_t, flags: u32) !?Stop { var status: u32 = 0; - p.tid = @intCast(try check(linux.waitpid(tid, @ptrCast(&status), WALL))); + const stopped = try check(linux.waitpid(tid, @ptrCast(&status), flags)); + if (stopped == 0) return null; + p.tid = @intCast(stopped); if (linux.W.IFEXITED(status) or linux.W.IFSIGNALED(status)) { if (p.tid == p.pid) p.gone = true else p.threads -= 1; return if (linux.W.IFEXITED(status)) .{ .exited = linux.W.EXITSTATUS(status) } else .{ .killed = linux.W.TERMSIG(status) }; |
