summaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
Diffstat (limited to 'src')
-rw-r--r--src/agent/agent.zig164
-rw-r--r--src/agent/check.zig263
-rw-r--r--src/agent/hook.zig150
-rw-r--r--src/agent/lib.zig212
-rw-r--r--src/agent/signal.zig116
-rw-r--r--src/agent/sud.zig129
-rw-r--r--src/agent/symbols.zig158
-rw-r--r--src/agent/watch.zig130
-rw-r--r--src/cli/run.zig208
9 files changed, 1513 insertions, 17 deletions
diff --git a/src/agent/agent.zig b/src/agent/agent.zig
new file mode 100644
index 0000000..ecf2768
--- /dev/null
+++ b/src/agent/agent.zig
@@ -0,0 +1,164 @@
+//! The in-process backend: code that lives inside the target, preloaded
+//! (libztrace-agent.so), linked in (libztrace-agent.a), or imported by a Zig
+//! program (this module). When the process starts it attaches the ring its
+//! tracer handed it and turns on what `ztrace run` asked for through
+//! ZTRACE_* variables; with no ring it does nothing.
+//!
+//! Raw syscalls only, no libc, no allocation: this code runs inside malloc
+//! and inside signal handlers.
+const std = @import("std");
+const linux = std.os.linux;
+const zt = @import("ztrace");
+const client = zt.client;
+const Kind = zt.Kind;
+pub const symbols = @import("symbols.zig");
+pub const signal = @import("signal.zig");
+pub const sud = @import("sud.zig");
+pub const hook = @import("hook.zig");
+pub const regions = @import("watch.zig");
+
+/// Null when nothing traces the process: every entry point returns at once.
+pub var ring: ?*zt.Ring = null;
+/// `alloc` and `free` events wanted (the library's interposed malloc asks).
+pub var allocations = false;
+/// The kinds that end a moment in the recording (ZTRACE_CUT): watched memory
+/// is brought up to date before each.
+var cut: u64 = 0;
+/// 0 not started, 1 starting, 2 started.
+var state: std.atomic.Value(u8) = .init(0);
+threadlocal var started = false;
+
+/// The most bytes an event of ours carries; more is cut short, or split.
+pub const max_payload = 1024;
+
+/// Every entry point comes through here first. A Zig program that wants its
+/// hooks and syscalls from the start calls it at the top of main; for the
+/// rest the library has a constructor.
+pub fn init() void {
+ if (state.load(.acquire) != 0 or state.cmpxchgStrong(0, 1, .acquire, .monotonic) != null) return;
+ defer state.store(2, .release);
+ const r = client.get() orelse return;
+ var buf: [1 << 16]u8 = undefined;
+ const env = client.environ(&buf);
+ cut = if (client.getenv(env, "ZTRACE_CUT")) |v| std.fmt.parseInt(u64, v, 0) catch 0 else 0;
+ ring = r;
+
+ var maps = symbols.Maps.open(null) orelse return;
+ while (maps.next()) |m| emit(.map, 0, .{ m.start, m.end - m.start, m.prot, m.offset, 0, 0 }, text(m.path));
+ maps.close();
+ threadStart();
+
+ if (client.getenv(env, "ZTRACE_WATCH")) |list| {
+ var specs = std.mem.tokenizeScalar(u8, list, ',');
+ while (specs.next()) |spec| {
+ const region = symbols.find(null, spec) orelse symbols.Symbol{ .addr = 0, .size = 0 };
+ if (region.size != 0) watch(@as([*]const u8, @ptrFromInt(region.addr))[0..region.size], spec) else unknown(spec);
+ }
+ }
+ if (client.getenv(env, "ZTRACE_HOOKS")) |list| {
+ var specs = std.mem.tokenizeScalar(u8, list, ',');
+ while (specs.next()) |spec| {
+ if (symbols.find(null, spec)) |function| hook.add(function.addr) else unknown(spec);
+ }
+ }
+ allocations = client.getenv(env, "ZTRACE_ALLOC") != null;
+ if (client.getenv(env, "ZTRACE_SYSCALLS") != null) {
+ sud.enable();
+ sud.selector = sud.block;
+ }
+}
+
+/// The user asked for something that is not there: say so where they will see it.
+fn unknown(spec: []const u8) void {
+ for ([_][]const u8{ "ztrace agent: nothing called ", spec, "\n" }) |part| _ = linux.write(2, part.ptr, part.len);
+}
+
+pub fn threadId() u32 {
+ return client.threadId();
+}
+
+/// The calling thread's first sign of life. Once per thread, whoever notices it first.
+pub fn threadStart() void {
+ if (started) return;
+ started = true;
+ emit(.thread_start, 0, .{ threadId(), 0, 0, 0, 0, 0 }, "");
+ sud.arm();
+}
+
+/// In a forked child, which remembers being its parent.
+pub fn forked() void {
+ const tid: u32 = @intCast(linux.gettid());
+ if (tid == client.tid) return;
+ client.tid = tid;
+ started = false;
+ threadStart();
+}
+
+pub fn emit(kind: Kind, aux: u16, a: [6]u64, payload: []const u8) void {
+ const r = ring orelse return;
+ // What the agent does to get an event out (a futex when the ring is
+ // full, or to wake the tracer) is not the target's doing.
+ const was = sud.selector;
+ sud.selector = sud.allow;
+ defer sud.selector = was;
+ if (cut & kind.bit() != 0) regions.diff();
+ 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);
+}
+
+/// `bytes` as a payload: cut to `max_payload`, and never the length of
+/// `Regs`, which the recorder would take for registers.
+pub fn text(bytes: []const u8) []const u8 {
+ const len = @min(bytes.len, max_payload);
+ return bytes[0 .. len - @intFromBool(len == @sizeOf(zt.Regs))];
+}
+
+/// `mem_write` events: `bytes` is what is at `addr` now.
+pub fn write(addr: u64, bytes: []const u8) void {
+ var at: usize = 0;
+ while (at < bytes.len) : (at += max_payload) {
+ const part = bytes[at..@min(bytes.len, at + max_payload)];
+ emit(.mem_write, 0, .{ addr + at, part.len, 0, 0, 0, 0 }, part);
+ }
+}
+
+// The target's side: what a program that links the agent calls. The same
+// three are in include/ztrace.h for C.
+
+/// A point in the run worth a moment: a `mark` event with a text and a value.
+pub fn mark(label: []const u8, value: u64) void {
+ init();
+ emit(.mark, 0, .{ value, 0, 0, 0, 0, 0 }, text(label));
+}
+
+/// Names `memory` (a `variable` event), records it, and keeps recording what
+/// changes in it: only the bytes that changed, before each event that ends a
+/// moment. It must stay mapped. Watched from inside a hooked call, it is
+/// forgotten when that call returns.
+pub fn watch(memory: []const u8, name: []const u8) void {
+ init();
+ if (ring == null) return;
+ const was = sud.selector;
+ sud.selector = sud.allow;
+ defer sud.selector = was;
+ const id = stringId(name);
+ emit(.string, 0, .{ id, 0, 0, 0, 0, 0 }, text(name));
+ emit(.variable, 0, .{ @intFromPtr(memory.ptr), memory.len, id, 0, 0, 0 }, "");
+ write(@intFromPtr(memory.ptr), memory);
+ regions.add(memory, threadId(), hook.open());
+}
+
+/// Records `memory` as it is now, once.
+pub fn snapshot(memory: []const u8) void {
+ init();
+ write(@intFromPtr(memory.ptr), memory);
+}
+
+test {
+ _ = symbols;
+ _ = regions;
+}
diff --git a/src/agent/check.zig b/src/agent/check.zig
new file mode 100644
index 0000000..1a972f0
--- /dev/null
+++ b/src/agent/check.zig
@@ -0,0 +1,263 @@
+//! The agent's tests: what a recording made through it has to contain.
+//! `zig build test-agent` records real targets under `ztrace run` and runs
+//! this on each recording: `check SCENARIO FILE [ARGUMENT]`.
+const std = @import("std");
+const zt = @import("ztrace");
+const expect = std.testing.expect;
+const expectEqual = std.testing.expectEqual;
+const expectEqualStrings = std.testing.expectEqualStrings;
+
+const Item = struct { moment: u64, ev: zt.Event, payload: []const u8 };
+
+const Recording = struct {
+ arena: std.mem.Allocator,
+ trace: *zt.Trace,
+ items: []const Item,
+
+ fn count(r: Recording, kind: zt.Kind) usize {
+ var n: usize = 0;
+ for (r.items) |item| n += @intFromBool(item.ev.kind == kind);
+ return n;
+ }
+
+ /// The address ranges of the file whose path ends in `name`.
+ fn mapped(r: Recording, name: []const u8) ![]const [2]u64 {
+ var ranges: std.ArrayList([2]u64) = .empty;
+ for (r.items) |item| {
+ if (item.ev.kind == .map and std.mem.endsWith(u8, item.payload, name)) try ranges.append(r.arena, .{ item.ev.a[0], item.ev.a[0] + item.ev.a[1] });
+ }
+ return ranges.items;
+ }
+
+ /// The `variable` event of the variable called `name`.
+ fn variable(r: Recording, name: []const u8) !Item {
+ var id: ?u64 = null;
+ for (r.items) |item| {
+ if (item.ev.kind == .string and std.mem.eql(u8, item.payload, name)) id = item.ev.a[0];
+ if (item.ev.kind == .variable and item.ev.a[2] == id) return item;
+ }
+ return error.NoSuchVariable;
+ }
+
+ /// The 16 numbers the sorting targets sort, as recorded at `moment`.
+ fn numbers(r: Recording, moment: u64, addr: u64) ![16]i32 {
+ var out: [16]i32 = undefined;
+ var known: [64]bool = undefined;
+ try (try r.trace.moment(moment)).read(addr, std.mem.asBytes(&out), &known);
+ try expect(std.mem.allEqual(bool, &known, true));
+ return out;
+ }
+};
+
+fn within(ranges: []const [2]u64, addr: u64) bool {
+ for (ranges) |range| {
+ if (addr >= range[0] and addr < range[1]) return true;
+ }
+ return false;
+}
+
+fn fib(n: u64) u64 {
+ return if (n < 2) n else fib(n - 1) + fib(n - 2);
+}
+
+pub fn main(init: std.process.Init) !void {
+ const arena = init.arena.allocator();
+ const args = try init.minimal.args.toSlice(arena);
+ if (args.len < 3) return error.Usage;
+ var trace = try zt.Trace.open(init.gpa, init.io, args[2]);
+ defer trace.close();
+ var items: std.ArrayList(Item) = .empty;
+ for (0..trace.len) |index| {
+ var events = try (try trace.moment(index)).events(arena);
+ while (events.next()) |item| try items.append(arena, .{ .moment = index, .ev = item.ev, .payload = item.payload });
+ }
+ const r: Recording = .{ .arena = arena, .trace = &trace, .items = items.items };
+ const argument: []const u8 = if (args.len > 3) args[3] else "";
+
+ // Whatever was asked for, the agent says where things are and who runs.
+ try expect(r.count(.map) >= 3);
+ try expect(r.count(.thread_start) >= 1);
+
+ const scenario = args[1];
+ if (std.mem.eql(u8, scenario, "list")) {
+ try list(r, try std.fmt.parseInt(usize, argument, 10));
+ } else if (std.mem.eql(u8, scenario, "fib")) {
+ try calls(r, try std.fmt.parseInt(u64, argument, 10));
+ } else if (std.mem.eql(u8, scenario, "sort")) {
+ try sorted(r, argument);
+ } else if (std.mem.eql(u8, scenario, "api")) {
+ try annotated(r);
+ } else if (std.mem.eql(u8, scenario, "syscalls")) {
+ try syscalls(r);
+ } else return error.NoSuchScenario;
+}
+
+/// agent_list N: N nodes allocated and freed, and nothing the program
+/// allocated left alive.
+fn list(r: Recording, n: usize) !void {
+ const program = try r.mapped("agent_list");
+ try expect(program.len > 0);
+ const Block = struct { size: u64, pc: u64 };
+ var live: std.AutoHashMapUnmanaged(u64, Block) = .empty;
+ var nodes: usize = 0;
+ var own: usize = 0;
+ var resized: usize = 0;
+ for (r.items) |item| switch (item.ev.kind) {
+ .alloc => {
+ const ptr = item.ev.a[0];
+ const pc = item.ev.a[2];
+ const how: zt.event.Alloc = @enumFromInt(item.ev.aux);
+ // Only a realloc in place may name a pointer that is alive.
+ if (live.contains(ptr)) {
+ try expectEqual(zt.event.Alloc.realloc, how);
+ resized += 1;
+ }
+ try live.put(r.arena, ptr, .{ .size = item.ev.a[1], .pc = pc });
+ if (!within(program, pc)) continue;
+ own += 1;
+ if (how == .malloc and item.ev.a[1] == 16) nodes += 1;
+ },
+ .free => {
+ // What was allocated before the agent attached is not ours to know.
+ const block = live.fetchRemove(item.ev.a[0]) orelse continue;
+ if (within(program, block.value.pc)) try expect(within(program, item.ev.a[1]));
+ },
+ else => {},
+ };
+ try expectEqual(n, nodes);
+ // The nodes, the vector, the two aligned blocks, and the vector again each time it grew.
+ try expect(own >= n + 3 + resized);
+ var left = live.valueIterator();
+ while (left.next()) |block| try expect(!within(program, block.pc));
+}
+
+/// agent_fib N hooked at fib: every call with its argument, every return
+/// with fib of that argument, each a moment.
+fn calls(r: Recording, n: u64) !void {
+ var stack: std.ArrayList(u64) = .empty;
+ var seen: u64 = 0;
+ var last_moment: ?u64 = null;
+ for (r.items) |item| switch (item.ev.kind) {
+ .call => {
+ const regs = std.mem.bytesToValue(zt.Regs, item.payload);
+ try expectEqual(item.ev.a[0], regs.rip);
+ try expectEqual(item.ev.a[2], regs.rsp);
+ if (stack.items.len == 0) try expectEqual(n, regs.rdi) else try expect(regs.rdi + 1 == stack.getLast() or regs.rdi + 2 == stack.getLast());
+ try stack.append(r.arena, regs.rdi);
+ seen += 1;
+ try expect(last_moment == null or item.moment > last_moment.?);
+ last_moment = item.moment;
+ // The recorder folded the registers into the moment the call ends.
+ try expectEqual(regs.rdi, (try (try r.trace.moment(item.moment)).regs(item.ev.tid)).?.rdi);
+ },
+ .ret => {
+ try expectEqual(fib(stack.pop().?), item.ev.a[1]);
+ try expect(item.moment > last_moment.?);
+ last_moment = item.moment;
+ },
+ else => {},
+ };
+ try expectEqual(@as(usize, 0), stack.items.len);
+ try expectEqual(2 * fib(n + 1) - 1, seen);
+}
+
+/// A sorting target: the variable `name` is a permutation of 0..15 at every
+/// moment, changes along the way, and ends sorted.
+fn sorted(r: Recording, name: []const u8) !void {
+ const variable = try r.variable(name);
+ try expectEqual(@as(u64, 64), variable.ev.a[1]);
+ var before = try r.numbers(variable.moment, variable.ev.a[0]);
+ var states: usize = 1;
+ for (variable.moment..r.trace.len) |moment| {
+ const now = try r.numbers(moment, variable.ev.a[0]);
+ var present: u16 = 0;
+ for (now) |v| present |= @as(u16, 1) << @intCast(v);
+ try expectEqual(@as(u16, 0xffff), present);
+ states += @intFromBool(!std.mem.eql(i32, &now, &before));
+ before = now;
+ }
+ try expect(states >= 8);
+ try expect(std.sort.isSorted(i32, &before, {}, std.sort.asc(i32)));
+}
+
+/// agent_api: a mark after each insertion, by when the prefix up to it is
+/// sorted in the recording; the snapshot of the checksum; the array sorted
+/// at the end.
+fn annotated(r: Recording) !void {
+ const variable = try r.variable("numbers");
+ var next: u64 = 1;
+ var checksum: ?u64 = null;
+ for (r.items) |item| switch (item.ev.kind) {
+ .mark => if (std.mem.eql(u8, item.payload, "inserted")) {
+ try expectEqual(next, item.ev.a[0]);
+ const now = try r.numbers(item.moment, variable.ev.a[0]);
+ try expect(std.sort.isSorted(i32, now[0 .. next + 1], {}, std.sort.asc(i32)));
+ next += 1;
+ } else {
+ try expectEqualStrings("done", item.payload);
+ try expectEqual(checksum.?, item.ev.a[0]);
+ },
+ // The snapshot: 8 bytes that are not in the array.
+ .mem_write => if (item.ev.a[1] == 8 and item.ev.a[0] -% variable.ev.a[0] >= 64) {
+ checksum = std.mem.readInt(u64, item.payload[0..8], .little);
+ },
+ else => {},
+ };
+ try expectEqual(@as(u64, 16), next);
+ try sorted(r, "numbers");
+}
+
+/// agent_sys: what it wrote, from which thread, and every syscall entered
+/// is left, innermost first.
+fn syscalls(r: Recording) !void {
+ const main_tid = for (r.items) |item| {
+ if (item.ev.kind == .thread_start) break item.ev.tid;
+ } else unreachable;
+ var open: std.AutoHashMapUnmanaged(u32, std.ArrayList(Item)) = .empty;
+ var written: std.AutoArrayHashMapUnmanaged(u32, std.ArrayList(u8)) = .empty;
+ var fd: ?u64 = null;
+ for (r.items) |item| switch (item.ev.kind) {
+ .thread_start => try expectEqual(@as(u64, item.ev.tid), item.ev.a[0]),
+ .syscall_enter => {
+ const stack = try open.getOrPutValue(r.arena, item.ev.tid, .empty);
+ try stack.value_ptr.append(r.arena, item);
+ },
+ .syscall_exit => {
+ const result = item.ev.a[0];
+ const enter = (if (open.getPtr(item.ev.tid)) |stack| stack.pop() else null) orelse {
+ // A forked child's first event is its side of the parent's clone.
+ try expectEqual(@intFromEnum(std.os.linux.SYS.clone), item.ev.aux);
+ try expectEqual(@as(u64, 0), result);
+ continue;
+ };
+ try expectEqual(enter.ev.aux, item.ev.aux);
+ switch (@as(std.os.linux.SYS, @enumFromInt(item.ev.aux))) {
+ .openat => if (std.mem.eql(u8, enter.payload, "/dev/null")) {
+ fd = result;
+ },
+ .write => if (enter.ev.a[0] == fd) {
+ try expectEqual(enter.ev.a[2], result);
+ try expectEqual(result, enter.payload.len);
+ const text = try written.getOrPutValue(r.arena, item.ev.tid, .empty);
+ try text.value_ptr.appendSlice(r.arena, enter.payload);
+ },
+ .getpid => try expectEqual(@as(u64, main_tid), result),
+ else => {},
+ }
+ },
+ else => {},
+ };
+ // Only a thread's last syscall has no exit.
+ var stacks = open.valueIterator();
+ while (stacks.next()) |stack| {
+ if (stack.items.len == 0) continue;
+ try expectEqual(@as(usize, 1), stack.items.len);
+ const last: std.os.linux.SYS = @enumFromInt(stack.items[0].ev.aux);
+ try expect(last == .exit or last == .exit_group);
+ }
+ try expectEqual(@as(usize, 3), r.count(.thread_start));
+ try expectEqual(@as(usize, 3), written.count());
+ try expectEqualStrings("hello from main\nmasked\nsignal\nchild exited 3\n", written.get(main_tid).?.items);
+ try expectEqualStrings("thread\n", written.values()[1].items);
+ try expectEqualStrings("child\n", written.values()[2].items);
+}
diff --git a/src/agent/hook.zig b/src/agent/hook.zig
new file mode 100644
index 0000000..d11ddbd
--- /dev/null
+++ b/src/agent/hook.zig
@@ -0,0 +1,150 @@
+//! Function hooks: `call` and `ret` events for chosen functions, with the
+//! registers at entry (the first six integer arguments among them) and the
+//! return value.
+//!
+//! Entry is a breakpoint: the function's first byte becomes int3, and the
+//! SIGTRAP handler runs here, in the target, with every register in hand. It
+//! needs no instruction decoding, so it works on any function, whatever its
+//! prologue. The handler then lets the replaced instruction run: emulated
+//! when it is `push %rbp` or `endbr64` (how compiled functions start), else
+//! the byte is put back for a single step. Return needs no trap: the entry
+//! handler swaps the return address on the stack for `returned`, which emits
+//! the event and jumps to the real one.
+//!
+//! shortcut: a signal per call, about a microsecond. For hooks on hot
+//! functions, copy the prologue to a trampoline and patch a jump in (this
+//! needs an x86-64 instruction-length decoder, to move whole instructions and
+//! fix their rip-relative operands).
+const std = @import("std");
+const linux = std.os.linux;
+const agent = @import("agent.zig");
+const signal = @import("signal.zig");
+const sud = @import("sud.zig");
+const watch = @import("watch.zig");
+
+const Hook = struct { addr: usize, first: [4]u8 };
+var hooks: [64]Hook = undefined;
+var count: usize = 0;
+
+/// A hooked call that has not returned: where its return address lives, and
+/// the real one.
+const Frame = struct { slot: usize, ret: usize, callee: usize };
+// shortcut: calls nested deeper than this are not reported; grow the stack on demand if a target recurses further.
+threadlocal var frames: [1024]Frame = @splat(.{ .slot = 0, .ret = 0, .callee = 0 });
+threadlocal var depth: u32 = 0;
+
+/// Hooked calls the calling thread has open.
+pub fn open() u32 {
+ return depth;
+}
+
+/// `addr` must be a function's first instruction, and nothing may jump back
+/// to it from inside the function.
+pub fn add(addr: usize) void {
+ if (count == hooks.len) return;
+ for (hooks[0..count]) |h| {
+ if (h.addr == addr) return;
+ }
+ listen();
+ // Left writable: a single step puts the first byte back for a moment.
+ const page = addr & ~@as(usize, 4095);
+ if (linux.errno(linux.mprotect(@ptrFromInt(page), 4096, .{ .READ = true, .WRITE = true, .EXEC = true })) != .SUCCESS) return;
+ const code: *[4]u8 = @ptrFromInt(addr);
+ hooks[count] = .{ .addr = addr, .first = code.* };
+ count += 1;
+ code[0] = 0xcc;
+}
+
+var listening = false;
+
+/// SIGTRAP is the agent's from here on: breakpoints, and single steps (its own and sud.zig's).
+pub fn listen() void {
+ if (!listening) signal.install(.TRAP, onTrap);
+ listening = true;
+}
+
+fn onTrap(_: i32, info: *const linux.siginfo_t, uc: *signal.Ucontext) callconv(.c) void {
+ const TRAP_TRACE = 2;
+ if (info.code == TRAP_TRACE) {
+ // A single step ended: over a hooked function's first instruction,
+ // or over a syscall the dispatcher let through.
+ for (hooks[0..count]) |h| @as(*u8, @ptrFromInt(h.addr)).* = 0xcc;
+ uc.eflags &= ~@as(u64, signal.trap_flag);
+ sud.stepped(uc);
+ return;
+ }
+ const hook = for (hooks[0..count]) |*h| {
+ if (h.addr == uc.rip - 1) break h;
+ } else {
+ // A breakpoint of the target's own: again, without us.
+ signal.install(.TRAP, null);
+ uc.rip -= 1;
+ return;
+ };
+ uc.rip = hook.addr;
+ if (depth < frames.len) {
+ const slot: *usize = @ptrFromInt(uc.rsp);
+ agent.emit(.call, 0, .{ hook.addr, slot.*, uc.rsp, 0, 0, 0 }, std.mem.asBytes(&uc.regs()));
+ frames[depth] = .{ .slot = uc.rsp, .ret = slot.*, .callee = hook.addr };
+ depth += 1;
+ slot.* = @intFromPtr(&returned);
+ }
+ if (hook.first[0] == 0x55) {
+ // push %rbp
+ uc.rsp -= 8;
+ @as(*u64, @ptrFromInt(uc.rsp)).* = uc.rbp;
+ uc.rip += 1;
+ } else if (std.mem.eql(u8, &hook.first, &.{ 0xf3, 0x0f, 0x1e, 0xfa })) {
+ // endbr64: nothing to do while indirect-branch tracking is off, as it is in user space.
+ uc.rip += 4;
+ } else {
+ // shortcut: while the byte is back another thread can enter unseen; a relocated copy of the instruction would close that.
+ @as(*u8, @ptrFromInt(hook.addr)).* = hook.first[0];
+ uc.eflags |= signal.trap_flag;
+ }
+}
+
+/// Where a hooked function returns to, in place of its caller. rax and rdx
+/// and xmm0 and xmm1 hold what it returns: kept. (A 256-bit return value
+/// would lose its upper half to the code called here.)
+fn returned() callconv(.naked) void {
+ asm volatile (
+ \\ pushq %%rax
+ \\ pushq %%rax
+ \\ pushq %%rdx
+ \\ subq $40, %%rsp
+ \\ movdqu %%xmm0, (%%rsp)
+ \\ movdqu %%xmm1, 16(%%rsp)
+ \\ movq %%rax, %%rdi
+ \\ leaq 64(%%rsp), %%rsi
+ \\ callq %[onReturn:P]
+ \\ movq %%rax, 56(%%rsp)
+ \\ movdqu (%%rsp), %%xmm0
+ \\ movdqu 16(%%rsp), %%xmm1
+ \\ addq $40, %%rsp
+ \\ popq %%rdx
+ \\ popq %%rax
+ \\ retq
+ :
+ : [onReturn] "X" (&onReturn),
+ );
+}
+
+/// `sp` is the stack pointer the function returned with. Returns where it
+/// meant to return to.
+fn onReturn(value: u64, sp: usize) callconv(.c) usize {
+ const was = sud.selector;
+ sud.selector = sud.allow;
+ defer sud.selector = was;
+ while (true) {
+ depth -= 1;
+ const frame = frames[depth];
+ // Frames below `sp` were left without returning (longjmp): they end here too.
+ const ours = frame.slot + 8 == sp or depth == 0;
+ agent.emit(.ret, 0, .{ frame.callee, if (ours) value else 0, 0, 0, 0, 0 }, "");
+ if (ours) {
+ watch.drop(agent.threadId(), depth);
+ return frame.ret;
+ }
+ }
+}
diff --git a/src/agent/lib.zig b/src/agent/lib.zig
new file mode 100644
index 0000000..c497cf4
--- /dev/null
+++ b/src/agent/lib.zig
@@ -0,0 +1,212 @@
+//! The agent as a library for programs that have a libc: the C side of the
+//! target's API (include/ztrace.h), and the libc functions it stands in
+//! front of: the allocator (`alloc` and `free` events with the caller's pc),
+//! pthread_create (`thread_start`, `thread_exit`) and fork.
+//!
+//! Preloaded, the library's `malloc` shadows libc's and finds it with
+//! dlsym(RTLD_NEXT). Linked in statically nothing can shadow libc, so the
+//! target is linked with `-Wl,--wrap=malloc` (and so on): its calls then go
+//! to `__wrap_malloc` here, which calls `__real_malloc`.
+const std = @import("std");
+const builtin = @import("builtin");
+const zt = @import("ztrace");
+const agent = @import("agent.zig");
+
+const preloaded = builtin.link_mode == .dynamic;
+
+/// A failed check says so and ends the process: no stack traces, no std I/O,
+/// from inside somebody else's program.
+pub const panic = std.debug.FullPanic(struct {
+ fn panic(message: []const u8, _: ?usize) noreturn {
+ @branchHint(.cold);
+ const linux = std.os.linux;
+ _ = linux.write(2, "ztrace agent: ", 14);
+ _ = linux.write(2, message.ptr, message.len);
+ _ = linux.write(2, "\n", 1);
+ linux.exit_group(134);
+ }
+}.panic);
+
+/// Runs when the program is loaded, before main.
+export const ztrace_agent_init linksection(".init_array") = [1]*const fn () callconv(.c) void{loaded};
+
+fn loaded() callconv(.c) void {
+ agent.init();
+}
+
+export fn ztrace_mark(label: [*:0]const u8, value: u64) void {
+ agent.mark(std.mem.span(label), value);
+}
+
+export fn ztrace_watch(ptr: [*]const u8, len: usize, name: [*:0]const u8) void {
+ agent.watch(ptr[0..len], std.mem.span(name));
+}
+
+export fn ztrace_snapshot(ptr: [*]const u8, len: usize) void {
+ agent.snapshot(ptr[0..len]);
+}
+
+const Start = *const fn (?*anyopaque) callconv(.c) ?*anyopaque;
+
+/// libc's own, by name.
+const Real = struct {
+ malloc: ?*const fn (usize) callconv(.c) ?*anyopaque,
+ calloc: ?*const fn (usize, usize) callconv(.c) ?*anyopaque,
+ realloc: ?*const fn (?*anyopaque, usize) callconv(.c) ?*anyopaque,
+ free: ?*const fn (?*anyopaque) callconv(.c) void,
+ posix_memalign: ?*const fn (*?*anyopaque, usize, usize) callconv(.c) c_int,
+ aligned_alloc: ?*const fn (usize, usize) callconv(.c) ?*anyopaque,
+ memalign: ?*const fn (usize, usize) callconv(.c) ?*anyopaque,
+ pthread_create: ?*const fn (*anyopaque, ?*const anyopaque, Start, ?*anyopaque) callconv(.c) c_int,
+ fork: ?*const fn () callconv(.c) c_int,
+};
+var real: Real = undefined;
+/// 0 not looked up, 1 looking up, 2 found.
+var found: std.atomic.Value(u8) = .init(0);
+
+/// False while the lookup itself is running: dlsym allocates, and lands here.
+fn ready() bool {
+ if (found.load(.acquire) == 2) return true;
+ if (found.cmpxchgStrong(0, 1, .acquire, .monotonic) != null) return false;
+ inline for (@typeInfo(Real).@"struct".field_names) |name| {
+ const T = @FieldType(Real, name);
+ @field(real, name) = if (preloaded) real: {
+ const dlsym = @extern(?*const fn (?*anyopaque, [*:0]const u8) callconv(.c) ?*anyopaque, .{ .name = "dlsym", .linkage = .weak }) orelse break :real null;
+ const RTLD_NEXT: ?*anyopaque = @ptrFromInt(std.math.maxInt(usize));
+ break :real @ptrCast(dlsym(RTLD_NEXT, name));
+ } else @extern(T, .{ .name = "__real_" ++ name, .linkage = .weak });
+ }
+ found.store(2, .release);
+ // The first call into libc that comes through us may come before the constructor.
+ agent.init();
+ return true;
+}
+
+/// Memory for the allocations made while the lookup runs. Never reused, so
+/// always zero; each block is preceded by its size.
+var early: [1 << 16]u8 align(16) = @splat(0);
+var early_used: std.atomic.Value(usize) = .init(0);
+
+fn earlyAlloc(size: usize, alignment: usize) ?*anyopaque {
+ const step = @max(alignment, 16);
+ const need = step + 16 + std.mem.alignForward(usize, size, 16);
+ const at = early_used.fetchAdd(need, .monotonic);
+ if (at + need > early.len) return null;
+ const block = std.mem.alignForward(usize, @intFromPtr(&early) + at + 16, step);
+ @as(*usize, @ptrFromInt(block - 16)).* = size;
+ return @ptrFromInt(block);
+}
+
+fn isEarly(p: ?*anyopaque) bool {
+ return @intFromPtr(p) -% @intFromPtr(&early) < early.len;
+}
+
+fn allocated(how: zt.event.Alloc, p: ?*anyopaque, size: usize, pc: usize) void {
+ if (agent.allocations and p != null) agent.emit(.alloc, @intFromEnum(how), .{ @intFromPtr(p), size, pc, 0, 0, 0 }, "");
+}
+
+fn freed(p: ?*anyopaque, pc: usize) void {
+ if (agent.allocations) agent.emit(.free, 0, .{ @intFromPtr(p), pc, 0, 0, 0, 0 }, "");
+}
+
+const interposed = struct {
+ fn malloc(size: usize) callconv(.c) ?*anyopaque {
+ if (!ready()) return earlyAlloc(size, 16);
+ const p = real.malloc.?(size);
+ allocated(.malloc, p, size, @returnAddress());
+ return p;
+ }
+
+ fn calloc(n: usize, size: usize) callconv(.c) ?*anyopaque {
+ if (!ready()) return earlyAlloc(n *| size, 16);
+ const p = real.calloc.?(n, size);
+ allocated(.calloc, p, n *| size, @returnAddress());
+ return p;
+ }
+
+ fn realloc(old: ?*anyopaque, size: usize) callconv(.c) ?*anyopaque {
+ if (!ready() or isEarly(old)) {
+ // An early block cannot grow in place: a new one, with its bytes.
+ const p: [*]u8 = @ptrCast((if (ready()) real.malloc.?(size) else earlyAlloc(size, 16)) orelse return null);
+ if (old) |o| {
+ const had = @as(*const usize, @ptrFromInt(@intFromPtr(o) - 16)).*;
+ @memcpy(p[0..@min(had, size)], @as([*]const u8, @ptrCast(o)));
+ }
+ return p;
+ }
+ const p = real.realloc.?(old, size);
+ // One that moved is a free and an alloc; one in place, an alloc at the same pointer.
+ if (old != null and p != old and (p != null or size == 0)) freed(old, @returnAddress());
+ allocated(.realloc, p, size, @returnAddress());
+ return p;
+ }
+
+ fn free(p: ?*anyopaque) callconv(.c) void {
+ if (p == null or isEarly(p) or !ready()) return;
+ // Before it is free: once it is, another thread's alloc may be given the same pointer.
+ freed(p, @returnAddress());
+ real.free.?(p);
+ }
+
+ fn posix_memalign(out: *?*anyopaque, alignment: usize, size: usize) callconv(.c) c_int {
+ if (!ready()) {
+ out.* = earlyAlloc(size, alignment) orelse return @intFromEnum(std.os.linux.E.NOMEM);
+ return 0;
+ }
+ const rc = real.posix_memalign.?(out, alignment, size);
+ if (rc == 0) allocated(.memalign, out.*, size, @returnAddress());
+ return rc;
+ }
+
+ fn aligned_alloc(alignment: usize, size: usize) callconv(.c) ?*anyopaque {
+ if (!ready()) return earlyAlloc(size, alignment);
+ const p = real.aligned_alloc.?(alignment, size);
+ allocated(.memalign, p, size, @returnAddress());
+ return p;
+ }
+
+ fn memalign(alignment: usize, size: usize) callconv(.c) ?*anyopaque {
+ if (!ready()) return earlyAlloc(size, alignment);
+ const p = real.memalign.?(alignment, size);
+ allocated(.memalign, p, size, @returnAddress());
+ return p;
+ }
+
+ fn pthread_create(thread: *anyopaque, attr: ?*const anyopaque, start: Start, arg: ?*anyopaque) callconv(.c) c_int {
+ _ = ready();
+ if (agent.ring == null) return real.pthread_create.?(thread, attr, start, arg);
+ // The new thread runs `threadMain`, which needs to know what it was meant to run.
+ const box: *Box = @ptrCast(@alignCast(real.malloc.?(@sizeOf(Box)) orelse return @intFromEnum(std.os.linux.E.AGAIN)));
+ box.* = .{ .start = start, .arg = arg };
+ const rc = real.pthread_create.?(thread, attr, threadMain, box);
+ if (rc != 0) real.free.?(box);
+ return rc;
+ }
+
+ fn fork() callconv(.c) c_int {
+ _ = ready();
+ const pid = real.fork.?();
+ if (pid == 0 and agent.ring != null) agent.forked();
+ return pid;
+ }
+};
+
+const Box = struct { start: Start, arg: ?*anyopaque };
+
+fn threadMain(arg: ?*anyopaque) callconv(.c) ?*anyopaque {
+ const box: *Box = @ptrCast(@alignCast(arg));
+ const run = box.*;
+ real.free.?(box);
+ agent.threadStart();
+ agent.sud.selector = agent.sud.resting;
+ const result = run.start(run.arg);
+ // shortcut: a thread that ends in pthread_exit or is cancelled does not come back here; hook the exit path if a target's threads end that way.
+ agent.emit(.thread_exit, 0, @splat(0), "");
+ return result;
+}
+
+comptime {
+ for (@typeInfo(Real).@"struct".field_names) |name| {
+ @export(&@field(interposed, name), .{ .name = (if (preloaded) "" else "__wrap_") ++ name });
+ }
+}
diff --git a/src/agent/signal.zig b/src/agent/signal.zig
new file mode 100644
index 0000000..99aead0
--- /dev/null
+++ b/src/agent/signal.zig
@@ -0,0 +1,116 @@
+//! What the agent's signal handlers share: the frame the kernel pushes on
+//! x86-64, and handlers installed with the raw syscall, behind libc's back.
+const std = @import("std");
+const linux = std.os.linux;
+const zt = @import("ztrace");
+
+/// The kernel's `struct ucontext`: the interrupted thread's registers, which
+/// a handler may change before they are restored.
+pub const Ucontext = extern struct {
+ flags: u64,
+ link: ?*Ucontext,
+ stack: extern struct { sp: usize, flags: i32, size: usize },
+ r8: u64,
+ r9: u64,
+ r10: u64,
+ r11: u64,
+ r12: u64,
+ r13: u64,
+ r14: u64,
+ r15: u64,
+ rdi: u64,
+ rsi: u64,
+ rbp: u64,
+ rbx: u64,
+ rdx: u64,
+ rax: u64,
+ rcx: u64,
+ rsp: u64,
+ rip: u64,
+ eflags: u64,
+ cs: u16,
+ gs: u16,
+ fs: u16,
+ ss: u16,
+ err: u64,
+ trapno: u64,
+ oldmask: u64,
+ cr2: u64,
+ fpstate: usize,
+ reserved: [8]u64,
+ sigmask: u64,
+
+ comptime {
+ std.debug.assert(@offsetOf(Ucontext, "sigmask") == 296);
+ }
+
+ pub fn regs(uc: *const Ucontext) zt.Regs {
+ var out: zt.Regs = .{ .orig_rax = uc.rax, .cs = uc.cs, .ss = uc.ss, .fs = uc.fs, .gs = uc.gs };
+ inline for (zt.Regs.names) |name| @field(out, name) = @field(uc, name);
+ return out;
+ }
+};
+
+/// The trap flag: one instruction, then SIGTRAP.
+pub const trap_flag = 0x100;
+
+/// The bit of a signal in a kernel signal set.
+pub fn bit(sig: linux.SIG) u64 {
+ return @as(u64, 1) << @intCast(@intFromEnum(sig) - 1);
+}
+
+// The gate: the only syscall instructions the dispatcher (sud.zig) lets
+// through whatever the selector says. One symbol after the other, so that
+// the range between the first and the last is these and nothing else.
+comptime {
+ asm (
+ \\ .pushsection .text.ztrace_gate, "ax", @progbits
+ \\ .globl ztrace_gate_sigreturn, ztrace_gate_restorer, ztrace_gate_syscall, ztrace_gate_end
+ \\ .hidden ztrace_gate_sigreturn, ztrace_gate_restorer, ztrace_gate_syscall, ztrace_gate_end
+ \\ ztrace_gate_sigreturn:
+ \\ movq %rdi, %rsp
+ \\ ztrace_gate_restorer:
+ \\ movl $15, %eax
+ \\ syscall
+ \\ ztrace_gate_syscall:
+ \\ movq %rdi, %rax
+ \\ movq %rsi, %rdi
+ \\ movq %rdx, %rsi
+ \\ movq %rcx, %rdx
+ \\ movq %r8, %r10
+ \\ movq %r9, %r8
+ \\ movq 8(%rsp), %r9
+ \\ syscall
+ \\ retq
+ \\ ztrace_gate_end:
+ \\ .popsection
+ );
+}
+
+/// rt_sigreturn from the signal frame whose `Ucontext` is at `uc`.
+pub extern fn ztrace_gate_sigreturn(uc: u64) callconv(.c) noreturn;
+/// The same for a handler that returns: its stack pointer is there already.
+extern fn ztrace_gate_restorer() callconv(.c) void;
+/// Any syscall, by number.
+pub extern fn ztrace_gate_syscall(number: u64, a0: u64, a1: u64, a2: u64, a3: u64, a4: u64, a5: u64) callconv(.c) u64;
+extern const ztrace_gate_end: u8;
+
+/// Where the gate is: start and length.
+pub fn gate() [2]usize {
+ return .{ @intFromPtr(&ztrace_gate_sigreturn), @intFromPtr(&ztrace_gate_end) - @intFromPtr(&ztrace_gate_sigreturn) };
+}
+
+pub const Handler = *const fn (i32, *const linux.siginfo_t, *Ucontext) callconv(.c) void;
+
+/// Null puts the default action back. The handler runs with no signal
+/// blocked, its own included: inside it the thread is still the target, with
+/// the target's mask.
+pub fn install(sig: linux.SIG, handler: ?Handler) void {
+ const act: linux.k_sigaction = .{
+ .handler = @ptrCast(handler),
+ .flags = linux.SA.SIGINFO | linux.SA.RESTORER | linux.SA.NODEFER,
+ .restorer = @ptrCast(&ztrace_gate_restorer),
+ .mask = linux.sigemptyset(),
+ };
+ _ = linux.syscall4(.rt_sigaction, @intFromEnum(sig), @intFromPtr(&act), 0, @sizeOf(linux.sigset_t));
+}
diff --git a/src/agent/sud.zig b/src/agent/sud.zig
new file mode 100644
index 0000000..e556df3
--- /dev/null
+++ b/src/agent/sud.zig
@@ -0,0 +1,129 @@
+//! Syscalls without ptrace: Syscall User Dispatch. The kernel turns every
+//! syscall the thread makes into SIGSYS; the handler runs here, in the
+//! target, emits `syscall_enter` (with the path or the bytes written, read
+//! straight from memory), makes the syscall itself, emits `syscall_exit`
+//! and returns the result. No context switch to a tracer: two signal frames
+//! a syscall.
+//!
+//! The agent's own syscalls pass because the selector byte says so while its
+//! code runs. The target's syscall itself is made with the selector back on
+//! `block`, through the gate (signal.zig), the range of code the kernel
+//! always lets through: a signal that interrupts it runs the target's handler
+//! as the target's code, its syscalls seen like any other.
+const std = @import("std");
+const linux = std.os.linux;
+const zt = @import("ztrace");
+const agent = @import("agent.zig");
+const signal = @import("signal.zig");
+
+pub const allow: u8 = 0;
+pub const block: u8 = 1;
+/// The kernel reads this at each of the thread's syscalls: `block` while the
+/// target's code runs, `allow` while the agent's does.
+pub threadlocal var selector: u8 = allow;
+/// What the target's code runs with: `block` once syscalls are traced.
+pub var resting: u8 = allow;
+/// 1 + the syscall this thread is making natively, under a single step.
+threadlocal var passing: u64 = 0;
+
+/// Signals the target may neither block nor take over: the kernel kills a
+/// process whose forced signal is blocked.
+const ours = signal.bit(.SYS) | signal.bit(.TRAP);
+
+fn nr(comptime name: linux.SYS) u64 {
+ return @intFromEnum(name);
+}
+
+pub fn enable() void {
+ signal.install(.SYS, onSyscall);
+ // Syscalls let through natively are stepped over: hook.zig's handler calls `stepped`.
+ @import("hook.zig").listen();
+ resting = block;
+ arm();
+}
+
+/// Dispatch on for the calling thread: the kernel keeps it per thread, and a
+/// clone starts without it.
+pub fn arm() void {
+ if (resting == allow) return;
+ const PR_SET_SYSCALL_USER_DISPATCH = 59;
+ const PR_SYS_DISPATCH_ON = 1;
+ const gate = signal.gate();
+ _ = linux.prctl(PR_SET_SYSCALL_USER_DISPATCH, PR_SYS_DISPATCH_ON, gate[0], gate[1], @intFromPtr(&selector));
+}
+
+fn onSyscall(_: i32, _: *const linux.siginfo_t, uc: *signal.Ucontext) callconv(.c) void {
+ selector = allow;
+ const number = uc.rax;
+ var a = [6]u64{ uc.rdi, uc.rsi, uc.rdx, uc.r10, uc.r8, uc.r9 };
+ if (number == nr(.rt_sigreturn)) {
+ // The target leaves a handler of its own: its frame is where its
+ // stack pointer is, and ours, pushed below, goes with it.
+ selector = block;
+ signal.ztrace_gate_sigreturn(uc.rsp);
+ }
+ agent.emit(.syscall_enter, @truncate(number), a, argument(number, a));
+ if (number == nr(.clone3) or number == nr(.vfork) or (number == nr(.clone) and a[0] & linux.CLONE.VM != 0)) {
+ // The child starts on another stack, or shares this one: not from
+ // inside a handler. Back onto the syscall instruction with dispatch
+ // off and one step to go; `stepped` turns it on again.
+ passing = number + 1;
+ uc.rip -= 2;
+ uc.eflags |= signal.trap_flag;
+ return;
+ }
+ var act: linux.k_sigaction = undefined;
+ var faked = false;
+ if (number == nr(.rt_sigaction) and a[1] != 0) {
+ // shortcut: the target is told its handler for one of our signals is installed, and it is not; chain to it when a target needs SIGTRAP or SIGSYS itself.
+ faked = a[0] == @intFromEnum(linux.SIG.SYS) or a[0] == @intFromEnum(linux.SIG.TRAP);
+ act = @as(*const linux.k_sigaction, @ptrFromInt(a[1])).*;
+ act.mask[0] &= ~ours;
+ a[1] = @intFromPtr(&act);
+ }
+ selector = block;
+ const result = if (faked) 0 else signal.ztrace_gate_syscall(number, a[0], a[1], a[2], a[3], a[4], a[5]);
+ selector = allow;
+ if (number == nr(.rt_sigprocmask)) {
+ // The mask it set is this handler's; the target's is the one the frame restores.
+ _ = linux.sigprocmask(linux.SIG.BLOCK, null, @ptrCast(&uc.sigmask));
+ uc.sigmask &= ~ours;
+ }
+ // A forked child.
+ if (result == 0 and (number == nr(.fork) or number == nr(.clone))) agent.forked();
+ agent.emit(.syscall_exit, @truncate(number), .{ result, 0, 0, 0, 0, 0 }, "");
+ uc.rax = result;
+ selector = block;
+}
+
+/// A single step ended (hook.zig's SIGTRAP handler): if it was over a syscall
+/// let through, here is its exit, in the parent and in a new thread both.
+pub fn stepped(uc: *const signal.Ucontext) void {
+ if (resting == allow) return;
+ agent.threadStart();
+ if (passing != 0) {
+ // shortcut: the step may end one instruction after the syscall, which could have changed rax; none of libc's do.
+ agent.emit(.syscall_exit, @truncate(passing - 1), .{ uc.rax, 0, 0, 0, 0, 0 }, "");
+ passing = 0;
+ }
+ selector = block;
+}
+
+/// What a syscall's pointer argument points at, for the event's payload.
+// shortcut: read without checking; a pointer the kernel would refuse with EFAULT faults here instead.
+fn argument(number: u64, a: [6]u64) []const u8 {
+ return switch (number) {
+ nr(.open), nr(.stat), nr(.lstat), nr(.access), nr(.execve), nr(.chdir), nr(.unlink), nr(.readlink), nr(.mkdir), nr(.rmdir), nr(.truncate), nr(.chmod) => string(a[0]),
+ nr(.openat), nr(.newfstatat), nr(.unlinkat), nr(.readlinkat), nr(.faccessat), nr(.faccessat2), nr(.statx), nr(.mkdirat), nr(.execveat) => string(a[1]),
+ nr(.write), nr(.pwrite64), nr(.sendto) => if (a[1] == 0) "" else agent.text(@as([*]const u8, @ptrFromInt(a[1]))[0..a[2]]),
+ else => "",
+ };
+}
+
+fn string(addr: u64) []const u8 {
+ if (addr == 0) return "";
+ const s: [*]const u8 = @ptrFromInt(addr);
+ var len: usize = 0;
+ while (len < agent.max_payload and s[len] != 0) len += 1;
+ return agent.text(s[0..len]);
+}
diff --git a/src/agent/symbols.zig b/src/agent/symbols.zig
new file mode 100644
index 0000000..6504ff6
--- /dev/null
+++ b/src/agent/symbols.zig
@@ -0,0 +1,158 @@
+//! Where things are in a process: its mappings (/proc/PID/maps) and the
+//! symbols of the ELF files mapped there. Raw syscalls and no allocation:
+//! the agent runs this on itself at startup, the tracer on its child.
+const std = @import("std");
+const linux = std.os.linux;
+const Elf = std.elf.Elf64;
+
+pub const Map = struct {
+ start: u64,
+ end: u64,
+ /// PROT_READ 1, PROT_WRITE 2, PROT_EXEC 4.
+ prot: u32,
+ offset: u64,
+ /// Empty for anonymous memory. Valid until the next `next`.
+ path: []const u8,
+};
+
+pub const Maps = struct {
+ fd: linux.fd_t,
+ buf: [8192]u8 = undefined,
+ len: usize = 0,
+ at: usize = 0,
+
+ /// `pid` null: this process.
+ pub fn open(pid: ?linux.pid_t) ?Maps {
+ var name: [32]u8 = undefined;
+ const path: [*:0]const u8 = if (pid) |p| @ptrCast(std.fmt.bufPrint(&name, "/proc/{d}/maps\x00", .{p}) catch unreachable) else "/proc/self/maps";
+ const rc = linux.open(path, .{}, 0);
+ return if (linux.errno(rc) == .SUCCESS) .{ .fd = @intCast(rc) } else null;
+ }
+
+ pub fn close(m: *Maps) void {
+ _ = linux.close(m.fd);
+ }
+
+ pub fn next(m: *Maps) ?Map {
+ while (true) {
+ if (std.mem.indexOfScalarPos(u8, m.buf[0..m.len], m.at, '\n')) |end| {
+ const line = m.buf[m.at..end];
+ m.at = end + 1;
+ return parse(line) orelse continue;
+ }
+ // No whole line left: keep the rest and read more.
+ std.mem.copyForwards(u8, &m.buf, m.buf[m.at..m.len]);
+ m.len -= m.at;
+ m.at = 0;
+ const n = linux.read(m.fd, m.buf[m.len..].ptr, m.buf.len - m.len);
+ if (linux.errno(n) != .SUCCESS or n == 0) return null;
+ m.len += n;
+ }
+ }
+
+ /// "55d0c0a00000-55d0c0a01000 r-xp 00001000 08:02 1234 /usr/bin/true"
+ fn parse(line: []const u8) ?Map {
+ var it = std.mem.tokenizeScalar(u8, line, ' ');
+ const range = it.next() orelse return null;
+ const perms = it.next() orelse return null;
+ const offset = it.next() orelse return null;
+ _ = it.next(); // device
+ _ = it.next(); // inode
+ const dash = std.mem.indexOfScalar(u8, range, '-') orelse return null;
+ if (perms.len < 3) return null;
+ return .{
+ .start = std.fmt.parseInt(u64, range[0..dash], 16) catch return null,
+ .end = std.fmt.parseInt(u64, range[dash + 1 ..], 16) catch return null,
+ .prot = @as(u32, @intFromBool(perms[0] == 'r')) | @as(u32, @intFromBool(perms[1] == 'w')) << 1 | @as(u32, @intFromBool(perms[2] == 'x')) << 2,
+ .offset = std.fmt.parseInt(u64, offset, 16) catch return null,
+ .path = it.rest(),
+ };
+ }
+};
+
+pub const Symbol = struct { addr: u64, size: u64 };
+
+/// The function or object called `name` in the first file mapped in `pid`
+/// (null: this process) that has one, lowest address first: the executable
+/// before its libraries. Static symbols count when the file is not stripped.
+pub fn lookup(pid: ?linux.pid_t, name: []const u8) ?Symbol {
+ var maps = Maps.open(pid) orelse return null;
+ defer maps.close();
+ while (maps.next()) |m| {
+ // A file's first mapping starts at its ELF header.
+ if (m.offset != 0 or m.path.len == 0 or m.path[0] != '/') continue;
+ if (inFile(m.path, m.start, name)) |symbol| return symbol;
+ }
+ return null;
+}
+
+/// What "ADDR", "ADDR:LEN" or a symbol's name stands for in `pid`.
+pub fn find(pid: ?linux.pid_t, spec: []const u8) ?Symbol {
+ if (spec.len == 0 or !std.ascii.isDigit(spec[0])) return lookup(pid, spec);
+ const colon = std.mem.indexOfScalar(u8, spec, ':') orelse spec.len;
+ return .{
+ .addr = std.fmt.parseInt(u64, spec[0..colon], 0) catch return null,
+ .size = if (colon == spec.len) 0 else std.fmt.parseInt(u64, spec[colon + 1 ..], 0) catch return null,
+ };
+}
+
+fn inFile(path: []const u8, base: u64, name: []const u8) ?Symbol {
+ var path_z: [4097]u8 = undefined;
+ if (path.len >= path_z.len) return null;
+ @memcpy(path_z[0..path.len], path);
+ path_z[path.len] = 0;
+ const rc = linux.open(@ptrCast(&path_z), .{}, 0);
+ if (linux.errno(rc) != .SUCCESS) return null;
+ const fd: linux.fd_t = @intCast(rc);
+ const size: usize = @intCast(linux.lseek(fd, 0, linux.SEEK.END));
+ const mapped = linux.mmap(null, size, .{ .READ = true }, .{ .TYPE = .PRIVATE }, fd, 0);
+ _ = linux.close(fd);
+ if (linux.errno(mapped) != .SUCCESS) return null;
+ defer _ = linux.munmap(@ptrFromInt(mapped), size);
+ const file = @as([*]const u8, @ptrFromInt(mapped))[0..size];
+
+ if (size < @sizeOf(Elf.Ehdr) or !std.mem.eql(u8, file[0..5], "\x7fELF\x02")) return null;
+ const ehdr: *align(1) const Elf.Ehdr = @ptrCast(file.ptr);
+ const phdrs = table(Elf.Phdr, file, ehdr.phoff, ehdr.phnum) orelse return null;
+ const shdrs = table(Elf.Shdr, file, ehdr.shoff, ehdr.shnum) orelse return null;
+
+ // `base` is where the lowest loaded page of the file went.
+ var low: u64 = std.math.maxInt(u64);
+ for (phdrs) |ph| {
+ if (ph.type == .LOAD) low = @min(low, ph.vaddr & ~@as(u64, 4095));
+ }
+ for (shdrs) |sh| {
+ if (sh.type != .SYMTAB and sh.type != .DYNSYM) continue;
+ if (sh.link >= shdrs.len) continue;
+ const syms = table(Elf.Sym, file, sh.offset, sh.size / @sizeOf(Elf.Sym)) orelse continue;
+ const names = table(u8, file, shdrs[sh.link].offset, shdrs[sh.link].size) orelse continue;
+ for (syms) |sym| {
+ if (sym.shndx == 0 or sym.name >= names.len) continue;
+ switch (sym.info.type) {
+ .FUNC, .OBJECT, .NOTYPE => {},
+ else => continue,
+ }
+ const rest = names[sym.name..];
+ if (rest.len > name.len and rest[name.len] == 0 and std.mem.startsWith(u8, rest, name)) return .{ .addr = sym.value -% low +% base, .size = sym.size };
+ }
+ }
+ return null;
+}
+
+fn table(comptime T: type, file: []const u8, offset: u64, count: u64) ?[]align(1) const T {
+ if (offset > file.len or count > (file.len - offset) / @sizeOf(T)) return null;
+ return @as([*]align(1) const T, @ptrCast(file.ptr + offset))[0..count];
+}
+
+test "this process's mappings and a symbol of its executable" {
+ var maps = Maps.open(null).?;
+ defer maps.close();
+ const here = @intFromPtr(&inFile);
+ var found = false;
+ while (maps.next()) |m| {
+ if (here >= m.start and here < m.end) found = m.prot & 4 != 0 and m.path.len > 0;
+ }
+ try std.testing.expect(found);
+ try std.testing.expect(lookup(null, "no such symbol anywhere") == null);
+ try std.testing.expectEqual(Symbol{ .addr = 0x1000, .size = 64 }, find(null, "0x1000:64").?);
+}
diff --git a/src/agent/watch.zig b/src/agent/watch.zig
new file mode 100644
index 0000000..356dac8
--- /dev/null
+++ b/src/agent/watch.zig
@@ -0,0 +1,130 @@
+//! Watched memory: regions whose changes become `mem_write` events. Each
+//! region has a shadow copy in the agent's own memory; `diff` compares the
+//! two and emits the runs that changed. Plain memory compares in the target's
+//! own address space: no syscall, no page protection, any granularity. The
+//! agent calls `diff` before every event that ends a moment, so a moment's
+//! memory is what the target had when that event happened.
+const std = @import("std");
+const linux = std.os.linux;
+const agent = @import("agent.zig");
+
+const Region = struct {
+ addr: usize,
+ len: usize,
+ shadow: [*]u8,
+ /// The thread that asked, and how many hooked calls it had open: the
+ /// region is forgotten when that call returns, as the recorder forgets
+ /// its `variable`. Depth 0 lives forever.
+ tid: u32,
+ depth: u32,
+};
+
+// shortcut: 64 regions, each compared whole at every moment; when a target
+// watches megabytes, find the dirty pages first (PAGEMAP_SCAN) and compare those.
+var table: [64]Region = undefined;
+var count: usize = 0;
+var busy: std.atomic.Value(bool) = .init(false);
+
+/// The memory must stay mapped for as long as it is watched.
+pub fn add(memory: []const u8, tid: u32, depth: u32) void {
+ if (memory.len == 0) return;
+ const shadow = linux.mmap(null, memory.len, .{ .READ = true, .WRITE = true }, .{ .TYPE = .PRIVATE, .ANONYMOUS = true }, -1, 0);
+ if (linux.errno(shadow) != .SUCCESS) return;
+ while (busy.swap(true, .acquire)) std.atomic.spinLoopHint();
+ defer busy.store(false, .release);
+ if (count == table.len) {
+ _ = linux.munmap(@ptrFromInt(shadow), memory.len);
+ return;
+ }
+ table[count] = .{ .addr = @intFromPtr(memory.ptr), .len = memory.len, .shadow = @ptrFromInt(shadow), .tid = tid, .depth = depth };
+ @memcpy(table[count].shadow, memory);
+ count += 1;
+}
+
+/// Forgets what `tid` watched from inside calls deeper than `depth`.
+pub fn drop(tid: u32, depth: u32) void {
+ if (count == 0) return;
+ while (busy.swap(true, .acquire)) std.atomic.spinLoopHint();
+ defer busy.store(false, .release);
+ var i: usize = 0;
+ while (i < count) {
+ const r = table[i];
+ if (r.tid != tid or r.depth <= depth) {
+ i += 1;
+ continue;
+ }
+ _ = linux.munmap(r.shadow, r.len);
+ count -= 1;
+ table[i] = table[count];
+ }
+}
+
+/// Emits what changed in every region since the last time.
+pub fn diff() void {
+ if (count == 0) return;
+ // Busy: another thread is at it, or this one is, below this frame.
+ if (busy.swap(true, .acquire)) return;
+ defer busy.store(false, .release);
+ for (table[0..count]) |r| {
+ var changes: Changes = .{ .old = r.shadow[0..r.len], .new = @as([*]const u8, @ptrFromInt(r.addr))[0..r.len] };
+ while (changes.next()) |run| agent.write(r.addr + run.at, run.bytes);
+ }
+}
+
+/// The runs of bytes where `new` differs from `old`, each brought into `old`
+/// as it is returned. Changes less than 8 bytes apart travel as one run.
+pub const Changes = struct {
+ old: []u8,
+ new: []const u8,
+ at: usize = 0,
+
+ pub const Run = struct { at: usize, bytes: []const u8 };
+
+ pub fn next(c: *Changes) ?Run {
+ const from = c.at + same(c.old[c.at..], c.new[c.at..]);
+ if (from == c.new.len) {
+ c.at = from;
+ return null;
+ }
+ var to = from + 1;
+ var i = to;
+ while (i < c.new.len and i - to < 8) : (i += 1) {
+ if (c.old[i] != c.new[i]) to = i + 1;
+ }
+ @memcpy(c.old[from..to], c.new[from..to]);
+ c.at = to;
+ // From the copy: the target may be writing there right now.
+ return .{ .at = from, .bytes = c.old[from..to] };
+ }
+
+ /// How many bytes at the start of `a` and `b` are equal.
+ fn same(a: []const u8, b: []const u8) usize {
+ const V = @Vector(32, u8);
+ var i: usize = 0;
+ while (i + 32 <= a.len) : (i += 32) {
+ const differ: u32 = @bitCast(@as(V, a[i..][0..32].*) != @as(V, b[i..][0..32].*));
+ if (differ != 0) return i + @ctz(differ);
+ }
+ while (i < a.len and a[i] == b[i]) i += 1;
+ return i;
+ }
+};
+
+test "changes are found as runs and folded into the old copy" {
+ var old: [200]u8 = @splat(0);
+ var new: [200]u8 = @splat(0);
+ new[3] = 1;
+ new[9] = 2; // 5 equal bytes after the first: one run
+ new[100] = 3;
+ new[199] = 4;
+ var changes: Changes = .{ .old = &old, .new = &new };
+ const a = changes.next().?;
+ try std.testing.expectEqual(@as(usize, 3), a.at);
+ try std.testing.expectEqualSlices(u8, &.{ 1, 0, 0, 0, 0, 0, 2 }, a.bytes);
+ try std.testing.expectEqual(@as(usize, 100), changes.next().?.at);
+ try std.testing.expectEqual(@as(usize, 199), changes.next().?.at);
+ try std.testing.expect(changes.next() == null);
+ try std.testing.expectEqualSlices(u8, &new, &old);
+ changes.at = 0;
+ try std.testing.expect(changes.next() == null);
+}
diff --git a/src/cli/run.zig b/src/cli/run.zig
index c4f1b25..2483a21 100644
--- a/src/cli/run.zig
+++ b/src/cli/run.zig
@@ -1,17 +1,42 @@
//! ztrace run: a program that carries a ring producer (the preloaded agent,
-//! or instrumentation linked in), recorded at full speed, no ptrace.
+//! or instrumentation linked in), recorded at full speed, no ptrace. The
+//! agent's capabilities are chosen here and reach it through ZTRACE_*
+//! variables; stops are the ring's (`stop_mask`), not the kernel's.
const std = @import("std");
+const linux = std.os.linux;
const zt = @import("ztrace");
+const agent = @import("ztrace-agent");
const util = @import("util.zig");
const fail = util.fail;
pub const usage =
- \\usage: ztrace run [-o FILE] [--preload LIB] [--ring BYTES] -- PROGRAM [ARGS]
+ \\usage: ztrace run [-o FILE] [--preload LIB] [--ring BYTES] [OPTIONS] -- PROGRAM [ARGS]
\\
\\Runs PROGRAM with a shared-memory ring in its environment and records
- \\what it emits (default out.ztrace). --preload puts a library (the agent)
- \\into it with LD_PRELOAD. --ring sizes the ring (a power of two, default
- \\16 MiB).
+ \\what it emits (default out.ztrace). --preload puts a library (the agent,
+ \\libztrace-agent.so) into it with LD_PRELOAD. --ring sizes the ring (a
+ \\power of two, default 16 MiB).
+ \\
+ \\What the agent records, preloaded or linked into PROGRAM:
+ \\ --alloc malloc, free and their family: alloc, free
+ \\ --syscalls every syscall, with paths and written bytes:
+ \\ syscall_enter, syscall_exit
+ \\ --hook SYM|ADDR a function's entry (with registers) and return
+ \\ (with its value): call, ret
+ \\ --watch SYM|ADDR:LEN memory: the bytes that changed in it, before each
+ \\ event that ends a moment
+ \\--hook and --watch repeat, or take a comma-separated list.
+ \\
+ \\ --cut KIND,... the kinds that end a moment (default: the
+ \\ recorder's, and call and ret)
+ \\
+ \\Stops, with the target otherwise at full speed:
+ \\ --stop-at KIND,... hold the target at each event of these kinds
+ \\ until the tracer is done with it
+ \\ --read SYM|ADDR:LEN at each stop read this memory from outside and
+ \\ record what changed (repeats)
+ \\ -i at each stop ask what next: s (step to the next
+ \\ stop), c (continue to the end), x ADDR [LEN], q
\\
;
@@ -19,34 +44,76 @@ pub fn run(init: std.process.Init, args: []const [:0]const u8) !void {
const arena = init.arena.allocator();
var out: []const u8 = "out.ztrace";
var options: zt.host.Options = .{};
+ var env: std.ArrayList(?[*:0]const u8) = .empty;
+ var hooks: []const u8 = "";
+ var watches: []const u8 = "";
+ var cut: ?u64 = null;
+ var stops: Stops = .{ .io = init.io, .arena = arena };
var i: usize = 0;
while (i < args.len) : (i += 1) {
const arg = args[i];
+ const value: [:0]const u8 = if (i + 1 < args.len) args[i + 1] else "";
if (std.mem.eql(u8, arg, "--")) {
i += 1;
break;
- } else if (std.mem.eql(u8, arg, "-o") and i + 1 < args.len) {
- i += 1;
- out = args[i];
- } else if (std.mem.eql(u8, arg, "--preload") and i + 1 < args.len) {
- i += 1;
- options.preload = args[i];
- } else if (std.mem.eql(u8, arg, "--ring") and i + 1 < args.len) {
- i += 1;
- options.ring_bytes = std.fmt.parseInt(usize, args[i], 0) catch 0;
+ } else if (std.mem.eql(u8, arg, "--alloc")) {
+ try env.append(arena, "ZTRACE_ALLOC=1");
+ continue;
+ } else if (std.mem.eql(u8, arg, "--syscalls")) {
+ try env.append(arena, "ZTRACE_SYSCALLS=1");
+ continue;
+ } else if (std.mem.eql(u8, arg, "-i")) {
+ stops.interactive = true;
+ continue;
+ } else if (i + 1 == args.len) {
+ fail(usage, .{});
+ } else if (std.mem.eql(u8, arg, "-o")) {
+ out = value;
+ } else if (std.mem.eql(u8, arg, "--preload")) {
+ options.preload = value;
+ } else if (std.mem.eql(u8, arg, "--ring")) {
+ options.ring_bytes = std.fmt.parseInt(usize, value, 0) catch 0;
if (!std.math.isPowerOfTwo(options.ring_bytes) or options.ring_bytes < 4096) fail("--ring needs a power of two, 4096 or more\n", .{});
+ } else if (std.mem.eql(u8, arg, "--hook")) {
+ hooks = try std.mem.concat(arena, u8, &.{ hooks, ",", value });
+ } else if (std.mem.eql(u8, arg, "--watch")) {
+ watches = try std.mem.concat(arena, u8, &.{ watches, ",", value });
+ } else if (std.mem.eql(u8, arg, "--read")) {
+ try stops.reads.append(arena, .{ .spec = value });
+ } else if (std.mem.eql(u8, arg, "--cut")) {
+ cut = kinds(value);
+ } else if (std.mem.eql(u8, arg, "--stop-at")) {
+ stops.mask = kinds(value);
} else fail(usage, .{});
+ i += 1;
}
if (i >= args.len) fail(usage, .{});
+ var rec = try zt.Recorder.create(init.gpa, init.io, out);
+ // A hooked call and its return are the steps of a run recorded from inside.
+ rec.cut = cut orelse rec.cut | zt.Kind.call.bit() | zt.Kind.ret.bit();
+ stops.rec = &rec;
+ if (hooks.len > 0) try env.append(arena, try std.fmt.allocPrintSentinel(arena, "ZTRACE_HOOKS={s}", .{hooks}, 0));
+ if (watches.len > 0) try env.append(arena, try std.fmt.allocPrintSentinel(arena, "ZTRACE_WATCH={s}", .{watches}, 0));
+ try env.append(arena, try std.fmt.allocPrintSentinel(arena, "ZTRACE_CUT=0x{x}", .{rec.cut}, 0));
+ for (init.minimal.environ.block.slice) |v| {
+ if (!std.mem.startsWith(u8, std.mem.span(v.?), "ZTRACE_")) try env.append(arena, v);
+ }
+
const path = try util.resolve(init, args[i]);
const argv = try util.targetArgv(arena, args[i..]);
- var session = try zt.host.Session.spawn(arena, path, argv, init.minimal.environ.block.slice, options);
+ var session = try zt.host.Session.spawn(arena, path, argv, try env.toOwnedSliceSentinel(arena, null), options);
defer session.close();
- var rec = try zt.Recorder.create(init.gpa, init.io, out);
+ // Set before the target has had time to load, let alone emit.
+ session.ring.hdr.stop_mask.store(stops.mask, .release);
+ stops.session = &session;
const start = zt.event.now();
- while (try session.pump(rec.sink(), 10 * std.time.ns_per_ms)) {}
+ while (try session.pump(stops.sink(), 10 * std.time.ns_per_ms)) {
+ // Everything pumped is recorded and read: whoever waits at it may go on.
+ if (stops.held) session.ring.resumeAll();
+ stops.held = false;
+ }
const ns = zt.event.now() - start;
const events = rec.count;
@@ -61,3 +128,110 @@ pub fn run(init: std.process.Init, args: []const [:0]const u8) !void {
@as(f64, @floatFromInt(events)) / (@as(f64, @floatFromInt(ns)) / 1e9), session.exit_code.?,
});
}
+
+/// "call,ret" as a set of `Kind.bit`s.
+fn kinds(list: []const u8) u64 {
+ var set: u64 = 0;
+ var names = std.mem.tokenizeScalar(u8, list, ',');
+ while (names.next()) |name| {
+ const kind = std.meta.stringToEnum(zt.Kind, name) orelse fail("{s}: not an event kind\n", .{name});
+ set |= kind.bit();
+ }
+ return set;
+}
+
+/// Between the ring and the recorder: at an event of a kind in `mask` the
+/// thread that emitted it waits inside the target, so the tracer can take its
+/// time: read memory from outside, ask the user.
+const Stops = struct {
+ io: std.Io,
+ arena: std.mem.Allocator,
+ rec: *zt.Recorder = undefined,
+ session: *zt.host.Session = undefined,
+ mask: u64 = 0,
+ reads: std.ArrayList(Read) = .empty,
+ interactive: bool = false,
+ /// Some thread waits at an event already pumped.
+ held: bool = false,
+ stdin: ?std.Io.File.Reader = null,
+ stdin_buf: [256]u8 = undefined,
+
+ /// Memory read from outside at each stop: `old` is what the recording has.
+ const Read = struct { spec: []const u8, addr: u64 = 0, old: []u8 = &.{}, new: []u8 = &.{} };
+
+ fn sink(s: *Stops) zt.Sink {
+ return .{ .ctx = s, .emitFn = emit };
+ }
+
+ fn emit(ctx: *anyopaque, ev: *const zt.Event, payload: []const u8) anyerror!void {
+ const s: *Stops = @ptrCast(@alignCast(ctx));
+ if (s.mask & ev.kind.bit() == 0) return s.rec.emit(ev.*, payload);
+ s.held = true;
+ for (s.reads.items) |*r| try s.read(r, ev);
+ try s.rec.emit(ev.*, payload);
+ if (s.interactive) try s.ask(ev, payload);
+ }
+
+ /// The memory first (it belongs to the moment the event ends), and only what changed.
+ fn read(s: *Stops, r: *Read, ev: *const zt.Event) !void {
+ if (r.old.len == 0) {
+ // The first stop: by now the target's libraries are mapped, and a name means something.
+ const found = agent.symbols.find(s.session.pid, r.spec) orelse fail("{s}: nothing called that in the target\n", .{r.spec});
+ if (found.size == 0) fail("{s}: how many bytes? (ADDR:LEN)\n", .{r.spec});
+ r.addr = found.addr;
+ r.old = try s.arena.alloc(u8, found.size);
+ r.new = try s.arena.alloc(u8, found.size);
+ const id = agent.stringId(r.spec);
+ try s.rec.emit(.{ .ts = ev.ts, .tid = ev.tid, .kind = .string, .a = .{ id, 0, 0, 0, 0, 0 } }, r.spec);
+ try s.rec.emit(.{ .ts = ev.ts, .tid = ev.tid, .kind = .variable, .a = .{ r.addr, found.size, id, 0, 0, 0 } }, "");
+ try s.rec.emit(.{ .ts = ev.ts, .tid = ev.tid, .kind = .mem_write, .a = .{ r.addr, found.size, 0, 0, 0, 0 } }, r.old[0..s.peek(r.addr, r.old)]);
+ return;
+ }
+ var changes: agent.regions.Changes = .{ .old = r.old, .new = r.new[0..s.peek(r.addr, r.new)] };
+ while (changes.next()) |change| try s.rec.emit(.{ .ts = ev.ts, .tid = ev.tid, .kind = .mem_write, .a = .{ r.addr + change.at, change.bytes.len, 0, 0, 0, 0 } }, change.bytes);
+ }
+
+ /// The target's memory: it is our child, so no ptrace is needed to read it.
+ fn peek(s: *Stops, addr: u64, buf: []u8) usize {
+ const local = [1]std.posix.iovec{.{ .base = buf.ptr, .len = buf.len }};
+ const remote = [1]std.posix.iovec_const{.{ .base = @ptrFromInt(addr), .len = buf.len }};
+ const rc = linux.process_vm_readv(s.session.pid, &local, &remote, 0);
+ return if (linux.errno(rc) == .SUCCESS) rc else 0;
+ }
+
+ fn ask(s: *Stops, ev: *const zt.Event, payload: []const u8) !void {
+ var out_buf: [4096]u8 = undefined;
+ var stdout = std.Io.File.stdout().writer(s.io, &out_buf);
+ // One reader for the whole run: it holds the lines read ahead.
+ if (s.stdin == null) s.stdin = std.Io.File.stdin().reader(s.io, &s.stdin_buf);
+ const w = &stdout.interface;
+ try w.print("{t} tid={d} aux={d} a={x} {x} {x} {x} {x} {x} +{d}\n", .{ ev.kind, ev.tid, ev.aux, ev.a[0], ev.a[1], ev.a[2], ev.a[3], ev.a[4], ev.a[5], payload.len });
+ while (true) {
+ try w.writeAll("> ");
+ try w.flush();
+ // The end of input ends the asking, not the run.
+ const line = try s.stdin.?.interface.takeDelimiter('\n') orelse "c";
+ var words = std.mem.tokenizeAny(u8, line, " \t\r");
+ const command = words.next() orelse "s";
+ if (std.mem.eql(u8, command, "s")) {
+ return;
+ } else if (std.mem.eql(u8, command, "c")) {
+ s.mask = 0;
+ s.session.ring.hdr.stop_mask.store(0, .release);
+ return;
+ } else if (std.mem.eql(u8, command, "q")) {
+ try s.rec.close();
+ s.session.close();
+ std.process.exit(0);
+ } else if (std.mem.eql(u8, command, "x")) {
+ var bytes: [256]u8 = undefined;
+ const addr = std.fmt.parseInt(u64, words.next() orelse "", 0) catch 0;
+ const len = @min(bytes.len, std.fmt.parseInt(usize, words.next() orelse "64", 0) catch 64);
+ const got = bytes[0..s.peek(addr, bytes[0..len])];
+ var at: usize = 0;
+ while (at < got.len) : (at += 16) try w.print("{x:0>12} {x}\n", .{ addr + at, got[at..@min(got.len, at + 16)] });
+ if (got.len < len) try w.print("{x:0>12} not readable\n", .{addr + got.len});
+ } else try w.writeAll("s: step to the next stop c: continue to the end x ADDR [LEN]: memory q: quit\n");
+ }
+ }
+};