diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-10 16:05:20 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-10 16:43:58 -0300 |
| commit | 165bb6c1344b98de7bef1d3c2b72147b4a40797a (patch) | |
| tree | 0e70e6222700063f604f78673f6ab3a5bfb9242d /anim/src/disasm.zig | |
| parent | 66a2a7cf733f6abc1f79561c52d901ce67019fb1 (diff) | |
| download | computeranim-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.zig | 419 |
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); +} |
