summaryrefslogtreecommitdiff
path: root/anim/src
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-11 20:08:07 -0300
committerGabriel Schneider <[email protected]>2026-11-11 21:45:12 -0300
commit15de88cf82c187635c1989e91bfa639a10304066 (patch)
tree16fa83854258c0c6aec1dff7f70ebabf5fd64c09 /anim/src
parent0ec2376cae2fdfc50e90d930ebc86c7a5b7f5594 (diff)
downloadcomputeranim-15de88cf82c187635c1989e91bfa639a10304066.tar.gz
computeranim-15de88cf82c187635c1989e91bfa639a10304066.zip
canim: a column of text as an experiment; the disassembly tied to the stack
From the user. A scene may set its text in a column beside the panes a beat is about: col.beat names the panes and their rows, where the text is placed (beside, below, above, or on a drawing) and what it is level with; panes the beat leaves out fold to their title bars on a shelf, their changes struck there. Tried as two scenes beside the originals: the call followed down (column) and a bubble on sort's rings (column_sort). annotation = .tied names the word an instruction touched and draws a touch to its stack row; offsets count from the frame's base; rsp's pin travels with its amount before the stack follows; .whole keeps the full chain. carry = .arrow draws a value's way between memory and a register. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNCKgYCGiANnEwcEQxa
Diffstat (limited to 'anim/src')
-rw-r--r--anim/src/column.zig942
-rw-r--r--anim/src/context.zig239
-rw-r--r--anim/src/cursor.zig363
-rw-r--r--anim/src/descent.zig37
-rw-r--r--anim/src/disasm.zig210
-rw-r--r--anim/src/graph.zig12
-rw-r--r--anim/src/root.zig11
-rw-r--r--anim/src/rows.zig20
-rw-r--r--anim/src/stage.zig18
-rw-r--r--anim/src/theme.zig20
-rw-r--r--anim/src/ties.zig145
-rw-r--r--anim/src/words.zig21
12 files changed, 1949 insertions, 89 deletions
diff --git a/anim/src/column.zig b/anim/src/column.zig
new file mode 100644
index 0000000..32b3d4d
--- /dev/null
+++ b/anim/src/column.zig
@@ -0,0 +1,942 @@
+//! The column (design/README.md, "column (an experiment)"): a second way
+//! to compose a scene, beside the working frame. Two columns of 880: the
+//! panes a beat is about on the left (x 64, from y 84 to 1032, 12 apart, in
+//! the frame's order), the narration on the right (x 976), each `bubble`
+//! level with the row it speaks of; every pane the beat leaves out folded to
+//! its tag on the `shelf` (y 48), a register struck on its tag as on its row.
+//!
+//! It is an author's instrument: the scene says, beat by beat, which panes
+//! stand and with how many rows, where the text is placed (`beside`,
+//! `below` the working frame as a caption, `above` or `on` a wide drawing),
+//! what each bubble is level with and what its stem points at; what a beat
+//! leaves out is defaulted, never against what it wrote:
+//!
+//! const col = canim.column(s, ctx, .{ .lens = log, .titles = .{ .band = "system calls", .view = "its bytes" } });
+//! col.beat(s, .{
+//! .panes = &.{ .{ .source, 3 }, .{ .disasm, 11 }, .{ .stack, canim.column_rest } },
+//! .say = "The call pushes where to come back to, `main+45`, and goes down to open's stub.",
+//! .level = .{ .row = call }, // default: the pc's row at the beat
+//! });
+//!
+//! Between beats, in a rest (design/README.md, "Panes between beats"): the
+//! last bubble dims; the panes that leave fade (12 f) and fold to the shelf
+//! (24 f, `glide`); those that stay glide (24 f); those that come unfold
+//! (24 f) and fade in (12 f); an older bubble in the way glides out of it
+//! (24 f); the next arrives (18 f, rising 8), its stem drawing (12 f); the
+//! lead; the stem draws back as the step fires. A bubble never travels
+//! between placements: the last leaves (12 f), the frame changes (48 f), the
+//! next arrives.
+const std = @import("std");
+const sk = @import("sketch");
+const anim = @import("anim");
+const ui = @import("ui.zig");
+const ties = @import("ties.zig");
+const words = @import("words.zig");
+const cursors = @import("cursor.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 Split = theme.layout.Split;
+const t = theme.color.text;
+const m = theme.metric.context;
+
+/// The panes, in the frame's order: the drawing, its view, the source, the
+/// disassembly (or the descent), the registers, the stack, the backtrace.
+pub const Part = enum { band, view, source, disasm, registers, stack, backtrace };
+const parts = std.enums.values(Part);
+/// A pane's rows: what the column has left (to 1032, the floor's foot).
+pub const rest: u32 = std.math.maxInt(u32);
+/// A pane that stands in a beat, and its rows (or `rest`).
+pub const Pane = struct { Part, u32 };
+pub const Placement = enum { beside, below, above, on };
+/// What a bubble is level with: the pc's row as the beat begins (the
+/// default), a row of the disassembly by its instruction's address, the head
+/// row over a function's window in a descent, the descent's floor (where the
+/// kernel's window opens), a graph's block by its address, or a height.
+pub const Level = union(enum) { pc, row: u64, head: []const u8, floor, block: u64, y: f32 };
+/// A bubble's stem: to what it is level with (the default), none (its level
+/// is the tie), or to another place.
+pub const Stem = union(enum) { level, none, to: Level };
+/// A folded pane's tag note, as the scene says it (`code` in backticks).
+pub const Note = struct { Part, []const u8 };
+
+pub const Beat = struct {
+ /// The panes that stand (`beside`); null: the beat's cause and effect,
+ /// the source (3 lines) and the disassembly (11 rows, a descent the rest)
+ /// and the pane the next step's effect lands in.
+ panes: ?[]const Pane = null,
+ say: []const u8,
+ /// Null: the column's (`Options.at`).
+ at: ?Placement = null,
+ level: Level = .pc,
+ stem: Stem = .level,
+ /// Folded panes' tag notes from this beat on (unless one is given: the
+ /// registers' is those the step changed, the source's its line, the
+ /// disassembly's the instruction at the pc).
+ notes: []const Note = &.{},
+ /// `on`: the bubble's top left in the frame (design units), in the drawing's free space.
+ where: ?[2]f32 = null,
+};
+
+pub const Options = struct {
+ /// The lens (one object drawing the band and its view: `Crossing`, a
+ /// graph), with its panes' titles for the shelf.
+ lens: ?anim.Obj = null,
+ titles: struct { band: []const u8 = "", view: []const u8 = "" } = .{},
+ /// The scene's placement where a beat names none.
+ at: Placement = .beside,
+};
+
+/// Frames, at 60 a second (design/README.md, "Panes between beats").
+const f = struct {
+ const dim = 18.0 / 60.0;
+ const rows = 12.0 / 60.0;
+ const fold = 24.0 / 60.0;
+ const glide = 24.0 / 60.0;
+ const relayout = theme.time.relayout;
+ const push = 24.0 / 60.0;
+ const arrive = 18.0 / 60.0;
+ const stem_after = 6.0 / 60.0;
+ const stem = 12.0 / 60.0;
+ const leave = 12.0 / 60.0;
+ const note = 12.0 / 60.0;
+};
+/// The bubble: Go 40 on 54, code in mono 35, 16 of padding, 812 wide at
+/// most, 40 characters a line; its first line's middle 40 under its top.
+const bubble = struct {
+ const x = 984;
+ const pad = 16;
+ const max_w = 812;
+ const chars = 40;
+ const pitch = theme.size.sans.caption_leading;
+ const first = 40;
+ const gap = 12;
+ const top = theme.canvas.stage.y;
+ const bottom = theme.canvas.stage.y + theme.canvas.stage.h;
+};
+/// A drawing's own size (the `blocks` lens's room, less its tag): `on` and `above` draw it larger.
+const lens_w = 896;
+const lens_h = 344;
+/// The panes' column: from 84 to 1032 (the floor's foot), 12 apart; the shelf at 48.
+const column_top = 84;
+const column_foot = 1032;
+const shelf_y = theme.canvas.stage.y;
+
+const Text = struct {
+ text: []const u8,
+ placement: Placement,
+ level: Level,
+ stem: ?Level,
+ where: ?[2]f32,
+ notes: [parts.len]?[]const u8,
+ /// 0 to 1: arriving (18 f), dimmed (18 f), leaving (12 f), its stem drawn,
+ /// the bubbles before it gliding out of its way (24 f), its notes in (12 f).
+ in: anim.Value,
+ dim: anim.Value,
+ out: anim.Value,
+ stem_v: anim.Value,
+ push: anim.Value,
+ notes_in: anim.Value,
+};
+
+pub const Column = struct {
+ cursor: cursors.Cursor,
+ stage: *Stage,
+ obj: anim.Obj = undefined,
+ objs: [parts.len]?anim.Obj,
+ titles: [parts.len][]const u8,
+ /// Whether each pane stands, as the scene's code has it so far.
+ standing: [parts.len]bool,
+ /// 1 on the shelf, 0 standing (the fold's travel between); 1 while the
+ /// column draws a pane's frame in its stead (folding, unfolding).
+ shelf: [parts.len]anim.Value,
+ ghost: [parts.len]anim.Value,
+ texts: [48]Text = undefined,
+ n: usize = 0,
+ placement: Placement = .below,
+ default: Placement,
+ /// The working frame's split, and the one the stage is going to.
+ working: Split,
+ split: Split,
+ /// The drawing across both columns (`on`, `above`): how much larger, and where its box goes.
+ zoom: f32 = 1,
+ read_by: f32 = 0,
+ said: bool = false,
+
+ /// One beat: the panes change (in a rest, never under a step), the text
+ /// arrives where the beat places it, the lead, then the scene's step.
+ pub fn beat(col: *Column, s: *anim.Frame, b: Beat) void {
+ const at = b.at orelse col.default;
+ const here = col.cursor.moment(s);
+ const rec = col.cursor.rec;
+ const level: Level = if (b.level == .pc) .{ .row = rec.register(here, "rip") } else b.level;
+ var notes: [parts.len]?[]const u8 = @splat(null);
+ for (b.notes) |note| notes[@intFromEnum(note[0])] = note[1];
+ // Which panes stand, and where.
+ var to: [parts.len]bool = @splat(false);
+ var split = col.split;
+ var zoom: f32 = 1;
+ switch (at) {
+ .below => {
+ for (parts) |p| to[@intFromEnum(p)] = col.objs[@intFromEnum(p)] != null;
+ split = col.working;
+ },
+ .beside => {
+ const panes = b.panes orelse col.defaults(s);
+ for (panes) |pane| to[@intFromEnum(pane[0])] = col.objs[@intFromEnum(pane[0])] != null;
+ split = col.columnSplit(panes);
+ },
+ .above, .on => {
+ to[@intFromEnum(Part.band)] = true;
+ for (b.panes orelse &.{}) |pane| to[@intFromEnum(pane[0])] = col.objs[@intFromEnum(pane[0])] != null;
+ // The drawing at its lens size across both columns, as large as the stage lets it.
+ const room: Rect = if (at == .on) .{ .x = 64, .y = column_top, .w = 1792, .h = 712 } else .{ .x = 64, .y = column_top + 132, .w = 1792, .h = bubble.bottom - column_top - 132 };
+ zoom = @min(room.w / lens_w, (room.h - m.tag) / lens_h);
+ split.band = room;
+ },
+ }
+ // Not before the text up has been read.
+ s.wait(@max(col.read_by - s.cursor, 0));
+ const kind = frameOf(at) != frameOf(col.placement);
+ const moves = !std.meta.eql(to, col.standing) or !sameBoxes(col.split, split, to) or zoom != col.zoom or kind;
+ const newest = col.newestStanding();
+ if (col.said) {
+ if (kind or at != .beside) {
+ // A text never travels between placements: what stands leaves (then a gap, as a caption's).
+ col.leaveAll(s);
+ if (!moves) s.wait(time.caption_gap);
+ } else if (moves) if (newest) |k| {
+ s.play(.{col.texts[k].dim.to(1)}, .{ .seconds = f.dim, .ease = anim.ease.linear });
+ };
+ }
+ if (moves) col.change(s, to, split, at, zoom, kind);
+ col.placement = at;
+ // A beat with nothing to say: the panes alone.
+ if (b.say.len == 0) return;
+ // The text.
+ const tx = col.add(s, b.say, at, level, switch (b.stem) {
+ .level => level,
+ .none => null,
+ .to => |l| l,
+ }, b.where, notes);
+ if (at == .beside) {
+ // Three stand at most: the oldest leaves first.
+ var standing: usize = 0;
+ var oldest: ?usize = null;
+ for (col.texts[0 .. col.n - 1], 0..) |x, k| if (x.placement == .beside and settled(s, x.out) < 1) {
+ standing += 1;
+ if (oldest == null) oldest = k;
+ };
+ if (standing >= 3) {
+ s.play(.{col.texts[oldest.?].out.to(1)}, .{ .seconds = f.leave, .ease = easeExit });
+ }
+ if (standing > 0) {
+ const start = s.cursor;
+ // A beat that keeps its panes: the last dims as the older ones make way.
+ if (!moves) if (newest) |k| {
+ s.play(.{col.texts[k].dim.to(1)}, .{ .seconds = f.dim, .ease = anim.ease.linear });
+ s.cursor = start;
+ };
+ s.play(.{tx.push.to(1)}, .{ .seconds = f.push, .ease = anim.ease.linear });
+ } else s.play(.{tx.push.to(1)}, .{ .seconds = 0 });
+ } else s.play(.{tx.push.to(1)}, .{ .seconds = 0 });
+ const arrives = s.cursor;
+ s.play(.{tx.notes_in.to(1)}, .{ .seconds = f.note, .ease = anim.ease.linear });
+ s.cursor = arrives;
+ s.play(.{tx.in.to(1)}, .{ .seconds = f.arrive, .ease = easeEnter });
+ if (tx.stem != null and at != .below and at != .above) {
+ const arrived = s.cursor;
+ s.cursor = arrives + f.stem_after;
+ s.play(.{tx.stem_v.to(1)}, .{ .seconds = f.stem, .ease = anim.ease.linear });
+ s.cursor = @max(s.cursor, arrived);
+ }
+ col.read_by = s.cursor + time.caption(@intCast(std.unicode.utf8CountCodepoints(b.say) catch b.say.len));
+ s.wait(if (col.said) time.caption_lead else time.caption_lead_first);
+ // The stem draws back as the step fires: the step's own ties have the gutter.
+ const fires = s.cursor;
+ s.play(.{tx.stem_v.to(2)}, .{ .seconds = f.stem, .ease = anim.ease.linear });
+ s.cursor = fires;
+ col.said = true;
+ }
+
+ /// The close: the last picture still, the last text read.
+ pub fn close(col: *Column, s: *anim.Frame) void {
+ s.wait(time.before_cut);
+ s.wait(@max(col.read_by - s.cursor, 0));
+ }
+
+ fn add(col: *Column, s: *anim.Frame, text: []const u8, at: Placement, level: Level, stem: ?Level, where: ?[2]f32, notes: [parts.len]?[]const u8) *Text {
+ const k = @min(col.n, col.texts.len - 1);
+ col.texts[k] = .{ .text = text, .placement = at, .level = level, .stem = stem, .where = where, .notes = notes, .in = s.value(0), .dim = s.value(0), .out = s.value(0), .stem_v = s.value(0), .push = s.value(0), .notes_in = s.value(0) };
+ col.n = k + 1;
+ return &col.texts[k];
+ }
+
+ fn newestStanding(col: *const Column) ?usize {
+ if (col.n == 0 or col.texts[col.n - 1].placement != .beside) return null;
+ return col.n - 1;
+ }
+
+ fn leaveAll(col: *Column, s: *anim.Frame) void {
+ var all: [48]anim.Animation = undefined;
+ var n: usize = 0;
+ for (col.texts[0..col.n]) |x| if (settled(s, x.out) < 1) {
+ all[n] = x.out.to(1);
+ n += 1;
+ };
+ if (n > 0) together(s, all[0..n], f.leave, easeExit);
+ }
+
+ /// The panes go from what stands to `to` at `split`: the leaving fade
+ /// and fold, the staying glide, the coming unfold and fade in; never a
+ /// fold and an unfold at once.
+ fn change(col: *Column, s: *anim.Frame, to: [parts.len]bool, split: Split, at: Placement, zoom: f32, kind: bool) void {
+ var leaving: [parts.len]bool = undefined;
+ var coming: [parts.len]bool = undefined;
+ // A pane that stays but changes its rows: its rows fade out and in round the
+ // glide (they are laid out for its height), its frame gliding as the column's.
+ var resized: [parts.len]bool = undefined;
+ var any_leaving = false;
+ var any_coming = false;
+ inline for (.{ "band", "view", "source", "disasm", "registers", "stack", "backtrace" }, 0..) |name, i| {
+ leaving[i] = col.standing[i] and !to[i];
+ coming[i] = !col.standing[i] and to[i];
+ resized[i] = col.standing[i] and to[i] and i > 1 and @field(col.split, name).h != @field(split, name).h;
+ any_leaving = any_leaving or leaving[i] or resized[i];
+ any_coming = any_coming or coming[i] or resized[i];
+ }
+ const band = @intFromEnum(Part.band);
+ const view = @intFromEnum(Part.view);
+ if (any_leaving) {
+ var anims: [3 * parts.len]anim.Animation = undefined;
+ var n: usize = 0;
+ for (parts, 0..) |_, i| if (leaving[i] or resized[i]) {
+ anims[n] = col.ghost[i].to(1);
+ n += 1;
+ };
+ for (parts, 0..) |_, i| if (resized[i]) if (col.objs[i]) |o| {
+ anims[n] = o.fadeOut();
+ n += 1;
+ };
+ for (parts, 0..) |_, i| if (leaving[i]) if (col.objs[i]) |o| {
+ // The lens is one object: it goes when neither of its panes stands (once).
+ const lens = i == band or i == view;
+ if (!lens or !(to[band] or to[view]) and !(i == view and leaving[band])) {
+ anims[n] = o.fadeOut();
+ n += 1;
+ }
+ if (i == band) {
+ anims[n] = col.stage.drawing.to(0);
+ n += 1;
+ }
+ };
+ if (n > 0) together(s, anims[0..n], f.rows, anim.ease.linear);
+ n = 0;
+ for (parts, 0..) |_, i| if (leaving[i]) {
+ anims[n] = col.shelf[i].to(1);
+ n += 1;
+ };
+ if (n > 0) {
+ together(s, anims[0..n], f.fold, anim.ease.linear);
+ n = 0;
+ for (parts, 0..) |_, i| if (leaving[i]) {
+ anims[n] = col.ghost[i].to(0);
+ n += 1;
+ };
+ together(s, anims[0..n], 0, anim.ease.linear);
+ }
+ }
+ // What stays glides (the frame changing between placements: 48 f); the
+ // folded keep their boxes, a folded band none, so that its view can stand alone.
+ var next = split;
+ inline for (.{ "band", "view", "source", "disasm", "registers", "stack", "backtrace" }, 0..) |name, i| if (!to[i]) {
+ @field(next, name) = @field(col.split, name);
+ if (i == band) next.band.h = 0;
+ };
+ const glides = !sameBoxes(col.split, next, col.standing) or zoom != col.zoom or kind;
+ const seconds: f32 = if (!glides) 0 else if (kind) f.relayout else f.glide;
+ const start = s.cursor;
+ // A pane going over to the other column goes down (or up) its own
+ // first, as the others make room, then across: never over another's rows.
+ var mid = next;
+ var crosses = false;
+ inline for (.{ "band", "view", "source", "disasm", "registers", "stack", "backtrace" }, 0..) |name, i| if (to[i] and col.standing[i] and @field(next, name).x != @field(col.split, name).x) {
+ @field(mid, name).x = @field(col.split, name).x;
+ crosses = true;
+ };
+ if (crosses) col.stage.glide(s, mid, seconds / 2);
+ col.stage.glide(s, next, if (crosses) seconds / 2 else seconds);
+ const end = s.cursor;
+ s.cursor = start;
+ s.play(.{col.stage.column.to(if (at == .beside) 1 else 0)}, .{ .seconds = seconds, .ease = anim.ease.linear });
+ // The drawing grows with its box, across both columns, its tag as it was.
+ s.cursor = start;
+ s.play(.{col.stage.zoom.to(zoom)}, .{ .seconds = seconds, .ease = easeGlide });
+ s.cursor = end;
+ col.split = next;
+ col.zoom = zoom;
+ if (any_coming) {
+ var anims: [3 * parts.len]anim.Animation = undefined;
+ var n: usize = 0;
+ for (parts, 0..) |_, i| if (coming[i]) {
+ anims[n] = col.ghost[i].to(1);
+ n += 1;
+ };
+ together(s, anims[0..n], 0, anim.ease.linear);
+ n = 0;
+ for (parts, 0..) |_, i| if (coming[i]) {
+ anims[n] = col.shelf[i].to(0);
+ n += 1;
+ };
+ if (n > 0) together(s, anims[0..n], f.fold, anim.ease.linear);
+ n = 0;
+ for (parts, 0..) |_, i| if (coming[i] or resized[i]) {
+ anims[n] = col.ghost[i].to(0);
+ n += 1;
+ };
+ for (parts, 0..) |_, i| if (resized[i]) if (col.objs[i]) |o| {
+ anims[n] = o.fadeIn();
+ n += 1;
+ };
+ for (parts, 0..) |_, i| if (coming[i]) if (col.objs[i]) |o| {
+ const lens = i == band or i == view;
+ if (!lens or !(col.standing[band] or col.standing[view]) and !(i == view and coming[band])) {
+ anims[n] = o.fadeIn();
+ n += 1;
+ }
+ if (i == band) {
+ anims[n] = col.stage.drawing.to(1);
+ n += 1;
+ }
+ };
+ if (n > 0) together(s, anims[0..n], f.rows, anim.ease.linear);
+ }
+ col.standing = to;
+ }
+
+ /// The beat's panes where the scene names none: its cause, the source
+ /// (three lines) over the disassembly; and where the next step's effect
+ /// lands, the registers or the stack.
+ fn defaults(col: *const Column, s: *anim.Frame) []const Pane {
+ const rec = col.cursor.rec;
+ const here = col.cursor.moment(s);
+ const next = rec.next(.moment, here);
+ const changed = rec.registersChanged(here, next) & ~cursors.quiet & ~(@as(u32, 1) << @intCast(context.index("rsp").?));
+ const pushes = rec.register(next, "rsp") != rec.register(here, "rsp") or rec.written(here, next).len > 0;
+ const out = s.arena.alloc(Pane, 3) catch @panic("column: out of memory");
+ out[0] = .{ .source, 3 };
+ if (changed != 0) {
+ out[1] = .{ .disasm, 11 };
+ out[2] = .{ .registers, if (col.stage.registers_rows > 0) @intFromFloat(col.stage.registers_rows) else @intCast(context.registerRows(context.every)) };
+ return out;
+ }
+ if (pushes) {
+ out[1] = .{ .disasm, 11 };
+ out[2] = .{ .stack, rest };
+ return out;
+ }
+ out[1] = .{ .disasm, rest };
+ return out[0..2];
+ }
+
+ /// The panes in one column, 12 apart from 84, in the frame's order.
+ fn columnSplit(col: *const Column, panes: []const Pane) Split {
+ var rows: [parts.len]?u32 = @splat(null);
+ for (panes) |p| rows[@intFromEnum(p[0])] = p[1];
+ var fixed: f32 = 0;
+ var n: f32 = 0;
+ for (rows) |r| if (r) |count| {
+ if (count != rest) fixed += theme.layout.panelH(@floatFromInt(count));
+ n += 1;
+ };
+ const left = column_foot - column_top - fixed - (n - 1) * theme.canvas.row_gap;
+ var out = col.split;
+ var y: f32 = column_top;
+ inline for (.{ "band", "view", "source", "disasm", "registers", "stack", "backtrace" }, 0..) |name, i| if (rows[i]) |count| {
+ const h = if (count == rest) theme.layout.panelH(@floatFromInt(theme.layout.rowsIn(left))) else theme.layout.panelH(@floatFromInt(count));
+ @field(out, name) = .{ .x = theme.layout.program.x, .y = y, .w = theme.layout.program.w, .h = h };
+ y += h + theme.canvas.row_gap;
+ };
+ return out;
+ }
+
+ pub fn draw(col: *const Column, fr: *sk.Frame, placed: anim.Placed) void {
+ const u: ui.Ui = .{ .f = fr, .at = placed };
+ col.drawShelf(u, placed);
+ col.drawTexts(u, placed);
+ }
+
+ fn box(col: *const Column, placed: anim.Placed, p: Part) Rect {
+ return col.stage.box(placed, switch (p) {
+ inline else => |tag| @field(@import("stage.zig").Part, @tagName(tag)),
+ });
+ }
+
+ /// The notes in force: the newest text's, crossfading from the one before.
+ fn notesNow(col: *const Column, placed: anim.Placed) struct { [parts.len]?[]const u8, [parts.len]?[]const u8, f32 } {
+ var k = col.n;
+ while (k > 0) {
+ k -= 1;
+ const p = placed.value(col.texts[k].notes_in);
+ if (p <= 0) continue;
+ const before: [parts.len]?[]const u8 = if (k > 0) col.texts[k - 1].notes else @splat(null);
+ return .{ before, col.texts[k].notes, p };
+ }
+ return .{ @splat(null), @splat(null), 1 };
+ }
+
+ /// The shelf: each folded pane's tag, side by side from 64 in the frame's
+ /// order; a pane folding or unfolding drawn as its frame on its way
+ /// between its box and its place there.
+ fn drawShelf(col: *const Column, u: ui.Ui, placed: anim.Placed) void {
+ const before, const after, const p = col.notesNow(placed);
+ var x: f32 = theme.layout.program.x;
+ for (parts, 0..) |part, i| {
+ if (col.objs[i] == null) continue;
+ const on = theme.ease(.glide, placed.value(col.shelf[i]));
+ // Its frame drawn in the pane's stead: crossfading with the pane at its box, alone on its way.
+ const ghost = placed.value(col.ghost[i]);
+ if (on <= 0 and ghost <= 0) continue;
+ const notes = [2]?[]const u8{ before[i], after[i] };
+ const w = std.math.lerp(tagWidth(col, u, placed, part, notes[0]), tagWidth(col, u, placed, part, notes[1]), p);
+ const slot: Rect = .{ .x = x, .y = shelf_y, .w = w, .h = m.tag };
+ const name = col.title(placed, part);
+ const b = col.box(placed, part);
+ const r: Rect = if (ghost > 0) .{ .x = std.math.lerp(b.x, slot.x, on), .y = std.math.lerp(b.y, slot.y, on), .w = std.math.lerp(b.w, slot.w, on), .h = std.math.lerp(b.h, slot.h, on) } else slot;
+ const v = u.moved(r.x, r.y).faded(if (on > 0) 1 else ghost);
+ _ = v.panel(r.w, r.h, name, .{});
+ // Its note comes as it lands on the shelf, and goes as it leaves.
+ const shows = std.math.clamp((on - 0.75) * 4, 0, 1);
+ if (shows > 0) {
+ const nx = 28 + v.width(.sans_medium, theme.size.sans.tag, name) + 12;
+ if (p < 1) _ = col.tagNote(v.faded(shows * (1 - p)), placed, part, nx, notes[0]);
+ _ = col.tagNote(v.faded(shows * p), placed, part, nx, notes[1]);
+ }
+ x += (w + theme.canvas.row_gap) * on;
+ }
+ }
+
+ fn title(col: *const Column, placed: anim.Placed, p: Part) []const u8 {
+ if (p != .source) return col.titles[@intFromEnum(p)];
+ const now = col.cursor.now(placed);
+ const rec = col.cursor.rec;
+ return rec.sources[rec.shown[now.marked()].src].name();
+ }
+
+ fn tagWidth(col: *const Column, u: ui.Ui, placed: anim.Placed, p: Part, note: ?[]const u8) f32 {
+ const title_w = u.width(.sans_medium, theme.size.sans.tag, col.title(placed, p));
+ const note_w = col.tagNote(u.faded(0), placed, p, 0, note);
+ return 28 + title_w + (if (note_w > 0) 12 + note_w else 0) + 12;
+ }
+
+ /// A folded pane's note from `x`: the scene's, or for the registers the
+ /// ones the last steps changed (the first with its value, struck on the
+ /// tag as on its row). How wide it is.
+ fn tagNote(col: *const Column, u: ui.Ui, placed: anim.Placed, p: Part, x: f32, note: ?[]const u8) f32 {
+ const base = m.tag - 6;
+ if (note) |text| return words.runs(u, x, base, text, .sans, theme.size.sans.micro, theme.size.mono.context, t.faint) - x;
+ if (p == .source or p == .disasm) {
+ // Where the mark is: the line, or the instruction and its address; changing with the advance.
+ const now = col.cursor.now(placed);
+ const turn = now.renaming();
+ const was = if (turn < 1) col.markNote(u.faded(1 - turn), now.marks[0], p, x) else 0;
+ const is = if (turn > 0) col.markNote(u.faded(turn), now.marks[1], p, x) else 0;
+ return std.math.lerp(was, is, turn);
+ }
+ if (p != .registers) return 0;
+ const now = col.cursor.now(placed);
+ // The step's registers come with their strike; the step before's go (6 f; at a run its 8 f).
+ const first = for (theme.metric.all_registers[0..16]) |name| {
+ const i = context.index(name).?;
+ if (now.registerAge(i) == 0) break ties.strikeDelay(now, i);
+ } else 0;
+ const turn: f32 = if (now.resting()) 1 else switch (now.plan.gait) {
+ .walk => std.math.clamp(now.since(.cpu, first) / time.strike.in, 0, 1),
+ .run => std.math.clamp(now.since(.cpu, 0) / time.run_ease, 0, 1),
+ .sprint => std.math.clamp(now.time / @max(now.plan.total, 1.0 / 60.0), 0, 1),
+ };
+ const was = if (turn < 1) col.registersNote(u.faded(1 - turn), now, x, 1) else 0;
+ const is = if (turn > 0) col.registersNote(u.faded(turn), now, x, 0) else 0;
+ return std.math.lerp(was, is, turn);
+ }
+
+ /// The source's line at `moment` (`line 12`), or the disassembly's instruction there (`jne 4011af`).
+ fn markNote(col: *const Column, u: ui.Ui, moment: u64, p: Part, x: f32) f32 {
+ const rec = col.cursor.rec;
+ const size = theme.size.mono.context;
+ const base = m.tag - 6;
+ var at = x;
+ if (p == .source) {
+ u.text(.mono, size, at, base, "line", t.dim);
+ at += u.width(.mono, size, "line") + ui.advance(size);
+ const n = u.print("{d}", .{rec.shown[moment].line});
+ u.text(.mono, size, at, base, n, t.primary);
+ return at + u.width(.mono, size, n) - x;
+ }
+ var buf: [256]u8 = undefined;
+ const pc = rec.register(moment, "rip");
+ const here = rec.instruction(moment, pc, &buf) orelse return 0;
+ const mn = (@import("disasm.zig").Insn{ .addr = pc, .len = here.len, .text = here.text }).mnemonic();
+ const word = u.print("{s}", .{mn});
+ u.text(.mono_bold, size, at, base, word, theme.color.code.keyword);
+ at += u.width(.mono, size, word) + ui.advance(size);
+ return u.address(at, base, pc, .{ .ink = ui.rgb(theme.color.region.code_) }) - x;
+ }
+
+ /// The registers the step `age` steps ago changed (three at most, in
+ /// pwndbg's order), the first with its value: struck on the tag as on its row.
+ fn registersNote(col: *const Column, u: ui.Ui, now: cursors.Now, x: f32, age: u64) f32 {
+ const base = m.tag - 6;
+ const rec = col.cursor.rec;
+ const size = theme.size.mono.context;
+ var at = x;
+ var shown: usize = 0;
+ for (theme.metric.all_registers[0..16]) |name| {
+ const i = context.index(name).?;
+ if (now.registerAgeFrom(i, age) != age or shown == 3) continue;
+ if (shown > 0) at += ui.advance(size);
+ u.text(.mono, size, at, base, name, if (shown == 0) t.dim else t.primary);
+ at += u.width(.mono, size, name);
+ if (shown == 0) {
+ const v = rec.register(now.stops[age], name);
+ at += ui.advance(size);
+ const digits = if (v < 0x10000) u.print("{d}", .{v}) else u.print("{x}", .{v});
+ const dw = u.width(.mono, size, digits);
+ const heat = if (age == 0) now.register(i, ties.strikeDelay(now, i)) else now.heat(1, null, 0);
+ const ink = u.written(.{ .x = at, .y = 0, .w = dw, .h = m.tag }, heat) orelse ui.Ink{};
+ u.text(ink.face, size, at, base, digits, ink.ink);
+ at += dw;
+ }
+ shown += 1;
+ }
+ return at - x;
+ }
+
+ fn drawTexts(col: *const Column, u: ui.Ui, placed: anim.Placed) void {
+ const inv = placed.xf.invert();
+ const now = col.cursor.now(placed);
+ // The newest text arriving (or arrived), and the beside ones standing.
+ var newest: ?usize = null;
+ for (col.texts[0..col.n], 0..) |x, k| if (placed.value(x.push) > 0 or placed.value(x.in) > 0) {
+ newest = k;
+ };
+ // While panes fold, unfold or are laid out anew, what has been said stays where it is, from then on.
+ for (col.ghost) |g| if (placed.value(g) > 0) {
+ for (col.texts[0..col.n], 0..) |_, k| if (last_level[k] != null) {
+ latched[k] = true;
+ };
+ break;
+ };
+ var with: [48]f32 = undefined;
+ var without: [48]f32 = undefined;
+ col.layout(placed, inv, newest, true, &with);
+ col.layout(placed, inv, newest, false, &without);
+ const push = if (newest) |k| theme.ease(.glide, placed.value(col.texts[k].push)) else 1;
+ for (col.texts[0..col.n], 0..) |x, k| {
+ const in = placed.value(x.in);
+ const out = placed.value(x.out);
+ if (in <= 0 or out >= 1) continue;
+ const rise = (1 - theme.ease(.enter, in)) * time.caption_rise;
+ var shows = in * (1 - out);
+ switch (x.placement) {
+ .below => {
+ const v = u.faded(shows).moved(0, rise);
+ var lines = std.mem.splitScalar(u8, x.text, '\n');
+ const two = std.mem.indexOfScalar(u8, x.text, '\n') != null;
+ var n: usize = if (two) 1 else 0;
+ while (lines.next()) |line| : (n += 1) {
+ if (n > 2) break;
+ _ = words.runs(v, theme.canvas.margin_x, theme.canvas.caption_baseline[n], line, .sans, theme.size.sans.caption, theme.size.mono.value, t.primary);
+ }
+ },
+ .above => {
+ const lines = wrap(u, x.text, 80);
+ const v = u.faded(shows).moved(0, rise);
+ for (lines, 0..) |line, n| _ = words.runs(v, theme.canvas.margin_x, column_top + bubble.first + @as(f32, @floatFromInt(n)) * bubble.pitch + 14, line, .sans, theme.size.sans.caption, theme.size.mono.value, t.primary);
+ },
+ .on => {
+ const where = x.where orelse .{ 104, 144 };
+ col.paper(u.faded(shows).moved(0, rise), x, where[0], where[1], 0);
+ if (x.stem) |target| col.stemOn(u, inv, x, where, target, placed);
+ },
+ .beside => {
+ // At a run only the newest stands.
+ if (newest != k) shows *= 1 - now.hurried;
+ const top = if (newest == k) with[k] else std.math.lerp(without[k], with[k], push);
+ col.paper(u.faded(shows).moved(0, rise), x, bubble.x, top, placed.value(x.dim));
+ if (x.stem) |target| col.stemBeside(u, inv, x, top, target, placed);
+ },
+ }
+ }
+ }
+
+ /// A bubble's text from `x, top`: on `raised` paper and primary, the
+ /// paper going and the ink dimming as it becomes the account (`dim`).
+ fn paper(_: *const Column, u: ui.Ui, x: Text, left: f32, top: f32, dim: f32) void {
+ const lines = wrap(u, x.text, bubble.chars);
+ const h = bubble.first * 2 + @as(f32, @floatFromInt(lines.len - 1)) * bubble.pitch;
+ if (dim < 1) u.faded(1 - dim).fill(.{ .x = left, .y = top, .w = paperWidth(u, x), .h = h }, theme.color.raised);
+ const ink = ui.mix(t.primary, t.dim, dim);
+ for (lines, 0..) |line, n| _ = words.runs(u, left + bubble.pad, top + bubble.first + @as(f32, @floatFromInt(n)) * bubble.pitch + 14, line, .sans, theme.size.sans.caption, theme.size.mono.value, ink);
+ }
+
+ /// Each beside text's top, the newest's or not: level with what it
+ /// speaks of where it can be; an older one in a newer one's way above it,
+ /// or under it where there is no room above.
+ fn layout(col: *const Column, placed: anim.Placed, inv: sk.math.Affine, newest: ?usize, with_newest: bool, out: *[48]f32) void {
+ var taken: [48][2]f32 = undefined;
+ var n_taken: usize = 0;
+ var k = col.n;
+ while (k > 0) {
+ k -= 1;
+ const x = col.texts[k];
+ out[k] = 0;
+ if (x.placement != .beside) continue;
+ if (!with_newest and newest == k) continue;
+ if (placed.value(x.out) >= 1) continue;
+ // Only what has arrived.
+ if (newest == null or k > newest.?) continue;
+ const h = height(x);
+ var top = std.math.clamp(levelY(placed, inv, k, x.level) - bubble.first, bubble.top, bubble.bottom - h);
+ // Above what is in its way, while there is room; else under it.
+ var tries: usize = 0;
+ while (tries < n_taken + 1) : (tries += 1) {
+ const hit = for (taken[0..n_taken]) |r| {
+ if (top < r[1] + bubble.gap and top + h + bubble.gap > r[0]) break r;
+ } else null;
+ const r = hit orelse break;
+ top = r[0] - bubble.gap - h;
+ }
+ if (top < bubble.top) {
+ var lowest: f32 = bubble.top;
+ for (taken[0..n_taken]) |r| lowest = @max(lowest, r[1] + bubble.gap);
+ top = lowest;
+ }
+ out[k] = top;
+ taken[n_taken] = .{ top, top + h };
+ n_taken += 1;
+ }
+ }
+
+ /// The stem of a beside text: from its first line across the gutter onto
+ /// the pane's right rule level with the row, a head 7 by 8 on the rule.
+ fn stemBeside(_: *const Column, u: ui.Ui, inv: sk.math.Affine, x: Text, top: f32, target: Level, placed: anim.Placed) void {
+ const v = placed.value(x.stem_v);
+ if (v <= 0 or v >= 2) return;
+ const r = find(inv, target) orelse return;
+ const y0 = top + bubble.first;
+ const y1 = (r[1] + r[3]) / 2;
+ const lane = theme.metric.tie.link_lane + 6;
+ var buf = [4]ui.Vec{ .{ bubble.x, y0 }, .{ lane, y0 }, .{ lane, y1 }, .{ r[2] + 1, y1 } };
+ const points: []const ui.Vec = if (@abs(y0 - y1) < 1) &.{ .{ bubble.x, y1 }, .{ r[2] + 1, y1 } } else buf[0..];
+ u.route(points, t.dim, .{ .width = theme.stroke.rule, .head = .{ 7, 8 }, .progress = cursors.standard(@min(v, 1)), .from = cursors.standard(@max(v - 1, 0)), .radius = 6 });
+ }
+
+ /// The stem of a text `on` a drawing: round the drawing's outside, along
+ /// its top lane (under its tag), down onto the part it speaks of.
+ fn stemOn(col: *const Column, u: ui.Ui, inv: sk.math.Affine, x: Text, where: [2]f32, target: Level, placed: anim.Placed) void {
+ const v = placed.value(x.stem_v);
+ if (v <= 0 or v >= 2) return;
+ const r = find(inv, target) orelse return;
+ const w = paperWidth(u, x);
+ const lane = column_top + m.tag + 10;
+ const from_x = where[0] + w - 32;
+ const to_x = r[2] - 24;
+ _ = col;
+ u.route(&.{ .{ from_x, where[1] }, .{ from_x, lane }, .{ to_x, lane }, .{ to_x, r[1] - 1 } }, t.dim, .{ .width = theme.stroke.rule, .head = .{ 7, 8 }, .progress = cursors.standard(@min(v, 1)), .from = cursors.standard(@max(v - 1, 0)), .radius = 8 });
+ }
+};
+
+/// `all` played together from the cursor, which then moves past them.
+fn together(s: *anim.Frame, all: []const anim.Animation, seconds: f32, ease: anim.Ease) void {
+ const start = s.cursor;
+ for (all) |a| {
+ s.cursor = start;
+ s.play(.{a}, .{ .seconds = seconds, .ease = ease });
+ }
+ s.cursor = start + seconds;
+}
+
+fn easeExit(x: f32) f32 {
+ return theme.ease(.exit, x);
+}
+fn easeEnter(x: f32) f32 {
+ return theme.ease(.enter, x);
+}
+fn easeGlide(x: f32) f32 {
+ return theme.ease(.glide, x);
+}
+
+fn frameOf(p: Placement) enum { working, column, wide } {
+ return switch (p) {
+ .below => .working,
+ .beside => .column,
+ .above, .on => .wide,
+ };
+}
+
+/// Whether the panes that stand in both have the same boxes.
+fn sameBoxes(a: Split, b: Split, standing: [parts.len]bool) bool {
+ inline for (.{ "band", "view", "source", "disasm", "registers", "stack", "backtrace" }, 0..) |name, i| {
+ if (standing[i] and !std.meta.eql(@field(a, name), @field(b, name))) return false;
+ }
+ return true;
+}
+
+fn settled(s: *const anim.Frame, v: anim.Value) f32 {
+ return s.values.items[@backingInt(v)].settled;
+}
+
+/// Where a level's place is this frame, in the frame's units: left, top, right, bottom.
+fn find(inv: sk.math.Affine, level: Level) ?[4]f32 {
+ const place: ties.Place = switch (level) {
+ .pc => .pc,
+ .row => |a| .{ .row = a },
+ .head => |name| .{ .row = @import("descent.zig").headKey(name) },
+ .floor => .floor,
+ .block => |a| .{ .block = a },
+ .y => |y| return .{ 0, y - m.row / 2, theme.layout.program.x + theme.layout.program.w, y + m.row / 2 },
+ };
+ const r = ties.find(place) orelse return null;
+ const a = inv.apply(.{ r[0], r[1] });
+ const b = inv.apply(.{ r[2], r[3] });
+ return .{ a[0], a[1], b[0], b[1] };
+}
+
+/// The middle of the row a text `k` is level with; where the row has gone
+/// (a window closed round it), where it last was.
+/// shortcut: remembered by the process as frames are drawn in order (an export, a player playing); after a seek a text whose row is gone sits at 400 until it is seen again.
+var last_level: [48]?f32 = @splat(null);
+/// Once its row has gone from a pane that is drawn, or the panes have changed, a text stays where it is (`latched`).
+var latched: [48]bool = @splat(false);
+fn levelY(_: anim.Placed, inv: sk.math.Affine, k: usize, level: Level) f32 {
+ if (!latched[k]) if (find(inv, level)) |r| {
+ const y = (r[1] + r[3]) / 2;
+ last_level[k] = y;
+ return y;
+ };
+ // A row of the disassembly, gone while the pane is there (its pc drawn): the text stays.
+ if (last_level[k] != null and (level == .row or level == .head or level == .floor) and ties.find(.pc) != null) latched[k] = true;
+ return last_level[k] orelse 400;
+}
+
+fn height(x: Text) f32 {
+ const n = lineCount(x.text, bubble.chars);
+ return bubble.first * 2 + @as(f32, @floatFromInt(n - 1)) * bubble.pitch;
+}
+
+fn paperWidth(u: ui.Ui, x: Text) f32 {
+ var w: f32 = 0;
+ for (wrap(u, x.text, bubble.chars)) |line| w = @max(w, runsWidth(u, line));
+ return @min(w + 2 * bubble.pad, bubble.max_w);
+}
+
+/// How wide `words.runs` sets `text`.
+fn runsWidth(u: ui.Ui, text: []const u8) f32 {
+ var w: f32 = 0;
+ var parts_ = std.mem.splitScalar(u8, text, '`');
+ var code = false;
+ while (parts_.next()) |part| : (code = !code) w += if (code) u.width(.mono, theme.size.mono.value, part) else u.width(.sans, theme.size.sans.caption, part);
+ return w;
+}
+
+/// `text` in lines of at most `chars` characters (a newline breaks one too),
+/// broken at spaces; a code span broken across two lines is closed and opened again.
+fn wrap(u: ui.Ui, text: []const u8, chars: usize) []const []const u8 {
+ var lines: std.ArrayList([]const u8) = .empty;
+ var paragraphs = std.mem.splitScalar(u8, text, '\n');
+ while (paragraphs.next()) |para| {
+ var line: std.ArrayList(u8) = .empty;
+ var count: usize = 0;
+ var code = false;
+ var ws = std.mem.splitScalar(u8, para, ' ');
+ while (ws.next()) |word| {
+ const n = visible(word);
+ if (count > 0 and count + 1 + n > chars) {
+ if (code) line.append(u.f.scratch, '`') catch {};
+ lines.append(u.f.scratch, line.items) catch {};
+ line = .empty;
+ count = 0;
+ if (code) line.append(u.f.scratch, '`') catch {};
+ }
+ if (count > 0) line.append(u.f.scratch, ' ') catch {};
+ line.appendSlice(u.f.scratch, word) catch {};
+ count += n + @intFromBool(count > 0);
+ for (word) |ch| if (ch == '`') {
+ code = !code;
+ };
+ }
+ lines.append(u.f.scratch, line.items) catch {};
+ }
+ return lines.items;
+}
+
+/// How many lines `wrap` makes of `text`.
+fn lineCount(text: []const u8, chars: usize) usize {
+ var n: usize = 0;
+ var paragraphs = std.mem.splitScalar(u8, text, '\n');
+ while (paragraphs.next()) |para| {
+ var count: usize = 0;
+ n += 1;
+ var ws = std.mem.splitScalar(u8, para, ' ');
+ while (ws.next()) |word| {
+ const w = visible(word);
+ if (count > 0 and count + 1 + w > chars) {
+ n += 1;
+ count = 0;
+ }
+ count += w + @intFromBool(count > 0);
+ }
+ }
+ return n;
+}
+
+/// Its characters as shown: backticks are not.
+fn visible(word: []const u8) usize {
+ const n = std.unicode.utf8CountCodepoints(word) catch word.len;
+ return n - std.mem.count(u8, word, "`");
+}
+
+/// The column over context `ctx`: add it after the panes and the lens and
+/// before the ties (`ctx.ties`); the scene opens in the working frame, its
+/// first beat usually `below` (the opening establishes everything).
+pub fn column(s: *anim.Frame, ctx: anytype, options: Options) *Column {
+ const st = ctx.stage;
+ const working = st.last();
+ var objs: [parts.len]?anim.Obj = .{ options.lens, options.lens, ctx.source, ctx.disasm, ctx.registers, ctx.stack, ctx.backtrace };
+ if (working.band.h <= 0) objs[0] = null;
+ if (working.view.h <= 0) objs[1] = null;
+ if (working.backtrace.h <= 0) objs[6] = null;
+ var shelf: [parts.len]anim.Value = undefined;
+ var ghost: [parts.len]anim.Value = undefined;
+ for (&shelf, &ghost) |*a, *b| {
+ a.* = s.value(0);
+ b.* = s.value(0);
+ }
+ var standing: [parts.len]bool = undefined;
+ for (objs, &standing) |o, *is| is.* = o != null;
+ const col = s.new(Column{
+ .cursor = ctx.cursor,
+ .stage = st,
+ .objs = objs,
+ .titles = .{ options.titles.band, options.titles.view, "", "disassembly", "registers", "stack", "backtrace" },
+ .standing = standing,
+ .shelf = shelf,
+ .ghost = ghost,
+ .default = options.at,
+ .working = working,
+ .split = working,
+ });
+ col.obj = s.custom(col, .{ .x = -640, .y = -360, .scale = ui.scale });
+ s.play(.{col.obj.fadeIn()}, .{ .seconds = 0 });
+ return col;
+}
+
+test "a bubble's lines: at most forty characters, a code span kept whole on each" {
+ const n = lineCount("main puts open's arguments where the convention says: \"note\" in rdi, 0 (O_RDONLY) in rsi.", 40);
+ try std.testing.expectEqual(@as(usize, 3), n);
+ try std.testing.expectEqual(@as(usize, 2), lineCount("`syscall` crosses down.\nThe kernel answers.", 40));
+ try std.testing.expectEqual(@as(usize, 4), visible("`rdi`,"));
+}
diff --git a/anim/src/context.zig b/anim/src/context.zig
index d4bc94d..16278e3 100644
--- a/anim/src/context.zig
+++ b/anim/src/context.zig
@@ -348,6 +348,42 @@ pub fn frames(rec: *const Recording, i: u64, out: []Frame) []Frame {
return out[0..found.len];
}
+/// The register the newest frame's code addresses its words by
+/// (design/README.md, `slot`): its call frame information's CFA register,
+/// rbp in a body that keeps a frame pointer; rsp at its entry, in its
+/// prologue before `mov rbp, rsp`, after its `pop rbp` or `leave`, in a
+/// function that keeps none, and where the recording has no such rows.
+pub const Base = struct {
+ rbp: bool = false,
+
+ pub fn name(b: Base) []const u8 {
+ return if (b.rbp) "rbp" else "rsp";
+ }
+
+ pub fn value(b: Base, regs: zt.Regs) u64 {
+ return if (b.rbp) regs.rbp else regs.rsp;
+ }
+};
+
+pub fn frameBase(rec: *const Recording, i: u64, regs: zt.Regs) Base {
+ const func = zt.telescope.function(rec.moment(i), regs.rip) orelse return .{};
+ const size = @sizeOf(zt.Symbols.Row);
+ var row: zt.Symbols.Row = .{};
+ var o: usize = 0;
+ while (o + size <= func.rows.len) : (o += size) {
+ const r = std.mem.bytesToValue(zt.Symbols.Row, func.rows[o..][0..size]);
+ if (r.offset > regs.rip -% func.start) break;
+ row = r;
+ }
+ // DWARF's 6 is rbp; and rbp must be in the frame (under its return address).
+ return .{ .rbp = row.cfa_reg == 6 and regs.rbp >= regs.rsp };
+}
+
+/// `d` bytes from base `name` (`rbp-18`, `rbp+8`, `rbp`), as the stack's tag writes a range.
+fn fromBase(u: ui.Ui, name: []const u8, d: i64) []const u8 {
+ return if (d == 0) name else if (d > 0) u.print("{s}+{x}", .{ name, @as(u64, @intCast(d)) }) else u.print("{s}-{x}", .{ name, @as(u64, @intCast(-d)) });
+}
+
/// A frame's span on the stack: its function's name, and as a call its
/// argument where it takes one (`fib(4)`): the digits on its node.
fn spanName(u: ui.Ui, rec: *const Recording, open: []const Recording.Call, i: usize, pc: u64) []const u8 {
@@ -439,6 +475,8 @@ pub const Stack = struct {
const hold = placed.value(k.stage.hold);
const held = hold >= 0;
const held_at: u64 = if (held) rec.register(@intFromFloat(hold), "rsp") -% 8 * @as(u64, @intFromFloat(placed.value(k.stage.hold_free))) else 0;
+ // `tied`: two `free` words over rsp, the window's headroom; offsets from the frame's base; rsp's and rbp's moves as pins travelling.
+ const tied = now.annotation == .tied;
var window = if (held) [2]u64{ held_at, held_at } else if (k.above != 0) [2]u64{ is.rsp -% @as(u64, @bitCast(@as(i64, 8 * k.above))), was.rsp -% @as(u64, @bitCast(@as(i64, 8 * k.above))) } else [2]u64{ windowAt(now, is, slots, 0), windowAt(now, was, slots, 1) };
// A window that goes farther than its own height (a continue to a
// stop deeper or shallower than a call is) does not scroll: the old
@@ -459,6 +497,11 @@ pub const Stack = struct {
// Going to the hold and coming from it, the rows scroll: the
// remaining way, in rows, from where the window would be.
const natural = windowAt(now, is, slots, 0);
+ // Under `tied`, the word the step touches, and the window over it before the touch goes there.
+ const touch: ?cursors.Touched = if (tied and !now.resting()) cursors.stackTouch(rec, now.stops[1], now.stops[0]) else null;
+ const touch_window = if (touch) |tt| if (!held and k.above == 0 and !jumped and (tt.addr < window[1] or tt.addr >= window[1] + 8 * @as(u64, slots))) windowOver(was, slots, tt.addr) else window[1] else window[1];
+ // The frame's base, before the step and after it (`whole`: rsp).
+ const bases = [2]Base{ if (tied) frameBase(rec, now.stops[1], was) else .{}, if (tied) frameBase(rec, now.stops[0], is) else .{} };
const hold_scroll: f32 = if (held) @as(f32, @floatFromInt(@as(i64, @bitCast(held_at -% natural)))) / 8 * (1 - cursors.glide(placed.value(k.stage.hold_in))) else 0;
// From rsp, or the range shown when the window is elsewhere: in
// bytes from rsp, as the catalogue writes it (`rsp+20 to rsp+48`).
@@ -471,10 +514,18 @@ pub const Stack = struct {
const words = if (slots < numbers.len) numbers[slots] else u.print("{d}", .{slots});
// The first word shown and the last.
// The range before memory lands and after: one that changes crossfades (12 f), as a role does.
- const recast = if (now.resting()) 1 else std.math.clamp(since_memory / time.quick, 0, 1);
+ // Under `tied` a walked step's labels change as its window follows, or its last pin lands (`Now.restacked`).
+ const recast = if (now.resting()) 1 else if (tied and now.walking()) std.math.clamp((now.time - now.restacked()) / time.quick, 0, 1) else std.math.clamp(since_memory / time.quick, 0, 1);
const ranges = [2]i64{ @bitCast(ways[1] -% was.rsp), @bitCast(ways[0] -% is.rsp) };
var notes: [2][]const u8 = undefined;
- for (ranges, &notes) |r_, *note| {
+ for (ranges, &notes, [2]zt.Regs{ was, is }, bases, 0..) |r_, *note, regs, base, side| {
+ if (tied) {
+ // From the base: `fourteen words` where the window is at its headroom, else the range.
+ const from: i64 = @bitCast(ways[1 - side] -% base.value(regs));
+ const range = if (ways[1 - side] == regs.rsp -% 16 and k.above == 0) u.print("{s} words", .{words}) else u.print("{s} to {s}", .{ fromBase(u, base.name(), from), fromBase(u, base.name(), from + 8 * (@as(i64, @intCast(slots)) - 1)) });
+ note.* = u.print("{s} \u{00b7} offsets from {s} \u{00b7} the frames they belong to", .{ range, base.name() });
+ continue;
+ }
const range = if (r_ == 0) u.print("{s} words from rsp", .{words}) else u.print("{s} to {s}", .{ offset(u, r_), offset(u, r_ + 8 * (@as(i64, @intCast(slots)) - 1)) });
note.* = u.print("{s} \u{00b7} the frames they belong to", .{range});
}
@@ -484,9 +535,38 @@ pub const Stack = struct {
u.faded(1 - recast).tagNote(box.w, notes[0]);
u.faded(recast).tagNote(box.w, notes[1]);
}
- const p = cursors.glide(now.moving(.memory, 0, time.move));
+ var p = cursors.glide(now.moving(.memory, 0, time.move));
const moved = @as(f32, @floatFromInt(@as(i64, @bitCast(window[0] -% window[1])))) / 8;
- const slide: f32 = (if (jumped) 0 else moved * (1 - p)) + hold_scroll;
+ var slide: f32 = (if (jumped) 0 else moved * (1 - p)) + hold_scroll;
+ // Under `tied`, walked (design/README.md, `stack`): the rows hold while the pin travels;
+ // a word the step touches outside the window is scrolled to before the touch goes there;
+ // where the climb is longer than the room over the pin, the rows slide under it (the pin on
+ // the top row); once it has landed the window follows (`Plan.follow`).
+ const pin_sp = now.pinGone(0);
+ if (tied and !jumped and !held and k.above == 0 and now.walking() and (now.plan.follow >= 0 or now.plan.touch >= 0 or pin_sp != null)) {
+ const rows_at = struct {
+ fn at(addr: u64, base: u64) f32 {
+ return @as(f32, @floatFromInt(@as(i64, @bitCast(addr -% base)))) / 8;
+ }
+ /// The window's top (rows from `window[0]`) with the pin at `pin`: never past it.
+ fn keep(d: f32, pin: f32, n: usize) f32 {
+ return std.math.clamp(d, pin - @as(f32, @floatFromInt(n - 1)), pin);
+ }
+ };
+ var d = rows_at.at(window[1], window[0]);
+ if (touch_window != window[1]) d = std.math.lerp(d, rows_at.at(touch_window, window[0]), cursors.glide(std.math.clamp(now.time / @max(now.plan.touch, time.fire), 0, 1)));
+ const pins_at = [2]f32{ rows_at.at(was.rsp, window[0]), rows_at.at(is.rsp, window[0]) };
+ const landed_d = rows_at.keep(rows_at.at(touch_window, window[0]), pins_at[1], slots);
+ if (pin_sp) |g| d = rows_at.keep(d, std.math.lerp(pins_at[0], pins_at[1], g), slots);
+ if (now.plan.follow >= 0) {
+ const span = @min(time.tied.follow + 2.0 / 60.0 * @max(@abs(landed_d) - 1, 0), time.tied.follow_most);
+ const q = cursors.glide(std.math.clamp((now.time - now.plan.follow) / span, 0, 1));
+ if (now.time >= now.plan.follow) d = std.math.lerp(landed_d, 0, q);
+ } else d = std.math.lerp(d, 0, p);
+ slide = -d;
+ // The strip's window goes as the pane's does.
+ p = if (moved != 0) std.math.clamp(1 - slide / moved, 0, 1) else 1;
+ }
const top = body.y + m.pad;
clipBody(u, box);
defer u.unclip();
@@ -532,11 +612,13 @@ pub const Stack = struct {
const calls_is = rec.stack(u.f.scratch, now.stops[0]);
var spans: [16]Span = undefined;
var n_spans: usize = 0;
+ // Under `tied` the spans ride rsp's pin: the newest stretches or shrinks with it.
+ const p_span = pin_sp orelse p;
for (chain, 0..) |frame, i| {
const old_frame = if (i < old_chain.len) old_chain[i] else frame;
- const first = std.math.lerp(rows_of(old_frame.lo, window[0]), rows_of(frame.lo, window[0]), p) + slide;
+ const first = std.math.lerp(rows_of(old_frame.lo, window[0]), rows_of(frame.lo, window[0]), p_span) + slide;
if (first >= @as(f32, @floatFromInt(slots))) break;
- const last = if (frame.hi) |hi| std.math.lerp(if (old_frame.hi) |oh| rows_of(oh, window[0]) else rows_of(hi, window[0]), rows_of(hi, window[0]), p) + slide else std.math.inf(f32);
+ const last = if (frame.hi) |hi| std.math.lerp(if (old_frame.hi) |oh| rows_of(oh, window[0]) else rows_of(hi, window[0]), rows_of(hi, window[0]), p_span) + slide else std.math.inf(f32);
if (last < 0) continue;
const open = last >= @as(f32, @floatFromInt(slots));
const y1 = top + (@min(last, @as(f32, @floatFromInt(slots)) - 1) + 1) * m.row;
@@ -558,6 +640,8 @@ pub const Stack = struct {
const goes = struct {
fn of(n: cursors.Now, a: zt.Regs, b: zt.Regs, name: []const u8) f32 {
if (n.resting()) return 1;
+ // `tied`: as its plan travels it (`Now.pinGone`).
+ if (n.pinGone(if (std.mem.eql(u8, name, "rsp")) 0 else 1)) |g| return g;
const pin = time.pin;
const rows_far: f32 = @floatFromInt(@abs(@as(i64, @bitCast((b.named(name) orelse 0) -% (a.named(name) orelse 0)))) / 8);
const takes = @min(pin.row + pin.step_per_row * @max(rows_far - 1, 0), pin.row_max);
@@ -592,19 +676,42 @@ pub const Stack = struct {
// Who points here: a pin in the lane, landing with its link.
const names = pins(u, now, is, was, addr, travel);
var marks: rows.Marks = .{ .lead = lead, .first = now.writtenWatched(addr, 8, .memory, 0, watched_from, watched_to) };
- if (watched_from == 0 and watched_to > 0 and now.wasRead(addr, 8) and now.writeAge(addr, 8) != 0) {
+ // Under `tied` the word a `pop`, a `ret` or a `leave` reads is read too (the recordings say no read there).
+ const touched_here = if (touch) |tt| tt.addr & ~@as(u64, 7) == addr else false;
+ if (watched_from == 0 and watched_to > 0 and (now.wasRead(addr, 8) or (touched_here and !touch.?.write)) and now.writeAge(addr, 8) != 0) {
marks.read = 0;
marks.read_shows = now.reading(.memory, 0);
}
- const below_rsp: i64 = @bitCast(addr -% if (held) rsp_shown else is.rsp);
+ // A word stored with the value it held (a `push rbp` over the old saved rbp): armed, and nothing struck.
+ if (touched_here and touch.?.write and now.walking() and now.writeAge(addr, 8) != 0) {
+ const s_at = now.plan.at[1];
+ marks.first.arm = std.math.clamp((now.time - (s_at - time.strike.arm)) / time.stagger, 0, 1) * (1 - std.math.clamp((now.time - s_at) / time.quick, 0, 1));
+ }
+ const below_rsp: i64 = if (tied) @bitCast(addr -% bases[1].value(is)) else @bitCast(addr -% if (held) rsp_shown else is.rsp);
map.row(.stack, addr, u, .{ .x = 0, .y = y, .w = box.w, .h = m.row });
// `free`: above rsp, not yet reached: its address at 60%, its word faint.
// A free word rsp reaches (a push, `sub rsp`) becomes a slot as memory strikes (12 f), never in a frame.
- const free_was = held and addr < was.rsp;
- const free_is = held and addr < is.rsp;
- const slot_shows: f32 = if (free_was == free_is or now.resting()) @as(f32, if (free_is) 0 else 1) else if (free_is) 1 - recast else recast;
- if (slot_shows < 1) rows.free(v.faded(1 - slot_shows), y, memory, addr, below_rsp, lead);
- if (slot_shows <= 0) continue;
+ // Under `tied` every word over rsp but a leaf's locals there (the red zone, its frame's).
+ const k_free = (addr -% roles_from) / 8;
+ // (A word a `push` is about to write has its role already, at the push's own stop: still free.)
+ const free_was = (held or tied) and addr < was.rsp and !(tied and k_free < roles[0].len and roles[0][k_free].frame != null and roles[0][k_free].role == .local);
+ const free_is = (held or tied) and addr < is.rsp and !(tied and k_free < roles[1].len and roles[1][k_free].frame != null and roles[1][k_free].role == .local);
+ // `tied`: gained or released as rsp's pin reaches it (12 f).
+ // A word the step writes over rsp (a push's, a call's, a store the line makes past the old rsp) is the frame's as its arm comes
+ // (the touch's word as the touch lands): armed, struck, and then the pin climbs over it.
+ const passed = if (touched_here and touch.?.write and now.walking() and now.plan.touch >= 0) now.time - now.plan.touch - time.tied.touch else if (tied and now.walking() and free_was and !free_is and now.writeAge(addr, 8) == 0) now.time - (now.plan.at[1] + now.writeDelay(addr, 8) - time.strike.arm) else if (pin_sp != null and !held) pinPassed(now, rows_of(was.rsp, window[0]), rows_of(is.rsp, window[0]), @as(f32, @floatFromInt(n))) else null;
+ const turned = if (passed) |ago| std.math.clamp(ago / time.quick, 0, 1) else recast;
+ const slot_shows: f32 = if (free_was == free_is or now.resting()) @as(f32, if (free_is) 0 else 1) else if (free_is) 1 - turned else turned;
+ const offset_was: ?i64 = if (tied) @as(i64, @bitCast(addr -% bases[0].value(was))) else null;
+ if (slot_shows < 1) rows.free(v.faded(1 - slot_shows), y, memory, addr, below_rsp, lead, .{ .name = "", .going = recast, .from_rsp = offset_was });
+ if (slot_shows <= 0) {
+ // `tied`: a free word is a place too (the touch of a push or a call goes to it).
+ if (tied and y >= top - 1 and y + m.row <= box.h - m.pad + 1) {
+ ties.anchor(u, .{ .word = addr }, .{ .x = theme.metric.slot.address, .y = y, .w = 120, .h = m.row });
+ ties.anchor(u, .{ .slot_pin = addr }, .{ .x = theme.metric.slot.lane, .y = y, .w = theme.metric.slot.lane_end - theme.metric.slot.lane, .h = m.row });
+ }
+ continue;
+ }
const vs = v.faded(slot_shows);
// A frame's name beside this row: the chain ends a character before it.
var room_w = map.content(box.w);
@@ -623,12 +730,11 @@ pub const Stack = struct {
const k_role = (addr -% roles_from) / 8;
var role_at: [2]@TypeOf(roleName(u, .none, 0)) = undefined;
for (&role_at, roles, [2]Recording.Moment{ now.before(), now.moment() }) |*r, of, mem| {
- const what: zt.telescope.Role = if (k_role < of.len) of[k_role].role else .none;
- r.* = roleName(u, what, (Recording.word(mem, addr, 8) catch null) orelse 1);
+ r.* = slotName(u, if (k_role < of.len) of[k_role] else .{}, (Recording.word(mem, addr, 8) catch null) orelse 1);
}
const what: zt.telescope.Role = if (k_role < roles[1].len) roles[1][k_role].role else .none;
const role = role_at[1];
- const role_was: rows.Role = .{ .name = role_at[0].name, .local = role_at[0].local, .going = recast, .from_rsp = @bitCast(addr -% was.rsp) };
+ const role_was: rows.Role = .{ .name = role_at[0].name, .local = role_at[0].local, .going = if (passed != null) turned else recast, .from_rsp = if (tied) @bitCast(addr -% bases[0].value(was)) else @bitCast(addr -% was.rsp), .offset_going = recast };
// At a run a word changes in place under an 8 f crossfade, as a register does.
const ran = runFade(now, .memory);
const word_was = Recording.word(now.before(), addr, 8) catch null;
@@ -669,18 +775,35 @@ pub const Stack = struct {
if (!ui.mapping) ties.stack_window = .{ .first = window[0], .slots = slots, .x = lane_at[0], .top = lane_at[1], .row = row_px };
// The travelling tags: both of them at one word share a pin.
var places: [2]f32 = undefined;
- for (travel, places[0..travel.len]) |name, *place| {
- const at_old = @as(f32, @floatFromInt(@as(i64, @bitCast((was.named(name) orelse 0) -% window[0])))) / 8 + slide;
+ var olds: [2]f32 = undefined;
+ const slots_f: f32 = @floatFromInt(slots);
+ for (travel, places[0..travel.len], olds[0..travel.len]) |name, *place, *old| {
+ var at_old = @as(f32, @floatFromInt(@as(i64, @bitCast((was.named(name) orelse 0) -% window[0])))) / 8 + slide;
const at_new = @as(f32, @floatFromInt(@as(i64, @bitCast((is.named(name) orelse 0) -% window[0])))) / 8 + slide;
+ // `tied`: a pin from outside the window comes in at its edge (rbp in from the window's foot).
+ if (tied) at_old = std.math.clamp(at_old, -1, slots_f);
+ old.* = at_old;
place.* = std.math.lerp(at_old, at_new, goes(now, was, is, name));
}
- for (travel, places[0..travel.len], 0..) |name, place, i| {
+ // `tied`: rsp's move on its pin as it travels, counting a row at a time, held to the advance and crossfading to the bare name (12 f).
+ const amount_shows: f32 = if (tied and now.walking() and pin_sp != null and now.time >= now.plan.pins[0]) 1 - std.math.clamp((now.time - now.plan.advance) / time.quick, 0, 1) else 0;
+ for (travel, places[0..travel.len], olds[0..travel.len], 0..) |name, place, old, i| {
if (i == 1 and @abs(places[0] - place) < 0.05) continue;
- if (place < -0.5 or place > @as(f32, @floatFromInt(slots)) - 0.5) continue;
+ if (place < (if (tied) @as(f32, -1) else -0.5) or place > (if (tied) slots_f else slots_f - 0.5)) continue;
const both = i == 0 and travel.len == 2 and @abs(places[1] - place) < 0.05;
// Alone, from its place among the names it leaves to its place among those it joins.
const x = if (lone != null) std.math.lerp(pinPlace(u, pins(u, now, is, was, was.named(name) orelse 0, travel).names, name), pinPlace(u, pins(u, now, is, was, is.named(name) orelse 0, travel).names, name), goes(now, was, is, name)) else theme.metric.slot.lane;
- u.pinRow(x, top + place * m.row, if (both) &.{ "rsp", "rbp" } else &.{name}, theme.color.region.stack);
+ const names_: []const []const u8 = if (both) &.{ "rsp", "rbp" } else &.{name};
+ if (amount_shows > 0 and std.mem.eql(u8, name, "rsp")) {
+ const crossed = @abs(place - old);
+ const total_rows = cursors.wordsApart(rec, now.stops[1], now.stops[0], "rsp");
+ // Rows crossed, counted on its whole way (its start may be off the window).
+ const count = std.math.clamp(@ceil(goes(now, was, is, "rsp") * total_rows - 0.01), 1, total_rows);
+ const bytes: u64 = @intFromFloat(count * 8);
+ pinAmount(u, x, top + place * m.row, names_, if (is.rsp < was.rsp) u.print("-{x}", .{bytes}) else u.print("+{x}", .{bytes}), amount_shows);
+ // The rows it crossed, a 3-unit vermilion bracket in the outer arc lane.
+ if (crossed > 0.05) u.faded(amount_shows).bracket(theme.metric.arc.lanes[0], top + @min(place, old) * m.row + 2, top + @max(place, old) * m.row - 2, theme.mark(.write).solid, theme.metric.bracket.tie, 1, false);
+ } else u.pinRow(x, top + place * m.row, names_, theme.color.region.stack);
}
for (spans[0..n_spans]) |sp| if (sp.was) |was_name| {
rows.span(v.faded(1 - renamed), map.content(box.w), sp.y0, sp.y1, was_name, sp.newest, sp.open);
@@ -694,10 +817,11 @@ pub const Stack = struct {
/// local's name (primary, `+8` a word into it); `argc`, `argv[0]`,
/// `argv end`, `envp end`, `auxv` (dim). A return address needs none:
/// its chain is code, named. `word`: what the slot holds (0 ends argv and envp).
- fn roleName(u: ui.Ui, role: zt.telescope.Role, word: u64) struct { name: []const u8, local: bool = false } {
+ pub fn roleName(u: ui.Ui, role: zt.telescope.Role, word: u64) struct { name: []const u8, local: bool = false } {
return switch (role) {
.none, .return_address => .{ .name = "" },
- .saved => |r| .{ .name = u.print("saved {s}", .{r}) },
+ // The stack protector's copy is the `canary`, not a register saved.
+ .saved => |r| .{ .name = if (std.mem.eql(u8, r, "canary")) "canary" else u.print("saved {s}", .{r}) },
.local => |l| .{ .name = if (l.offset > 0) u.print("{s}+{x}", .{ l.name, @as(u32, @intCast(l.offset)) }) else if (l.offset == -4 and l.size == 4) u.print("{s}, high half", .{l.name}) else if (l.offset < 0) u.print("{s}, from byte {d}", .{ l.name, -l.offset }) else l.name, .local = true },
.argc => .{ .name = "argc" },
.argv => |i| .{ .name = if (word == 0) "argv end" else u.print("argv[{d}]", .{i}) },
@@ -706,6 +830,31 @@ pub const Stack = struct {
};
}
+ /// A slot's role (`roleName`), with the other locals that share its word: `i, n`.
+ pub fn slotName(u: ui.Ui, slot: zt.telescope.Slot, word: u64) @TypeOf(roleName(u, .none, 0)) {
+ if (slot.role != .local or slot.also[0] == null) return roleName(u, slot.role, word);
+ var out: []const u8 = slot.role.local.name;
+ for (slot.also) |a| if (a) |l| {
+ out = u.print("{s}, {s}", .{ out, l.name });
+ };
+ return .{ .name = out, .local = true };
+ }
+
+ /// A row pin of `names` with rsp's move on it (`amount`, `-18`, bold in
+ /// write's vermilion), `shows` of the amount; its head after it.
+ fn pinAmount(u: ui.Ui, x: f32, y: f32, names: []const []const u8, amount: []const u8, shows: f32) void {
+ const size = theme.size.mono.context;
+ const p = theme.metric.pin;
+ const shown = if (names.len == 2) u.print("{s} {s}", .{ names[0], names[1] }) else names[0];
+ const base = theme.baseline(y, m.row, size);
+ u.text(.mono_bold, size, x, base, shown, t.primary);
+ const end = x + u.width(.mono, size, shown);
+ u.faded(shows).text(.mono_bold, size, end + ui.advance(size), base, amount, theme.mark(.write).solid);
+ const hx = end + shows * (ui.advance(size) + u.width(.mono, size, amount)) + p.row_gap;
+ const mid = y + m.row / 2;
+ sk.draw.polygon(u.f, &.{ .{ hx + p.row_head[0], mid }, .{ hx, mid - p.row_head[1] / 2 }, .{ hx, mid + p.row_head[1] / 2 } }, u.at.pen(.{ .fill = ui.rgb(theme.color.region.stack) }));
+ }
+
/// Where `name` goes in a row pin of `others` and it, in the registers' order.
fn pinPlace(u: ui.Ui, others: []const []const u8, name: []const u8) f32 {
const size = theme.size.mono.context;
@@ -736,6 +885,25 @@ pub const Stack = struct {
sk.draw.polygon(u.f, &.{ .{ hx + p.row_head[0], mid }, .{ hx, mid - p.row_head[1] / 2 }, .{ hx, mid + p.row_head[1] / 2 } }, u.at.pen(.{ .fill = ui.rgb(theme.color.region.stack) }));
}
+ /// Seconds since rsp's pin, going from row `from` to row `to` of the
+ /// window, passed the middle of row `n` (negative before it): when a word
+ /// it reaches is gained, or one it leaves released. Null where it does not cross it.
+ fn pinPassed(now: cursors.Now, from: f32, to: f32, n: f32) ?f32 {
+ if (from == to) return null;
+ const q = (n + 0.5 - from) / (to - from);
+ if (q < 0 or q > 1) return null;
+ const run = now.plan.gait == .run;
+ const start: f32 = if (run) 0 else now.plan.pins[0];
+ // When its eased way reaches q.
+ var lo: f32 = 0;
+ var hi: f32 = 1;
+ for (0..16) |_| {
+ const mid = (lo + hi) / 2;
+ if ((if (run) cursors.standard(mid) else cursors.glide(mid)) < q) lo = mid else hi = mid;
+ }
+ return now.time - (start + lo * cursors.pinTime(@abs(to - from), run));
+ }
+
/// Whether a window of `slots` going from word `a` to word `b` goes
/// farther than its own height: it fades, and does not scroll.
fn far(a: u64, b: u64, slots: usize) bool {
@@ -761,9 +929,11 @@ pub const Stack = struct {
/// read there is in the window's middle.
fn windowAt(now: cursors.Now, regs: zt.Regs, slots: usize, skip: usize) u64 {
const frame_end = regs.rbp +% 16;
- if (frame_end <= regs.rsp or frame_end - regs.rsp > 8 * 64) return regs.rsp;
- const words = (frame_end - regs.rsp) / 8;
- if (words <= slots) return regs.rsp;
+ // `tied`: from its headroom, two `free` words over rsp (the room a push, a call or a `sub rsp` takes).
+ const top = if (now.annotation == .tied) regs.rsp -% 16 else regs.rsp;
+ if (frame_end <= regs.rsp or frame_end - regs.rsp > 8 * 64) return top;
+ const words = (frame_end - top) / 8;
+ if (words <= slots) return top;
for (skip..skip + 3) |age| {
if (age + 1 >= now.stops.len) break;
for ([_][]const Recording.Span{ now.rec.written(now.stops[age + 1], now.stops[age]), now.rec.read(now.stops[age + 1], now.stops[age]) }) |spans| {
@@ -771,14 +941,23 @@ pub const Stack = struct {
while (k > 0) {
k -= 1;
const a = spans[k].addr;
- if (a < regs.rsp or a >= frame_end) continue;
- const word = (a - regs.rsp) / 8;
+ if (a < top or a >= frame_end) continue;
+ const word = (a - top) / 8;
const first = @min(word -| (slots - 1) / 2, words - slots);
- return regs.rsp + 8 * first;
+ return top + 8 * first;
}
}
}
- return regs.rsp;
+ return top;
+ }
+
+ /// Under `tied`, a window of `slots` from the headroom over `regs`'s rsp
+ /// that has word `addr` in its middle: where it scrolls before a touch.
+ fn windowOver(regs: zt.Regs, slots: usize, addr: u64) u64 {
+ const top = regs.rsp -% 16;
+ if (addr < top) return addr & ~@as(u64, 7);
+ const words = (@max(regs.rbp +% 16, addr + 8) - top) / 8;
+ return top + 8 * @min(((addr - top) / 8) -| (slots - 1) / 2, words -| slots);
}
const Pins = struct { names: []const []const u8, shows: f32 };
diff --git a/anim/src/cursor.zig b/anim/src/cursor.zig
index 16ccd77..5cb625a 100644
--- a/anim/src/cursor.zig
+++ b/anim/src/cursor.zig
@@ -63,6 +63,17 @@ pub const Levels = struct {
/// sets it, `Context.Options.syscalls`): what the step changed in the
/// registers strikes once the call is back.
crossings: bool = false,
+ /// The disassembly's annotation (design/README.md, `insn`), read when
+ /// the context is made: `tied` names the word an instruction touches,
+ /// the stack counts from the frame's base with two `free` words over
+ /// rsp, and a walked step goes cause to effect (the `touch`, the word,
+ /// rsp's or rbp's pin, then the window); `whole` is pwndbg's chain,
+ /// offsets from rsp, and the cascade as it was.
+ annotation: enum { tied, whole } = .tied,
+ /// A value's way between memory and a register (`carry`, "4. Ties"),
+ /// read at each step (a beat may turn it on): none, an arrow, or the
+ /// arrow carrying the value's digits on a chip.
+ carry: enum { off, arrow, value } = .off,
};
/// How a step is drawn. Walk: everything, as a sentence. Run: the mark and
@@ -88,6 +99,46 @@ pub const Plan = struct {
/// (a step that went on from it without its rest: a crossing from its
/// call row): what it struck goes on cooling, never cut in a frame.
cooling: f32 = 0,
+ /// A walk under `tied` (design/motion.md, "A word touched", "The
+ /// stack's own instructions"), seconds from its first frame, negative
+ /// where the step has none: the touch sets off; what the step read is
+ /// framed; the carry sets off (`carry_value`: its digits ride it); rsp's
+ /// pin and rbp's set off; the stack's window follows; the projection
+ /// sets off (else from memory's strike).
+ touch: f32 = -1,
+ read: f32 = -1,
+ carry: f32 = -1,
+ carry_value: bool = false,
+ pins: [2]f32 = .{ -1, -1 },
+ follow: f32 = -1,
+ project: f32 = -1,
+
+ /// How many values a plan is on the timeline (`pack`).
+ const values = 18;
+
+ fn pack(p: Plan) [values]f32 {
+ return .{ @floatFromInt(@intFromEnum(p.gait)), p.at[0], p.at[1], p.at[2], p.advance, p.travel, p.total, @floatFromInt(@intFromBool(p.wave)), @floatFromInt(@intFromBool(p.fires)), p.cooling, p.touch, p.read, p.carry, @floatFromInt(@intFromBool(p.carry_value)), p.pins[0], p.pins[1], p.follow, p.project };
+ }
+
+ fn unpack(v: [values]f32) Plan {
+ return .{
+ .gait = @enumFromInt(@as(u2, @intFromFloat(std.math.clamp(@round(v[0]), 0, 2)))),
+ .at = .{ v[1], v[2], v[3] },
+ .advance = v[4],
+ .travel = v[5],
+ .total = v[6],
+ .wave = v[7] >= 0.5,
+ .fires = v[8] >= 0.5,
+ .cooling = v[9],
+ .touch = v[10],
+ .read = v[11],
+ .carry = v[12],
+ .carry_value = v[13] >= 0.5,
+ .pins = .{ v[14], v[15] },
+ .follow = v[16],
+ .project = v[17],
+ };
+ }
/// Once the pattern is known: the levels a stagger apart from the
/// first frame, the mark after them, in `seconds`.
@@ -110,6 +161,116 @@ pub const quiet: u32 = blk: {
break :blk mask;
};
+/// rsp's and rbp's places in `Regs.names`.
+pub const sp_index: u5 = blk: {
+ for (zt.Regs.names, 0..) |name, i| if (std.mem.eql(u8, name, "rsp")) break :blk i;
+ unreachable;
+};
+pub const bp_index: u5 = blk: {
+ for (zt.Regs.names, 0..) |name, i| if (std.mem.eql(u8, name, "rbp")) break :blk i;
+ unreachable;
+};
+
+/// The word of the stack a step's instruction reads or writes: what its
+/// `touch` goes to (design/README.md, "4. Ties"). The instruction's moment,
+/// the word's address and width, and whether it writes there.
+pub const Touched = struct { at: u64, addr: u64, len: u64, write: bool };
+
+/// The step's touched word: a write first (the effect), else the first
+/// read; the recorder's `touch` where it has one, else what a `push` or a
+/// `call` writes at the new rsp, a `pop` or a `ret` reads at the old, a
+/// `leave` at the old rbp (a recording made before the tracer's touches of
+/// implicit operands, the gallery's, carries none for those).
+pub fn stackTouch(rec: *const Recording, from: u64, to: u64) ?Touched {
+ var read: ?Touched = null;
+ var buf: [256]u8 = undefined;
+ var i = from;
+ // shortcut: a step of more than 64 instructions looks at its first 64.
+ while (i < to and i < from + 64 and i < rec.end()) : (i += 1) {
+ const m = rec.moment(i);
+ for (rec.insn_touches[i]) |maybe| if (maybe) |tt| {
+ if ((zt.telescope.region(m, tt.addr) catch .none) != .stack) continue;
+ const one: Touched = .{ .at = i, .addr = tt.addr, .len = tt.len, .write = tt.how & 2 != 0 };
+ if (one.write) return one;
+ if (read == null) read = one;
+ };
+ const was = rec.registers[i];
+ const is = rec.registers[i + 1];
+ const here = rec.instruction(i, was.rip, &buf) orelse continue;
+ const mn = here.text[0 .. std.mem.indexOfScalar(u8, here.text, ' ') orelse here.text.len];
+ const eql = std.mem.eql;
+ // Only where the moment after is the instruction's own (a recording by instruction).
+ const next = is.rip == was.rip + here.len or (rec.insn_branches[i] != null and rec.insn_branches[i].?.to == is.rip);
+ if (!next) continue;
+ if ((eql(u8, mn, "push") or eql(u8, mn, "call")) and is.rsp +% 8 == was.rsp) return .{ .at = i, .addr = is.rsp, .len = 8, .write = true };
+ if (read != null) continue;
+ if ((eql(u8, mn, "pop") or eql(u8, mn, "ret")) and is.rsp == was.rsp +% 8) read = .{ .at = i, .addr = was.rsp, .len = 8, .write = false };
+ if (eql(u8, mn, "leave")) read = .{ .at = i, .addr = was.rbp, .len = 8, .write = false };
+ }
+ return read;
+}
+
+/// A value's way for `carry`: a load (into the register, `load`) or a store
+/// (from it), by the touched instruction's operands: `mov` a register and
+/// the word, a `push` or a `pop` of a register. Null for anything else (a
+/// call's return address, an access with no register at its other end).
+pub const Carry = struct { load: bool, reg: []const u8 };
+
+pub fn carried(rec: *const Recording, touch: Touched) ?Carry {
+ var buf: [256]u8 = undefined;
+ const here = rec.instruction(touch.at, rec.register(touch.at, "rip"), &buf) orelse return null;
+ const text = here.text;
+ const space = std.mem.indexOfScalar(u8, text, ' ') orelse return null;
+ const mn = text[0..space];
+ const ops = std.mem.trim(u8, text[space..], " ");
+ const comma = std.mem.indexOfScalar(u8, ops, ',');
+ const first = std.mem.trim(u8, ops[0 .. comma orelse ops.len], " ");
+ const second = if (comma) |cm| std.mem.trim(u8, ops[cm + 1 ..], " ") else "";
+ const eql = std.mem.eql;
+ if (eql(u8, mn, "push")) return if (register64(first)) |r| .{ .load = false, .reg = r } else null;
+ if (eql(u8, mn, "pop")) return if (register64(first)) |r| .{ .load = true, .reg = r } else null;
+ if (!std.mem.startsWith(u8, mn, "mov")) return null;
+ if (touch.write) return if (register64(second)) |r| .{ .load = false, .reg = r } else null;
+ return if (register64(first)) |r| .{ .load = true, .reg = r } else null;
+}
+
+/// A general register's 64-bit name, from any of its widths; null for anything else.
+pub fn register64(name: []const u8) ?[]const u8 {
+ const table = [_][4][]const u8{
+ .{ "rax", "eax", "ax", "al" }, .{ "rbx", "ebx", "bx", "bl" }, .{ "rcx", "ecx", "cx", "cl" }, .{ "rdx", "edx", "dx", "dl" },
+ .{ "rsi", "esi", "si", "sil" }, .{ "rdi", "edi", "di", "dil" }, .{ "rbp", "ebp", "bp", "bpl" }, .{ "rsp", "esp", "sp", "spl" },
+ };
+ for (table) |row| for (row) |n| if (std.mem.eql(u8, n, name)) return row[0];
+ for ([_][]const u8{ "r8", "r9", "r10", "r11", "r12", "r13", "r14", "r15" }) |r| {
+ if (std.mem.startsWith(u8, name, r) and (name.len == r.len or (name.len == r.len + 1 and std.mem.indexOfScalar(u8, "dwb", name[r.len]) != null))) return r;
+ }
+ return null;
+}
+
+/// How many words register `name` (rsp, rbp) moved over the step from `from` to `to`.
+pub fn wordsApart(rec: *const Recording, from: u64, to: u64, name: []const u8) f32 {
+ const a = rec.register(from, name);
+ const b = rec.register(to, name);
+ return @floatFromInt(@abs(@as(i64, @bitCast(b -% a))) / 8);
+}
+
+/// Whether the step is a `pop rbp` (or ends in one alone): rbp's pin flies before rsp's falls.
+fn popsRbp(rec: *const Recording, from: u64, to: u64) bool {
+ if (to != from + 1) return false;
+ var buf: [256]u8 = undefined;
+ const here = rec.instruction(from, rec.register(from, "rip"), &buf) orelse return false;
+ return std.mem.startsWith(u8, here.text, "pop");
+}
+
+/// How long rsp's or rbp's pin takes over `rows` rows (`time.tied`): 24 f
+/// to the next, 6 f a further one, 48 f at most; at a run 8 f and 2 f a
+/// row, 16 f at most.
+pub fn pinTime(rows: f32, run: bool) f32 {
+ const k = time.tied;
+ if (run) return @min(time.run_ease + 2.0 / 60.0 * @max(rows - 1, 0), k.run_pin_most);
+ return @min(k.stack_pin + k.stack_pin_row * @max(rows - 1, 0), k.stack_pin_most);
+}
+
pub const Cursor = struct {
rec: *Recording,
/// Where it is (or is arriving), where it came from, and before that.
@@ -119,8 +280,8 @@ pub const Cursor = struct {
gaits: [history]anim.Value,
/// 0 to 1 through the step it is taking; 1 at rest.
phase: anim.Value,
- /// The step's `Plan`, a value a field.
- plan: [10]anim.Value,
+ /// The step's `Plan`, a value a field (`Plan.pack`).
+ plan: [Plan.values]anim.Value,
/// The moment the current mark was on, and the one it is on (or going to).
marks: [2]anim.Value,
/// 1 while steps are hurried (the head counts them), and while what
@@ -154,7 +315,7 @@ pub const Cursor = struct {
.stops = undefined,
.gaits = undefined,
.phase = s.value(1),
- .plan = .{ s.value(0), s.value(plan.at[0]), s.value(plan.at[1]), s.value(plan.at[2]), s.value(plan.advance), s.value(plan.travel), s.value(plan.total), s.value(0), s.value(1), s.value(0) },
+ .plan = undefined,
.marks = .{ s.value(here), s.value(here) },
.hurried = s.value(0),
.veil = s.value(0),
@@ -164,6 +325,7 @@ pub const Cursor = struct {
.first = start,
.last = start,
};
+ for (&c.plan, Plan.pack(plan)) |*value, is| value.* = s.value(is);
// shortcut: an f32 holds whole moments up to 16 million; a longer recording needs two values a stop.
for (&c.stops) |*stop| stop.* = s.value(here);
for (&c.gaits) |*gait| gait.* = s.value(0);
@@ -183,7 +345,7 @@ pub const Cursor = struct {
stops: [history]anim.Value,
gaits: [history]anim.Value,
phase: anim.Value,
- plan: [10]anim.Value,
+ plan: [Plan.values]anim.Value,
marks: [2]anim.Value,
hurried: anim.Value,
veil: anim.Value,
@@ -261,24 +423,25 @@ pub const Cursor = struct {
const Step = struct {
stops: [history]f32,
gaits: [history]f32,
- plan: [10]f32,
+ plan: [Plan.values]f32,
marks: [2]f32,
count: f32,
seconds: f32,
fn run(st: @This(), sf: *anim.Frame, v: Cursor) void {
- var set: [2 * history + 14]anim.Animation = undefined;
+ const n_plan = Plan.values;
+ var set: [2 * history + n_plan + 4]anim.Animation = undefined;
for (v.stops, st.stops, 0..) |value, is, i| set[i] = value.to(is);
- for (v.gaits, st.gaits, 0..) |value, is, i| set[history + 14 + i] = value.to(is);
+ for (v.gaits, st.gaits, 0..) |value, is, i| set[history + n_plan + 4 + i] = value.to(is);
for (v.plan, st.plan, history..) |value, is, n| set[n] = value.to(is);
- set[history + 10] = v.marks[0].to(st.marks[0]);
- set[history + 11] = v.marks[1].to(st.marks[1]);
- set[history + 12] = v.phase.to(0);
- set[history + 13] = v.count.to(st.count);
+ set[history + n_plan] = v.marks[0].to(st.marks[0]);
+ set[history + n_plan + 1] = v.marks[1].to(st.marks[1]);
+ set[history + n_plan + 2] = v.phase.to(0);
+ set[history + n_plan + 3] = v.count.to(st.count);
sf.play(set, .{ .seconds = 0 });
sf.play(.{v.phase.to(1)}, .{ .seconds = st.seconds, .ease = anim.ease.linear });
}
};
- var st: Step = .{ .stops = undefined, .gaits = undefined, .plan = .{ @floatFromInt(@intFromEnum(plan.gait)), plan.at[0], plan.at[1], plan.at[2], plan.advance, plan.travel, plan.total, @floatFromInt(@intFromBool(plan.wave)), @floatFromInt(@intFromBool(plan.fires)), plan.cooling }, .marks = undefined, .count = settled(s, c.count) + 1, .seconds = seconds };
+ var st: Step = .{ .stops = undefined, .gaits = undefined, .plan = Plan.pack(plan), .marks = undefined, .count = settled(s, c.count) + 1, .seconds = seconds };
st.stops[0] = @floatFromInt(to);
for (1..history) |i| st.stops[i] = settled(s, c.stops[i - 1]);
st.gaits[0] = @floatFromInt(@intFromEnum(plan.gait));
@@ -333,6 +496,7 @@ pub const Cursor = struct {
}
fn timetable(c: Cursor, from: u64, to: u64, wave: bool) Plan {
+ if (c.levels.annotation == .tied and !wave) return c.tiedTable(from, to);
const rec = c.rec;
const regs: f32 = @floatFromInt(@popCount(rec.registersChanged(from, to) & ~quiet));
// Memory gives up its slot when nothing it touched is drawn.
@@ -392,6 +556,126 @@ pub const Cursor = struct {
return plan;
}
+ /// `timetable` under `tied` (design/motion.md, "A word touched", "A call
+ /// pushed", "A return", "The stack's own instructions"): cause before
+ /// effect, nothing downstream marked before what causes it has shown.
+ /// Fire; what the step read, its touch first (a stack word), then its
+ /// frame; the registers it filled (not rsp or rbp), armed after their
+ /// cause, a load's carry between; what it wrote, its touch (or a store's
+ /// carry) first, then armed and struck; a return's idea; rsp's pin and
+ /// rbp's, each struck as it lands (a `pop`'s rbp first); a call's or the
+ /// data's idea; the window follows; the hold, the advance, the rest.
+ fn tiedTable(c: Cursor, from: u64, to: u64) Plan {
+ const rec = c.rec;
+ const k = time.tied;
+ const f = 1.0 / 60.0;
+ const changed = rec.registersChanged(from, to) & ~quiet;
+ const regs: f32 = @floatFromInt(@popCount(changed & ~(@as(u32, 1) << sp_index | @as(u32, 1) << bp_index)));
+ var wrote_n: usize = 0;
+ var strikes_n: usize = 0;
+ for (rec.written(from, to)) |span| {
+ wrote_n += @intFromBool(rec.drawn(span, from, to));
+ strikes_n += @intFromBool(takesPlace(rec, span, from, to));
+ }
+ var read_n: usize = 0;
+ for (rec.read(from, to)) |span| read_n += @intFromBool(rec.drawn(span, from, to));
+ const wrote: f32 = @floatFromInt(if (wrote_n > 0) @max(strikes_n, 1) else 0);
+ const touch = stackTouch(rec, from, to);
+ const deeper = rec.depths[to] > rec.depths[from];
+ const back = rec.depths[to] < rec.depths[from];
+ const idea = switch (c.levels.idea) {
+ .none => false,
+ .calls => deeper or back,
+ .data => wrote_n > 0 or read_n > 0,
+ };
+ const carry: ?Carry = if (c.levels.carry != .off) if (touch) |tt| carried(rec, tt) else null else null;
+ var plan: Plan = .{ .travel = c.travel(from, to, false), .carry_value = c.levels.carry == .value };
+ // When the last cause has shown, and how many things there are to read.
+ var t: f32 = time.fire;
+ var values: f32 = 0;
+ const reads = c.levels.memory and (read_n > 0 or (touch != null and !touch.?.write));
+ if (reads) {
+ if (touch) |tt| if (!tt.write) {
+ plan.touch = t + 6 * f;
+ };
+ plan.read = if (plan.touch >= 0) plan.touch + k.touch else t + 6 * f;
+ t = plan.read + time.read.in;
+ values += 1;
+ }
+ // (A load carried fills its register even where the value is the one it held: the arrow lands, nothing is struck.)
+ const loads = if (carry) |cc| cc.load else false;
+ if (c.levels.cpu and (regs > 0 or loads)) {
+ if (carry) |cc| if (cc.load) {
+ plan.carry = t;
+ t += k.carry;
+ };
+ plan.at[0] = @max(time.cascade, t + time.strike.arm);
+ t = plan.at[0] + @min(@max(regs - 1, 0), 3) * write_apart;
+ values += 1;
+ }
+ const writes = c.levels.memory and (wrote > 0 or (touch != null and touch.?.write));
+ if (writes) {
+ const store = if (carry) |cc| !cc.load else false;
+ if (store) {
+ // The register framed as read (6 f), then the carry: no touch, the row having named the word.
+ plan.carry = t + 12 * f;
+ plan.at[1] = plan.carry + k.carry + time.strike.arm;
+ } else if (touch != null and touch.?.write) {
+ plan.touch = t + 6 * f;
+ plan.at[1] = plan.touch + k.touch + time.strike.arm;
+ } else plan.at[1] = @max(time.cascade, (if (regs > 0) plan.at[0] else if (reads) plan.read else 0) + time.cascade);
+ t = plan.at[1] + @min(@max(wrote - 1, 0), 3) * write_apart;
+ values += 1;
+ } else plan.at[1] = if (reads) plan.read else t;
+ // The idea (design/motion.md, "A return"): a return's node answers before rsp falls.
+ var follow_through: f32 = 0;
+ if (idea and back) {
+ plan.at[2] = t + time.cascade;
+ t = plan.at[2];
+ follow_through = time.snap;
+ values += 1;
+ }
+ // rsp's pin and rbp's, one after the other: a `pop`'s rbp first (it takes the word rsp leaves).
+ const rows = [2]f32{ wordsApart(rec, from, to, "rsp"), wordsApart(rec, from, to, "rbp") };
+ if (rows[0] > 0 or rows[1] > 0) {
+ const order: [2]usize = if (popsRbp(rec, from, to)) .{ 1, 0 } else .{ 0, 1 };
+ var start = t + 6 * f;
+ var first_land: ?f32 = null;
+ for (order) |r| if (rows[r] > 0) {
+ plan.pins[r] = start;
+ t = start + pinTime(rows[r], false);
+ first_land = first_land orelse t;
+ start = t + 6 * f;
+ };
+ // Nothing else in the CPU's slot: it is rsp's (or rbp's) landing.
+ if (!(c.levels.cpu and regs > 0)) plan.at[0] = first_land.?;
+ values += 1;
+ }
+ if (idea and !back) {
+ // A drawing made of the bytes, or a call's node from the frame its return address made: projected once they have shown.
+ const projected = writes or reads;
+ plan.project = if (plan.pins[0] >= 0 or plan.pins[1] >= 0) t + 6 * f else plan.at[1];
+ if (projected) {
+ plan.at[2] = @max(t, plan.project + time.project.bracket + @as(f32, if (c.levels.idea == .data) time.project.draw else time.project.far) + @as(f32, if (wrote > 0 and c.levels.idea == .data) time.strike.arm else 0));
+ } else plan.at[2] = t + time.cascade;
+ t = plan.at[2];
+ follow_through = switch (c.levels.idea) {
+ .none => 0,
+ .calls => time.snap,
+ .data => c.levels.follow,
+ };
+ values += 1;
+ }
+ // The window follows, once rsp's pin has landed.
+ if (rows[0] > 0) {
+ plan.follow = t + 6 * f;
+ t = plan.follow + k.follow;
+ }
+ plan.advance = if (values > 0) t + follow_through + @min(time.read_value + time.read_more * (values - 1), time.read_most) else time.fire;
+ plan.total = plan.advance + plan.travel + time.rest;
+ return plan;
+ }
+
/// How long the mark takes to the next line: a slide by how far, or a
/// jump (out, then in) into or out of a call, further than a few rows,
/// or at the end of a continue (`wave`).
@@ -501,16 +785,7 @@ pub const Cursor = struct {
.rec = rec,
.stops = undefined,
.time = std.math.inf(f32),
- .plan = .{
- .gait = @enumFromInt(@as(u2, @intFromFloat(std.math.clamp(@round(placed.value(c.plan[0])), 0, 2)))),
- .at = .{ placed.value(c.plan[1]), placed.value(c.plan[2]), placed.value(c.plan[3]) },
- .advance = placed.value(c.plan[4]),
- .travel = placed.value(c.plan[5]),
- .total = placed.value(c.plan[6]),
- .wave = placed.value(c.plan[7]) >= 0.5,
- .fires = placed.value(c.plan[8]) >= 0.5,
- .cooling = placed.value(c.plan[9]),
- },
+ .plan = undefined,
.marks = .{ whole(rec, placed.value(c.marks[0])), whole(rec, placed.value(c.marks[1])) },
.hurried = placed.value(c.hurried),
.veil = placed.value(c.veil),
@@ -520,8 +795,12 @@ pub const Cursor = struct {
.place = 0,
.fired = c.levels.fire,
.crossings = c.levels.crossings,
+ .annotation = c.levels.annotation,
.way = .{ c.first, c.last },
};
+ var plan: [Plan.values]f32 = undefined;
+ for (&plan, c.plan) |*is, v| is.* = placed.value(v);
+ n.plan = Plan.unpack(plan);
for (&n.stops, c.stops) |*stop_at, v| stop_at.* = whole(rec, placed.value(v));
for (&n.gaits, c.gaits) |*gait, v| gait.* = @enumFromInt(@as(u2, @intFromFloat(std.math.clamp(@round(placed.value(v)), 0, 2))));
const phase = placed.value(c.phase);
@@ -586,6 +865,8 @@ pub const Now = struct {
fired: @FieldType(Levels, "fire") = .source,
/// Steps that make a syscall cross into the kernel (`Levels.crossings`).
crossings: bool = false,
+ /// The disassembly's annotation, and what goes with it (`Levels.annotation`).
+ annotation: @FieldType(Levels, "annotation") = .tied,
/// The scene's way through the recording: its first moment and its last.
way: [2]u64 = .{ 0, 0 },
@@ -927,12 +1208,48 @@ pub const Now = struct {
/// gold, and out as the mark leaves, gone before the next line fires.
pub fn reading(n: Now, level: Level, delay: f32) f32 {
return switch (n.plan.gait) {
- .walk => n.held(n.plan.at[@intFromEnum(level)] + delay),
+ // Under `tied` what a step read is framed in its own slot, before what it fills (`Plan.read`).
+ .walk => n.held((if (level == .memory and n.plan.read >= 0) n.plan.read else n.plan.at[@intFromEnum(level)]) + delay),
.run => if (n.resting()) 0 else @min(std.math.clamp(n.since(level, 0) / time.stagger, 0, 1), std.math.clamp((n.plan.total - n.time) / time.snap, 0, 1)),
.sprint => 0,
};
}
+ /// Under `tied`, rsp's (`k` 0) or rbp's (1) pin: how far (0 to 1, on
+ /// `glide`) it has travelled from where the step found it, at a walk
+ /// from `Plan.pins`, at a run over its 8 f and 2 f a row from the step's
+ /// start; 1 at rest. Null where the step does not move it so (the old
+ /// timing: a plan with no pins, a sprint, `whole`).
+ pub fn pinGone(n: Now, k: usize) ?f32 {
+ if (n.annotation != .tied) return null;
+ if (n.resting()) return 1;
+ const rows = wordsApart(n.rec, n.stops[1], n.stops[0], if (k == 0) "rsp" else "rbp");
+ if (rows == 0) return null;
+ return switch (n.plan.gait) {
+ .walk => if (n.plan.pins[k] < 0) null else glide(std.math.clamp((n.time - n.plan.pins[k]) / pinTime(rows, false), 0, 1)),
+ .run => standard(std.math.clamp(n.time / pinTime(rows, true), 0, 1)),
+ .sprint => null,
+ };
+ }
+
+ /// Seconds into a walked step when rsp's (`k` 0) or rbp's (1) pin lands: its strike.
+ pub fn pinLands(n: Now, k: usize) ?f32 {
+ if (n.annotation != .tied or n.plan.gait != .walk or n.plan.pins[k] < 0) return null;
+ return n.plan.pins[k] + pinTime(wordsApart(n.rec, n.stops[1], n.stops[0], if (k == 0) "rsp" else "rbp"), false);
+ }
+
+ /// When the stack's labels that the step changes (an offset whose base
+ /// moved, the tag's note) crossfade from, under `tied`: as the window
+ /// follows, else as the last pin lands, else with memory's strike.
+ pub fn restacked(n: Now) f32 {
+ if (n.plan.follow >= 0) return n.plan.follow;
+ var last: ?f32 = null;
+ for (0..2) |k| if (n.pinLands(k)) |l| {
+ last = @max(last orelse l, l);
+ };
+ return last orelse n.plan.at[1];
+ }
+
/// The same for a frame that comes in `from` seconds into a walked step.
pub fn held(n: Now, from: f32) f32 {
const r = time.read;
diff --git a/anim/src/descent.zig b/anim/src/descent.zig
index 5dd156c..ff478df 100644
--- a/anim/src/descent.zig
+++ b/anim/src/descent.zig
@@ -59,15 +59,32 @@ pub fn step(cur: cursors.Cursor, s: *anim.Frame, by: Recording.Stop) void {
const b = rec.insn_branches[from] orelse return cur.walk(s, by, to);
var name_buf: [256]u8 = undefined;
const here = (rec.moment(from).string(rec.register(from, "rip"), &name_buf) catch null) orelse "";
+ // `tied`: the push or the read first, as any call's or return's (the touch, the word, rsp's pin, the
+ // window following: the stack's own timetable), then the windows, 42 f (a call) or 48 f (a return) later.
+ const tied = cur.levels.annotation == .tied;
const plan: cursors.Plan = switch (b.kind) {
- .call => .{ .at = .{ f(24), f(60), f(60) }, .advance = f(138), .travel = f(12), .total = f(174) },
- .ret => .{ .at = .{ f(36), f(18), f(36) }, .advance = f(114), .travel = f(12), .total = f(150) },
+ .call => if (tied) stacked(cur, from, to, f(180), f(216)) else .{ .at = .{ f(24), f(60), f(60) }, .advance = f(138), .travel = f(12), .total = f(174) },
+ .ret => if (tied) stacked(cur, from, to, f(162), f(198)) else .{ .at = .{ f(36), f(18), f(36) }, .advance = f(114), .travel = f(12), .total = f(150) },
.jump => if (std.mem.indexOf(u8, here, "@plt") != null) .{ .at = .{ f(18), f(24), f(24) }, .advance = f(96), .travel = f(12), .total = f(132) } else return cur.walk(s, by, to),
.none => return cur.walk(s, by, to),
};
cur.step(s, to, plan, plan.total);
}
+/// The key of the head row over function `name`'s window (a `ties.Place.row`).
+pub fn headKey(name: []const u8) u64 {
+ return std.hash.Wyhash.hash(0, name) | 1 << 63;
+}
+
+/// The stack's own timetable for the step (`Cursor.planned`), its advance and its end the descent's.
+fn stacked(cur: cursors.Cursor, from: u64, to: u64, advance: f32, total: f32) cursors.Plan {
+ var plan = cur.planned(from, to, false);
+ plan.advance = advance;
+ plan.travel = f(12);
+ plan.total = total;
+ return plan;
+}
+
/// A row of the panel.
const Item = struct {
key: u64,
@@ -110,9 +127,15 @@ pub const Descent = struct {
const after = layout(u, rec, now.stops[0], room, d.root);
// On the map its box is as long as the rows it has wanted: not 69 for a function of 30.
if (ui.mapping) map.measure(.disasm, @max(before.items.len, after.items.len));
- const tm = now.time;
const going = now.advancing();
const kind: enum { same, down, through, up } = if (now.resting() or now.stops[0] == now.stops[1]) .same else if (after.windows > before.windows) (if (before.in_stub) .through else .down) else if (after.windows < before.windows) .up else .same;
+ // `tied` (a plan with the stack's own moves, `stacked`): the windows move once the stack has, 42 f later down, 48 f up.
+ const shift: f32 = if (now.plan.follow < 0) 0 else switch (kind) {
+ .down => f(42),
+ .up => f(48),
+ .same, .through => 0,
+ };
+ const tm = now.time - shift;
const shown = if (going >= 0.5) after else before;
// A tag that changes with the advance crossfades over it.
const retag = !std.mem.eql(u8, before.tag, after.tag);
@@ -268,6 +291,7 @@ pub const Descent = struct {
last_window = p.item.window;
switch (p.item.what) {
.head => |h| {
+ ties.anchor(u, .{ .row = p.item.key }, .{ .x = 0, .y = y, .w = box.w, .h = m.row });
v.fill(.{ .x = theme.stroke.rule, .y = y, .w = box.w - 2 * theme.stroke.rule, .h = theme.stroke.rule }, theme.color.rule);
v.text(.sans_medium, theme.size.sans.micro, c.address, y + 18, h.name, t.primary);
v.text(.sans, theme.size.sans.micro, map.content(box.w) - m.side - v.width(.sans, theme.size.sans.micro, h.note), y + 18, h.note, t.faint);
@@ -319,6 +343,7 @@ pub const Descent = struct {
covered = if (p.twin) @max(covered, hangs) else @max(covered -| 1, hangs);
last_line = line;
map.row(.disasm, row.addr, u, .{ .x = 0, .y = y, .w = box.w, .h = m.row });
+ if (!p.twin) ties.anchor(u, .{ .row = row.addr }, .{ .x = 0, .y = y, .w = box.w, .h = m.row });
},
}
}
@@ -348,7 +373,9 @@ pub const Descent = struct {
// Its strip is the deepest window's function's column, that window framed on it.
map.window(.disasm, deepest(after), deepest(before), cursors.glide(going));
if (pc_y[1] orelse pc_y[0]) |y| ties.anchor(u, .pc, .{ .x = 0, .y = y, .w = theme.metric.plaque.pc, .h = m.row });
- kernel(u, now, box, under orelse top + @as(f32, @floatFromInt(room -| 3)) * m.row, pc_y[0] orelse pc_y[1]);
+ const floor = under orelse top + @as(f32, @floatFromInt(room -| 3)) * m.row;
+ if (shown.kernel) ties.anchor(u, .floor, .{ .x = 0, .y = floor, .w = box.w, .h = m.row });
+ kernel(u, now, box, floor, pc_y[0] orelse pc_y[1]);
context.veiled(u, box, now.veil);
// Going down or up, the strip is another function's column: it fades through as the mark lands (24 f).
map.strip(.disasm, if (kind == .same) u else u.faded(map.through(now, now.plan.travel + f(12))), box);
@@ -513,7 +540,7 @@ fn layout(u: ui.Ui, rec: *const Recording, i: u64, room: usize, root: []const u8
row += 1;
}
if (li > 0) {
- items.append(a, .{ .key = std.hash.Wyhash.hash(0, l.name) | 1 << 63, .row = row, .window = window, .what = .{ .head = .{ .name = l.name, .note = headNote(u, rec, i, l) } } }) catch {};
+ items.append(a, .{ .key = headKey(l.name), .row = row, .window = window, .what = .{ .head = .{ .name = l.name, .note = headNote(u, rec, i, l) } } }) catch {};
row += 1;
}
const nearest = li + 2 == kept.len and l.kind == .caller;
diff --git a/anim/src/disasm.zig b/anim/src/disasm.zig
index 7017453..085982d 100644
--- a/anim/src/disasm.zig
+++ b/anim/src/disasm.zig
@@ -225,6 +225,7 @@ pub const Disasm = struct {
continue;
}
map.row(.disasm, row.addr, u, .{ .x = 0, .y = y, .w = box.w, .h = m.row });
+ ties.anchor(u, .{ .row = row.addr }, .{ .x = 0, .y = y, .w = box.w, .h = m.row });
const is_pc = row.addr == pc[if (going >= 0.5) 1 else 0];
const was = if (is_pc) null else ran[j];
if (was) |r| lit.trail(c.mark, y, r.k);
@@ -287,6 +288,12 @@ pub const Disasm = struct {
return 0;
}
if (!row.bare) _ = at.address(c.address, base_y, row.addr, .{ .ink = ui.rgb(code_ink), .lead = lead });
+ // `tied`: the row the step's touch (or carry) leaves from, its right rule, for the ties.
+ if (!ui.mapping and now.annotation == .tied and now.walking() and (now.plan.touch >= 0 or now.plan.carry >= 0)) if (touchPc(rec, now)) |pc| if (pc == row.addr) {
+ const a = at.at.xf.apply(.{ w + theme.strip.cost, y });
+ const b = at.at.xf.apply(.{ w + theme.strip.cost, y + m.row });
+ ties.touch_row = .{ a[0], a[1], b[0], b[1] };
+ };
if (first_of_line) if (line) |l| {
const num = u.print("{d}", .{l});
const now_line = l == current_line;
@@ -356,6 +363,15 @@ pub const Disasm = struct {
if (state == .ran) if (returned(rec, row, moment, now.stops[base])) |back| {
return a.said(a.cForm(row, b.to, moment, rec.register(back, "rax"), a.room - a.x), t.primary);
};
+ // `tied`: a call to the program's own function in C's form (a PLT stub's callee by name,
+ // its arguments under it), then its move of rsp, struck with rsp: `fib(4) · rsp -8`.
+ if (now.annotation == .tied and state == .current) {
+ const stub = pltName(u, rec, target(row).?).len > 0;
+ var note = if (stub) a.callee(b.to, moment) else a.said(a.cForm(row, b.to, moment, null, a.room - a.x - 10 * adv), t.primary);
+ note.end = a.move(note.end + adv, -8, a.rspHeat(now, base), null, true);
+ if (stub) note.hangs = a.arguments(row, b.to, moment);
+ return note;
+ }
var note = a.callee(b.to, moment);
// Its arguments hang under it, a small `reg` a row, as many as the prototype has.
if (state == .current) note.hangs = a.arguments(row, b.to, moment);
@@ -363,7 +379,10 @@ pub const Disasm = struct {
},
.ret => {
u.text(.mono, size, x, base_y, "\u{2192}", t.faint);
- return .{ .drawn = true, .end = u.address(x + 2 * adv, base_y, b.to, .{ .ink = ui.rgb(code_ink), .name = rec.strings.get(b.to) orelse "" }) };
+ const end = u.address(x + 2 * adv, base_y, b.to, .{ .ink = ui.rgb(code_ink), .name = rec.strings.get(b.to) orelse "" });
+ // `tied`: then its move of rsp, `· rsp +8`.
+ if (now.annotation == .tied) return .{ .drawn = true, .end = a.move(end + adv, 8, if (state == .current) a.rspHeat(now, base) else .none, null, true) };
+ return .{ .drawn = true, .end = end };
},
.jump => {
// Through memory or a register: where it goes. Straight: nothing to say.
@@ -386,6 +405,8 @@ pub const Disasm = struct {
if (std.mem.eql(u8, mn, "jmp")) if (ripSlot(row)) |slot| if ((zt.telescope.got(rec.moment(moment), slot) catch null)) |held| return a.went(held.value, .{ .addr = slot, .len = 8, .how = 1 }, moment);
return .{};
}
+ // `tied`: an instruction that moves rsp or rbp says the move first.
+ if (now.annotation == .tied) if (a.stackMove(now, row, moment, after, state, base)) |note| return note;
// A compare: the two values, then (once it has run) the flags it leaves.
if (std.mem.eql(u8, mn, "cmp") or std.mem.eql(u8, mn, "test")) {
const left = a.compared(row, moment, touches[0]);
@@ -463,6 +484,8 @@ pub const Disasm = struct {
marks.changed_heat = now.written(touch.addr, touch.len, .memory, 0);
}
};
+ // `tied`: the word by its name and the value, one hop (the stack's row holds the rest).
+ if (now.annotation == .tied) if (a.tiedWord(touch, moment, shown, marks, d.stage.first.view.h > 0 or d.stage.last().view.h > 0)) |note| return note;
// Narrower than a word, it is read at its width.
if (touch.len < 8) return .{ .drawn = true, .end = rows.narrow(u, x, y, shown, touch.addr, touch.len, room, marks).end };
return .{ .drawn = true, .end = rows.chain(u, x, y, shown, touch.addr, room, marks).end };
@@ -472,7 +495,8 @@ pub const Disasm = struct {
const at = value_at orelse return .{};
const value = rec.register(at, reg);
u.text(.mono, size, x, base_y, reg, t.dim);
- return .{ .drawn = true, .end = rows.chain(u, x + @as(f32, @floatFromInt(reg.len + 1)) * adv, y, rec.moment(at), value, room, .{}).end };
+ // `tied`: its first value (the registers' row has its chain, struck in the same frame).
+ return .{ .drawn = true, .end = rows.chain(u, x + @as(f32, @floatFromInt(reg.len + 1)) * adv, y, rec.moment(at), value, room, .{ .most = if (now.annotation == .tied) 1 else 6 }).end };
}
};
@@ -509,6 +533,155 @@ const Say = struct {
return bare[0 .. bare.len - 4];
}
+ /// rsp's mark in this step, for the amount an annotation moves it by: an echo of its strike.
+ fn rspHeat(a: Say, now: cursors.Now, base: usize) ui.Heat {
+ _ = a;
+ if (base != 1 or now.resting()) return .none;
+ // The amount is new in this row: no corner of rsp's last change under it.
+ return now.heat(now.registerAge(cursors.sp_index), null, now.since(.cpu, ties.strikeDelay(now, cursors.sp_index)));
+ }
+
+ /// `rsp -8` from `x` (after something else: `· rsp -8`): the amount
+ /// `by` (in bytes) struck with `heat`; then, `· role` faint and its
+ /// role, where the word it writes or reads has one.
+ fn move(a: Say, x: f32, by: i64, heat: ui.Heat, role: ?Role, after: bool) f32 {
+ var end = a.word(if (after) a.word(x, "\u{00b7}", t.faint) + adv else x, "rsp", t.dim);
+ const n: u64 = @abs(by);
+ const amount = if (n <= 9) a.u.print("{c}{d}", .{ @as(u8, if (by < 0) '-' else '+'), n }) else a.u.print("{c}0x{x}", .{ @as(u8, if (by < 0) '-' else '+'), n });
+ end = a.struck(end + adv, amount, heat);
+ if (role) |r| if (r.shows > 0) {
+ const v = a.u.faded(r.shows);
+ const b: Say = .{ .u = v, .rec = a.rec, .y = a.y, .x = a.x, .room = a.room };
+ end = b.word(b.word(end + adv, "\u{00b7}", t.faint) + adv, r.name, if (r.local) t.primary else t.dim);
+ };
+ return end;
+ }
+
+ /// A word's role in an annotation, and how much of it shows.
+ const Role = struct { name: []const u8, local: bool, shows: f32 = 1 };
+
+ /// `text` at `x` in primary, marked as `heat` says (armed, struck, held): where it ends.
+ fn struck(a: Say, x: f32, text: []const u8, heat: ui.Heat) f32 {
+ const w = @as(f32, @floatFromInt(text.len)) * adv;
+ var ink: ui.Ink = .{ .ink = ui.rgb(t.primary) };
+ if (a.u.written(.{ .x = x, .y = a.y, .w = w, .h = m.row }, heat)) |s| ink = s;
+ a.u.text(ink.face, size, x, rows.baseline(a.y), text, ink.ink);
+ return x + w;
+ }
+
+ /// Under `tied` (design/README.md, `insn`, "moves rsp or rbp"): the move
+ /// in its own terms, first, its amount struck with rsp's strike: `rsp -8
+ /// · saved rbp` (a `push`; its word's role once the step has made it),
+ /// `rsp +8 · saved rbp` (a `pop`), `rsp +0x20 · saved rbp` (a `leave`),
+ /// `rsp -0x18 3 words` (`sub`, `add`), `rbp = rsp` (and its value,
+ /// struck as rbp lands). Null for any other instruction.
+ fn stackMove(a: Say, now: cursors.Now, row: Insn, moment: u64, after: ?u64, state: Disasm.State, base: usize) ?Disasm.Note {
+ const mn = row.mnemonic();
+ const ops = row.operands();
+ const eql = std.mem.eql;
+ const regs = a.rec.registers[@min(moment, a.rec.end())];
+ const heat = if (state == .current) a.rspHeat(now, base) else ui.Heat.none;
+ var by: i64 = 0;
+ var touched: ?u64 = null;
+ var word_at = moment;
+ var counts = false;
+ if (eql(u8, mn, "push")) {
+ by = -8;
+ touched = regs.rsp -% 8;
+ // The word it makes has its role at the push's own stop (a recording that says so);
+ // else the moment after's, arriving with the touch.
+ if (wordName(a.u, a.rec, moment, regs.rsp -% 8, 8) == null) if (after) |aa| {
+ word_at = aa;
+ };
+ } else if (eql(u8, mn, "pop")) {
+ by = 8;
+ touched = regs.rsp;
+ } else if (eql(u8, mn, "leave")) {
+ by = @bitCast(regs.rbp +% 8 -% regs.rsp);
+ touched = regs.rbp;
+ } else if ((eql(u8, mn, "sub") or eql(u8, mn, "add")) and std.mem.startsWith(u8, ops, "rsp, ")) {
+ const n: i64 = @bitCast(parseImmediate(std.mem.trim(u8, ops[5..], " ")) orelse return null);
+ by = if (eql(u8, mn, "sub")) -n else n;
+ counts = true;
+ } else if (eql(u8, mn, "mov") and eql(u8, ops, "rbp, rsp")) {
+ var end = a.word(a.x, "rbp = rsp", t.primary);
+ // Its value once rbp has landed, struck with it.
+ const lands = ties.strikeDelay(now, cursors.bp_index);
+ const value_at: ?u64 = switch (state) {
+ .ran => after,
+ .current => if (after != null and now.landed(.cpu, lands)) after.? else null,
+ .ahead, .waiting => null,
+ };
+ if (value_at) |v| end = a.struck(end + adv, a.u.print("{x}", .{a.rec.register(v, "rbp")}), if (state == .current and base == 1) now.heat(now.registerAge(cursors.bp_index), null, now.since(.cpu, lands)) else .none);
+ return .{ .drawn = true, .end = end };
+ } else return null;
+ var role: ?Role = null;
+ if (touched) |w| if (wordName(a.u, a.rec, word_at, w, 8)) |named| {
+ role = .{ .name = named.name, .local = named.local };
+ // A push's word arrives with the touch's landing (12 f), never in a frame.
+ if (word_at != moment and state == .current and !now.resting() and now.plan.touch >= 0) role.?.shows = std.math.clamp((now.time - now.plan.touch - theme.time.tied.touch) / theme.time.quick, 0, 1);
+ };
+ var end = a.move(a.x, by, heat, role, false);
+ if (counts) end = a.word(end + 2 * adv, a.u.print("{d} words", .{@abs(by) / 8}), t.faint);
+ return .{ .drawn = true, .end = end };
+ }
+
+ /// Under `tied` (design/README.md, `insn`, and its fallbacks), a word of
+ /// memory the instruction reads or writes: a stack word by its name, bold
+ /// in the stack's ink (an unnamed one by its address), and the value it
+ /// holds at the access's width, one hop: `next → 405010`, `n ◂ 15`,
+ /// `7fffffffecd0 ◂ 1`; a word a view on screen shows (`view`), its
+ /// address and one hop, `405038 → 405010`. The name (or address) framed
+ /// as read in the step, a write's value struck. Null for a word no pane
+ /// shows: the whole chain stands.
+ fn tiedWord(a: Say, touch: Recording.Touch, moment: u64, shown: Recording.Moment, marks: rows.Marks, view: bool) ?Disasm.Note {
+ const u = a.u;
+ const region = rows.regionOf(a.rec.moment(moment), touch.addr);
+ const named = if (region == .stack) wordName(u, a.rec, moment, touch.addr, touch.len) else null;
+ // The band's view is a dump of the heap. A word no pane shows (a global) keeps its whole
+ // chain, its data name in place of the address where it has one (`head → 405050 ◂ 9`).
+ if (region != .stack and !(view and region == .heap)) return a.globalWord(touch, moment, shown, marks);
+ const base_y = rows.baseline(a.y);
+ const mid = a.y + m.row / 2;
+ var x = a.x;
+ const w = if (named) |n| @as(f32, @floatFromInt(n.name.len)) * adv else ui.Value.of(touch.addr, true).width();
+ if (marks.read == 0) u.read(.{ .x = x, .y = a.y, .w = w, .h = m.row }, marks.read_shows);
+ if (named) |n| u.text(.mono_bold, size, x, base_y, n.name, rows.ink(.stack)) else _ = u.address(x, base_y, touch.addr, .{ .ink = ui.rgb(rows.ink(region)) });
+ x += w;
+ const len: usize = @intCast(@min(touch.len, 8));
+ var raw: [8]u8 = @splat(0);
+ var known: [8]bool = @splat(false);
+ shown.read(touch.addr, raw[0..len], known[0..len]) catch return .{ .drawn = true, .end = x };
+ if (std.mem.indexOfScalar(bool, known[0..len], false) != null) {
+ x = u.arrow(x, mid, .points);
+ u.unknown(.{ .x = x, .y = a.y, .w = 24, .h = m.row });
+ return .{ .drawn = true, .end = x + 24 };
+ }
+ const v = std.mem.readInt(u64, &raw, .little);
+ const pointer = len == 8 and rows.regionOf(shown, v) != .none;
+ x = u.arrow(x, mid, if (pointer) .points else .holds);
+ // The value, its first hop alone (a code address with its name), cut with `…` where the row ends; a write's struck.
+ return .{ .drawn = true, .end = rows.chain(u, x, a.y, shown, v, a.room, .{ .first = if (marks.changed == 1) marks.changed_heat else .none, .most = 1 }).end };
+ }
+
+ /// Under `tied`, a word no pane shows: its whole chain with its data
+ /// name (`head`, `big+4096`) in place of its address, bold in its
+ /// region's ink, read in the step; a write's value struck. Null where it
+ /// has no name (the chain as `whole` draws it).
+ fn globalWord(a: Say, touch: Recording.Touch, moment: u64, shown: Recording.Moment, marks: rows.Marks) ?Disasm.Note {
+ if (touch.len != 8) return null;
+ const full_name = ui.symbol(a.u, a.rec.strings.get(touch.addr) orelse return null);
+ // `head+0` is `head`.
+ const name = if (std.mem.endsWith(u8, full_name, "+0")) full_name[0 .. full_name.len - 2] else full_name;
+ const u = a.u;
+ const w = @as(f32, @floatFromInt(name.len)) * adv;
+ if (marks.read == 0) u.read(.{ .x = a.x, .y = a.y, .w = w, .h = m.row }, marks.read_shows);
+ u.text(.mono_bold, size, a.x, rows.baseline(a.y), name, rows.ink(rows.regionOf(a.rec.moment(moment), touch.addr)));
+ const v = (Recording.word(shown, touch.addr, 8) catch null) orelse return .{ .drawn = true, .end = a.x + w };
+ const x = u.arrow(a.x + w, a.y + m.row / 2, if (rows.regionOf(shown, v) != .none) .points else .holds);
+ return .{ .drawn = true, .end = rows.chain(u, x, a.y, shown, v, a.room, .{ .first = if (marks.changed == 1) marks.changed_heat else .none }).end };
+ }
+
/// A direct call's callee, bright.
fn callee(a: Say, to: u64, moment: u64) Disasm.Note {
return .{ .drawn = true, .end = a.word(a.x, a.functionName(to, moment), t.bright) };
@@ -645,6 +818,39 @@ const Say = struct {
}
};
+/// The pc of the instruction a step's touch leaves from (`cursors.stackTouch`), kept for the step.
+var touch_memo: struct { rec: ?*const Recording = null, from: u64 = 0, to: u64 = 0, pc: ?u64 = null } = .{};
+
+fn touchPc(rec: *const Recording, now: cursors.Now) ?u64 {
+ if (touch_memo.rec != rec or touch_memo.from != now.stops[1] or touch_memo.to != now.stops[0]) {
+ const tt = cursors.stackTouch(rec, now.stops[1], now.stops[0]);
+ touch_memo = .{ .rec = rec, .from = now.stops[1], .to = now.stops[0], .pc = if (tt) |x| rec.register(x.at, "rip") else null };
+ }
+ return touch_memo.pc;
+}
+
+/// A stack word's name under `tied`, its role at moment `i` (a local's
+/// name, primary; `saved rbp`, `argv[0]`, dim), for an access of `len`
+/// bytes at `addr`; null where it has none, or where the local the word is
+/// named by does not hold those bytes (two locals in a word: never a guess).
+fn wordName(u: ui.Ui, rec: *const Recording, i: u64, addr: u64, len: u64) ?struct { name: []const u8, local: bool } {
+ const regs = rec.registers[@min(i, rec.end())];
+ var one: [1]zt.telescope.Slot = undefined;
+ const word = addr & ~@as(u64, 7);
+ const got = zt.telescope.slots(rec.moment(i), &regs, word, &one) catch return null;
+ if (got.len == 0) return null;
+ return switch (got[0].role) {
+ .none, .return_address => null,
+ // Of the locals that share the word (`Slot.also`), the one the access is to.
+ .local => |first| for ([_]?zt.telescope.Local{first} ++ got[0].also) |maybe| {
+ const l = maybe orelse continue;
+ const at = word -% @as(u64, @bitCast(@as(i64, l.offset)));
+ if (if (l.size > 0) addr >= at and addr + len <= at + l.size else addr == at) break .{ .name = l.name, .local = true };
+ } else null,
+ else => |role| .{ .name = context.Stack.roleName(u, role, (Recording.word(rec.moment(i), addr & ~@as(u64, 7), 8) catch null) orelse 1).name, .local = false },
+ };
+}
+
/// How many rows of arguments hang under `row` while it is current at
/// `moment`: a direct call's, a `syscall`'s; 0 for anything else.
pub fn hanging(u: ui.Ui, rec: *const Recording, row: Insn, moment: u64) usize {
diff --git a/anim/src/graph.zig b/anim/src/graph.zig
index 7066580..01b4ac7 100644
--- a/anim/src/graph.zig
+++ b/anim/src/graph.zig
@@ -1942,6 +1942,7 @@ fn drawPills(u: ui.Ui, v: Instant) void {
}
const o = u.faded(shows);
const r: ui.Rect = .{ .x = x, .y = y, .w = n.w, .h = n.h };
+ @import("ties.zig").anchor(u, .{ .block = n.start }, r);
const base_y = rows.baseline(y);
if (n.folded > 0) {
pill(o, r, ui.rgb(theme.color.page), ui.rgb(theme.color.rule), theme.stroke.rule, true);
@@ -2023,7 +2024,9 @@ pub const Blocks = struct {
defer u.unclip();
const now = b.cursor.now(placed);
const rule = theme.stroke.rule;
- const room: [2]f32 = .{ box.w - 2 * rule, box.h - m.tag - rule };
+ // Drawn larger (a column's drawing across both columns): laid out in its room at its own size, then scaled.
+ const z = placed.value(b.stage.zoom);
+ const room: [2]f32 = .{ (box.w - 2 * rule) / z, (box.h - m.tag - rule) / z };
const v = instant(f.scratch, now, b.form, room) orelse {
_ = u.panel(box.w, box.h, "its blocks", .{ .focus = b.focus });
return;
@@ -2033,8 +2036,11 @@ pub const Blocks = struct {
const short = name[0 .. std.mem.lastIndexOfScalar(u8, name, '+') orelse name.len];
const title = if (std.mem.indexOfScalar(u8, full, '!')) |bang| u.print("the blocks of {s} \u{00b7} {s}", .{ short, full[0..bang] }) else u.print("the blocks of {s}", .{short});
_ = u.panel(box.w, box.h, title, .{ .focus = b.focus, .note = if (v.g.rings.len > 0) "its blocks \u{00b7} the visits so far \u{00b7} the path \u{00b7} the loops' turns" else "its blocks \u{00b7} the visits so far \u{00b7} the path" });
- u.clip(.{ .x = rule, .y = m.tag, .w = room[0], .h = room[1] });
- const o = u.moved(rule + v.at[0], m.tag + v.at[1]);
+ u.clip(.{ .x = rule, .y = m.tag, .w = room[0] * z, .h = room[1] * z });
+ var big = u.moved(rule, m.tag);
+ big.at.xf = big.at.xf.mul(.scale(z, z));
+ big.at.scale *= z;
+ const o = big.moved(v.at[0], v.at[1]);
drawEdges(o, v);
drawTurns(o, v);
drawPills(o, v);
diff --git a/anim/src/root.zig b/anim/src/root.zig
index dca9a60..fcdb572 100644
--- a/anim/src/root.zig
+++ b/anim/src/root.zig
@@ -63,6 +63,14 @@ pub const Caption = words.Caption;
pub const Label = words.Label;
pub const Veil = words.Veil;
pub const Legend = words.Legend;
+/// The column (design/README.md, "column (an experiment)"): beat by beat,
+/// the panes a beat is about on the left, its text beside them, the rest
+/// folded to their tags on the shelf (`column.zig`).
+const columns = @import("column.zig");
+pub const Column = columns.Column;
+pub const column = columns.column;
+/// A column pane's rows: what the column has left.
+pub const column_rest = columns.rest;
/// The page behind every scene: `pub const background = canim.background;`.
pub const background: u32 = theme.color.page;
@@ -334,7 +342,7 @@ pub fn context(s: *anim.Frame, cursor_: Cursor, options: Context.Options) Contex
.registers = add(s, Registers{ .cursor = at, .stage = stage, .syscalls = options.syscalls, .quiet = options.quiet, .moves = moves }),
.stack = add(s, Stack{ .cursor = at, .stage = stage }),
.backtrace = add(s, Backtrace{ .cursor = at, .stage = stage, .lens = options.backtrace }),
- .clock = add(s, Clock{ .cursor = at, .map = whole }),
+ .clock = add(s, Clock{ .cursor = at, .map = whole, .stage = stage }),
};
}
@@ -407,4 +415,5 @@ test {
_ = @import("syscalls.zig");
_ = objects;
_ = words;
+ _ = columns;
}
diff --git a/anim/src/rows.zig b/anim/src/rows.zig
index 03c5898..08f1fb2 100644
--- a/anim/src/rows.zig
+++ b/anim/src/rows.zig
@@ -59,6 +59,8 @@ pub const Marks = struct {
/// How much the hops after the first show: they fade out as the memory
/// they read is about to change (`Now.following`).
hops: f32 = 1,
+ /// How many hops at most: a `tied` annotation's register is its first value (`rax 405010`).
+ most: usize = 6,
};
/// `chain` of a memory access narrower than a word: its address, then what
@@ -117,7 +119,7 @@ pub fn chain(u: ui.Ui, x: f32, y: f32, moment: Recording.Moment, value: u64, roo
const mid = y + row_h / 2;
var hops: Hops = .{};
var at = x;
- for (links, 0..) |link, i| {
+ for (links[0..@min(links.len, marks.most)], 0..) |link, i| {
const pointer = link.region != .none;
const shown = ui.Value.of(link.value, pointer);
const w = shown.width();
@@ -278,7 +280,7 @@ fn ripFlag(u: ui.Ui, x: f32, y: f32, flag: Flag, set: bool) void {
}
/// A slot's role as it was before the step, and how far (0 to 1) the role it has now has come in over it.
-pub const Role = struct { name: []const u8, local: bool = false, going: f32 = 1, from_rsp: ?i64 = null };
+pub const Role = struct { name: []const u8, local: bool = false, going: f32 = 1, from_rsp: ?i64 = null, offset_going: ?f32 = null };
/// `slot`: a word of the stack: a lane to 112 for `row` pins (`pins`, the
/// registers that hold its address); its offset from rsp (`from_rsp`
@@ -292,9 +294,9 @@ pub fn slot(u: ui.Ui, y: f32, w: f32, moment: Recording.Moment, addr: u64, from_
const s = theme.metric.slot;
if (pins.len > 0 and pin_shows > 0) u.faded(pin_shows).pinRow(s.lane, y, pins, theme.color.region.stack);
// An offset that changes with rsp (the window held, or moved by more than the slide) crossfades as a role does.
- if (was) |o| if (o.from_rsp) |old| if (old != from_rsp and o.going < 1) {
- offset(u.faded(1 - o.going), y, old);
- offset(u.faded(o.going), y, from_rsp);
+ if (was) |o| if (o.from_rsp) |old| if (old != from_rsp and (o.offset_going orelse o.going) < 1) {
+ offset(u.faded(1 - (o.offset_going orelse o.going)), y, old);
+ offset(u.faded(o.offset_going orelse o.going), y, from_rsp);
} else offset(u, y, from_rsp) else offset(u, y, from_rsp) else offset(u, y, from_rsp);
var lead = marks;
lead.first = .none;
@@ -333,10 +335,14 @@ fn offset(u: ui.Ui, y: f32, from_rsp: i64) void {
/// `slot` `free`: a word above rsp the stack has not reached, shown while
/// the window is held for the camera: its offset, its address at 60%, its
/// word faint, no chain, no pin.
-pub fn free(u: ui.Ui, y: f32, moment: Recording.Moment, addr: u64, from_rsp: i64, lead: usize) void {
+pub fn free(u: ui.Ui, y: f32, moment: Recording.Moment, addr: u64, from_rsp: i64, lead: usize, was: ?Role) void {
const s = theme.metric.slot;
const base = baseline(y);
- offset(u, y, from_rsp);
+ // An offset whose base the step moves crossfades, as a slot's does.
+ if (was) |o| if (o.from_rsp) |old| if (old != from_rsp and o.going < 1) {
+ offset(u.faded(1 - o.going), y, old);
+ offset(u.faded(o.going), y, from_rsp);
+ } else offset(u, y, from_rsp) else offset(u, y, from_rsp) else offset(u, y, from_rsp);
const end = u.address(s.address, base, addr, .{ .ink = ui.mix(theme.color.region.stack, theme.color.page, theme.metric.context.lead_alpha), .lead = lead });
const word = (Recording.word(moment, addr, 8) catch null) orelse return u.unknown(.{ .x = end + m.arrow_w, .y = y, .w = 24, .h = row_h });
u.text(.mono, size, end + m.arrow_w, base, u.print("{x}", .{word}), t.faint);
diff --git a/anim/src/stage.zig b/anim/src/stage.zig
index a03c8bd..bbf5887 100644
--- a/anim/src/stage.zig
+++ b/anim/src/stage.zig
@@ -14,7 +14,7 @@ pub const Part = enum { band, view, source, disasm, registers, stack, backtrace,
pub const Stage = struct {
first: Split,
- moves: [8]Move = undefined,
+ moves: [32]Move = undefined,
count: usize = 0,
/// Seconds into the band's lens rising from its bytes (`Context.establish`,
/// `ties.rise`); far past it, for a scene that does not raise one.
@@ -31,12 +31,26 @@ pub const Stage = struct {
hold_in: anim.Value,
/// The registers panel's rows (the scene's, `layout.fit`): every split it changes to keeps them. 0: as the split has it.
registers_rows: f32 = 0,
+ /// 0 the working frame, 1 the column (`column.zig`): the clock under the text column.
+ column: anim.Value,
+ /// How much larger the band's drawing is drawn than its lens's size (a
+ /// column's `on`, `above`: the drawing across both columns), its tag not.
+ zoom: anim.Value,
const Move = struct { from: Split, to: Split, p: anim.Value };
/// A stage at `split`, made where a scene's components can keep a pointer to it.
pub fn init(s: *anim.Frame, split: Split) *Stage {
- return s.new(Stage{ .first = split, .rise = s.value(std.math.floatMax(f32)), .drawing = s.value(1), .view = s.value(1), .hold = s.value(-1), .hold_free = s.value(0), .hold_in = s.value(0) });
+ return s.new(Stage{ .first = split, .rise = s.value(std.math.floatMax(f32)), .drawing = s.value(1), .view = s.value(1), .hold = s.value(-1), .hold_free = s.value(0), .hold_in = s.value(0), .column = s.value(0), .zoom = s.value(1) });
+ }
+
+ /// Every panel to its box in `to`, as it is (no fit), over `seconds` on
+ /// `glide`, the drawing not faded: the column's moves (`column.zig`).
+ pub fn glide(st: *Stage, s: *anim.Frame, to: Split, seconds: f32) void {
+ const p = s.value(0);
+ st.moves[st.count] = .{ .from = st.last(), .to = to, .p = p };
+ st.count += 1;
+ s.play(.{p.to(1)}, .{ .seconds = seconds, .ease = anim.ease.linear });
}
/// The split the stage ends in, after every move so far.
diff --git a/anim/src/theme.zig b/anim/src/theme.zig
index 8d4b044..90ad36b 100644
--- a/anim/src/theme.zig
+++ b/anim/src/theme.zig
@@ -767,6 +767,8 @@ pub const metric = struct {
pub const tie = struct {
pub const thread_x = 54;
pub const link_lane = 950;
+ /// The `touch`'s, from a row of the disassembly to a word of the stack.
+ pub const touch_lane = 956;
pub const projection_lane = 962;
pub const radius = 8;
pub const projection_radius = 6;
@@ -1034,6 +1036,24 @@ pub const time = struct {
pub const out = 0.20;
pub const names = 0.20;
};
+ /// Under `tied` (design/README.md, `touch`, `carry`, `travel`,
+ /// `follow`): the touch draws `touch` (`touch_long` past six rows); the
+ /// carry `carry` (`carry_long` past eight); rsp's and rbp's pins travel
+ /// `stack_pin` to the next row and `stack_pin_row` a further one,
+ /// `stack_pin_most` at most (at a run `run_ease`, 2 f a row, `run_pin_most`);
+ /// the window follows `follow`, 2 f a further slot, `follow_most` at most.
+ pub const tied = struct {
+ pub const touch = 0.20;
+ pub const touch_long = 0.30;
+ pub const carry = 0.30;
+ pub const carry_long = 0.40;
+ pub const stack_pin = 0.40;
+ pub const stack_pin_row = 0.10;
+ pub const stack_pin_most = 0.80;
+ pub const run_pin_most = 16.0 / 60.0;
+ pub const follow = 0.40;
+ pub const follow_most = 0.60;
+ };
/// `leave` (and `turn`, round a ring's foot): the jump fires; the
/// compare's chips framed as read from `chips` (the CPU's slot); the
/// edge it takes drawn gold over `edge`, ending as the mark sets off at
diff --git a/anim/src/ties.zig b/anim/src/ties.zig
index 58ada36..1b6a6ed 100644
--- a/anim/src/ties.zig
+++ b/anim/src/ties.zig
@@ -25,6 +25,7 @@ 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 theme = ui.theme;
const time = theme.time;
@@ -55,6 +56,13 @@ pub const Place = union(enum) {
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,
fn key(p: Place) u64 {
const low = (1 << 56) - 1;
@@ -72,6 +80,9 @@ pub const Place = union(enum) {
.pc => 11 << 56,
.run => |k| 12 << 56 | @as(u64, k),
.dump_pin => |a| 13 << 56 | (a & low),
+ .row => |a| 14 << 56 | (a & low),
+ .floor => 15 << 56,
+ .block => |a| 16 << 56 | (a & low),
};
}
};
@@ -80,6 +91,10 @@ pub const Place = union(enum) {
/// 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 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`).
+pub var 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.
pub var thread_waits = false;
@@ -110,10 +125,15 @@ pub fn find(place: Place) ?[4]f32 {
/// 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;
@@ -188,6 +208,7 @@ pub const Ties = struct {
defer said = 0;
defer stack_window = null;
defer thread_waits = false;
+ defer touch_row = null;
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;
@@ -200,8 +221,107 @@ pub const Ties = struct {
if (g.threaded) thread(raw.faded(@import("context.zig").thread_shows), at, k);
if (g.beat) |b| named(raw, at, now, k, split, b);
if (!now.walking()) return;
- if (!g.quiet) g.link(raw, at, now, k, split);
- g.projection(raw, at, now, k, split);
+ const linked = !g.quiet and g.link(raw, at, now, k, split);
+ const projected = g.projection(raw, at, now, k, split);
+ // Three lines at most: the touch is the first to give way (to an echo), where a step draws a link and a projection.
+ if (!(linked and projected)) g.touch(raw, at, now, k, split);
+ g.carry(raw, at, now, k);
+ }
+
+ /// `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(g: *const Ties, raw: ui.Ui, at: anim.Placed, now: cursors.Now, k: f32, split: theme.layout.Split) void {
+ if (now.plan.touch < 0 or now.time < now.plan.touch) return;
+ const row = touch_row orelse return;
+ const tt = cursors.stackTouch(g.cursor.rec, now.stops[1], now.stops[0]) orelse return;
+ const word = find(.{ .word = tt.addr & ~@as(u64, 7) }) orelse return;
+ const lane_pin = find(.{ .slot_pin = tt.addr & ~@as(u64, 7) }) orelse return;
+ const lane = 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 at.xf.apply(.{ split.stack.x + 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 !tt.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 (tt.write) .write else .read).solid;
+ 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(g: *const Ties, raw: ui.Ui, at: anim.Placed, now: cursors.Now, k: f32) void {
+ if (now.plan.carry < 0) return;
+ const rec = g.cursor.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 = find(.{ .register = i }) orelse return;
+ const panel = find(.registers) orelse return;
+ const word = find(.{ .word = tt.addr & ~@as(u64, 7) }) orelse return;
+ const lane_pin = 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 gold thread: the current line and its instructions, one mark.
@@ -225,20 +345,23 @@ pub const Ties = struct {
/// 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(g: *const Ties, raw: ui.Ui, at: anim.Placed, now: cursors.Now, k: f32, split: theme.layout.Split) void {
+ fn link(g: *const Ties, raw: ui.Ui, at: anim.Placed, now: cursors.Now, k: f32, split: theme.layout.Split) bool {
const rec = g.cursor.rec;
- const regs = (now.moment().regs(rec.tid) catch null) orelse return;
+ const regs = (now.moment().regs(rec.tid) catch null) orelse return false;
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;
+ // `tied`: rbp's move is its pin's flight in the stack's lane, not a link.
+ if (i == cursors.bp_index and now.pinGone(1) != null) continue;
const value = regs.named(name) orelse continue;
const since = linkSince(now, i);
const l = time.link;
const node = find(.{ .node_pin = value }) != null;
const drawn = cursors.standard(std.math.clamp((since - l.after) / linkTime(if (node) .node else .slot), 0, 1));
const back = std.math.clamp((now.time - now.plan.advance) / l.out, 0, 1);
- if (linkTo(raw, at, now, k, split, name, value, drawn, back)) return;
+ if (linkTo(raw, at, now, k, split, name, value, drawn, back)) return true;
}
+ return false;
}
/// A link from register `name` to what it points at (`value`): a node's
@@ -340,7 +463,7 @@ pub const Ties = struct {
/// 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 {
+ fn projection(g: *const Ties, raw: ui.Ui, at: anim.Placed, now: cursors.Now, k: f32, split: theme.layout.Split) bool {
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 },
@@ -360,11 +483,12 @@ pub const Ties = struct {
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);
+ // 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;
+ if (bracket <= 0 or out <= 0) return true;
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 };
@@ -386,7 +510,7 @@ pub const Ties = struct {
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;
+ return true;
}
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];
@@ -397,8 +521,9 @@ pub const Ties = struct {
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;
+ return true;
};
+ return false;
}
};
diff --git a/anim/src/words.zig b/anim/src/words.zig
index 5411385..6549dfb 100644
--- a/anim/src/words.zig
+++ b/anim/src/words.zig
@@ -24,17 +24,26 @@ pub const Clock = struct {
box: Rect = .{ .x = theme.canvas.stage.x, .y = theme.canvas.clock_y - 12, .w = theme.canvas.stage.w, .h = 24 },
/// The map: with `CANIM_MAP`, drawn over everything (`Map.wholeMap`).
map: ?*const @import("map.zig").Map = null,
+ /// The stage: in the column (`Stage.column`) the clock is under the text column alone.
+ stage: ?*const @import("stage.zig").Stage = null,
pub fn draw(k: *const Clock, f: *sk.Frame, at: anim.Placed) void {
const u = fixed(f, at, 0);
const c = theme.canvas;
const now = k.cursor.now(at);
- const stage = c.stage;
- // The margins are the page's, whatever the camera has brought under them.
- u.fill(.{ .x = -c.width, .y = -c.height, .w = 3 * c.width, .h = c.height + stage.y }, theme.color.page);
- u.fill(.{ .x = -c.width, .y = stage.y + stage.h, .w = 3 * c.width, .h = 2 * c.height }, theme.color.page);
- u.fill(.{ .x = -c.width, .y = 0, .w = c.width + stage.x - 8, .h = c.height }, theme.color.page);
- u.fill(.{ .x = stage.x + stage.w + 8, .y = 0, .w = c.width, .h = c.height }, theme.color.page);
+ const in_column = if (k.stage) |st| at.value(st.column) else 0;
+ const whole = c.stage;
+ // The margins are the page's, whatever the camera has brought under them
+ // (in the column the panes run on under the floor, 888 to 1032).
+ u.fill(.{ .x = -c.width, .y = -c.height, .w = 3 * c.width, .h = c.height + whole.y }, theme.color.page);
+ const floor_x: f32 = if (in_column > 0) theme.layout.state.x - c.gutter / 2 else -c.width;
+ u.fill(.{ .x = floor_x, .y = whole.y + whole.h, .w = 3 * c.width, .h = 2 * c.height }, theme.color.page);
+ u.fill(.{ .x = -c.width, .y = 0, .w = c.width + whole.x - 8, .h = c.height }, theme.color.page);
+ u.fill(.{ .x = whole.x + whole.w + 8, .y = 0, .w = c.width, .h = c.height }, theme.color.page);
+ // The rule: the stage's width, or the text column's.
+ var stage = whole;
+ stage.x = std.math.lerp(whole.x, theme.layout.state.x, theme.ease(.glide, in_column));
+ stage.w = whole.x + whole.w - stage.x;
u.fill(.{ .x = stage.x, .y = c.clock_y - 1, .w = stage.w, .h = theme.stroke.rule }, theme.color.rule);
// Time itself: still while a step plays at a walk or a run; once its
// mark has landed, the step's piece fades in (12 f, 8 at a run) and