//! 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 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 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 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, 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, 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\"` 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 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); }