diff options
| -rw-r--r-- | anim/README.md | 194 | ||||
| -rw-r--r-- | anim/build.zig | 11 | ||||
| -rw-r--r-- | anim/scenes/intro.zig | 228 | ||||
| -rw-r--r-- | anim/scenes/intro_code.zig | 106 | ||||
| -rw-r--r-- | anim/scenes/intro_memory.zig | 52 | ||||
| -rw-r--r-- | anim/scenes/intro_registers.zig | 326 | ||||
| -rw-r--r-- | anim/scenes/intro_stack.zig | 252 | ||||
| -rw-r--r-- | anim/src/Recording.zig | 57 | ||||
| -rw-r--r-- | anim/src/aside.zig | 74 | ||||
| -rw-r--r-- | anim/src/context.zig | 175 | ||||
| -rw-r--r-- | anim/src/cursor.zig | 40 | ||||
| -rw-r--r-- | anim/src/disasm.zig | 57 | ||||
| -rw-r--r-- | anim/src/hexdump.zig | 14 | ||||
| -rw-r--r-- | anim/src/map.zig | 15 | ||||
| -rw-r--r-- | anim/src/objects.zig | 2 | ||||
| -rw-r--r-- | anim/src/regroup.zig | 35 | ||||
| -rw-r--r-- | anim/src/root.zig | 20 | ||||
| -rw-r--r-- | anim/src/segments.zig | 42 | ||||
| -rw-r--r-- | anim/src/ties.zig | 5 | ||||
| -rw-r--r-- | anim/src/words.zig | 53 | ||||
| -rw-r--r-- | anim/test/intro.script | 13 | ||||
| -rw-r--r-- | anim/test/intro_code.script | 12 | ||||
| -rw-r--r-- | anim/test/intro_memory.script | 13 | ||||
| -rw-r--r-- | anim/test/intro_stack.script | 10 | ||||
| -rw-r--r-- | anim/tools/chart.py | 15 |
25 files changed, 1362 insertions, 459 deletions
diff --git a/anim/README.md b/anim/README.md index 8b04975..ed8ff22 100644 --- a/anim/README.md +++ b/anim/README.md @@ -191,9 +191,7 @@ canim.descent.step(cur, s, .moment); | `gallery` | every block in its states, a page or a state each 3 s; at 21 s the `blocks` lens (sort's rings at rest, `leave` mid-way, a `turn` landing with its ring's count struck; libc's `open` in `layers` at its `syscall`, what it has not reached folded), at 24 s the moves of a first time (sort's first swap `reach`ed, its pill filling; `open` stepped past its `syscall`, its fold mid-`unfold`; sort in `layers` panned to the pc; the fold open, at rest). Its context pages fold the registers its one step does not change | all three, `blocks` | `gallery`, and for the graph pages `test/gallery/sort.ztrace` and `hello.ztrace` (the second page's picture keeps the old name `graph-map.png`) | | `column` | the text column (design/motion.md, "A scene in the column"): `syscalls`' story on the same recording and steps, beat by beat as the storyboard's table C1 to C12 has it, its texts as it cuts them (C4's 57 characters): the opening `below` (the working frame whole, its caption); the arguments beside the source and the disassembly over the registers; the call and the stub's jmp beside the descent over a stack of twenty words (the touch from the call row down the gutter to the free word, rsp's pin climbing); the wrapper at a run over a source of two lines, the text level with open's head; its last three beside the registers; the crossing beside a descent of twenty-four rows, the text level with the kernel's floor; back up, the text at main's call row; `read`, `close`, `write` stepped over, the bytes over the source, each text beside its call row; the close `below`. Every other pane on the shelf, the registers' strikes on their tag | the column (`column.zig`), the working frame `beside` at the opening and the close | `hello` | | `column_sort` | the column's wide placements on sort's first trip: the opening `below`, then the rings across both columns twice their size, the others on the shelf (`sort.c line 12`, `disassembly jne …`), a text `on` the drawing in the corner the rings leave free with its stem round the drawing's top to the pc's block; then a text `above` it; then the working frame again | `blocks`, then the drawing across both columns (`Stage.zoom`) | `sort` | -| `intro_memory` | the introduction's first chapter (design/motion.md, "A scene: the introduction", I1 to I10): the 128 bytes at the top of the stack under the camera at x2, arriving as the first text lands (`128 bytes at 7fffffffebc8`); `regroup`, sixteen a row to eight (the return address walked: the top row, so its offsets stand over it in the header's row, `low byte` and `high byte` outside them, and its bytes fly over that row, one in the air at a time, each with its offset; the rest at a run; a plain number with `0x`); three words that hold addresses framed; into the column, the rows gliding up into the header, which becomes the tag (`the 128 bytes`) and goes to the shelf; the address space to scale (`segments`, mock 34: a slim bar, then `enlarge` a cluster at a time, the stack, the libraries, the program by segment, start, end and size on every band), texts beside; back to the working frame: the dump's `tie` and `link` onto the stack's box (mock 30), its addresses in the stack's ink as the box lights; a visit at x2 framing the box and the dump's top rows, the place marked `128 bytes` on the box; `ink`, three chains (`→` and `←` said) | the working frame (`below`), the column for I4 to I6 | `intro`, reverse's first instruction (`push rbp`) | -| `intro_stack` | chapter II (six beats, mock 31), from I's last picture: the words glide into the stack panel's rows (sixteen and four `free` over rsp, the window held: nothing in the panel moves) and become it, the convention said there (lower addresses drawn higher) as the offsets come down its rows (a `column`); rsp's and rbp's rows arrive over the stack, rsp's pin on the top word, rsp's link down to it (`Context.tiesWith`); the call first: the way back framed, main's three rows round its call arriving in the program column and the word aimed at the row it returns to (`aim`, drawn head first at full ink, 60% through the push); reverse's first rows (the disassembly, seven rows) under main's, `push rbp` walked (the touch from its row, rbp's value carried to the word, struck though it held it, rsp's pin climbing); `mov rbp, rsp` and `sub rsp` walked, the roles (`the way back`) and the spans a `column` each, the panels' tags last (`frame up`); the registers built row by row, their tag last; texts beside on the left, in the program column | the working frame without a backtrace, texts on the left | `intro`, reverse's first three instructions | -| `intro_code` | chapter III (III1 to III5, mocks 32, 33, 36), from II's last picture (its texts and code give way, its state column stays veiled at 50% until the decoded code spans it): the code's bytes as a dump row in code's ink, an instruction's four framed; `decode` into `aligned` (`interleaved`, mock 33: lines and addresses in one column, a rule over every group, the load's row annotated), the neighbours at a run; `align` to `columns` (mock 36; the width squares said); `stack` to the working frame (the lines glide to the source panel's rows, the instructions down and into the disassembly's, the panels come in under them), `Later, at line 21`; the list's nodes from the heap's bytes (node 9's pin `head cur rax` in full, its row `9 → 405030`), rax's link up to it; each pane's minimap last (said); the map's text lands, then `surface` under it | `aligned`, texts above (two lines of 80); then `subject`, `nodes`; the map | `intro`, the load on line 21 | +| `intro` | the introduction, one video in four chapters (design/motion.md, "A scene: the introduction"), each a function of its own file the scene calls in order (`intro_memory.zig`, `intro_registers.zig`, `intro_stack.zig`, `intro_code.zig`), each opening on the last picture of the one before at a seam (`title`: 30 f still, the texts out, the title said in the caption's place, `II Registers`, the clock's label crossfading to the chapter's, 60 f still, the opening under the title; mock 62). **I Memory** (I1 to I10): the 128 bytes at the top of the stack under the camera at x2 (`128 bytes at 7fffffffecc8`); `regroup` (the return address walked, the rest at a run); three addresses framed; the address space to scale in the column (`segments`, `enlarge`), texts beside; the dump's `tie` and `link` onto the stack's box; a visit at x2; `ink`; three chains. **II Registers** (II1 to II8, mocks 58 to 61), from push(9) at line 40, before I's moment: the 128 bytes fold to the shelf (rising to its height, then along it); the registers at the state column's top, every register a row, a row at a time, the name then the chain; rip's row, `◂ rip` on list's code band (`Segments.pins`, `ink`'s echo), `frame up`, the clock and its label beside it; rbp and rsp framed, their pin in the stack's band, rax, rcx, rsi with the heap's; push's six rows at the program column's foot with no panel round them, the texts beside on the left from here (an older one gliding down under a newer, three at most: `Asides.floor`); rip and its row framed together; rdi opened into its `parts` (`unpack`), `mov edi, 0x10` walked, the operand, the part `edi` and its bytes framed together, the byte `09` to `10` struck with the row's `rdi 0x10 16`, `pack`; `call malloc@plt` stepped over (`Cursor.over`: rdi framed with its hanging row, rax struck first with the row's `malloc(16) = 405050`, then rcx, rsi, rdi in a wave); a continue to reverse's first instruction; `fold` (the ten registers never changed into their cells, the rule last), the 128 bytes back at the rows III's stack gives them. **III The stack** (III1 to III5, mock 31), on II's context: the words become the stack panel where they stand, the convention, rsp's pin and link, the call (main's rows, the `aim`), `push rbp`, `mov rbp, rsp`, `sub rsp` walked, roles, spans, `frame up` on the disassembly and the stack. **IV Code and meaning** (IV1 to IV5, mocks 32, 33, 36): the code's bytes, `decode`, `align`, `stack` into the working frame (the one clock stepped on to the load, 185 to 191), the nodes from the heap's bytes, the minimaps, the map | the working frame `below` and the column (I); the working frame `below`, then texts beside (II, III); `aligned`, texts above, then `subject`, `nodes`, the map (IV) | `intro`: one clock from its first stop at line 40, `moment 6 of 193` to `191` | | `asan` | plain against AddressSanitizer on `overflow.c` (design/motion.md, "A scene: ASan against a plain build", A1 to A16): a `pair` (A1 to A9, A14 to A16: the shared source, each run's disassembly, registers and frame as bytes eight a row with ASan's shadow byte beside each row, `only here` and `differs` bars, the parting framed `attention`, ASan's stderr in place of its registers once stopped) and the column for A10 to A13 (ASan folded to one shelf tag, its report's first line on it; plain's disassembly a descent, main's window over fill's whole; plain's frame the column's rest; each text level with the field the letter lands in; `aim = .standing`: the return address aims at main's row after the call, glides to `fill+1` at i = 24 and frays at i = 25); i = 27 held 4.9 s (mock 38, the poster); the fault at `ret` (SIGSEGV, rip stays) | `pair.split`, then the column | `overflow`, `overflow_asan`, `overflow_report` | ## The blocks @@ -208,9 +206,9 @@ every state the code has in the `gallery` scene. | | `byte` | `src/rows.zig` `bytes` | `number`, `pointer`, `text` (a string's ink), `loose` (a byte of no field: the allocator's, padding, past what a dump is of), `unread`; `pad`; `bytesAt` moves the bytes right of a long (stack) address, by the dump's widest; a write's arm, strike and held corner cover the bytes whose value changed, first to last (`Run.changed`, `Now.changedBytes`), struck a byte a frame from the low address (what a read fills, 2 f apart); until its strike lands (s+3) a run keeps its old bytes and their reading, through the arm, read by its old field where the step retypes it (`hexdump.keepOld`, `Fields.was`) | | 2 row | `chain`, `reg` (and `rip` with the flags), `slot`, `line`, `bytes`, `call` (`span`, `callRow`) | `src/rows.zig` | `chain` follows `zt.telescope.chase`; cut at its far end, `more`; a register's reads memory as the panels show it, the step's bytes from their strike (s+3): its later hops fade out from the strike and are followed again 4 f after the bytes land (`Now.following`, `Marks.hops`). `slot`: pins from 16, the offset ranged right to 172 (under `tied` from the frame's base, the call frame information's CFA register: `context.frameBase`; under `whole` from rsp; a `free` word's crossfading), the address at 184, the chain, its role ranged right where the room ends (48 sooner in a pane: its strip), from `zt.telescope.slots` (`saved rbx`, a local's name in primary, `n, high half` for a narrower local in the word's top four bytes, `argc`, `argv[0]`, `argv end`, `envp end`, `auxv`; `i, n` where locals share a word (`Slot.also`); the stack protector's copy `canary`; nothing for a return address or `.none`). `bytes`: the bracket at 24, the address at 34, the bytes 12 after it and at 132 at least | | | `arc` | `src/rows.zig` (`Arcs`), `src/hexdump.zig` (`pointerArcs`) | a pointer to a row of its own panel: lanes at 4, 10, 16 in a dump or a loupe, 4 and 10 on the stack; longest outermost, a chain in one lane; standing at 60% toward the page, full in the step that writes or reads it and always in a loupe; rewritten: the old dashed with the arm, fading from 6 f after the strike as the new draws (12 f), quieting with the cool; a lane change glides while the arc that causes it draws or fades (`Arcs.assign`, with and without the arcs on their way); a stub to the rule for a target in the region past the window, only in its step; a saved rbp's only in its step, going with its advance (18 f); a dump withholds the arcs an open loupe carries | -| | `insn` | `src/disasm.zig` | columns at 2, 31, 40, 134, 180, 264, 564 (540 in a pane, whose strip takes 48 of the row; `map.content`); size words dropped from every operand, a `width` of byte cells (`metric.width`) after the `]` where no register outside the brackets has the access's size and the mnemonic does not fix it; `nop` and `endbr64` faint; a PLT target named (`401070 open@plt`); the annotation from 564 or a character after the operands, then the operands give way, never inside `[]`; `current`, `ran` (every instruction of the last three steps), `ahead`, `outside`, `waiting`, `pass`; the jump lane from the jump just before the pc's moment. The row's detail, every value the recording's at that moment: a compare's two values and the flags it leaves as chips (those the conditional after it reads; CF ZF SF OF when none); a conditional's `taken`/`not taken · reads` and its flags, `→ target` when it leaves the window, and while it runs the setting row's chips and rip's framed as read (an echo); `lea`'s `= value`; a call through memory or a register `→ target name · read from open@got, 403fd8` (out of room the slot goes, then the digits); a call through a PLT stub by the function it reaches (`the resolver` while its slot is lazy); `fs:[0x28]` as the stack's canary (`canary` where the row has no room); a `rep`'s count and step; `syscall` with its name and number, its arguments under it by register, typed (`-100 AT_FDCWD`, `O_RDONLY`), the rows they hang over giving up their own annotation; a call that has run in C's form with its result (`read(3, …) = 15`: out of room the arguments go from the right, the result stays); a memory access narrower than a word read at its width (`rows.narrow`: `7fffffffecc4 ◂ 15`). The annotation's form is the scene's knob (`Levels.annotation`, above): under `tied` a word the stack shows by its role and one hop (`tiedWord`; a local's name, the one of a shared word that holds the bytes accessed; an unnamed word, a spill, by its address and one hop; a store's value cut with `…`, never dropped), a heap word with a view on screen by its address and one hop, a word no pane shows its whole chain with its data name in place of the address (`head → 407050 ← 9`); a register set its first value; a move of rsp or rbp first (`stackMove`: `rsp -8 · saved rbp`, the role from the push's own stop, `rsp -0x20 4 words`, `rbp = rsp`, `leave`'s, `fib(4) · rsp -8`, `→ 4011ad main+45 · rsp +8`), the amount struck as rsp's pin lands; the row publishes where the touch leaves it (`ties.touch_row`); under `whole` the row as before. What the step leaves on its own row (`lea`'s `=`, a register's first value, a compare's flags, the canary's word, `rbp = rsp`'s value) fades in from its strike (12 f; at a run the run's ease); a row the advance changes (its state, its trail, its line number, the moment its annotation reads: the pc's row back on itself, a loop's turn at a run) is drawn as before and as after the advance and crossfades over its middle, at a run over the whole advance (8 f, the run's ease). A `pair`'s (`Disasm.run`, `.aligned`, `.stopped`): its run's name on the tag (`plain · fill`); the pc's line's first row at the window's top while the pc is in its upper half; a stopped run's call `4e8450 __asan_report_store1 never returned`, its plaque gone, the tag `· stopped` | +| | `insn` | `src/disasm.zig` | columns at 2, 31, 40, 134, 180, 264, 564 (540 in a pane, whose strip takes 48 of the row; `map.content`); size words dropped from every operand, a `width` of byte cells (`metric.width`) after the `]` where no register outside the brackets has the access's size and the mnemonic does not fix it; `nop` and `endbr64` faint; a PLT target named (`401070 open@plt`); the annotation from 564 or a character after the operands, then the operands give way, never inside `[]`; `current`, `ran` (every instruction of the last three steps), `ahead`, `outside`, `waiting`, `pass`; the jump lane from the jump just before the pc's moment. The row's detail, every value the recording's at that moment: a compare's two values and the flags it leaves as chips (those the conditional after it reads; CF ZF SF OF when none); a conditional's `taken`/`not taken · reads` and its flags, `→ target` when it leaves the window, and while it runs the setting row's chips and rip's framed as read (an echo); `lea`'s `= value`; a call through memory or a register `→ target name · read from open@got, 403fd8` (out of room the slot goes, then the digits); a call through a PLT stub by the function it reaches (`the resolver` while its slot is lazy); `fs:[0x28]` as the stack's canary (`canary` where the row has no room); a `rep`'s count and step; `syscall` with its name and number, its arguments under it by register, typed (`-100 AT_FDCWD`, `O_RDONLY`), the rows they hang over giving up their own annotation; a call that has run in C's form with its result (`read(3, …) = 15`, an address in hex: `malloc(16) = 405050`; out of room the arguments go from the right, the result stays); a call stepped over (`Cursor.over`, `Plan.result`): its callee and its arguments hanging under it, framed as read from 18 f, then as rax strikes (48) its C form and its result, struck with rax (an echo), the hanging rows going (6 f); a memory access narrower than a word read at its width (`rows.narrow`: `7fffffffecc4 ◂ 15`). The annotation's form is the scene's knob (`Levels.annotation`, above): under `tied` a word the stack shows by its role and one hop (`tiedWord`; a local's name, the one of a shared word that holds the bytes accessed; an unnamed word, a spill, by its address and one hop; a store's value cut with `…`, never dropped), a heap word with a view on screen by its address and one hop, a word no pane shows its whole chain with its data name in place of the address (`head → 407050 ← 9`); a register set its first value; a move of rsp or rbp first (`stackMove`: `rsp -8 · saved rbp`, the role from the push's own stop, `rsp -0x20 4 words`, `rbp = rsp`, `leave`'s, `fib(4) · rsp -8`, `→ 4011ad main+45 · rsp +8`), the amount struck as rsp's pin lands; the row publishes where the touch leaves it (`ties.touch_row`); under `whole` the row as before. What the step leaves on its own row (`lea`'s `=`, a register's first value, a compare's flags, the canary's word, `rbp = rsp`'s value) fades in from its strike (12 f; at a run the run's ease); a row the advance changes (its state, its trail, its line number, the moment its annotation reads: the pc's row back on itself, a loop's turn at a run) is drawn as before and as after the advance and crossfades over its middle, at a run over the whole advance (8 f, the run's ease). A `pair`'s (`Disasm.run`, `.aligned`, `.stopped`): its run's name on the tag (`plain · fill`); the pc's line's first row at the window's top while the pc is in its upper half; a stopped run's call `4e8450 __asan_report_store1 never returned`, its plaque gone, the tag `· stopped`. The introduction's (`Levels.introduction`): a register's first value struck with it (the parts' bytes are), and no `· rsp -8` on a call row (it walks none); `Disasm.mark_in`, the pc's mark coming after the rows it stands on | | | `descent` | `src/descent.zig` (`Descent`, `step`) | the disassembly a call deep: the root's window on top (main), each callee's under the row that called it (that row `waiting`, ringed, its annotation the call in C's form), a PLT stub gone through kept as its `jmp`, `pass`; a head row over each window (the name at 40, Go Medium 18; what it is ranged right: `libc.so.6 · open64.c` (the file of its function's entry, where the build has the source), `libc.so.6 · no source`, `the PLT · its jmp reads open@got, 403fd8`, `the PLT, jumped through`); the call lane at x 14; the nearest caller takes the rows the deepest does not use, all above its call row (one row after it, the return row, the callee's head directly under that), and where its function starts first the rest go back to the deepest window; three code windows at most, the rest one `more` row; each window's addresses its own width; the tag the deepest function and its module (`open · libc.so.6`); at a `syscall` (and the stop after it) the floor's three rows are the kernel's: in a crossing the lane down from the plaque (3, vellum), the window filling down, `the kernel` and `openat, system call 257`, the call in C's form, `returns` struck, `rcx, r11: clobbered`, the answer climbing the lane (24 f, `glide`), the window drawing back at the advance. A crossing stepped over opens the same window under the call row, past the arguments hanging under it, the rows after them making room (18 f) and closing up with the window. Every row keyed (an address, a head), so a step is the rows both stops have gliding (and a change of the panel's height at rest the rows both heights' layouts have, `Stage.resizing`; a row's shared digits are of its own window's rows that show) and the rest leaving or arriving on its verb's timetable, in two moves, never at once: `descend` (2.9 s: the given-up rows fade 66–78, the kept ones glide 78–96, ring 84–96, lane 96–114, head 108–120, rows 114–138), on through a stub's `jmp` (2.2 s), `ascend` (2.5 s: the window closes 48–72, lane back 72–84, the kept rows glide 84–102, the given-up ones fade in 102–114), `cross` (`syscalls.step`); a row whose state the verb changes (the call row to `waiting` with its hanging arguments, a jmp to `pass`, a waiting call taking its result) crossfades; with it the source's line `waiting` where the pc is in code without source (ringed, the tag `main waits at line 6 · the pc is in libc's open`, crossfading over the 12 f before the advance, as a stack span's name does) and the thread waiting (primary, 2); where the build has the library's source the panel goes on with the pc into it. Its strip is the deepest window's function's linear column (a `Disasm` drawn for the strip alone, `Map.In.strips`), that window framed on it; going down or up it fades through as the mark lands (`map.through`) | -| 3 panel | `registers`, `stack`, `backtrace` | `src/context.zig` | the registers `quiet` (`Registers.moves`, `movedBy`, `registerRows`): the scene's set chosen once, from its clock's way (`Cursor.journey`: the registers any of its steps of that kind changes, net, with rsp, rbp and rip), each a row with its chain; the rest folded three to a row on a pitch of 285 under a 2-unit rule, in pwndbg's order (`rows.quiet`: the name faint at 12, the value at 60, a pointer cut to `more` at once, a code address alone; framed as read while it carries a system call), rip last; the panel as tall as its rows and the stack the rest (`layout.fit`); in a `dive` it arrives whole from the map and folds as it lands (`Zoom.fold`: each quiet row gliding into its cell, the chain past its first hop gone over the first 40% of the move, a rule fading in); rip's value crossfading over the advance, a flag set or cleared over the 6 f it lands in (`rows.RipWas`); the backtrace newest at the bottom, `#0` last, the oldest dropped from the top (`newest at the bottom · 2 more above`), as a panel, the calls lens's view, the backtrace lens and on the map, all one block (`backtraceRows`: frames leave, slide and arrive; what a kept row says that changes, its depth, its pc's offset, its line, and the tag's count, crossfades, 12 f before the advance); the stack's window on `[rsp, rbp+16)` keeping the touched word in view, its tag the first and last word shown (`rsp+20 to rsp+48`), a word's role and offset, and the tag, crossfading (12 f from memory's strike) where the step changes them, rsp and rbp's pins travelling 18 f after rsp's strike (`time.pin`, keeping their place among the names they leave and join), at rest only where the register points; a window that moves farther than its own height (six or eight slots) fades out and in round memory's strike (12 f each; at a run half its step each), and what it brings, and what changed before it, is plain; while rows slide they keep their roles (those of both windows are read), and a word becoming a saved rbp, or no longer one, has its arc go or come with its role; a frame's name longer than the spans' room shortens the chains beside it; `call` spans and the backtrace (`#n`, name, arguments at 384, file and line) from `zt.telescope.frames`, the frames two stops share sliding to their new depth; the backtrace as a lens's drawing with `Context.Options.backtrace`. Under `tied` the window has two `free` words of headroom over rsp (a leaf's locals under rsp are the frame's), the tag says the base (`· offsets from rbp`, crossfading as it changes), and when rsp or rbp moves the rows hold while the pin travels (`Plan.pins`: the amount on it, `rsp -18`, counting row by row, a vermilion bracket over the rows crossed, each row gained or released as it passes, the newest frame's span riding it, the register struck as it lands; rbp's pin flies to rsp's, `pop rbp` moves rbp first), and only then the window follows (`Plan.follow`); under `whole` as before | +| 3 panel | `registers`, `stack`, `backtrace` | `src/context.zig` | on a beat a scene plays: `Registers.fold` (0 every register a row, 1 the quiet ones folded into their cells, the dive's fold on the scene's clock, `glide`; the rule over them drawing once they have, 12 f), `Registers.parts` (`reg`'s `parts`: one register's value as its eight bytes from 72 on a pitch of 30, high first, the zeros in front at `pad`, spreading out of the value as it was written and closing back into it (`unpack`: the rows under it make room 18 f, the bytes spread 12 f, its parts' rows widest first, a bracket under the bytes each is and its name before it, 12 f each, 6 f apart; `pack`: the parts out 12 f, the bytes close and the rows close up 24 f); a write strikes the bytes it changed, as a dump's; `echo`: the part an instruction names and its bytes framed as read), `Registers.framed` (a register's value, rip's too, framed as read on a beat); `Context.Options.moves`, the scene's set where it is not its clock's way's (the introduction's one set for its four chapters). The registers `quiet` (`Registers.moves`, `movedBy`, `registerRows`): the scene's set chosen once, from its clock's way (`Cursor.journey`: the registers any of its steps of that kind changes, net, with rsp, rbp and rip), each a row with its chain; the rest folded three to a row on a pitch of 285 under a 2-unit rule, in pwndbg's order (`rows.quiet`: the name faint at 12, the value at 60, a pointer cut to `more` at once, a code address alone; framed as read while it carries a system call), rip last; the panel as tall as its rows and the stack the rest (`layout.fit`); in a `dive` it arrives whole from the map and folds as it lands (`Zoom.fold`: each quiet row gliding into its cell, the chain past its first hop gone over the first 40% of the move, a rule fading in); rip's value crossfading over the advance, a flag set or cleared over the 6 f it lands in (`rows.RipWas`); the backtrace newest at the bottom, `#0` last, the oldest dropped from the top (`newest at the bottom · 2 more above`), as a panel, the calls lens's view, the backtrace lens and on the map, all one block (`backtraceRows`: frames leave, slide and arrive; what a kept row says that changes, its depth, its pc's offset, its line, and the tag's count, crossfades, 12 f before the advance); the stack's window on `[rsp, rbp+16)` keeping the touched word in view, its tag the first and last word shown (`rsp+20 to rsp+48`), a word's role and offset, and the tag, crossfading (12 f from memory's strike) where the step changes them, rsp and rbp's pins travelling 18 f after rsp's strike (`time.pin`, keeping their place among the names they leave and join), at rest only where the register points; a window that moves farther than its own height (six or eight slots) fades out and in round memory's strike (12 f each; at a run half its step each), and what it brings, and what changed before it, is plain; while rows slide they keep their roles (those of both windows are read), and a word becoming a saved rbp, or no longer one, has its arc go or come with its role; a frame's name longer than the spans' room shortens the chains beside it; `call` spans and the backtrace (`#n`, name, arguments at 384, file and line) from `zt.telescope.frames`, the frames two stops share sliding to their new depth; the backtrace as a lens's drawing with `Context.Options.backtrace`. Under `tied` the window has two `free` words of headroom over rsp (a leaf's locals under rsp are the frame's), the tag says the base (`· offsets from rbp`, crossfading as it changes), and when rsp or rbp moves the rows hold while the pin travels (`Plan.pins`: the amount on it, `rsp -18`, counting row by row, a vermilion bracket over the rows crossed, each row gained or released as it passes, the newest frame's span riding it, the register struck as it lands; rbp's pin flies to rsp's, `pop rbp` moves rbp first), and only then the window follows (`Plan.follow`); under `whole` as before | | | `source` | `src/source.zig` | fourteen lines alone, eight with a lens, six with `blocks`; the file the pc is on a line of, of the recording's sources (`Recording.sources`, `shown`: the program's own, or a library's the build gave; else the last such line, a frame up, where the pc waits), whole in a window, its middle third; its lines cut at 63 characters in a pane (67 on the map); the trail's bars (of that file's lines) crossfading with the advance; numbers as wide as the widest file's largest line (SQLite's six digits), the text moved right by as much; another file: the panel fades through (12 f out, 12 f in), its tag's title and note crossfading with it, its strip with it (`map.through`); a window going farther than its own height in one file: the advance is 48 f, the window gliding on the strip for the first 24 (the gold lit on its new row there), then the pane out and in | | | `disasm` | `src/disasm.zig` | under the source in every split: 17 rows (11 as subject and with `blocks`), fewer above near a function's start; on the map 69 from the function's start where the pc is in its first three quarters (a strip's column stays still while the pc walks it), else round the pc; the line column as wide as the source's, a row's number where its line is of the file the source panel shows (libc's rows open64.c's while it shows open64.c, main's none then); two windows that overlap scroll, others fade out and in; its tag's function (a descent's tag too) crossfading with the advance; a 2-unit `rule` across over each block's first row (not its function's), and the block's visits by the moment shown ranged right, faint (`×3`), where the row's annotation leaves room, crossfading with the advance (`graph.Rules`, a descent's windows too); the rows clipped above the panel's padding (a row scrolling out takes its rule with it) | | | `graph` | `src/graph.zig` (`read`, `layout`, `place`, `Blocks`, `Rules`, `leave`) | the function's blocks from the recording (`zt.telescope.blocks`; a block of `nop` padding nothing goes to left out), their edges by how each ends, and the run over them by the moment shown and nothing after (design/README.md, Forbidden): each block's visits, each edge's count, the last three edges taken, the pc's block, counted where one stop in the function follows another across an edge (`exact`: by instruction; by line, visits only). Laid out from the code alone (`place`: never the run's counts), in two forms (`Blocks.form`): `rings` wherever the function has a loop (natural loops merged by header, back edges by the walk from the entry in address order; each a ring, its pills upright at their centres clockwise from the header at 9 o'clock, radius as its pills need, 12 apart and 24 of arc between two; a nested loop a smaller ring outside its parent touching it at its header, the parent's 3 o'clock; an edge to the next pill an arc of its ring cut at the pills' frames, the back edge round the ring's foot, a fork inside a loop an arc 30 inside, a way out along the tangent out of the pill's foot 30 in from its far end, then quarter circles of 16; outside every loop the blocks as `layers` lays them, the entry left of the header, the blocks after under it; `3 turns` 30 under the ring's centre, from the first) and `layers` (layers by the longest path, a block under its fall-through predecessor, a taken target right of it, back edges up lanes on the left, every corner a quarter circle of 12; panning by thirds round the pc's pill where it is taller than its pane). A block a pill 24 high: its offset, the program's callees after it, faint (the tracer's `__zt_*` left out), its visits ranged right, room kept for `×99` so it never widens as the run counts; not reached yet on the page, `rule` framed, faint, no count; the pc's framed gold 3. Edges not taken yet `rule`, taken `dim`, the trail's golds, the newest 3. Too big for its pane (`layout`), the blocks not reached by the scene's first moment fold (`cursor.first`: the code beyond each way the run had not taken, `+5b … · 7`), keeping a fold's room; a fold opens when the run reaches a block of it and never closes (`unfold`: the pills beyond make room 24 f, `glide`, the fold's blocks fade in quiet 12 f, 2 f apart, then the mark lands). `leave` and `turn` along the curves (12 f and 2 f a 100 units, 12 to 42 f; the turn's count at the ring's centre armed as the mark leaves the latch, struck as it lands); `reach` (the edge from `rule` to gold under the mark, the pill filling page to `raised` 12 f, `×1` in 6 f and struck). Kept per function, form, room, first moment and open folds (`memo`), counted again each frame. On the map the drawing is the lens's at its size over the source, the disassembly linear beside it (`Rules`) | @@ -219,17 +217,17 @@ every state the code has in the `gallery` scene. | | `loupe` | `src/loupe.zig` (`canim.loupe`, `Loupe.open`, `.close`) | from a register, a loupe's field, or a dump's row read by the scene's fields (`.row`: malloc's tcache, `num_slots[0]` and `entries[0]`, the rest `more`); five rows round a pointer's target, lifted (`color.lift`, `lift_tag`, `shade` 12 and 16; 20 and 26 deeper), hanging from its pointer (its tag on the row's foot, 92 left of the digits, clamped to the stage), a 4-high bracket under the digits its stem, the target's fields framed bright; one opened from the band's view lies over the stack, never the registers, its stem down the gutter's right lane (x 962), its fields struck once it has opened (6 f after, 6 f apart: `Fields.struck`); a deeper one with no room to the right hangs under the one it opens from, its stem down to its tag; a note that does not fit is cut at a word with `…`; `open` 36 f (read 6, stem and rise 18 with the shadow, the frame 6 f after), `close` 12 f; it opens again after a close | | | lenses: `nodes`, `array`, `calls`, `syscalls`, `backtrace` | `src/nodes.zig`, `src/array.zig`, `src/calls.zig` (`Tree`), `src/syscalls.zig` (`Crossing`), `src/context.zig` (`Backtrace`, `lens`) | the drawing in `band` (over the program column), its view in `view` (over the state column): `nodes` and `array` a dump (`hexdump.panel`), `calls` the backtrace with arguments, `syscalls` the calls so far as strace writes them (oldest on top, the newest coming in once it is back, held; the rows make room for it, a full log scrolling a row, 24 f, `glide`, but from rest at least a pixel a frame (the rows are drawn on whole pixels), the count above crossfading; out of room a row gives up its faint names first, then its arguments from the right, and keeps what it returned; a path by its string, the kernel's capture where the stop did not read it) over the bytes the call crossing in the step is given or fills (in with the argument framing, 12 f out and 12 f in; what a read fills landing a byte every 2 f, struck, the stack's words with them; a write's buffer framed as read while the kernel takes it; cleared with the log's new row: between crossings `no call crossing now`), `backtrace` (eleven rows as subject, five beside) a `Dump` the scene gives; an `under` pin's names in the order they came, the first left (past the second a count, or with `Nodes.named` by name where they fit before the next node), faded out through the middle of a register's joining or leaving (`Pins.text`); a call node's look (gold, ringed, done) crossfading as the tree's moment changes (6 f), and at a sprint a new node coming in over its step; a left child's result on its left shoulder, off its parent; a view's row a register points into carries the register's `pin` at the row's end (`hexdump` `rowPin`; 48 to the left in a pane, its strip at the right), the reading ending before it; at a sprint the array's pins hold and move where a phrase ends | | 4 tie | the relations: `thread`, `link` (and its `pin`), `projection`, `touch`, `carry`, `aim`, `echo` | `src/relations.zig` (the tables and the pure passes), `src/ties.zig` (`Ties`, the resolver; `anchor`, `show`, `find`, `of`) | the relations are one data problem (design/README.md, "4. Ties"): each frame's tables are in the frame's own scratch (`sk.Frame.user`, made at its first place: no process globals, two players at once each have theirs): `places` (a key, the place's kind in its top byte and its address below, its box, its pane; struct of arrays) that panels say as they draw (`anchor`), `values` (what a pane shows that may be an address: the value, its box, its pane, the word holding it, a register's index, its panel's rules: `show`, from the registers, the stack's words, a pair's frame), and the facts the panels publish beside them (the stack's window, the touch's row, the thread waiting); both sorted once by key (or value) after a change, a lookup a binary search (`find`), a join a merge of the two sorted sides (`relations.join`). `Ties`, added last, is the resolver, six passes, each a loop over one table: candidates (each kind's join, or the step's events against the places), the knobs (`relations.filter`: a kind whose default is off, `carry` and `aim`, only where the scene turned it on; the budget never turns one on), priority (`byPriority`), the budget (`cut`: the thread; one beat; a link, a projection and a touch, two of them, the touch giving way first; a carry; one aim), then each kind's route and drawing. The kinds are one table of data (`relations.specs`: knob, class, priority, most). Map panels say their places into the map's own tables. `CANIM_RELATIONS=1` says each frame's counts and times on stderr; `zig build bench -- relations` times the passes on a working frame's tables and a map's. The kinds' pictures and timings are as they were: fib, list, zoom, sqlite and column render identical frames before and after (every frame compared). `aim` (`Cursor.aim(s, .standing | .step | .drawn | .off)`, off by default): a word in memory holding a code address whose row is on screen, out of its panel's rule nearer the gutter, up the left lane (x 950), onto the disassembly's right rule, the row's address framed in code's ink, its head 10 by 10; standing at 60% toward the page, in and out with the knob over 18 f (`.drawn`: head first at full ink, 18 f, the address framed as it lands, 6 f); the step's full ink after the word's strike, back with the advance; written again, its head glides to the new row 24 f after the strike, or it frays (dashed over 12 f, gone over 18 more) where the new value is no code. Draws in the channels: a link climbs to a node by the gutter's left lane and goes down to a slot by the right, its name riding its head, a target past the stack's window a stub and a row count; to a view's row (`dump_pin`) by the left lane, into the row's edge; on a beat the narration names (`Context.tiesWith`, `ties.Beat`): the register framed as read, then its link, held, drawn back with the frame, its head fading over the draw-back's last third; a projection from the view's bytes, or from a frame's return address to its call's node. Under `tied`, `touch` (`Plan.touch`): from the row's right rule along the gutter's middle lane (x 956) to the word, onto the stack's rule nearer the lane (its right one where the stack stands under the disassembly, a column's beat), in read's or write's colour, the first of the three lines to give way; `carry` (`Levels.carry`, `Plan.carry`): the value's way between a stack word and a register along x 962, primary, an open chevron, `.value` its digits on a raised chip, `.after_touch` after the instruction's touch to the word (a store's too). Places a column's text is level with: `row` (a disassembly's row by its address, a descent's head by `descent.headKey`), `floor`, `block` | -| 5 frame | `map`, `minimap`, `dive`, `surface` | `src/map.zig` (`Map`, `split`, `strip`, `Map.strips`), `Context.map` | the working frame's panels bound to a stage of 3840 by 2160 (`map.split`, packed by content: each box as long as the most rows its panel has wanted, `measure`, the backtrace's as long as the deepest call chain of the scene's way, so that it is packed once; the drawing, the source and under it the backtrace; the disassembly; the view (none where nothing draws one), the registers, and in the column's rest the stack going on, `stack, continued`; the stack from 16 words above rsp; and the first two columns' rest (`Split.spare`) given, in the catalogue's order, to `map.Spare`: a five-row dump round each place the registers (pwndbg's order, not rsp or rbp) and the 64 words up from rsp point at outside the stack and the code, none within another's rows, then the loupes open (`Map.loupes`, lifted, nine rows), then the key (the recording and the moment, the marks as drawn, the inks); only then page); its rows published while `ui.mapping` (the dumps' too); the working windows outlined (2 `dim`, 4 out), each window published with where its step took it from and how far its scroll has gone, so its outline glides; the thread across the gutter (x 1008), gold; a scene without a band can put a drawing on its map (`Map.drawing`); with `Context.Options.graph` the map's drawing is the `blocks` lens's (`graph.Blocks` at its size, 880 by 344, over the source: `split`'s band is the working frame's), the disassembly linear beside it with its blocks ruled. Each pane's minimap (`map.strip`): a strip 40 wide inside its frame at its right, under the tag, on `well` (`theme.strip`), drawn from its column of the map (the source's boxes, the stack's with `stack, continued`, the view's dump; the disassembly's the linear rows round the pc, drawn for the strips alone where the map has a graph or a descent: `Map.In.strips`) at 4 units a row and 36 of 880 across, from what the map drawn for it collects (`ui.strokes`, `ui.collected`: each run of text a stroke 3 high in its ink 65% from the page, the marks 4 by 4 at a row's left in the catalogue's order, an arc with an end off the window a 2-unit line down the left edge, a block's first row ticked); a column longer than the strip the rows round its window, the window in the middle, clamped to the ends, three faint dots where it goes on (fading in over its first row's scroll); the window framed 2 in primary; a mark no working window shows (a word struck or read on the stack or in the view's dump) flashing on its row (a ring 8 to 14 in the mark's colour, 12 f). The strips are one image a frame (`Map.strips`): the map drawn for them six times, each from the cursor's mirror a frame later (6 to 11 f behind: `Cursor.lagInto`) with the panes' windows as long ago (`past`), every strip drawn as it shows (its rows, dots and window in place) and the six averaged, so that every change on a strip fades in over 6 f from 6 f after its onset and nothing on it moves a pixel in a frame; the panes blit their part (source, disassembly and its descent and the `blocks` lens's view, stack, a dump's view: not the registers, a drawing, a loupe, the backtrace, the `syscalls` lens's log). A pane with a strip has 48 less for its rows (`map.content`). `Map.show`, `.dive` (outlines bright 6 f, veil to 24, each panel from its window to its place 60 f, 6 f apart, a panel drawn over another setting off first (drawing, view, disassembly, stack, source, registers) so that none in its place is crossed by one on its way, opaque on the way, its rows on the window's rows, its tag and rules in from 84 f; with each, the rest of its column (the rows its strip shows) squeezing from its place on the map into the strip, its width and height each on its logarithm (to 36 of 880, 4 of 24 a row), its window's outline riding on it, gone into the strip's own drawing over the 12 f before its pane lands (`Map.squeeze`, `stripShows`); the map's other parts fading where they are, 24 to 72; 120 f and 30 f still), `.surface` (the dive back, 84 f, then 30 f still); per-panel transforms through `context.at` (`context.zoomed`); the clock's count ranged right at 1856. `unroll` and `roll` (`Map.unroll`, `.roll`, `map.Unroll`, added over everything by `Context.ties`): the panes veiled and the strip's window framed bright (18 f), the pane's whole column growing out of its strip (36 f, `glide`) to as many rows as the stage holds (24 a row at most; right on the strip's edge, the window's rows level with the pane's where the stage allows), its scale on the logarithm from the strip's, the window's outline riding from the strip to the pane's rows in it; held as the scene says; `roll` the reverse (36 f), the veil lifting (18 f). A far jump in the same column at a walk (the source's window farther than its height to lines the map's column of the file holds too, `source.unrolling`, `inColumn`: no step said faster in a hurry) is `unroll`, the window travelling along the column (24 f, `glide`, the mark lighting gold at its new line as the window gets there, the tag's note changing then), `roll` (96 f: `Cursor.travel`), the pane going into the column and coming out of it at its new place, never a fade. Out of the column (another function, a long file) the map's column goes over as the advance starts, so the strip (6 to 11 f behind, a 6 f crossfade) shows where the pane goes before the pane fades through (`over`, `far` on the map at half its height); a window going farther than the column holds keeps its place on the strip until the column goes over (`spanOf2`); the tag's line range changes with the pane's fade; the map's disassembly is measured by the moment the pane shows (a continue repacks the map as the pane gets there), and a recording of breakpoints has its deepest chain read at every stop (`deepest`: the backtrace's box packed once) | +| 5 frame | `map`, `minimap`, `dive`, `surface` | `src/map.zig` (`Map`, `split`, `strip`, `Map.strips`), `Context.map` | the working frame's panels bound to a stage of 3840 by 2160 (`map.split`, packed by content: each box as long as the most rows its panel has wanted, `measure`, the backtrace's as long as the deepest call chain of the scene's way, so that it is packed once; the drawing, the source and under it the backtrace; the disassembly; the view (none where nothing draws one), the registers, and in the column's rest the stack going on, `stack, continued`; the stack from 16 words above rsp; and the first two columns' rest (`Split.spare`) given, in the catalogue's order, to `map.Spare`: a five-row dump round each place the registers (pwndbg's order, not rsp or rbp) and the 64 words up from rsp point at outside the stack and the code, none within another's rows, then the loupes open (`Map.loupes`, lifted, nine rows), then the key (the recording and the moment, the marks as drawn, the inks); only then page); its rows published while `ui.mapping` (the dumps' too); the working windows outlined (2 `dim`, 4 out), each window published with where its step took it from and how far its scroll has gone, so its outline glides; the thread across the gutter (x 1008), gold; a scene without a band can put a drawing on its map (`Map.drawing`); with `Context.Options.graph` the map's drawing is the `blocks` lens's (`graph.Blocks` at its size, 880 by 344, over the source: `split`'s band is the working frame's), the disassembly linear beside it with its blocks ruled. Each pane's minimap (`map.strip`): a strip 40 wide inside its frame at its right, under the tag, on `well` (`theme.strip`), drawn from its column of the map (the source's boxes, the stack's with `stack, continued`, the view's dump; the disassembly's the linear rows round the pc, drawn for the strips alone where the map has a graph or a descent: `Map.In.strips`) at 4 units a row and 36 of 880 across, from what the map drawn for it collects (`ui.strokes`, `ui.collected`: each run of text a stroke 3 high in its ink 65% from the page, the marks 4 by 4 at a row's left in the catalogue's order, an arc with an end off the window a 2-unit line down the left edge, a block's first row ticked); a column longer than the strip the rows round its window, the window in the middle, clamped to the ends, three faint dots where it goes on (fading in over its first row's scroll); the window framed 2 in primary; a mark no working window shows (a word struck or read on the stack or in the view's dump) flashing on its row (a ring 8 to 14 in the mark's colour, 12 f). The strips are one image a frame (`Map.strips`): the map drawn for them six times, each from the cursor's mirror a frame later (6 to 11 f behind: `Cursor.lagInto`) with the panes' windows as long ago (`past`), every strip drawn as it shows (its rows, dots and window in place) and the six averaged, so that every change on a strip fades in over 6 f from 6 f after its onset and nothing on it moves a pixel in a frame; the panes blit their part (source, disassembly and its descent and the `blocks` lens's view, stack, a dump's view: not the registers, a drawing, a loupe, the backtrace, the `syscalls` lens's log). A pane with a strip has 48 less for its rows (`map.content`); its strip is its own context's map's (`map.maps`, each frame's contexts, matched by the pane's box: a scene in chapters has several). `Map.show`, `.dive` (outlines bright 6 f, veil to 24, each panel from its window to its place 60 f, 6 f apart, a panel drawn over another setting off first (drawing, view, disassembly, stack, source, registers) so that none in its place is crossed by one on its way, opaque on the way, its rows on the window's rows, its tag and rules in from 84 f; with each, the rest of its column (the rows its strip shows) squeezing from its place on the map into the strip, its width and height each on its logarithm (to 36 of 880, 4 of 24 a row), its window's outline riding on it, gone into the strip's own drawing over the 12 f before its pane lands (`Map.squeeze`, `stripShows`); the map's other parts fading where they are, 24 to 72; 120 f and 30 f still), `.surface` (the dive back, 84 f, then 30 f still); per-panel transforms through `context.at` (`context.zoomed`); the clock's count ranged right at 1856. `unroll` and `roll` (`Map.unroll`, `.roll`, `map.Unroll`, added over everything by `Context.ties`): the panes veiled and the strip's window framed bright (18 f), the pane's whole column growing out of its strip (36 f, `glide`) to as many rows as the stage holds (24 a row at most; right on the strip's edge, the window's rows level with the pane's where the stage allows), its scale on the logarithm from the strip's, the window's outline riding from the strip to the pane's rows in it; held as the scene says; `roll` the reverse (36 f), the veil lifting (18 f). A far jump in the same column at a walk (the source's window farther than its height to lines the map's column of the file holds too, `source.unrolling`, `inColumn`: no step said faster in a hurry) is `unroll`, the window travelling along the column (24 f, `glide`, the mark lighting gold at its new line as the window gets there, the tag's note changing then), `roll` (96 f: `Cursor.travel`), the pane going into the column and coming out of it at its new place, never a fade. Out of the column (another function, a long file) the map's column goes over as the advance starts, so the strip (6 to 11 f behind, a 6 f crossfade) shows where the pane goes before the pane fades through (`over`, `far` on the map at half its height); a window going farther than the column holds keeps its place on the strip until the column goes over (`spanOf2`); the tag's line range changes with the pane's fade; the map's disassembly is measured by the moment the pane shows (a continue repacks the map as the pane gets there), and a recording of breakpoints has its deepest chain read at every stop (`deepest`: the backtrace's box packed once) | | | `stage` and `relayout` | `src/stage.zig` | splits `none`, `beside`, `subject`, `blocks` (`theme.layout.split`, layout A: the disassembly under the source in every split; the source 14, 8, 8 and 6 lines, the disassembly 17, 17, 11 and 11 rows; `blocks` a drawing of 880 by 344 over the program column and no view, the state column the registers' and the stack's from the top), each for a registers panel of eleven rows; `layout.fit` gives the scene's registers their rows and the stack the rest above the backtrace, whole slots, any rest above it (`Stage.registers_rows`: every split a `relayout` goes to keeps them); the band is `band` (the drawing) and `view`; `relayout` fades the drawing round its move; `holdStack` holds the stack's window for the camera, with `free` slots; `glide` (a column's moves: no fit, no fade), `column` (the clock under the text column), `zoom` (the band's drawing drawn larger, its tag not: `graph.Blocks`) | | | `column` | `src/column.zig` (`Column`, `canim.column`, `beat`) | the shelf (y 48: each folded pane's tag in the frame's order, its note: the scene's, or computed for the registers (those the step changed, the first's value struck as on its row, crossfading with the strike), the source (`line 12`) and the disassembly (`jne 4011af`), crossfading with the advance); the panes from 84 to 1032, 12 apart; texts: `beside` (Go 40 on 54, at most 40 characters a line, 16 of padding, on `raised` while newest, dimming to `dim` without paper, three at most, level with their row, riding it until the panes change or the row goes, an older one gliding above the newest's place or under it), `below` (the caption band), `above` (a band over the drawing), `on` (where the scene puts it, its stem round the drawing's top lane); the change between beats (`change`: fade 6 f, fold where it stands and the tag to the shelf 18 f, glide 24 f (a pane crossing to the other column going down its own first, then across, 24 f each), unfold 18 f, fade in 6 f; a pane that changes its height keeps its rows: `Stage.resizing`, the descent's two layouts glided between, the source's window glided); a stem about a folded pane to its tag; `Beat.held`, and a bubble read past its beat flagged on stderr | -| | `segments` | `src/segments.zig` (`read`, `Segments`, `Place`) | the address space to true scale from the recording's mappings (permissions, file offsets), the tracer's own (its ring, its preloaded agent and the agent's bss) left out: a slim bar the column's height, its ends' addresses and its size; clusters split at gaps of 16 MiB or more, and a band eight times the rest of its cluster in a box of its own; `enlarge` a box at a time (its bands with start, end and size, leaders to the bar), 108 wide; an edge's address in the ink of the band that starts there; a file name past the column's edge cut with `…`; kept above y 888 under the camera (`clipStage`); `Place`, a dump's place on it (the `tie` and the `link`), and for a camera's visit the place marked on its box (`tick`: a 2-unit line across the box in the stack's ink, `128 bytes` over it) | -| | the introduction's dump | `src/regroup.zig` (`Words`) | 128 bytes sixteen a row, no ink, the addresses faint, its header the address it starts at; `regroup` to eight a row (bytes become words, low byte last, a word that is no address with `0x`; a word in the top four rows has its offsets over it in the header's row (veiled with the rest), `low byte` left of `+0` and `high byte` right of `+7`, and its bytes fly over that row, 40 up, each with its offset over it, one in the air at a time (24 f each, 18 f apart: the 36 f of motion.md, 6 f apart, crossed in the air there), a label going as its byte lifts and coming as it lands; nothing printed over a row), `fold` (the rows glide up into the header, 24 f, the header becomes the tag, which goes to the shelf, 24 f), `ink`, `extend`, `become` (the bytes go, then the words and addresses glide into the stack panel's rows); with no heap word in the bytes, the first other address is framed | +| | `segments` | `src/segments.zig` (`read`, `Segments`, `Place`) | the address space to true scale from the recording's mappings (permissions, file offsets), the tracer's own (its ring, its preloaded agent and the agent's bss) left out: a slim bar the column's height, its ends' addresses and its size; clusters split at gaps of 16 MiB or more, and a band eight times the rest of its cluster in a box of its own; `enlarge` a box at a time (its bands with start, end and size, leaders to the bar), 108 wide; an edge's address in the ink of the band that starts there; a file name past the column's edge cut with `…`; kept above y 888 under the camera (`clipStage`); `Place`, a dump's place on it (the `tie` and the `link`), and for a camera's visit the place marked on its box (`tick`: a 2-unit line across the box in the stack's ink, `128 bytes` over it); live (`Segments.pins`, the introduction's II2 and II3): rip a `row` pin at the end of its band's row (`◂ rip`), rsp and rbp an `under` pin in the stack's band, rbp's name left, each in rising 8 as the scene plays it; `ink`'s echoes, up to 24 | +| | the introduction's dump | `src/regroup.zig` (`Words`) | 128 bytes sixteen a row, no ink, the addresses faint, its header the address it starts at; `regroup` to eight a row (bytes become words, low byte last, a word that is no address with `0x`; a word in the top four rows has its offsets over it in the header's row (veiled with the rest), `low byte` left of `+0` and `high byte` right of `+7`, and its bytes fly over that row, 40 up, each with its offset over it, one in the air at a time (24 f each, 18 f apart: the 36 f of motion.md, 6 f apart, crossed in the air there), a label going as its byte lifts and coming as it lands; nothing printed over a row), `fold` (the rows glide up into the header, 24 f, the header becomes the tag, which goes to the shelf, 24 f: to the shelf's height first, then along it, over what stands under it; back, the reverse), `back` (its header back over its rows after it was tied to its place, before a fold), `top` (set anew while folded, it unfolds there: II8 brings it back at the rows III's stack gives it), `ink`, `extend`, `become` (the bytes go, then the words and addresses glide into the stack panel's rows); with no heap word in the bytes, the first other address is framed | | | `aligned` | `src/aligned.zig` | the source and its instructions in one panel, each line level with its code: `interleaved` and `columns`; the lines without their indent; the mnemonics after the longest instruction's bytes; the pc's row annotated (what it reads, its chain); `decode` (an instruction's bytes to its row), `align` (one form to the other: the bytes go first, then the columns glide) and `stack` (to the working frame: the heads' paper, rules and tag out 12 f, the lines to the source panel's rows 36 f, the instructions down their column 24 f and into the disassembly's rows 24 f, those its window does not show fading past its edge; the scene fades the panels in under them) | -| | a text standing alone | `src/aside.zig` (`Aside`, `Asides`) | a column's bubble where no `Column` stands (the introduction's texts beside, and above its aligned code, two lines of 80 characters there: `Asides.wrap`); a newline breaks where the author says; one the new text would stand on leaves first, then a gap; `shortcut:` it repeats `column.zig`'s bubble drawing | +| | a text standing alone | `src/aside.zig` (`Aside`, `Asides`) | a column's bubble where no `Column` stands (the introduction's texts beside, and above its aligned code, two lines of 80 characters there: `Asides.wrap`); a newline breaks where the author says; one the new text would stand on leaves first, then a gap; with a `floor` (the introduction's II), one in the way glides down under the new one instead (24 f, the new one arriving after), the others under it with it, as far as the floor (past it, it leaves), and three stand at most; `shortcut:` it repeats `column.zig`'s bubble drawing | | | a caller's rows alone, a stack built a column at a time | `src/descent.zig` (`Caller`), `src/context.zig` (`Stack.reveal`) | `Caller`: a descent's head row over a call, the row it returns to and the next, each a `row` place for an `aim` (chapter II's main); `reveal`: the stack's offsets, roles and spans each under the page until the scene's clock lets them in top down (`column`, 2 f apart, 12 f each) | | | `pair` | `src/pair.zig` (`split`, `Frame`, `Report`, `Marks`, `Clock`, `Shelf`) | two runs on either side of the seam (design/README.md, `pair`): `split` each side's stage; `Frame` a frame as bytes eight a row read by its fields (`hexdump` `eight`: fields live from a moment, the letters keeping a string's ink in a pointer's field, the shadow byte of each row beside it, tall in the column, its words said as values for the relations); `Report` a stopped run's stderr in place of its registers; `Marks` `only here`, `differs`, `attention` and the `fault` (hazard bands round an ink plaque, SIGSEGV); `Clock` one rule and each run's moment; `Shelf` a folded side's tag | -| | `clock`, `caption`, `veil`, `card` | `src/words.zig`, `src/root.zig` (`Narrator`, `Camera`) | the clock still while a step plays, its piece fading in once the mark lands; a caption stays its reading time; the title card is `scenes/title.zig` | -| 6 verb | `fire`, `arm`, `strike`, `cool`, `read`, `extend`, `link`, `project`, `travel` (pins), `advance`, `cascade`, `continue` (`Cursor.continue`, `Plan.wave`), `run`, `sprint`, `establish` (`Context.establish`: a drawing's elements fade in rising, no lines), `scroll`, `relayout`, `visit`, `say`; `unroll` and `roll` (`Map.unroll`, `Map.roll`, above); `reach` and `unfold` (`graph`, above); `leave` and `turn` (`graph.leave`, from a block's last row, `graph.toEnd` to get there, along the curves of `rings` or `layers`: fire 0–12; the compare's chips framed as read from 18 (the CPU's slot, the jump's echo), held while the edge draws gold, head first, 24–42; the mark (a gold plaque, its point the way it goes) along the edge 42 to 42 + 12 f and 2 f a 100 units of the drawing's edge (42 f at most), round the ring's foot for a turn; landing, the advance; the target's count armed and struck 6 f after (a ring's turns at its centre armed as the mark leaves the latch, struck as it lands), cooled to nothing by the step's end; the trail recoloured over 18 f from the landing; a rest of 42 f from the landing); over a graph at a walk of several blocks, a run or a sprint the trail, the counts and the gold crossfade with the advance (8 f at a run, the step at a sprint), the pan gliding with it | `src/cursor.zig` (the timetable), `src/graph.zig` (`leave`, `instant`), the blocks (each draws its state at the instant) | tokens in `theme.time`; a level gives up its slot when nothing it touched is drawn (`Recording.drawn`); a label that changes in place with a step crossfades over the 12 f before the advance, or from the step's start where that is sooner (`Now.renaming`); at a run what marked a value goes with the run's ease (8 f) and a pin changes over it; at a sprint an ember and what grows come in over the step (4 f), never in a frame | +| | `clock`, `caption`, `veil`, `card`, `chapter` | `src/words.zig`, `src/root.zig` (`Narrator`, `Camera`) | the clock still while a step plays, its piece fading in once the mark lands; a caption stays its reading time; the title card is `scenes/title.zig`; a chapter's title said in the caption's place (`Title`: Go Medium 40, the numeral faint, the name bright, in rising 8 as a caption) and its name the clock's label (`ChapterLabel`: Go 18 faint, ranged right 24 left of the count at its widest, `moment 193 of 193`, so that it stands still as the count grows, or alone at 1856 where there is no clock yet; the chapters' names crossfading at a seam, and from alone to beside the count out, then in, never over it) | +| 6 verb | `fire`, `arm`, `strike`, `cool`, `read`, `extend`, `link`, `project`, `travel` (pins), `advance`, `cascade`, `continue` (`Cursor.continue`, `Plan.wave`), a call stepped over (`Cursor.over`: rax struck first, in the CPU's slot at 48, then the others in a wave from 66, 2 f apart; a hold of 36 f; 2.4 s), `unpack` and `pack` (`Registers.parts`), `fold` on a beat (`Registers.fold`), `title` (a scene in chapters: `scenes/intro.zig`, `seam`), `run`, `sprint`, `establish` (`Context.establish`: a drawing's elements fade in rising, no lines), `scroll`, `relayout`, `visit`, `say`; `unroll` and `roll` (`Map.unroll`, `Map.roll`, above); `reach` and `unfold` (`graph`, above); `leave` and `turn` (`graph.leave`, from a block's last row, `graph.toEnd` to get there, along the curves of `rings` or `layers`: fire 0–12; the compare's chips framed as read from 18 (the CPU's slot, the jump's echo), held while the edge draws gold, head first, 24–42; the mark (a gold plaque, its point the way it goes) along the edge 42 to 42 + 12 f and 2 f a 100 units of the drawing's edge (42 f at most), round the ring's foot for a turn; landing, the advance; the target's count armed and struck 6 f after (a ring's turns at its centre armed as the mark leaves the latch, struck as it lands), cooled to nothing by the step's end; the trail recoloured over 18 f from the landing; a rest of 42 f from the landing); over a graph at a walk of several blocks, a run or a sprint the trail, the counts and the gold crossfade with the advance (8 f at a run, the step at a sprint), the pan gliding with it | `src/cursor.zig` (the timetable), `src/graph.zig` (`leave`, `instant`), the blocks (each draws its state at the instant) | tokens in `theme.time`; a level gives up its slot when nothing it touched is drawn (`Recording.drawn`); a label that changes in place with a step crossfades over the 12 f before the advance, or from the step's start where that is sooner (`Now.renaming`); at a run what marked a value goes with the run's ease (8 f) and a pin changes over it; at a sprint an ember and what grows come in over the step (4 f), never in a frame | `Recording` (`src/Recording.zig`) is the index every block reads: lines, calls, syscalls, allocations, which registers and bytes each moment changed @@ -288,7 +286,7 @@ before. The source panel follows the pc into any file it has | `musl` | `hello.c` again, built by Zig for `x86_64-linux-musl`, static, `-O0 -g` (musl compiled from its sources with it: no PLT, its lines its own) | every instruction, `--from main`, `--steps 166` (to main's return) | 173, 55 KB | reads `tools/note` | | `gallery` | the old `list` by line, kept in `test/gallery/list.ztrace`; for the graph pages `sort` and `hello` as recorded on 11 November (with blocks), kept in `test/gallery/sort.ztrace` and `hello.ztrace` (`gallery_sort`, `gallery_hello`) | | 134, 88 KB; 776 KB; 87 KB | the gallery's pictures depend on the drawing only | | `sqlite` | `sqlite.c` (three rows into a table, committed) with SQLite 3.50.4's amalgamation, system clang `-O2 -g -fno-omit-frame-pointer -no-pie -fno-stack-protector -Wl,-z,now`, glibc | `--by break`: `sqlite3_step`, `sqlite3BtreeInsert`, `unixWrite`, and the instruction after its `pwrite64` (found by objdump); every syscall recorded, `-s 4096` | 181 (42 stops, 138 syscalls), 494 KB | made only with `-Dsqlite=DIR` (default `~/05-genizah/sqlite/sqlite-amalgamation-3500400`), in a new temporary directory each time; `sqlite3.c` is embedded as the source | -| `intro` | `list.c` again, as the compiler alone makes it: the system's clang `-O0 -g -mno-red-zone -no-pie -fno-stack-protector -Wl,-z,now`, glibc, no instrumentation (no red zone: reverse's prologue is `push rbp; mov rbp, rsp; sub rsp, 0x18`, its locals at `rbp-8`, `-0x10`, `-0x18`) | every instruction, `--from list.c:41` (main's call of reverse), `--until list.c:22` (past the load); run as `./list` | 74 (60 of them the loader's and the agent's syscalls before main), 54 KB | `--alloc --preload` (the allocations), `-w head`; its locals named by the debug info (`zt.telescope.slots`); the types the nodes lens needs (`head`, `struct node`) declared by chapter III (`Recording.declare`): the tracer reads none from the debug info | +| `intro` | `list.c` again, as the compiler alone makes it: the system's clang `-O0 -g -mno-red-zone -no-pie -fno-stack-protector -Wl,-z,now`, glibc, no instrumentation (no red zone: reverse's prologue is `push rbp; mov rbp, rsp; sub rsp, 0x18`, its locals at `rbp-8`, `-0x10`, `-0x18`) | every instruction, `--from list.c:40` (main's push(9), the first stop at moment 32: the clock counts from it), `--until list.c:22` (past the load); run as `./list` | 226 (32 of them the loader's system calls before main; malloc's 162 instructions in push(9) stepped through), 208 KB | the program's alone (no agent: the step over `call malloc` changes only rax, rcx, rsi and rdi, and r11's word); `--heap` (glibc's heap at each stop: the list's nodes are the chunks in use there, the scene reading its allocations off it, `Recording.allocationsFromHeap`, `Recording.allocated`), `-w head`; its locals named by the debug info (`zt.telescope.slots`); the types the nodes lens needs (`head`, `struct node`) declared by the scene (`Recording.declare`): the tracer reads none from the debug info | | `overflow` | `overflow.c` (design/mock/overflow.c: a loop writing 32 bytes into `char buf[16]`), the system's clang `-O0 -g -fno-omit-frame-pointer -no-pie -fno-stack-protector`, glibc | every instruction, `--from main`, to the fault | 298, 60 KB | the recorder says `exit 139`; the SIGSEGV on the moment after `ret`, rip unchanged | | `overflow_asan` | the same with `-fsanitize=address`, `ASAN_OPTIONS=detect_leaks=0` | every instruction, `--from main`, `--until __asan_report_store1` (its first stop there: past its `endbr64; push rbp; mov rbp, rsp`, as `-b` places a function's breakpoint) | 788, 257 KB | `--asan` (the shadow); the fake frame's header parsed by the scene from memory; the scene finds its moments by what the instructions are (the parting turn's load, `je`, the partial check's `cmp` and branch, the call), none by a count | | `overflow_report` | the same run | `--by syscall --stack 0 --telescope 0 -s 4096` | 707, 401 KB | the report: its `write(2, …)`s, shown from their capture; `exit 1` | @@ -369,41 +367,77 @@ captions do not pair up it says so and checks no reading time), or the picture moving within 60 f of its arrival; chart.py does not count the list's dive (150 to 300 f) as a caption's change. -| | fib | list | sort | syscalls | musl | zoom | sqlite | heap | gallery | title | column | column_sort | asan | intro_memory | intro_stack | intro_code | -| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | -| POP, before / after | 3 / 3 | 10 / 10 | 4 / 4 | 13 / 13 | 7 / 7 | 2 / 2 | 6 / 6 | 15 / 15 | 9 / 9 | 0 / 0 | 4 / 4 | 6 / 6 | 16 / 16 | 1 / 1 | 0 / 0 | 0 / 0 | -| of them the strips', before / after | 1 / 1 | 4 / 4 | 3 / 3 | 9 / 9 | 1 / 1 | 1 / 1 | 0 / 0 | 4 / 4 | 3 / 3 | 0 / 0 | 2 / 2 | 3 / 3 | 0 / 0 | – | – | – | -| POP exempt, before / after | | keyframe 1 / keyframe 1 | | | | | | | cut 5 / cut 5 | | | | | | | | -| CROWD, before / after | 3 / 3 | 7 / 7 | 8 / 8 | 4 / 4 | 6 / 6 | 3 / 3 | 2 / 2 | 16 / 16 | 5 / 5 | 0 / 0 | 0 / 0 | 0 / 0 | 15 / 15 | 0 / 0 | 0 / 1 | 0 / 0 | -| METRONOME, before / after | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | -| CAPTION up over 720 f, before / after | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | | 0 / 0 | 1 / 1 | 1 / 1 | 1 / 1 | 0 / 0 | 0 / 0 | -| CAPTION under its reading time, before / after | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | | | not checked | not checked | not checked | not checked | not checked | not checked | -| CAPTION picture moving within 60 f, before / after | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | | not checked | 1 / 1 | not checked | 1 / 1 | 0 / 0 | 1 / 0 | -| AIR, before / after | 0 / 0 | 0 / 0 | 1 / 1 | 0 / 0 | 0 / 0 | 1 / 1 | 1 / 1 | 0 / 0 | 1 / 1 | 1 / 1 | 0 / 0 | 0 / 0 | 1 / 1 | 0 / 1 | 1 / 1 | 1 / 0 | -| seconds, before / after | 48.2 / 48.2 | 83.9 / 83.9 | 74.5 / 74.5 | 85.4 / 85.4 | 66.8 / 66.8 | 34.9 / 34.9 | 62.9 / 62.9 | 80.2 / 80.2 | 27.0 / 27.0 | 12.3 / 12.3 | 95.3 / 95.3 | 29.5 / 29.5 | 120.0 / 120.0 | 67.2 / 70.0 | 31.8 / 42.5 | 40.8 / 44.8 | +| | fib | list | sort | syscalls | musl | zoom | sqlite | heap | gallery | title | column | column_sort | asan | intro | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| POP, before / after | 3 / 3 | 10 / 10 | 4 / 4 | 13 / 13 | 7 / 7 | 2 / 2 | 6 / 6 | 15 / 15 | 9 / 9 | 0 / 0 | 4 / 4 | 6 / 6 | 16 / 16 | – / 0 | +| of them the strips', before / after | 1 / 1 | 4 / 4 | 3 / 3 | 9 / 9 | 1 / 1 | 1 / 1 | 0 / 0 | 4 / 4 | 3 / 3 | 0 / 0 | 2 / 2 | 3 / 3 | 0 / 0 | – / – | +| POP exempt, before / after | | keyframe 1 / keyframe 1 | | | | | | | cut 5 / cut 5 | | | | | – / none | +| CROWD, before / after | 3 / 3 | 7 / 7 | 8 / 8 | 4 / 4 | 6 / 6 | 3 / 3 | 2 / 2 | 16 / 16 | 5 / 5 | 0 / 0 | 0 / 0 | 0 / 0 | 15 / 15 | – / 0 | +| METRONOME, before / after | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | – / 0 | +| CAPTION up over 720 f, before / after | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | | 0 / 0 | 1 / 1 | 1 / 1 | – / 4 | +| CAPTION under its reading time, before / after | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | | | not checked | not checked | not checked | – / not checked | +| CAPTION picture moving within 60 f, before / after | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | | not checked | 1 / 1 | not checked | – / 4 | +| AIR, before / after | 0 / 0 | 0 / 0 | 1 / 1 | 0 / 0 | 0 / 0 | 1 / 1 | 1 / 1 | 0 / 0 | 1 / 1 | 1 / 1 | 0 / 0 | 0 / 0 | 1 / 1 | – / 3 | +| seconds, before / after | 48.2 / 48.2 | 83.9 / 83.9 | 74.5 / 74.5 | 85.4 / 85.4 | 66.8 / 66.8 | 34.9 / 34.9 | 62.9 / 62.9 | 80.2 / 80.2 | 27.0 / 27.0 | 12.3 / 12.3 | 95.3 / 95.3 | 29.5 / 29.5 | 120.0 / 120.0 | – / 210.6 | -"Before" is the last pass's "after". This pass exported again (at 1080 -and 2160) the introduction's three (`intro_memory`, `intro_stack`, -`intro_code`) alone; every other scene's cells repeat the last pass's. The -column's, column_sort's and asan's "caption" regions are not a caption's -(the text column, a drawing's band), so their CAPTION lines are not a -caption's; the column's own check is the renderer's (`column: bubble N is -still read …`): C2's bubble (74 characters) 1.8 s past its three steps. -The introduction's texts beside are not in the caption band either: in -`intro_memory` the band is empty for the column part (from 21.6 s), which -the instrument reads as one caption up 22 s with the picture moving; the -reading times are the scenes' own (`Narrator`, `Asides`: each text waits -until the last is read). `intro_memory`'s POP (38.70) is the program's -`enlarge`, its line framed bright at the stage's foot (looked at, frame by -frame: it changes from 38.62, 12 pixels, growing). `intro_stack`'s CROWD -(23.32) is the push's advance: the pc's mark moving down reverse's rows, -the registers' marks and the stack's cooling, as every walked step's -advance does where the three panels stand (the last pass's II showed no -code). I's and II's AIR is the chapter's last picture, the last text read -and the 2 s before the cut (III ends as the map surfaces under its text). +"Before" is the last pass's "after". This pass exported (at 1080 and 2160) +the introduction alone, `intro`, new as one scene (its regions are the two +columns: `chart.py`; its three chapter scenes and their charts are gone, the +last pass's cells for them: intro_memory POP 1, CROWD 0, AIR 1, 70.0 s; +intro_stack 0, 1, 1, 42.5 s; intro_code 0, 0, 0, 44.8 s); every other scene's +cells repeat the last pass's. The column's, column_sort's and asan's +"caption" regions are not a caption's (the text column, a drawing's band), +so their CAPTION lines are not a caption's; the column's own check is the +renderer's (`column: bubble N is still read …`): C2's bubble (74 +characters) 1.8 s past its three steps. The introduction's texts beside are +not in the caption band either: the band is empty for I's column part (from +23.35 s), II from II4 (94.15 s), III (130.22 s) and IV's texts above (167.02 +s), which the instrument reads as four captions up over 12 s with the picture +moving; the reading times are the scene's own (`Narrator`, `Asides`: each +text waits until the last is read; the titles theirs). Its AIR is three +chapters' last pictures held while their last text is read and the seam's +30 f before the texts go (67.22 s, 5.0 s: I10's 91 characters; 122.48 s, +4.6 s: II8's 93) and IV3's reading (183.33 s, 3.7 s). No POP: the draft's +three were looked at, frame by frame, and are gone (96.33, the pc's mark +coming to its row, now eased; 108.90, r11's later hop changing at the +step's first frame, now with memory's strike over 6 f; 206.23, the clock +gone under IV's map as it surfaced, now the same clock over it). The chart: +`out/motion/intro`. -This pass changed (the introduction, a correction round after a review of -its three chapters frame by frame): +This pass changed (the introduction as one scene, with its chapter on registers): + +- `intro` (`scenes/intro.zig`) is the introduction's one scene and video; its + chapters are functions of their own files, called in order, each opening on + the last picture of the one before at a seam (`title`); the three chapter + scenes and their videos and test scripts are gone. Chapter II, registers, is + new (`scenes/intro_registers.zig`); III goes on on II's context (its + registers, its code, its cursor: III's beat that built the registers is + gone, and rsp's and rbp's rows and reverse's rows no longer arrive in it); + IV's clock is the same clock stepped on to the load. +- The recording `intro` starts at `list.c:40`, push(9), the program's alone + (no agent), with glibc's heap at each stop (`--heap`): the nodes' memory + blocks are the chunks in use there (`Recording.allocationsFromHeap`, which + the scene calls: the allocations read off the heap where no agent told + them, `Born.gone`; `Recording.allocated`, used by the objects' liveness and + the dump's reading; the `heap` scene, which draws the heap its own way, + does not call it, and times its steps as before). +- New blocks and verbs: `Registers.fold` on a beat, `Registers.parts` + (`unpack`, `pack`, its echo), `Registers.framed`; `Context.Options.moves`; + `Cursor.over` and `Plan.result` (a call stepped over, its result first; + `ties.strikeDelay`, `Now.register`); the call row's annotation in that step + and a call's result in hex where it is an address (`malloc(16) = + 405050`; in any scene: the other videos were not exported again); `Disasm.mark_in`; the + introduction's first value struck with its register, and no `· rsp -8` on + its call row; `Segments.pins` (`◂ rip`, rbp and rsp in the stack's band); + `Words.top` and `.back`, the tag's way to the shelf (its height first, then + along it); `Asides.floor` (an older text glides down under a newer one, three + at most); `words.Title` and `ChapterLabel`; each pane's strip from its own + context's map (`map.maps`). +- Outside the introduction the pictures are as they were (the gallery's + pictures compared by the tests), but for a call's result that is an address. + +The pass before (the introduction, a correction round after a review of +its three chapters frame by frame) changed: - The recording `intro` is the plain build (`-O0 -g -mno-red-zone`, no instrumentation; `Recording.cc`), so II walks reverse's own `push rbp; mov @@ -441,7 +475,7 @@ its three chapters frame by frame): history), `Asides.wrap`, `Stack.Reveal.apart`, `Nodes.named` and `Place.tick` are new and off by default. -The pass before changed: +Two passes before changed: - The ASan run is recorded `--until __asan_report_store1` (no count), and the scene finds its moments by what the instructions are; the pair's @@ -475,7 +509,7 @@ The pass before changed: it is inside a step by line, so rbp lands on the saved rbp's row, not rsp's (f586 to f623, smooth). fib's and zoom's counts are unchanged. -The pass before that (the introduction) changed, outside its three scenes: a pin +Three passes before (the introduction) changed, outside its three scenes: a pin joining another's row in front of its names (`mov rbp, rsp`: rbp onto rsp) lets its own head go as it lands, not in the advance's frame (`Stack`); the pc's triangle on `aligned`'s plaque is drawn where it is (it was transformed @@ -617,48 +651,30 @@ What fires still (the finals; located where it says so): (`column: bubble 3`) is read 1.5 s past its beat's steps. The fake frame's header is parsed by the scene from memory, plain's fields from the instructions' rbp offsets, and the two runs' stops are matched by pc. -- The introduction (`intro_memory`, `intro_stack`, `intro_code`), exported: - where it differs from its storyboard and mocks. The recording is `intro`, - the plain build (main's call of reverse to past the load), so the push II - walks is reverse's own `push rbp`, I's 128 bytes are at rsp at that push - (the return address the top word, `main+50`, `401272`, not the - storyboard's `main+80`), and the frame is `sub rsp, 0x18`. The types - chapter III's nodes are drawn by are declared by the scene from `list.c` - (`Recording.declare`): the tracer reads no types from the debug info, - only the locals' names and places. I (70 s against 66): the walked word - is the top row, with two rows of room over it at x2: its offsets stand in - the header's row, `low byte` and `high byte` outside them, and its bytes - fly over that row (40 up) one at a time (24 f each, 18 f apart; motion.md's 36 f, - 6 f apart, crossed in the air there), each label going as its byte lifts - and coming as it lands; a library's file name past the column's edge is - cut (`ld-linux-x86-64…`; mock 34 says `ld.so`); the visit is at x2 (the - storyboard's x4 showed the box alone, cut its names), the dump's rows - running on past the frame's right edge at a byte's edge. II (42.5 s - against 26.5): six beats (the convention, rsp, the call, the push, the - frame, the registers), the call before the push; reverse's rows are a - disassembly panel of seven rows under main's three (its tag with the - stack's, `frame up`); its registers canim's folded layout at x1 (mock 31: - seventeen rows at x1.25), so the stack keeps twenty rows, four of them - `free` over rsp and held; the push's store of the value its word held is - struck (the catalogue arms it alone); a return address's role is `the way - back` (II4's words; `return address` would cut `main+50`); main's rows go - at III's opening (III's code is reverse's). III (44.8 s against 30.3): it - opens on II's last picture (as II walked it: `Cursor.jumpWalked`), its - state column veiled until the decoded code spans it (the review said until - `align`: the interleaved panel spans the state column, and its code - printed over the veiled stack); `columns` (mock 36) is a beat of its own; - no camera (at x1.5 the band's nodes and its dump do not both fit); the - texts above take two lines of 80 characters (the band of 120); node 9's - row in the dump reads `9 → 405030` beside `◂rax`, which stays at the row's - end (the review asked for it in the address gutter, where the arcs' lanes - leave no room), node 12's still `12 …` beside `◂rcx`; the minimaps draw - themselves 72 f apart, the decoded rows come 4 f apart and `align` takes - 120 f (the texts are long, and would stand still over 3 s); II's offsets - and roles come down the rows 4 f apart (`Stack.Reveal.apart`); the map's text is a caption, landing before - `surface`. The strips fill in over III's first 10 frames (no lagged - windows yet), as before. The caption checks cannot pair the texts beside - with the caption band, so their reading times are the scenes' own - (`Asides`, `Narrator`). +- The introduction (`intro`), exported: where it differs from its + storyboard and mocks. One video, 210.6 s against 206: I 0:00 to 1:11.7 + (71.7 s against 71.4), II to 2:06.6 (54.9 s against 52.0: an older text in + the way glides down under the newer before it arrives, 24 f each time, and + II5's step and `pack` take their own frames), III to 2:43.0 (36.4 s against + 35.3), IV to 3:30.6 (47.6 s against 47.5). The recording's moments are the + storyboard's (6 at II's start, 7, 169 after malloc, 182 at reverse, 191 at + the load, of 193); its stack is 256 bytes lower than the mocks' (the 128 + bytes at `7fffffffecc8`: a run with no agent preloaded). The clock's label + stands where it is beside the count at its widest (`moment 193 of 193`), so + it is 48 left of `moment 6` (mock 58: 24 left of the count, moving with + it); from alone at 1856 to beside the count it goes out, then in, with the + clock (12 f each), never over it. The tag of the 128 bytes crosses the + registers' tag on its way back (II8: along the shelf's height, then down); + in `fold` the quiet rows going down cross the rows going up, as the dive's + fold does. Push's six rows scroll a row as the pc comes onto the call (the + window keeps the pc in its third row; mock 60 holds it). The chapters' own + beats are as they were (I's, III's less its registers' beat, IV's); IV1's + `08is` (a mono run's spaces in a text beside drawn wider than measured, + `aside.zig`) is as it was. The chart's caption checks cannot pair + the texts beside with the caption band; their reading times are the + scene's own (`Narrator`, `Asides`). The register set is the one II's steps + change (rax rcx rsi rdi, rbp rsp), computed from the recording, eleven rows + from II8 to the end. - The relations: arcs within a panel (the stack's, a dump's, a loupe's) are still each panel's own (`rows.Arcs`, lanes per panel), not rows of the frame's tables; the column's stems are drawn by the column, their diff --git a/anim/build.zig b/anim/build.zig index 2263c61..9c95ff5 100644 --- a/anim/build.zig +++ b/anim/build.zig @@ -16,7 +16,7 @@ const std = @import("std"); const sketchbook = @import("sketchbook"); -const scenes = [_][]const u8{ "title", "fib", "list", "sort", "syscalls", "musl", "zoom", "heap", "gallery", "column", "column_sort", "intro_memory", "intro_stack", "intro_code", "asan" }; +const scenes = [_][]const u8{ "title", "fib", "list", "sort", "syscalls", "musl", "zoom", "heap", "gallery", "column", "column_sort", "intro", "asan" }; pub fn build(b: *std.Build) void { const target = b.standardTargetOptions(.{}); @@ -139,9 +139,12 @@ pub fn build(b: *std.Build) void { // The introduction's: the same program as the compiler alone makes it // (no tracer's calls in reverse; no red zone, so its prologue makes // room for its locals: `push rbp; mov rbp, rsp; sub rsp, 0x18`; its - // locals named by the debug info), from main's call of reverse to - // line 22, past the load; `head` watched, the global the list hangs from. - .{ .name = "intro", .source = "list.c", .by = "insn", .glibc = true, .cc = &.{ "clang", "-O0", "-g", "-mno-red-zone", "-no-pie", "-fno-stack-protector", "-Wl,-z,now" }, .from = "list.c:41", .until = "list.c:22", .alloc = true, .watch = &.{"head"}, .program = "list" }, + // locals named by the debug info), from main's push(9) (its call of + // malloc, which chapter II steps over) to line 22, past the load; the + // program's alone (no agent: malloc changes only what glibc's does), + // glibc's heap at each stop for the list's nodes; `head` watched, the + // global the list hangs from. + .{ .name = "intro", .source = "list.c", .by = "insn", .glibc = true, .cc = &.{ "clang", "-O0", "-g", "-mno-red-zone", "-no-pie", "-fno-stack-protector", "-Wl,-z,now" }, .from = "list.c:40", .until = "list.c:22", .heap = true, .watch = &.{"head"}, .program = "list" }, // `hello` again, built by Zig against musl, static: no PLT; musl's // own source (`open.c`, `syscall_cp`) on the way down to the kernel. .{ .name = "musl", .source = "hello.c", .by = "insn", .from = "main", .steps = "166", .reads = "note" }, diff --git a/anim/scenes/intro.zig b/anim/scenes/intro.zig new file mode 100644 index 0000000..2289981 --- /dev/null +++ b/anim/scenes/intro.zig @@ -0,0 +1,228 @@ +//! The introduction (design/motion.md, "A scene: the introduction"): one +//! scene, one video, four chapters on one recording (`intro`: list.c from +//! main's push(9) to line 22) and one clock counted forward only, from the +//! recording's first stop at line 40. Each chapter opens on the last +//! picture of the one before, at a seam that says its title in the +//! caption's place (`title`) and keeps its name as the clock's label: +//! I Memory (`intro_memory.zig`), II Registers (`intro_registers.zig`), +//! III The stack (`intro_stack.zig`), IV Code and meaning (`intro_code.zig`), +//! each a function this scene calls in order. +const std = @import("std"); +const anim = @import("anim"); +const sk = @import("sketch"); +const canim = @import("canim"); +const recordings = @import("recordings"); +const memory = @import("intro_memory.zig"); +const registers = @import("intro_registers.zig"); +const stack = @import("intro_stack.zig"); +const code = @import("intro_code.zig"); + +pub const background = canim.background; +pub const scene = anim.Live(frame, struct {}); + +const t = canim.theme.time; + +/// The chapters' names, as the clock's label says them (`II registers`). +const names = [_][]const u8{ "I memory", "II registers", "III the stack", "IV code and meaning" }; + +fn frame(s: *anim.Frame) void { + const rec = canim.open(recordings.intro); + // The list's nodes are the chunks in use on glibc's heap (no agent told the allocations). + rec.allocationsFromHeap(); + // list.c's types as the pass would tell them: the recording is of the + // plain build, which tells none (its locals are the debug info's). + rec.declare("head", "*`struct node`"); + rec.declare("`struct node`", "struct(16){value@0:i64;next@8:*`struct node`;}"); + const label: Label = .{ .which = s.value(0), .docked = s.value(0) }; + + // I: its title from nothing (in at 6 f, read, out), the chapter's first text 6 f after it. + s.cursor = f(6); + const first = say(s, "I", "Memory"); + first.out(s); + const one = memory.chapter(s, rec); + const two_title = seam(s, one.e, &.{one.caption}, "II", "Registers", label, 1); + const two = registers.chapter(s, rec, one, two_title, label); + const three_title = seam(s, two.e, two.texts(s), "III", "The stack", label, 2); + const three = stack.chapter(s, rec, two, three_title); + const four_title = seam(s, three.e, three.texts(s), "IV", "Code and meaning", label, 3); + code.chapter(s, rec, three, four_title); + + // The clock's label, over every clock, from the first frame (the scene's end is where the cursor is left). + const end = s.cursor; + s.cursor = 0; + const o = place(s, s.new(canim.ChapterLabel{ .names = &names, .which = label.which, .docked = label.docked, .widest = "moment 193 of 193" })); + s.play(.{o.fadeIn()}, .{ .seconds = 0 }); + s.cursor = end; +} + +/// The clock's label: which chapter (`ChapterLabel.which`), and whether the clock is there to stand beside. +pub const Label = struct { which: anim.Value, docked: anim.Value }; + +/// A chapter's title on screen, and when it has been read. +pub const Title = struct { + obj: anim.Obj, + read_by: f32, + + /// It leaves at its reading time or now, the later (12 f); the cursor + /// 6 f after: where the chapter's first text arrives. + pub fn out(ti: Title, s: *anim.Frame) void { + s.wait(@max(ti.read_by - s.cursor, 0)); + s.play(.{ti.obj.fadeOut()}, .{ .seconds = t.caption_out, .ease = canim.ease.exit }); + s.wait(t.caption_gap); + } +}; + +/// A chapter's title said in the caption's place (18 f, rising 8); the cursor where it has landed. +pub fn say(s: *anim.Frame, numeral: []const u8, name: []const u8) Title { + const o = canim.add(s, canim.Title{ .numeral = numeral, .name = name }); + s.play(.{o.fadeIn()}, .{ .seconds = t.caption_in, .ease = canim.ease.enter }); + return .{ .obj = o, .read_by = s.cursor + t.caption(@intCast(numeral.len + 2 + name.len)) }; +} + +/// A seam (design/README.md, `title`), from `e`, the frame the chapter +/// before has its last text read: still 30 f; `going` (its texts) leave +/// together (12 f); the title arrives (48 to 66, rising 8), the clock's +/// label crossfading to the chapter's with it (54 to 66, secondary); +/// still to 126, where the cursor is left: the next chapter's opening. +pub fn seam(s: *anim.Frame, e: f32, going: []const anim.Obj, numeral: []const u8, name: []const u8, label: Label, chapter: f32) Title { + for (going) |o| { + s.cursor = e + f(30); + s.play(.{o.fadeOut()}, .{ .seconds = t.caption_out, .ease = canim.ease.exit }); + } + s.cursor = e + f(48); + const ti = say(s, numeral, name); + s.cursor = e + f(54); + s.play(.{label.which.to(chapter)}, .{ .seconds = f(12), .ease = anim.ease.linear }); + s.cursor = e + f(126); + return ti; +} + +pub fn f(frames: f32) f32 { + return frames / 60; +} + +/// Clock `v` from 0 to `frames`, linear, from the cursor; the cursor after it. +pub fn run(s: *anim.Frame, v: anim.Value, frames: f32) void { + s.play(.{v.to(0)}, .{ .seconds = 0 }); + s.play(.{v.to(frames)}, .{ .seconds = f(frames), .ease = anim.ease.linear }); +} + +/// The same, the cursor left where it was. +pub fn start(s: *anim.Frame, v: anim.Value, frames: f32) void { + const at = s.cursor; + run(s, v, frames); + s.cursor = at; +} + +/// `v` to `to` over `frames`, linear, the cursor left where it was. +pub fn to(s: *anim.Frame, v: anim.Value, value: f32, frames: f32) void { + const at = s.cursor; + s.play(.{v.to(value)}, .{ .seconds = f(frames), .ease = anim.ease.linear }); + s.cursor = at; +} + +/// A value at once, from the cursor. +pub fn set(s: *anim.Frame, v: anim.Value, value: f32) void { + s.play(.{v.to(value)}, .{ .seconds = 0 }); +} + +pub fn place(s: *anim.Frame, data: anytype) anim.Obj { + return s.custom(data, .{ .x = -640, .y = -360, .scale = canim.ui.scale }); +} + +/// The page over a part of a panel the beat has not reached: lifted (its fade out) as the beat says it. +pub const Cover = struct { + box: canim.Rect, + pub fn draw(c: *const Cover, fr: *sk.Frame, placed: anim.Placed) void { + (canim.ui.Ui{ .f = fr, .at = placed }).fill(c.box, canim.theme.color.page); + } +}; + +/// A value framed as read (6 f in with its object's fade). +pub const Read = struct { + box: canim.Rect, + pub fn draw(r: *const Read, fr: *sk.Frame, placed: anim.Placed) void { + (canim.ui.Ui{ .f = fr, .at = placed }).read(r.box, 1); + } +}; + +/// A part of a disassembly row framed as read on a beat (an echo): the row +/// of `addr` where the panel says it is this frame, from `x` (from the +/// panel's left: the address 40, the operands 264, `disasm.zig`'s columns) +/// `w` wide, `shows` of it. +pub const RowRead = struct { + addr: u64, + x: f32, + w: f32, + shows: anim.Value, + pub fn draw(r: *const RowRead, fr: *sk.Frame, placed: anim.Placed) void { + const shows = std.math.clamp(placed.value(r.shows), 0, 1); + if (shows <= 0) return; + const px = canim.findPlace(fr, .{ .row = r.addr }) orelse return; + const u = canim.fixed(fr, placed, 0); + // Canvas pixels to the design's units (the camera is home: the frame fitted into the canvas). + const w = @max(@floor(fr.in.window_width), 1); + const h = @max(@floor(fr.in.window_height), 1); + const k = @min(w / canim.theme.canvas.width, h / canim.theme.canvas.height); + const left = (px[0] - w / 2) / k + canim.theme.canvas.width / 2.0; + const top = (px[1] - h / 2) / k + canim.theme.canvas.height / 2.0; + u.read(.{ .x = left + r.x, .y = top, .w = r.w, .h = canim.theme.metric.context.row }, shows); + } +}; + +pub fn cover(s: *anim.Frame, box: canim.Rect) anim.Obj { + const o = place(s, s.new(Cover{ .box = box })); + s.play(.{o.fadeIn()}, .{ .seconds = 0 }); + return o; +} + +/// Every one of `objs` there at once, from the cursor (a panel and the page over what it has not said yet). +pub fn show(s: *anim.Frame, objs: []const ?anim.Obj) void { + const at = s.cursor; + for (objs) |o| if (o) |obj| { + s.cursor = at; + s.play(.{obj.fadeIn()}, .{ .seconds = 0 }); + }; + s.cursor = at; +} + +/// A panel's tag and rules under the page, for `frame up`: its tag, its left, right and bottom rules, and its strip. +pub fn chrome(s: *anim.Frame, b: canim.Rect, strip: bool) [5]?anim.Obj { + const w = canim.theme.stroke.rule; + const tag = canim.theme.metric.context.tag; + return .{ + cover(s, .{ .x = b.x, .y = b.y, .w = b.w, .h = tag }), + cover(s, .{ .x = b.x, .y = b.y + tag, .w = w, .h = b.h - tag }), + cover(s, .{ .x = b.x + b.w - w, .y = b.y + tag, .w = w, .h = b.h - tag }), + cover(s, .{ .x = b.x, .y = b.y + b.h - w, .w = b.w, .h = w }), + if (strip) cover(s, .{ .x = b.x + b.w - canim.theme.strip.cost, .y = b.y + tag, .w = canim.theme.strip.cost - w, .h = b.h - tag - w }) else null, + }; +} + +/// Lifts `covers` one after another, `apart` frames apart, `each` frames each, from the cursor; the cursor after the last. +pub fn lift(s: *anim.Frame, covers: []const ?anim.Obj, apart: f32, each: f32) void { + const at = s.cursor; + var end = at; + for (covers, 0..) |o, i| if (o) |obj| { + s.cursor = at + f(apart * @as(f32, @floatFromInt(i))); + s.play(.{obj.fadeOut()}, .{ .seconds = f(each), .ease = anim.ease.linear }); + end = s.cursor; + }; + s.cursor = end; +} + +/// The first moment from `from` at an instruction whose text has `text` in it. +pub 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.indexOf(u8, here.text, text) != null) return i; + return from; +} + +/// A clock counting the recording from its first stop at line 40 (`moment 6 of 193`), on `cursor`'s steps, in `ctx`'s frame. +pub fn clock(s: *anim.Frame, rec: *canim.Recording, cursor: canim.Cursor, ctx: canim.Context) anim.Obj { + var counts = cursor; + counts.first = rec.lineMoment(40, 0); + counts.last = rec.end(); + return canim.add(s, canim.Clock{ .cursor = counts, .map = ctx.map, .stage = ctx.stage }); +} diff --git a/anim/scenes/intro_code.zig b/anim/scenes/intro_code.zig index eb66554..7682842 100644 --- a/anim/scenes/intro_code.zig +++ b/anim/scenes/intro_code.zig @@ -1,44 +1,30 @@ -//! The introduction, chapter III: code and meaning (design/motion.md, "A -//! scene: the introduction", III1 to III5; mocks 32, 33, 36). On the +//! The introduction, chapter IV: code and meaning (design/motion.md, "A +//! scene: the introduction", IV1 to IV5; mocks 32, 33, 36), a function the +//! scene `intro` calls after III's seam. On the //! `intro` recording at the load in `reverse` (line 21, `node *next = //! cur->next;`, the instruction that reads `cur->next`): the code's bytes //! as a dump row, that instruction's four framed; `decode`d into its row //! of `aligned` (`interleaved`), its neighbours at a run, each line level //! with its run; then `align` to `columns`; then the working frame with the //! nodes drawn from the heap's bytes, each pane's minimap drawing itself -//! last; then the map (`surface`). It opens on chapter II's last picture, -//! its state column staying veiled until the decoded code spans it. The +//! last; then the map (`surface`). It opens on chapter III's last picture, +//! its state column staying veiled until the decoded code spans it, and +//! the one clock steps on to the load as the working frame assembles. The //! texts `above` the aligned panel, then below the working frame, the //! last landing before the map surfaces under it. const std = @import("std"); const anim = @import("anim"); const sk = @import("sketch"); const canim = @import("canim"); -const recordings = @import("recordings"); -const two = @import("intro_stack.zig"); - -pub const background = canim.background; -pub const scene = anim.Live(frame, struct {}); +const intro = @import("intro.zig"); +const stack = @import("intro_stack.zig"); const t = canim.theme.time; +const f = intro.f; +const run = intro.run; +const on = intro.on; -fn f(frames: f32) f32 { - return frames / 60; -} - -fn run(s: *anim.Frame, v: anim.Value, frames: f32) void { - s.play(.{v.to(0)}, .{ .seconds = 0 }); - s.play(.{v.to(frames)}, .{ .seconds = f(frames), .ease = anim.ease.linear }); -} - -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.indexOf(u8, here.text, text) != null) return i; - return from; -} - -/// The page over a part not drawn yet (a pane's minimap until III4). +/// The page over a part not drawn yet (a pane's minimap until IV4). const Page = struct { box: canim.Rect, pub fn draw(c: *const Page, fr: *sk.Frame, placed: anim.Placed) void { @@ -46,46 +32,11 @@ const Page = struct { } }; -/// Chapter II's last picture (scenes/intro_stack.zig, its layout and texts -/// as there): its registers and stack, a context of their own at II's last -/// moment, the window held as II holds it; main's rows, faint, and reverse's -/// first rows under them; II4's text dimmed and II5's. -fn lastOfTwo(s: *anim.Frame, rec: *canim.Recording) struct { state: [2]anim.Obj, code: [2]anim.Obj, texts: [2]anim.Obj } { - const enter = rec.call("reverse", 0).enter; - const last = enter + 3; - var at = canim.cursor(s, rec, enter); - at.journey(.moment, last); - at.levels = .{ .fire = .disasm, .source_rows = 14, .introduction = true }; - // As II walked it: its push, `mov` and `sub` the steps behind its last moment. - at.jumpWalked(s, enter, last); - var split = canim.layout.split.none; - split.backtrace.h = 0; - const ctx = canim.context(s, at, .{ .split = split }); - const g = two.layout(ctx.stage, rec, enter); - two.hold(s, ctx.stage, enter); - const stack = canim.add(s, canim.Stack{ .cursor = ctx.cursor, .stage = ctx.stage }); - // (Placed at the origin: it draws at its own box.) - const caller = s.custom(s.new(canim.descent.Caller{ .rec = rec, .at = enter, .call = rec.register(enter - 1, "rip"), .box = g.caller, .in = s.value(999), .faint = s.value(1) }), .{ .x = -640, .y = -360, .scale = canim.ui.scale }); - const left = canim.theme.canvas.margin_x; - const said = [2]canim.Aside{ - .{ .text = two.texts[two.texts.len - 2], .x = left, .level = g.span_y, .dim = s.value(1) }, - .{ .text = two.texts[two.texts.len - 1], .x = left, .level = g.registers_y, .dim = s.value(0) }, - }; - var texts: [2]anim.Obj = undefined; - for (said, &texts) |a, *o| o.* = s.custom(s.new(a), .{ .x = -640, .y = -360, .scale = canim.ui.scale }); - for ([_]anim.Obj{ ctx.registers, stack, caller, ctx.disasm, texts[0], texts[1] }) |o| s.play(.{o.fadeIn()}, .{ .seconds = 0 }); - return .{ .state = .{ ctx.registers, stack }, .code = .{ caller, ctx.disasm }, .texts = texts }; -} - /// The variables whose tags the nodes carry, as the list scene's. const tracked = [_][]const u8{ "prev", "cur", "next", "head" }; -fn frame(s: *anim.Frame) void { - const rec = canim.open(recordings.intro); - // list.c's types as the pass would tell them: the recording is of the - // plain build, which tells none (its locals are the debug info's). - rec.declare("head", "*`struct node`"); - rec.declare("`struct node`", "struct(16){value@0:i64;next@8:*`struct node`;}"); +/// From the seam's opening (the cursor), on chapter III's last picture. +pub fn chapter(s: *anim.Frame, rec: *canim.Recording, three: stack.Three, title: intro.Title) void { const reverse = rec.call("reverse", 0); // The load: `cur->next` read, line 21's second instruction. const moment = on(rec, rec.lineMoment(21, reverse.enter), "[rax + 8]"); @@ -100,9 +51,8 @@ fn frame(s: *anim.Frame) void { for (code[0..insn.len], 0..) |b, k| hex.print(s.arena, "{s}{x:0>2}", .{ if (k > 0) " " else "", b }) catch {}; const text = std.mem.replaceOwned(u8, s.arena, insn.text, "qword ptr ", "") catch insn.text; - // Chapter II's last picture, which this chapter opens on (II's own - // context at II's last moment, laid out as II has it, under this one's). - const opening = lastOfTwo(s, rec); + const opening = three; + const begun = s.cursor; var at = canim.cursor(s, rec, moment); at.journey(.moment, moment + 1); @@ -110,6 +60,8 @@ fn frame(s: *anim.Frame) void { const ctx = canim.context(s, at, .{ .split = canim.layout.split.subject }); const list = canim.nodes(s, .{ .cursor = at, .stage = ctx.stage, .root = "head", .track = &tracked, .named = true }); ctx.map.add(s, canim.Nodes{ .cursor = at, .stage = ctx.map.stage, .root = "head", .track = &tracked, .named = true }); + // The one clock (II's and III's cursor), over this context's map: it takes the old one's place at once, the same picture. + const clock = intro.clock(s, rec, opening.at, ctx); // The relations, and rax's link to the node as III3 names it. const joins, const rax_link = ctx.tiesWith(s, "rax", 1.0); @@ -122,19 +74,18 @@ fn frame(s: *anim.Frame) void { const al = s.new(canim.Aligned.init(s, rec, moment)); const panel = s.custom(al, .{ .x = -640, .y = -360, .scale = canim.ui.scale }); + s.cursor = begun; s.play(.{panel.fadeIn()}, .{ .seconds = 0 }); // Texts above the panel that spans both columns: twice a beside's line (two lines in the band of 120). var asides: canim.Asides = .{ .wrap = 2 * 40 }; const left = canim.theme.canvas.margin_x; const above = canim.theme.canvas.stage.y + 40; - // From II's last picture: its texts and code give way (12 f, 18 f); its - // state column stays, veiled at 50%, until the decoded code takes both columns. - s.wait(t.beat); - s.play(.{ opening.texts[0].fadeOut(), opening.texts[1].fadeOut() }, .{ .seconds = t.caption_out, .ease = canim.ease.exit }); - s.cursor -= t.caption_out; - s.play(.{ opening.code[0].fadeOut(), opening.code[1].fadeOut(), opening.state[0].move(.{ .opacity = 0.5 }), opening.state[1].move(.{ .opacity = 0.5 }) }, .{ .seconds = f(18), .ease = anim.ease.linear }); - s.wait(t.beat); + // The opening, from III's last picture (its texts gone at the seam): its code gives + // way (18 f); its state column stays, veiled at 50%, until the decoded code takes both + // columns; the clock and its label stay, under the stage. + s.play(.{ opening.code[0].fadeOut(), opening.code[1].fadeOut(), opening.code[2].fadeOut(), opening.state[0].move(.{ .opacity = 0.5 }), opening.state[1].move(.{ .opacity = 0.5 }) }, .{ .seconds = f(18), .ease = anim.ease.linear }); + title.out(s); // III1: the code's bytes, one instruction's framed. asides.say(s, std.fmt.allocPrint(s.arena, "Code is bytes too: `{s}` is one instruction.", .{hex.items}) catch "", left, above); @@ -171,7 +122,14 @@ fn frame(s: *anim.Frame) void { s.play(.{ strips[0].fadeIn(), strips[1].fadeIn(), strips[2].fadeIn(), strips[3].fadeIn() }, .{ .seconds = 0 }); s.play(.{ ctx.source.fadeIn(), ctx.disasm.fadeIn(), panel.fadeOut() }, .{ .seconds = f(12), .ease = anim.ease.linear }); var says: canim.Narrator = .{}; - canim.establish(s, .{ ctx.clock, ctx.registers, ctx.stack, joins }); + // The one clock goes on, forward, to IV's moment: the chapters before's cursor taken + // there (its panels gone), the count changing and its gold fading in as a step's (12 f). + const later: canim.Plan = .{ .advance = 0, .travel = 0, .total = t.quick }; + const counted = s.cursor; + s.play(.{ opening.clock.fadeOut(), clock.fadeIn() }, .{ .seconds = 0 }); + opening.at.step(s, moment, later, later.total); + s.cursor = counted; + canim.establish(s, .{ ctx.registers, ctx.stack, joins }); // III3: the node it reads, as bytes and drawn: the band comes in, its // elements rising from their bytes. No camera: at x1.5 the drawing's // nodes and its bytes do not both fit the frame, and the band is whole at x1. diff --git a/anim/scenes/intro_memory.zig b/anim/scenes/intro_memory.zig index 2dfda5e..7b25098 100644 --- a/anim/scenes/intro_memory.zig +++ b/anim/scenes/intro_memory.zig @@ -1,5 +1,6 @@ //! The introduction, chapter I: memory (design/motion.md, "A scene: the -//! introduction", I1 to I10; mocks 29, 30, 34, 37). The frame built from +//! introduction", I1 to I10; mocks 29, 30, 34, 37), a function the scene +//! `intro` calls after its title (`chapter`). The frame built from //! its bytes up, on the `intro` recording (the list program from main's //! call of `reverse`) at reverse's first instruction, its `push rbp` (the //! push chapter II walks; rsp holds the way back to main), each part in @@ -13,33 +14,27 @@ 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 {}); +const intro = @import("intro.zig"); const t = canim.theme.time; +const f = intro.f; +const run = intro.run; +const start = intro.start; -fn f(frames: f32) f32 { - return frames / 60; -} +/// The chapter's last picture, which chapter II opens on: the address +/// space, the 128 bytes and their place's tie (each an object of its +/// own), the last text, and `e`, the frame it has been read by. +pub const One = struct { + space: *canim.Segments, + dump: *canim.Words, + objs: [3]anim.Obj, + caption: anim.Obj, + e: f32, +}; -/// Clock `v` from 0 to `frames`, linear, from the cursor; the cursor after it. -fn run(s: *anim.Frame, v: anim.Value, frames: f32) void { - s.play(.{v.to(0)}, .{ .seconds = 0 }); - s.play(.{v.to(frames)}, .{ .seconds = f(frames), .ease = anim.ease.linear }); -} - -/// The same, the cursor left where it was. -fn start(s: *anim.Frame, v: anim.Value, frames: f32) void { - const at = s.cursor; - run(s, v, frames); - s.cursor = at; -} - -fn frame(s: *anim.Frame) void { - const rec = canim.open(recordings.intro); - // reverse's first instruction (its call's first moment): its `push rbp`, which chapter II walks. +/// From the cursor, where its first text arrives. +pub fn chapter(s: *anim.Frame, rec: *canim.Recording) One { + // reverse's first instruction (its call's first moment): its `push rbp`, which chapter III walks. const moment = rec.call("reverse", 0).enter; const ui = canim.ui; const at = canim.regroup.at; @@ -62,7 +57,7 @@ fn frame(s: *anim.Frame) void { } space.n_echoes = order.len; - const objs = .{ s.custom(space, .{ .x = -640, .y = -360, .scale = ui.scale }), s.custom(dump, .{ .x = -640, .y = -360, .scale = ui.scale }), s.custom(place, .{ .x = -640, .y = -360, .scale = ui.scale }) }; + const objs = [3]anim.Obj{ s.custom(space, .{ .x = -640, .y = -360, .scale = ui.scale }), s.custom(dump, .{ .x = -640, .y = -360, .scale = ui.scale }), s.custom(place, .{ .x = -640, .y = -360, .scale = ui.scale }) }; inline for (objs) |o| s.play(.{o.fadeIn()}, .{ .seconds = 0 }); // The camera at x2 on the dump from the first frame (I1 to I3), with the @@ -78,7 +73,6 @@ fn frame(s: *anim.Frame) void { // I1: the bytes, a row at a time (18 f apart), a text's lead (60 f) after it lands, not // the first's 120: little "here" over an empty stage, and they come while it is read. - s.wait(1.0); const said_at = s.cursor; says.line(s, "A running program is bytes in memory:\nhere are 128 of them."); const lead_end = s.cursor; @@ -182,8 +176,8 @@ fn frame(s: *anim.Frame) void { says.line(s, "Follow an address and you reach another word: a chain.\n`→` points to a word, `←` holds a value."); run(s, dump.left, 24); run(s, dump.chains, 36 * 2 + 30); - s.wait(t.beat); - // The chapter's last picture. - says.close(s); + // The chapter's last picture, held until its text is read: then the seam. + s.wait(@max(says.read_by - s.cursor, 0)); cam.apply(s); + return .{ .space = space, .dump = dump, .objs = objs, .caption = says.current.?, .e = s.cursor }; } 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 }; +} diff --git a/anim/scenes/intro_stack.zig b/anim/scenes/intro_stack.zig index 378d624..3fb0213 100644 --- a/anim/scenes/intro_stack.zig +++ b/anim/scenes/intro_stack.zig @@ -1,121 +1,64 @@ -//! The introduction, chapter II: the stack (design/motion.md, "A scene: the -//! introduction", II1 to II4, here six beats; mock 31). It opens on chapter -//! I's last picture, at the same moment of the `intro` recording (reverse's -//! first instruction, its `push rbp`): the address space and the dump's link -//! fade, the words glide into the stack panel's rows where it stands in the -//! working frame (sixteen of them and four `free` over rsp, the window held -//! there so that nothing in the panel moves while the frame is made) and -//! become it; the convention said there (lower addresses drawn higher), the -//! offsets coming down the rows. rsp's and rbp's rows arrive over the stack, -//! rsp's pin landing on the top word. The call first: the way back main -//! left framed, main's three rows round its call arriving in the program -//! column, the word aimed at the row it returns to (`aim`, drawn head first, -//! standing at 60% through the push). Then reverse's first rows under -//! main's (the disassembly) and `push rbp` walked: the pc's mark on its -//! row, the touch to the word, rbp's value carried to it and struck, rsp's -//! pin climbing. `mov rbp, rsp` and `sub rsp` walked: the frame; its roles -//! (the way back named) and spans, a `column` each, the panels' tags last -//! (`frame up`). Then the registers built over it a row at a time, their -//! tag last. The text stands beside on the left, in the program column, -//! over the code. +//! The introduction, chapter III: the stack (design/motion.md, "A scene: +//! the introduction", III1 to III5; mock 31), a function the scene `intro` +//! calls after II's seam. It goes on from chapter II's last picture, on +//! II's context (its registers, folded to the scene's one set; reverse's +//! rows at the program column's foot, no panel round them; the clock): the +//! 128 bytes, back at the rows II gave them, become the stack panel where +//! they stand (sixteen words and four `free` over rsp, the window held +//! there so that nothing in the panel moves while the frame is made); the +//! convention said there (lower addresses drawn higher), the offsets coming +//! down the rows; rsp's pin landing on the top word and its link to it. The +//! call first: the way back main left framed, main's three rows round its +//! call arriving in the program column, the word aimed at the row it +//! returns to (`aim`, drawn head first, standing at 60% through the push). +//! Then `push rbp` walked: the pc's mark on its row, the touch to the word, +//! rbp's value carried to it and struck, rsp's pin climbing. `mov rbp, rsp` +//! and `sub rsp` walked: the frame; its roles (the way back named) and +//! spans, a `column` each, the panels' tags last (`frame up`). The text +//! stands beside on the left, in the program column, over the code. //! -//! What a beat has not reached yet is under the page (`Cover`, and the +//! What a beat has not reached yet is under the page (`intro.Cover`, and the //! stack's own `reveal`), lifted as the beat says it: the context's panels //! draw every column at once. const std = @import("std"); const anim = @import("anim"); -const sk = @import("sketch"); const canim = @import("canim"); -const recordings = @import("recordings"); - -pub const background = canim.background; -pub const scene = anim.Live(frame, struct {}); +const intro = @import("intro.zig"); +const registers = @import("intro_registers.zig"); const t = canim.theme.time; const row = canim.theme.metric.context.row; -const tag = canim.theme.metric.context.tag; -const pad = canim.theme.metric.context.pad; - -fn f(frames: f32) f32 { - return frames / 60; -} - -fn place(s: *anim.Frame, data: anytype) anim.Obj { - return s.custom(data, .{ .x = -640, .y = -360, .scale = canim.ui.scale }); -} +const f = intro.f; +const run = intro.run; +const place = intro.place; +const cover = intro.cover; +const lift = intro.lift; -/// The page over a part of a panel the beat has not reached: lifted (its fade out) as the beat says it. -const Cover = struct { - box: canim.Rect, - pub fn draw(c: *const Cover, fr: *sk.Frame, placed: anim.Placed) void { - (canim.ui.Ui{ .f = fr, .at = placed }).fill(c.box, canim.theme.color.page); - } -}; +/// The chapter's last picture, which chapter IV opens on. +pub const Three = struct { + /// The state column (the registers, the stack) and the code (main's rows, reverse's, the ties). + state: [2]anim.Obj, + code: [3]anim.Obj, + clock: anim.Obj, + /// The cursor the clock counts on (II's and III's). + at: canim.Cursor, + asides: canim.Asides, + e: f32, -/// A value framed as read (6 f in with its object's fade). -const Read = struct { - box: canim.Rect, - pub fn draw(r: *const Read, fr: *sk.Frame, placed: anim.Placed) void { - (canim.ui.Ui{ .f = fr, .at = placed }).read(r.box, 1); + pub fn texts(three: *const Three, s: *anim.Frame) []const anim.Obj { + return registers.standing(s, &three.asides); } }; -fn cover(s: *anim.Frame, box: canim.Rect) anim.Obj { - const o = place(s, s.new(Cover{ .box = box })); - s.play(.{o.fadeIn()}, .{ .seconds = 0 }); - return o; -} - -/// A panel's tag and rules under the page, for `frame up`. -fn chrome(s: *anim.Frame, b: canim.Rect, strip: bool) [5]?anim.Obj { - const w = canim.theme.stroke.rule; - return .{ - cover(s, .{ .x = b.x, .y = b.y, .w = b.w, .h = tag }), - cover(s, .{ .x = b.x, .y = b.y + tag, .w = w, .h = b.h - tag }), - cover(s, .{ .x = b.x + b.w - w, .y = b.y + tag, .w = w, .h = b.h - tag }), - cover(s, .{ .x = b.x, .y = b.y + b.h - w, .w = b.w, .h = w }), - if (strip) cover(s, .{ .x = b.x + b.w - canim.theme.strip.cost, .y = b.y + tag, .w = canim.theme.strip.cost - w, .h = b.h - tag - w }) else null, - }; -} - -/// Lifts `covers` one after another, `apart` frames apart, `each` frames each, from the cursor; the cursor after the last. -fn lift(s: *anim.Frame, covers: []const ?anim.Obj, apart: f32, each: f32) void { - const at = s.cursor; - var end = at; - for (covers, 0..) |o, i| if (o) |obj| { - s.cursor = at + f(apart * @as(f32, @floatFromInt(i))); - s.play(.{obj.fadeOut()}, .{ .seconds = f(each), .ease = anim.ease.linear }); - end = s.cursor; - }; - s.cursor = end; -} - -/// A value at once, from the cursor. -fn set(s: *anim.Frame, v: anim.Value, to: f32) void { - s.play(.{v.to(to)}, .{ .seconds = 0 }); -} - -/// Clock `v` from 0 to `frames`, linear, from the cursor; the cursor after it. -fn run(s: *anim.Frame, v: anim.Value, frames: f32) void { - s.play(.{v.to(0)}, .{ .seconds = 0 }); - s.play(.{v.to(frames)}, .{ .seconds = f(frames), .ease = anim.ease.linear }); -} - -fn frame(s: *anim.Frame) void { - const rec = canim.open(recordings.intro); - const reverse = rec.call("reverse", 0); +/// From the seam's opening (the cursor), on chapter II's context. +pub fn chapter(s: *anim.Frame, rec: *canim.Recording, two: registers.Two, title: intro.Title) Three { + const ctx = two.ctx; + var at = two.at; // Chapter I's moment: reverse's first instruction, `push rbp`; then `mov rbp, rsp` and `sub rsp, 0x18`. - const moment = reverse.enter; + const moment = rec.call("reverse", 0).enter; const framed = moment + 3; - var at = canim.cursor(s, rec, moment); - at.journey(.moment, framed); - 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 }); const g = layout(ctx.stage, rec, moment); const sb = g.stack; - const rb = ctx.stage.first.registers; const rsp = g.rsp; const first = g.first; const top = g.top; @@ -123,78 +66,57 @@ fn frame(s: *anim.Frame) void { // The window held where it is, four `free` words over rsp: the push and `sub rsp` fill them. hold(s, ctx.stage, moment); - // The panels and the page over what they have not said yet, first: chapter I's - // picture, the words gliding into the stack among them, draws over them. // The stack, its offsets, roles and spans under the page until their beats. // (Rows 4 f apart: the offsets come down while the convention is read.) const reveal: canim.Stack.Reveal = .{ .offsets = s.value(-1), .roles = s.value(-1), .spans = s.value(-1), .apart = 4 }; const stack = canim.add(s, canim.Stack{ .cursor = ctx.cursor, .stage = ctx.stage, .reveal = reveal }); - // The registers, under the page: rbp's and rsp's rows (the scene's two, the first two), the rest, the chrome. - s.play(.{ctx.registers.fadeIn()}, .{ .seconds = 0 }); - var regs_rows: [16]?anim.Obj = @splat(null); - for (0..@min(canim.layout.rowsIn(rb.h), 16)) |k| - // (From the third row on 2 higher: the rule over the folded rows goes with them.) - regs_rows[k] = cover(s, .{ .x = rb.x + 2, .y = rb.y + tag + pad + row * @as(f32, @floatFromInt(k)) - @as(f32, if (k >= 2) 2 else 0), .w = rb.w - 4, .h = row + @as(f32, if (k >= 2) 2 else 0) }); - const regs_chrome = chrome(s, rb, false); // The pins' lane: rsp's row's lifted with rsp, the rest (rbp's pin) with the push. var lane: [32]?anim.Obj = @splat(null); const rsp_row: usize = held_free; for (0..@min(slots, 32)) |k| lane[k] = cover(s, .{ .x = sb.x + 2, .y = top + row * @as(f32, @floatFromInt(k)), .w = canim.theme.metric.slot.lane_end - 2, .h = row }); - const stack_chrome = chrome(s, sb, true); - // Reverse's first rows, the disassembly under main's: its rows with the push, its tag and strip last. - const disasm_chrome = chrome(s, ctx.stage.first.disasm, true); + const stack_chrome = intro.chrome(s, sb, true); - // Chapter I's last picture: the address space, the words with their chains, the link standing. - const space = s.new(canim.Segments.init(s, rec, moment)); - const dump = s.new(canim.Words.init(s, rec, moment)); + // The 128 bytes become the stack's rows where they stand (II8 put them there). + const dump = two.dump; dump.panel = .{ .x = sb.x, .top = top, .first = first }; - const at_ = canim.regroup.at; - const tie = s.new(canim.segments.Place{ .segments = space, .addr = rsp, .x = at_.bracket, .y0 = at_.top + 2, .y1 = at_.top + 16 * 24 - 2, .clock = s.value(60), .quiet = s.value(24) }); - for ([_]anim.Value{ space.form, dump.placed }) |v| set(s, v, 1); - set(s, space.whole, 999); - for (space.rides) |v| set(s, v, 999); - for ([_]anim.Value{ dump.in, dump.ink, dump.chains }) |v| set(s, v, 999); - set(s, dump.regroup, canim.regroup.regroup_frames); - set(s, dump.left, 24); - const objs = .{ place(s, space), place(s, dump), place(s, tie) }; - inline for (objs) |o| s.play(.{o.fadeIn()}, .{ .seconds = 0 }); + // (Over the page that covers the stack's lane: the addresses travel across it.) + const dump_obj = place(s, dump); // main's rows, in the program column over reverse's; the aim joins them to the word. const back_y = rowY(top, first, rsp); const main_rows = s.new(canim.descent.Caller{ .rec = rec, .at = moment, .call = rec.register(moment - 1, "rip"), .box = g.caller, .in = s.value(-1), .faint = s.value(0) }); - s.play(.{place(s, main_rows).fadeIn()}, .{ .seconds = 0 }); + const caller = place(s, main_rows); const main_word: canim.Rect = .{ .x = sb.x + canim.theme.metric.slot.address + 12 * 12 + canim.theme.metric.context.arrow_w, .y = back_y, .w = @as(f32, @floatFromInt(canim.ui.digits(rec.register(moment - 1, "rip") + 5))) * 12, .h = row }; - const word_frame = place(s, s.new(Read{ .box = main_word })); - // The relations, and rsp's link to its word as II2 names it. + const word_frame = place(s, s.new(intro.Read{ .box = main_word })); + // The relations, and rsp's link to its word as III2 names it. const joins, const rsp_link = ctx.tiesWith(s, "rsp", 1.0); - s.play(.{joins.fadeIn()}, .{ .seconds = 0 }); + const opening = s.cursor; + s.play(.{ caller.fadeIn(), joins.fadeIn(), two.dump_obj.fadeOut(), dump_obj.fadeIn() }, .{ .seconds = 0 }); + s.cursor = opening; var asides: canim.Asides = .{}; const left = canim.theme.canvas.margin_x; - // II1: the address space and the link fade (18 f); the words glide into - // the stack's rows (36 f) and become the panel (12 f). Where it first - // stands, its convention said, unlike the bar's: the offsets come down - // its rows (a column, 4 f apart), growing as the addresses do. - s.wait(t.beat); - s.play(.{ objs[0].fadeOut(), objs[2].fadeOut() }, .{ .seconds = f(18), .ease = anim.ease.linear }); + // The opening (126 to 174): the bytes fade, the addresses and the words glide into the + // stack's rows (36 f) and become the panel (12 f). Where it first stands, its convention + // said, unlike the bar's: the offsets come down its rows (a column, 4 f apart). s.play(.{dump.become.to(1)}, .{ .seconds = f(36), .ease = anim.ease.linear }); - s.play(.{ stack.fadeIn(), objs[1].fadeOut() }, .{ .seconds = f(12), .ease = anim.ease.linear }); + s.play(.{ stack.fadeIn(), dump_obj.fadeOut() }, .{ .seconds = f(12), .ease = anim.ease.linear }); + title.out(s); asides.say(s, texts[0], left, rowY(top, first, first) + row / 2); const column = reveal.apart * @as(f32, @floatFromInt(slots)) + 12; run(s, reveal.offsets, column); s.wait(t.beat); - // II2: rsp's and rbp's rows arrive over the stack (12 f), rsp's pin lands on the top word (12 f), - // then rsp's link from its row down to the word, held, drawn back. + // III2: rsp's pin lands on the top word (12 f), then rsp's link from its row down to the + // word, held, drawn back. Its row was built in II: nothing arrives. asides.say(s, texts[1], left, back_y + row / 2); - lift(s, &.{ regs_rows[0], regs_rows[1] }, 0, 12); lift(s, &.{lane[rsp_row]}, 0, 12); rsp_link.play(s); s.wait(rsp_link.total()); s.wait(f(18)); s.wait(t.beat); - // II3: the call, first: the way back main left, framed; main's rows; the aim drawn to its row. + // III3: the call, first: the way back main left, framed; main's rows; the aim drawn to its row. asides.say(s, texts[2], left, back_y + row / 2); s.play(.{word_frame.fadeIn()}, .{ .seconds = f(6), .ease = anim.ease.linear }); s.wait(f(12)); @@ -204,12 +126,11 @@ fn frame(s: *anim.Frame) void { s.wait(f(24 + 30)); s.wait(t.beat); - // II4: the push: reverse's first rows under main's, rbp's pin; `push rbp` walked - // (its row fires, the touch to the word, rbp's value carried there and struck, rsp's pin climbing). + // III4: the push: rbp's pin; `push rbp` walked (its row fires, the touch to the word, + // rbp's value carried there and struck, rsp's pin climbing). Reverse's rows are on screen since II. asides.say(s, texts[3], left, rowY(top, first, rsp - 8) + row / 2); at.aim(s, .standing); s.play(.{ word_frame.fadeOut(), main_rows.faint.to(1) }, .{ .seconds = f(18), .ease = anim.ease.linear }); - s.play(.{ctx.disasm.fadeIn()}, .{ .seconds = f(12), .ease = anim.ease.linear }); var lanes: [32]?anim.Obj = lane; lanes[rsp_row] = null; lift(s, &lanes, 0, 12); @@ -219,7 +140,7 @@ fn frame(s: *anim.Frame) void { at.levels.carry = .off; s.wait(t.beat); - // II5: the frame made (`mov rbp, rsp`, `sub rsp`); its roles, spans, and the tags last. + // III5: the frame made (`mov rbp, rsp`, `sub rsp`); its roles, spans, and the tags last. asides.say(s, texts[4], left, g.span_y); at.aim(s, .off); at.walk(s, .moment, moment + 2); @@ -229,48 +150,40 @@ fn frame(s: *anim.Frame) void { s.wait(t.beat); // `frame up`: the rules (12 f), then the tags and strips (12 f). const at_rules = s.cursor; - lift(s, disasm_chrome[1..4], 0, 12); + lift(s, two.disasm_chrome[1..4], 0, 12); s.cursor = at_rules; lift(s, stack_chrome[1..4], 0, 12); const at_tags = s.cursor; - lift(s, &.{ disasm_chrome[0], disasm_chrome[4] }, 0, 12); + lift(s, &.{ two.disasm_chrome[0], two.disasm_chrome[4] }, 0, 12); s.cursor = at_tags; lift(s, &.{ stack_chrome[0], stack_chrome[4] }, 0, 12); - s.wait(t.beat); - - // II6: the registers built over the stack, a row at a time, their tag last. - asides.say(s, texts[5], left, g.registers_y); - lift(s, regs_rows[2..], 12, 12); - lift(s, regs_chrome[1..4], 0, 12); - lift(s, &.{regs_chrome[0]}, 0, 12); - // The chapter's last picture. + // The chapter's last picture, held until its last text is read: then the seam. s.wait(@max(asides.read_by - s.cursor, 0)); - s.wait(t.before_cut); + return .{ .state = .{ two.registers, stack }, .code = .{ caller, two.disasm, joins }, .clock = two.clock, .at = at, .asides = asides, .e = s.cursor }; } -/// The chapter's texts, in order (chapter III opens on the last two). +/// The chapter's texts, in order. pub const texts = [_][]const u8{ "Here lower addresses are drawn higher: down a word is up a row.", "`rsp` holds the address of the top of the stack.", "A call pushes the address to come back to: here, `main+50`.", "A push moves `rsp` down a word and stores there: `push rbp` keeps the caller's `rbp`.", "`rbp` marks the frame's base. A function's words are its frame: the saved rbp, its locals, the way back.", - "The registers are the other place values live: seventeen of them.", }; /// Free words over rsp in the held window. -pub const held_free = 4; +const held_free = 4; -/// The stack's window held from the first frame (no scroll to it), `held_free` words over rsp at `moment`. -pub fn hold(s: *anim.Frame, stage: *canim.Stage, moment: u64) void { +/// The stack's window held from here (no scroll to it), `held_free` words over rsp at `moment`. +fn hold(s: *anim.Frame, stage: *canim.Stage, moment: u64) void { s.play(.{ stage.hold.to(@floatFromInt(moment)), stage.hold_free.to(held_free), stage.hold_in.to(1) }, .{ .seconds = 0 }); } -/// Where the chapter's parts stand (chapter III opens on its last picture, -/// laid out the same): the stack under the registers, its window from -/// `first` (four free words over rsp), its rows from `top`; main's rows -/// in the program column level with the lower stack, reverse's under them. -pub fn layout(stage: *canim.Stage, rec: *canim.Recording, moment: u64) struct { stack: canim.Rect, rsp: u64, first: u64, top: f32, caller: canim.Rect, span_y: f32, registers_y: f32 } { +/// Where the chapter's parts stand: the stack under the registers' eleven +/// rows (356 to 868), its window from `first` (four free words over rsp), +/// its rows from `top`; main's rows in the program column (604 to 700) over +/// reverse's six, where chapter II put them (712 to 888). +fn layout(stage: *canim.Stage, rec: *canim.Recording, moment: u64) struct { stack: canim.Rect, rsp: u64, first: u64, top: f32, caller: canim.Rect, span_y: f32 } { const rb = stage.first.registers; // Sixteen slots and the headroom under the registers' box (the words // become them where they stand), not the column's rest. @@ -279,12 +192,11 @@ pub fn layout(stage: *canim.Stage, rec: *canim.Recording, moment: u64) struct { const sb = stage.first.stack; const rsp = rec.register(moment, "rsp"); const first = rsp - 8 * held_free; - const top = sb.y + tag + pad; - const caller: canim.Rect = .{ .x = canim.theme.layout.program.x, .y = rowY(top, first, rsp) + row / 2 + 152, .w = canim.theme.layout.program.w, .h = 4 * row }; - // Seven rows: reverse's from its first, which none of the chapter's steps scrolls away. - stage.first.disasm = .{ .x = caller.x, .y = caller.y + caller.h + canim.theme.canvas.row_gap, .w = caller.w, .h = canim.layout.panelH(7) }; + const top = sb.y + canim.theme.metric.context.tag + canim.theme.metric.context.pad; + const code = stage.first.disasm; + const caller: canim.Rect = .{ .x = code.x, .y = code.y - canim.theme.canvas.row_gap - 4 * row, .w = code.w, .h = 4 * row }; const rsp_framed = rec.register(moment + 3, "rsp"); - return .{ .stack = sb, .rsp = rsp, .first = first, .top = top, .caller = caller, .span_y = (rowY(top, first, rsp_framed) + rowY(top, first, rsp + 8)) / 2, .registers_y = rb.y + tag + pad + row * 2.5 }; + return .{ .stack = sb, .rsp = rsp, .first = first, .top = top, .caller = caller, .span_y = (rowY(top, first, rsp_framed) + rowY(top, first, rsp + 8)) / 2 }; } fn rowY(t0: f32, from: u64, addr: u64) f32 { diff --git a/anim/src/Recording.zig b/anim/src/Recording.zig index bcc8903..c6a305f 100644 --- a/anim/src/Recording.zig +++ b/anim/src/Recording.zig @@ -58,7 +58,11 @@ pub const Mark = struct { moment: u64, text: []const u8 }; /// An allocation ever made: its place in this list is its identity, the /// same in every view. -pub const Born = struct { ptr: u64, size: u64, moment: u64, event: u64 }; +/// An allocation: the agent's (`event` its event), or, in a recording with +/// none and glibc's heap at each stop (`--heap`), a chunk in use there, its +/// body (`ptr` 16 into the chunk, `size` the chunk's less its 16), from the +/// first stop that has it to the first that does not (`gone`). +pub const Born = struct { ptr: u64, size: u64, moment: u64, event: u64, gone: u64 = std.math.maxInt(u64) }; /// A run of bytes a moment changed, or read. pub const Span = struct { addr: u64, len: u64 }; @@ -125,6 +129,8 @@ calls: []Call = &.{}, syscalls: []Syscall = &.{}, marks: []Mark = &.{}, allocations: []Born = &.{}, +/// Whether `allocations` were read off the heap (`allocationsFromHeap`). +heap_read: bool = false, /// The registers of `tid` after each moment (the last known, before any). registers: []zt.Regs = &.{}, write_spans: Spans = .{}, @@ -607,6 +613,55 @@ fn index(r: *Recording) !void { r.globals = globals.items; } +/// A scene that draws the program's allocations from glibc's heap +/// (`--heap`) where no agent told them (the introduction's list nodes): +/// `allocations` read off the heap, once. Not by default: a scene of the +/// heap's own (`heap`) times its steps by what it draws, not by these. +pub fn allocationsFromHeap(r: *Recording) void { + if (r.allocations.len > 0 or r.heap_read) return; + r.heap_read = true; + r.allocations = heapBorn(r, r.arena.allocator()) catch &.{}; +} + +/// The program's allocations read off glibc's heap at each stop (`--heap`), +/// where no agent told them: each chunk in use but the tcache's own, from +/// the first stop that has it; `gone` at the first that does not. In the +/// order they were first seen, by address within one stop. +fn heapBorn(r: *const Recording, arena: std.mem.Allocator) ![]Born { + var out: std.ArrayList(Born) = .empty; + var scratch: std.heap.ArenaAllocator = .init(gpa); + defer scratch.deinit(); + var i: u64 = 0; + while (i <= r.end()) : (i += 1) { + _ = scratch.reset(.retain_capacity); + const h = (zt.heap.glibc(scratch.allocator(), r.moment(i), r.tid) catch null) orelse continue; + const own: u64 = if (h.tcache) |tc| tc.addr else 0; + for (h.chunks) |c| { + if (c.free or c.in != .none or c.addr + 16 == own or c.size() < 32) continue; + const ptr = c.addr + 16; + const known = for (out.items) |b| { + if (b.ptr == ptr and b.gone > i) break true; + } else false; + if (!known) try out.append(arena, .{ .ptr = ptr, .size = c.size() - 16, .moment = i, .event = std.math.maxInt(u64) }); + } + // What was in use and is not now has gone. + for (out.items) |*b| if (b.gone > i and b.moment < i) { + const still = for (h.chunks) |c| { + if (c.addr + 16 == b.ptr and !c.free and c.in == .none) break true; + } else false; + if (!still) b.gone = i; + }; + } + return out.items; +} + +/// The allocation live at `m` that holds `addr`: the agent's (`Moment.allocation`) or one read off the heap. +pub fn allocated(r: *const Recording, m: Moment, addr: u64) bool { + if ((m.allocation(addr) catch null) != null) return true; + for (r.allocations) |b| if (b.event == std.math.maxInt(u64) and addr >= b.ptr and addr - b.ptr < @max(b.size, 1) and b.moment <= m.index and m.index < b.gone) return true; + return false; +} + /// A string id for `text`, for names the recording did not define itself. fn intern(r: *Recording, text: []const u8) !u64 { const id = std.hash.Wyhash.hash(0, text) | 1 << 63; diff --git a/anim/src/aside.zig b/anim/src/aside.zig index c2c0ef8..66c8ce7 100644 --- a/anim/src/aside.zig +++ b/anim/src/aside.zig @@ -29,11 +29,13 @@ pub const Aside = struct { level: f32, /// 0 newest, 1 the account (no paper, `dim`). dim: anim.Value, + /// Units it has glided down from `level` to make room for a newer one. + drop: ?anim.Value = null, /// Characters a line, at most. wrap: usize = chars, pub fn draw(a: *const Aside, f: *sk.Frame, placed: anim.Placed) void { - const u = (ui.Ui{ .f = f, .at = placed }).moved(0, (1 - placed.pose.opacity) * theme.time.caption_rise); + const u = (ui.Ui{ .f = f, .at = placed }).moved(0, (1 - placed.pose.opacity) * theme.time.caption_rise + if (a.drop) |d| placed.value(d) else 0); const wrapped = wrap(u, a.text, a.wrap); const top = a.level - first; const h = first * 2 + @as(f32, @floatFromInt(wrapped.len - 1)) * line_pitch; @@ -50,39 +52,101 @@ pub const Aside = struct { /// until the last has been read, arrives (18 f, `enter`), and is followed /// by its lead (60 f); the one before it dims (18 f), or leaves (12 f, /// `exit`, then the caption's gap) where the new one would stand on it. +/// With a `floor`, one in the way glides down under it instead (24 f, +/// `glide`), the others under that with it, as far as the floor (past it, +/// it leaves), and three stand at most (the column's way). /// `leave`: all go together. pub const Asides = struct { shown: [8]?anim.Obj = @splat(null), dims: [8]anim.Value = undefined, + drops: [8]anim.Value = undefined, spans: [8][2]f32 = undefined, + /// Each text's first top, before it glided. + tops: [8]f32 = undefined, n: usize = 0, read_by: f32 = 0, /// Characters a line, at most, of the texts it says. wrap: usize = chars, + /// Where texts in the way glide down to, at most (null: they leave). + floor: ?f32 = null, pub fn say(a: *Asides, s: *anim.Frame, text: []const u8, x: f32, level: f32) void { s.wait(@max(a.read_by - s.cursor, 0)); const dim = s.value(0); - const made = s.new(Aside{ .text = text, .x = x, .level = level, .dim = dim, .wrap = a.wrap }); + const drop = s.value(0); + const made = s.new(Aside{ .text = text, .x = x, .level = level, .dim = dim, .wrap = a.wrap, .drop = drop }); const obj = s.custom(made, .{ .x = -640, .y = -360, .scale = ui.scale }); const span = [2]f32{ level - first, level + first + @as(f32, @floatFromInt(lines(text, a.wrap) - 1)) * line_pitch }; const at = s.cursor; var in_the_way = false; - for (a.shown[0..a.n], a.dims[0..a.n], a.spans[0..a.n]) |*o, d, other| { + var glided = false; + // With a floor: the two newest stay, top down, each in the way gliding under what is over it. + var keep: [8]bool = @splat(false); + if (a.floor) |floor| { + var kept: usize = 0; + var k = a.n; + while (k > 0) { + k -= 1; + if (a.shown[k] == null or kept == 2) continue; + keep[k] = true; + kept += 1; + } + var bottom = span[1] + 12; + while (true) { + // The highest kept one not yet placed. + var next: ?usize = null; + for (0..a.n) |j| if (keep[j] and a.shown[j] != null and (next == null or a.spans[j][0] < a.spans[next.?][0])) { + next = j; + }; + const j = next orelse break; + keep[j] = false; + const sp = a.spans[j]; + s.cursor = at; + s.play(.{a.dims[j].to(1)}, .{ .seconds = 18.0 / 60.0, .ease = easeGlide }); + s.cursor = at; + if (sp[1] + 12 <= span[0]) continue; + const shift = @max(bottom - sp[0], 0); + if (sp[1] + shift > floor) { + s.play(.{a.shown[j].?.fadeOut()}, .{ .seconds = time.caption_out, .ease = easeExit }); + a.shown[j] = null; + in_the_way = true; + continue; + } + if (shift > 0) { + s.play(.{a.drops[j].to(sp[0] + shift - a.tops[j])}, .{ .seconds = 24.0 / 60.0, .ease = easeGlide }); + a.spans[j] = .{ sp[0] + shift, sp[1] + shift }; + glided = true; + } + bottom = a.spans[j][1] + 12; + } + } + for (a.shown[0..a.n], a.dims[0..a.n], a.spans[0..a.n], 0..) |*o, d, other, j| { s.cursor = at; if (o.* == null) continue; + if (a.floor != null) { + // Past the two newest: it leaves. + var newer: usize = 0; + for (a.shown[j + 1 .. a.n]) |later| newer += @intFromBool(later != null); + if (newer >= 2) { + s.play(.{o.*.?.fadeOut()}, .{ .seconds = time.caption_out, .ease = easeExit }); + o.* = null; + } + continue; + } if (other[0] < span[1] + 12 and span[0] < other[1] + 12) { s.play(.{o.*.?.fadeOut()}, .{ .seconds = time.caption_out, .ease = easeExit }); o.* = null; in_the_way = true; } else s.play(.{d.to(1)}, .{ .seconds = 18.0 / 60.0, .ease = easeGlide }); } - // One it would stand on is gone first, then a gap: never two texts over each other. - s.cursor = if (in_the_way) at + time.caption_out + time.caption_gap else at; + // One it would stand on is gone first, then a gap, or has glided from under it: never two texts over each other. + s.cursor = at + @max(@as(f32, if (in_the_way) time.caption_out + time.caption_gap else 0), @as(f32, if (glided) 24.0 / 60.0 else 0)); s.play(.{obj.fadeIn()}, .{ .seconds = time.caption_in, .ease = easeEnter }); a.shown[a.n] = obj; a.dims[a.n] = dim; + a.drops[a.n] = drop; a.spans[a.n] = span; + a.tops[a.n] = span[0]; a.n += 1; a.read_by = s.cursor + time.caption(@intCast(std.unicode.utf8CountCodepoints(text) catch text.len)); s.wait(time.caption_lead); diff --git a/anim/src/context.zig b/anim/src/context.zig index 874a22a..577071d 100644 --- a/anim/src/context.zig +++ b/anim/src/context.zig @@ -103,16 +103,75 @@ pub const Registers = struct { folds: bool = true, /// Its tag's title (a `pair`'s names its run). title: []const u8 = "registers", + /// The quiet rows folded on a beat the scene plays (`fold`, 0 to 1: + /// every register a row, then folded; the introduction's II8); null: + /// folded, or as a dive has it. + fold: ?anim.Value = null, + /// One register opened into its bytes and its parts (`reg` `parts`, `unpack`, `pack`). + parts: ?*const Parts = null, + /// Registers framed as read on a beat the scene plays (rip's value too). + framed: []const Framed = &.{}, + + pub const Framed = struct { name: []const u8, shows: anim.Value }; + + /// `parts` (design/README.md, `reg`): register `name`'s value as its + /// eight bytes from 72 on a pitch of 30, high first, the zeros in front + /// at `pad`, and under it a row for each name its low bytes go by, + /// widest first, a bracket under the bytes it is. Clocks in frames: + /// `unpack` (the rows under it make room 0 to 18, the bytes spread 18 + /// to 30, the parts' rows 30 to 54, 6 f apart); `pack` (the parts' rows + /// fade 0 to 12, then the bytes close into the value and the rows close + /// up, 12 to 36); `echo`, 0 to 1: the part `echoed` and its bytes framed as read. + pub const Parts = struct { + name: []const u8, + unpack: anim.Value, + pack: anim.Value, + echo: anim.Value, + echoed: usize = 0, + + /// The rows it takes under its register (0 to 3). + fn room(p: *const Parts, placed: anim.Placed) f32 { + const un = placed.value(p.unpack); + if (un < 0) return 0; + const pk = placed.value(p.pack); + return 3 * theme.ease(.glide, std.math.clamp(un / 18, 0, 1)) * (1 - theme.ease(.glide, std.math.clamp((pk - 12) / 24, 0, 1))); + } + + /// How far its bytes have spread out of the value (0 closed, 1 open). + fn spread(p: *const Parts, placed: anim.Placed) f32 { + const un = placed.value(p.unpack); + if (un < 18) return 0; + const pk = placed.value(p.pack); + return theme.ease(.glide, std.math.clamp((un - 18) / 12, 0, 1)) * (1 - theme.ease(.glide, std.math.clamp((pk - 12) / 24, 0, 1))); + } + + /// How much part row `j`'s shows. + fn shows(p: *const Parts, placed: anim.Placed, j: usize) f32 { + const un = placed.value(p.unpack); + return std.math.clamp((un - 30 - 6 * @as(f32, @floatFromInt(j))) / 12, 0, 1) * (1 - std.math.clamp(placed.value(p.pack) / 12, 0, 1)); + } + + /// Its names, widest first (4, 2 and 1 bytes): `eax ax al`, `edi di dil`, `r8d r8w r8b`. + fn names(u: ui.Ui, name: []const u8) [3][]const u8 { + if (name.len >= 2 and std.ascii.isDigit(name[1])) return .{ u.print("{s}d", .{name}), u.print("{s}w", .{name}), u.print("{s}b", .{name}) }; + const bare = name[1..]; + if (bare.len == 2 and bare[1] == 'x') return .{ u.print("e{s}", .{bare}), bare, u.print("{c}l", .{bare[0]}) }; + return .{ u.print("e{s}", .{bare}), bare, u.print("{s}l", .{bare}) }; + } + }; const Shown = struct { regs: zt.Regs, moment: Recording.Moment }; pub fn draw(r: *const Registers, f: *sk.Frame, placed: anim.Placed) void { const box = r.stage.box(placed, .registers); const u = at(f, placed, box); - // In a dive the panel comes whole out of the map and folds as it lands (`Zoom.fold`). - const fold = if (ui.mapping) 1 else foldOf(box); + // In a dive the panel comes whole out of the map and folds as it lands (`Zoom.fold`); on a beat, as the scene plays it. + const fold = if (r.fold) |v| theme.ease(.glide, std.math.clamp(placed.value(v), 0, 1)) else if (ui.mapping) 1 else foldOf(box); var shape = box; shape.h = std.math.lerp(theme.layout.panelH(@floatFromInt(theme.metric.all_registers.len)), box.h, fold); + // A register opened into its parts: the rows under it make room. + const room = if (r.parts) |p| p.room(placed) * m.row else 0; + shape.h += room; const now = r.cursor.now(placed); const rec = r.cursor.rec; const is: Shown = .{ .regs = (now.moment().regs(rec.tid) catch null) orelse zt.Regs{}, .moment = now.moment() }; @@ -128,23 +187,30 @@ pub const Registers = struct { const full = fullRows(r.moves); const top = body.y + m.pad; // The quiet ones under a rule across, in pwndbg's order; rip the last row. - if (full < 16 and r.folds) u.faded(fold).fill(.{ .x = theme.stroke.rule, .y = top + @as(f32, @floatFromInt(full)) * m.row - 1, .w = shape.w - 2 * theme.stroke.rule, .h = theme.stroke.rule }, theme.color.rule); + // (On a beat the rule draws once they have folded, 12 f.) + const rule_shows = if (r.fold != null) std.math.clamp((placed.value(r.fold.?) - 1) * 3, 0, 1) else fold; + if (full < 16 and r.folds) u.faded(rule_shows).fill(.{ .x = theme.stroke.rule, .y = top + @as(f32, @floatFromInt(full)) * m.row - 1 + room, .w = shape.w - 2 * theme.stroke.rule, .h = theme.stroke.rule }, theme.color.rule); var rows_before: usize = 0; var quiet_before: usize = 0; + // The rows under an opened register are `room` lower. + var below: f32 = 0; for (theme.metric.all_registers[0..16], 0..) |name, i| { const unfolded = top + @as(f32, @floatFromInt(i)) * m.row; if (r.moves >> @intCast(i) & 1 != 0) { - r.row(u, now, is, was, name, std.math.lerp(unfolded, top + @as(f32, @floatFromInt(rows_before)) * m.row, fold), shape.w); + r.row(u, placed, now, is, was, name, std.math.lerp(unfolded, top + @as(f32, @floatFromInt(rows_before)) * m.row, fold) + below, shape.w); rows_before += 1; + if (r.parts) |p| if (std.mem.eql(u8, p.name, name)) { + below = room; + }; continue; } if (!r.folds) continue; - const y = std.math.lerp(unfolded, top + @as(f32, @floatFromInt(full + quiet_before / q.quiet_per_row)) * m.row, fold); + const y = std.math.lerp(unfolded, top + @as(f32, @floatFromInt(full + quiet_before / q.quiet_per_row)) * m.row, fold) + below; const x = std.math.lerp(theme.metric.context.side, q.quiet_from + @as(f32, @floatFromInt(quiet_before % q.quiet_per_row)) * q.quiet_pitch, fold); quiet_before += 1; r.quietRow(u, now, is, was, name, x, y, shape.w, fold); } - r.rip(u, now, std.math.lerp(top + 16 * m.row, top + @as(f32, @floatFromInt(if (r.folds) registerRows(r.moves) - 1 else full)) * m.row, fold), shape.w, is, was); + r.rip(u, placed, now, std.math.lerp(top + 16 * m.row, top + @as(f32, @floatFromInt(if (r.folds) registerRows(r.moves) - 1 else full)) * m.row, fold) + below, shape.w, is, was); veiled(u, shape, now.veil); } @@ -157,7 +223,15 @@ pub const Registers = struct { const read_shows = if (r.carrier(now, name, was.regs.named(name) orelse value)) |c| c.shows else 0; if (fold < 1) { const dx = x - theme.metric.context.side; - _ = rows.reg(u.faded(1 - fold).moved(dx, 0), y, w - dx, name, is.moment, value, .{ .hops = 1 - std.math.clamp(fold / 0.4, 0, 1) }); + const v = u.faded(1 - fold).moved(dx, 0); + const hops = 1 - std.math.clamp(fold / 0.4, 0, 1); + // Its chain reads memory as the panels show it: what a step wrote under it, from memory's strike (6 f), never in a frame. + const k = if (now.resting()) 1 else std.math.clamp(now.since(.memory, 0) / time.strike.in, 0, 1); + if (k < 1 and cursors.chainMoved(was.moment, is.moment, value)) { + v.text(.mono, theme.size.mono.context, m.side, rows.baseline(y), name, t.dim); + _ = rows.chain(v.faded(1 - k), m.chain_x, y, was.moment, value, w - dx - m.side, .{ .hops = hops }); + _ = rows.chain(v.faded(k), m.chain_x, y, is.moment, value, w - dx - m.side, .{ .hops = hops }); + } else _ = rows.reg(v, y, w - dx, name, is.moment, value, .{ .hops = hops }); } const hops = rows.quiet(u.faded(fold), x, y, name, is.moment, value, read_shows); anchor(u, i, hops, y, value, w); @@ -185,8 +259,12 @@ pub const Registers = struct { /// rip: where execution is, a current mark like the source's and the /// disassembly's; it moves with them, at the advance. - fn rip(r: *const Registers, u: ui.Ui, now: cursors.Now, y: f32, w: f32, is: Shown, was: Shown) void { + fn rip(r: *const Registers, u: ui.Ui, placed: anim.Placed, now: cursors.Now, y: f32, w: f32, is: Shown, was: Shown) void { const rec = r.cursor.rec; + defer for (r.framed) |fr| if (std.mem.eql(u8, fr.name, "rip")) { + const pc = rec.register(now.marks[1], "rip"); + u.read(.{ .x = theme.metric.context.chain_x, .y = y, .w = @as(f32, @floatFromInt(ui.digits(pc))) * ui.advance(theme.size.mono.context), .h = m.row }, std.math.clamp(placed.value(fr.shows), 0, 1)); + }; // The flags' corners are secondary: 6 f after the registers strike, // not with them; in a continue's wave, in its place after r15. const delay = if (now.plan.wave) ties.strikeDelay(now, index("eflags").?) else cursors.write_apart; @@ -206,9 +284,26 @@ pub const Registers = struct { rows.rip(u, y, w, rec.moment(now.marks[1]), rec.register(now.marks[1], "rip"), is.regs.eflags, changed, held, 0, reads, now.reading(.cpu, 0), .{ .moment = rec.moment(now.marks[0]), .pc = rec.register(now.marks[0], "rip"), .eflags = was.regs.eflags, .going = now.advancing(), .flip = if (now.resting()) 1 else flip }); } - fn row(r: *const Registers, u: ui.Ui, now: cursors.Now, line_is: Shown, line_was: Shown, name: []const u8, y: f32, w: f32) void { + fn row(r: *const Registers, u_row: ui.Ui, placed: anim.Placed, now: cursors.Now, line_is: Shown, line_was: Shown, name: []const u8, y: f32, w: f32) void { const rec = r.cursor.rec; const i = index(name) orelse return; + // Opened into its parts: its value as bytes, its chain gone (the name stays). + const opened = if (r.parts) |p| (if (std.mem.eql(u8, p.name, name)) p else null) else null; + const spread = if (opened) |p| p.spread(placed) else 0; + if (spread > 0) r.partsRow(u_row, placed, now, opened.?, line_is, line_was, name, i, y, spread); + // The value as it was written crossfades with its own pairs where they stand (the spread's + // first tenth), before the pairs move off and the zeros in front come. + const u = u_row.faded(std.math.clamp(1 - 10 * spread, 0, 1)); + // (Its name drawn whole over the fading row's: never dimmer for the crossfade.) + if (spread > 0) u_row.text(.mono, theme.size.mono.context, m.side, rows.baseline(y), name, t.dim); + defer for (r.framed) |fr| if (std.mem.eql(u8, fr.name, name)) { + // Round the value shown: the one before the step's until its strike lands. + const struck = now.registerAge(i) != 0 or now.since(.cpu, ties.strikeDelay(now, i)) >= time.strike.in / 2.0; + const side = if (struck) line_is else line_was; + const value = side.regs.named(name) orelse 0; + const shown = ui.Value.of(value, rows.regionOf(side.moment, value) != .none); + u.read(.{ .x = m.chain_x, .y = y, .w = shown.width(), .h = m.row }, std.math.clamp(placed.value(fr.shows), 0, 1)); + }; // Every register is the program's, at its line stops, as every // other panel is: what crossed into the kernel is the crossing's // to show, and a register is framed as carrying it only where it @@ -278,6 +373,68 @@ pub const Registers = struct { anchor(u, i, hops, y, if (landed or ran < 1) value_now else value_was, w); } + /// A register opened into its parts (`Parts`): its eight bytes, high + /// first, the zeros in front at `pad`, spreading out of the value as it + /// was written (`spread`); the bytes a write changed armed and struck as + /// a dump's; under it its parts' rows, each a bracket under its bytes. + fn partsRow(r: *const Registers, u: ui.Ui, placed: anim.Placed, now: cursors.Now, p: *const Parts, is: Shown, was: Shown, name: []const u8, i: usize, y: f32, spread: f32) void { + const size = theme.size.mono.context; + const adv = ui.advance(size); + const pitch: f32 = 30; + const value_now = is.regs.named(name) orelse return; + const value_was = was.regs.named(name) orelse value_now; + const age = now.registerAge(i); + const delay = if (age == 0) ties.strikeDelay(now, i) else 0; + const heat = if (r.quiet) ui.Heat.none else now.register(i, delay); + const landed = now.resting() or now.since(.cpu, delay) >= time.strike.in / 2.0; + const value = if (landed) value_now else value_was; + // Closed: the pairs side by side, ranged so that the last ends where the value's hex digits end. + const shown = ui.Value.of(value, rows.regionOf(is.moment, value) != .none); + const closed_end = m.chain_x + u.width(.mono, size, shown.prefix) + @as(f32, @floatFromInt(shown.digits().len)) * adv; + var lead: usize = 0; + while (lead < 7 and (value >> @intCast(8 * (7 - lead))) & 0xff == 0) lead += 1; + for (0..8) |k| { + const b: u8 = @truncate(value >> @intCast(8 * (7 - k))); + const before: u8 = @truncate(value_was >> @intCast(8 * (7 - k))); + const after: u8 = @truncate(value_now >> @intCast(8 * (7 - k))); + const open_x = m.chain_x + pitch * @as(f32, @floatFromInt(k)); + // (The zeros in front close onto the value's first digit, fading: never over the name.) + const closed_x = @max(closed_end - 2 * adv * @as(f32, @floatFromInt(8 - k)), if (k < lead) m.chain_x else m.chain_x - 2 * adv); + const x = std.math.lerp(closed_x, open_x, spread); + const cell: Rect = .{ .x = x, .y = y, .w = 2 * adv, .h = m.row }; + const struck = if (before != after) u.faded(spread).written(cell, heat) else null; + const pad = k < lead and struck == null; + // The value's own pairs at once; the zeros in front over the last 40% (never piled up), at `pad`. + const v = u.faded(if (k < lead) std.math.clamp((spread - 0.6) / 0.4, 0, 1) * @as(f32, if (pad) 0.55 else 1) else std.math.clamp(10 * spread, 0, 1)); + const text = u.print("{x:0>2}", .{b}); + if (struck) |in| v.text(in.face, size, x, rows.baseline(y), text, in.ink) else v.text(.mono, size, x, rows.baseline(y), text, if (pad) t.faint else t.primary); + } + // Its parts' rows, widest first: a bracket under the bytes each is, its name before it. + const parts = Parts.names(u, name); + const counts = [3]usize{ 4, 2, 1 }; + const echo = std.math.clamp(placed.value(p.echo), 0, 1); + for (parts, counts, 0..) |part, n, j| { + const shows_ = p.shows(placed, j); + const ry = y + m.row * @as(f32, @floatFromInt(j + 1)); + const x0 = m.chain_x + pitch * @as(f32, @floatFromInt(8 - n)) - 3; + const x1 = m.chain_x + pitch * 7 + 2 * adv + 3; + const by = ry + 10; + if (shows_ > 0) { + const v = u.faded(shows_); + v.fill(.{ .x = x0, .y = by, .w = x1 - x0, .h = 2 }, t.dim); + v.fill(.{ .x = x0, .y = by - 11, .w = 2, .h = 13 }, t.dim); + v.fill(.{ .x = x1 - 2, .y = by - 11, .w = 2, .h = 13 }, t.dim); + const nx = x0 - 10 - v.width(.mono, size, part); + v.text(.mono, size, nx, rows.baseline(ry), part, t.dim); + // The part an instruction names, and its bytes in the register's row, framed as read together (an echo). + if (j == p.echoed and echo > 0) { + u.read(.{ .x = nx, .y = ry, .w = v.width(.mono, size, part), .h = m.row }, echo * shows_); + u.read(.{ .x = x0 + 3, .y = y, .w = x1 - x0 - 6, .h = m.row }, echo * shows_); + } + } + } + } + /// The `fd` class's note after a register's value: faint, what it is open on. fn fdNote(u: ui.Ui, hops: rows.Hops, y: f32, on: []const u8) void { if (hops.n > 0 and on.len > 0) u.text(.mono, theme.size.mono.context, hops.end + 8, rows.baseline(y), on, t.faint); diff --git a/anim/src/cursor.zig b/anim/src/cursor.zig index c145823..f574941 100644 --- a/anim/src/cursor.zig +++ b/anim/src/cursor.zig @@ -129,12 +129,17 @@ pub const Plan = struct { pins: [2]f32 = .{ -1, -1 }, follow: f32 = -1, project: f32 = -1, + /// A call stepped over (design/motion.md, "A call stepped over"): its + /// result first, rax armed and struck as a walked register in the CPU's + /// slot, the call's row taking its C form with it; the others it changed + /// in a wave from here (seconds from the step's first frame); -1: none. + result: f32 = -1, /// How many values a plan is on the timeline (`pack`). - const values = 18; + const values = 19; fn pack(p: Plan) [values]f32 { - return .{ @floatFromInt(@intFromEnum(p.gait)), p.at[0], p.at[1], p.at[2], p.advance, p.travel, p.total, @floatFromInt(@intFromBool(p.wave)), @floatFromInt(@intFromBool(p.fires)), p.cooling, p.touch, p.read, p.carry, @floatFromInt(@intFromBool(p.carry_value)), p.pins[0], p.pins[1], p.follow, p.project }; + return .{ @floatFromInt(@intFromEnum(p.gait)), p.at[0], p.at[1], p.at[2], p.advance, p.travel, p.total, @floatFromInt(@intFromBool(p.wave)), @floatFromInt(@intFromBool(p.fires)), p.cooling, p.touch, p.read, p.carry, @floatFromInt(@intFromBool(p.carry_value)), p.pins[0], p.pins[1], p.follow, p.project, p.result }; } fn unpack(v: [values]f32) Plan { @@ -154,6 +159,7 @@ pub const Plan = struct { .pins = .{ v[14], v[15] }, .follow = v[16], .project = v[17], + .result = v[18], }; } @@ -178,7 +184,11 @@ pub const quiet: u32 = blk: { break :blk mask; }; -/// rsp's and rbp's places in `Regs.names`. +/// rax's, rsp's and rbp's places in `Regs.names`. +pub const rax_index: u5 = blk: { + for (zt.Regs.names, 0..) |name, i| if (std.mem.eql(u8, name, "rax")) break :blk i; + unreachable; +}; pub const sp_index: u5 = blk: { for (zt.Regs.names, 0..) |name, i| if (std.mem.eql(u8, name, "rsp")) break :blk i; unreachable; @@ -523,6 +533,28 @@ pub const Cursor = struct { c.step(s, to, plan, plan.total); } + /// A call stepped over (design/motion.md, "A call stepped over"), from + /// the call's row to the row after it: fire; the arguments framed as read + /// (18 to 24, `Registers`, `Disasm`); still while it runs; rax armed and + /// struck at 48, the row's C form and result with it; the others it + /// changed in a wave from 66, 2 f apart; a hold of 36 f; the advance; a rest. + pub fn over(c: Cursor, s: *anim.Frame, to: u64) void { + const f = 1.0 / 60.0; + const from = c.moment(s); + var plan = c.timetable(from, to, true); + const changed = c.rec.registersChanged(from, to) & ~quiet; + const others: f32 = @floatFromInt(@popCount(changed & ~(@as(u32, 1) << rax_index))); + plan.at[0] = 48 * f; + plan.result = 66 * f; + const last = if (others > 0) plan.result + (others - 1) * time.continue_wave else plan.at[0]; + // What it left in memory is not this beat's: its slot with the wave's end. + plan.at[1] = last; + plan.at[2] = last; + plan.advance = last + time.read_value; + plan.total = plan.advance + plan.travel + time.rest; + c.step(s, to, plan, plan.total); + } + fn timetable(c: Cursor, from: u64, to: u64, wave: bool) Plan { if (c.levels.annotation == .tied and !wave) return c.tiedTable(from, to); const rec = c.rec; @@ -1280,7 +1312,7 @@ pub const Now = struct { /// The mark of a register: the CPU's level. In a continue's wave, no arm and no pulse. pub fn register(n: Now, reg: usize, delay: f32) ui.Heat { var h = n.heat(n.registerAge(reg), n.registerAgeFrom(reg, 1), n.since(.cpu, delay)); - if (n.plan.wave) { + if (n.plan.wave and !(n.plan.result >= 0 and reg == rax_index)) { h.arm = 0; h.out = 0; } diff --git a/anim/src/disasm.zig b/anim/src/disasm.zig index f61c721..67b0572 100644 --- a/anim/src/disasm.zig +++ b/anim/src/disasm.zig @@ -85,6 +85,8 @@ pub const Disasm = struct { /// A `pair`'s stopped run, 0 to 1: the call at the pc never returned. Its /// row reads so, the plaque goes, the tag says `stopped`. stopped: ?anim.Value = null, + /// 0 to 1: how much the pc's mark shows (the introduction's code arrives before its mark, II4). + mark_in: ?anim.Value = null, pub fn draw(d: *const Disasm, f: *sk.Frame, placed: anim.Placed) void { const box = d.stage.box(placed, .disasm); @@ -154,6 +156,7 @@ pub const Disasm = struct { mark_y = top + (j - scroll) * m.row; } if (to.rows.len == 0) mark_shows = 0; + if (d.mark_in) |v| mark_shows *= std.math.clamp(placed.value(v), 0, 1); // Which moment the current mark stands for, and the three steps before it. const base: usize = if (going >= 0.5) 0 else 1; @@ -411,16 +414,41 @@ pub const Disasm = struct { .call => { // Through memory or a register: where it went, and where that was read. if (target(row) == null) return a.went(b.to, touches[0], moment); - // Once it has run: the call in C's form and its result. + // Once it has run: the call in C's form and its result (struck with rax while the step that stepped over it plays). if (state == .ran) if (returned(rec, row, moment, now.stops[base])) |back| { + if (now.plan.result >= 0 and state.ran.at == now.stops[1]) return a.returning(row, b.to, moment, rec.register(back, "rax"), now.register(cursors.rax_index, 0)); return a.said(a.cForm(row, b.to, moment, rec.register(back, "rax"), a.room - a.x), t.primary); }; + // A call stepped over (`Plan.result`, design/motion.md "A call stepped over"): its + // callee and its arguments hanging under it, framed as read from 18 f; then, as rax + // strikes, its C form and its result, struck with it, the hanging rows going (6 f). + if (now.plan.result >= 0 and state == .current and !now.resting()) if (returned(rec, row, moment, now.stops[0])) |back| { + const k = std.math.clamp((now.time - now.plan.at[0]) / (6.0 / 60.0), 0, 1); + var note: Note = .{}; + if (k < 1) { + const before: Say = .{ .u = u.faded(1 - k), .rec = rec, .y = y, .x = x, .room = room }; + note = before.callee(b.to, moment); + note.hangs = before.arguments(row, b.to, moment); + const framed = std.math.clamp((now.time - 18.0 / 60.0) / (6.0 / 60.0), 0, 1) * (1 - k); + for (carriers[0..note.hangs], 1..) |reg, j| { + const v = rec.register(moment, reg); + const shown = ui.Value.of(v, rows.regionOf(rec.moment(moment), v) != .none); + u.read(.{ .x = x + 4 * adv, .y = y + @as(f32, @floatFromInt(j)) * m.row, .w = shown.width(), .h = m.row }, framed); + } + } + if (k > 0) { + const struck: Say = .{ .u = u.faded(k), .rec = rec, .y = y, .x = x, .room = room }; + note = struck.returning(row, b.to, moment, rec.register(back, "rax"), now.register(cursors.rax_index, 0)); + } + return note; + }; // `tied`: a call to the program's own function in C's form (a PLT stub's callee by name, // its arguments under it), then its move of rsp, struck with rsp: `fib(4) · rsp -8`. if (now.annotation == .tied and state == .current) { const stub = pltName(u, rec, target(row).?).len > 0; var note = if (stub) a.callee(b.to, moment) else a.said(a.cForm(row, b.to, moment, null, a.room - a.x - 10 * adv), t.primary); - note.end = a.move(note.end + adv, -8, a.rspHeat(now, base), null, true); + // (The introduction walks no call: the one it shows is stepped over, rsp as it was after it.) + if (!now.introduction) note.end = a.move(note.end + adv, -8, a.rspHeat(now, base), null, true); if (stub) note.hangs = a.arguments(row, b.to, moment); return note; } @@ -548,8 +576,13 @@ pub const Disasm = struct { const at = value_at orelse return .{}; const value = rec.register(at, reg); new.u.text(.mono, size, x, base_y, reg, t.dim); - // `tied`: its first value (the registers' row has its chain, struck in the same frame). - return .{ .drawn = true, .end = rows.chain(new.u, x + @as(f32, @floatFromInt(reg.len + 1)) * adv, y, rec.moment(at), value, room, .{ .most = if (now.annotation == .tied) 1 else 6 }).end }; + // `tied`: its first value (the registers' row has its chain, struck in the same frame); + // in the introduction struck with its register (a part's bytes are struck so: `reg` `parts`). + var marks: rows.Marks = .{ .most = if (now.annotation == .tied) 1 else 6 }; + if (now.introduction and state == .current) if (context.index(reg)) |ri| { + marks.first = now.register(ri, ties.strikeDelay(now, ri)); + }; + return .{ .drawn = true, .end = rows.chain(new.u, x + @as(f32, @floatFromInt(reg.len + 1)) * adv, y, rec.moment(at), value, room, marks).end }; } }; @@ -738,6 +771,14 @@ const Say = struct { return .{ .drawn = true, .end = rows.chain(u, x, a.y, shown, v, a.room, .{ .first = if (marks.changed == 1) marks.changed_heat else .none }).end }; } + /// A call that has run, in C's form with its result struck as `heat` says (rax's: an echo). + fn returning(a: Say, row: Insn, to: u64, moment: u64, value: u64, heat: ui.Heat) Disasm.Note { + const back = resultText(a.u, a.rec, moment, value); + var end = a.word(a.x, a.cForm(row, to, moment, null, a.room - a.x - @as(f32, @floatFromInt(back.len + 3)) * adv), t.primary); + end = a.word(end, " = ", t.primary); + return .{ .drawn = true, .end = a.struck(end, back, heat) }; + } + /// A direct call's callee, bright. fn callee(a: Say, to: u64, moment: u64) Disasm.Note { return .{ .drawn = true, .end = a.word(a.x, a.functionName(to, moment), t.bright) }; @@ -791,7 +832,7 @@ const Say = struct { } if (shown < count) out = u.print("{s}{s}\u{2026}", .{ out, if (shown > 0) ", " else "" }); out = u.print("{s})", .{out}); - if (result) |r| out = u.print("{s} = {d}", .{ out, @as(i64, @bitCast(r)) }); + if (result) |r| out = u.print("{s} = {s}", .{ out, resultText(u, a.rec, moment, r) }); if (shown == 0 or @as(f32, @floatFromInt(std.unicode.utf8CountCodepoints(out) catch out.len)) * adv <= width) return out; } } @@ -994,6 +1035,12 @@ fn returned(rec: *const Recording, row: Insn, moment: u64, until: u64) ?u64 { return null; } +/// A call's result as a caller reads it: an address in hex, as the chains write it; else signed, in decimal. +fn resultText(u: ui.Ui, rec: *const Recording, moment: u64, r: u64) []const u8 { + if (rows.regionOf(rec.moment(moment), r) != .none) return u.print("{x}", .{r}); + return u.print("{d}", .{@as(i64, @bitCast(r))}); +} + /// The slot a `jmp` or `call` through `[rip + X]` reads. fn ripSlot(row: Insn) ?u64 { const ops = row.operands(); diff --git a/anim/src/hexdump.zig b/anim/src/hexdump.zig index d1c363c..3ef1ac9 100644 --- a/anim/src/hexdump.zig +++ b/anim/src/hexdump.zig @@ -30,7 +30,7 @@ pub const Kind = enum { number, pointer, loose, unread }; /// a field of a struct the program's pointers reach (by its type), other /// allocated bytes, `loose` (the allocator's own between allocations), or /// never observed. -pub fn kindOf(things: []const objects.Object, moment: Recording.Moment, addr: u64) struct { Kind, ?Recording.types.Type } { +pub fn kindOf(rec: *const Recording, things: []const objects.Object, moment: Recording.Moment, addr: u64) struct { Kind, ?Recording.types.Type } { for (things) |o| { if (!o.holds(addr)) continue; for (o.type.record.fields) |field| if (o.addr + field.offset == addr) return .{ if (field.type == .pointer) .pointer else .number, field.type }; @@ -40,7 +40,7 @@ pub fn kindOf(things: []const objects.Object, moment: Recording.Moment, addr: u6 var known: [8]bool = undefined; moment.read(addr, &bytes, &known) catch return .{ .unread, null }; if (std.mem.indexOfScalar(bool, &known, true) == null) return .{ .unread, null }; - return .{ if ((moment.allocation(addr) catch null) != null) .number else .loose, null }; + return .{ if (rec.allocated(moment, addr)) .number else .loose, null }; } /// The rows of a region (`lo .. hi`, sixteen-aligned) a dump of `count` @@ -207,7 +207,7 @@ pub fn drawArcs(u: ui.Ui, now: cursors.Now, x: f32, y: f32, first: u64, count: u if (of.array) |arr| if (here < arr.addr and arr.addr < here + run.len) { run.len = @intCast(arr.addr - here); }; - const word, kind = kindOf(of.things, moment, here); + const word, kind = kindOf(now.rec, of.things, moment, here); run.kind = switch (word) { .number => .number, .pointer => .pointer, @@ -240,7 +240,7 @@ pub fn drawArcs(u: ui.Ui, now: cursors.Now, x: f32, y: f32, first: u64, count: u const end = readingIn(v, ry, shift, moment, &values, &known, readings[0..n], room); // The size word of the chunk after: malloc's, a note after the reading. const last = runs[n - 1]; - if (last.kind == .loose and last.first == 8 and last.len == 8 and std.mem.indexOfScalar(bool, known[8..], false) == null and chunkAfter(moment, addr + 8)) { + if (last.kind == .loose and last.first == 8 and last.len == 8 and std.mem.indexOfScalar(bool, known[8..], false) == null and chunkAfter(now.rec, moment, addr + 8)) { const size = std.mem.readInt(u64, values[8..16], .little) & ~@as(u64, 7); v.text(.sans, theme.size.sans.micro, end, rows.baseline(ry) - 1, v.print("malloc's: a chunk of {d}", .{size}), t.faint); } @@ -419,9 +419,9 @@ fn aim(arcs: *rows.Arcs, now: cursors.Now, field: u64, target: u64, from: f32, s /// Whether an allocation the recording has begins just after the word at /// `word` (the chunk's size word, glibc's and musl's alike): only there are /// bytes between allocations the allocator's own, to be read as its. -fn chunkAfter(moment: Recording.Moment, word: u64) bool { - const a = (moment.allocation(word + 8) catch return false) orelse return false; - return a.ptr == word + 8; +fn chunkAfter(rec: *const Recording, moment: Recording.Moment, word: u64) bool { + if ((moment.allocation(word + 8) catch null)) |a| return a.ptr == word + 8; + return rec.allocated(moment, word + 8) and !rec.allocated(moment, word); } /// What a field of a region reads as: a number (little-endian, or `big`), diff --git a/anim/src/map.zig b/anim/src/map.zig index eaec991..2a2077a 100644 --- a/anim/src/map.zig +++ b/anim/src/map.zig @@ -1133,6 +1133,19 @@ fn spanOf2(maybe: ?Window, col: *const Column) ?[2]f32 { /// The map whose columns the strips are (`context` sets it). /// shortcut: process-wide, as the drawing flags are: one scene drawn at a time. pub var current: ?*const Map = null; +/// Every context's map (a scene in chapters has one a context, `context`): a +/// pane's strip is drawn from its own context's, the one whose working +/// frame has the pane's box; `current` where none has. +pub var maps: [8]?*const Map = @splat(null); +pub var maps_frame: u64 = std.math.maxInt(u64); + +fn ownMap(panel: Panel, at: anim.Placed, box: Rect) ?*const Map { + for (maps) |maybe| if (maybe) |m| { + const b = m.frame.box(at, @enumFromInt(@intFromEnum(panel))); + if (@abs(b.x - box.x) < 0.5 and @abs(b.y - box.y) < 0.5 and @abs(b.w - box.w) < 0.5 and @abs(b.h - box.h) < 0.5) return m; + }; + return current; +} /// A mark no working window shows, `flash`ing on its pane's strip. const Flash = struct { panel: Panel, key: u64, ink: u24, p: f32 }; @@ -1220,7 +1233,7 @@ fn stripRect(box: Rect) Rect { /// pane fading through passes its faded one); drawn last, over its rows. pub fn strip(panel: Panel, u: ui.Ui, box: Rect) void { if (ui.mapping) return; - const m = current orelse return; + const m = ownMap(panel, u.at, box) orelse return; const f = u.f; if (looking(f)) return; const slot = slotOf(panel) orelse return; diff --git a/anim/src/objects.zig b/anim/src/objects.zig index dd9ea85..ec40481 100644 --- a/anim/src/objects.zig +++ b/anim/src/objects.zig @@ -67,7 +67,7 @@ fn follow(scratch: std.mem.Allocator, rec: *const Recording, m: Recording.Moment if (std.mem.startsWith(u8, name, "struct ") or std.mem.startsWith(u8, name, "union ")) o.name = name; return; }; - const live = (m.allocation(addr) catch null) != null; + const live = rec.allocated(m, addr); found.append(scratch, .{ .addr = addr, .type = t, .slot = slotOf(rec, addr, m), .freed = !live and wasAllocated(rec, addr, m.index), .name = name }) catch {}; } diff --git a/anim/src/regroup.zig b/anim/src/regroup.zig index a904ba2..f5c5fd9 100644 --- a/anim/src/regroup.zig +++ b/anim/src/regroup.zig @@ -99,10 +99,15 @@ pub const Words = struct { /// address, each word to where the slot's chain has it. become: anim.Value, panel: struct { x: f32 = 0, top: f32 = 0, first: u64 = 0 } = .{}, + /// Its first row's top (`at.top`): folded on the shelf it can be set + /// anew, and unfolds there (the introduction's II8: at the rows III's stack gives the words). + top: anim.Value, + /// 0 to 1: its header back over its rows after the dump was tied to its place (before a fold). + back: anim.Value, pub fn init(s: *anim.Frame, rec: *const Recording, moment: u64) Words { const picked = pick(rec, moment); - return .{ .rec = rec, .at = moment, .in = s.value(-1), .regroup = s.value(-1), .framed = s.value(-1), .fold = s.value(0), .placed = s.value(0), .ink = s.value(-1), .left = s.value(-1), .chains = s.value(-1), .walked = picked.walked, .three = picked.three, .become = s.value(0) }; + return .{ .rec = rec, .at = moment, .in = s.value(-1), .regroup = s.value(-1), .framed = s.value(-1), .fold = s.value(0), .placed = s.value(0), .ink = s.value(-1), .left = s.value(-1), .chains = s.value(-1), .walked = picked.walked, .three = picked.three, .become = s.value(0), .top = s.value(at.top), .back = s.value(0) }; } /// The return address the newest frame has, and the first word that @@ -149,14 +154,14 @@ pub const Words = struct { } /// Word `i`'s row's top, its bytes' first x, and how much its address shows, at regroup clock `r`. - fn where(i: usize, r: f32) struct { y: f32, x: f32, address: f32 } { + fn where(i: usize, r: f32, top: f32) struct { y: f32, x: f32, address: f32 } { const row: f32 = @floatFromInt(i / 2); const half: f32 = @floatFromInt(i % 2); const a = glide(r / 18); const b = glide((r - 18) / 12); const c = glide((r - 30) / 18); return .{ - .y = at.top + pitch * (row + row * a + half * b), + .y = top + pitch * (row + row * a + half * b), .x = at.bytes + half * (8 * at.pair + at.middle) * (1 - c), .address = if (half == 0) 1 else clamp01((r - 36) / 12), }; @@ -172,8 +177,9 @@ pub const Words = struct { const fold = placed.value(w.fold); // Folding: the rows glide up into the header (24 f), which becomes the tag (`tag`). const gather = glide(fold / 24); - const header_y = at.top - pitch; - w.tag(u, fold); + const top = placed.value(w.top); + const header_y = top - pitch; + w.tag(u, fold, top); if (gather >= 1) return; const v = u; const data = read(w.rec, w.at); @@ -181,14 +187,14 @@ pub const Words = struct { // The header (mock 29), with the first row; gone as the dump is tied to its place. // The veil over every row but the walked one, while it is walked (the header too). const veil = clamp01((r - 48) / 18) - clamp01((r - 270 - later) / 18); - const header = clamp01(in / 18) * (1 - placed.value(w.placed)) * (1 - veil) * (1 - clamp01((fold - 12) / 8)); - if (header > 0) v.faded(header).text(.sans, theme.size.sans.micro, at.address, at.top - 12, v.print("128 bytes at {x}", .{w.rec.register(w.at, "rsp")}), t.faint); + const header = clamp01(in / 18) * (1 - placed.value(w.placed) * (1 - clamp01(placed.value(w.back)))) * (1 - veil) * (1 - clamp01((fold - 12) / 8)); + if (header > 0) v.faded(header).text(.sans, theme.size.sans.micro, at.address, top - 12, v.print("128 bytes at {x}", .{w.rec.register(w.at, "rsp")}), t.faint); const address_ink = ui.mix(t.faint, theme.color.region.stack, placed.value(w.placed)); const become = placed.value(w.become); const g = glide(become); for (0..words) |i| { - const p = where(i, r); + const p = where(i, r, top); const arrive = clamp01((in - rows_apart * @as(f32, @floatFromInt(i / 2))) / 18); if (arrive <= 0) continue; const row = v.faded(arrive * (if (i == w.walked) 1 else 1 - theme.color.veil_alpha * veil) * (1 - gather)); @@ -207,7 +213,7 @@ pub const Words = struct { if (framed >= 0) for (w.three, 0..) |i, k| { const shows = clamp01((framed - 30 * @as(f32, @floatFromInt(k))) / 6); var rect = w.wordRect(i, data.words[i], placed); - rect.y = std.math.lerp(rect.y, header_y, gather); + rect.y = std.math.lerp(rect.y - at.top + top, header_y, gather); if (shows > 0) v.faded(1 - gather).read(rect, shows); }; } @@ -395,13 +401,16 @@ pub const Words = struct { /// header out 12 to 20, the tag in 16 to 24, its title where the /// header's was), which then goes to the shelf (24 f, `glide`); back, /// the reverse. - fn tag(_: *const Words, u: ui.Ui, fold: f32) void { + fn tag(_: *const Words, u: ui.Ui, fold: f32, top: f32) void { if (fold <= 16) return; const title = "the 128 bytes"; - const p = glide((fold - 24) / 24); + // To the shelf's height first, then along it (over what stands under it, crossing none); back, the reverse. + const p = clamp01((fold - 24) / 24); const w = u.width(.sans_medium, theme.size.sans.tag, title) + 40; - const x = std.math.lerp(at.address - 28, theme.canvas.margin_x, p); - const y = std.math.lerp(at.top - 30, theme.canvas.stage.y, p); + const dy = @abs(top - 30 - theme.canvas.stage.y); + const share = std.math.clamp(dy / (at.address - 28 - theme.canvas.margin_x + dy), 0.25, 0.6); + const y = std.math.lerp(top - 30, theme.canvas.stage.y, glide(p / share)); + const x = std.math.lerp(at.address - 28, theme.canvas.margin_x, glide((p - 0.6 * share) / (1 - 0.6 * share))); const v = u.faded(clamp01((fold - 16) / 8)).moved(x, y); v.fill(.{ .x = 0, .y = 0, .w = w, .h = theme.metric.context.tag }, theme.color.raised); v.frame(.{ .x = 8, .y = 6, .w = 12, .h = 12 }, t.faint, theme.stroke.rule); diff --git a/anim/src/root.zig b/anim/src/root.zig index 5482285..bc807de 100644 --- a/anim/src/root.zig +++ b/anim/src/root.zig @@ -54,6 +54,8 @@ pub const Ties = tying.Ties; pub const Place = tying.Place; /// Says where a place is this frame, for a scene's own component the ties should find. pub const anchor = tying.anchor; +/// Where a place is this frame, in canvas pixels, if a panel said (`ties.find`). +pub const findPlace = tying.find; pub const Array = @import("array.zig").Array; pub const Loupe = @import("loupe.zig").Loupe; pub const syscalls = @import("syscalls.zig"); @@ -65,6 +67,10 @@ const words = @import("words.zig"); pub const Clock = words.Clock; pub const Caption = words.Caption; pub const Label = words.Label; +pub const Title = words.Title; +pub const ChapterLabel = words.ChapterLabel; +/// A `Ui` in the design's units that the camera does not move (`words.fixed`). +pub const fixed = words.fixed; pub const Veil = words.Veil; pub const Legend = words.Legend; /// The column (design/README.md, "column (an experiment)"): beat by beat, @@ -279,6 +285,9 @@ pub const Context = struct { /// (`graph.Blocks`), the map's drawing over the source; the /// disassembly beside it linear, its blocks ruled. graph: bool = false, + /// The registers the scene moves, where not its clock's way's + /// (`movedBy`): a scene in chapters has one set for all of them. + moves: ?u32 = null, }; /// The ties between the panes, drawn over everything added before. @@ -325,7 +334,7 @@ pub const Context = struct { pub fn context(s: *anim.Frame, cursor_: Cursor, options: Context.Options) Context { // The registers the scene moves keep their rows, the rest fold, chosen // once from its way; the panel is as tall as its rows, the stack has the rest. - const moves = contexts.movedBy(cursor_.rec, cursor_.by, .{ cursor_.first, cursor_.last }); + const moves = options.moves orelse contexts.movedBy(cursor_.rec, cursor_.by, .{ cursor_.first, cursor_.last }); const registers_rows: f32 = @floatFromInt(contexts.registerRows(moves)); const stage = Stage.init(s, layout.fit(options.split, registers_rows)); stage.registers_rows = registers_rows; @@ -352,6 +361,15 @@ pub fn context(s: *anim.Frame, cursor_: Cursor, options: Context.Options) Contex // The rest of the first two columns: no pane's. whole.addIn(s, map.Spare{ .cursor = at, .stage = whole.stage, .map = whole }, .map, .backtrace); map.current = whole; + // (Each frame anew: what a frame's `frame` made lives for that frame.) + if (map.maps_frame != s.in.frame) { + map.maps = @splat(null); + map.maps_frame = s.in.frame; + } + for (&map.maps) |*slot| if (slot.* == null) { + slot.* = whole; + break; + }; return .{ .stage = stage, .map = whole, diff --git a/anim/src/segments.zig b/anim/src/segments.zig index a304993..fa30b76 100644 --- a/anim/src/segments.zig +++ b/anim/src/segments.zig @@ -269,10 +269,16 @@ pub const Segments = struct { /// Frames into each cluster's `enlarge`, top down (negative: not begun). rides: [6]anim.Value, /// `ink`'s echoes: the band holding `addr` framed as read, `shows` of it. - echoes: [16]Echo = undefined, + echoes: [24]Echo = undefined, n_echoes: usize = 0, + /// Live (design/README.md, `segments`): rip a `row` pin at the end of + /// its band's row (`◂ rip`); rsp and rbp an `under` pin in the stack's + /// band, rbp's name left of the stub and rsp's right. Each 0 to 1, in + /// over the scene's 12 f rising 8. + pins: ?Pins = null, pub const Echo = struct { addr: u64, shows: anim.Value }; + pub const Pins = struct { rip: anim.Value, stack: anim.Value }; pub fn init(s: *anim.Frame, rec: *const Recording, at: u64) Segments { var rides: [6]anim.Value = undefined; @@ -369,6 +375,40 @@ pub const Segments = struct { } for (0..n) |i| g.enlarged(u, l, i, placed.value(g.rides[i])); for (g.echoes[0..g.n_echoes]) |echo| g.echoed(u, l, echo.addr, placed.value(echo.shows)); + if (g.pins) |pins| g.live(u, l, pins, placed); + } + + /// The registers' pins (`pins`), at the moment `at`. + fn live(g: *const Segments, u: ui.Ui, l: Layout, pins: Pins, placed: anim.Placed) void { + const mono = theme.size.mono.context; + const rip = std.math.clamp(placed.value(pins.rip), 0, 1); + if (rip > 0) if (g.rowOf(u, l, g.rec.register(g.at, "rip"))) |y| { + const v = u.faded(rip).moved(0, (1 - rip) * theme.time.caption_rise); + const x = g.x + m.size_end + 14; + _ = v.pinEnd(x + theme.metric.pin.row_head[0] + theme.metric.pin.row_gap + v.width(.mono, mono, "rip"), y - 12, &.{"rip"}, region.code_); + }; + const stack = std.math.clamp(placed.value(pins.stack), 0, 1); + if (stack > 0) if (Segments.place(l, g.rec.register(g.at, "rsp"))) |at| { + u.faded(stack).moved(0, (1 - stack) * theme.time.caption_rise).pinUnder(at[0], at[1] + 2, &.{ "rbp", "rsp" }, region.stack, mono); + }; + } + + /// The middle of the row of names of the unit holding `addr`, once its box has landed. + fn rowOf(_: *const Segments, u: ui.Ui, l: Layout, addr: u64) ?f32 { + for (l.space.clusters, 0..) |c, i| if (i < 6 and addr >= c.lo and addr < c.hi) { + const all = rows(l, i, u.f.scratch); + var targets: [64]f32 = undefined; + var ys: [64]f32 = undefined; + const n = @min(all.len, 64); + for (all[0..n], 0..) |r, k| targets[k] = r.target; + const room = share(l, i); + pool(targets[0..n], ys[0..n], room[0], room[1], m.pitch); + for (all[0..n], 0..) |r, k| if (r.kind == .unit) { + const un = l.space.units[r.unit]; + if (addr >= un.lo and addr < un.hi) return ys[k]; + }; + }; + return null; } /// The ink of a cluster's largest band (its line on the whole). diff --git a/anim/src/ties.zig b/anim/src/ties.zig index 3048e32..f746f97 100644 --- a/anim/src/ties.zig +++ b/anim/src/ties.zig @@ -186,13 +186,18 @@ pub fn strikeDelay(now: cursors.Now, i: usize) f32 { const pin = [2]?f32{ now.pinLands(0), now.pinLands(1) }; if (i == cursors.sp_index) if (pin[0]) |land| return land - now.plan.at[0]; if (i == cursors.bp_index) if (pin[1]) |land| return land - now.plan.at[0]; + // A call stepped over: its result (rax) in the CPU's slot, the others in a wave after it. + const over = now.plan.result >= 0; + if (over and i == cursors.rax_index) return 0; var before: f32 = 0; for (theme.metric.all_registers[0..16]) |name| { const k = @import("context.zig").index(name).?; if (k == i) break; if ((k == cursors.sp_index and pin[0] != null) or (k == cursors.bp_index and pin[1] != null)) continue; + if (over and k == cursors.rax_index) continue; if (now.registerAge(k) == 0) before += 1; } + if (over) return now.plan.result - now.plan.at[0] + before * time.continue_wave; if (now.plan.wave) return before * time.continue_wave; return @min(before * cursors.write_apart, time.cascade) + @import("syscalls.zig").crossingDelay(now); } diff --git a/anim/src/words.zig b/anim/src/words.zig index 6549dfb..9bec54c 100644 --- a/anim/src/words.zig +++ b/anim/src/words.zig @@ -110,6 +110,59 @@ pub const Caption = struct { } }; +/// A chapter's title (design/README.md, `chapter`, `title`): said, not +/// carded, in the caption's place, one line of Go Medium 40, its numeral +/// faint and its name bright (`II Registers`); it arrives rising as a +/// caption does, over the picture it grows from. +pub const Title = struct { + numeral: []const u8, + name: []const u8, + box: Rect = theme.canvas.caption, + + pub fn draw(c: *const Title, f: *sk.Frame, at: anim.Placed) void { + const u = fixed(f, at, (1 - at.pose.opacity) * theme.time.caption_rise); + const size = theme.size.sans.caption; + const base = theme.canvas.caption_baseline[0]; + u.text(.sans_medium, size, theme.canvas.margin_x, base, c.numeral, t.faint); + const x = theme.canvas.margin_x + u.width(.sans_medium, size, c.numeral) + 2 * u.width(.sans_medium, size, " "); + u.text(.sans_medium, size, x, base, c.name, t.bright); + } +}; + +/// The clock's label (design/README.md, `clock`): the chapter, Go 18, +/// faint, ranged right 24 left of the clock's count (its widest, so that it +/// stands still as the count grows), or alone at 1856 where there is no +/// clock yet. `which` is the chapter (between two, their names +/// crossfading); `docked` 0 alone, 1 beside the count (out over its first +/// half, in over its second, with the clock: it is secondary, it only fades). +pub const ChapterLabel = struct { + names: []const []const u8, + which: anim.Value, + docked: anim.Value, + /// The count at its widest, `moment 193 of 193`. + widest: []const u8, + + pub fn draw(l: *const ChapterLabel, f: *sk.Frame, at: anim.Placed) void { + const u = fixed(f, at, 0); + const size = theme.size.sans.micro; + const base = theme.canvas.clock_y + 28; + const right = theme.canvas.stage.x + theme.canvas.stage.w; + const ends = [2]f32{ right, right - u.width(.mono, theme.size.mono.context, l.widest) - 24 }; + const which = std.math.clamp(at.value(l.which), 0, @as(f32, @floatFromInt(l.names.len - 1))); + const lo: usize = @intFromFloat(@floor(which)); + const hi = @min(lo + 1, l.names.len - 1); + const k = which - @floor(which); + const docked = std.math.clamp(at.value(l.docked), 0, 1); + for ([2]usize{ lo, hi }, [2]f32{ 1 - k, k }) |n, shows| { + if (shows <= 0) continue; + const name = l.names[n]; + const w = u.width(.sans, size, name); + // Gone from where it stood alone before it comes beside the count: never over it. + for (ends, [2]f32{ std.math.clamp(1 - 2 * docked, 0, 1), std.math.clamp(2 * docked - 1, 0, 1) }) |end, here| if (here > 0) u.faded(shows * here).text(.sans, size, end - w, base, name, t.faint); + } + } +}; + /// Text with `code` between backticks set in mono, from `x` on `baseline`. /// Returns where it ends. pub fn runs(u: ui.Ui, x: f32, baseline: f32, text: []const u8, face: ui.Face, size: f32, mono_size: f32, ink: anytype) f32 { diff --git a/anim/test/intro.script b/anim/test/intro.script new file mode 100644 index 0000000..4b0a0f7 --- /dev/null +++ b/anim/test/intro.script @@ -0,0 +1,13 @@ +# The introduction, headless: it runs to an instant of each chapter of its +# timeline without failing (I's bytes regrouping, II's rdi opened into its +# parts, III's push, IV's map at the close). +frames 2 +console set playing false +console set t 14 +screenshot .zig-cache/canim/intro-memory.png +console set t 99 +screenshot .zig-cache/canim/intro-registers.png +console set t 143 +screenshot .zig-cache/canim/intro-stack.png +console set t 999 +screenshot .zig-cache/canim/intro-end.png diff --git a/anim/test/intro_code.script b/anim/test/intro_code.script deleted file mode 100644 index 58811a4..0000000 --- a/anim/test/intro_code.script +++ /dev/null @@ -1,12 +0,0 @@ -# The introduction's third chapter, headless: it runs to four instants of its -# timeline without failing (the bytes decoded, the two forms, the working frame, the map). -frames 2 -console set playing false -console set t 8 -screenshot .zig-cache/canim/intro_code-decode.png -console set t 20 -screenshot .zig-cache/canim/intro_code-columns.png -console set t 30 -screenshot .zig-cache/canim/intro_code-frame.png -console set t 999 -screenshot .zig-cache/canim/intro_code-end.png diff --git a/anim/test/intro_memory.script b/anim/test/intro_memory.script deleted file mode 100644 index a36d36a..0000000 --- a/anim/test/intro_memory.script +++ /dev/null @@ -1,13 +0,0 @@ -# The introduction's first chapter, headless: it runs to four instants of its -# timeline without failing (the bytes regrouping, the address space enlarged, -# the dump tied to its place, the close). -frames 2 -console set playing false -console set t 14 -screenshot .zig-cache/canim/intro_memory-words.png -console set t 40 -screenshot .zig-cache/canim/intro_memory-segments.png -console set t 50 -screenshot .zig-cache/canim/intro_memory-place.png -console set t 999 -screenshot .zig-cache/canim/intro_memory-end.png diff --git a/anim/test/intro_stack.script b/anim/test/intro_stack.script deleted file mode 100644 index 7bb93ca..0000000 --- a/anim/test/intro_stack.script +++ /dev/null @@ -1,10 +0,0 @@ -# The introduction's second chapter, headless: it runs to three instants of -# its timeline without failing (the words becoming the stack, the push, the close). -frames 2 -console set playing false -console set t 2 -screenshot .zig-cache/canim/intro_stack-become.png -console set t 6 -screenshot .zig-cache/canim/intro_stack-push.png -console set t 999 -screenshot .zig-cache/canim/intro_stack-end.png diff --git a/anim/tools/chart.py b/anim/tools/chart.py index 53324ff..0ca0eb1 100644 --- a/anim/tools/chart.py +++ b/anim/tools/chart.py @@ -84,16 +84,11 @@ motion.REGIONS.update({ "plain disasm": (64, 212, 880, ph(9)), "asan disasm": (976, 212, 880, ph(5)), "plain registers": (64, 472, 880, ph(4)), "asan stderr": (976, 376, 880, ph(6)), "plain frame": (64, 612, 880, ph(10)), "asan frame": (976, 612, 880, ph(10)), **words}, - # The introduction (motion.md, "A scene: the introduction"), chapter I: the address space in the - # program column, the dump in the state column (the texts beside the address space there while - # the dump is on the shelf); the camera at x2 on the dump for its first three beats. - "intro_memory": {"space": (64, 48, 880, 840), "dump": (976, 48, 880, 840), **words}, - # Chapter II: the texts on the left (the program column), main's rows and reverse's first under them, - # the registers built over the stack. - "intro_stack": {"text": (64, 48, 880, 536), "code": (64, 584, 880, 304), "registers": (976, 48, 880, 236), "stack": (976, 296, 880, 592), **words}, - # Chapter III: the aligned panel across both columns under its text above, then the working frame - # (the nodes lens as the list scene's), then the map. - "intro_code": {"text": (64, 48, 1792, 120), "aligned": (64, 168, 1792, 720), **words}, + # The introduction (motion.md, "A scene: the introduction"): one scene in four chapters, each + # building its parts in place, so its regions are the two columns: the program column (the + # address space, then the texts beside and the code, then the aligned code and the frame's + # source and disassembly) and the state column (the bytes, the registers, the stack). + "intro": {"program": (64, 48, 880, 840), "state": (976, 48, 880, 840), **words}, }) # `cut`: the gallery is the catalogue's pages, cut from one to the next (scenes/gallery.zig: 3, 6, 9.6, 13, 16, # 19.8, 21 and 24 s), not a scene: a page's first frame changes everything at once by design. |
