//! Ties (design/README.md, "4. Ties"): the panes are one machine at //! different levels, and a tie says which thing in one pane a thing in //! another is. Every tie is a relation, and the relations are one data //! problem (`relations.zig`): per frame, a table of the places the panels //! drew their things at (`anchor`) and of the values they show that could //! be addresses (`show`), both in the frame's own scratch (`sk.Frame.user`, //! `of`); `Ties`, added after them, is the resolver: six passes over those //! tables, each a loop over one (`Ties.draw`): candidates (a join of values //! with places by address, or the step's own events against places), the //! knobs (off unless the scene turned the kind on, where its default is //! off), priority, the budget (the thread always; two active lines across //! panes, the touch giving way first; one standing), route, draw. The kinds: //! //! - `thread` (standing): the source's current line is these //! instructions. Gold, 3: a bracket on the line, one on each run of its //! instructions in the disassembly, a line down the left margin. //! - `link` (for the step that set it): this register now points at //! that. In the ink of the region pointed into, 3 wide, up the gutter's //! left lane, head on the target; it ends in the target's `pin` and //! leaves it behind (`pinShows` times the pin for its owner). //! - `projection` (for the step): these bytes are that part of the //! drawing. In the mark's colour, 2 wide: a bracket on the dump's row, //! a line down the gutter's right lane and along the lens's top lane, //! a bracket over the node's address. //! - `touch`, `carry` (under `tied`; the carry the scene's knob), and //! `aim` (the scene's knob, off by default): a word holding the address //! of an instruction whose row is on screen, tied to that row. //! - `echo`: the same mark at the same instant in two panels; no line. const std = @import("std"); const sk = @import("sketch"); const anim = @import("anim"); const zt = @import("ztrace"); const ui = @import("ui.zig"); const cursors = @import("cursor.zig"); const rows = @import("rows.zig"); const Recording = @import("Recording.zig"); const Stage = @import("stage.zig").Stage; const relations = @import("relations.zig"); const theme = ui.theme; const time = theme.time; const Rect = ui.Rect; pub const Pane = relations.Pane; /// A thing with a place on screen. pub const Place = union(enum) { /// A register's value (its first hop), by its place in `Regs.names`. register: usize, /// The registers panel: a link leaves from its edge. registers, /// A stack slot's row, by its address. word: u64, /// The pin lane of a stack slot, by its address. slot_pin: u64, /// A drawn node, by its address; its address over it; the pin under it. node: u64, node_address: u64, node_pin: u64, /// A part of a node (its value, its pointer half), by the address of the field it is drawn from. node_part: u64, /// A run of bytes in the lens's dump, by its address; a view's row, by /// its first byte's: where a link to what a register points at lands. dump_run: u64, dump_pin: u64, /// The source's current line; the disassembly's pc row; each run of /// the current line's instructions in the disassembly. source, pc, run: usize, /// A row of the disassembly by its key (an instruction's address, a /// descent's head's `descent.headKey`); the descent's floor, where the /// kernel's window opens; a graph's pill by its block's address: what a /// column's bubble is level with (`column.zig`). row: u64, floor, block: u64, /// Its kind in the key's top byte (`relations.keyOf`), its address or index below. pub fn key(p: Place) u64 { return switch (p) { .register => |i| relations.keyOf(1, i), .registers => relations.keyOf(2, 0), .word => |a| relations.keyOf(3, a), .slot_pin => |a| relations.keyOf(4, a), .node => |a| relations.keyOf(5, a), .node_address => |a| relations.keyOf(6, a), .node_pin => |a| relations.keyOf(7, a), .node_part => |a| relations.keyOf(8, a), .dump_run => |a| relations.keyOf(9, a), .source => relations.keyOf(10, 0), .pc => relations.keyOf(11, 0), .run => |k| relations.keyOf(12, k), .dump_pin => |a| relations.keyOf(13, a), .row => |a| relations.keyOf(14, a), .floor => relations.keyOf(15, 0), .block => |a| relations.keyOf(16, a), }; } /// The pane it is drawn in. pub fn pane(p: Place) Pane { return switch (p) { .register, .registers => .registers, .word, .slot_pin => .stack, .node, .node_address, .node_pin, .node_part, .block => .drawing, .dump_run, .dump_pin => .view, .source => .source, .pc, .run, .row, .floor => .disasm, }; } }; /// The kinds of place keys, by number (`Place.key`). const key_kind = struct { const node_address = 6; const node_pin = 7; const slot_pin = 4; const dump_pin = 13; const run = 12; const row = 14; }; /// A frame's relations: its tables (the working frame's, and the map's for /// what the map's panels say) and the facts the panels publish beside them. pub const State = struct { work: relations.Tables = .{}, map: relations.Tables = .{}, /// The stack's window this frame: its first word, how many it shows, and /// where its pin lane runs (canvas pixels: x, the first row's top, the /// row's height). A link to a word outside it ends at its edge. stack_window: ?struct { first: u64, slots: usize, x: f32, top: f32, row: f32 } = null, /// The disassembly's row the step's `touch` and `carry` leave from or reach, /// this frame (canvas pixels: its right rule's x, the row's top, that x, its /// bottom), where it is drawn (`Disasm.insn`). touch_row: ?[4]f32 = null, /// The source's line waits (a `descent`: the pc is in code without source): /// the thread waits with it, primary and 2 units. thread_waits: bool = false, stats: relations.Stats = .{}, }; /// The frame's relations, made in its scratch at the first place said. pub fn of(f: *sk.Frame) *State { if (f.user) |p| return @ptrCast(@alignCast(p)); const st = f.scratch.create(State) catch @panic("ties: out of scratch memory"); st.* = .{}; f.user = st; return st; } /// `r` (in `u`'s units) is where `place` is, this frame. On the map (not /// its strips) into the map's table. pub fn anchor(u: ui.Ui, place: Place, r: Rect) void { if (ui.mapping and ui.strokes) return; const a = u.at.xf.apply(.{ r.x, r.y }); const b = u.at.xf.apply(.{ r.x + r.w, r.y + r.h }); const st = of(u.f); (if (ui.mapping) &st.map else &st.work).add(u.f.scratch, .{ .key = place.key(), .box = .{ a[0], a[1], b[0], b[1] }, .pane = place.pane() }); } /// `value`, which may be an address, is shown at `r` (in `u`'s units) in /// `pane`, a panel `panel_w` wide from `u`'s origin: `at` the address of /// the word holding it (0: none), `ref` a register's index. pub fn show(u: ui.Ui, value: u64, r: Rect, pane: Pane, at: u64, ref: u32, panel_w: f32) void { if (ui.mapping and ui.strokes) return; const a = u.at.xf.apply(.{ r.x, r.y }); const b = u.at.xf.apply(.{ r.x + r.w, r.y + r.h }); // Its panel's rules: a tie leaves by the one nearer its lane. const rules = [2]f32{ u.at.xf.apply(.{ 0, 0 })[0], u.at.xf.apply(.{ panel_w, 0 })[0] }; const st = of(u.f); (if (ui.mapping) &st.map else &st.work).show(u.f.scratch, .{ .value = value, .box = .{ a[0], a[1], b[0], b[1] }, .pane = pane, .ref = ref, .at = at, .rules = rules }); } /// Where `place` is this frame, in canvas pixels (left, top, right, bottom), if a panel said. pub fn find(f: *sk.Frame, place: Place) ?[4]f32 { const st = of(f); return st.work.find(f.scratch, place.key()); } /// When register `i` strikes in this step: the registers one step wrote /// strike 6 f apart, in the registers' order; from the fourth on with the /// third, within the CPU's slot of the cascade; in a crossing, once the /// call is back; in a continue, a wave, 2 f after the one above it. Its /// pin and its link go with it. pub fn strikeDelay(now: cursors.Now, i: usize) f32 { // Under `tied` rsp and rbp strike as their pins land (`Now.pinLands`), not in the CPU's slot. const pin = [2]?f32{ now.pinLands(0), now.pinLands(1) }; if (i == cursors.sp_index) if (pin[0]) |land| return land - now.plan.at[0]; if (i == cursors.bp_index) if (pin[1]) |land| return land - now.plan.at[0]; var before: f32 = 0; for (theme.metric.all_registers[0..16]) |name| { const k = @import("context.zig").index(name).?; if (k == i) break; if ((k == cursors.sp_index and pin[0] != null) or (k == cursors.bp_index and pin[1] != null)) continue; if (now.registerAge(k) == 0) before += 1; } if (now.plan.wave) return before * time.continue_wave; return @min(before * cursors.write_apart, time.cascade) + @import("syscalls.zig").crossingDelay(now); } /// Seconds since register `i`'s link (and its pin) set off: its strike; /// in a continue, memory's, when the stack's window is at its new place /// (a tie arrives at what is on screen, not at a window about to go). fn linkSince(now: cursors.Now, i: usize) f32 { return if (now.plan.wave) now.since(.memory, 0) else now.since(.cpu, strikeDelay(now, i)); } /// How long a link draws: to a slot near by, or across to the lens. pub fn linkTime(target: enum { slot, node }) f32 { return if (target == .slot) time.link.in else time.link.in_far; } /// How much a pin of register `i` shows at the place it pointed at /// before this step (`old`) and at the one it points at now (`new`): /// 6 f after its strike the old pin fades (12 f); the new lands with /// its link's head and settles (12 f). At a run or a sprint it moves /// with its level; at rest it is where the register points, and only /// there; for a register the step did not write, the two are one place. pub fn pinShows(now: cursors.Now, i: usize, target: enum { slot, node }) struct { old: f32, new: f32 } { if (now.registerAge(i) != 0) return .{ .old = 1, .new = 1 }; if (now.resting()) return .{ .old = 0, .new = 1 }; const since = linkSince(now, i); // At a run the pin changes with the run's ease (8 f), never in a frame. if (!now.walking()) { const p = std.math.clamp(since / time.run_ease, 0, 1); return .{ .old = 1 - p, .new = p }; } const l = time.link; const arrives = l.after + linkTime(if (target == .slot) .slot else .node); return .{ .old = 1 - std.math.clamp((since - l.after) / l.pin_out, 0, 1), .new = std.math.clamp((since - arrives) / l.settle, 0, 1), }; } /// `establish` for a lens: its element `k` (in address order), `r` /// seconds into its elements' coming in: each fades in rising 8 units /// over 12 f, 2 f after the one before (all begun by 12 f after the /// first), with its row's quiet bracket beside it; no lines. How much of /// it shows, and how far below its place it is. pub fn rise(r: f32, k: usize, n: usize) struct { element: f32, below: f32 } { const apart = @min(time.stagger, time.quick / @as(f32, @floatFromInt(@max(n, 2) - 1))); const p = std.math.clamp((r - @as(f32, @floatFromInt(k)) * apart) / time.quick, 0, 1); const eased = theme.ease(.enter, p); return .{ .element = p, .below = (1 - eased) * time.caption_rise }; } /// How long `n` elements take to come in. pub fn riseTime(n: usize) f32 { const apart = @min(time.stagger, time.quick / @as(f32, @floatFromInt(@max(n, 2) - 1))); return @as(f32, @floatFromInt(n -| 1)) * apart + time.quick; } /// What a candidate ties, found in the tables: the boxes (canvas pixels) /// its kind's route and drawing read, and what it is of. const Line = struct { kind: relations.Kind, /// Its source and target, and a third place its route needs (the /// registers panel's edge, a slot's pin lane, a node's address). from: [4]f32 = @splat(0), to: [4]f32 = @splat(0), third: [4]f32 = @splat(0), value: u64 = 0, /// The register a link or a beat leaves from. name: []const u8 = "", /// A link's target: a node's pin, a view's row, a slot's pin, or past the stack's window `words` away. target: enum { node, row, slot, beyond } = .slot, words: i64 = 0, /// A projection: from the stack to a call's node (else from the view to a node's part); a write (else a read). stacked: bool = false, write: bool = false, /// The word a projection, a touch or an aim is of; an aim's value before the step. word: u64 = 0, was: u64 = 0, /// An aim's lanes into its word's panel: its panel's rules. rules: [2]f32 = .{ 0, 0 }, }; /// The most candidates a frame keeps: a few of each kind. const max_lines = 64; pub const Ties = struct { cursor: cursors.Cursor, stage: *const Stage, box: Rect = .{ .x = 0, .y = 0, .w = theme.canvas.width, .h = theme.canvas.height }, /// The thread: whether the scene draws it (a scene with no source has none). threaded: bool = true, /// No links: the registers are not marked (`Registers.quiet`). quiet: bool = false, /// A link the scene plays on a beat of its own (`Context.tiesWith`). beat: ?*const Beat = null, /// The resolver: six passes over the frame's tables, each a loop over one. pub fn draw(g: *const Ties, f: *sk.Frame, at: anim.Placed) void { const st = of(f); const began = relations.clock(); defer report(f, st, began); const now = g.cursor.now(at); // Diving or surfacing, the panels are on their way: no ties; nor while the map alone is looked at. for (@import("context.zig").zoomed) |z| if (z != null) return; if (@import("map.zig").looking(f)) return; // In canvas pixels, `k` of them a unit: places come from panels anywhere. var raw: ui.Ui = .{ .f = f, .at = at }; raw.at.xf = .identity; const cx: Cx = .{ .g = g, .f = f, .st = st, .raw = raw, .at = at, .now = now, .k = at.scale, .split = g.stage.now(at) }; // 1. Candidates: each kind's join, or the step's events against the places. var lines: [max_lines]Line = undefined; var cands: [max_lines]relations.Candidate = undefined; var n: usize = 0; cx.candidates(&lines, &cands, &n); const found = relations.clock(); // 2. Knobs: a kind whose default is off only where the scene turned it on. var knobs = relations.Knobs.initOne(.always); if (g.threaded) knobs.insert(.thread); if (!g.quiet) knobs.insert(.links); if (now.plan.carry >= 0) knobs.insert(.carry); if (now.aim > 0) knobs.insert(.code); var kept = relations.filter(cands[0..n], knobs); // 3. Priority, then 4. the budget: it only removes. relations.byPriority(kept); kept = relations.cut(kept); const passed = relations.clock(); // 5. Route and 6. draw, in priority order: each kind's verb at its frames. for (kept) |c| cx.drawLine(lines[c.from]); st.stats.candidates = n; st.stats.kept = kept.len; st.stats.ns.candidates = found - began; st.stats.ns.passes = passed - found; st.stats.ns.draw = relations.clock() - passed; } }; /// A frame's resolver at work: the frame, its tables, the step. const Cx = struct { g: *const Ties, f: *sk.Frame, st: *State, raw: ui.Ui, at: anim.Placed, now: cursors.Now, k: f32, split: theme.layout.Split, fn find(cx: Cx, place: Place) ?[4]f32 { return cx.st.work.find(cx.f.scratch, place.key()); } /// The node a field's address belongs to: the drawn node at or below it, within a record. fn nodeOf(cx: Cx, addr: u64) ?u64 { return cx.st.work.atOrBelow(cx.f.scratch, key_kind.node_address, addr, 64); } /// Pass 1: every kind's candidates, into `lines` and `cands` (`n` of them). fn candidates(cx: Cx, lines: *[max_lines]Line, cands: *[max_lines]relations.Candidate, n: *usize) void { const now = cx.now; const add = struct { fn one(ls: *[max_lines]Line, cs: *[max_lines]relations.Candidate, at: *usize, line: Line, rank: u32) void { if (at.* == max_lines) return; ls[at.*] = line; cs[at.*] = .{ .kind = line.kind, .rank = rank, .from = @intCast(at.*) }; at.* += 1; } }.one; if (cx.find(.source)) |line| add(lines, cands, n, .{ .kind = .thread, .from = line }, 0); if (cx.g.beat) |b| { const t = cx.at.value(b.t); if (t >= 0 and t < b.total()) add(lines, cands, n, .{ .kind = .beat }, 0); } // Standing aims, at rest as in a step. if (now.aim > 0) cx.aims(lines, cands, n, add); if (!now.walking()) return; cx.links(lines, cands, n, add); cx.projections(lines, cands, n, add); if (cx.touchLine()) |line| add(lines, cands, n, line, 0); if (now.plan.carry >= 0) add(lines, cands, n, .{ .kind = .carry }, 0); } /// `link`'s join: the registers' values the step struck ⋈ the places /// with a pin lane at their address (a node's pin, a slot's, a view's /// row), or past the stack's window; ranked in pwndbg's order. fn links(cx: Cx, lines: *[max_lines]Line, cands: *[max_lines]relations.Candidate, n: *usize, add: anytype) void { const t = &cx.st.work; const gpa = cx.f.scratch; const values = t.values.items(.value); const by_value = t.byValue(gpa); const keys = t.places.items(.key); const by_key = t.byKey(gpa); // One merge per kind of target, the nearer first: a node's pin, a slot's, a view's row. var pairs: std.ArrayList(relations.Pair) = .empty; const kinds = [3]struct { u8, u64 }{ .{ key_kind.node_pin, ~@as(u64, 0) }, .{ key_kind.slot_pin, ~@as(u64, 0) }, .{ key_kind.dump_pin, ~@as(u64, 15) } }; var starts: [4]usize = undefined; for (kinds, 0..) |kind, j| { starts[j] = pairs.items.len; relations.join(values, by_value, keys, by_key, kind[0], kind[1], &pairs, gpa); } starts[3] = pairs.items.len; const panes = t.values.items(.pane); const refs = t.values.items(.ref); for (theme.metric.all_registers[0..16], 0..) |name, rank| { const i = @import("context.zig").index(name).?; if (cx.now.registerAge(i) != 0 or std.mem.eql(u8, name, "rsp")) continue; // `tied`: rbp's move is its pin's flight in the stack's lane, not a link. if (i == cursors.bp_index and cx.now.pinGone(1) != null) continue; const regs = (cx.now.moment().regs(cx.now.rec.tid) catch null) orelse return; const value = regs.named(name) orelse continue; var line: Line = .{ .kind = .link, .name = name, .value = value }; line.from = cx.find(.{ .register = i }) orelse continue; line.third = cx.find(.registers) orelse continue; // The value's targets, as the join found them. const hit: ?struct { usize, u32 } = for (0..3) |j| { const found = for (pairs.items[starts[j]..starts[j + 1]]) |pr| { if (panes[pr.value] == .registers and refs[pr.value] == i) break pr.place; } else null; if (found) |p| break .{ j, p }; } else null; if (hit) |h| { line.to = t.places.items(.box)[h[1]]; line.target = switch (h[0]) { 0 => .node, 1 => .slot, else => .row, }; } else if (cx.beyond(value)) |b| { line.to = b.box; line.target = .beyond; line.words = b.words; } else continue; add(lines, cands, n, line, @intCast(rank)); } } /// A word of the stack outside its window: the link ends at the /// window's edge, with a stub and how many words on it is. fn beyond(cx: Cx, value: u64) ?struct { box: [4]f32, words: i64 } { const w = cx.st.stack_window orelse return null; if (value % 8 != 0 or rows.regionOf(cx.now.moment(), value) != .stack) return null; const words = @as(i64, @bitCast(value -% w.first)) >> 3; if (words >= 0 and words < w.slots) return null; if (@abs(words) > 64) return null; // Its nearest row's pin lane. const y = if (words < 0) w.top else w.top + @as(f32, @floatFromInt(w.slots - 1)) * w.row; return .{ .box = .{ w.x, y, w.x + 10 * cx.k, y + w.row }, .words = if (words < 0) words else words - @as(i64, @intCast(w.slots)) + 1 }; } /// `projection`'s join: the step's events (its writes, then its reads) /// ⋈ the runs of the lens's dump and the parts of the drawing made of /// them; or a word of the stack ⋈ the call it is the way back of. fn projections(cx: Cx, lines: *[max_lines]Line, cands: *[max_lines]relations.Candidate, n: *usize, add: anytype) void { const rec = cx.now.rec; const events = [2]struct { spans: []const Recording.Span, write: bool }{ .{ .spans = rec.written(cx.now.stops[1], cx.now.stops[0]), .write = true }, .{ .spans = rec.read(cx.now.stops[1], cx.now.stops[0]), .write = false }, }; var rank: u32 = 0; for (events) |kind| for (kind.spans) |span| { defer rank += 1; // The run that begins where the bytes do (an element of an // array), else the word they are in (a field of a node). const word = if (cx.find(.{ .dump_run = span.addr }) != null) span.addr else span.addr & ~@as(u64, 7); const slot = cx.find(.{ .word = span.addr }); // (A return draws no line: its node's badge is struck with rax's digits.) const stacked = kind.write and slot != null and cx.find(.{ .node_address = span.addr }) != null and cx.find(.{ .dump_run = word }) == null; const run = if (stacked) slot.? else cx.find(.{ .dump_run = word }) orelse continue; if (!stacked) _ = cx.find(.{ .node_part = word }) orelse continue; const node_addr = if (stacked) span.addr else cx.nodeOf(word) orelse continue; const over = cx.find(.{ .node_address = node_addr }) orelse continue; add(lines, cands, n, .{ .kind = .projection, .from = run, .to = over, .stacked = stacked, .write = kind.write, .word = word }, rank); }; } /// `touch`: the step's touch event ⋈ the word's slot, from the row it leaves. fn touchLine(cx: Cx) ?Line { const now = cx.now; if (now.plan.touch < 0 or now.time < now.plan.touch) return null; const row = cx.st.touch_row orelse return null; const tt = cursors.stackTouch(now.rec, now.stops[1], now.stops[0]) orelse return null; const word = cx.find(.{ .word = tt.addr & ~@as(u64, 7) }) orelse return null; const lane_pin = cx.find(.{ .slot_pin = tt.addr & ~@as(u64, 7) }) orelse return null; return .{ .kind = .touch, .from = row, .to = word, .third = lane_pin, .write = tt.write }; } /// `aim`'s join: the values on screen in memory that are code ⋈ the /// disassembly's rows by address; standing, every one; for the step, /// those of the words it writes or reads. Ranked by where they are, top first. fn aims(cx: Cx, lines: *[max_lines]Line, cands: *[max_lines]relations.Candidate, n: *usize, add: anytype) void { const t = &cx.st.work; const gpa = cx.f.scratch; const values = t.values.items(.value); var pairs: std.ArrayList(relations.Pair) = .empty; relations.join(values, t.byValue(gpa), t.places.items(.key), t.byKey(gpa), key_kind.row, ~@as(u64, 0), &pairs, gpa); const panes = t.values.items(.pane); const ats = t.values.items(.at); const boxes = t.values.items(.box); const step = cx.now.aim > 1.5; const moment = cx.now.moment(); // The words whose value was code before the step and is not now: the aim frays from its old row. for (t.values.items(.value), 0..) |v, j| { if (ats[j] == 0 or panes[j] == .registers) continue; const was = (Recording.word(cx.now.before(), ats[j], 8) catch null) orelse continue; if (was == v) continue; // (Still code with a row: the join below has it, gliding from its old row.) if (cx.find(.{ .row = v }) != null) continue; const row = cx.find(.{ .row = was }) orelse continue; if (step and !cx.touched(ats[j])) continue; add(lines, cands, n, .{ .kind = .code, .from = boxes[j], .to = row, .value = v, .was = was, .word = ats[j], .rules = t.values.items(.rules)[j] }, @intFromFloat(@max(boxes[j][1], 0))); } for (pairs.items) |pr| { const j = pr.value; if (ats[j] == 0 or panes[j] == .registers) continue; if (rows.regionOf(moment, values[j]) != .code) continue; if (step and !cx.touched(ats[j])) continue; const was = (Recording.word(cx.now.before(), ats[j], 8) catch null) orelse values[j]; add(lines, cands, n, .{ .kind = .code, .from = boxes[j], .to = t.places.items(.box)[pr.place], .value = values[j], .was = was, .word = ats[j], .rules = t.values.items(.rules)[j] }, @intFromFloat(@max(boxes[j][1], 0))); } } /// Whether the step wrote or read the word at `addr`. fn touched(cx: Cx, addr: u64) bool { return cx.now.writeAge(addr, 8) == 0 or cx.now.wasRead(addr, 8); } /// Pass 6 for one relation: its kind's verb at its frames. fn drawLine(cx: Cx, line: Line) void { switch (line.kind) { .thread => cx.thread(line), .beat => cx.named(), .link => cx.link(line), .projection => cx.projection(line), .touch => cx.touch(line), .carry => cx.carry(), .code => cx.aim(line), } cx.st.stats.drawn += 1; } /// The gold thread: the current line and its instructions, one mark. fn thread(cx: Cx, line_box: Line) void { const raw = cx.raw.faded(@import("context.zig").thread_shows); const k = cx.k; const line = line_box.from; const x = cx.at.xf.apply(.{ theme.metric.tie.thread_x, 0 })[0]; const gold = if (cx.st.thread_waits) ui.rgb(theme.color.text.primary) else ui.rgb(theme.mark(.current).solid); const kind = if (cx.st.thread_waits) [2]f32{ theme.metric.bracket.quiet[0] * k, theme.metric.bracket.quiet[1] * k } else [2]f32{ theme.metric.bracket.thread[0] * k, theme.metric.bracket.thread[1] * k }; raw.bracket(x, line[1] + 2 * k, line[3] - 2 * k, gold, kind, 1, false); var bottom = line[3] - 2 * k; var top = line[1] + 2 * k; var n: usize = 0; while (cx.find(.{ .run = n })) |run| : (n += 1) { raw.bracket(x, run[1] + 2 * k, run[3] - 2 * k, gold, kind, 1, false); bottom = @max(bottom, run[3] - 2 * k); top = @min(top, run[1] + 2 * k); } if (n > 0) raw.fill(.{ .x = x - kind[0] / 2, .y = top, .w = kind[0], .h = bottom - top }, gold); } /// `touch` (design/README.md, "4. Ties"), `tied`, in a walked step: this /// instruction reads or writes that word. From the disassembly's right /// rule level with the row, into the gutter's middle lane (x 956), up or /// down it to the word's height, onto the stack's rule, a head 7 by 8 on /// it: 2 units in read's colour or write's vermilion, 12 f (18 f past six /// rows), `standard`, from `Plan.touch`; held to the advance and drawn /// back into the row with it (12 f), or, a load carried, as the carry /// leaves the word. Only to a word on show: the window is there first. fn touch(cx: Cx, line: Line) void { const now = cx.now; const k = cx.k; const row = line.from; const word = line.to; const lane_pin = line.third; const lane = cx.at.xf.apply(.{ theme.metric.tie.touch_lane, 0 })[0]; // Onto the stack's rule nearer the lane: its left in the state column, its right // where it stands under the disassembly (a column's beat), the head pointing back. const left = lane_pin[0] - theme.metric.slot.lane * k; const rule = if (left > lane) left else cx.at.xf.apply(.{ cx.split.stack.x + cx.split.stack.w, 0 })[0]; const ya = (row[1] + row[3]) / 2; const yb = (word[1] + word[3]) / 2; const long = @abs(yb - ya) > 6 * theme.metric.context.row * k; const drawn = cursors.standard(std.math.clamp((now.time - now.plan.touch) / @as(f32, if (long) time.tied.touch_long else time.tied.touch), 0, 1)); const back_at = if (now.plan.carry >= 0 and !line.write) now.plan.carry else now.plan.advance; const back = cursors.standard(std.math.clamp((now.time - back_at) / time.quick, 0, 1)); if (back >= 1) return; const color = theme.mark(if (line.write) .write else .read).solid; cx.raw.route(&.{ .{ row[0], ya }, .{ lane, ya }, .{ lane, yb }, .{ rule, yb } }, color, .{ .width = theme.stroke.tie.projection * k, .head = .{ 7 * k, 8 * k }, .progress = @min(drawn, 1 - back), .radius = theme.metric.tie.radius * k }); } /// `carry` (design/README.md, "4. Ties"; `Levels.carry`), in a walked /// step: this value went from that word into this register, or from this /// register into that word (a load, a store, a push's register, a pop's). /// 2 units in primary, an open chevron 7 by 8 drawn in two strokes: from /// the source's rule level with its row, along the gutter's right lane /// (x 962) between the stack and the registers, onto the destination's /// rule; 18 f (24 f past eight rows), `standard`, from `Plan.carry`, a /// store's register framed as read the 6 f before; drawn back as the /// destination strikes (18 f). With `carry_value` the value's digits ride /// its head on a `raised` chip, landing as the strike. fn carry(cx: Cx) void { const now = cx.now; const k = cx.k; const raw = cx.raw; const at = cx.at; const rec = now.rec; const tt = cursors.stackTouch(rec, now.stops[1], now.stops[0]) orelse return; const how = cursors.carried(rec, tt) orelse return; const i = @import("context.zig").index(how.reg) orelse return; const reg = cx.find(.{ .register = i }) orelse return; const panel = cx.find(.registers) orelse return; const word = cx.find(.{ .word = tt.addr & ~@as(u64, 7) }) orelse return; const lane_pin = cx.find(.{ .slot_pin = tt.addr & ~@as(u64, 7) }) orelse return; const stack_rule = lane_pin[0] - theme.metric.slot.lane * k; const lane = at.xf.apply(.{ theme.metric.tie.projection_lane, 0 })[0]; const y_reg = (reg[1] + reg[3]) / 2; const y_word = (word[1] + word[3]) / 2; const strike = if (how.load) now.plan.at[0] else now.plan.at[1]; // A store's register framed as read first (6 f), held while its value goes. if (!how.load) { const inv = at.xf.invert(); const a = inv.apply(.{ reg[0], reg[1] }); const c = inv.apply(.{ reg[2], reg[3] }); const shows = std.math.clamp((now.time - now.plan.carry + time.read.in) / time.read.in, 0, 1) * (1 - std.math.clamp((now.time - now.plan.advance) / time.read.out, 0, 1)); (ui.Ui{ .f = raw.f, .at = at }).read(.{ .x = a[0], .y = a[1], .w = c[0] - a[0], .h = c[1] - a[1] }, shows); } if (now.time < now.plan.carry) return; const far = @abs(y_reg - y_word) > 8 * theme.metric.context.row * k; const drawn = cursors.standard(std.math.clamp((now.time - now.plan.carry) / @as(f32, if (far) time.tied.carry_long else time.tied.carry), 0, 1)); const back = cursors.standard(std.math.clamp((now.time - strike) / (18.0 / 60.0), 0, 1)); if (back >= 1) return; const points: [4]ui.Vec = if (how.load) .{ .{ stack_rule, y_word }, .{ lane, y_word }, .{ lane, y_reg }, .{ panel[0], y_reg } } else .{ .{ panel[0], y_reg }, .{ lane, y_reg }, .{ lane, y_word }, .{ stack_rule, y_word } }; const color = theme.color.text.primary; raw.route(&points, color, .{ .width = theme.stroke.tie.projection * k, .head = null, .progress = drawn, .from = back, .radius = theme.metric.tie.radius * k }); // The open chevron at its head, two strokes. const tip = along(&points, drawn); const behind = along(&points, @max(drawn - 0.02, 0)); const dir = sk.math.normalize(if (sk.math.distance(tip, behind) > 0.01) tip - behind else points[3] - points[2]); const side = sk.math.scale(sk.math.perp(dir), 4 * k); const tail = tip - sk.math.scale(dir, 7 * k); raw.line(tail + side, tip, color, theme.stroke.tie.projection * k); raw.line(tail - side, tip, color, theme.stroke.tie.projection * k); // `value`: the digits on a raised chip at the head, gone as the strike lands. if (now.plan.carry_value) { const shows = 1 - std.math.clamp((now.time - strike) / time.strike.in, 0, 1); if (shows <= 0) return; const value = if (how.load) (Recording.word(rec.moment(now.stops[0]), tt.addr, @intCast(@min(tt.len, 8))) catch null) orelse return else rec.register(tt.at, how.reg); const v = raw.faded(shows); const text = v.print("{x}", .{value}); const size = theme.size.mono.context * k; const w = v.width(.mono, size, text) + 12 * k; const h = theme.metric.context.row * k; // Beside the head, on the lane's outer side: never over the rules. const box: ui.Rect = .{ .x = lane - w - 6 * k, .y = tip[1] - h / 2, .w = w, .h = h }; v.fill(box, theme.color.raised); v.text(.mono_bold, size, box.x + 6 * k, theme.baseline(box.y, h, size), text, theme.color.text.bright); } } /// The step's link: the first register it struck that now holds the /// address of a pinned thing (a stack slot, a node, a view's row). rip /// and rsp are where execution and the stack are, and have none. fn link(cx: Cx, line: Line) void { const now = cx.now; const i = @import("context.zig").index(line.name).?; const since = linkSince(now, i); const l = time.link; const drawn = cursors.standard(std.math.clamp((since - l.after) / linkTime(if (line.target == .node) .node else .slot), 0, 1)); const back = std.math.clamp((now.time - now.plan.advance) / l.out, 0, 1); cx.linkTo(line, drawn, back); } /// A link from register `line.name` to what it points at: a node's /// pin, a slot's, a view's row, or a slot past the stack's window (a /// stub and a row count), `drawn` of the way and drawing back `back` of it. fn linkTo(cx: Cx, line: Line, drawn: f32, back: f32) void { const now = cx.now; const k = cx.k; const raw = cx.raw; const at = cx.at; const edge = line.third; const from = line.from; const target = line.to; if (drawn <= 0 or back >= 1) return; const color = rows.ink(rows.regionOf(now.moment(), line.value)); const y = (from[1] + from[3]) / 2; // What climbs into the band takes the gutter's left lane; what // goes down to a slot, the right. const lane = at.xf.apply(.{ if (line.target == .node or line.target == .row) theme.metric.tie.link_lane else theme.metric.tie.projection_lane, 0 })[0]; var points: [5]ui.Vec = undefined; var n: usize = 0; points[0] = .{ edge[0] + 2 * k, y }; points[1] = .{ lane, y }; switch (line.target) { .node => { // Up the gutter, along the lens's bottom lane, up into the pin under the node. const bottom = at.xf.apply(.{ 0, cx.split.band.y + cx.split.band.h - theme.metric.lens.bottom_lane })[1]; const cx_ = (target[0] + target[2]) / 2; points[2] = .{ lane, bottom }; points[3] = .{ cx_, bottom }; points[4] = .{ cx_, target[1] }; n = 5; }, .beyond => { // Off the window: to its nearest row, into the pin lane, out // to the panel's rule, where a head points on. const mid = (target[1] + target[3]) / 2; const rule = if (line.words < 0) target[1] - 6 * k else target[3] + 6 * k; points[2] = .{ lane, mid }; points[3] = .{ target[0] + 6 * k, mid }; points[4] = .{ target[0] + 6 * k, rule }; n = 5; }, .slot, .row => { // Along the gutter to the row, and into its pin lane (a view's row: to its edge). const mid = (target[1] + target[3]) / 2; points[2] = .{ lane, mid }; points[3] = .{ target[0] + (if (line.target == .row) @as(f32, 2) else -2) * k, mid }; n = 4; }, } const past = line.target == .beyond; raw.route(points[0..n], color, .{ .width = theme.stroke.tie.link * k, .head = if (!past) .{ 10 * k, 10 * k } else .{ 9 * k, 12 * k }, .progress = drawn, .from = cursors.standard(back), .radius = theme.metric.tie.radius * k }); if (past and drawn >= 1) { // How far the target is, faint, 6 past the head. const v = raw.faded(1 - back); const tip = points[4]; v.text(.mono, theme.size.mono.context, tip[0] + 12 * k, tip[1] + (if (line.words < 0) @as(f32, 6) else 14) * k, v.print("{d} rows", .{@abs(line.words)}), theme.color.text.faint); } // The pin rides the line's head: the register's name beside it. if (drawn > 0 and drawn < 1 and !past) { const tip = along(points[0..n], drawn); raw.text(.mono_bold, theme.size.mono.context, tip[0] + 8 * k, tip[1] - 6 * k, line.name, theme.color.text.primary); } } /// The scene's `Beat`: its register framed as read, then its link. fn named(cx: Cx) void { const b = cx.g.beat.?; const now = cx.now; const at = cx.at; const t = at.value(b.t); const i = @import("context.zig").index(b.name) orelse return; const px = cx.find(.{ .register = i }) orelse return; const l = time.link; const back = std.math.clamp((t - (b.total() - l.out)) / l.out, 0, 1); // Its value framed as read, in the panel's units. const u: ui.Ui = .{ .f = cx.raw.f, .at = at }; const inv = at.xf.invert(); const a = inv.apply(.{ px[0], px[1] }); const c = inv.apply(.{ px[2], px[3] }); u.read(.{ .x = a[0], .y = a[1], .w = c[0] - a[0], .h = c[1] - a[1] }, std.math.clamp(t / time.read.in, 0, 1) * (1 - back)); const rec = b.cursor.rec; const regs = (now.moment().regs(rec.tid) catch null) orelse return; const value = regs.named(b.name) orelse return; const drawn = cursors.standard(std.math.clamp((t - l.after) / l.in_far, 0, 1)); // Its target as a link's: a node's pin, a slot's, a view's row, or past the window. var line: Line = .{ .kind = .beat, .name = b.name, .value = value, .from = px }; line.third = cx.find(.registers) orelse return; if (cx.find(.{ .node_pin = value })) |p| { line.to = p; line.target = .node; } else if (cx.find(.{ .slot_pin = value })) |p| { line.to = p; line.target = .slot; } else if (cx.find(.{ .dump_pin = value & ~@as(u64, 15) })) |p| { line.to = p; line.target = .row; } else if (cx.beyond(value)) |bb| { line.to = bb.box; line.target = .beyond; line.words = bb.words; } else return; cx.linkTo(line, drawn, back); } /// The step's projection: the first run of bytes it read or wrote in /// the lens's dump that a part of the drawing is made of. fn projection(cx: Cx, line: Line) void { const now = cx.now; const k = cx.k; const at = cx.at; const run = line.from; const over = line.to; const stacked = line.stacked; const word = line.word; const p = time.project; // Under `tied`, once what made them has shown (a call's push, rsp's pin landed: `Plan.project`). const since = if (now.plan.project >= 0) now.time - now.plan.project else now.since(.memory, 0); const bracket = std.math.clamp(since / p.bracket, 0, 1); const drawn = cursors.standard(std.math.clamp((since - p.bracket) / @as(f32, if (stacked) p.far else p.draw), 0, 1)); const out = 1 - std.math.clamp((now.time - now.plan.advance) / p.out, 0, 1); if (bracket <= 0 or out <= 0) return; const color = theme.mark(if (line.write) .write else .read).solid; const v = cx.raw.faded(out); const tie = [2]f32{ theme.metric.bracket.tie[0] * k, theme.metric.bracket.tie[1] * k }; // The bracket takes the row: x 7 of the dump, the row's height; // on the stack, the panel's left padding. const bx = if (stacked) run[0] - (theme.metric.slot.address - 5) * k else run[0] - (rows.byteX(@intCast(word % 16)) - 4 - theme.metric.bytes.bracket) * k; v.faded(bracket).bracket(bx, run[1] + 2 * k, run[3] - 2 * k, color, tie, 1, false); const cx_ = (over[0] + over[2]) / 2; const y = (run[1] + run[3]) / 2; if (stacked) { // A frame's way back to its call's node: up the gutter's // left lane, along the drawing's bottom lane, up to a // bracket under the node, serifs up. const lane = at.xf.apply(.{ theme.metric.tie.link_lane, 0 })[0]; const bottom = at.xf.apply(.{ 0, cx.split.band.y + cx.split.band.h - theme.metric.lens.bottom_lane })[1]; v.route(&.{ .{ bx - 1 * k, y }, .{ lane, y }, .{ lane, bottom }, .{ cx_, bottom }, .{ cx_, over[3] + 5 * k } }, color, .{ .width = theme.stroke.tie.projection * k, .head = null, .progress = drawn, .radius = theme.metric.tie.projection_radius * k }); if (drawn >= 1) { v.fill(.{ .x = over[0], .y = over[3] + 2 * k, .w = over[2] - over[0], .h = 3 * k }, color); v.fill(.{ .x = over[0], .y = over[3] - 3 * k, .w = 3 * k, .h = 8 * k }, color); v.fill(.{ .x = over[2] - 3 * k, .y = over[3] - 3 * k, .w = 3 * k, .h = 8 * k }, color); } return; } const lane = at.xf.apply(.{ theme.metric.tie.projection_lane, 0 })[0]; const top = at.xf.apply(.{ 0, cx.split.band.y + theme.metric.context.tag + theme.metric.lens.top_lane })[1]; v.route(&.{ .{ bx - 1 * k, y }, .{ lane, y }, .{ lane, top }, .{ cx_, top }, .{ cx_, over[1] - 4 * k } }, color, .{ .width = theme.stroke.tie.projection * k, .head = null, .progress = drawn, .radius = theme.metric.tie.projection_radius * k }); // Over the node's address: a bracket, serifs down. if (drawn >= 1) { v.fill(.{ .x = over[0], .y = over[1] - 5 * k, .w = over[2] - over[0], .h = 3 * k }, color); v.fill(.{ .x = over[0], .y = over[1] - 5 * k, .w = 3 * k, .h = 8 * k }, color); v.fill(.{ .x = over[2] - 3 * k, .y = over[1] - 5 * k, .w = 3 * k, .h = 8 * k }, color); } } /// `aim` (design/README.md, "4. Ties"; the scene's knob, off by default): /// this word holds the address of that instruction. 2 units in code's /// ink, a filled head: out of the word's panel's rule nearer the gutter, /// along its left lane (x 950), onto the disassembly's right rule level /// with the row, whose address is framed in code's ink as the head lands. /// Standing, 60% toward the page, in and out with the knob (18 f); for /// the step, full, after the word's mark (18 f, 24 past ten rows), back /// with the advance. Written again: still code with its row shown, the /// head glides to it (24 f) after the strike; no longer code, it frays /// (dashed over 12 f, gone over 18 more). The disassembly never moves for it. fn aim(cx: Cx, line: Line) void { const now = cx.now; const k = cx.k; const at = cx.at; const step = now.aim > 1.5; const lane = at.xf.apply(.{ theme.metric.tie.link_lane, 0 })[0]; // Leaves by its panel's rule nearer the lane. const rule = if (@abs(line.rules[0] - lane) < @abs(line.rules[1] - lane)) line.rules[0] else line.rules[1]; const y_word = (line.from[1] + line.from[3]) / 2; // Where the word changed this step: its strike, and the row it held. const struck: ?f32 = if (line.was != line.value) now.struckAgo(line.word, 8) else null; const old_row = if (line.was != line.value) cx.find(.{ .row = line.was }) else null; const code_now = rows.regionOf(now.moment(), line.value) == .code; const new_row = if (code_now) cx.find(.{ .row = line.value }) else null; // The head: on the old row until the strike, then gliding to the new one (24 f); fraying where there is none. var y_row = (line.to[1] + line.to[3]) / 2; var fray: f32 = 0; var row_box = line.to; if (old_row) |o| { const after = if (struck) |sa| sa else if (now.resting()) std.math.inf(f32) else -1; if (new_row) |nr| { const p = cursors.glide(std.math.clamp(after / (24.0 / 60.0), 0, 1)); y_row = std.math.lerp((o[1] + o[3]) / 2, (nr[1] + nr[3]) / 2, p); row_box = if (p < 0.5) o else nr; } else { y_row = (o[1] + o[3]) / 2; row_box = o; fray = std.math.clamp(after / (30.0 / 60.0), 0, 1); if (fray >= 1) return; } } const right = row_box[2]; // How much it shows: standing with the knob (18 f in and out), for the step from the word's mark to the advance. var drawn: f32 = 1; var shows: f32 = if (step) 1 else @min(now.aim, 1); if (step) { if (now.resting()) return; const from = @max(now.plan.at[1], 0) + time.strike.in; const long = @abs(y_row - y_word) > 10 * theme.metric.context.row * k; drawn = cursors.standard(std.math.clamp((now.time - from) / @as(f32, if (long) 24.0 / 60.0 else 18.0 / 60.0), 0, 1)); shows = 1 - std.math.clamp((now.time - now.plan.advance) / time.quick, 0, 1); } if (drawn <= 0 or shows <= 0) return; // Standing, 60% toward the page; fraying, dashed over its first 12 f, then fading. const ink = if (step) ui.rgb(theme.color.region.code_) else ui.mix(theme.color.region.code_, theme.color.page, 0.6); const v = cx.raw.faded(shows * (1 - std.math.clamp((fray - 0.4) / 0.6, 0, 1))); const points = [4]ui.Vec{ .{ rule, y_word }, .{ lane, y_word }, .{ lane, y_row }, .{ right, y_row } }; if (fray > 0) { // Dashed, 12 on 8, the gaps opening over the fray's first 12 f. const open = std.math.clamp(fray / 0.4, 0, 1); dashed(v, &points, ink, theme.stroke.rule * k, 12 * k, 8 * k * open); } else v.route(&points, ink, .{ .width = theme.stroke.rule * k, .head = .{ 8 * k, 8 * k }, .progress = drawn, .radius = theme.metric.tie.radius * k }); // The row's address framed in code's ink as the head lands. if (drawn >= 1 and fray == 0) { const adv = ui.advance(theme.size.mono.context) * k; const digits: f32 = @floatFromInt(ui.digits(if (row_box[1] == line.to[1]) line.value else line.was)); const x0 = row_box[0] + (theme.metric.insn.address - 4) * k; v.frame(.{ .x = x0, .y = row_box[1], .w = digits * adv + 8 * k, .h = row_box[3] - row_box[1] }, ink, theme.stroke.rule * k); } } }; /// `points` as dashes `on` long with gaps `off` wide, `width` thick. fn dashed(u: ui.Ui, points: []const ui.Vec, ink: anytype, width: f32, on: f32, off: f32) void { for (points[0 .. points.len - 1], points[1..]) |a, b| { const d = sk.math.distance(a, b); if (d <= 0) continue; var s: f32 = 0; while (s < d) : (s += on + off) { const e = @min(s + on, d); u.line(sk.math.mix(a, b, s / d), sk.math.mix(a, b, e / d), ink, width); } } } /// The frame's counts and times, on stderr with `CANIM_RELATIONS=1`; and, /// for the measure, the map's join of its values with its rows. fn report(f: *sk.Frame, st: *State, began: u64) void { if (!relations.reporting()) return; st.stats.places = st.work.places.len; st.stats.values = st.work.values.len; st.stats.ns.sort = st.work.sort_ns; st.stats.map_places = st.map.places.len; st.stats.map_values = st.map.values.len; if (st.map.places.len > 0) { const start = relations.clock(); var pairs: std.ArrayList(relations.Pair) = .empty; relations.join(st.map.values.items(.value), st.map.byValue(f.scratch), st.map.places.items(.key), st.map.byKey(f.scratch), key_kind.row, ~@as(u64, 0), &pairs, f.scratch); st.stats.map_pairs = pairs.items.len; st.stats.ns.map = relations.clock() - start; } const x = st.stats; std.debug.print("relations frame {d} places {d} values {d} candidates {d} kept {d} drawn {d} ns sort {d} candidates {d} passes {d} draw {d} all {d} map places {d} values {d} pairs {d} ns {d}\n", .{ f.in.frame, x.places, x.values, x.candidates, x.kept, x.drawn, x.ns.sort, x.ns.candidates, x.ns.passes, x.ns.draw, relations.clock() - began, x.map_places, x.map_values, x.map_pairs, x.ns.map }); } /// A link the narration plays on a beat the caption names, not a step's: /// register `name` framed as read (6 f), then its link to what it points at /// (6 f after, 36 f, `standard`, the name riding its head), held `hold`, /// and drawn back with the frame (18 f). pub const Beat = struct { cursor: cursors.Cursor, name: []const u8, hold: f32, /// Seconds into it; negative: none. t: anim.Value, pub fn total(b: *const Beat) f32 { return time.link.after + time.link.in_far + b.hold + time.link.out; } /// Plays it from here; the scene's cursor stays where it was. pub fn play(b: *const Beat, s: *anim.Frame) void { const start = s.cursor; s.play(.{b.t.to(0)}, .{ .seconds = 0 }); s.play(.{b.t.to(b.total())}, .{ .seconds = b.total(), .ease = anim.ease.linear }); s.play(.{b.t.to(-1)}, .{ .seconds = 0 }); s.cursor = start; } }; /// The point `p` of the way along the straight path through `points`. fn along(points: []const ui.Vec, p: f32) ui.Vec { var total: f32 = 0; for (points[0 .. points.len - 1], points[1..]) |a, b| total += sk.math.distance(a, b); var left = total * p; for (points[0 .. points.len - 1], points[1..]) |a, b| { const d = sk.math.distance(a, b); if (left <= d and d > 0) return sk.math.mix(a, b, left / d); left -= d; } return points[points.len - 1]; } test "places have keys of their own" { try std.testing.expect((Place{ .word = 0x1000 }).key() != (Place{ .node = 0x1000 }).key()); try std.testing.expect((Place{ .source = {} }).key() != (Place{ .pc = {} }).key()); try std.testing.expect((Place{ .run = 0 }).key() != (Place{ .run = 1 }).key()); }