//! The cursor: where in the recording the picture is, as numbers on the //! scene's timeline. It moves in steps, each from one moment straight to a //! later one (the next instruction, the next source line, the line after a //! call returns, the next syscall: `Recording.Stop`), and remembers the //! last few places it stopped. //! //! A step is a sentence (design/motion.md): the line about to run fires; //! what it did lands a level at a time, the CPU, then memory, then the idea //! drawn from them, each armed and then struck; it is held to be read; and //! last the current mark moves on. The cursor writes that timetable (a //! `Plan`) for each step from what the step changed, so a walk has the //! program's rhythm and not a clock's, and every component reads it //! (`Cursor.now`) with no state of its own. const std = @import("std"); const anim = @import("anim"); const zt = @import("ztrace"); const Recording = @import("Recording.zig"); const ui = @import("ui.zig"); const syscalls = @import("syscalls.zig"); const theme = ui.theme; const time = theme.time; /// The writes of one step strike this far apart, in the order they happened. pub const write_apart = 6.0 / 60.0; /// A mark lasts this many steps, then one more to leave in. const history = time.strike.ember_steps + 2; /// Slow in and slow out, for things with weight: a value in flight, a /// layout, a colour cooling. Quickest at the middle. pub fn glide(t: f32) f32 { return theme.ease(.glide, t); } /// For things that answer the program (the mark, cards, tags, an arrow /// growing): off promptly, a long settle. pub fn standard(t: f32) f32 { return theme.ease(.standard, t); } /// The levels a step's effects land on, in the order they are caused. pub const Level = enum(u2) { cpu, memory, idea }; /// What is on screen for the cursor to time a step by. A level the scene /// does not show gives up its place in the cascade. pub const Levels = struct { cpu: bool = true, memory: bool = true, /// The idea drawn from them, when one is shown: the calls (cards, a /// tree), or the data (nodes, an array's cells). idea: enum { none, calls, data } = .none, /// Follow-through: seconds the data's view goes on moving after its /// strike (an arrow redrawn, a tag sliding), before the hold begins. follow: f32 = 0, /// Where a step fires: on the source line, or (a scene that steps by /// instruction) on the pc's row of the disassembly. One place: two /// views of the same thing start together, and only one of them pulses. fire: enum { source, disasm } = .source, /// How many lines the source panel shows (the split's): a step that /// takes the program out of its window has the window's glide to wait for. source_rows: u32 = 12, /// A step that makes one syscall is drawn as its crossing (the context /// 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 /// structures eased, values as embers. Sprint: structures grow, embers. pub const Gait = enum(u2) { walk, run, sprint }; /// A step's timetable, in seconds from its first frame. pub const Plan = struct { gait: Gait = .walk, /// When each level strikes (`Level` is the index). at: [3]f32 = @splat(time.cascade), /// When the mark sets off for the next line, and how long it takes. advance: f32 = time.fire, travel: f32 = time.step, /// The whole step: the advance, then a rest in which the next line is read. total: f32 = time.fire + time.step + time.rest, /// A `continue`: the registers strike in a wave, no arm and no pulse. wave: bool = false, /// The line fires (not on a step that goes on from the last one's /// mark: a crossing stepped over, from its call row). fires: bool = true, /// Seconds of the step before's cool still to run at this one's start /// (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`. pub fn running(seconds: f32) Plan { return .{ .gait = .run, .at = .{ 0, time.stagger, 2 * time.stagger }, .advance = time.run_ease, .travel = time.run_ease, .total = seconds }; } /// The mark, seen only where a phrase ends, moves over the step there: never in a frame. pub fn sprinting(seconds: f32) Plan { return .{ .gait = .sprint, .at = @splat(0), .advance = 0, .travel = seconds, .total = seconds }; } }; /// Registers whose change is no value to read: where execution is, and the flags. pub const quiet: u32 = blk: { var mask: u32 = 0; for (zt.Regs.names, 0..) |name, i| { if (std.mem.eql(u8, name, "rip") or std.mem.eql(u8, name, "eflags")) mask |= 1 << i; } 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. stops: [history]anim.Value, /// The pace each of those steps was taken at (`Gait`): what a run /// changed is not marked, then or after. 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.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 /// cannot be read at that pace is veiled. hurried: anim.Value, veil: anim.Value, /// The veil over what a sprint also cannot show: the source and the band's view. sprint_veil: anim.Value, /// Steps taken. count: anim.Value, /// The same values a little behind (`time.minimap_lag`, then a frame /// later each, `time.minimap_fade` of them): what the minimap draws /// from, secondary action that never starts on a primary onset's frame /// and fades over those frames. lags: [time.minimap_fade]Lagged, /// The levels the scene shows: set before the first step. levels: Levels = .{}, /// The scene's whole way, for the head's progress line and counter (`journey`). first: u64, last: u64, of: u32 = 0, /// The stops the clock counts its way in (`journey`). by: Recording.Stop = .moment, /// A cursor at rest at moment `start`. pub fn init(s: *anim.Frame, rec: *Recording, start: u64) Cursor { const here: f32 = @floatFromInt(start); const plan: Plan = .{}; var c: Cursor = .{ .rec = rec, .stops = undefined, .gaits = undefined, .phase = s.value(1), .plan = undefined, .marks = .{ s.value(here), s.value(here) }, .hurried = s.value(0), .veil = s.value(0), .sprint_veil = s.value(0), .count = s.value(0), .lags = undefined, .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); for (&c.lags) |*lag| inline for (@typeInfo(Lagged).@"struct".field_names) |name| { const from = @field(c, name); if (@TypeOf(from) == anim.Value) { @field(lag, name) = s.value(s.get(from)); } else for (&@field(lag, name), from) |*to, one| { to.* = s.value(s.get(one)); } }; return c; } /// The cursor's animated values, mirrored for the minimap. pub const Lagged = struct { stops: [history]anim.Value, gaits: [history]anim.Value, phase: anim.Value, plan: [Plan.values]anim.Value, marks: [2]anim.Value, hurried: anim.Value, veil: anim.Value, sprint_veil: anim.Value, count: anim.Value, }; /// Plays `plays(values)` on the cursor's values from here, and on their /// lagging mirrors `time.minimap_lag` later and a frame apart; the cursor ends where the first left it. fn both(c: Cursor, s: *anim.Frame, plays: anytype) void { const start = s.cursor; for (0..c.lags.len) |k| { s.cursor = start + time.minimap_lag + @as(f32, @floatFromInt(k)) / 60.0; plays.run(s, lagged(c, k)); } s.cursor = start; plays.run(s, c); } /// `c` with its `k`th lagging values in place of its own. fn lagged(c: Cursor, k: usize) Cursor { var out = c; inline for (@typeInfo(Lagged).@"struct".field_names) |name| @field(out, name) = @field(c.lags[k], name); return out; } /// `values` (a frame's every value, a copy) with the cursor's own as its /// `k`th lagging mirror has them: what the minimap's `k`th drawing reads. /// Returns whether they differ from the mirror before's (a drawing to make, not one to reuse). pub fn lagInto(c: Cursor, values: []f32, k: usize) bool { var differs = k == 0; inline for (@typeInfo(Lagged).@"struct".field_names) |name| { const own = @field(c, name); const mirror = @field(c.lags[k], name); const before = @field(c.lags[k -| 1], name); if (@TypeOf(own) == anim.Value) { values[@backingInt(own)] = values[@backingInt(mirror)]; differs = differs or values[@backingInt(mirror)] != values[@backingInt(before)]; } else for (own, mirror, before) |o, mv, b| { values[@backingInt(o)] = values[@backingInt(mv)]; differs = differs or values[@backingInt(mv)] != values[@backingInt(b)]; } } return differs; } /// Where the timeline has taken the cursor so far: for scene code that /// finds the next place from the last. pub fn moment(c: Cursor, s: *const anim.Frame) u64 { return @intFromFloat(settled(s, c.stops[0])); } /// Tells the cursor how far the scene will take it, in steps of `by`: /// what the head's progress line and step counter are measured against. pub fn journey(c: *Cursor, by: Recording.Stop, until: u64) void { c.last = until; c.by = by; c.of = c.steps(by, c.first, until); } /// How many steps of `by` from `from` to `until`. pub fn steps(c: Cursor, by: Recording.Stop, from: u64, until: u64) u32 { var n: u32 = 0; var here = from; while (here < until) : (n += 1) here = @min(c.rec.next(by, here), until); return n; } /// One step, straight to moment `to`, drawn as `plan` says and played /// in `seconds` (a plan played in less than its `total` is the same /// sentence said faster). pub fn step(c: Cursor, s: *anim.Frame, to: u64, plan: Plan, seconds: f32) void { const from = c.moment(s); // Where each value goes, from the cursor's own (the mirror goes the same way, later). const Step = struct { stops: [history]f32, gaits: [history]f32, plan: [Plan.values]f32, marks: [2]f32, count: f32, seconds: f32, fn run(st: @This(), sf: *anim.Frame, v: Cursor) void { 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 + n_plan + 4 + i] = value.to(is); for (v.plan, st.plan, history..) |value, is, n| set[n] = value.to(is); 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 = 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)); for (1..history) |i| st.gaits[i] = settled(s, c.gaits[i - 1]); // At a sprint the mark is seen only where a phrase ends. const was = settled(s, c.marks[1]); st.marks = .{ was, if (plan.gait == .sprint and !c.phraseEnds(from, to)) was else @floatFromInt(to) }; c.both(s, st); } /// Steps of `by` up to moment `until`, each shown in full and as long /// as what it changed takes to read (`reading`), with a beat's rest /// where a phrase ends. For the first time anything happens, and /// whatever the narration names. pub fn walk(c: Cursor, s: *anim.Frame, by: Recording.Stop, until: u64) void { var here = c.moment(s); while (here < until) { const next = @min(c.rec.next(by, here), until); const plan = c.reading(here, next); c.step(s, next, plan, plan.total); if (c.phraseEnds(here, next)) s.wait(time.phrase_rest); here = next; } } /// Timing: the timetable a walked step from `from` to `to` deserves. /// Fire; a slot of the cascade for each level it touched; the idea's /// follow-through; a hold as long as the values take to read; the /// advance; a rest. A line and no more comes to 0.8 s, one value to /// 1.5, a register and memory to 2.0, a call through three levels 2.5. pub fn reading(c: Cursor, from: u64, to: u64) Plan { return c.timetable(from, to, false); } /// The timetable a step from `from` to `to` gets walked (`wave`: as a `continue`), for a scene that adds a beat to it. pub fn planned(c: Cursor, from: u64, to: u64, wave: bool) Plan { return c.timetable(from, to, wave); } /// `continue`: straight to a stop far from this one (a breakpoint, not /// a step). The line it leaves fires; the registers it changed strike /// in a wave, 2 f apart in pwndbg's order, the fill in over 6 f, no arm /// and no pulse (a dozen arms at once are a crowd, a dozen pulses a /// flash); memory 18 f after the last of them (the stack's window /// scrolls or fades to its place, the backtrace's frames leave, slide /// and arrive), then the idea; a hold of 36 f after the last strike; /// the advance, the mark out and in (6 f each), the source fading /// through first if it goes farther than its window; a rest. pub fn @"continue"(c: Cursor, s: *anim.Frame, to: u64) void { const plan = c.timetable(c.moment(s), to, true); c.step(s, to, plan, plan.total); } 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. 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)); // As many strikes as writes take a place (`takesPlace`): the last is 6 f a write after the first. const wrote: f32 = @floatFromInt(if (wrote_n > 0) @max(strikes_n, 1) else 0); const touched = wrote_n > 0 or read_n > 0; const deeper = rec.depths[to] > rec.depths[from]; const back = rec.depths[to] < rec.depths[from]; const levels = [3]bool{ c.levels.cpu and regs > 0, c.levels.memory and touched, switch (c.levels.idea) { .none => false, .calls => deeper or back, .data => touched, }, }; var plan: Plan = .{ .travel = c.travel(from, to, wave), .wave = wave }; var slot: f32 = 0; for (levels, &plan.at, 0..) |is, *strikes, level| { // A drawing made of the bytes reacts when the projection from // them arrives: its bracket and its line after their strike, and // for a write its own arm. const projected = level == 2 and is and levels[1] and (c.levels.idea == .data or deeper); if (projected) slot += 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 if (is) slot += time.cascade; strikes.* = @max(slot, time.cascade); // A wave's last register strikes 2 f a register after its first, // a cascade's 6 f (the fourth and on with the third): the next level is 18 f after that. if (level == 0 and is) slot += if (wave) (regs - 1) * time.continue_wave else @min(regs - 1, 3) * write_apart; } // The writes of one step strike 6 f apart: the last is later. if (levels[1]) slot += @min(@max(wrote - 1, 0), 3) * write_apart; if (slot > 0) { // What there is to read: a level's worth each. (In the whole // context a line changes more registers than anyone reads; // the hold is for the one the scene is about.) var values: f32 = 0; for (levels) |is| values += @floatFromInt(@intFromBool(is)); // A card leaves after its result is read; an arrow lands after its word strikes. const follow: f32 = if (!levels[2]) 0 else switch (c.levels.idea) { .none => 0, .calls => if (back) time.returning else time.snap, .data => c.levels.follow, }; // A continue's hold is 36 f: what it changed is too much to read value by value. plan.advance = slot + follow + if (wave) time.read_value else @min(time.read_value + time.read_more * (values - 1), time.read_most); } plan.total = plan.advance + plan.travel + time.rest; 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`). fn travel(c: Cursor, from: u64, to: u64, wave: bool) f32 { const rec = c.rec; const a = rec.shown[from]; const b = rec.shown[to]; // Another file: the source fades through (12 f out, 12 f in). if (a.src != b.src) return time.move; // The source's window moves with it: by whole lines, and never a cut; // farther than its own height, its strip shows where it goes first // (the window gliding there, 24 f), then the pane fades through. const fit = c.levels.source_rows; const windows = [2]u32{ rec.shownFirst(fit, a), rec.shownFirst(fit, b) }; // In the column the map has of the file: `unroll`, the window's travel, `roll` (96 f). if (@import("source.zig").inColumn(rec, a.src, windows, fit)) return time.unroll.grow + time.unroll.travel + time.unroll.roll; if (@max(windows[0], windows[1]) - @min(windows[0], windows[1]) > fit) return 2 * time.move; if (windows[0] != windows[1]) return time.move; if (wave or jumps(rec, from, to)) return 2 * time.current_jump; const rows: f32 = @floatFromInt(@max(a.line, b.line) - @min(a.line, b.line)); return @min(time.step + time.step_per_row * @max(rows - 1, 0), time.step_max); } /// A phrase ends where a call returns, or a loop comes round again. pub fn phraseEnds(c: Cursor, from: u64, to: u64) bool { const rec = c.rec; return rec.depths[to] < rec.depths[from] or (rec.depths[to] == rec.depths[from] and rec.own[to] < rec.own[from]); } pub const Hurry = struct { /// Seconds a step, once up to speed: `time.run`, or `time.sprint`. pace: f32 = time.run, /// What the pace was before, and is to be after. from: f32 = time.walk, to: f32 = time.walk, /// Veil what cannot be read at that pace (null: at a sprint). veil: ?bool = null, /// Lift the veil and rest a beat afterwards: not when another /// stretch at another pace follows at once. settle: bool = true, }; /// Pacing: steps of `by` up to `until`, hurried, for a pattern already /// seen in full. A change of pace is never a switch: each step is /// `time.ramp` of the one before on the way down from `from`, and on /// the way back up to `to`, and then the picture is still for a beat. /// A step with time enough is still a whole sentence, said faster; /// shorter, it is a run (the mark and structures eased, values as /// embers), with a short rest where a phrase ends; shorter still, a /// sprint. The head counts the steps while it lasts. pub fn hurry(c: Cursor, s: *anim.Frame, by: Recording.Stop, until: u64, options: Hurry) void { var here = c.moment(s); const n: f32 = @floatFromInt(c.steps(by, here, until)); if (n == 0) return; // Anticipation: the veil and the counter come with the first shortened step. // What changes faster than it can be read is veiled at a run too. const veiled = options.veil orelse true; const start = s.cursor; c.both(s, Veils{ .to = .{ 1, if (veiled) 1 else 0, if (options.pace < time.run) 1 else 0 } }); s.cursor = start; var k: f32 = 0; while (here < until) : (k += 1) { const next = @min(c.rec.next(by, here), until); const natural = c.reading(here, next); const down = options.from * std.math.pow(f32, time.ramp, k + 1); const up = options.to * std.math.pow(f32, time.ramp, n - k); // Whole frames, at 30 a second as at 60. const seconds = @round(@min(natural.total, @max(options.pace, @min(down, up))) * 30) / 30; const plan: Plan = if (seconds >= time.walk_least) natural else if (seconds > 1.5 * time.sprint) .running(seconds) else .sprinting(seconds); c.step(s, next, plan, seconds); if (plan.gait != .sprint and c.phraseEnds(here, next)) s.wait(time.phrase_rest_running); here = next; } if (!options.settle) return; c.both(s, Veils{ .to = .{ 0, 0, 0 } }); s.wait(time.beat); } /// The hurry's veils going to `to` (hurried, veil, sprint_veil). const Veils = struct { to: [3]f32, fn run(v: Veils, s: *anim.Frame, c: Cursor) void { s.play(.{ c.hurried.to(v.to[0]), c.veil.to(v.to[1]), c.sprint_veil.to(v.to[2]) }, .{ .seconds = time.veil, .ease = anim.ease.linear }); } }; /// There at once, with nothing struck: a cut. pub fn jump(c: Cursor, s: *anim.Frame, to: u64) void { const Jump = struct { to: u64, fn run(j: @This(), sf: *anim.Frame, v: Cursor) void { var all: [history + 3]anim.Animation = undefined; for (v.stops, 0..) |stop_value, i| all[i] = stop_value.to(@floatFromInt(j.to)); all[history] = v.phase.to(1); all[history + 1] = v.marks[0].to(@floatFromInt(j.to)); all[history + 2] = v.marks[1].to(@floatFromInt(j.to)); sf.play(all, .{ .seconds = 0 }); } }; c.both(s, Jump{ .to = to }); } /// For a component, while it draws (on the minimap the values are a lagging mirror's: `lagInto`). pub fn now(c: Cursor, placed: anim.Placed) Now { const rec = c.rec; var n: Now = .{ .rec = rec, .stops = undefined, .time = std.math.inf(f32), .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), .sprint_veil = placed.value(c.sprint_veil), .count = @intFromFloat(@max(placed.value(c.count), 0)), .of = c.of, .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); if (phase < 1) n.time = phase * n.plan.total; if (c.last > c.first) { // Linear: time itself. const here = std.math.lerp(@as(f32, @floatFromInt(n.stops[1])), @as(f32, @floatFromInt(n.stops[0])), std.math.clamp(phase, 0, 1)); n.place = std.math.clamp((here - @as(f32, @floatFromInt(c.first))) / @as(f32, @floatFromInt(c.last - c.first)), 0, 1); } return n; } }; /// Whether a write of the step from `from` to `to` takes a place among /// its strikes: not on a stack frame the step has already left (a callee's /// words, under rsp, that no window shows: `Recording.drawn`). fn takesPlace(rec: *const Recording, span: Recording.Span, from: u64, to: u64) bool { return rec.drawn(span, from, to) or zt.telescope.region(rec.moment(to), span.addr) catch .none != .stack; } fn whole(rec: *const Recording, value: f32) u64 { return @min(@as(u64, @intFromFloat(@max(value, 0))), rec.end()); } fn settled(s: *const anim.Frame, v: anim.Value) f32 { return s.values.items[@backingInt(v)].settled; } /// Whether the mark jumps from the line of moment `from` to that of `to` /// (fades out there and in here) and does not slide: a call is not a /// journey across the lines between. pub fn jumps(rec: *const Recording, from: u64, to: u64) bool { const a = rec.shown[from]; const b = rec.shown[to]; const rows = @max(a.line, b.line) - @min(a.line, b.line); return a.src != b.src or rec.depths[from] != rec.depths[to] or rows > time.current_jump_rows; } /// The cursor at one instant. pub const Now = struct { rec: *const Recording, /// `stops[0]` is the moment shown, `stops[1]` where the step came /// from: the step is every moment after it up to the one shown. stops: [history]u64, /// The pace each step to them was taken at: `gaits[0]` this one's. gaits: [history]Gait = @splat(.walk), /// Seconds into the step's plan; infinite at rest. time: f32, plan: Plan, /// The moment whose line the current mark is leaving, and the one it goes to. marks: [2]u64, /// 0 to 1: steps are hurried; what cannot be read is veiled. hurried: f32, veil: f32, sprint_veil: f32 = 0, /// Steps taken, of how many in the scene (0: not told). count: u32, of: u32, /// 0 to 1 along the scene's way through the recording. place: f32, /// Where the scene's steps fire (`Levels.fire`). 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 }, /// The program's state as shown. pub fn moment(n: Now) Recording.Moment { return n.rec.moment(n.stops[0]); } /// Its state before this step. pub fn before(n: Now) Recording.Moment { return n.rec.moment(n.stops[1]); } pub fn resting(n: Now) bool { return std.math.isInf(n.time); } /// A step shown in full: fire, arm, strike, hold. pub fn walking(n: Now) bool { return n.plan.gait == .walk and !n.resting(); } /// Seconds since `level` struck, for the one of several that strikes /// `delay` after the first: negative before, infinite at rest. pub fn since(n: Now, level: Level, delay: f32) f32 { return n.time - n.plan.at[@intFromEnum(level)] - delay; } /// Whether `level`'s changes show yet: until then a component draws /// the state before the step. The digits change as the fill comes in. pub fn landed(n: Now, level: Level, delay: f32) bool { return n.since(level, delay) >= time.strike.in / 2.0; } /// The state to draw for `level`. pub fn shown(n: Now, level: Level) Recording.Moment { return if (n.landed(level, 0)) n.moment() else n.before(); } /// The moment to ask the recording's index about, for `level`. pub fn stop(n: Now, level: Level) u64 { return if (n.landed(level, 0)) n.stops[0] else n.stops[1]; } /// How far (0 to 1, to be eased) a thing has got that moves as `level` /// strikes: it sets off `lead` seconds before the strike and takes /// `seconds`. At a run it sets off with its level and takes /// `time.run_ease`; at a sprint it takes the step (4 f: never one /// frame); at rest it is there. pub fn moving(n: Now, level: Level, lead: f32, seconds: f32) f32 { return switch (n.plan.gait) { .walk => std.math.clamp((n.since(level, 0) + lead) / seconds, 0, 1), .run => std.math.clamp(n.since(level, 0) / time.run_ease, 0, 1), .sprint => if (n.resting()) 1 else std.math.clamp(n.time / @max(n.plan.total, 1.0 / 60.0), 0, 1), }; } /// The fire: how far out (in units) the edges of the mark's plaque /// are, on the line about to run. The step's first beat, alone. pub fn fire(n: Now) f32 { return if (n.walking() and n.plan.fires and n.time < time.fire) theme.pulse(n.time / time.fire) else 0; } /// The same for the view the scene fires in, 0 for the other. pub fn fires(n: Now, in: @FieldType(Levels, "fire")) f32 { return if (n.fired == in) n.fire() else 0; } /// 0 to 1 over the 12 f before the advance (from the step's start where /// that is sooner, over the step at a sprint): how far a label that /// changes in place with the step (a frame's name, a tag's note) has /// crossfaded to the new one. Never in a frame. pub fn renaming(n: Now) f32 { if (n.resting()) return 1; const span = @min(time.quick, n.plan.advance); if (span <= 0) return std.math.clamp(n.time / @max(n.plan.total, 1.0 / 60.0), 0, 1); return std.math.clamp((n.time - (n.plan.advance - span)) / span, 0, 1); } /// 0 to 1 (to be eased) through the mark's move to the next line: the /// step's follow-through, and the next step's anticipation. pub fn advancing(n: Now) f32 { return n.advancingAfter(0); } /// The same for another view of where execution is (the pc's row, the /// value of rip), which follows the source's mark `delay` seconds /// behind: three panels do not start on one frame. pub fn advancingAfter(n: Now, delay: f32) f32 { if (n.resting() or n.plan.travel <= 0) return 1; return std.math.clamp((n.time - n.plan.advance - delay) / @max(n.plan.travel - delay, 1.0 / 60.0), 0, 1); } /// The moment the current mark stands for: the step's own line until /// the mark has left it. pub fn marked(n: Now) u64 { return if (n.advancing() >= 0.5) n.marks[1] else n.marks[0]; } /// How many steps ago (0: in this one) the bytes `addr .. addr + size` /// last changed; null when longer ago than a mark lasts. pub fn writeAge(n: Now, addr: u64, size: u64) ?u64 { return n.writeAgeFrom(addr, size, 0); } /// Of the bytes `addr .. addr + len` (16 at most), the first and the last /// (from `addr`) whose value the step that last wrote them changed: what /// its strike covers. Null where that is not known. pub fn changedBytes(n: Now, addr: u64, len: u64) ?[2]u8 { const age = n.writeAge(addr, len) orelse return null; const l: usize = @intCast(@min(len, 16)); var was: [16]u8 = undefined; var is: [16]u8 = undefined; var known_was: [16]bool = undefined; var known_is: [16]bool = undefined; n.rec.moment(n.stops[age + 1]).read(addr, was[0..l], known_was[0..l]) catch return null; n.rec.moment(n.stops[age]).read(addr, is[0..l], known_is[0..l]) catch return null; var out: ?[2]u8 = null; for (0..l) |i| if (known_was[i] and known_is[i] and was[i] != is[i]) { // Its first apart: assigned in one expression, `out` would be read as it is written. const first: u8 = if (out) |o| o[0] else @intCast(i); out = .{ first, @intCast(i) }; }; return out; } /// The same, not counting the `skip` newest steps. fn writeAgeFrom(n: Now, addr: u64, size: u64, skip: usize) ?u64 { for (skip..history - 1) |age| { if (Recording.touches(n.rec.written(n.stops[age + 1], n.stops[age]), addr, size)) return age; } return null; } /// The same for a register, by its place in `Regs.names`. pub fn registerAge(n: Now, reg: usize) ?u64 { return n.registerAgeFrom(reg, 0); } pub fn registerAgeFrom(n: Now, reg: usize, skip: usize) ?u64 { for (skip..history - 1) |age| { if (n.rec.registersChanged(n.stops[age + 1], n.stops[age]) >> @intCast(reg) & 1 != 0) return age; } return null; } /// Whether this step read any of `addr .. addr + size`. pub fn wasRead(n: Now, addr: u64, size: u64) bool { return Recording.touches(n.rec.read(n.stops[1], n.stops[0]), addr, size); } /// How far into the run of bytes this step wrote `addr` is: bytes of /// one write strike a frame apart, low address first. pub fn writeOffset(n: Now, addr: u64) u64 { for (n.rec.written(n.stops[1], n.stops[0])) |span| { if (addr >= span.addr and addr < span.addr + span.len) return addr - span.addr; } return 0; } /// What a step `age` steps ago left on a thing it wrote: an ember for /// three steps, leaving in the one after. fn left(n: Now, age: ?u64) ui.Heat { const s = time.strike; const a = age orelse return .none; if (a == 0 or a > s.ember_steps) return .none; // A run changes values unmarked: it shows them settled. if (n.gaits[a] == .run) return .none; // The step before went on into this one before its cool was done: it cools on. if (a == 1 and n.plan.cooling > 0 and n.gaits[1] == .walk and !n.resting() and n.time < n.plan.cooling) return cooled(1 - (n.plan.cooling - n.time) / s.cool, .nothing, 0); if (a < s.ember_steps) return .ember; // Linear: a fade, as the mark leaves: secondary action does not // start on the fire's frame, where the step's primary one does. // Within the step: a short one (a run's) is not cut off mid-fade by the next. return .{ .level = 1 - std.math.clamp((n.time - n.plan.advance) / @max(@min(s.out, n.plan.total - n.plan.advance), 1.0 / 60.0), 0, 1) }; } /// The mark of a thing last changed `age` steps ago (`older`: not /// counting this step), whose strike came `since_strike` seconds ago. /// Anticipation: armed first, a frame round the old value. Then the /// strike: the fill comes in (never in one frame) with a pulse of its /// edges, the one exaggeration there is. Held solid while the line /// that did it is still gold; cooled as the mark leaves. pub fn heat(n: Now, age: ?u64, older: ?u64, since_strike: f32) ui.Heat { const s = time.strike; if (age != 0) return n.left(age); const was = n.left(older); switch (n.plan.gait) { // Faster than a strike can be seen: embers only, coming in over the step. .sprint => return .{ .level = if (n.resting()) 1 else std.math.clamp(n.time / @max(n.plan.total, 1.0 / 60.0), 0, 1) }, // A run strikes nothing: its values change in place, and what // marked them before goes with the run's ease, not in a frame. .run => { var gone = was; gone.level *= 1 - (if (n.resting()) 1 else std.math.clamp(n.time / time.run_ease, 0, 1)); return gone; }, .walk => {}, } if (n.resting()) return .ember; if (since_strike < 0) { var armed = was; if (since_strike >= -s.arm) armed.arm = std.math.clamp((since_strike + s.arm) / time.stagger, 0, 1); return armed; } const in = std.math.clamp(since_strike / s.in, 0, 1); var h = cooled((n.time - n.plan.advance) / s.cool, if (was.level >= 1) .ember else .nothing, if (was.level >= 1) 1 - in else 0); h.in = in; h.out = if (since_strike < s.pulse) theme.pulse(since_strike / s.pulse) else 0; return h; } /// A struck thing `cooled` of the way through its cool (0 to 1): the /// paper going on `glide`; the turned corner coming in over the cool's /// last 6 f (and the old one, `corner_was`, going as a strike comes in over it). fn cooled(p: f32, from: @FieldType(ui.Heat, "from"), corner_was: f32) ui.Heat { const s = time.strike; return .{ .level = 1, .solid = 1 - glide(std.math.clamp(p, 0, 1)), .from = from, .corner = @max(std.math.clamp((p - 1) * s.cool / s.corner + 1, 0, 1), corner_was), }; } /// The mark of the bytes `addr .. addr + size`, which strike with /// `level`, `delay` seconds after its first, and 6 f after the write of /// this step before theirs. pub fn written(n: Now, addr: u64, size: u64, level: Level, delay: f32) ui.Heat { var h = n.heat(n.writeAge(addr, size), n.writeAgeFrom(addr, size, 1), n.sinceStrike(addr, size, level, delay)); // What the kernel fills in a crossing lands as its work does it, unpulsed. if (level == .memory and syscalls.filledAt(n, addr) != null) h.out = 0; return h; } /// Seconds since the strike of `addr .. addr + size` with `level`, /// `delay` after its first and 6 f after the write of this step before /// theirs; what the kernel fills in a crossing, as its work lands it. fn sinceStrike(n: Now, addr: u64, size: u64, level: Level, delay: f32) f32 { if (level == .memory) if (syscalls.filledAt(n, addr)) |at| return n.time - at; return n.since(level, delay + n.writeDelay(addr, size)); } /// Seconds since this step's write of `addr .. addr + size` struck in /// memory, at a walk; null where the step did not write it, or at /// another pace. Until `in / 2` after it (s+3) the old value stands, /// through the arm (`shownAt`, a dump's runs, a chain's hops). pub fn struckAgo(n: Now, addr: u64, size: u64) ?f32 { if (!n.walking() or n.writeAge(addr, size) != 0) return null; // What the kernel fills, a byte every 2 f: the value is there once its last byte is. var last: ?f32 = null; for (0..size) |i| if (syscalls.filledAt(n, addr + i)) |at| { last = @max(last orelse at, at); }; if (last) |at| return n.time - at; return n.sinceStrike(addr, size, .memory, 0); } /// `written`, struck `since` seconds ago (a loupe's own times: it strikes once it has opened). pub fn writtenAt(n: Now, addr: u64, size: u64, struck: f32) ui.Heat { return n.heat(n.writeAge(addr, size), n.writeAgeFrom(addr, size, 1), struck); } /// The state to draw the memory at `addr .. addr + size` from: /// `shown(.memory)`, but a write of this step from its own strike /// (s+3), never before its arm; what the kernel fills in a crossing /// from when its byte lands. pub fn shownAt(n: Now, addr: u64, size: u64) Recording.Moment { return if (n.landedAt(addr, size)) n.moment() else n.before(); } /// Whether memory at `addr .. addr + size` shows the step's state (`shownAt`). pub fn landedAt(n: Now, addr: u64, size: u64) bool { if (n.struckAgo(addr, size)) |ago| return ago >= time.strike.in / 2.0; return n.landed(.memory, 0); } /// The memory a chain from `value` (a register's, struck or not) reads /// as the panels show it (`shownAt`: the word it points at, from its /// strike), and, where the step changes what the chain says, seconds /// since its hops are followed again (`extend`): 4 f after the bytes /// land, never before. Null where the chain did not change. /// Before the bytes land, from their strike, the hops it shows fade out /// (the third: how much they show), so that none goes in a frame. pub fn following(n: Now, value: u64) struct { Recording.Moment, ?f32, f32 } { const memory = n.shownAt(value, 8); if (!n.walking()) return .{ memory, null, 1 }; const struck = n.struckAgo(value, 8) orelse n.since(.memory, 0); const land = time.strike.in / 2.0; // Followed again only while that shows (its hops 4 f apart, 6 f each). if (struck < 0 or struck > land + 0.5) return .{ memory, null, 1 }; var bufs: [2][6]zt.telescope.Link = undefined; var texts: [2][48]u8 = undefined; const was = zt.telescope.chase(n.before(), value, &bufs[0], &texts[0]) catch return .{ memory, null, 1 }; const is = zt.telescope.chase(n.moment(), value, &bufs[1], &texts[1]) catch return .{ memory, null, 1 }; const same = was.len == is.len and for (was, is) |a, b| { if (a.value != b.value or !std.mem.eql(u8, a.text, b.text)) break false; } else true; if (same) return .{ memory, null, 1 }; if (!n.landedAt(value, 8)) return .{ memory, null, 1 - std.math.clamp(struck / land, 0, 1) }; return .{ memory, struck - 4.0 / 60.0, 1 }; } /// `written`, on a thing the viewer has watched only through the steps /// `lo` to `hi` ago (a window that faded to its place, a view that came /// in after its step): what changed in any other step is plain. pub fn writtenWatched(n: Now, addr: u64, size: u64, level: Level, delay: f32, lo: usize, hi: usize) ui.Heat { const age = n.writeAge(addr, size) orelse return .none; return if (age >= lo and age < hi) n.written(addr, size, level, delay) else .none; } /// How far after this step's first write the one of `addr .. addr + size` is. pub fn writeDelay(n: Now, addr: u64, size: u64) f32 { var order: f32 = 0; var last: ?u64 = null; for (n.rec.written(n.stops[1], n.stops[0])) |span| { if (span.addr < addr +| size and span.addr + span.len > addr) return @min(order, 3) * write_apart; // The kernel's own writes have their own times (`filledAt`); a frame the step has left takes no place. if (syscalls.filledAt(n, span.addr) != null or !takesPlace(n.rec, span, n.stops[1], n.stops[0])) continue; // Bytes of one write (one store, in pieces) are one strike. if (last == null or span.addr != last.?) order += 1; last = span.addr + span.len; } return 0; } /// The mark of a register: the CPU's level. In a continue's wave, no arm and no pulse. pub fn register(n: Now, reg: usize, delay: f32) ui.Heat { var h = n.heat(n.registerAge(reg), n.registerAgeFrom(reg, 1), n.since(.cpu, delay)); if (n.plan.wave) { h.arm = 0; h.out = 0; } return h; } /// How much (0 to 1) the frame round a thing this step read shows: in /// with its level, never armed or pulsed, held while the line is /// 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) { // 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; if (!n.walking()) return 0; return @min(std.math.clamp((n.time - from) / r.in, 0, 1), 1 - std.math.clamp((n.time - n.plan.advance) / r.out, 0, 1)); } }; fn instant(seconds: f32, plan: Plan) Now { return .{ .rec = undefined, .stops = undefined, .time = seconds, .plan = plan, .marks = undefined, .hurried = 0, .veil = 0, .count = 0, .of = 0, .place = 0 }; } test "a write is armed, strikes, holds, cools with the advance, and leaves after three steps" { const s = time.strike; const expect = std.testing.expect; const expectEqual = std.testing.expectEqual; // One register written: struck at 0.30, the mark leaves at 0.90. const plan: Plan = .{ .at = @splat(0.30), .advance = 0.90, .total = 1.50 }; // Armed: a frame, and no fill yet. var h = instant(0.20, plan).heat(0, null, 0.20 - 0.30); try expect(h.arm == 1 and h.level == 0); // Not before its arm. try expectEqual(ui.Heat.none, instant(0.05, plan).heat(0, null, 0.05 - 0.30)); // Struck: the fill half in, the edges out. h = instant(0.35, plan).heat(0, null, 0.05); try expect(h.level == 1 and h.solid == 1 and @abs(h.in - 0.5) < 1e-3 and h.out > 2 and h.arm == 0); // Held solid until the mark leaves, then cooled, halfway at the middle. h = instant(0.89, plan).heat(0, null, 0.59); try expect(h.solid == 1 and h.in == 1 and h.out == 0); try expect(h.corner == 0); h = instant(0.90 + s.cool / 2.0, plan).heat(0, null, 0.8); try std.testing.expectApproxEqAbs(@as(f32, 0.5), h.solid, 1e-3); // The turned corner: none until the cool's last 6 f, then in. try expect(h.corner == 0); try std.testing.expectApproxEqAbs(@as(f32, 0.5), instant(0.90 + s.cool - s.corner / 2.0, plan).heat(0, null, 1).corner, 1e-3); // At rest, and for the steps after: the ember; then it goes. const rest = instant(std.math.inf(f32), plan); try expectEqual(ui.Heat.ember, rest.heat(0, null, std.math.inf(f32))); try expectEqual(ui.Heat.ember, rest.heat(2, 2, 0)); try expectEqual(ui.Heat.none, rest.heat(4, 4, 0)); try expectEqual(ui.Heat.none, rest.heat(null, null, 0)); try std.testing.expectApproxEqAbs(@as(f32, 0.5), instant(0.90 + s.out / 2.0, plan).heat(s.ember_steps, s.ember_steps, 0).level, 1e-3); // Struck again over its ember: armed with the ember still under it. h = instant(0.20, plan).heat(0, 1, -0.10); try expect(h.level == 1 and h.arm == 1 and h.solid == 0); // Running: nothing struck, and the ember before goes over the run's ease. Sprinting: an ember, coming in over the step. try expectEqual(ui.Heat.none, instant(0.2, Plan.running(0.3)).heat(0, null, 0.2)); try std.testing.expectApproxEqAbs(@as(f32, 0.5), instant(time.run_ease / 2.0, Plan.running(0.3)).heat(0, 1, 0).level, 1e-4); try std.testing.expectApproxEqAbs(@as(f32, 0.2), instant(0.01, Plan.sprinting(0.05)).heat(0, null, 0.01).level, 1e-4); } test "what a step read is framed while its line is gold" { const plan: Plan = .{ .at = @splat(0.30), .advance = 0.90, .total = 1.50 }; try std.testing.expectEqual(@as(f32, 0), instant(0.2, plan).reading(.memory, 0)); try std.testing.expectEqual(@as(f32, 1), instant(0.6, plan).reading(.memory, 0)); try std.testing.expectEqual(@as(f32, 0), instant(0.9 + time.read.out, plan).reading(.memory, 0)); try std.testing.expectEqual(@as(f32, 0), instant(std.math.inf(f32), plan).reading(.memory, 0)); } test "the mark fires first and moves last" { const plan: Plan = .{ .at = @splat(0.30), .advance = 0.90, .travel = 0.20, .total = 1.50 }; try std.testing.expect(instant(0.10, plan).fire() > 3.9); try std.testing.expectEqual(@as(f32, 0), instant(0.30, plan).fire()); try std.testing.expectEqual(@as(f32, 0), instant(0.89, plan).advancing()); try std.testing.expectEqual(@as(f32, 1), instant(1.10, plan).advancing()); try std.testing.expectEqual(@as(f32, 1), instant(std.math.inf(f32), plan).advancing()); }