summaryrefslogtreecommitdiff
path: root/src/trace
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 13:36:32 -0300
committerGabriel Schneider <[email protected]>2026-11-10 14:12:08 -0300
commit02aa51a6f54235cf18e627dbbfe21f21e502eb0b (patch)
treea53416bdf0e5bb0ce80da63176fe13393c502a2c /src/trace
parent16895292becf82f493aaced2b10f889bad436156 (diff)
downloadcomputeranim-02aa51a6f54235cf18e627dbbfe21f21e502eb0b.tar.gz
computeranim-02aa51a6f54235cf18e627dbbfe21f21e502eb0b.zip
context: disassembly, telescopes and names in every stop; strings as one table
For a viewer to show what pwndbg's context shows, the debugger records it while the memory is there: each register and the top of the stack followed as pointers three deep (--telescope), every code address met named, eight instructions from the pc disassembled by capstone (built from source for x86, into the command only; pinned as in 03-codenomicom). zt.telescope reads a chain back with the kind of memory each link points into, and ztrace show prints the context, coloured on a terminal as pwndbg colours. The thirty thousand strings of a small run showed that a string map in each keyframe costs 700 bytes of tree a string: strings are now one table for the recording, appended a batch and read whole at open. fib(12) by instruction with everything on: 9 MB, 71 000 moments/s.
Diffstat (limited to 'src/trace')
-rw-r--r--src/trace/Debugger.zig90
-rw-r--r--src/trace/Symbols.zig18
-rw-r--r--src/trace/event.zig8
-rw-r--r--src/trace/root.zig3
-rw-r--r--src/trace/store.zig65
-rw-r--r--src/trace/telescope.zig169
6 files changed, 334 insertions, 19 deletions
diff --git a/src/trace/Debugger.zig b/src/trace/Debugger.zig
index 5e679dd..41a908f 100644
--- a/src/trace/Debugger.zig
+++ b/src/trace/Debugger.zig
@@ -65,6 +65,22 @@ next_id: u32 = 1,
/// What the sink was sent of the target's memory, by page.
shadow: std.AutoHashMapUnmanaged(u64, *Page) = .empty,
scratch: std.ArrayList(u8) = .empty,
+/// Decodes one instruction into `text`; null where there is none. Whoever
+/// has a disassembler sets it (the ztrace command links capstone): the
+/// library has none of its own.
+disasm: ?*const fn (code: []const u8, addr: u64, text: []u8) ?Insn = null,
+/// The instructions from the pc on whose text a stop records.
+disasm_ahead: usize = 8,
+/// How far a stop follows pointers, from each register and from each of
+/// the first `telescope_words` words of the stack: the memory they lead to
+/// is recorded, and each that leads into code is named. 0, the library's
+/// default: not at all (the commands ask for 3).
+telescope: u8 = 0,
+telescope_words: usize = 16,
+/// The addresses already named, and the instructions already recorded
+/// with the length of each.
+described: std.AutoHashMapUnmanaged(u64, void) = .empty,
+code_len: std.AutoHashMapUnmanaged(u64, u8) = .empty,
/// The static probes armed (`usdt`): what each one's hook reads.
sites: std.ArrayList(*Site) = .empty,
/// The threads that have stopped before: a first stop is a thread's birth.
@@ -99,6 +115,8 @@ pub const Hook = struct {
pub const Action = enum { go, stop };
pub const Breakpoint = struct { id: u32, addr: u64, saved: u8, hook: ?Hook };
+/// An instruction decoded: its length and its text ("mov rbp, rsp").
+pub const Insn = struct { len: u8, text: []const u8 };
pub const Watch = struct { addr: u64, len: usize };
const Page = struct {
@@ -140,6 +158,8 @@ pub fn deinit(d: *Debugger) void {
d.breakpoints.deinit(d.gpa);
for (d.sites.items) |site| d.gpa.destroy(site);
d.sites.deinit(d.gpa);
+ d.described.deinit(d.gpa);
+ d.code_len.deinit(d.gpa);
var pages = d.shadow.valueIterator();
while (pages.next()) |page| d.gpa.destroy(page.*);
d.shadow.deinit(d.gpa);
@@ -368,11 +388,74 @@ fn report(d: *Debugger, stop: Stop) !Stop {
try d.emitLine();
if (d.stack_watch > 0) try d.snapshot(d.regs.rsp, d.stack_watch);
for (d.watches.items) |w| try d.snapshot(w.addr, w.len);
+ try d.emitCode();
+ try d.emitTelescope();
}
try d.emitStop(stop);
return stop;
}
+/// The instructions at the pc and after it, each a string (`event.codeId`)
+/// recorded once: what a viewer shows as the disassembly.
+fn emitCode(d: *Debugger) !void {
+ const insnAt = d.disasm orelse return;
+ var code: [256]u8 = undefined;
+ // Read only when an instruction not seen before is met: a loop costs nothing.
+ var n: ?usize = null;
+ var at: usize = 0;
+ for (0..d.disasm_ahead) |_| {
+ const addr = d.regs.rip + at;
+ if (d.code_len.get(addr)) |len| {
+ at += len;
+ continue;
+ }
+ if (n == null) n = d.read(d.regs.rip, code[0..@min(code.len, d.disasm_ahead * 15)]);
+ if (at >= n.?) break;
+ // A byte for the length, then the text.
+ var text: [192]u8 = undefined;
+ const insn = insnAt(code[at..n.?], addr, text[1..]) orelse break;
+ text[0] = insn.len;
+ try d.emit(.{ .kind = .string, .a = .{ event.codeId(addr), 0, 0, 0, 0, 0 } }, text[0 .. 1 + insn.text.len]);
+ try d.code_len.put(d.gpa, addr, insn.len);
+ at += insn.len;
+ }
+}
+
+/// What a viewer follows from the registers and the top of the stack, as
+/// pwndbg's telescope does: recorded here, while the memory is there to read.
+fn emitTelescope(d: *Debugger) !void {
+ if (d.telescope == 0) return;
+ const r = &d.regs;
+ for ([_]u64{ r.rip, r.rax, r.rbx, r.rcx, r.rdx, r.rsi, r.rdi, r.rbp, r.rsp, r.r8, r.r9, r.r10, r.r11, r.r12, r.r13, r.r14, r.r15 }) |value| try d.chase(value);
+ var words: [64]u64 = undefined;
+ const n = d.read(r.rsp, std.mem.sliceAsBytes(words[0..@min(words.len, d.telescope_words)])) / 8;
+ for (words[0..n]) |value| try d.chase(value);
+}
+
+/// Follows `value` as a pointer: a pointer into code gets its name and
+/// ends the chain, any other readable target is recorded (32 bytes: a word
+/// to follow, and enough to tell a string) and followed.
+fn chase(d: *Debugger, value: u64) !void {
+ var v = value;
+ for (0..d.telescope) |_| {
+ const m = d.syms.mappingAt(v) orelse return;
+ if (m.prot & 1 == 0) return;
+ if (m.prot & 4 != 0) return d.nameAddress(v);
+ const bytes = try d.snap(v, 32);
+ const off: usize = @intCast(v & 7);
+ if (bytes.len < off + 8) return;
+ v = std.mem.readInt(u64, bytes[off..][0..8], .little);
+ }
+}
+
+/// The string whose id is `addr`: its name ("main+4"), recorded once.
+fn nameAddress(d: *Debugger, addr: u64) !void {
+ if ((try d.described.getOrPut(d.gpa, addr)).found_existing) return;
+ var buf: [256]u8 = undefined;
+ var w: std.Io.Writer = .fixed(&buf);
+ if (d.syms.label(&w, addr) catch false) try d.emit(.{ .kind = .string, .a = .{ addr, 0, 0, 0, 0, 0 } }, w.buffered());
+}
+
fn emitStop(d: *Debugger, stop: Stop) !void {
const r = &d.regs;
const regs = std.mem.asBytes(r);
@@ -488,6 +571,12 @@ pub fn watch(d: *Debugger, addr: u64, len: usize) !void {
/// target, then only the words (8 bytes, aligned) the sink was not sent
/// before or that changed since.
pub fn snapshot(d: *Debugger, addr: u64, len: usize) !void {
+ _ = try d.snap(addr, len);
+}
+
+/// `snapshot`, returning what was read: from `addr` rounded down to a word,
+/// valid until the next read.
+fn snap(d: *Debugger, addr: u64, len: usize) ![]const u8 {
const start = addr & ~@as(u64, 7);
try d.scratch.resize(d.gpa, std.mem.alignForward(usize, len + (addr - start), 8));
const bytes = d.scratch.items[0 .. d.read(start, d.scratch.items) & ~@as(usize, 7)];
@@ -521,6 +610,7 @@ pub fn snapshot(d: *Debugger, addr: u64, len: usize) !void {
}
}
if (run_from) |from| try d.emitWrite(start + from, bytes[from..]);
+ return bytes;
}
fn emitWrite(d: *Debugger, addr: u64, bytes: []const u8) !void {
diff --git a/src/trace/Symbols.zig b/src/trace/Symbols.zig
index 7c1e345..ace4c41 100644
--- a/src/trace/Symbols.zig
+++ b/src/trace/Symbols.zig
@@ -351,15 +351,23 @@ pub fn lineAddress(s: *Symbols, file: []const u8, wanted: u32) ?u64 {
/// `addr` for a reader: "fib+12 (fib.c:5)", "libc.so.6!write+18",
/// "libc.so.6!27781" where no symbol covers it, "[stack]+1f40".
pub fn describe(s: *Symbols, w: *std.Io.Writer, addr: u64) !void {
- try w.print("{x}", .{addr});
+ try w.print("{x} ", .{addr});
+ if (!try s.label(w, addr)) w.undo(1);
+ if (s.lineAt(addr)) |l| try w.print(" ({s}:{d})", .{ std.fs.path.basename(l.name), l.line });
+}
+
+/// The name of `addr` alone: "fib+12", "libc.so.6!write+18", "[stack]+1f40".
+/// False, and nothing written, for an address with none.
+pub fn label(s: *Symbols, w: *std.Io.Writer, addr: u64) !bool {
if (s.moduleAt(addr)) |m| {
const sym = s.symbolAt(addr);
- try w.writeAll(" ");
// The executable is the first module mapped: its symbols need no prefix.
if (sym == null or m != &s.modules.items[0]) try w.print("{s}!", .{std.fs.path.basename(m.path)});
if (sym) |found| try w.print("{s}+{d}", .{ found.name, addr - found.addr }) else try w.print("{x}", .{addr - m.bias});
- } else if (s.mappingAt(addr)) |m| {
- if (m.name.len > 0) try w.print(" {s}+{x}", .{ m.name, addr - m.start });
+ return true;
}
- if (s.lineAt(addr)) |l| try w.print(" ({s}:{d})", .{ std.fs.path.basename(l.name), l.line });
+ const m = s.mappingAt(addr) orelse return false;
+ if (m.name.len == 0) return false;
+ try w.print("{s}+{x}", .{ m.name, addr - m.start });
+ return true;
}
diff --git a/src/trace/event.zig b/src/trace/event.zig
index 9ce8e94..7830979 100644
--- a/src/trace/event.zig
+++ b/src/trace/event.zig
@@ -168,6 +168,14 @@ pub fn stringId(text: []const u8) u64 {
return std.hash.Wyhash.hash(0, text) | 1 << 63;
}
+/// The id of the string that describes the instruction at `addr`: a byte
+/// for its length, then its text ("mov rbp, rsp"). The string whose id is
+/// `addr` itself is the address's name ("main+4"). Addresses stay below
+/// bit 47 and hashed ids have bit 63: bit 62 keeps the two apart.
+pub fn codeId(addr: u64) u64 {
+ return addr | 1 << 62;
+}
+
pub fn now() u64 {
var ts: std.os.linux.timespec = undefined;
_ = std.os.linux.clock_gettime(.MONOTONIC, &ts);
diff --git a/src/trace/root.zig b/src/trace/root.zig
index 62a7a90..88e2935 100644
--- a/src/trace/root.zig
+++ b/src/trace/root.zig
@@ -9,6 +9,8 @@ pub const store = @import("store.zig");
pub const Recorder = store.Recorder;
pub const Trace = store.Trace;
pub const ptrace = @import("ptrace.zig");
+/// Pointers followed through a moment, pwndbg's way.
+pub const telescope = @import("telescope.zig");
pub const Debugger = @import("Debugger.zig");
pub const Symbols = @import("Symbols.zig");
pub const syscalls = @import("syscalls.zig");
@@ -28,6 +30,7 @@ test {
_ = Ring;
_ = store;
_ = ptrace;
+ _ = telescope;
_ = Debugger;
_ = Symbols;
_ = syscalls;
diff --git a/src/trace/store.zig b/src/trace/store.zig
index c8c32e7..0b7e8fe 100644
--- a/src/trace/store.zig
+++ b/src/trace/store.zig
@@ -4,6 +4,7 @@
//! root = map {
//! moments list of bytes: a moment's events, encoded (`Codec`)
//! keys list of keyframe, one a batch of moments (4096)
+//! strings list of bytes: the strings defined in each batch, (id, length, text)*
//! }
//! keyframe = map {
//! moment the last moment it holds
@@ -15,9 +16,12 @@
//! heap sorted map, big-endian ptr -> Allocation: the live allocations
//! vars sorted map, big-endian addr -> Variable: the live named variables
//! maps sorted map, big-endian addr -> Mapping, path: the mapped regions
-//! strings map id -> text
//! }
//!
+//! Strings are names, not state: one table for the whole recording, read
+//! whole when it is opened. (As a map in each keyframe, the thirty thousand
+//! instructions and names of a small run cost twenty megabytes of tree.)
+//!
//! A keyframe shares what did not change with the one before, so its cost
//! is what changed since, once, however often it changed. The state at any
//! moment is the keyframe before it with the moments since replayed over
@@ -206,7 +210,8 @@ const State = struct {
const t: ?*Thread = if (ev.tid != 0) try s.thread(gpa, ev.tid) else null;
switch (ev.kind) {
.mem_write => return s.write(gpa, a[0], payload),
- .string => return s.strings.put(gpa, a[0], try s.arena.allocator().dupe(u8, payload)),
+ // A reader has every string from the recording's table already.
+ .string => return if (s.mem_dirty != null) s.strings.put(gpa, a[0], try s.arena.allocator().dupe(u8, payload)),
.alloc => try s.heap.put(gpa, a[0], .{ .ptr = a[0], .size = a[1], .pc = a[2], .born = s.count }),
// Freeing what was never seen allocated removes nothing.
.free => try s.heap.put(gpa, a[0], null),
@@ -536,8 +541,14 @@ pub const Recorder = struct {
}
}
if (s.strings.count() > 0) {
- const strings = try Map.init(try k.putCursor(key(.strings)));
- for (s.strings.keys(), s.strings.values()) |id, text| try strings.put(id, .{ .bytes = text });
+ var table: std.ArrayList(u8) = .empty;
+ defer table.deinit(r.gpa);
+ for (s.strings.keys(), s.strings.values()) |id, text| {
+ try table.appendSlice(r.gpa, std.mem.asBytes(&id));
+ try table.appendSlice(r.gpa, std.mem.asBytes(&@as(u32, @intCast(text.len))));
+ try table.appendSlice(r.gpa, text);
+ }
+ try (try List.init(try root.putCursor(key(.strings)))).append(.{ .bytes = table.items });
}
}
};
@@ -553,6 +564,9 @@ pub const Trace = struct {
len: u64,
/// The last moment of each keyframe.
key_moments: []u64,
+ /// Every string the recording defines, by id.
+ strings: std.AutoHashMapUnmanaged(u64, []const u8) = .empty,
+ strings_arena: std.heap.ArenaAllocator,
cache: *Cache,
const Map = ReadDB.HashMap(.read_only);
@@ -586,7 +600,24 @@ pub const Trace = struct {
errdefer gpa.destroy(db);
db.* = try ReadDB.init(io, .{ .file = file, .fsync = false });
- var t: Trace = .{ .gpa = gpa, .io = io, .file = file, .db = db, .len = 0, .key_moments = &.{}, .cache = undefined };
+ var t: Trace = .{ .gpa = gpa, .io = io, .file = file, .db = db, .len = 0, .key_moments = &.{}, .strings_arena = .init(gpa), .cache = undefined };
+ errdefer {
+ t.strings.deinit(gpa);
+ t.strings_arena.deinit();
+ }
+ if (try root0(db).getCursor(key(.strings))) |cursor| {
+ var it = try (try List.init(cursor)).iterator();
+ while (try it.next()) |blob| {
+ const table = try blob.readBytesAlloc(t.strings_arena.allocator(), null);
+ var pos: usize = 0;
+ while (pos < table.len) {
+ const id = std.mem.readInt(u64, table[pos..][0..8], .little);
+ const len = std.mem.readInt(u32, table[pos + 8 ..][0..4], .little);
+ try t.strings.put(gpa, id, table[pos + 12 ..][0..len]);
+ pos += 12 + len;
+ }
+ }
+ }
const root = try Map.init(db.rootCursor().readOnly());
if (try root.getCursor(key(.moments))) |cursor| t.len = try (try List.init(cursor)).count();
var key_moments: std.ArrayList(u64) = .empty;
@@ -603,7 +634,14 @@ pub const Trace = struct {
return t;
}
+ fn root0(db: *ReadDB) Map {
+ // An empty file has no root map yet: a map that holds nothing.
+ return Map.init(db.rootCursor().readOnly()) catch unreachable;
+ }
+
pub fn close(t: *Trace) void {
+ t.strings.deinit(t.gpa);
+ t.strings_arena.deinit();
for (&t.cache.slots) |*slot| {
slot.state.deinit(t.gpa);
slot.events.deinit(t.gpa);
@@ -869,16 +907,15 @@ pub const Moment = struct {
return found.mapping;
}
+ /// The string with this id, copied into `buf`: a file's name, a
+ /// function's, a type's description, an instruction (`event.codeId`).
+ /// Strings are the recording's, not a moment's: one defined later is
+ /// found too.
pub fn string(m: Moment, id: u64, buf: []u8) !?[]const u8 {
- const s = try m.state();
- if (s.strings.get(id)) |text| {
- const n = @min(buf.len, text.len);
- @memcpy(buf[0..n], text[0..n]);
- return buf[0..n];
- }
- const base = s.base orelse return null;
- const all = try Trace.Map.init((try base.getCursor(key(.strings))) orelse return null);
- return try ((try all.getCursor(id)) orelse return null).readBytes(buf);
+ const text = m.trace.strings.get(id) orelse return null;
+ const n = @min(buf.len, text.len);
+ @memcpy(buf[0..n], text[0..n]);
+ return buf[0..n];
}
/// The events that led from the moment before to this one. Free with
diff --git a/src/trace/telescope.zig b/src/trace/telescope.zig
new file mode 100644
index 0000000..f4cf09a
--- /dev/null
+++ b/src/trace/telescope.zig
@@ -0,0 +1,169 @@
+//! Following a value through a moment of a recording, as pwndbg's telescope
+//! does: what it points at, what that points at, until something that is no
+//! pointer; and for each step the kind of memory it lives in, which is what
+//! a viewer colours a pointer by.
+const std = @import("std");
+const event = @import("event.zig");
+const store = @import("store.zig");
+const Moment = store.Moment;
+
+/// The kind of memory an address is in, from its mapping.
+pub const Region = enum {
+ /// Not mapped: the value is a number.
+ none,
+ /// Executable.
+ code,
+ /// Writable and executable: worth a look of its own.
+ rwx,
+ stack,
+ heap,
+ /// Writable: a program's variables, an anonymous mapping.
+ data,
+ /// Readable only: constants.
+ rodata,
+
+ pub fn of(mapping: store.Mapping, name: []const u8) Region {
+ if (mapping.prot & 4 != 0) return if (mapping.prot & 2 != 0) .rwx else .code;
+ if (std.mem.eql(u8, name, "[stack]")) return .stack;
+ if (std.mem.eql(u8, name, "[heap]")) return .heap;
+ return if (mapping.prot & 2 != 0) .data else .rodata;
+ }
+};
+
+pub const Link = struct {
+ value: u64,
+ /// Where `value` points; `.none` when it is no pointer.
+ region: Region,
+ /// What the chain ends on, when it ends on something that can be said:
+ /// a code address's name ("main+4"), or the string the pointer leads to.
+ text: []const u8 = "",
+ /// `text` is a string found in memory, not a name.
+ string: bool = false,
+};
+
+/// The kind of memory `addr` is in at this moment.
+pub fn region(m: Moment, addr: u64) !Region {
+ var name: []const u8 = "";
+ var buf: [64]u8 = undefined;
+ const mapping = (try m.mapping(addr, &name, &buf)) orelse return .none;
+ const kind = Region.of(mapping, name);
+ // An allocation outside the heap the kernel names: an arena of mmap's.
+ return if (kind == .data and try m.allocation(addr) != null) .heap else kind;
+}
+
+/// The chain from `value`: itself, what it points at, and on, as far as
+/// `links` goes. A chain ends at a number, at code (named, when the
+/// recording named it), at a string (four printable bytes or more, ended
+/// by a zero), or at memory that was never recorded. `text` holds the
+/// names and strings the links refer to.
+pub fn chase(m: Moment, value: u64, links: []Link, text: []u8) ![]Link {
+ var v = value;
+ var n: usize = 0;
+ while (n < links.len) {
+ const link = &links[n];
+ link.* = .{ .value = v, .region = try region(m, v) };
+ n += 1;
+ switch (link.region) {
+ .none => break,
+ .code, .rwx => {
+ if (try m.string(v, text)) |name| link.text = name;
+ break;
+ },
+ else => {},
+ }
+ var bytes: [32]u8 = undefined;
+ var known: [32]bool = undefined;
+ try m.read(v, &bytes, &known);
+ var printable: usize = 0;
+ while (printable < bytes.len and known[printable] and bytes[printable] >= 0x20 and bytes[printable] < 0x7f) printable += 1;
+ const ended = printable == bytes.len or (known[printable] and bytes[printable] == 0);
+ if (printable >= 4 and ended and printable <= text.len) {
+ @memcpy(text[0..printable], bytes[0..printable]);
+ link.text = text[0..printable];
+ link.string = true;
+ break;
+ }
+ if (std.mem.indexOfScalar(bool, known[0..8], false) != null) break;
+ v = std.mem.readInt(u64, bytes[0..8], .little);
+ }
+ return links[0..n];
+}
+
+/// The instruction at `addr` as the recording has it (`event.codeId`): its
+/// length and its text. Null where none was recorded.
+pub fn instruction(m: Moment, addr: u64, buf: []u8) !?struct { len: u8, text: []const u8 } {
+ const s = (try m.string(event.codeId(addr), buf)) orelse return null;
+ if (s.len == 0) return null;
+ return .{ .len = s[0], .text = s[1..] };
+}
+
+test "a chain is followed to a string, to code, to a number, and no further than is known" {
+ const gpa = std.testing.allocator;
+ var tmp = std.testing.tmpDir(.{});
+ defer tmp.cleanup();
+ var dir_buf: [std.Io.Dir.max_path_bytes]u8 = undefined;
+ const dir = dir_buf[0..try tmp.dir.realPath(std.testing.io, &dir_buf)];
+ const path = try std.fs.path.join(gpa, &.{ dir, "t.ztrace" });
+ defer gpa.free(path);
+
+ var rec = try store.Recorder.create(gpa, std.testing.io, path);
+ const map = struct {
+ fn at(r: *store.Recorder, addr: u64, len: u64, prot: u64, name: []const u8) !void {
+ try r.emit(.{ .kind = .map, .tid = 1, .a = .{ addr, len, prot, 0, 0, 0 } }, name);
+ }
+ }.at;
+ try map(&rec, 0x400000, 0x1000, 5, "/bin/prog");
+ try map(&rec, 0x600000, 0x1000, 3, "/bin/prog");
+ try map(&rec, 0x7ff000, 0x1000, 3, "[stack]");
+ try map(&rec, 0x900000, 0x1000, 3, "");
+ try rec.emit(.{ .kind = .alloc, .tid = 1, .a = .{ 0x900010, 32, 0, 0, 0, 0 } }, "");
+ try rec.emit(.{ .kind = .string, .a = .{ 0x400123, 0, 0, 0, 0, 0 } }, "main+4");
+ try rec.emit(.{ .kind = .string, .a = .{ event.codeId(0x400123), 0, 0, 0, 0, 0 } }, "\x03mov rbp, rsp");
+ const word = struct {
+ fn at(r: *store.Recorder, addr: u64, value: u64) !void {
+ try r.emit(.{ .kind = .mem_write, .tid = 1, .a = .{ addr, 8, 0, 0, 0, 0 } }, std.mem.asBytes(&value));
+ }
+ }.at;
+ // Stack word -> heap -> a string in the data; another -> code; another -> a number.
+ try word(&rec, 0x7ff100, 0x900010);
+ try word(&rec, 0x900010, 0x600020);
+ try rec.emit(.{ .kind = .mem_write, .tid = 1, .a = .{ 0x600020, 6, 0, 0, 0, 0 } }, "hello\x00");
+ try word(&rec, 0x7ff108, 0x400123);
+ try word(&rec, 0x7ff110, 42);
+ try rec.emit(.{ .kind = .mark, .tid = 1 }, "");
+ try rec.close();
+
+ var trace = try store.Trace.open(gpa, std.testing.io, path);
+ defer trace.close();
+ const m = try trace.moment(0);
+ var links: [6]Link = undefined;
+ var text: [64]u8 = undefined;
+
+ const to_string = try chase(m, 0x7ff100, &links, &text);
+ try std.testing.expectEqual(@as(usize, 3), to_string.len);
+ try std.testing.expectEqual(Region.stack, to_string[0].region);
+ try std.testing.expectEqual(Region.heap, to_string[1].region);
+ try std.testing.expectEqual(Region.data, to_string[2].region);
+ try std.testing.expectEqualStrings("hello", to_string[2].text);
+ try std.testing.expect(to_string[2].string);
+
+ const to_code = try chase(m, 0x7ff108, &links, &text);
+ try std.testing.expectEqual(@as(usize, 2), to_code.len);
+ try std.testing.expectEqual(Region.code, to_code[1].region);
+ try std.testing.expectEqualStrings("main+4", to_code[1].text);
+
+ const to_number = try chase(m, 0x7ff110, &links, &text);
+ try std.testing.expectEqual(@as(usize, 2), to_number.len);
+ try std.testing.expectEqual(@as(u64, 42), to_number[1].value);
+ try std.testing.expectEqual(Region.none, to_number[1].region);
+
+ // A pointer to memory never recorded is a pointer still, and ends there.
+ const unknown = try chase(m, 0x7ff800, &links, &text);
+ try std.testing.expectEqual(@as(usize, 1), unknown.len);
+ try std.testing.expectEqual(Region.stack, unknown[0].region);
+
+ const insn = (try instruction(m, 0x400123, &text)).?;
+ try std.testing.expectEqual(@as(u8, 3), insn.len);
+ try std.testing.expectEqualStrings("mov rbp, rsp", insn.text);
+ try std.testing.expect(try instruction(m, 0x400126, &text) == null);
+}