summaryrefslogtreecommitdiff
path: root/anim/src/Recording.zig
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 16:05:20 -0300
committerGabriel Schneider <[email protected]>2026-11-10 16:43:58 -0300
commit165bb6c1344b98de7bef1d3c2b72147b4a40797a (patch)
tree0e70e6222700063f604f78673f6ab3a5bfb9242d /anim/src/Recording.zig
parent66a2a7cf733f6abc1f79561c52d901ce67019fb1 (diff)
downloadcomputeranim-165bb6c1344b98de7bef1d3c2b72147b4a40797a.tar.gz
computeranim-165bb6c1344b98de7bef1d3c2b72147b4a40797a.zip
canim: the renderer speaks the design language
The blocks, their states and the tokens carry the catalogue's names: atoms in ui, chain/reg/slot in rows, insn with its line column, jump lane and annotations (read, write, taken or not, a call with its arguments, a return, a syscall) in disasm, bytes and hexdump with field paper and the reading column, the three splits and relayout in stage, the ties (thread, link and pin, projection, echo). A lens is a band over the whole context, its drawing left and its bytes right. Frames' spans on the stack, each instruction's line and a callee's parameter count come from the tracer. A gallery scene draws every block; the test compares six of its pages with pictures kept in test/gallery, drawn from a recording kept there too. The scenes are ported; the motion checks report no pop and no metronome in any of them. Co-Authored-By: Claude Fable 5.2 <[email protected]>
Diffstat (limited to 'anim/src/Recording.zig')
-rw-r--r--anim/src/Recording.zig89
1 files changed, 83 insertions, 6 deletions
diff --git a/anim/src/Recording.zig b/anim/src/Recording.zig
index aeaacf9..92bb917 100644
--- a/anim/src/Recording.zig
+++ b/anim/src/Recording.zig
@@ -63,6 +63,18 @@ pub const Born = struct { ptr: u64, size: u64, moment: u64, event: u64 };
/// A run of bytes a moment changed, or read.
pub const Span = struct { addr: u64, len: u64 };
+/// What the instruction at a moment's pc is about to do to memory (the
+/// debugger's `touch`): `how` 1 reads there, 2 writes there, 3 both.
+pub const Touch = struct { addr: u64, len: u64, how: u8 };
+
+/// Where the instruction at a moment's pc goes, if it is a call, a jump
+/// or a return (the debugger's `branch`), and whether it will.
+pub const Branch = struct { to: u64, taken: bool, kind: enum(u8) { none, call, jump, ret } };
+
+/// The source line an instruction was compiled from, as the recording saw
+/// the program stopped there.
+pub const CodeLine = struct { addr: u64, line: u32 };
+
/// Where a cursor's step may end.
pub const Stop = enum {
/// The next moment, whatever the recorder made one: an instruction, a line.
@@ -105,6 +117,12 @@ allocations: []Born = &.{},
registers: []u32 = &.{},
write_spans: Spans = .{},
read_spans: Spans = .{},
+/// For each moment, what the instruction at its pc touches and where it branches.
+insn_touches: [][2]?Touch = &.{},
+insn_branches: []?Branch = &.{},
+/// Every instruction address the program stopped at in its own source,
+/// with that line, in address order.
+code_lines: []CodeLine = &.{},
strings: std.AutoHashMapUnmanaged(u64, []const u8) = .empty,
arena: std.heap.ArenaAllocator,
@@ -151,11 +169,35 @@ fn load(bytes: []const u8, file: []const u8, source: []const u8) !*Recording {
}
/// The instruction at `addr` as the debugger disassembled it at moment
-/// `i` (`text` is Intel syntax, in `buf`); null where it recorded none.
-/// `back` is how long the instruction before it in its function is (0: not known).
-pub fn instruction(r: *const Recording, i: u64, addr: u64, buf: []u8) ?struct { len: u8, back: u8, text: []const u8 } {
+/// `i` (`text` is Intel syntax, in `buf`: give it 212 bytes or more); null
+/// where it recorded none. `back` is how long the instruction before it in
+/// its function is (0: not known); `line`, the line of the program's own
+/// source it was compiled from (null: another file's, or not known);
+/// `params`, a direct call's callee's parameter count.
+pub fn instruction(r: *const Recording, i: u64, addr: u64, buf: []u8) ?struct { len: u8, back: u8, text: []const u8, line: ?u32, params: ?u8 } {
const found = (zt.telescope.instruction(r.moment(i), addr, buf) catch return null) orelse return null;
- return .{ .len = found.len, .back = found.back, .text = found.text };
+ var line: ?u32 = null;
+ if (found.line) |l| if (std.mem.eql(u8, std.fs.path.basename(r.name(l.file)), r.file)) {
+ line = l.line;
+ };
+ return .{ .len = found.len, .back = found.back, .text = found.text, .line = line orelse r.lineOf(addr), .params = found.params };
+}
+
+/// The source line the instruction at `addr` was compiled from, for a
+/// recording whose instructions do not carry it (`instruction` gives it
+/// where they do): where the program stopped there, the line it was on;
+/// else the line of the nearest instruction before it that it stopped at,
+/// close by. Null where nothing is known.
+pub fn lineOf(r: *const Recording, addr: u64) ?u32 {
+ var lo: usize = 0;
+ var hi: usize = r.code_lines.len;
+ while (lo < hi) {
+ const mid = (lo + hi) / 2;
+ if (r.code_lines[mid].addr <= addr) lo = mid + 1 else hi = mid;
+ }
+ if (lo == 0) return null;
+ const near = r.code_lines[lo - 1];
+ return if (addr - near.addr <= 96) near.line else null;
}
/// The first line a source panel of `fit` lines shows when the program is
@@ -200,6 +242,12 @@ fn index(r: *Recording) !void {
var write_ends: std.ArrayList(u32) = .empty;
var reads: std.ArrayList(Span) = .empty;
var read_ends: std.ArrayList(u32) = .empty;
+ var touch_list: std.ArrayList([2]?Touch) = .empty;
+ // What the instruction at a stop is about to read is read by the step after it.
+ var pending_reads: [2]?Touch = .{ null, null };
+ var branch_list: std.ArrayList(?Branch) = .empty;
+ var code_lines: std.AutoHashMapUnmanaged(u64, u32) = .empty;
+ defer code_lines.deinit(gpa);
var open_calls: std.ArrayList(u32) = .empty;
defer open_calls.deinit(gpa);
// A recording of instructions tells no calls: they are read off the
@@ -230,7 +278,10 @@ fn index(r: *Recording) !void {
// An instrumented program's own events are drained before the
// debugger reports its stop: what follows its line is the debugger's.
var debugger_spoke = false;
+ var touched: [2]?Touch = .{ null, null };
+ var branched: ?Branch = null;
snapshots.clearRetainingCapacity();
+ for (pending_reads) |p| if (p) |read_by| if (read_by.how & 1 != 0) try reads.append(arena, .{ .addr = read_by.addr, .len = read_by.len });
while (events.next()) |item| {
const ev = item.ev;
count += 1;
@@ -281,6 +332,16 @@ fn index(r: *Recording) !void {
if (ev.a[0] >> 63 != 0) debugger_spoke = true;
},
.step, .breakpoint => stepped = true,
+ .touch => {
+ const slot: usize = if (touched[0] == null) 0 else 1;
+ if (touched[slot] == null) touched[slot] = .{ .addr = ev.a[0], .len = ev.a[1], .how = @intCast(ev.aux & 3) };
+ },
+ .branch => branched = .{ .to = ev.a[0], .taken = ev.a[1] != 0, .kind = switch (ev.aux) {
+ 1 => .call,
+ 2 => .jump,
+ 3 => .ret,
+ else => .none,
+ } },
else => {},
}
}
@@ -316,6 +377,10 @@ fn index(r: *Recording) !void {
const ours = line.line != 0 and std.mem.eql(u8, std.fs.path.basename(r.name(line.file)), r.file);
try own.append(arena, if (ours) line.line else if (own.items.len > 0) own.items[own.items.len - 1] else 0);
try reached.append(arena, ours and line_file != null);
+ try touch_list.append(arena, touched);
+ pending_reads = touched;
+ try branch_list.append(arena, branched);
+ if (ours and regs != null) try code_lines.put(gpa, regs.?.rip, line.line);
try registers.append(arena, if (regs != null and before != null) changedRegisters(before.?, regs.?) else 0);
if (!told and stepped and regs != null and before != null) {
@@ -380,6 +445,17 @@ fn index(r: *Recording) !void {
r.allocations = allocations.items;
r.registers = registers.items;
r.write_spans = .{ .all = writes.items, .ends = write_ends.items };
+ r.insn_touches = touch_list.items;
+ r.insn_branches = branch_list.items;
+ r.code_lines = try arena.alloc(CodeLine, code_lines.count());
+ var it = code_lines.iterator();
+ var n: usize = 0;
+ while (it.next()) |e| : (n += 1) r.code_lines[n] = .{ .addr = e.key_ptr.*, .line = e.value_ptr.* };
+ std.mem.sort(CodeLine, r.code_lines, {}, struct {
+ fn less(_: void, a: CodeLine, b: CodeLine) bool {
+ return a.addr < b.addr;
+ }
+ }.less);
r.read_spans = .{ .all = reads.items, .ends = read_ends.items };
}
@@ -392,8 +468,9 @@ fn intern(r: *Recording, text: []const u8) !u64 {
pub const Function = struct {
name: []const u8,
- /// Whether it has parameters: `main(void)` has none.
+ /// Whether it has parameters: `main(void)` has none; and how many.
takes: bool,
+ params: usize = 0,
/// Its declaration's first line (from 1) and last.
first: u32,
last: u32,
@@ -413,7 +490,7 @@ pub fn outline(arena: std.mem.Allocator, source: []const u8, file: []const u8) !
if (from == paren) continue;
const close = std.mem.indexOfScalarPos(u8, header, paren, ')') orelse header.len;
const params = std.mem.trim(u8, header[paren + 1 .. close], " ");
- try found.append(arena, .{ .name = header[from..paren], .takes = params.len > 0 and !std.mem.eql(u8, params, "void"), .first = @intCast(d.start_line + 1), .last = @intCast(d.end_line + 1) });
+ try found.append(arena, .{ .name = header[from..paren], .takes = params.len > 0 and !std.mem.eql(u8, params, "void"), .params = if (params.len > 0 and !std.mem.eql(u8, params, "void")) std.mem.count(u8, params, ",") + 1 else 0, .first = @intCast(d.start_line + 1), .last = @intCast(d.end_line + 1) });
}
return found.items;
}