//! 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. Panels publish the `place`s of their things as they draw //! (`anchor`); `Ties`, added after them, draws between places, along the //! channels only, never across a letter or another tie: //! //! - `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. //! - `echo`: the same mark at the same instant in two panels; no line. //! //! Budget: one thread; for a step one link and one projection. 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 Stage = @import("stage.zig").Stage; const theme = ui.theme; const time = theme.time; const Rect = ui.Rect; /// 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. dump_run: 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, fn key(p: Place) u64 { const low = (1 << 56) - 1; return switch (p) { .register => |i| 1 << 56 | @as(u64, i), .registers => 2 << 56, .word => |a| 3 << 56 | (a & low), .slot_pin => |a| 4 << 56 | (a & low), .node => |a| 5 << 56 | (a & low), .node_address => |a| 6 << 56 | (a & low), .node_pin => |a| 7 << 56 | (a & low), .node_part => |a| 8 << 56 | (a & low), .dump_run => |a| 9 << 56 | (a & low), .source => 10 << 56, .pc => 11 << 56, .run => |k| 12 << 56 | @as(u64, k), }; } }; /// 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. pub var stack_window: ?struct { first: u64, slots: usize, x: f32, top: f32, row: 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. pub var thread_waits = false; /// What this frame's components have said so far, in canvas pixels: left, top, right, bottom. /// shortcut: one table for the process, emptied by `Ties.draw`; a scene with two players at once wants it on the frame. var table: [512]struct { key: u64, box: [4]f32 } = undefined; var said: usize = 0; /// `r` (in `u`'s units) is where `place` is, this frame. pub fn anchor(u: ui.Ui, place: Place, r: Rect) void { if (said == table.len or ui.mapping) 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 }); table[said] = .{ .key = place.key(), .box = .{ a[0], a[1], b[0], b[1] } }; said += 1; } /// Where `place` is this frame, in canvas pixels (left, top, right, bottom), if a panel said. pub fn find(place: Place) ?[4]f32 { for (table[0..said]) |entry| if (entry.key == place.key()) return entry.box; return null; } /// 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 { var before: f32 = 0; for (theme.metric.all_registers[0..16]) |name| { const k = @import("context.zig").index(name).?; if (k == i) break; 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; } 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, pub fn draw(g: *const Ties, f: *sk.Frame, at: anim.Placed) void { defer said = 0; defer stack_window = null; defer thread_waits = false; 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 k = at.scale; const split = g.stage.now(at); if (g.threaded) thread(raw, at, k); if (!now.walking()) return; if (!g.quiet) g.link(raw, at, now, k, split); g.projection(raw, at, now, k, split); } /// The gold thread: the current line and its instructions, one mark. fn thread(raw: ui.Ui, at: anim.Placed, k: f32) void { const line = find(.source) orelse return; const x = at.xf.apply(.{ theme.metric.tie.thread_x, 0 })[0]; const gold = if (thread_waits) ui.rgb(theme.color.text.primary) else ui.rgb(theme.mark(.current).solid); const kind = if (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 (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); } /// The step's link: the first register it struck that now holds the /// address of a pinned thing (a stack slot, a node). rip and rsp are /// where execution and the stack are, and have none. fn link(g: *const Ties, raw: ui.Ui, at: anim.Placed, now: cursors.Now, k: f32, split: theme.layout.Split) void { const rec = g.cursor.rec; const regs = (now.moment().regs(rec.tid) catch null) orelse return; const edge = find(.registers) orelse return; for (theme.metric.all_registers[0..16]) |name| { const i = @import("context.zig").index(name).?; if (now.registerAge(i) != 0 or std.mem.eql(u8, name, "rsp")) continue; const value = regs.named(name) orelse continue; const from = find(.{ .register = i }) orelse continue; const node = find(.{ .node_pin = value }); // 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. var beyond: ?i64 = null; const target = node orelse find(.{ .slot_pin = value }) orelse edge: { const w = stack_window orelse continue; if (value % 8 != 0 or rows.regionOf(now.moment(), value) != .stack) continue; const words = @as(i64, @bitCast(value -% w.first)) >> 3; if (words >= 0 and words < w.slots) continue; if (@abs(words) > 64) continue; beyond = if (words < 0) words else words - @as(i64, @intCast(w.slots)) + 1; // Its nearest row's pin lane. const y = if (words < 0) w.top else w.top + @as(f32, @floatFromInt(w.slots - 1)) * w.row; break :edge [4]f32{ w.x, y, w.x + 10 * k, y + w.row }; }; const since = linkSince(now, i); const l = time.link; const drawn = cursors.standard(std.math.clamp((since - l.after) / linkTime(if (node != null) .node else .slot), 0, 1)); const back = std.math.clamp((now.time - now.plan.advance) / l.out, 0, 1); if (drawn <= 0 or back >= 1) return; const color = rows.ink(rows.regionOf(now.moment(), 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 (node != null) 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 }; if (node) |pin| { // Up the gutter, along the lens's bottom lane, up into the pin under the node. const bottom = at.xf.apply(.{ 0, split.band.y + split.band.h - theme.metric.lens.bottom_lane })[1]; const cx = (pin[0] + pin[2]) / 2; points[2] = .{ lane, bottom }; points[3] = .{ cx, bottom }; points[4] = .{ cx, pin[1] }; n = 5; } else if (beyond) |words| { // 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 (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; } else { // Along the gutter to the slot's row, and into its pin lane. const mid = (target[1] + target[3]) / 2; points[2] = .{ lane, mid }; points[3] = .{ target[0] - 2 * k, mid }; n = 4; } raw.route(points[0..n], color, .{ .width = theme.stroke.tie.link * k, .head = if (beyond == null) .{ 10 * k, 10 * k } else .{ 9 * k, 12 * k }, .progress = drawn, .from = cursors.standard(back), .radius = theme.metric.tie.radius * k }); if (beyond) |words| if (drawn >= 1) { // How far the target is, faint, 6 past the head. const v = raw.faded(1 - std.math.clamp((now.time - now.plan.advance) / l.out, 0, 1)); const tip = points[4]; v.text(.mono, theme.size.mono.context, tip[0] + 12 * k, tip[1] + (if (words < 0) @as(f32, 6) else 14) * k, v.print("{d} rows", .{@abs(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 beyond == null) { const tip = along(points[0..n], drawn); raw.text(.mono_bold, theme.size.mono.context, tip[0] + 8 * k, tip[1] - 6 * k, name, theme.color.text.primary); } return; } } /// 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(g: *const Ties, raw: ui.Ui, at: anim.Placed, now: cursors.Now, k: f32, split: theme.layout.Split) void { const rec = g.cursor.rec; const kinds = [2]struct { spans: []const @import("Recording.zig").Span, role: theme.Role }{ .{ .spans = rec.written(now.stops[1], now.stops[0]), .role = .write }, .{ .spans = rec.read(now.stops[1], now.stops[0]), .role = .read }, }; for (kinds) |kind| for (kind.spans) |span| { // 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 (find(.{ .dump_run = span.addr }) != null) span.addr else span.addr & ~@as(u64, 7); // From the dump's run to the part of the drawing made of it; or // from a word of the stack to the call it is the way back of. const slot = find(.{ .word = span.addr }); // (A return draws no line: its node's badge is struck with rax's digits.) const stacked = kind.role == .write and slot != null and find(.{ .node_address = span.addr }) != null and find(.{ .dump_run = word }) == null; const run = if (stacked) slot.? else find(.{ .dump_run = word }) orelse continue; if (!stacked) _ = find(.{ .node_part = word }) orelse continue; const node_addr = if (stacked) span.addr else nodeOf(word) orelse continue; const over = find(.{ .node_address = node_addr }) orelse continue; const p = time.project; const since = 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(kind.role).solid; const v = 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, split.band.y + 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, 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); } return; }; } }; /// 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]; } /// The node a field's address belongs to: the drawn node at or below it, within a record. fn nodeOf(addr: u64) ?u64 { var best: ?u64 = null; for (table[0..said]) |entry| { if (entry.key >> 56 != 6) continue; const a = entry.key & ((1 << 56) - 1); if (a <= addr and addr - a < 64 and (best == null or a > best.?)) best = a; } return best; } 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()); }