summaryrefslogtreecommitdiff
path: root/anim/scenes/column.zig
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/column.zig
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/column.zig')
-rw-r--r--anim/scenes/column.zig133
1 files changed, 133 insertions, 0 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);
+}