summaryrefslogtreecommitdiff
path: root/anim/scenes/column.zig
blob: db211a7a70e9df6a4eaed8bddce587453f3583d0 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
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 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);
}