summaryrefslogtreecommitdiff
path: root/anim/scenes/intro_registers.zig
diff options
context:
space:
mode:
Diffstat (limited to 'anim/scenes/intro_registers.zig')
-rw-r--r--anim/scenes/intro_registers.zig326
1 files changed, 326 insertions, 0 deletions
diff --git a/anim/scenes/intro_registers.zig b/anim/scenes/intro_registers.zig
new file mode 100644
index 0000000..326bcd0
--- /dev/null
+++ b/anim/scenes/intro_registers.zig
@@ -0,0 +1,326 @@
+//! The introduction, chapter II: registers (design/motion.md, "A scene: the
+//! introduction", II1 to II8; mocks 58 to 61), opening on chapter I's last
+//! picture at its seam (mock 62). The recording begins before I's moment:
+//! push(9) at line 11, its `mov edi, 0x10` and its `call malloc@plt`, then
+//! on to reverse's first instruction, where I's 128 bytes were read. The
+//! 128 bytes fold to the shelf while II's moments run, and come back as I
+//! left them once II reaches that instruction.
+//!
+//! II1 to II3 in the working frame with the text below, the address space
+//! in the program column: the registers built a row at a time, every
+//! register a row; rip, `frame up` and the clock; the stack's and the
+//! heap's registers, `segments` live (`◂ rip`, rbp and rsp in the stack's
+//! band). II4 to II8 beside, on the left, over push's rows at the program
+//! column's foot (no panel round them until III's `frame up`): rip and the
+//! row; rdi opened into its parts around `mov edi, 0x10` (`unpack`, the
+//! step, `pack`); `call malloc@plt` stepped over (its result first, then
+//! the wave); a continue to reverse; the quiet registers `fold`ed and the
+//! 128 bytes back at the rows III's stack will give them.
+const std = @import("std");
+const anim = @import("anim");
+const canim = @import("canim");
+const intro = @import("intro.zig");
+const memory = @import("intro_memory.zig");
+
+const t = canim.theme.time;
+const row = canim.theme.metric.context.row;
+const f = intro.f;
+const run = intro.run;
+const to = intro.to;
+const set = intro.set;
+const place = intro.place;
+const cover = intro.cover;
+const lift = intro.lift;
+
+/// The chapter's last picture, which chapter III opens on, and what III goes on with.
+pub const Two = struct {
+ ctx: canim.Context,
+ at: canim.Cursor,
+ registers: anim.Obj,
+ disasm: anim.Obj,
+ clock: anim.Obj,
+ /// The disassembly's tag, rules and strip, under the page until III's `frame up`.
+ disasm_chrome: [5]?anim.Obj,
+ dump: *canim.Words,
+ dump_obj: anim.Obj,
+ asides: canim.Asides,
+ e: f32,
+
+ /// The texts standing at its end.
+ pub fn texts(two: *const Two, s: *anim.Frame) []const anim.Obj {
+ return standing(s, &two.asides);
+ }
+};
+
+/// The texts `asides` has standing.
+pub fn standing(s: *anim.Frame, asides: *const canim.Asides) []const anim.Obj {
+ var out: std.ArrayList(anim.Obj) = .empty;
+ for (asides.shown[0..asides.n]) |o| if (o) |obj| out.append(s.arena, obj) catch {};
+ return out.items;
+}
+
+/// A register's place in the recording's registers, a bit each.
+fn bit(name: []const u8) u32 {
+ for (canim.ztrace.Regs.names, 0..) |known, i| if (std.mem.eql(u8, known, name)) return @as(u32, 1) << @intCast(i);
+ unreachable;
+}
+
+/// Row `k` of the registers panel (pwndbg's order, rip the 17th): its top.
+fn rowY(box: canim.Rect, k: f32) f32 {
+ return box.y + canim.theme.metric.context.tag + canim.theme.metric.context.pad + row * k;
+}
+
+/// From the seam's opening (the cursor), `e` the frame I's last text was read.
+pub fn chapter(s: *anim.Frame, rec: *canim.Recording, one: memory.One, title: intro.Title, label: intro.Label) Two {
+ const e = one.e;
+ // The moments: push(9)'s `mov edi, 0x10`, its call of malloc, the row after it, reverse's first instruction.
+ const push = rec.call("push", 0);
+ const start = intro.on(rec, push.enter, "edi, 0x10");
+ const call = start + 1;
+ const call_at = rec.register(call, "rip");
+ var back = call + 1;
+ while (back < rec.end() and rec.register(back, "rip") != call_at + 5) back += 1;
+ const reverse = rec.call("reverse", 0).enter;
+
+ // One set of registers for the four chapters: those II's steps change, with rsp, rbp and rip.
+ var moves: u32 = bit("rsp") | bit("rbp") | bit("rip");
+ for ([_][2]u64{ .{ start, call }, .{ call, back }, .{ back, reverse }, .{ reverse, reverse + 3 } }) |w| moves |= rec.registersChanged(w[0], w[1]);
+ moves &= (1 << 17) - 1;
+
+ var at = canim.cursor(s, rec, start);
+ at.journey(.moment, reverse + 3);
+ at.levels = .{ .fire = .disasm, .source_rows = 14, .introduction = true };
+ var split = canim.layout.split.none;
+ split.backtrace.h = 0;
+ const ctx = canim.context(s, at, .{ .split = split, .moves = moves });
+ // The code at the program column's foot: six rows, 712 to 888 (its rows 740 to 884).
+ const program = canim.theme.layout.program;
+ ctx.stage.first.disasm = .{ .x = program.x, .y = canim.theme.canvas.stage.y + canim.theme.canvas.stage.h - canim.layout.panelH(6), .w = program.w, .h = canim.layout.panelH(6) };
+
+ // The registers: every register a row, folded on II8; rdi opened into its parts on II5;
+ // rip, rbp, rsp, rax, rcx, rsi and rdi framed as read on their beats.
+ const fold = s.value(0);
+ const parts = s.new(canim.Registers.Parts{ .name = "rdi", .unpack = s.value(-1), .pack = s.value(-1), .echo = s.value(0) });
+ const framed_names = [_][]const u8{ "rip", "rbp", "rsp", "rax", "rcx", "rsi", "rdi" };
+ const framed = s.arena.alloc(canim.Registers.Framed, framed_names.len) catch unreachable;
+ for (framed, framed_names) |*fr, name| fr.* = .{ .name = name, .shows = s.value(0) };
+ const shows = struct {
+ fn of(all: []const canim.Registers.Framed, name: []const u8) anim.Value {
+ for (all) |fr| if (std.mem.eql(u8, fr.name, name)) return fr.shows;
+ unreachable;
+ }
+ }.of;
+ const registers = canim.add(s, canim.Registers{ .cursor = ctx.cursor, .stage = ctx.stage, .moves = moves, .fold = fold, .parts = parts, .framed = framed });
+ const mark_in = s.value(0);
+ const disasm = canim.add(s, canim.Disasm{ .cursor = ctx.cursor, .stage = ctx.stage, .mark_in = mark_in });
+ const clock = intro.clock(s, rec, ctx.cursor, ctx);
+ // The 128 bytes, over the registers from here (their tag crosses the panel when they come back).
+ const dump = one.dump;
+ const dump_obj = place(s, dump);
+
+ // What the beats have not reached, under the page: each register's name and its chain,
+ // rip's row, the panel's chrome; there with the panel, once the 128 bytes have left
+ // the state column (216), as the code's are with its rows (II's way into the code).
+ const opening = s.cursor;
+ s.cursor = e + f(216);
+ const rb = ctx.stage.first.registers;
+ var names: [16]?anim.Obj = undefined;
+ var chains: [16]?anim.Obj = undefined;
+ const name_w: f32 = 58;
+ for (0..16) |k| {
+ const y = rowY(rb, @floatFromInt(k));
+ names[k] = cover(s, .{ .x = rb.x + 2, .y = y, .w = name_w, .h = row });
+ chains[k] = cover(s, .{ .x = rb.x + 2 + name_w, .y = y, .w = rb.w - 4 - name_w, .h = row });
+ }
+ const rip_row = cover(s, .{ .x = rb.x + 2, .y = rowY(rb, 16), .w = rb.w - 4, .h = row });
+ const tall: canim.Rect = .{ .x = rb.x, .y = rb.y, .w = rb.w, .h = canim.layout.panelH(17) };
+ const regs_chrome = intro.chrome(s, tall, false);
+ s.play(.{registers.fadeIn()}, .{ .seconds = 0 });
+ s.cursor = opening;
+ const db = ctx.stage.first.disasm;
+ var code_rows: [6]?anim.Obj = undefined;
+ for (&code_rows, 0..) |*o, k| o.* = place(s, s.new(intro.Cover{ .box = .{ .x = db.x + 2, .y = db.y + canim.theme.metric.context.tag + canim.theme.metric.context.pad + row * @as(f32, @floatFromInt(k)), .w = db.w - 4, .h = row } }));
+ var disasm_chrome: [5]?anim.Obj = undefined;
+ for (&disasm_chrome, [_]canim.Rect{
+ .{ .x = db.x, .y = db.y, .w = db.w, .h = canim.theme.metric.context.tag },
+ .{ .x = db.x, .y = db.y + canim.theme.metric.context.tag, .w = canim.theme.stroke.rule, .h = db.h - canim.theme.metric.context.tag },
+ .{ .x = db.x + db.w - canim.theme.stroke.rule, .y = db.y + canim.theme.metric.context.tag, .w = canim.theme.stroke.rule, .h = db.h - canim.theme.metric.context.tag },
+ .{ .x = db.x, .y = db.y + db.h - canim.theme.stroke.rule, .w = db.w, .h = canim.theme.stroke.rule },
+ .{ .x = db.x + db.w - canim.theme.strip.cost, .y = db.y + canim.theme.metric.context.tag, .w = canim.theme.strip.cost - canim.theme.stroke.rule, .h = db.h - canim.theme.metric.context.tag - canim.theme.stroke.rule },
+ }) |*o, box| o.* = place(s, s.new(intro.Cover{ .box = box }));
+ // Echoes on the code: the pc's row's address (II4), the operand `edi` (II5).
+ const pc_shows = s.value(0);
+ const operand_shows = s.value(0);
+ const pc_read = place(s, s.new(intro.RowRead{ .addr = rec.register(start, "rip"), .x = 40, .w = 6 * 12, .shows = pc_shows }));
+ const operand_read = place(s, s.new(intro.RowRead{ .addr = rec.register(start, "rip"), .x = 264, .w = 3 * 12, .shows = operand_shows }));
+ const space = one.space;
+ space.pins = .{ .rip = s.value(0), .stack = s.value(0) };
+ const echo = struct {
+ fn add(sp: *canim.Segments, sf: *anim.Frame, addr: u64) anim.Value {
+ sp.echoes[sp.n_echoes] = .{ .addr = addr, .shows = sf.value(0) };
+ sp.n_echoes += 1;
+ return sp.echoes[sp.n_echoes - 1].shows;
+ }
+ }.add;
+ const code_echo = echo(space, s, rec.register(start, "rip"));
+ const stack_echo = echo(space, s, rec.register(start, "rsp"));
+ const heap_names = [_][]const u8{ "rax", "rcx", "rsi" };
+ var heap_echoes: [3]anim.Value = undefined;
+ for (&heap_echoes, heap_names) |*h, name| h.* = echo(space, s, rec.register(start, name));
+
+ inline for (.{ pc_read, operand_read }) |o| s.play(.{o.fadeIn()}, .{ .seconds = 0 });
+ s.cursor = opening;
+ // The opening (126 to 216): the dump's tie and link fade (18 f); its header comes
+ // back over its rows (12 f); the rows glide up into it, it becomes the tag, and
+ // the tag goes to the shelf over the program column (48 f): the bytes wait there,
+ // folded, while the chapter's moments run, which come before I's.
+ s.play(.{ one.objs[1].fadeOut(), dump_obj.fadeIn() }, .{ .seconds = 0 });
+ s.play(.{one.objs[2].fadeOut()}, .{ .seconds = f(18), .ease = anim.ease.linear });
+ s.play(.{dump.back.to(1)}, .{ .seconds = f(12), .ease = anim.ease.linear });
+ s.cursor = e + f(168);
+ run(s, dump.fold, 48);
+ title.out(s);
+
+ var says: canim.Narrator = .{};
+ const left = canim.theme.canvas.margin_x;
+
+ // II1: every register a row, top down, the name and then the chain (12 f each, 14 f apart).
+ const said = s.cursor;
+ says.line(s, "The CPU keeps sixteen words of its own, named, not addressed: the registers.");
+ s.cursor = said + t.caption_in + t.caption_lead;
+ const rows_from = s.cursor;
+ for (0..16) |k| {
+ s.cursor = rows_from + f(14 * @as(f32, @floatFromInt(k)));
+ lift(s, &.{names[k]}, 0, 12);
+ s.cursor = rows_from + f(14 * @as(f32, @floatFromInt(k)) + 6);
+ lift(s, &.{chains[k]}, 0, 12);
+ }
+
+ // II2: rip's row, its value framed, list's code band and its row framed and `◂ rip`;
+ // `frame up` on the registers; the clock comes, and the label goes beside it.
+ says.line(s, "And `rip`: where the CPU is, an address in list's code.");
+ lift(s, &.{rip_row}, 0, 12);
+ to(s, shows(framed, "rip"), 1, 6);
+ s.wait(f(24));
+ to(s, code_echo, 1, 6);
+ to(s, space.pins.?.rip, 1, 12);
+ s.wait(f(72));
+ to(s, shows(framed, "rip"), 0, 18);
+ to(s, code_echo, 0, 18);
+ s.wait(f(18));
+ lift(s, regs_chrome[1..4], 0, 12);
+ lift(s, &.{regs_chrome[0]}, 0, 12);
+ // The label leaves where it stood alone (12 f), then comes beside the count as the clock comes (12 f).
+ s.play(.{label.docked.to(1)}, .{ .seconds = f(24), .ease = anim.ease.linear });
+ s.cursor -= f(12);
+ s.play(.{clock.fadeIn()}, .{ .seconds = f(12), .ease = anim.ease.linear });
+
+ // II3: rbp and rsp framed, the stack's band and its row, their pin in it; held;
+ // then rax, rcx and rsi at a run, each framed with the heap's band.
+ says.line(s, "`rsp` and `rbp` point into the stack,\n`rax`, `rcx` and `rsi` into the heap.");
+ to(s, shows(framed, "rbp"), 1, 6);
+ s.wait(f(6));
+ to(s, shows(framed, "rsp"), 1, 6);
+ s.wait(f(18));
+ to(s, stack_echo, 1, 6);
+ to(s, space.pins.?.stack, 1, 12);
+ s.wait(f(102));
+ for ([_][]const u8{ "rbp", "rsp" }) |name| to(s, shows(framed, name), 0, 18);
+ to(s, stack_echo, 0, 18);
+ s.wait(f(24));
+ const heaps = s.cursor;
+ for (heap_names, heap_echoes, 0..) |name, h, k| {
+ s.cursor = heaps + f(2 * @as(f32, @floatFromInt(k)));
+ to(s, shows(framed, name), 1, 4);
+ to(s, h, 1, 4);
+ s.wait(f(4));
+ to(s, shows(framed, name), 0, 8);
+ to(s, h, 0, 8);
+ }
+ s.cursor = heaps + f(2 * 2 + 12);
+
+ // Into the code: the text leaves; the address space goes with its pins; push's six rows
+ // round the pc arrive at the program column's foot (12 f each, 2 f apart), no panel round them.
+ s.wait(@max(says.read_by - s.cursor, 0));
+ s.play(.{says.current.?.fadeOut()}, .{ .seconds = t.caption_out, .ease = canim.ease.exit });
+ s.wait(f(6));
+ s.play(.{one.objs[0].fadeOut()}, .{ .seconds = f(18), .ease = anim.ease.linear });
+ s.wait(f(6));
+ s.play(.{disasm.fadeIn()}, .{ .seconds = 0 });
+ intro.show(s, &code_rows);
+ intro.show(s, &disasm_chrome);
+ lift(s, &code_rows, 2, 12);
+
+ var asides: canim.Asides = .{ .floor = ctx.stage.first.disasm.y - 12 };
+ const level = struct {
+ /// Level with row `k` of the registers (`room` rows lower for an opened register's parts), under the shelf.
+ fn of(box: canim.Rect, k: f32) f32 {
+ return @max(rowY(box, k) + row / 2, 124);
+ }
+ }.of;
+
+ // II4: the pc's mark comes to its row; rip's value and the row's address framed together.
+ asides.say(s, "`rip` holds this row's address: the next to run, in push(9).", left, level(rb, 16));
+ // (Eased: its first frame barely there, as the mark's own in is.)
+ s.play(.{mark_in.to(1)}, .{ .seconds = f(12), .ease = canim.ease.glide });
+ to(s, shows(framed, "rip"), 1, 6);
+ to(s, pc_shows, 1, 6);
+ s.wait(f(102));
+ to(s, shows(framed, "rip"), 0, 18);
+ to(s, pc_shows, 0, 18);
+
+ // II5: rdi framed (push's argument); `unpack`; `mov edi, 0x10` walked, the byte that changes
+ // struck with the row's annotation; `pack`.
+ asides.say(s, "`rdi` holds push's argument, 9. Its low four bytes are `edi`, as `eax` are `rax`'s.", left, level(rb, 5));
+ to(s, shows(framed, "rdi"), 1, 6);
+ s.wait(f(12));
+ to(s, shows(framed, "rdi"), 0, 12);
+ run(s, parts.unpack, 54);
+ s.wait(f(24));
+ var plan = at.planned(start, call, false);
+ plan.at[0] = f(36);
+ plan.advance = f(72);
+ plan.total = plan.advance + plan.travel + t.rest;
+ const stepped = s.cursor;
+ at.step(s, call, plan, plan.total);
+ const after_step = s.cursor;
+ s.cursor = stepped + f(18);
+ to(s, parts.echo, 1, 6);
+ to(s, operand_shows, 1, 6);
+ s.cursor = stepped + plan.advance;
+ to(s, parts.echo, 0, 12);
+ to(s, operand_shows, 0, 12);
+ s.cursor = stepped + f(102);
+ run(s, parts.pack, 36);
+ s.cursor = @max(s.cursor, after_step);
+
+ // II6: `call malloc@plt` stepped over: rdi framed with the argument hanging under the call;
+ // rax struck with the result, the row's C form with it; the others in a wave.
+ asides.say(s, "Arguments go in `rdi`, `rsi`…; the result comes back in `rax`.", left, level(rb, 0));
+ const over = s.cursor;
+ s.cursor = over + f(18);
+ to(s, shows(framed, "rdi"), 1, 6);
+ s.cursor = over + f(48);
+ to(s, shows(framed, "rdi"), 0, 6);
+ s.cursor = over;
+ at.over(s, back);
+
+ // II7: on to reverse's first instruction, a continue: the wave, the code fading through.
+ asides.say(s, "On, into `reverse()`: `rsp` and `rbp` move with the calls.", left, level(rb, 7));
+ at.@"continue"(s, reverse);
+
+ // II8: the registers the scene never changes fold, three to a row, under a rule; then the
+ // 128 bytes come back from the shelf, as I left them, at the rows III's stack gives them.
+ asides.say(s, "Registers we will not follow fold, three to a row. We are back where the 128 bytes were read.", left, level(rb, 6));
+ s.play(.{fold.to(1)}, .{ .seconds = f(36), .ease = anim.ease.linear });
+ s.play(.{fold.to(4.0 / 3.0)}, .{ .seconds = f(12), .ease = anim.ease.linear });
+ s.wait(f(12));
+ // rsp's word at 480: four free rows over it in III's stack, under the registers' eleven rows.
+ const stack_top = rb.y + canim.layout.panelH(11) + canim.theme.canvas.row_gap + canim.theme.metric.context.tag + canim.theme.metric.context.pad;
+ set(s, dump.top, stack_top + 4 * row);
+ s.play(.{dump.fold.to(0)}, .{ .seconds = f(48), .ease = anim.ease.linear });
+ s.play(.{dump.back.to(0)}, .{ .seconds = f(12), .ease = anim.ease.linear });
+ s.wait(@max(asides.read_by - s.cursor, 0));
+
+ return .{ .ctx = ctx, .at = at, .registers = registers, .disasm = disasm, .clock = clock, .disasm_chrome = disasm_chrome, .dump = dump, .dump_obj = dump_obj, .asides = asides, .e = s.cursor };
+}