summaryrefslogtreecommitdiff
path: root/anim/scenes
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-11 20:08:07 -0300
committerGabriel Schneider <[email protected]>2026-11-11 21:45:12 -0300
commit15de88cf82c187635c1989e91bfa639a10304066 (patch)
tree16fa83854258c0c6aec1dff7f70ebabf5fd64c09 /anim/scenes
parent0ec2376cae2fdfc50e90d930ebc86c7a5b7f5594 (diff)
downloadcomputeranim-15de88cf82c187635c1989e91bfa639a10304066.tar.gz
computeranim-15de88cf82c187635c1989e91bfa639a10304066.zip
canim: a column of text as an experiment; the disassembly tied to the stack
From the user. A scene may set its text in a column beside the panes a beat is about: col.beat names the panes and their rows, where the text is placed (beside, below, above, or on a drawing) and what it is level with; panes the beat leaves out fold to their title bars on a shelf, their changes struck there. Tried as two scenes beside the originals: the call followed down (column) and a bubble on sort's rings (column_sort). annotation = .tied names the word an instruction touched and draws a touch to its stack row; offsets count from the frame's base; rsp's pin travels with its amount before the stack follows; .whole keeps the full chain. carry = .arrow draws a value's way between memory and a register. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNCKgYCGiANnEwcEQxa
Diffstat (limited to 'anim/scenes')
-rw-r--r--anim/scenes/column.zig133
-rw-r--r--anim/scenes/column_sort.zig59
-rw-r--r--anim/scenes/gallery.zig2
-rw-r--r--anim/scenes/heap.zig3
-rw-r--r--anim/scenes/sqlite.zig3
-rw-r--r--anim/scenes/zoom.zig5
6 files changed, 202 insertions, 3 deletions
diff --git a/anim/scenes/column.zig b/anim/scenes/column.zig
new file mode 100644
index 0000000..b1a8df7
--- /dev/null
+++ b/anim/scenes/column.zig
@@ -0,0 +1,133 @@
+//! The column, a trial (design/motion.md, "A scene in the column: `open`
+//! followed down"): the syscalls scene's story told beat by beat with the
+//! panes each beat is about in one column and its text beside them, level
+//! with the row it speaks of, the rest folded to their tags on the shelf.
+//! The same recording and the same steps as `syscalls`; the scene's
+//! choices, a beat at a time, are the storyboard's table (C1 to C12):
+//! the opening and the close the working frame whole, its caption below.
+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 {});
+
+/// The first moment from `from` whose pc is named `name` (`open@plt+0`).
+fn at(rec: *canim.Recording, from: u64, name: []const u8) u64 {
+ var i = from;
+ while (i < rec.end()) : (i += 1) if (std.mem.eql(u8, rec.strings.get(rec.register(i, "rip")) orelse "", name)) return i;
+ return rec.end();
+}
+
+/// The first moment from `from` whose instruction is `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();
+}
+
+fn frame(s: *anim.Frame) void {
+ const rec = canim.open(recordings.hello);
+ const main = rec.call("main", 0);
+ var cur = canim.cursor(s, rec, main.enter);
+ const stub = at(rec, main.enter, "open@plt+0");
+ const crossing = on(rec, stub, "syscall");
+ const back = on(rec, crossing, "ret");
+ const done = rec.lineMoment(10, back);
+ const call = rec.register(stub - 1, "rip");
+ cur.journey(.moment, done);
+ cur.levels = .{ .source_rows = 8, .fire = .disasm };
+ const ctx = canim.context(s, cur, .{ .split = canim.layout.split.beside, .syscalls = true, .descent = true });
+ const log = canim.crossing(s, .{ .cursor = cur, .stage = ctx.stage, .focus = true });
+ ctx.map.add(s, canim.Crossing{ .cursor = cur, .stage = ctx.map.stage });
+ const col = canim.column(s, ctx, .{ .lens = log, .titles = .{ .band = "system calls", .view = "its bytes" } });
+ const t = canim.theme.time;
+ const joins = ctx.ties(s);
+ canim.establish(s, .{ ctx.clock, ctx.registers, ctx.stack, ctx.source, ctx.disasm, log, joins });
+ const rest = canim.column_rest;
+ const regs: u32 = @intFromFloat(ctx.stage.registers_rows);
+
+ // C1: the working frame whole, its caption below.
+ col.beat(s, .{ .at = .below, .say = "A program cannot open a file itself.\nIt asks the kernel, and waits." });
+ cur.walk(s, .line, rec.lineMoment(6, main.enter));
+ // 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`.",
+ .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.",
+ });
+ 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 } } });
+ 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 } },
+ .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`.",
+ .stem = .none,
+ .notes = &.{ .{ .band, "none yet" }, .{ .view, "`\"note\"`" } },
+ });
+ 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`.",
+ .level = .floor,
+ .stem = .none,
+ .notes = &.{ .{ .band, "none yet" }, .{ .view, "`\"note\"`" } },
+ });
+ canim.descent.step(cur, s, .moment);
+ s.wait(t.phrase_rest);
+ // C8: back up; the bubble climbs back to main's call row.
+ col.beat(s, .{
+ .panes = &.{ .{ .source, 3 }, .{ .disasm, 11 }, .{ .stack, rest } },
+ .say = "open's `ret` comes straight back to main: the stub was a jump, not a call. main keeps the answer in `f`.",
+ .level = .{ .row = call },
+ .stem = .none,
+ .notes = &.{ .{ .band, "`openat(…) = 3`" }, .{ .view, "" } },
+ });
+ cur.hurry(s, .moment, back, .{});
+ canim.descent.step(cur, s, .moment);
+ s.wait(t.phrase_rest);
+ cur.walk(s, .line, rec.lineMoment(7, back));
+
+ // C9 to C11: the other three stepped over, each beside its call row,
+ // its bytes over the source.
+ const lines = [_][]const u8{
+ "`read`: the kernel copies the file's bytes into `buf`, and says how many.",
+ "`close`: the number is handed back.",
+ "`write`: the same bytes go the other way, from `buf` to file number 1, the output.",
+ };
+ for (lines) |line| {
+ const here = cur.moment(s);
+ col.beat(s, .{
+ .panes = &.{ .{ .view, 3 }, .{ .source, 3 }, .{ .disasm, rest } },
+ .say = line,
+ .level = .{ .row = rec.register(on(rec, here, "call"), "rip") },
+ .notes = &.{.{ .band, "the calls so far" }},
+ });
+ canim.syscalls.step(cur, s, .line);
+ s.wait(t.phrase_rest);
+ }
+ // C12: the working frame whole again, to main's return.
+ col.beat(s, .{ .at = .below, .say = "" });
+ cur.walk(s, .line, done);
+ col.close(s);
+}
diff --git a/anim/scenes/column_sort.zig b/anim/scenes/column_sort.zig
new file mode 100644
index 0000000..d851172
--- /dev/null
+++ b/anim/scenes/column_sort.zig
@@ -0,0 +1,59 @@
+//! The column's wide placements, on sort's rings (design/README.md,
+//! "column (an experiment)", mock 55): the opening in the working frame
+//! (the `blocks` lens), then the drawing across both columns twice its size,
+//! the rest folded to the shelf, a beat's text `on` it, in the corner the
+//! rings leave free, its stem round the drawing's outside to the pc's block;
+//! then a beat `above` it; then the working frame again. The steps are
+//! sort's own: its first trip round the inner loop, a block at a time.
+const anim = @import("anim");
+const canim = @import("canim");
+const recordings = @import("recordings");
+
+pub const background = canim.background;
+pub const scene = anim.Live(frame, struct {});
+
+fn frame(s: *anim.Frame) void {
+ const rec = canim.open(recordings.sort);
+ const graph = canim.graph;
+ // As the sort scene opens: the `while`, about to compare 31 with 12.
+ var start = rec.call("sort", 0).enter;
+ while (rec.next(.over, rec.next(.over, start)) < rec.call("swap", 0).enter) start = rec.next(.over, start);
+ var at = canim.cursor(s, rec, start);
+ at.levels = .{ .fire = .disasm, .source_rows = 6 };
+ at.journey(.over, rec.call("swap", 0).exit.?);
+ const ctx = canim.context(s, at, .{ .split = canim.layout.split.blocks, .graph = true });
+ const blocks = canim.add(s, graph.Blocks{ .cursor = at, .stage = ctx.stage, .focus = true });
+ const col = canim.column(s, ctx, .{ .lens = blocks, .titles = .{ .band = "its blocks" }, .at = .below });
+ const joins = ctx.ties(s);
+ const block = struct {
+ fn walk(c: canim.Cursor, f: *anim.Frame) void {
+ graph.toEnd(c, f);
+ graph.leave(c, f);
+ }
+ /// The block the pc is in, by its first instruction's address.
+ fn here(c: canim.Cursor, f: *anim.Frame) u64 {
+ const i = c.moment(f);
+ const pc = c.rec.register(i, "rip");
+ const g = graph.read(f.arena, c.rec, i, pc) orelse return pc;
+ return g.nodes[g.nodeOf(pc) orelse return pc].start;
+ }
+ };
+
+ canim.establish(s, .{ ctx.clock, ctx.registers, ctx.stack, ctx.source, ctx.disasm, blocks, joins });
+ col.beat(s, .{ .say = "`sort` as its blocks: each loop a ring, the inner touching\nthe outer. `j > 0`, so `jle` goes on to the compare." });
+ block.walk(at, s);
+ // `on`: the drawing across both columns, the text in the corner the rings leave free.
+ col.beat(s, .{
+ .at = .on,
+ .say = "31 > 12: `setg` leaves 1,\nand `jne` takes the swap,\nthe first time it is reached.",
+ .where = .{ 104, 144 },
+ .level = .{ .block = block.here(at, s) },
+ });
+ block.walk(at, s);
+ block.walk(at, s);
+ // `above`: the text leads the eye in at the top.
+ col.beat(s, .{ .at = .above, .say = "The swap and `j--`; then the inner loop turns, back up to `j > 0`: its first turn." });
+ block.walk(at, s);
+ col.beat(s, .{ .at = .below, .say = "" });
+ col.close(s);
+}
diff --git a/anim/scenes/gallery.zig b/anim/scenes/gallery.zig
index 17d38ed..f6e4d9d 100644
--- a/anim/scenes/gallery.zig
+++ b/anim/scenes/gallery.zig
@@ -422,6 +422,8 @@ fn frame(s: *anim.Frame) void {
s.play(.{pages.fadeIn()}, .{ .seconds = 0 });
var at = canim.cursor(s, rec, rest);
+ // Its pictures are the frame as `test/gallery` keeps them: pwndbg's chains, offsets from rsp.
+ at.levels.annotation = .whole;
// Its way, the one step it takes: the registers that step does not change are folded.
at.journey(.line, rec.next(.line, rest));
const ctx = canim.context(s, at, .{ .split = canim.layout.split.beside, .quiet = true });
diff --git a/anim/scenes/heap.zig b/anim/scenes/heap.zig
index d42da12..6e521d0 100644
--- a/anim/scenes/heap.zig
+++ b/anim/scenes/heap.zig
@@ -423,7 +423,8 @@ fn frame(s: *anim.Frame) void {
// From main's first line, `push(7)`.
var at = canim.cursor(s, rec, rec.lineMoment(24, main.enter));
at.journey(.line, rec.lineMoment(30, main.enter));
- at.levels = .{ .idea = .data, .source_rows = 8 };
+ // The allocator's words are the story, by their addresses: pwndbg's chains (`annotation = .whole`).
+ at.levels = .{ .idea = .data, .source_rows = 8, .annotation = .whole };
const ctx = canim.context(s, at, .{ .split = canim.layout.split.subject });
// `head`, the program's global: where line 13 (`n->next = head;`) reads it, `[rip + X]`.
const head_at = globalOf(rec, lineIn(rec, "push", 0, 13));
diff --git a/anim/scenes/sqlite.zig b/anim/scenes/sqlite.zig
index 36630bd..dab127a 100644
--- a/anim/scenes/sqlite.zig
+++ b/anim/scenes/sqlite.zig
@@ -103,7 +103,8 @@ fn frame(s: *anim.Frame) void {
const start = stopAt(rec, "sqlite3_step+", first);
var at = canim.cursor(s, rec, start);
- at.levels = .{ .source_rows = 8 };
+ // Where a row's bytes go is the story, by their addresses: pwndbg's chains (`annotation = .whole`).
+ at.levels = .{ .source_rows = 8, .annotation = .whole };
at.journey(.moment, back);
// The lens is the subject: the backtrace, eleven rows, over the
// program column (where the kernel's side comes later), and over the
diff --git a/anim/scenes/zoom.zig b/anim/scenes/zoom.zig
index 426d3a3..8164b3b 100644
--- a/anim/scenes/zoom.zig
+++ b/anim/scenes/zoom.zig
@@ -36,8 +36,11 @@ fn frame(s: *anim.Frame) void {
const joins = ctx.ties(s);
canim.establish(s, .{ ctx.clock, ctx.registers, ctx.stack, ctx.backtrace, ctx.source, ctx.disasm, joins });
says.line(s, "A line of C is a handful of instructions.\nThis one calls `fib(n-1)`: follow it down.");
- // The CPU's level: an instruction a step. The argument is worked out in `rdi`.
+ // The CPU's level: an instruction a step. The argument is worked out in `rdi`,
+ // `n` carried into it from its word first (`carry`, for this beat).
+ at.levels.carry = .arrow;
at.walk(s, .moment, call.enter - 1);
+ at.levels.carry = .off;
says.line(s, "`call` writes eight bytes on the stack: the way back.");
// The stack holds still under the camera, set before it moves: six free