diff options
Diffstat (limited to 'anim/scenes/column.zig')
| -rw-r--r-- | anim/scenes/column.zig | 133 |
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); +} |
