summaryrefslogtreecommitdiff
path: root/anim/src/disasm.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/disasm.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/disasm.zig')
-rw-r--r--anim/src/disasm.zig419
1 files changed, 419 insertions, 0 deletions
diff --git a/anim/src/disasm.zig b/anim/src/disasm.zig
new file mode 100644
index 0000000..e429643
--- /dev/null
+++ b/anim/src/disasm.zig
@@ -0,0 +1,419 @@
+//! `disasm` (design/README.md, "3. Panels"): seventeen `insn`s in address
+//! order, the pc's, eight above and eight below (eleven as the lens's
+//! subject): pwndbg's way, each instruction and what its operands are now.
+//! Rows above the pc are the function's own; near its start there are
+//! fewer and the pc's row sits higher. Past the function's end the rows
+//! are `outside`. The rows that ran in the last three steps are `ran`,
+//! with the jump lane showing how control came here. The current line's
+//! runs of instructions are published for the `thread`.
+//! Reads the recorded instructions (`zt.telescope.instruction`), each
+//! moment's `touch` and `branch`, and the registers.
+const std = @import("std");
+const sk = @import("sketch");
+const anim = @import("anim");
+const zt = @import("ztrace");
+const ui = @import("ui.zig");
+const rows = @import("rows.zig");
+const cursors = @import("cursor.zig");
+const Recording = @import("Recording.zig");
+const ties = @import("ties.zig");
+const context = @import("context.zig");
+const Stage = @import("stage.zig").Stage;
+const theme = ui.theme;
+const time = theme.time;
+const Rect = ui.Rect;
+const t = theme.color.text;
+const m = theme.metric.context;
+const c = theme.metric.insn;
+const size = theme.size.mono.context;
+const adv = size * 3 / 5;
+
+/// An instruction in the window.
+pub const Insn = struct {
+ addr: u64,
+ len: u8,
+ text: []const u8,
+ /// Past the function's end.
+ outside: bool = false,
+ /// The line of the program's source it was compiled from.
+ line: ?u32 = null,
+ /// A direct call's callee's parameter count.
+ params: ?u8 = null,
+
+ pub fn mnemonic(i: Insn) []const u8 {
+ return i.text[0 .. std.mem.indexOfScalar(u8, i.text, ' ') orelse i.text.len];
+ }
+
+ pub fn operands(i: Insn) []const u8 {
+ return std.mem.trim(u8, i.text[i.mnemonic().len..], " ");
+ }
+};
+
+/// The window at a moment: the instructions, and which is the pc's.
+const Listing = struct { rows: []Insn, pc: usize };
+
+pub const Disasm = struct {
+ cursor: cursors.Cursor,
+ stage: *const Stage,
+ focus: bool = false,
+
+ pub fn draw(d: *const Disasm, f: *sk.Frame, placed: anim.Placed) void {
+ const box = d.stage.box(placed, .disasm);
+ const u = context.at(f, placed, box);
+ const now = d.cursor.now(placed);
+ const rec = d.cursor.rec;
+ const room = theme.layout.rowsIn(box.h);
+ const above = (room -| 1) / 2;
+ // The mark: it moves last, with the source's and rip.
+ const going = now.advancing();
+ const from = listing(u, rec, now.marks[0], room, above);
+ const to = listing(u, rec, now.marks[1], room, above);
+
+ const pc = [2]u64{ rec.register(now.marks[0], "rip"), rec.register(now.marks[1], "rip") };
+ const name = rec.strings.get(pc[if (going >= 0.5) 1 else 0]) orelse "";
+ const body = u.panel(box.w, box.h, "disassembly", .{ .focus = d.focus, .note = name[0 .. std.mem.lastIndexOfScalar(u8, name, '+') orelse name.len] });
+ const top = body.y + m.pad;
+ u.clip(.{ .x = theme.stroke.rule, .y = m.tag, .w = box.w - 2 * theme.stroke.rule, .h = box.h - m.tag - theme.stroke.rule });
+ defer u.unclip();
+
+ // The two windows as one list, if they are of one function: the
+ // rows scroll, whole rows, on `glide`; else what leaves has left
+ // before what replaces it arrives.
+ var merged: []const Insn = to.rows;
+ var offsets = [2]f32{ 0, 0 };
+ var fade: f32 = 1;
+ var shown = to;
+ if (pc[0] != pc[1] and going < 1) {
+ if (merge(u, from.rows, to.rows)) |both| {
+ merged = both.rows;
+ offsets = .{ @floatFromInt(both.from), @floatFromInt(both.to) };
+ } else {
+ merged = if (going < 0.5) from.rows else to.rows;
+ shown = if (going < 0.5) from else to;
+ fade = @abs(2 * going - 1);
+ }
+ }
+ const scroll = std.math.lerp(offsets[0], offsets[1], cursors.glide(going));
+ const lit = if (fade < 1) u.faded(fade) else u;
+
+ // Where the pc's plaque is: it slides from the row it was on to the
+ // one it goes to (in one function), or goes out and comes in.
+ var mark_y = top + @as(f32, @floatFromInt(shown.pc)) * m.row;
+ var mark_shows: f32 = fade;
+ if (pc[0] != pc[1] and going < 1 and fade >= 1) {
+ const j = std.math.lerp(@as(f32, @floatFromInt(from.pc)) + offsets[0], @as(f32, @floatFromInt(to.pc)) + offsets[1], cursors.standard(going));
+ mark_y = top + (j - scroll) * m.row;
+ }
+ if (to.rows.len == 0) mark_shows = 0;
+
+ // Which moment the current mark stands for, and the three steps before it.
+ const base: usize = if (going >= 0.5) 0 else 1;
+ const current_line = rec.own[now.marks[if (going >= 0.5) 1 else 0]];
+ const lead = blk: {
+ var addrs: [24]u64 = undefined;
+ var n: usize = 0;
+ for (shown.rows) |row| if (!row.outside and n < addrs.len) {
+ addrs[n] = row.addr;
+ n += 1;
+ };
+ break :blk ui.shared(addrs[0..n]);
+ };
+
+ // The pc's row: gold ember across, a plaque with an ink triangle.
+ const gold = theme.mark(.current);
+ const out = now.fires(.disasm);
+ if (mark_shows > 0) {
+ const v = u.faded(mark_shows);
+ v.current(.{ .x = theme.stroke.rule, .y = mark_y, .w = box.w - 2 * theme.stroke.rule, .h = m.row }, theme.metric.plaque.pc, out);
+ sk.draw.polygon(u.f, &.{ .{ 20, mark_y + m.row / 2 }, .{ 10, mark_y + 6 }, .{ 10, mark_y + m.row - 6 } }, v.at.pen(.{ .fill = ui.rgb(gold.on_solid) }));
+ ties.anchor(u, .pc, .{ .x = 0, .y = mark_y, .w = theme.metric.plaque.pc, .h = m.row });
+ }
+
+ var last_line: ?u32 = null;
+ var run: usize = 0;
+ var run_start: ?f32 = null;
+ var lanes: [2]?f32 = .{ null, null };
+ for (merged, 0..) |row, j| {
+ const y = top + (@as(f32, @floatFromInt(j)) - scroll) * m.row;
+ const line = if (row.outside) null else row.line;
+ // The thread: the current line's runs of instructions.
+ const on_line = line != null and line.? == current_line and mark_shows >= 1;
+ if (on_line and run_start == null) run_start = @max(y, top);
+ if (!on_line and run_start != null) {
+ ties.anchor(u, .{ .run = run }, .{ .x = 0, .y = run_start.?, .w = box.w, .h = @min(y, box.h - m.pad) - run_start.? });
+ run += 1;
+ run_start = null;
+ }
+ if (y + m.row < m.tag or y > box.h) {
+ last_line = line;
+ continue;
+ }
+ // `ran`: it ran in one of the last three steps.
+ var ran: ?usize = null;
+ for (0..3) |k| {
+ const at_k = now.stops[@min(base + 1 + k, now.stops.len - 1)];
+ if (at_k != now.stops[base] and rec.register(at_k, "rip") == row.addr) {
+ ran = k;
+ break;
+ }
+ }
+ const is_pc = row.addr == pc[if (going >= 0.5) 1 else 0];
+ if (ran != null and !is_pc) lit.trail(c.mark, y, ran.?);
+ d.insn(lit, now, row, y, box.w, line, line != last_line, current_line, lead, if (is_pc) .current else if (ran) |k| .{ .ran = k } else .ahead, base);
+ last_line = line;
+ // The jump that brought control here: from its row, up or down the lane.
+ if (ran == 0 and !is_pc) if (rec.insn_branches[now.stops[base + 1]]) |b| if (b.kind == .jump and b.taken) {
+ lanes[0] = y;
+ };
+ if (is_pc) lanes[1] = y;
+ }
+ if (run_start) |y0| ties.anchor(u, .{ .run = run }, .{ .x = 0, .y = y0, .w = box.w, .h = @min(top + (@as(f32, @floatFromInt(merged.len)) - scroll) * m.row, box.h - m.pad) - y0 });
+ if (lanes[0] != null and lanes[1] != null and lanes[0].? != lanes[1].?) {
+ const ya = lanes[0].? + m.row / 2;
+ const yb = lanes[1].? + m.row / 2;
+ lit.route(&.{ .{ 38, ya }, .{ c.jump_lane, ya }, .{ c.jump_lane, yb }, .{ 39, yb } }, theme.color.trail[0], .{ .width = theme.stroke.rule, .head = .{ 7, 8 }, .radius = 4 });
+ }
+ context.veiled(u, box, now.veil);
+ }
+
+ const State = union(enum) { current, ran: usize, ahead };
+
+ /// `insn`: an instruction and its annotation, pwndbg's way.
+ fn insn(d: *const Disasm, u: ui.Ui, now: cursors.Now, row: Insn, y: f32, w: f32, line: ?u32, first_of_line: bool, current_line: u32, lead: usize, state: State, base: usize) void {
+ const rec = d.cursor.rec;
+ const base_y = rows.baseline(y);
+ const code_ink = theme.color.region.code_;
+ if (row.outside) {
+ // The function ends: a rule, and the next one's name.
+ u.fill(.{ .x = theme.stroke.rule, .y = y, .w = w - 2 * theme.stroke.rule, .h = theme.stroke.rule }, theme.color.rule);
+ _ = u.address(c.address, base_y, row.addr, .{ .ink = ui.mix(code_ink, theme.color.page, theme.metric.context.lead_alpha) });
+ u.text(.mono, size, c.mnemonic, base_y, row.mnemonic(), t.faint);
+ u.text(.mono, size, c.operands, base_y, clipText(u, row.operands(), c.operand_chars), t.faint);
+ if (rec.strings.get(row.addr)) |name| u.text(.mono, size, c.annotation, base_y, name[0 .. std.mem.lastIndexOfScalar(u8, name, '+') orelse name.len], t.faint);
+ return;
+ }
+ const on = state == .current;
+ _ = u.address(c.address, base_y, row.addr, .{ .ink = ui.rgb(code_ink), .lead = lead });
+ if (first_of_line) if (line) |l| {
+ const num = u.print("{d}", .{l});
+ const now_line = l == current_line;
+ u.text(if (now_line) .mono_bold else .mono, size, c.line + 3 * adv - @as(f32, @floatFromInt(num.len)) * adv, base_y, num, if (now_line) theme.mark(.current).solid else t.faint);
+ };
+ u.text(.mono_bold, size, c.mnemonic, base_y, row.mnemonic(), theme.color.code.keyword);
+ operands(u, row, base_y);
+
+ // The annotation: what it does, now. What it left behind is shown
+ // only where the step ran this instruction alone: a step by line
+ // runs others after it, and the state after them is not its doing.
+ const moment, var after = switch (state) {
+ .current => .{ now.stops[base], if (base == 1) now.stops[0] else null },
+ .ran => |k| .{ now.stops[base + 1 + k], now.stops[base + k] },
+ .ahead => .{ now.stops[base], null },
+ };
+ if (after) |a| if (!alone(rec, moment, a, row)) {
+ after = null;
+ };
+ const room = w - m.side;
+ const x: f32 = c.annotation;
+ const branch = if (state == .ahead) null else rec.insn_branches[moment];
+ const touches = if (state == .ahead) [2]?Recording.Touch{ null, null } else rec.insn_touches[moment];
+ _ = on;
+ if (branch) |b| switch (b.kind) {
+ .call => {
+ const callee = rec.strings.get(b.to) orelse "";
+ u.text(.mono, size, x, base_y, callee[0 .. std.mem.lastIndexOfScalar(u8, callee, '+') orelse callee.len], t.bright);
+ // Its arguments hang under it, a small `reg` a row, as many as the prototype has.
+ if (state == .current) {
+ const callee_name = callee[0 .. std.mem.lastIndexOfScalar(u8, callee, '+') orelse callee.len];
+ // As many as the callee's prototype has (the debug info's, else the source's), three when neither says.
+ const count: usize = row.params orelse for (rec.functions) |fun| {
+ if (std.mem.eql(u8, fun.name, callee_name)) break fun.params;
+ } else 3;
+ const shown_moment = rec.moment(moment);
+ const args = [_][]const u8{ "rdi", "rsi", "rdx", "rcx", "r8", "r9" };
+ for (args[0..@min(count, 6)], 1..) |reg, k| {
+ const ry = y + @as(f32, @floatFromInt(k)) * m.row;
+ u.text(.mono, size, x, rows.baseline(ry), reg, t.dim);
+ _ = rows.chain(u, x + 4 * adv, ry, shown_moment, rec.register(moment, reg), room, .{});
+ }
+ }
+ return;
+ },
+ .ret => {
+ u.text(.mono, size, x, base_y, "\u{2192}", t.faint);
+ _ = u.address(x + 2 * adv, base_y, b.to, .{ .ink = ui.rgb(code_ink), .name = rec.strings.get(b.to) orelse "" });
+ return;
+ },
+ .jump => {
+ // A jump always taken says nothing; a conditional one, which way.
+ if (std.mem.eql(u8, row.mnemonic(), "jmp")) return;
+ if (!b.taken) return u.text(.mono, size, x, base_y, "not taken", t.dim);
+ u.text(.mono, size, x, base_y, "taken", t.primary);
+ return;
+ },
+ .none => {},
+ };
+ if (std.mem.eql(u8, row.mnemonic(), "syscall") and state != .ahead) {
+ const nr = rec.register(moment, "rax");
+ u.text(.mono, size, x, base_y, zt.syscalls.name(nr) orelse "syscall", t.bright);
+ const names = zt.syscalls.names(nr);
+ const carriers = [_][]const u8{ "rdi", "rsi", "rdx" };
+ if (state == .current) for (names[0..@min(names.len, 3)], carriers[0..@min(names.len, 3)], 1..) |arg, reg, k| {
+ const ry = y + @as(f32, @floatFromInt(k)) * m.row;
+ u.text(.mono, size, x, rows.baseline(ry), arg, t.dim);
+ _ = rows.chain(u, x + @as(f32, @floatFromInt(arg.len + 1)) * adv, ry, rec.moment(moment), rec.register(moment, reg), room, .{});
+ };
+ return;
+ }
+ // Memory: a chain from the address it computes. Before the step,
+ // where it will look; in the step its first hop is read (with the
+ // dump's run: an echo), or the value it leaves is struck.
+ if (touches[0]) |touch| {
+ // In the step that runs it: the read is this step's (an echo of
+ // the dump's or the stack's), and a write's value after it, struck.
+ const in_step = state == .current and base == 1;
+ const reads = touch.how & 1 != 0;
+ const writes = touch.how & 2 != 0;
+ var marks: rows.Marks = .{};
+ var shown = rec.moment(moment);
+ if (in_step and reads and !writes) {
+ marks.read = 0;
+ marks.read_shows = now.reading(.memory, 0);
+ }
+ if (writes) if (after) |a| {
+ if (state == .ran or now.landed(.memory, 0)) shown = rec.moment(a);
+ if (in_step) {
+ marks.changed = 1;
+ marks.changed_heat = now.written(touch.addr, touch.len, .memory, 0);
+ }
+ };
+ _ = rows.chain(u, x, y, shown, touch.addr, room, marks);
+ return;
+ }
+ // Only a register: a small `reg` of what it left there.
+ const reg = written(row) orelse return;
+ const value_at = switch (state) {
+ .ran => after orelse return,
+ .current => if (after != null and now.landed(.cpu, 0)) after.? else return,
+ .ahead => return,
+ };
+ const value = rec.register(value_at, reg);
+ u.text(.mono, size, x, base_y, reg, t.dim);
+ _ = rows.chain(u, x + @as(f32, @floatFromInt(reg.len + 1)) * adv, y, rec.moment(value_at), value, room, .{});
+ }
+};
+
+/// Whether the step from moment `i` to `after` ran the instruction `row`
+/// alone: the moment after it is at the next instruction, or where it jumped.
+fn alone(rec: *const Recording, i: u64, after: u64, row: Insn) bool {
+ if (after != i + 1) return false;
+ const next = rec.register(after, "rip");
+ if (next == row.addr + row.len) return true;
+ if (rec.insn_branches[i]) |b| return b.to == next;
+ return false;
+}
+
+/// `text` in `chars` characters: cut at its far end, and saying so.
+fn clipText(u: ui.Ui, text: []const u8, chars: usize) []const u8 {
+ if (text.len <= chars) return text;
+ return u.print("{s}\u{2026}", .{text[0 .. chars - 1]});
+}
+
+/// The operands, as the disassembler writes them, 24 characters; a jump's
+/// or a call's target is an `address` in code's ink.
+fn operands(u: ui.Ui, row: Insn, base_y: f32) void {
+ const ops = row.operands();
+ const mn = row.mnemonic();
+ const branches = mn[0] == 'j' or std.mem.eql(u8, mn, "call");
+ if (branches and std.mem.startsWith(u8, ops, "0x")) {
+ if (std.fmt.parseInt(u64, ops[2..], 16)) |target| {
+ _ = u.address(c.operands, base_y, target, .{ .ink = ui.rgb(theme.color.region.code_) });
+ return;
+ } else |_| {}
+ }
+ u.text(.mono, size, c.operands, base_y, clipText(u, ops, c.operand_chars), theme.color.code.plain);
+}
+
+/// The register an instruction leaves a value in, if that is all it does
+/// (Intel syntax: the first operand is where it goes).
+fn written(row: Insn) ?[]const u8 {
+ const mn = row.mnemonic();
+ for ([_][]const u8{ "cmp", "test", "push", "nop", "endbr64", "call", "ret", "leave", "hlt", "syscall", "ud2", "int3" }) |none| if (std.mem.eql(u8, mn, none)) return null;
+ if (mn[0] == 'j' or std.mem.startsWith(u8, mn, "cmov") and false) return null;
+ const ops = row.operands();
+ const dest = ops[0 .. std.mem.indexOfScalar(u8, ops, ',') orelse ops.len];
+ return full(std.mem.trim(u8, dest, " "));
+}
+
+/// A register's 64-bit name, from any of its widths.
+fn full(name: []const u8) ?[]const u8 {
+ const table = [_][2][]const u8{
+ .{ "rax", "eax" }, .{ "rbx", "ebx" }, .{ "rcx", "ecx" }, .{ "rdx", "edx" },
+ .{ "rsi", "esi" }, .{ "rdi", "edi" }, .{ "rbp", "ebp" }, .{ "rsp", "esp" },
+ };
+ for (table) |pair| {
+ if (std.mem.eql(u8, name, pair[0]) or std.mem.eql(u8, name, pair[1])) return pair[0];
+ if (name.len == 2 and pair[0][1] == name[0] and (name[1] == 'x' or name[1] == 'l' or name[1] == 'h' or name[1] == 'i' or name[1] == 'p')) return pair[0];
+ }
+ if (name.len >= 2 and name[0] == 'r' and std.ascii.isDigit(name[1])) {
+ const digits = if (name.len >= 3 and std.ascii.isDigit(name[2])) name[0..3] else name[0..2];
+ for ([_][]const u8{ "r8", "r9", "r10", "r11", "r12", "r13", "r14", "r15" }) |r| if (std.mem.eql(u8, r, digits)) return r;
+ }
+ return null;
+}
+
+/// The window at moment `i`: up to `above` of the function's own
+/// instructions over the pc (fewer near its start), the pc's, and as many
+/// after it as fill `room`; past the function's end, `outside`.
+fn listing(u: ui.Ui, rec: *const Recording, i: u64, room: usize, above: usize) Listing {
+ const out = u.f.scratch.alloc(Insn, room) catch return .{ .rows = &.{}, .pc = 0 };
+ const pc = rec.register(i, "rip");
+ var buf: [256]u8 = undefined;
+ var up: [16]Insn = undefined;
+ var n_up: usize = 0;
+ var addr = pc;
+ while (n_up < @min(above, up.len)) {
+ const here = rec.instruction(i, addr, &buf) orelse break;
+ if (here.back == 0) break;
+ addr -= here.back;
+ const one = rec.instruction(i, addr, &buf) orelse break;
+ up[n_up] = .{ .addr = addr, .len = one.len, .text = u.print("{s}", .{one.text}), .line = one.line, .params = one.params };
+ n_up += 1;
+ }
+ var n: usize = 0;
+ while (n < n_up) : (n += 1) out[n] = up[n_up - 1 - n];
+ const pc_row = n;
+ addr = pc;
+ var outside = false;
+ while (n < room) : (n += 1) {
+ const one = rec.instruction(i, addr, &buf) orelse break;
+ if (n > pc_row and one.back == 0) outside = true;
+ out[n] = .{ .addr = addr, .len = one.len, .text = u.print("{s}", .{one.text}), .outside = outside, .line = one.line, .params = one.params };
+ addr += one.len;
+ }
+ return .{ .rows = out[0..n], .pc = pc_row };
+}
+
+/// Two windows of one function as one list in address order, and where each begins in it.
+fn merge(u: ui.Ui, a: []const Insn, b: []const Insn) ?struct { rows: []const Insn, from: usize, to: usize } {
+ if (a.len == 0 or b.len == 0) return null;
+ const lo = if (a[0].addr <= b[0].addr) a else b;
+ const hi = if (lo.ptr == a.ptr) b else a;
+ // Where `hi` begins in `lo`: they must overlap.
+ const at = for (lo, 0..) |row, k| {
+ if (row.addr == hi[0].addr) break k;
+ } else return null;
+ const total = @max(lo.len, at + hi.len);
+ const out = u.f.scratch.alloc(Insn, total) catch return null;
+ @memcpy(out[0..lo.len], lo);
+ if (at + hi.len > lo.len) @memcpy(out[lo.len..], hi[lo.len - at ..]);
+ return .{ .rows = out, .from = if (lo.ptr == a.ptr) 0 else at, .to = if (lo.ptr == b.ptr) 0 else at };
+}
+
+test "a register is known by any of its widths" {
+ try std.testing.expectEqualStrings("rax", full("eax").?);
+ try std.testing.expectEqualStrings("rdi", full("rdi").?);
+ try std.testing.expectEqualStrings("r10", full("r10d").?);
+ try std.testing.expectEqualStrings("rax", full("al").?);
+ try std.testing.expect(full("qword ptr [rbp - 8]") == null);
+}