//! 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 }; }