//! Two pages of the Intel SDM (Vol. 2) as a talk, in two slides. The //! pages are Typst's import of the PDF, every glyph and rule a vector //! shape; what moves are `part`s of them, cut out by rectangles in the //! page's units (read off the player's guides and `pdftotext -bbox`, //! points to units: (pt - 306) * 4/3 across, (pt - 396) * 4/3 down). //! //! 1. Figure 2-1, the instruction format (page 31), comes alive: `83 C0 //! 01`, `add eax, 1`, is written below, its bytes fly into their //! fields, and C0 splits into its ModR/M bits. //! 2. ADD's opcode table (page 132) is written row by row; its row `80 /0 //! ib` becomes SUB's `80 /5 ib` (page 1400): the digit first, alone, //! then the rest of the row, and the two rows end one over the other. //! //! The PDF is the build's `-Dmanual` (`~/01-resources/intel-devref-ii.pdf` //! by default) and is never committed; without it the scene says so. //! //! click, space, page down next step page up back //! ] / [ next / previous slide const std = @import("std"); const anim = @import("anim"); const pdf: ?[]const u8 = @import("manual").pdf; pub const name = "manual"; pub const hold = 1.5; pub const typst_preamble = \\#set page(width: auto, height: auto, margin: 0pt, fill: none) \\#set text(font: "DejaVu Sans Mono", size: 14pt, fill: rgb("#c0392b")) ; pub const typst = struct { pub const page = "#image(\"" ++ (pdf orelse "") ++ "\", page: 31)"; pub const title = "#text(font: \"New Computer Modern\", size: 40pt, fill: rgb(\"#ece6e2\"))[Figure 2-1, alive]"; pub const from = "#text(font: \"New Computer Modern\", size: 16pt, fill: rgb(\"#8c8c8c\"))[IntelĀ® 64 and IA-32 SDM, Vol. 2, page 31]"; pub const add = "#text(fill: rgb(\"#555555\"))[add eax, 1]"; pub const b83 = "83"; pub const c0 = "C0"; pub const b01 = "01"; pub const bits = "11000000"; pub const direct = "#text(size: 8pt, fill: rgb(\"#555555\"))[direct]"; pub const is_add = "#text(size: 8pt, fill: rgb(\"#555555\"))[/0 ADD]"; pub const eax = "#text(size: 8pt, fill: rgb(\"#555555\"))[EAX]"; pub const add_page = "#image(\"" ++ (pdf orelse "") ++ "\", page: 132)"; pub const sub_page = "#image(\"" ++ (pdf orelse "") ++ "\", page: 1400)"; pub const table_title = "#text(font: \"New Computer Modern\", size: 40pt, fill: rgb(\"#ece6e2\"))[ADD, then SUB]"; pub const table_from = "#text(font: \"New Computer Modern\", size: 16pt, fill: rgb(\"#8c8c8c\"))[IntelĀ® 64 and IA-32 SDM, Vol. 2, pages 132 and 1400]"; pub const group = "#text(font: \"New Computer Modern\", size: 11pt, fill: rgb(\"#555555\"))[One opcode byte, 80: the reg field of the ModR/M byte picks the operation]"; }; const missing = struct { pub const note = "#text(font: \"New Computer Modern\", size: 24pt, fill: rgb(\"#ece6e2\"))[No manual: build with `-Dmanual=/path/to/intel-sdm-vol2.pdf`]"; }; pub const scene = anim.Live(if (pdf == null) placeholder else talk, if (pdf == null) missing else typst); fn placeholder(s: *anim.Frame) void { s.play(.{s.typst(missing.note, .{}).write()}, .{}); } /// Rectangles in the page's units, as `s.part` and `s.rect` take them. const Area = struct { x: f32, y: f32, w: f32, h: f32 }; /// The labels of the figure's top row of fields: Prefixes, Opcode, /// ModR/M, SIB, Displacement, Immediate (inside the rules, which stay). const fields = [_]Area{ .{ .x = -199.5, .y = -110.7, .w = 69.3, .h = 33.3 }, .{ .x = -127.5, .y = -110.7, .w = 69.3, .h = 33.3 }, .{ .x = -55.5, .y = -110.7, .w = 69.3, .h = 33.3 }, .{ .x = 16.5, .y = -110.7, .w = 69.3, .h = 33.3 }, .{ .x = 100.5, .y = -110.7, .w = 93.3, .h = 33.3 }, .{ .x = 184.9, .y = -110.7, .w = 70.1, .h = 33.3 }, }; const opcode = 1; const modrm = 2; const immediate = 5; /// The ModR/M byte's own boxes: Mod, Reg/Opcode, R/M. const bit_boxes = [_]Area{ .{ .x = -144.0, .y = 5.3, .w = 33.3, .h = 25.3 }, .{ .x = -102.0, .y = 5.3, .w = 45.3, .h = 25.3 }, .{ .x = -53.7, .y = 5.3, .w = 46.0, .h = 25.3 }, }; /// The ModR/M byte's three boxes together, across. const byte_x = -95.7; /// The figure: both rows of boxes, the arrows and the notes; and its /// footnotes, under it. const figure: Area = .{ .x = -7.3, .y = -54.7, .w = 468, .h = 160 }; const footnotes: Area = .{ .x = -8, .y = 70.7, .w = 453, .h = 56 }; /// `11000000` in its own units: 8 characters of 0.6 em at 14 pt. const char = 0.6 * 14 * 4.0 / 3.0; fn talk(s: *anim.Frame) void { s.slide(); instructionFormat(s); s.pause(); s.clear(.{ .seconds = 0.8 }); s.slide(); opcodeTable(s); } /// Slide 1: Figure 2-1 comes alive. fn instructionFormat(s: *anim.Frame) void { // The page, whole, on paper; the camera far enough out to see it all. const paper = s.rect(.{ .w = 816, .h = 1056, .fill = 0xffffff }); const page = s.typst(typst.page, .{}); const title = s.typst(typst.title, .{ .x = -700, .y = -380 }); const from = s.typst(typst.from, .{ .x = -700, .y = -325 }); // A tint over each field's label box (the same rectangle as its part), // laid before the parts so that they draw over it. var tints: [fields.len]anim.Obj = undefined; for (&tints, fields) |*t, f| t.* = s.rect(.{ .x = f.x, .y = f.y, .w = f.w, .h = f.h, .fill = 0x58c4dd60 }); s.play(.{anim.camera(.{ .zoom = 0.65 })}, .{ .seconds = 0 }); s.play(.{ title.write(), from.fadeIn(), paper.fadeIn(), page.fadeIn() }, .{ .seconds = 2 }); s.pause(); // Onto the figure. Its labels, the ModR/M byte's boxes, the figure // around them and its footnotes become parts of the page; the rest of // the page greys, and the footnotes go, to make room. var labels: [fields.len]anim.Obj = undefined; for (&labels, fields) |*l, f| l.* = s.part(page, f); var boxes: [bit_boxes.len]anim.Obj = undefined; for (&boxes, bit_boxes) |*b, area| b.* = s.part(page, area); _ = s.part(page, figure); const notes = s.part(page, footnotes); s.play(.{ anim.camera(.{ .zoom = 2.3, .x = -7, .y = -35 }), page.move(.{ .opacity = 0.25 }), notes.fadeOut(), title.fadeOut(), from.fadeOut() }, .{ .seconds = 1.5 }); s.pause(); // Each field in turn. for (labels, tints, 0..) |label, tint, i| { if (i > 0) s.play(.{ tints[i - 1].fadeOut(), label.indicate(), tint.fadeIn() }, .{}) else s.play(.{ label.indicate(), tint.fadeIn() }, .{}); s.pause(); } s.play(.{tints[fields.len - 1].fadeOut()}, .{ .seconds = 0.5 }); // An instruction: add eax, 1. const b83 = s.typst(typst.b83, .{ .x = -40, .y = 70 }); const c0 = s.typst(typst.c0, .{ .y = 70 }); const b01 = s.typst(typst.b01, .{ .x = 40, .y = 70 }); const add = s.typst(typst.add, .{ .x = 150, .y = 70 }); s.play(.{ b83.write(), c0.write(), b01.write(), add.write() }, .{ .seconds = 1.5, .lag = 0.3 }); s.pause(); // Each byte flies into its field; the fields it has none for fade. var flights: [fields.len + 3]anim.Animation = undefined; for (labels, 0..) |label, i| flights[i] = switch (i) { opcode, modrm, immediate => label.fadeOut(), else => label.move(.{ .opacity = 0.3 }), }; flights[6] = b83.move(.{ .x = fields[opcode].x, .y = fields[opcode].y, .scale = 1.3 }); flights[7] = c0.move(.{ .x = fields[modrm].x, .y = fields[modrm].y, .scale = 1.3 }); flights[8] = b01.move(.{ .x = fields[immediate].x, .y = fields[immediate].y, .scale = 1.3 }); s.play(flights, .{ .seconds = 1.5, .lag = 0.2 }); s.pause(); // C0 is a ModR/M byte: down the arrow into its boxes, as bits. const bits = s.typst(typst.bits, .{ .x = byte_x, .y = bit_boxes[0].y }); s.play(.{ boxes[0].fadeOut(), boxes[1].fadeOut(), boxes[2].fadeOut(), c0.transformInto(bits) }, .{ .seconds = 1.5 }); s.pause(); // 11 000 000: mod, reg, r/m, each into its box, and what it says. const mod = s.part(bits, .{ .x = -3 * char, .w = 2 * char, .h = 40 }); const reg = s.part(bits, .{ .x = -0.5 * char, .w = 3 * char, .h = 40 }); const rm = s.part(bits, .{ .x = 2.5 * char, .w = 3 * char, .h = 40 }); const says = [_]anim.Obj{ s.typst(typst.direct, .{ .x = bit_boxes[0].x, .y = 28 }), s.typst(typst.is_add, .{ .x = bit_boxes[1].x, .y = 28 }), s.typst(typst.eax, .{ .x = bit_boxes[2].x, .y = 28 }), }; s.play(.{ mod.move(.{ .x = bit_boxes[0].x }), reg.move(.{ .x = bit_boxes[1].x }), rm.move(.{ .x = bit_boxes[2].x }), says[0].write(), says[1].write(), says[2].write(), }, .{ .seconds = 1.5 }); s.pause(); // Back to the page, filled in. s.play(.{ anim.camera(.{ .zoom = 0.65, .x = 0, .y = 0 }), page.move(.{ .opacity = 1 }), notes.fadeIn(), add.fadeOut(), title.fadeIn(), from.fadeIn() }, .{ .seconds = 1.5 }); } /// PDF points, a box from the top left of a 612 x 792 pt page, as an area /// in the page's units. fn onPage(x0: f32, y0: f32, x1: f32, y1: f32) Area { return .{ .x = ((x0 + x1) / 2 - 306) * 4.0 / 3.0, .y = ((y0 + y1) / 2 - 396) * 4.0 / 3.0, .w = (x1 - x0) * 4.0 / 3.0, .h = (y1 - y0) * 4.0 / 3.0 }; } /// ADD's opcode table on page 132, in points: the y of each of its /// horizontal rules, from the top of the header row to the foot of the /// last. The page draws the table's text row by row, left to right, and /// its rules after all of its text; a row is taken with the rule above /// it, so it is written with it. const add_rules = [_]f32{ 82, 107, 122, 137, 152, 167, 182, 197, 212, 227, 253, 268, 283, 298, 313, 328, 343, 358, 373, 388, 403, 418, 433, 448 }; /// The column rules run the table's whole height, so their centres all /// lie in one row (`83 /0 ib`, at 265 pt) and would go with it: a band /// one point high through 265 takes them first, and nothing else. const column_rules = onPage(40, 264.5, 565, 265.5); /// The row `80 /0 ib ADD r/m8, imm8`, between the rules at 167 and 182. /// SUB's `80 /5 ib SUB r/m8, imm8` is a row lower on page 1400 (182 to /// 197), so that page stands 15 pt (20 units) higher: the rows coincide. const row = 5; const sub_y = -20; /// Each of the two rows in the same eight pieces, in points across (from /// `pdftotext -bbox`): the digit after the slash (`0`, `5`; its glyph's /// centre is at 67.5 in both), then the spans between these cuts: the /// rest of the opcode (`80 /`, `ib`), the instruction, the three short /// columns, and the description, word by word (`Add`, `imm8`, `to`, /// `r/m8.`; `Subtract`, `imm8`, `from`, `r/m8.`). const add_cuts = [_]f32{ 46.5, 144, 256, 376, 395, 418, 428.5, 557 }; const sub_cuts = [_]f32{ 46.5, 144, 256, 376, 412.5, 436, 457, 557 }; const digit = 0; /// The pieces that morph with the row, and those that are the same glyphs /// in the same places in both rows, and hold. const follow = [_]usize{ 2, 4, 5, 6, 7 }; const same = [_]usize{ 1, 3 }; /// What differs, marked at the end, in points across: the digit, the /// mnemonic, and two words of the description (ADD's, then SUB's). const add_differs = [_][2]f32{ .{ 65.5, 70.5 }, .{ 146, 166 }, .{ 377, 395 }, .{ 418, 428.5 } }; const sub_differs = [_][2]f32{ .{ 65.5, 70.5 }, .{ 146, 166 }, .{ 377, 412.5 }, .{ 436, 457 } }; /// How far below ADD's row SUB's goes at the end, in units (a row is 20). const gap = 30; /// Piece `i` of a row between `y0` and `y1` (points) cut at `cuts`. fn piece(cuts: []const f32, i: usize, y0: f32, y1: f32) Area { return if (i == digit) onPage(65.5, y0, 70.5, y1) else onPage(cuts[i - 1], y0, cuts[i], y1); } /// Slide 2: ADD's opcode table, written row by row, and its row `80 /0 ib` /// turned into SUB's `80 /5 ib`. fn opcodeTable(s: *anim.Frame) void { const paper = s.rect(.{ .w = 816, .h = 1056, .fill = 0xffffff }); const add = s.typst(typst.add_page, .{}); const sub = s.typst(typst.sub_page, .{ .y = sub_y }); const title = s.typst(typst.table_title, .{ .x = -700, .y = -380 }); const from = s.typst(typst.table_from, .{ .x = -700, .y = -325 }); // Tints, laid before the parts so that they draw over them: the // row's opcode cell, and what differs, over ADD's row and over SUB's // where it ends. const cell = onPage(46, 167, 144.6, 182); const tint = s.rect(.{ .x = cell.x, .y = cell.y, .w = cell.w, .h = cell.h, .fill = 0x58c4dd60 }); var marks: [add_differs.len + sub_differs.len]anim.Obj = undefined; for (&marks, add_differs ++ sub_differs, 0..) |*m, d, i| { const a = onPage(d[0], 167, d[1], 182); const down: f32 = if (i < add_differs.len) 0 else gap; m.* = s.rect(.{ .x = a.x, .y = a.y + down, .w = a.w, .h = a.h, .fill = 0xf7d96f80 }); } // The table comes out of the page before it shows, to be written in: // the column rules, then each row (the last with the rule under it // too). And SUB's row out of its page, piece by piece. const columns = s.part(add, column_rules); var rows: [add_rules.len - 1]anim.Obj = undefined; for (&rows, 0..) |*r, i| { const foot = if (i == rows.len - 1) add_rules[i + 1] + 0.5 else add_rules[i + 1] - 0.5; r.* = s.part(add, onPage(40, add_rules[i] - 0.5, 565, foot)); } var subs: [add_cuts.len]anim.Obj = undefined; for (&subs, 0..) |*p, i| p.* = s.part(sub, piece(&sub_cuts, i, 182.5, 196.5)); s.play(.{anim.camera(.{ .zoom = 0.65, .x = 0, .y = 0 })}, .{ .seconds = 0 }); s.play(.{ title.write(), from.fadeIn(), paper.fadeIn(), add.fadeIn() }, .{ .seconds = 2 }); s.pause(); // The table, row by row. s.play(.{columns.create()}, .{ .seconds = 0.6 }); for (rows) |r| s.play(.{r.write()}, .{ .seconds = 0.25 }); s.pause(); // Onto the row 80 /0 ib, cut in its pieces; the rest greys. const at = onPage(40, add_rules[row] - 0.5, 565, add_rules[row + 1] - 0.5); var adds: [add_cuts.len]anim.Obj = undefined; for (&adds, 0..) |*p, i| { const a = piece(&add_cuts, i, 167.5, 181.5); p.* = s.part(rows[row], .{ .x = a.x - at.x, .y = a.y - at.y, .w = a.w, .h = a.h }); } var grey: [rows.len + 5]anim.Animation = undefined; for (rows, 0..) |r, i| grey[i] = r.move(.{ .opacity = 0.25 }); grey[rows.len..].* = .{ columns.move(.{ .opacity = 0.25 }), add.move(.{ .opacity = 0.25 }), title.fadeOut(), from.fadeOut(), anim.camera(.{ .zoom = 1.7, .x = at.x, .y = at.y }) }; s.play(grey, .{ .seconds = 1.5 }); s.pause(); // Its opcode cell, and the opcode in it: the digit and the rest. s.play(.{ tint.fadeIn(), adds[digit].indicate(), adds[1].indicate() }, .{}); s.pause(); // Close in (a little right of the cell, to stay on the paper): the // digit after the slash, and only it, becomes SUB's. s.play(.{anim.camera(.{ .zoom = 4, .x = cell.x + 40, .y = at.y })}, .{}); s.play(.{adds[digit].transformInto(subs[digit])}, .{ .seconds = 1.5 }); s.pause(); // The rest of the row follows, and the page around it is SUB's. var swap: [rows.len + follow.len + 3]anim.Animation = undefined; for (rows, 0..) |r, i| swap[i] = r.fadeOut(); for (follow, 0..) |i, j| swap[rows.len + j] = adds[i].transformInto(subs[i]); swap[rows.len + follow.len ..].* = .{ columns.fadeOut(), add.fadeOut(), anim.camera(.{ .zoom = 1.7, .x = at.x, .y = at.y }) }; s.play(swap, .{ .seconds = 2 }); s.play(.{ sub.fadeIn(), sub.move(.{ .opacity = 0.25 }) }, .{}); s.pause(); // ADD's row again, and SUB's under it: the pieces that morphed come // back, SUB's that held (the same glyphs as ADD's) come out from // under them, what differs is marked, and why. const group = s.typst(typst.group, .{ .x = at.x, .y = at.y + gap + 40 }); const back = [_]usize{digit} ++ follow; var both: [back.len + same.len + subs.len + 3]anim.Animation = undefined; for (back, 0..) |i, j| both[j] = adds[i].fadeIn(); for (same, 0..) |i, j| both[back.len + j] = subs[i].fadeIn(); for (subs, 0..) |p, i| both[back.len + same.len + i] = p.move(.{ .y = piece(&sub_cuts, i, 182.5, 196.5).y + sub_y + gap }); both[both.len - 3 ..].* = .{ sub.fadeOut(), tint.fadeOut(), anim.camera(.{ .zoom = 1.8, .x = at.x, .y = at.y + gap + 10 }) }; s.play(both, .{ .seconds = 1.5 }); var why: [marks.len + 1]anim.Animation = undefined; for (marks, 0..) |m, i| why[i] = m.fadeIn(); why[marks.len] = group.write(); s.play(why, .{ .seconds = 1.5 }); }