diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-11 20:08:07 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-11 21:45:12 -0300 |
| commit | 15de88cf82c187635c1989e91bfa639a10304066 (patch) | |
| tree | 16fa83854258c0c6aec1dff7f70ebabf5fd64c09 /anim/scenes | |
| parent | 0ec2376cae2fdfc50e90d930ebc86c7a5b7f5594 (diff) | |
| download | computeranim-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.zig | 133 | ||||
| -rw-r--r-- | anim/scenes/column_sort.zig | 59 | ||||
| -rw-r--r-- | anim/scenes/gallery.zig | 2 | ||||
| -rw-r--r-- | anim/scenes/heap.zig | 3 | ||||
| -rw-r--r-- | anim/scenes/sqlite.zig | 3 | ||||
| -rw-r--r-- | anim/scenes/zoom.zig | 5 |
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 |
