diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-11 23:46:02 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-12 01:40:04 -0300 |
| commit | 60e07feef401d9044db3a1c925cb9d1f6d20dac9 (patch) | |
| tree | 98957ba8425193f686c8e8692cd10a10f27dbf4b /anim/scenes | |
| parent | 9c0696447dbc5cf37e56aee562c7ebba4f4d4e6b (diff) | |
| download | computeranim-60e07feef401d9044db3a1c925cb9d1f6d20dac9.tar.gz computeranim-60e07feef401d9044db3a1c925cb9d1f6d20dac9.zip | |
canim: relations as one data-oriented subsystem; aim; the ASan pair; the introduction's chapters
From the user. Relations between panes are one subsystem: per-frame
tables of places and values in struct-of-arrays, owned by the frame;
the kinds one table of data; a resolver of pure passes (join, filter,
priority, cut) unit-tested on hand-written tables. Ported kinds draw
byte-identical frames; a synthetic map of 4000 places and 6000 values
resolves in 0.56 ms against the old table's 5.7. aim, a word holding a
code address tied to its row, is the first new kind, off unless a scene
turns it on.
The ASan pair: one overflow built plain and with ASan, recorded by
instruction; the frame as bytes eight a row; the plain run goes on alone
in the column, its return address aimed at main's row until the letters
reach it; the fault at ret. The introduction's three chapters are built
and tested, not yet exported. Annotations, rows and scrolls that changed
in one frame now fade; captions stand twelve seconds at most.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_016Y9MNCKgYCGiANnEwcEQxa
Diffstat (limited to 'anim/scenes')
| -rw-r--r-- | anim/scenes/asan.zig | 563 | ||||
| -rw-r--r-- | anim/scenes/column.zig | 16 | ||||
| -rw-r--r-- | anim/scenes/fib.zig | 4 | ||||
| -rw-r--r-- | anim/scenes/heap.zig | 15 | ||||
| -rw-r--r-- | anim/scenes/intro_code.zig | 110 | ||||
| -rw-r--r-- | anim/scenes/intro_memory.zig | 186 | ||||
| -rw-r--r-- | anim/scenes/intro_stack.zig | 193 | ||||
| -rw-r--r-- | anim/scenes/list.zig | 7 | ||||
| -rw-r--r-- | anim/scenes/musl.zig | 10 | ||||
| -rw-r--r-- | anim/scenes/sort.zig | 4 | ||||
| -rw-r--r-- | anim/scenes/zoom.zig | 3 |
11 files changed, 1092 insertions, 19 deletions
diff --git a/anim/scenes/asan.zig b/anim/scenes/asan.zig new file mode 100644 index 0000000..2fe743f --- /dev/null +++ b/anim/scenes/asan.zig @@ -0,0 +1,563 @@ +//! ASan against a plain build (design/motion.md, "A scene: ASan against a +//! plain build"): `overflow.c`'s loop writes 32 bytes into 16, built plain +//! and with AddressSanitizer, the two runs a `pair` (design/README.md): +//! the shared source, each run's disassembly, registers and frame as bytes +//! on its side of the seam, `buf` facing `buf`. They go together to i = 16, +//! where they part: plain stores into its saved rbp, ASan reads `f3` in the +//! shadow and calls its report, which comes in from the run's own `write`s +//! in place of its registers; plain goes on alone, a letter a turn, through +//! the saved rbp and the return address (the held rest at i = 27 is the +//! poster, mock 38), to `ret` and its fault. Beats A1 to A16, the +//! storyboard's texts as written; A10 to A13 in the pair as captions (see +//! the README: the column holds no frame as bytes). +const std = @import("std"); +const anim = @import("anim"); +const canim = @import("canim"); +const recordings = @import("recordings"); +const pair = canim.pair; + +pub const background = canim.background; +pub const scene = anim.Live(frame, struct {}); + +/// The first moment from `from` whose instruction begins with `text`. +fn on(rec: *canim.Recording, from: u64, text: []const u8) u64 { + var buf: [256]u8 = undefined; + var i = from; + while (i < rec.end()) : (i += 1) if (rec.instruction(i, rec.register(i, "rip"), &buf)) |here| if (std.mem.startsWith(u8, here.text, text)) return i; + return rec.end(); +} + +/// The `n`th moment (from 0) from `from` whose pc is `pc`. +fn nth(rec: *canim.Recording, from: u64, pc: u64, n: usize) u64 { + var seen: usize = 0; + var i = from; + while (i < rec.end()) : (i += 1) if (rec.register(i, "rip") == pc) { + if (seen == n) return i; + seen += 1; + }; + return rec.end(); +} + +/// Each moment from here to `until` walked, its whole sentence said in +/// `seconds` (null: as long as it takes). +fn walk(s: *anim.Frame, c: canim.Cursor, until: u64, seconds: ?f32) void { + var here = c.moment(s); + while (here < until) : (here += 1) { + const plan = c.reading(here, here + 1); + c.step(s, here + 1, plan, seconds orelse plan.total); + } +} + +/// Straight to `to` at a run: unmarked, values changing in place under 8 f crossfades. +fn run(s: *anim.Frame, c: canim.Cursor, to: u64, seconds: f32) void { + c.step(s, to, canim.Plan.running(seconds), seconds); +} + +/// To `until` at a run, `per` moments a step (each step at least 18 f: the +/// mark's 8 f ease and its 8 f advance), the first steps as long as `ramp` +/// says and the rest as long as its last. +fn runTo(s: *anim.Frame, c: canim.Cursor, until: u64, per: u64, ramp: []const f32) void { + var here = c.moment(s); + var k: usize = 0; + while (here < until) : (k += 1) { + const next = @min(here + per, until); + const sec = ramp[@min(k, ramp.len - 1)]; + run(s, c, next, sec); + here = next; + } +} + +/// The two runs from one instant: the scene goes on when the later is done. +const Together = struct { + start: f32, + end: f32, + fn begin(s: *anim.Frame) Together { + return .{ .start = s.cursor, .end = s.cursor }; + } + /// The next run's part, from the same start. + fn next(tg: *Together, s: *anim.Frame) void { + tg.end = @max(tg.end, s.cursor); + s.cursor = tg.start; + } + fn done(tg: *Together, s: *anim.Frame) void { + s.cursor = @max(tg.end, s.cursor); + } +}; + +/// Of the right run's function, the rows no row of the left faces (`only +/// here`): all but the frame's own instructions, the loop counter's (the +/// memory the loop's `cmp …, 0x20` reads), the branch after that compare, +/// `add eax, 1`, the store of 'A', and the jump back to the compare. +fn onlyHere(a: std.mem.Allocator, rec: *canim.Recording, at: u64, start: u64) []const u64 { + var out: std.ArrayList(u64) = .empty; + var buf: [256]u8 = undefined; + var counter: []const u8 = ""; + var head: u64 = 0; + var addr = start; + var after_head = false; + while (rec.instruction(at, addr, &buf)) |one| : (addr += one.len) { + const text = a.dupe(u8, one.text) catch break; + if (std.mem.startsWith(u8, text, "cmp dword ptr [") and std.mem.endsWith(u8, text, ", 0x20")) { + counter = text[std.mem.indexOfScalar(u8, text, '[').? .. std.mem.indexOfScalar(u8, text, ']').? + 1]; + head = addr; + } + } + addr = start; + while (rec.instruction(at, addr, &buf)) |one| : (addr += one.len) { + const text = one.text; + const jump_back = std.mem.startsWith(u8, text, "jmp") and std.mem.endsWith(u8, text, a.dupe(u8, std.fmt.bufPrint(buf[200..], "0x{x}", .{head}) catch "") catch ""); + const faces = std.mem.eql(u8, text, "push rbp") or std.mem.eql(u8, text, "mov rbp, rsp") or std.mem.eql(u8, text, "pop rbp") or + (counter.len > 0 and std.mem.indexOf(u8, text, counter) != null) or after_head or std.mem.eql(u8, text, "add eax, 1") or + (std.mem.startsWith(u8, text, "mov byte ptr") and std.mem.endsWith(u8, text, ", 0x41")) or jump_back; + after_head = addr == head; + if (!faces) out.append(a, addr) catch break; + if (std.mem.eql(u8, text, "ret")) break; + } + return out.items; +} + +/// The signal that stopped the run, if one did: its moment and its name. +fn signal(rec: *canim.Recording) ?struct { at: u64, name: []const u8 } { + var i = rec.end(); + while (i > 0) { + i -= 1; + var events = rec.moment(i).events(std.heap.page_allocator) catch continue; + defer events.deinit(std.heap.page_allocator); + while (events.next()) |item| if (item.ev.kind == .signal) { + return .{ .at = i, .name = switch (item.ev.aux) { + 4 => "SIGILL", + 5 => "SIGTRAP", + 6 => "SIGABRT", + 7 => "SIGBUS", + 8 => "SIGFPE", + 11 => "SIGSEGV", + else => "a signal", + } }; + }; + } + return null; +} + +/// A stopped run's tag on the shelf: `stopped:` and its report's first words +/// (the error's kind, and the access: `stack-buffer-overflow, WRITE of size 1`). +fn stopped(a: std.mem.Allocator, said: []const u8) []const u8 { + const kind = blk: { + const at = std.mem.indexOf(u8, said, "AddressSanitizer: ") orelse break :blk ""; + const rest = said[at + "AddressSanitizer: ".len ..]; + break :blk rest[0 .. std.mem.indexOfAny(u8, rest, " \n") orelse rest.len]; + }; + const access = blk: { + const at = std.mem.indexOf(u8, said, "WRITE of size") orelse std.mem.indexOf(u8, said, "READ of size") orelse break :blk ""; + const rest = said[at..]; + break :blk rest[0 .. std.mem.indexOf(u8, rest, " at ") orelse rest.len]; + }; + return std.fmt.allocPrint(a, "stopped: {s}, {s}", .{ kind, access }) catch "stopped"; +} + +fn frame(s: *anim.Frame) void { + const plain = canim.open(recordings.overflow); + const asan = canim.open(recordings.overflow_asan); + const report = canim.open(recordings.overflow_report); + const t = canim.theme.time; + + // Plain: main's call; fill's line 4; the turns, each from its compare; the store of each; the way out. + const p_call = on(plain, plain.call("main", 0).enter, "call"); + const p_line4 = plain.lineMoment(4, p_call + 1); + const p_head = plain.register(on(plain, p_line4, "cmp"), "rip"); + var p_turn: [33]u64 = undefined; + var p_store: [32]u64 = undefined; + for (&p_turn, 0..) |*m, i| m.* = nth(plain, p_line4, p_head, i); + for (&p_store, 0..) |*m, i| m.* = on(plain, p_turn[i], "mov byte ptr"); + const p_pop = on(plain, p_turn[32], "pop rbp"); + const fault = signal(plain); + const p_end = if (fault) |f| f.at else p_pop + 2; + + // ASan: the same call; its prologue and `__asan_stack_malloc_0`, stepped over; line 3; the turns. + const q_call = on(asan, asan.call("main", 0).enter, "call"); + const q_fill = q_call + 1; + const q_malloc = on(asan, q_fill, "call"); + var ibuf: [256]u8 = undefined; + const malloc_pc = asan.register(q_malloc, "rip"); + const q_back = nth(asan, q_malloc + 1, malloc_pc + asan.instruction(q_malloc, malloc_pc, &ibuf).?.len, 0); + const q_line3 = asan.lineMoment(3, q_back); + const q_line4 = asan.lineMoment(4, q_line3); + const q_head = asan.register(on(asan, q_line4, "cmp dword ptr"), "rip"); + var q_turn: [17]u64 = undefined; + for (&q_turn, 0..) |*m, i| m.* = nth(asan, q_line4, q_head, i); + const q_load = struct { + fn of(rec: *canim.Recording, from: u64) u64 { + var buf: [256]u8 = undefined; + var i = from; + while (i < rec.end()) : (i += 1) if (rec.instruction(i, rec.register(i, "rip"), &buf)) |here| if (std.mem.indexOf(u8, here.text, "0x7fff8000]") != null) return i; + return rec.end(); + } + }.of; + const report_call = on(asan, q_load(asan, q_turn[16]), "call"); + + // The frames: plain's from rbp at line 4 (`i` at rbp-0x14, `buf` at rbp-0x10, then the saved rbp and the + // return address); ASan's fake frame, where `__asan_stack_malloc_0` put it, by its descriptor. + const rbp = plain.register(p_line4, "rbp"); + const buf = rbp - 0x10; + const fake = asan.register(q_back, "rax"); + const real = asan.register(q_line4, "rbp"); + // The descriptor ("1 32 16 5 buf:3"): one variable, at 32, 16 long. + var var_at: u64 = 32; + var var_len: u64 = 16; + if (canim.Recording.word(asan.moment(q_line3), fake + 8, 8) catch null) |descr| { + var text: [32]u8 = undefined; + var known: [32]bool = undefined; + if (asan.moment(q_line3).read(descr, &text, &known)) |_| { + var it = std.mem.tokenizeScalar(u8, text[0 .. std.mem.indexOfScalar(u8, &text, 0) orelse text.len], ' '); + _ = it.next(); + if (it.next()) |a| var_at = std.fmt.parseInt(u64, a, 10) catch var_at; + if (it.next()) |a| var_len = std.fmt.parseInt(u64, a, 10) catch var_len; + } else |_| {} + } + const fake_buf = fake + var_at; + + var at = canim.cursor(s, plain, p_call); + var as = canim.cursor(s, asan, q_call); + for ([_]*canim.Cursor{ &at, &as }) |c| c.levels = .{ .source_rows = 5, .fire = .disasm }; + at.journey(.moment, p_end); + as.journey(.moment, report_call); + + const left = canim.Stage.init(s, pair.split(.left, false)); + const right = canim.Stage.init(s, pair.split(.right, false)); + const fake_in = s.value(0); + const differs = s.value(0); + const attention = s.value(0); + const framed = s.value(0); + + const source = canim.add(s, canim.Source{ .cursor = at, .stage = left, .tag = "both builds" }); + const dis_l = canim.add(s, canim.Disasm{ .cursor = at, .stage = left }); + // In the column (A10 to A13) plain's disassembly is a descent: main's window, the row + // its return address names among them, over fill's whole (motion.md, the column's panes). + const desc_l = canim.add(s, canim.Descent{ .cursor = at, .stage = left }); + const dis_r = canim.add(s, canim.Disasm{ .cursor = as, .stage = right, .rows = 9 }); + const reg_moves = struct { + fn of(names: []const []const u8) u32 { + var mask: u32 = 0; + for (names) |n| for (canim.ztrace.Regs.names, 0..) |known, i| { + if (std.mem.eql(u8, known, n)) mask |= @as(u32, 1) << @intCast(i); + }; + return mask; + } + }.of; + const regs_l = canim.add(s, canim.Registers{ .cursor = at, .stage = left, .moves = reg_moves(&.{ "rax", "rbp", "rsp", "rip" }), .folds = false, .title = "plain \u{00b7} registers" }); + const regs_r = canim.add(s, canim.Registers{ .cursor = as, .stage = right, .moves = reg_moves(&.{ "rax", "rbx", "rcx", "rip" }), .folds = false, .title = "asan \u{00b7} registers" }); + const offset = pair.shadowOffset(asan) orelse 0x7fff8000; + const frame_l = canim.add(s, pair.Frame{ + .cursor = at, + .stage = left, + .title = "plain \u{00b7} stack", + .note = "fill's frame as bytes, eight a row", + .first = buf - 32, + .rows = 10, + .fields = s.arena.dupe(pair.Field, &.{ + .{ .at = rbp - 0x14, .len = 4, .name = "i", .from = p_line4 }, + .{ .at = buf, .len = 16, .name = "buf", .reads = .text, .from = p_line4 }, + .{ .at = rbp, .len = 8, .name = "saved rbp", .reads = .pointer, .from = p_call + 2 }, + .{ .at = rbp + 8, .len = 8, .name = "return", .reads = .pointer, .from = p_call + 1 }, + }) catch unreachable, + .letters = buf, + .span = .{ rbp - 0x18, rbp + 16 }, + .span_from = p_call + 1, + .tall = rbp - 0x18, + .name = "fill", + .side = .left, + .shows = s.value(1), + .differs = differs, + .differ = s.arena.dupe(u64, &.{ rbp, rbp + 8 }) catch unreachable, + }); + const frame_r = canim.add(s, pair.Frame{ + .cursor = as, + .stage = right, + .title = "asan \u{00b7} fake frame", + .note = std.fmt.allocPrint(s.arena, "its shadow at addr >> 3 + {x} \u{00b7} then the real stack's way back", .{offset}) catch "", + .first = fake, + .rows = 8, + .then = real, + .more = 2, + .fields = s.arena.dupe(pair.Field, &.{ + .{ .at = fake, .len = 8, .name = "magic", .reads = .bytes }, + .{ .at = fake + 8, .len = 8, .name = "descr", .reads = .pointer }, + .{ .at = fake + 16, .len = 8, .name = "pc", .reads = .pointer }, + .{ .at = fake + 24, .len = 8, .name = "real stack", .reads = .pointer }, + .{ .at = fake_buf, .len = var_len, .name = "buf", .reads = .text }, + .{ .at = fake_buf + var_len, .len = 8, .name = "redzone", .reads = .bytes }, + .{ .at = fake_buf + var_len + 8, .len = 8, .name = "redzone", .reads = .bytes }, + .{ .at = real, .len = 8, .name = "saved rbp", .reads = .pointer, .from = q_fill + 1 }, + .{ .at = real + 8, .len = 8, .name = "return", .reads = .pointer, .from = q_fill }, + }) catch unreachable, + .letters = fake_buf, + .shadow = true, + .span = .{ fake, real + 16 }, + .span_from = q_fill, + .name = "fill", + .side = .right, + .shows = fake_in, + .differs = differs, + .differ = s.arena.dupe(u64, &.{ fake_buf + var_len, fake_buf + var_len + 8 }) catch unreachable, + }); + const stderr = canim.add(s, pair.Report{ + .rec = report, + .stage = right, + .title = "asan \u{00b7} stderr", + .lines = &.{ "ERROR: AddressSanitizer", "WRITE of size", "is located in stack", "This frame has", "<== Memory access", "=>0x" }, + .words = &.{ "stack-buffer-overflow", "WRITE of size 1", "[32, 48) 'buf'", "[f3]" }, + .framed = framed, + }); + const store_pc = plain.register(p_store[0], "rip"); + const load_pc = asan.register(q_load(asan, q_turn[0]), "rip"); + const right_shows = s.value(1); + const marks = canim.add(s, pair.Marks{ + .left = at, + .right = as, + .stages = .{ left, right }, + .name = "asan", + .only = onlyHere(s.arena, asan, q_fill, asan.register(q_fill, "rip")), + .attend = .{ store_pc, load_pc }, + .attention = attention, + .right_shows = right_shows, + .fault = if (fault) |f| .{ .at = f.at, .pc = plain.register(f.at, "rip"), .name = f.name } else null, + }); + const clock = canim.add(s, pair.Clock{ .left = at, .right = as, .names = .{ "plain", "asan" }, .counter = rbp - 0x14, .counting = p_line4 + 1, .stage = left }); + // A10 to A13 in the column (`canim.column`): plain's panes, its frame as bytes the column's height; ASan's + // side folded to one tag on the shelf, its report's first line its note. + const col = canim.column(s, .{ .stage = left, .source = source, .disasm = dis_l, .registers = regs_l, .stack = frame_l, .backtrace = frame_l, .cursor = at }, .{}); + const shelf_fold = s.value(0); + const said = pair.Report.stderr(report, s.arena); + const shelf = canim.add(s, pair.Shelf{ .stage = right, .title = "asan", .note = stopped(s.arena, said), .fold = shelf_fold }); + // No ties across the seam: this one draws nothing (no thread, no stack words) and clears the frame's places. + const joins = canim.add(s, canim.Ties{ .cursor = at, .stage = left, .threaded = false, .quiet = true }); + s.play(.{ marks.fadeIn(), joins.fadeIn(), shelf.fadeIn() }, .{ .seconds = 0 }); + var says: canim.Narrator = .{}; + + canim.establish(s, .{ clock, source, dis_l, dis_r, regs_l, regs_r, frame_l, frame_r }); + + // A1: fill() called in both, as any call. + says.line(s, "Plain against AddressSanitizer: a loop writes 32 bytes into 16."); + var tg = Together.begin(s); + walk(s, at, p_call + 1, null); + tg.next(s); + walk(s, as, q_fill, null); + tg.done(s); + + // A2: line 2, the prologues: plain's two rows walked; ASan's at a run (four rows a step), its + // stack_malloc stepped over, the fake frame's rows coming in as it is made; then the store that + // poisons the shadow walked, its cells struck 2 f apart. + says.line(s, "ASan's prologue moves `buf` to a fake frame\nand poisons its shadow: `f1` before `buf`, `f3` after."); + tg = Together.begin(s); + walk(s, at, p_line4, null); + tg.next(s); + { + const start = s.cursor; + s.play(.{ as.veil.to(1), as.hurried.to(1) }, .{ .seconds = t.veil }); + s.cursor = start; + // Ramping in: each step 0.6 of the one before, to a run's 18 f. + runTo(s, as, q_malloc, 4, &.{ 0.5, 0.36, 0.3 }); + run(s, as, q_back, 0.4); + // The fake frame is made: its rows come in (12 f). + const made = s.cursor; + s.play(.{fake_in.to(1)}, .{ .seconds = t.quick }); + s.cursor = made; + runTo(s, as, q_line3 - 1, 5, &.{ 0.3, 0.36, 0.5 }); + s.play(.{ as.veil.to(0), as.hurried.to(0) }, .{ .seconds = t.veil }); + s.wait(t.beat); + walk(s, as, q_line3, null); + } + tg.done(s); + + // A3: line 3, ASan's alone: buf's shadow f8 f8 turns 00 00. + says.line(s, "Line 3 is ASan's alone: `buf`'s shadow `f8 f8` turns `00 00`."); + // One step under a text read for 4.8 s: said slower, so that it covers the reading. + walk(s, as, q_line4, 2.2); + + // A4: i = 0, the check: plain at a run to its store, where it waits facing ASan's check; ASan's + // counter and compare at a run, then its address and check rows walked, 30 f a row, the load longer. + says.line(s, "Before each store ASan reads `buf[i]`'s shadow byte,\nat `(addr >> 3) + 7fff8000`."); + const q_check0 = q_load(asan, q_turn[0]); + tg = Together.begin(s); + runTo(s, at, p_store[0], 1, &.{ 0.4, 0.3, 0.3 }); + tg.next(s); + runTo(s, as, q_turn[0] + 2, 1, &.{ 0.4, 0.3, 0.3 }); + walk(s, as, q_check0, 0.5); + walk(s, as, q_check0 + 1, 0.9); + walk(s, as, q_check0 + 3, 0.5); + tg.done(s); + + // A5: i = 0, the stores: ASan's rows after the check, then both stores, plain first, and each side's i++. + says.line(s, "It is `00`: the store may go. Both write `'A'`;\nplain in one instruction, ASan in seventeen."); + const q_store0 = on(asan, q_check0, "mov byte ptr"); + walk(s, as, q_store0, 0.5); + tg = Together.begin(s); + walk(s, at, p_store[0] + 1, null); + tg.next(s); + s.wait(6.0 / 60.0); + walk(s, as, q_store0 + 1, null); + tg.done(s); + tg = Together.begin(s); + runTo(s, at, p_turn[1], 1, &.{ 0.3, 0.3, 0.36 }); + tg.next(s); + runTo(s, as, q_turn[1], 1, &.{ 0.3, 0.3, 0.36 }); + tg.done(s); + + // A6: i = 1 to 14 at a run, a turn a step on each side, ramping in and out. + says.line(s, "Fourteen more turns, at a run: `buf` fills on both sides."); + { + const start = s.cursor; + s.play(.{ at.veil.to(1), at.hurried.to(1), as.veil.to(1), as.hurried.to(1) }, .{ .seconds = t.veil }); + s.cursor = start; + const paces = [_]f32{ 0.6, 0.36, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.36, 0.6 }; + for (paces, 1..) |sec, i| { + tg = Together.begin(s); + run(s, at, p_turn[i + 1], sec); + tg.next(s); + run(s, as, q_turn[i + 1], sec); + tg.done(s); + } + s.play(.{ at.veil.to(0), at.hurried.to(0), as.veil.to(0), as.hurried.to(0) }, .{ .seconds = t.veil }); + s.wait(t.beat); + } + + // A7: i = 15: the rows to each side's store at a run, ASan's load walked (the last 00 read), both stores + // walked, plain first; then each side's i++ at a run, to the turn's first row. + says.line(s, "i = 15, `buf`'s last byte:\nstill `00` on ASan's side, still `buf` on plain's."); + const q_check15 = q_load(asan, q_turn[15]); + const q_store15 = on(asan, q_check15, "mov byte ptr"); + tg = Together.begin(s); + runTo(s, at, p_store[15], 2, &.{ 0.4, 0.4 }); + tg.next(s); + runTo(s, as, q_check15, 2, &.{ 0.4, 0.3, 0.3 }); + walk(s, as, q_check15 + 1, 1.0); + runTo(s, as, q_store15, 3, &.{0.3}); + tg.done(s); + tg = Together.begin(s); + walk(s, at, p_store[15] + 1, 1.4); + run(s, at, p_turn[16], 0.4); + tg.next(s); + s.wait(6.0 / 60.0); + walk(s, as, q_store15 + 1, 1.4); + run(s, as, q_turn[16], 0.4); + tg.done(s); + + // A8: i = 16, they part (the storyboard's chart): plain to its store at a run over the time ASan takes + // to reach its check; the two first different rows framed `attention`; plain's store into the saved + // rbp, its `differs` bar 12 f after; ASan's load reads f3, its compare, its `je` not taken. + says.line(s, "i = 16, one past `buf`: plain writes an A into the saved rbp;\nASan reads `f3`, a redzone."); + const q_check16 = q_load(asan, q_turn[16]); + tg = Together.begin(s); + runTo(s, at, p_store[16], 1, &.{ 0.4, 0.4, 0.4 }); + tg.next(s); + runTo(s, as, q_check16, 4, &.{ 0.6, 0.6 }); + tg.done(s); + s.play(.{attention.to(1)}, .{ .seconds = 6.0 / 60.0 }); + s.wait(6.0 / 60.0); + tg = Together.begin(s); + { + const plan = at.reading(p_store[16], p_store[16] + 1); + at.step(s, p_store[16] + 1, plan, plan.total); + const after = s.cursor; + s.cursor = tg.start + plan.at[1] + 12.0 / 60.0; + s.play(.{differs.to(1)}, .{ .seconds = t.quick }); + s.cursor = after; + } + tg.next(s); + s.wait(30.0 / 60.0); + for (q_check16..q_check16 + 3) |m| { + const plan = as.reading(m, m + 1); + as.step(s, m + 1, plan, plan.total * 0.75); + } + tg.done(s); + s.play(.{attention.to(0)}, .{ .seconds = t.quick }); + + // A9: ASan's partial check and its call walked; its run stops: its registers give way to its stderr. + says.line(s, "ASan does not store: it calls its report,\nwhich names `buf` and the write."); + // The partial check's compare and branch walked; the loads round them at a run. + runTo(s, as, q_check16 + 7, 1, &.{0.3}); + walk(s, as, q_check16 + 9, 0.9); + runTo(s, as, report_call, 1, &.{0.3}); + s.wait(t.beat); + s.play(.{regs_r.fadeOut()}, .{ .seconds = t.quick, .ease = anim.ease.linear }); + right.glide(s, pair.split(.right, true), 0.4); + s.play(.{stderr.fadeIn()}, .{ .seconds = t.quick, .ease = anim.ease.linear }); + s.play(.{framed.to(3)}, .{ .seconds = 18.0 / 60.0, .ease = anim.ease.linear }); + + // A10 to A13: plain goes on alone, a store a turn, into the saved rbp and then the return address, + // in the column: the caption leaves; ASan's side folds to one tag on the shelf; plain's panes glide left + // and its frame's bytes open to the column's height; each text level with the field the turn's letter lands in. + const Store = struct { + /// Turn `i`: its rows up to the store at a run, then the store walked. + fn turn(sf: *anim.Frame, c: canim.Cursor, store: u64) void { + turnIn(sf, c, store, 78.0 / 60.0); + } + /// The same, the store's step `seconds` long (the aim's glide or fray in it, its text read within the beat). + fn turnIn(sf: *anim.Frame, c: canim.Cursor, store: u64, seconds: f32) void { + run(sf, c, store, 18.0 / 60.0); + walk(sf, c, store + 1, seconds); + } + }; + s.wait(@max(says.read_by - s.cursor, 0)); + if (says.current) |caption| { + const out = s.cursor; + s.play(.{caption.fadeOut()}, .{ .seconds = t.caption_out, .ease = canim.ease.exit }); + s.cursor = out; + } + s.play(.{ dis_r.fadeOut(), stderr.fadeOut(), frame_r.fadeOut(), right_shows.to(0), differs.to(0), shelf_fold.to(1), dis_l.fadeOut(), desc_l.fadeIn() }, .{ .seconds = t.quick, .ease = anim.ease.linear }); + s.play(.{shelf_fold.to(2)}, .{ .seconds = 18.0 / 60.0, .ease = anim.ease.linear }); + col.beat(s, .{ .panes = &.{ .{ .source, 3 }, .{ .disasm, 18 }, .{ .stack, canim.column_rest } }, .say = "Plain goes on alone, an A a turn, into the saved rbp.", .level = .{ .row = rbp } }); + { + // `aim = .standing` for these four beats: once the bubble has arrived, the return + // address's field aims at the row it names (18 f), in the lead before the first store. + const fires = s.cursor; + s.cursor = fires - 0.7; + at.aim(s, .standing); + s.cursor = fires; + } + for (17..21) |i| Store.turn(s, at, p_store[i]); + col.beat(s, .{ .panes = &.{ .{ .source, 3 }, .{ .disasm, 18 }, .{ .stack, canim.column_rest } }, .say = "The saved rbp fills: `4141414141414141`, no longer an address.", .level = .{ .row = rbp } }); + for (21..24) |i| Store.turn(s, at, p_store[i]); + col.beat(s, .{ .panes = &.{ .{ .source, 3 }, .{ .disasm, 18 }, .{ .stack, canim.column_rest } }, .say = "i = 24, the return address: it reads `fill+1`, still code.", .level = .{ .row = rbp + 8 } }); + Store.turnIn(s, at, p_store[24], 132.0 / 60.0); + col.beat(s, .{ .panes = &.{ .{ .source, 3 }, .{ .disasm, 18 }, .{ .stack, canim.column_rest } }, .say = "Each turn makes it stranger: `404141` is data, `414141` is nowhere.", .level = .{ .row = rbp + 8 } }); + for (25..27) |i| Store.turnIn(s, at, p_store[i], 128.0 / 60.0); + // Back to the pair: the aim goes with the column; the texts leave together, plain's panes glide back to their side, ASan's unfolds from the shelf. + at.aim(s, .off); + col.beat(s, .{ .at = .below, .say = "" }); + s.play(.{ desc_l.fadeOut(), dis_l.fadeIn() }, .{ .seconds = t.quick, .ease = anim.ease.linear }); + s.play(.{shelf_fold.to(1)}, .{ .seconds = 18.0 / 60.0, .ease = anim.ease.linear }); + s.play(.{ dis_r.fadeIn(), stderr.fadeIn(), frame_r.fadeIn(), right_shows.to(1), differs.to(1), shelf_fold.to(0) }, .{ .seconds = t.quick, .ease = anim.ease.linear }); + says.read_by = 0; + + // A14: i = 27 walked, then the held rest (the poster: mock 38), ASan standing on its report. + says.line(s, "Half written: `41414141`, no longer an address.\nOn the right, ASan stopped at the first byte past `buf`."); + run(s, at, p_store[27], 18.0 / 60.0); + { + // Its hold runs on under its own text (4.9 s): the struck byte solid, the plaque on the store. + var plan = at.reading(p_store[27], p_store[27] + 1); + const held = 4.9; + plan.advance += held; + plan.total += held; + const start = s.cursor; + at.step(s, p_store[27] + 1, plan, plan.total); + const after = s.cursor; + // ASan's side, read meanwhile: the shadow byte its check stopped on, framed in its report. + s.cursor = start + plan.at[1] + 1.0; + s.play(.{framed.to(4)}, .{ .seconds = t.quick, .ease = anim.ease.linear }); + s.cursor = after; + } + + // A15: i = 28 to 31. + says.line(s, "Four more turns: the last A lands,\nand it reads `4141414141414141`."); + for (28..32) |i| Store.turn(s, at, p_store[i]); + + // A16: the loop's exit, pop rbp, ret, and the fault. + says.line(s, "The loop ends: `pop rbp`, then `ret` to `4141414141414141`:\nthe CPU faults. SIGSEGV."); + run(s, at, p_turn[32], 18.0 / 60.0); + runTo(s, at, p_pop, 1, &.{ 0.4, 0.4 }); + for (p_pop..p_end) |m| { + const plan = at.reading(m, m + 1); + at.step(s, m + 1, plan, if (m + 1 == p_end) plan.total else plan.total * 0.8); + } + says.close(s); +} diff --git a/anim/scenes/column.zig b/anim/scenes/column.zig index b1a8df7..db211a7 100644 --- a/anim/scenes/column.zig +++ b/anim/scenes/column.zig @@ -55,40 +55,40 @@ fn frame(s: *anim.Frame) void { // C2: the arguments, beside the rows that set them. col.beat(s, .{ .panes = &.{ .{ .source, 3 }, .{ .disasm, 11 }, .{ .registers, regs } }, - .say = "main puts open's arguments where the convention says: \"note\" in `rdi`, 0 (O_RDONLY) in `rsi`.", + .say = "main puts open's arguments in registers: \"note\" in `rdi`, O_RDONLY in `rsi`.", .notes = &.{ .{ .band, "none yet" }, .{ .view, "no call crossing" } }, }); cur.walk(s, .moment, stub - 1); // C3: the call goes down; the stack under the descent. col.beat(s, .{ .panes = &.{ .{ .source, 3 }, .{ .disasm, 11 }, .{ .stack, rest } }, - .say = "The call pushes where to come back to, `main+45`, and goes down to open's stub.", + .say = "The call pushes the way back, `main+45`, and goes down to the stub.", }); canim.descent.step(cur, s, .moment); s.wait(t.phrase_rest); // C4: the stub's jmp: the stack holds still. - col.beat(s, .{ .say = "The stub in the PLT is one jump: it reads `open@got`, where the loader wrote libc's `open`. It pushes nothing.", .panes = &.{ .{ .source, 3 }, .{ .disasm, 11 }, .{ .stack, rest } } }); + col.beat(s, .{ .say = "The stub is one jump through `open@got`: it pushes nothing.", .panes = &.{ .{ .source, 3 }, .{ .disasm, 11 }, .{ .stack, rest } } }); canim.descent.step(cur, s, .moment); s.wait(t.phrase_rest); // C5: the wrapper at a run, the bubble level with its window's head. col.beat(s, .{ - .panes = &.{ .{ .source, 3 }, .{ .disasm, 11 }, .{ .stack, rest } }, + .panes = &.{ .{ .source, 2 }, .{ .disasm, 11 }, .{ .stack, rest } }, .say = "libc's `open` is a wrapper: a few lines of C around the one instruction that calls the kernel.", .level = .{ .head = "open" }, }); cur.hurry(s, .moment, crossing - 3, .{}); // C6: its last three, beside the registers they set. col.beat(s, .{ - .panes = &.{ .{ .source, 3 }, .{ .disasm, 11 }, .{ .registers, regs } }, - .say = "Its last three set the kernel's arguments: AT_FDCWD in `rdi`, and 257, openat's number, in `rax`.", + .panes = &.{ .{ .source, 2 }, .{ .disasm, 11 }, .{ .registers, regs } }, + .say = "Its last three set the kernel's arguments, and openat's number, 257, in `rax`.", .stem = .none, - .notes = &.{ .{ .band, "none yet" }, .{ .view, "`\"note\"`" } }, + .notes = &.{ .{ .band, "none yet" }, .{ .view, "`\"note\"` handed in" }, .{ .stack, "open's frame, 16 words" } }, }); cur.walk(s, .moment, crossing); // C7: the crossing, the kernel at the descent's floor. col.beat(s, .{ .panes = &.{ .{ .source, 3 }, .{ .disasm, 24 } }, - .say = "`syscall` crosses down. The kernel opens \"note\" and answers 3: the file's descriptor, in `rax`.", + .say = "`syscall` crosses down; the kernel opens \"note\" and answers 3 in `rax`.", .level = .floor, .stem = .none, .notes = &.{ .{ .band, "none yet" }, .{ .view, "`\"note\"`" } }, diff --git a/anim/scenes/fib.zig b/anim/scenes/fib.zig index 5f958dd..983f2da 100644 --- a/anim/scenes/fib.zig +++ b/anim/scenes/fib.zig @@ -39,8 +39,8 @@ fn frame(s: *anim.Frame) void { const joins = ctx.ties(s); canim.establish(s, .{ ctx.clock, ctx.registers, ctx.stack, ctx.source, ctx.disasm, tree, joins }); says.line(s, "`fib` calls itself. A call is a frame on the stack and a node\nin the tree; its argument arrives in `rdi`."); - // The call, once, in full; and the two lines that lead to the next one. - at.walk(s, .line, rec.lineMoment(6, call(rec, 0).enter)); + // The call, once, in full, to its frame made; the lines after it run with the next caption's. + at.walk(s, .line, rec.lineMoment(4, call(rec, 0).enter)); s.wait(canim.theme.time.beat); // Pacing: the same three lines three times more. Seen once, so diff --git a/anim/scenes/heap.zig b/anim/scenes/heap.zig index 6e521d0..07eccea 100644 --- a/anim/scenes/heap.zig +++ b/anim/scenes/heap.zig @@ -176,7 +176,10 @@ const Lists = struct { const changed = counts[0] == null or !real[0] or counts[0].? != counts[1].?; const comes = !real[0] or counts[0] == null; const bv = v.faded(if (comes) after(now, 42, 6) else 1); - const heat = if (changed and now.walking()) now.heat(0, null, now.since(.idea, 0) - 60.0 / 60.0) else if (changed) canim.ui.Heat.ember else canim.ui.Heat.none; + // Changed in the step before: its mark leaves as any does (with a run's ease, or its embers' steps), never in a frame. + const before = if (heapAt(a, rec, now.stops[2])) |hp| holds(hp) else null; + const changed_before = now.stops[2] != now.stops[1] and real[0] and counts[0] != null and before != counts[0]; + const heat = if (changed and now.walking()) now.heat(0, null, now.since(.idea, 0) - 60.0 / 60.0) else if (changed) canim.ui.Heat.ember else if (changed_before) now.heat(1, null, std.math.inf(f32)) else canim.ui.Heat.none; bv.fill(badge, theme.color.page); const ink = bv.cellWritten(badge, heat, theme.color.page); // Framed, but while the strike's paper is on it. @@ -199,7 +202,15 @@ const Lists = struct { const sx = top_r.x + top_r.w - 16 - tv.width(.mono, theme.size.mono.context, size_text); tv.text(.mono, theme.size.mono.context, top_r.x + 16, theme.baseline(top_r.y, h, theme.size.mono.context), "top", t.dim); var ink: canim.ui.Ink = .{ .ink = ui.rgb(t.dim) }; - if (side == 1 and moved and tops[0] != null and now.walking()) ink = tv.cellWritten(.{ .x = sx - 4, .y = top_r.y + 10, .w = tv.width(.mono, theme.size.mono.context, size_text) + 8, .h = 24 }, now.heat(0, null, now.since(.idea, 0) - 12.0 / 60.0), null); + const cell: canim.Rect = .{ .x = sx - 4, .y = top_r.y + 10, .w = tv.width(.mono, theme.size.mono.context, size_text) + 8, .h = 24 }; + if (side == 1 and moved and tops[0] != null) ink = tv.cellWritten(cell, if (now.resting() and now.gaits[0] == .walk) canim.ui.Heat.ember else now.heat(0, null, now.since(.idea, 0) - 12.0 / 60.0), null) else if (side == 1 and !moved and now.stops[2] != now.stops[1] and now.gaits[1] == .walk) { + // Moved in the step before: its mark leaves as any does, never in a frame. + const old = heapAt(a, rec, now.stops[2]); + const was = if (old) |hp| (if (hp.chunks.len > 0) hp.chunks[hp.chunks.len - 1] else null) else null; + if (was) |top_was| if (top_was.addr != top.addr or top_was.size() != top.size()) { + ink = tv.cellWritten(cell, now.heat(1, null, std.math.inf(f32)), null); + }; + } tv.text(ink.face, theme.size.mono.context, sx, theme.baseline(top_r.y, h, theme.size.mono.context), size_text, ink.ink); _ = tv.address(top_r.x + 16, top_r.y - 8, top.addr, .{ .ink = ui.rgb(theme.color.region.heap) }); }; diff --git a/anim/scenes/intro_code.zig b/anim/scenes/intro_code.zig new file mode 100644 index 0000000..a5660ed --- /dev/null +++ b/anim/scenes/intro_code.zig @@ -0,0 +1,110 @@ +//! The introduction, chapter III: code and meaning (design/motion.md, "A +//! scene: the introduction", III1 to III5; mocks 32, 33, 36). On the +//! `list` recording at the load in `reverse` (line 21, `node *next = +//! cur->next;`, the instruction that reads `cur->next`): the code's bytes +//! as a dump row, that instruction's four framed; `decode`d into its row +//! of `aligned` (`interleaved`), its neighbours at a run, each line level +//! with its run; then `align` to `columns`; then the working frame with the +//! nodes drawn from the heap's bytes; then the map (`surface`). The texts +//! `above` the aligned panel, then below the working frame. +const std = @import("std"); +const anim = @import("anim"); +const canim = @import("canim"); +const recordings = @import("recordings"); + +pub const background = canim.background; +pub const scene = anim.Live(frame, struct {}); + +const t = canim.theme.time; + +fn f(frames: f32) f32 { + return frames / 60; +} + +fn run(s: *anim.Frame, v: anim.Value, frames: f32) void { + s.play(.{v.to(0)}, .{ .seconds = 0 }); + s.play(.{v.to(frames)}, .{ .seconds = f(frames), .ease = anim.ease.linear }); +} + +fn on(rec: *canim.Recording, from: u64, text: []const u8) u64 { + var buf: [256]u8 = undefined; + var i = from; + while (i < rec.end()) : (i += 1) if (rec.instruction(i, rec.register(i, "rip"), &buf)) |here| if (std.mem.indexOf(u8, here.text, text) != null) return i; + return from; +} + +/// The variables whose tags the nodes carry, as the list scene's. +const tracked = [_][]const u8{ "prev", "cur", "next", "head" }; + +fn frame(s: *anim.Frame) void { + const rec = canim.open(recordings.list); + const reverse = rec.call("reverse", 0); + // The load: `cur->next` read, line 21's second instruction. + const moment = on(rec, rec.lineMoment(21, reverse.enter), "[rax + 8]"); + const pc = rec.register(moment, "rip"); + var buf: [256]u8 = undefined; + const insn = rec.instruction(moment, pc, &buf).?; + // Its bytes and its text as canim writes it (the size word dropped), from the recording. + var code: [16]u8 = undefined; + var known: [16]bool = undefined; + rec.moment(moment).read(pc, code[0..insn.len], known[0..insn.len]) catch {}; + var hex: std.ArrayList(u8) = .empty; + for (code[0..insn.len], 0..) |b, k| hex.print(s.arena, "{s}{x:0>2}", .{ if (k > 0) " " else "", b }) catch {}; + const text = std.mem.replaceOwned(u8, s.arena, insn.text, "qword ptr ", "") catch insn.text; + + var at = canim.cursor(s, rec, moment); + at.journey(.moment, moment + 1); + at.levels = .{ .idea = .data, .follow = t.move, .source_rows = 8 }; + const ctx = canim.context(s, at, .{ .split = canim.layout.split.subject }); + const list = canim.nodes(s, .{ .cursor = at, .stage = ctx.stage, .root = "head", .track = &tracked }); + ctx.map.add(s, canim.Nodes{ .cursor = at, .stage = ctx.map.stage, .root = "head", .track = &tracked }); + const joins = ctx.ties(s); + + const al = s.new(canim.Aligned.init(s, rec, moment)); + const panel = s.custom(al, .{ .x = -640, .y = -360, .scale = canim.ui.scale }); + s.play(.{panel.fadeIn()}, .{ .seconds = 0 }); + var asides: canim.Asides = .{}; + const left = canim.theme.canvas.margin_x; + const above = canim.theme.canvas.stage.y + 40; + + // III1: the code's bytes, one instruction's framed. + s.wait(1.0); + asides.say(s, std.fmt.allocPrint(s.arena, "Code is bytes too: `{s}` is one instruction.", .{hex.items}) catch "", left, above); + s.wait(t.caption_lead); + run(s, al.bytes, 12 + 2 * 15 + 12 + 6); + s.wait(t.beat); + + // III2: decoded into its row, its neighbours at a run, each line level with its run. + asides.say(s, std.fmt.allocPrint(s.arena, "Decoded: `{s}`, from line {d}. Each line sits level with its code.", .{ text, insn.line orelse 0 }) catch "", left, above); + run(s, al.decode, 60); + run(s, al.rows_in, 2 * 32 + 8); + run(s, al.chrome, 24); + s.wait(t.beat); + + // III2, the other form: two columns, each line level with the first of its instructions. + asides.say(s, "Two columns: each line level with its first instruction.", left, above); + run(s, al.form, 72); + s.wait(t.beat); + + // Into the working frame: the texts above leave, the panel goes, the frame comes in. + asides.leave(s); + s.play(.{panel.fadeOut()}, .{ .seconds = f(12), .ease = anim.ease.linear }); + var says: canim.Narrator = .{}; + var cam: canim.Camera = .{}; + canim.establish(s, .{ ctx.clock, ctx.registers, ctx.stack, ctx.source, ctx.disasm, joins }); + // III3: the node it reads, as bytes and drawn: the band comes in, its + // elements rising from their bytes, and the camera nearer on it (x1.5). + says.line(s, "`rax` points at a list node on the heap:\nits bytes, and drawn, the node."); + ctx.establish(s, .{list}, 3); + cam.go(s, .{ .x = 512, .y = 48, .w = 896, .h = 296 }, 1.5, .{}); + s.wait(t.beat); + // III4: the whole frame: the camera back to x1. + says.line(s, "This is the whole frame.\nEvery view in it is these same bytes."); + cam.back(s, .{}); + s.wait(t.beat); + // III5: the map. + says.line(s, "And all of it at once: the map."); + ctx.map.surface(s); + says.close(s); + cam.apply(s); +} diff --git a/anim/scenes/intro_memory.zig b/anim/scenes/intro_memory.zig new file mode 100644 index 0000000..07e694a --- /dev/null +++ b/anim/scenes/intro_memory.zig @@ -0,0 +1,186 @@ +//! The introduction, chapter I: memory (design/motion.md, "A scene: the +//! introduction", I1 to I10; mocks 29, 30, 34, 37). The frame built from +//! its bytes up, on the `list` recording stopped in `reverse`'s prologue, +//! at its first call (line 17: the push chapter II walks; the 128 bytes at +//! rsp then are the load's but for `prev`, not yet stored), each part in +//! the place it keeps: the 128 bytes at the top +//! of the stack where the stack panel will stand, under the camera at x2; +//! made words (`regroup`); three of them addresses; then the address space +//! to scale in the program column (`segments`), each cluster enlarged, its +//! text beside it; back to the working frame, the dump tied to its place, +//! a visit at x4, `ink`, and three chains. +const std = @import("std"); +const anim = @import("anim"); +const canim = @import("canim"); +const recordings = @import("recordings"); + +pub const background = canim.background; +pub const scene = anim.Live(frame, struct {}); + +const t = canim.theme.time; + +fn f(frames: f32) f32 { + return frames / 60; +} + +/// Clock `v` from 0 to `frames`, linear, from the cursor; the cursor after it. +fn run(s: *anim.Frame, v: anim.Value, frames: f32) void { + s.play(.{v.to(0)}, .{ .seconds = 0 }); + s.play(.{v.to(frames)}, .{ .seconds = f(frames), .ease = anim.ease.linear }); +} + +/// The same, the cursor left where it was. +fn start(s: *anim.Frame, v: anim.Value, frames: f32) void { + const at = s.cursor; + run(s, v, frames); + s.cursor = at; +} + +/// The first moment from `from` whose instruction reads `text`. +fn on(rec: *canim.Recording, from: u64, text: []const u8) u64 { + var buf: [256]u8 = undefined; + var i = from; + while (i < rec.end()) : (i += 1) if (rec.instruction(i, rec.register(i, "rip"), &buf)) |here| if (std.mem.indexOf(u8, here.text, text) != null) return i; + return from; +} + +fn frame(s: *anim.Frame) void { + const rec = canim.open(recordings.list); + const reverse = rec.call("reverse", 0); + // reverse's first call (line 17, the tracer's `__zt_var` for its first + // local): the push chapter II walks. The recording begins after + // reverse's own `push rbp` (`--from` breaks past the prologue), so it is + // the first push of reverse's that the recording has. + const moment = on(rec, reverse.enter, "call"); + const ui = canim.ui; + const at = canim.regroup.at; + + const space = s.new(canim.Segments.init(s, rec, moment)); + const dump = s.new(canim.Words.init(s, rec, moment)); + const place = s.new(canim.segments.Place{ .segments = space, .addr = rec.register(moment, "rsp"), .x = at.bracket, .y0 = at.top + 2, .y1 = at.top + 16 * 24 - 2, .clock = s.value(-1), .quiet = s.value(0) }); + + // `ink`'s echoes: the walked word's band first, then the rest at a run, 2 f apart. + const values = canim.Words.read(rec, moment); + var order: [canim.regroup.words]usize = undefined; + order[0] = dump.walked; + var n_order: usize = 1; + for (0..canim.regroup.words) |i| if (i != dump.walked) { + order[n_order] = i; + n_order += 1; + }; + for (order, 0..) |i, k| { + space.echoes[k] = .{ .addr = values.words[i], .shows = s.value(0) }; + } + space.n_echoes = order.len; + + const objs = .{ s.custom(space, .{ .x = -640, .y = -360, .scale = ui.scale }), s.custom(dump, .{ .x = -640, .y = -360, .scale = ui.scale }), s.custom(place, .{ .x = -640, .y = -360, .scale = ui.scale }) }; + inline for (objs) |o| s.play(.{o.fadeIn()}, .{ .seconds = 0 }); + + // The camera at x2 on the dump from the first frame (I1 to I3). + const near = ui.framing(.{ .x = 888, .y = 72, .w = 896, .h = 408 }, 2); + var cam: canim.Camera = .{}; + cam.moves[0] = .{ .from = near, .to = near, .p = s.value(1) }; + cam.count = 1; + cam.at = near; + var says: canim.Narrator = .{}; + var asides: canim.Asides = .{}; + + // I1: the bytes, a row at a time. + s.wait(1.0); + says.line(s, "A running program is bytes in memory:\nhere, 128 of them at the top of the stack."); + run(s, dump.in, 7 * 12 + 18); + s.wait(t.beat); + + // I2: eight a row; the return address walked, the other fifteen at a run. + says.line(s, "Eight bytes make a word, stored low byte first:\nthe lowest byte is its last two digits."); + run(s, dump.regroup, 386); + s.wait(t.beat); + + // I3: three words that hold addresses, framed as read. + says.line(s, "Some words are addresses:\nthey name a place in memory."); + run(s, dump.framed, 66); + s.wait(@max(says.read_by - s.cursor, 0)); + + // Into the column: the caption leaves, the camera out to x1, the dump to its tag on the shelf. + s.play(.{says.current.?.fadeOut()}, .{ .seconds = t.caption_out, .ease = canim.ease.exit }); + says.current = canim.caption(s, ""); + s.wait(t.caption_gap); + cam.back(s, .{}); + run(s, dump.fold, 30); + // Folded, the three frames go with the rows: unfolded, the dump is plain words again. + s.play(.{dump.framed.to(-1)}, .{ .seconds = 0 }); + + // I4: the whole, deliberately. + const column_x = canim.theme.layout.state.x + 8; + const l = space.layout(0, s.arena); + asides.say(s, "Its address space, 128 TiB, to scale: mapped only at each end.", column_x, (l.top + l.foot) / 2); + run(s, space.whole, 72 + 18 + 72); + s.wait(t.beat); + + // I5: the top end, a box a cluster, each riding out as the one before lands. + const clusters = @min(l.space.clusters.len, 6); + var top_end: usize = 0; + while (top_end < clusters and l.space.clusters[top_end].lo > canim.segments.user_end / 2) top_end += 1; + asides.say(s, "Enlarged, the top end: the stack, the libraries and the tracer's ring, each band with its addresses and size.", column_x, l.boxes[0].y + 12); + for (0..top_end) |i| { + start(s, space.rides[i], 6 + 72 + 90 + 2 * 12 + 12); + s.wait(f(78)); + } + s.wait(f(90 + 2 * 12 + 12)); + // I6: the foot, the program by segment. + for (top_end..clusters) |i| { + asides.say(s, "At the foot, the program: its code, its data, its heap.", column_x, l.boxes[i].y + l.boxes[i].h / 2); + run(s, space.rides[i], 6 + 72 + 90 + 2 * 12 + 12); + } + s.wait(t.beat); + + // Back to the working frame: the texts leave, the drawing to the stage's height, the dump unfolds. + asides.leave(s); + s.play(.{space.form.to(1)}, .{ .seconds = f(24), .ease = anim.ease.linear }); + s.play(.{dump.fold.to(0)}, .{ .seconds = f(30), .ease = anim.ease.linear }); + + // I7: the dump's place: the tie bracket, the link onto the stack's box. + says.line(s, "These 128 bytes are here,\nat the very top of the stack."); + s.play(.{dump.placed.to(1)}, .{ .seconds = f(12), .ease = anim.ease.linear }); + s.cursor -= f(12); + run(s, place.clock, 60); + s.wait(t.beat); + + // I8: a visit at x4 to where the link lands, and back. + says.line(s, "Were the bar the Eiffel Tower,\nthey would be an atom thick, at its top."); + const landed = space.layout(1, s.arena); + const head = canim.Segments.place(landed, place.addr) orelse .{ 0, 0 }; + cam.go(s, .{ .x = head[0] - 112, .y = 48, .w = 224, .h = 104 }, 4, .{}); + s.wait(t.beat); + cam.back(s, .{}); + + // I9: `ink`: the return address walked, its band framed; the rest at a run; the link quiets. + const walked = values.words[dump.walked]; + const band = for (landed.space.bands) |b| { + if (walked >= b.lo and walked < b.hi) break b; + } else landed.space.bands[0]; + says.line(s, std.fmt.allocPrint(s.arena, "A word takes the ink of where it points:\n`{x}` is {s}'s code.", .{ walked, band.name }) catch ""); + const inking = s.cursor; + start(s, place.quiet, 24); + for (order[1..], 1..) |_, k| { + s.cursor = inking + f(@floatFromInt(72 + 2 * (k - 1))); + s.play(.{space.echoes[k].shows.to(1)}, .{ .seconds = f(4), .ease = anim.ease.linear }); + s.play(.{space.echoes[k].shows.to(0)}, .{ .seconds = f(8), .ease = anim.ease.linear }); + } + s.cursor = inking; + s.play(.{space.echoes[0].shows.to(1)}, .{ .seconds = f(6), .ease = anim.ease.linear }); + s.cursor = inking + f(72 + 2 * 16 + 12); + s.play(.{space.echoes[0].shows.to(0)}, .{ .seconds = f(18), .ease = anim.ease.linear }); + s.cursor = inking; + run(s, dump.ink, 72 + 2 * 16 + 12 + 18); + s.wait(t.beat); + + // I10: the words to their field's left, then three chains, walked. + says.line(s, "Follow an address and you reach another word:\na chain."); + run(s, dump.left, 24); + run(s, dump.chains, 36 * 2 + 30); + s.wait(t.beat); + // The chapter's last picture. + says.close(s); + cam.apply(s); +} diff --git a/anim/scenes/intro_stack.zig b/anim/scenes/intro_stack.zig new file mode 100644 index 0000000..e504ffc --- /dev/null +++ b/anim/scenes/intro_stack.zig @@ -0,0 +1,193 @@ +//! The introduction, chapter II: the stack (design/motion.md, "A scene: the +//! introduction", II1 to II4; mock 31). It opens on chapter I's last +//! picture, at the same moment of the `list` recording (reverse's first +//! call, line 17): the address space and the dump's link fade, the words +//! glide into the stack panel's rows where it stands in the working frame +//! and become it; a push walked from the recording (that call's: the +//! address to come back to, rsp's pin climbing onto it); the return +//! address main left, and the offsets; rbp's pin and the panel's tag last; +//! then the registers built over it a row at a time, their tag last. The +//! text stands beside on the left, in the program column, empty until +//! chapter III. +//! +//! What a beat has not reached yet is under the page (`Cover`), lifted as +//! the beat says it: the context's panels draw every column at once. +const std = @import("std"); +const anim = @import("anim"); +const sk = @import("sketch"); +const canim = @import("canim"); +const recordings = @import("recordings"); + +pub const background = canim.background; +pub const scene = anim.Live(frame, struct {}); + +const t = canim.theme.time; +const row = canim.theme.metric.context.row; +const tag = canim.theme.metric.context.tag; +const pad = canim.theme.metric.context.pad; + +fn f(frames: f32) f32 { + return frames / 60; +} + +fn place(s: *anim.Frame, data: anytype) anim.Obj { + return s.custom(data, .{ .x = -640, .y = -360, .scale = canim.ui.scale }); +} + +/// The page over a part of a panel the beat has not reached: lifted (its fade out) as the beat says it. +const Cover = struct { + box: canim.Rect, + pub fn draw(c: *const Cover, fr: *sk.Frame, placed: anim.Placed) void { + (canim.ui.Ui{ .f = fr, .at = placed }).fill(c.box, canim.theme.color.page); + } +}; + +/// A value framed as read (6 f in with its object's fade). +const Read = struct { + box: canim.Rect, + pub fn draw(r: *const Read, fr: *sk.Frame, placed: anim.Placed) void { + (canim.ui.Ui{ .f = fr, .at = placed }).read(r.box, 1); + } +}; + +fn cover(s: *anim.Frame, box: canim.Rect) anim.Obj { + const o = place(s, s.new(Cover{ .box = box })); + s.play(.{o.fadeIn()}, .{ .seconds = 0 }); + return o; +} + +/// A panel's tag and rules under the page, for `frame up`. +fn chrome(s: *anim.Frame, b: canim.Rect, strip: bool) [5]?anim.Obj { + const w = canim.theme.stroke.rule; + return .{ + cover(s, .{ .x = b.x, .y = b.y, .w = b.w, .h = tag }), + cover(s, .{ .x = b.x, .y = b.y + tag, .w = w, .h = b.h - tag }), + cover(s, .{ .x = b.x + b.w - w, .y = b.y + tag, .w = w, .h = b.h - tag }), + cover(s, .{ .x = b.x, .y = b.y + b.h - w, .w = b.w, .h = w }), + if (strip) cover(s, .{ .x = b.x + b.w - canim.theme.strip.cost, .y = b.y + tag, .w = canim.theme.strip.cost - w, .h = b.h - tag - w }) else null, + }; +} + +/// Lifts `covers` one after another, `apart` frames apart, `each` frames each, from the cursor; the cursor after the last. +fn lift(s: *anim.Frame, covers: []const ?anim.Obj, apart: f32, each: f32) void { + const at = s.cursor; + var end = at; + for (covers, 0..) |o, i| if (o) |obj| { + s.cursor = at + f(apart * @as(f32, @floatFromInt(i))); + s.play(.{obj.fadeOut()}, .{ .seconds = f(each), .ease = anim.ease.linear }); + end = s.cursor; + }; + s.cursor = end; +} + +fn on(rec: *canim.Recording, from: u64, text: []const u8) u64 { + var buf: [256]u8 = undefined; + var i = from; + while (i < rec.end()) : (i += 1) if (rec.instruction(i, rec.register(i, "rip"), &buf)) |here| if (std.mem.indexOf(u8, here.text, text) != null) return i; + return from; +} + +/// A value at once, from the cursor. +fn set(s: *anim.Frame, v: anim.Value, to: f32) void { + s.play(.{v.to(to)}, .{ .seconds = 0 }); +} + +fn frame(s: *anim.Frame) void { + const rec = canim.open(recordings.list); + const reverse = rec.call("reverse", 0); + // Chapter I's moment: reverse's first call, whose push is walked here. + const moment = on(rec, reverse.enter, "call"); + var at = canim.cursor(s, rec, moment); + at.journey(.moment, moment + 1); + at.levels = .{ .fire = .disasm, .source_rows = 14 }; + // The working frame with no backtrace: the stack goes to the stage's foot under the registers. + var split = canim.layout.split.none; + split.backtrace.h = 0; + const ctx = canim.context(s, at, .{ .split = split }); + const sb = ctx.stage.first.stack; + const rb = ctx.stage.first.registers; + const rsp = rec.register(moment, "rsp"); + const rsp_after = rec.register(moment + 1, "rsp"); + // The window has two `free` words over rsp; rows from the panel's tag and padding. + const first = rsp - 16; + const top = sb.y + tag + pad; + const slots = canim.layout.rowsIn(sb.h); + const rowY = struct { + fn y(t0: f32, from: u64, addr: u64) f32 { + return t0 + row * @as(f32, @floatFromInt((addr - from) / 8)); + } + }.y; + + // What has not been said yet, under the page: the stack's offsets, the + // pins' lane under rsp's row, its tag, rules and strip; the registers' rows, tag and rules. + var offsets: [32]?anim.Obj = @splat(null); + var lane: [32]?anim.Obj = @splat(null); + const rsp_row = (rsp - first) / 8; + for (0..@min(slots, 32)) |k| { + const y = top + row * @as(f32, @floatFromInt(k)); + offsets[k] = cover(s, .{ .x = sb.x + 92, .y = y, .w = 84, .h = row }); + if (k > rsp_row) lane[k] = cover(s, .{ .x = sb.x + 2, .y = y, .w = 88, .h = row }); + } + const stack_chrome = chrome(s, sb, true); + var regs_rows: [16]?anim.Obj = @splat(null); + for (0..@min(canim.layout.rowsIn(rb.h), 16)) |k| + regs_rows[k] = cover(s, .{ .x = rb.x + 2, .y = rb.y + tag + pad + row * @as(f32, @floatFromInt(k)), .w = rb.w - 4, .h = row }); + const regs_chrome = chrome(s, rb, false); + + // Chapter I's last picture: the address space, the words with their chains, the link standing. + const space = s.new(canim.Segments.init(s, rec, moment)); + const dump = s.new(canim.Words.init(s, rec, moment)); + dump.panel = .{ .x = sb.x, .top = top, .first = first }; + const at_ = canim.regroup.at; + const tie = s.new(canim.segments.Place{ .segments = space, .addr = rsp, .x = at_.bracket, .y0 = at_.top + 2, .y1 = at_.top + 16 * 24 - 2, .clock = s.value(60), .quiet = s.value(24) }); + for ([_]anim.Value{ space.form, dump.placed }) |v| set(s, v, 1); + set(s, space.whole, 999); + for (space.rides) |v| set(s, v, 999); + for ([_]anim.Value{ dump.in, dump.ink, dump.chains }) |v| set(s, v, 999); + set(s, dump.regroup, 386); + set(s, dump.left, 24); + const objs = .{ place(s, space), place(s, dump), place(s, tie) }; + inline for (objs) |o| s.play(.{o.fadeIn()}, .{ .seconds = 0 }); + const main_word: canim.Rect = .{ .x = sb.x + canim.theme.metric.slot.address + 12 * 12 + canim.theme.metric.context.arrow_w, .y = rowY(top, rsp_after - 16, rsp + 8 * dump.walked), .w = 6 * 12, .h = row }; + const framed = place(s, s.new(Read{ .box = main_word })); + var asides: canim.Asides = .{}; + const left = canim.theme.canvas.margin_x; + + // II1: the address space and the link fade (18 f); the words glide into + // the stack's rows (36 f) and become the panel (12 f); then the push. + s.wait(t.beat); + s.play(.{ objs[0].fadeOut(), objs[2].fadeOut() }, .{ .seconds = f(18), .ease = anim.ease.linear }); + s.play(.{dump.become.to(1)}, .{ .seconds = f(36), .ease = anim.ease.linear }); + s.play(.{ ctx.stack.fadeIn(), objs[1].fadeOut() }, .{ .seconds = f(12), .ease = anim.ease.linear }); + asides.say(s, "`rsp` holds the address of the stack's top; a push moves it down a word.", left, rowY(top, first, rsp) + row / 2); + at.walk(s, .moment, moment + 1); + s.wait(t.beat); + + // II2: the address the call pushed, and main's under it; the offsets, a column. + asides.say(s, "Each call pushes where to come back to: `main+50` is main's.", left, main_word.y + row / 2); + s.play(.{framed.fadeIn()}, .{ .seconds = f(6), .ease = anim.ease.linear }); + s.wait(f(24)); + lift(s, &offsets, 2, 12); + s.wait(t.beat); + + // II3: a function's frame: rbp's pin, and the panel's tag, last. + asides.say(s, "A function's words are its frame: saved rbp, locals, the way back.", left, rowY(top, rsp_after - 16, rec.register(moment + 1, "rbp")) + row / 2); + s.play(.{framed.fadeOut()}, .{ .seconds = f(18), .ease = anim.ease.linear }); + s.cursor -= f(18); + lift(s, &lane, 2, 12); + s.wait(t.beat); + // `frame up`: its rules (12 f), then its tag and strip (12 f). + lift(s, stack_chrome[1..4], 0, 12); + lift(s, &.{ stack_chrome[0], stack_chrome[4] }, 0, 12); + s.wait(t.beat); + + // II4: the registers built over the stack, a row at a time, their tag last. + asides.say(s, "The registers are the other place values live: seventeen of them.", left, rb.y + tag + pad + row * 2.5); + s.play(.{ctx.registers.fadeIn()}, .{ .seconds = 0 }); + lift(s, ®s_rows, 12, 12); + lift(s, regs_chrome[1..4], 0, 12); + lift(s, &.{regs_chrome[0]}, 0, 12); + // The chapter's last picture. + s.wait(@max(asides.read_by - s.cursor, 0)); + s.wait(t.before_cut); +} diff --git a/anim/scenes/list.zig b/anim/scenes/list.zig index d3d53ed..6a51d45 100644 --- a/anim/scenes/list.zig +++ b/anim/scenes/list.zig @@ -76,7 +76,8 @@ fn frame(s: *anim.Frame) void { says.line(s, "`cur->next` takes `prev`, NULL:\nthe first node is now the end of the list."); at.walk(s, .line, rec.lineMoment(23, loaded)); says.line(s, "Then `prev` and `cur` each step one node along,\nand the loop comes round to the second node."); - at.walk(s, .line, second_trip); + // To the loop's test: the test passing runs with the second trip (a caption is up 12 s at most). + at.walk(s, .line, rec.lineMoment(20, rec.lineMoment(24, first_trip))); // Pacing: the second trip is the same, so hurried; it keeps its rest. says.line(s, "The second node, the same way, faster:\nits `next` turns back to the first."); const third_trip = rec.lineMoment(21, rec.lineMoment(24, second_trip)); @@ -85,7 +86,9 @@ fn frame(s: *anim.Frame) void { says.line(s, "The last node: its `next` turns too,\nback to the node before it."); at.walk(s, .line, rec.lineMoment(23, third_trip)); says.line(s, "`prev` takes the last node, and `cur` runs off the end\nof the list: NULL, so the loop ends."); - at.walk(s, .line, rec.lineMoment(26, third_trip)); + at.walk(s, .line, rec.lineMoment(20, rec.lineMoment(24, third_trip))); + // The test failing, said faster (a caption is up 12 s at most). + at.hurry(s, .line, rec.lineMoment(26, third_trip), .{ .veil = false }); says.line(s, "`head` takes the last node: the same three nodes,\nin the same places, read the other way."); at.walk(s, .line, end); says.close(s); diff --git a/anim/scenes/musl.zig b/anim/scenes/musl.zig index 3112a27..87c4fe5 100644 --- a/anim/scenes/musl.zig +++ b/anim/scenes/musl.zig @@ -51,10 +51,11 @@ fn frame(s: *anim.Frame) void { const joins = ctx.ties(s); canim.establish(s, .{ ctx.clock, ctx.registers, ctx.stack, ctx.source, ctx.disasm, log, joins }); + // What the captions do not name runs: main's prologue and the call's arguments (the syscalls scene walks them). says.line(s, "The same `hello`, built by Zig against musl, static."); - cur.walk(s, .line, rec.lineMoment(6, main.enter)); + cur.hurry(s, .line, rec.lineMoment(6, main.enter), .{}); says.line(s, "`main` calls `open` itself: no PLT stub, no GOT.\nmusl is compiled from its source with the program."); - cur.walk(s, .moment, call_open); + cur.hurry(s, .moment, call_open, .{}); canim.descent.step(cur, s, .moment); s.wait(t.phrase_rest); says.line(s, "musl's `open` is open.c: the source follows it."); @@ -64,8 +65,9 @@ fn frame(s: *anim.Frame) void { canim.descent.step(cur, s, .moment); s.wait(t.phrase_rest); says.line(s, "Which jumps on to `__syscall_cp_c`, in the same file."); - // __syscall_cp's few rows, and its jump on. - while (cur.moment(s) <= jump) canim.descent.step(cur, s, .moment); + // __syscall_cp's few rows at a run (its frame made and unmade), and its jump on walked. + cur.hurry(s, .moment, jump, .{}); + canim.descent.step(cur, s, .moment); s.wait(t.phrase_rest); says.line(s, "The `syscall` is one line of C, in syscall_arch.h:\nrax holds 2, open's number, and rdi the path."); cur.hurry(s, .moment, crossing - 2, .{}); diff --git a/anim/scenes/sort.zig b/anim/scenes/sort.zig index 454c3ad..38c2a7f 100644 --- a/anim/scenes/sort.zig +++ b/anim/scenes/sort.zig @@ -73,9 +73,11 @@ fn frame(s: *anim.Frame) void { at.hurry(s, .over, last_trip, .{ .pace = t.sprint, .from = t.run }); ctx.map.dive(s); - says.line(s, "The last value, 20: 26 > 20, so `jne` takes the swap."); + // Two captions: one would be up over 12 s across the three blocks. + says.line(s, "The last value, 20: `j > 0`, and 26 > 20,"); block(at, s); block(at, s); + says.line(s, "so `jne` takes the swap."); block(at, s); says.line(s, "The swap, and the inner loop turns once more."); block(at, s); diff --git a/anim/scenes/zoom.zig b/anim/scenes/zoom.zig index 8164b3b..42ef60d 100644 --- a/anim/scenes/zoom.zig +++ b/anim/scenes/zoom.zig @@ -55,6 +55,9 @@ fn frame(s: *anim.Frame) void { at.walk(s, .moment, call.enter); // The frame built under them, under a caption of its own (12 s at most). says.line(s, "The new frame saves `rbp` under them,\nthen stores its own `n`."); + // `push rbp` and the store walked; `mov rbp, rsp` and `sub rsp`, which it does not name, said faster. + at.walk(s, .moment, call.enter + 1); + at.hurry(s, .moment, call.enter + 3, .{ .veil = false }); at.walk(s, .moment, call.enter + 4); s.wait(canim.theme.time.beat); ctx.stage.releaseStack(s); |
