summaryrefslogtreecommitdiff
path: root/anim/scenes/syscalls.zig
blob: db670459a8698f182185257f4c3edcbe0759dd90 (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
//! A program that needs the kernel four times: open, read, close, write.
//! glibc's `hello`, by instruction from main: `open` followed down (the
//! disassembly a `descent`: main's call, the PLT's stub, libc's wrapper,
//! the kernel's window at the floor, and back up), then the other three
//! stepped over, each crossing under its call. The band is the calls so
//! far, as strace writes them.
//!
//! How it moves (design/motion.md, "A call followed down", "A system
//! call"): no effect before its cause. Each beat has its caption first;
//! the call row's plaque becomes a ring and the lane draws down to the
//! callee's head before its rows come; the registers that carry the call
//! are framed one at a time; the crossing lane goes down before the
//! kernel's window opens; `returns` has the value before rax is struck.
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);
    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 });
    var says: canim.Narrator = .{};
    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 });

    says.line(s, "A program cannot open a file itself.\nIt asks the kernel, and waits.");
    cur.walk(s, .line, rec.lineMoment(6, main.enter));
    cur.walk(s, .moment, stub - 1);
    says.line(s, "`main` calls `open` by its stub in the PLT. The arguments\nare in rdi and rsi: \"note\" and O_RDONLY.");
    canim.descent.step(cur, s, .moment);
    s.wait(t.phrase_rest);
    says.line(s, "The call went down: main's window keeps its call, ringed;\nthe stub's jmp reads the GOT, and goes on to libc.");
    canim.descent.step(cur, s, .moment);
    s.wait(t.phrase_rest);
    says.line(s, "libc's `open` is a wrapper: it puts openat's number in rax\nand its arguments in rdi, rsi, rdx and r10.");
    cur.hurry(s, .moment, crossing, .{});
    says.line(s, "`syscall` crosses down. The kernel opens the file\nand answers in rax: 3, the descriptor.");
    canim.descent.step(cur, s, .moment);
    s.wait(t.phrase_rest);
    cur.hurry(s, .moment, back, .{});
    says.line(s, "`open`'s ret comes straight back to main: the stub\nwas a jump, not a call. The windows close up.");
    canim.descent.step(cur, s, .moment);
    s.wait(t.phrase_rest);

    // The other three, stepped over: each crossing opens under its call.
    const lines = [_][]const u8{
        "`read`: the kernel copies the file's bytes into `buf`,\nand says how many.",
        "`close`: the number is handed back.",
        "`write`: the same bytes go the other way,\nfrom `buf` to file number 1, the output.",
    };
    cur.walk(s, .line, rec.lineMoment(7, back));
    for (lines) |line| {
        says.line(s, line);
        canim.syscalls.step(cur, s, .line);
        s.wait(t.phrase_rest);
    }
    cur.walk(s, .line, done);
    says.close(s);
}