summaryrefslogtreecommitdiff
path: root/anim
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-11 20:08:07 -0300
committerGabriel Schneider <[email protected]>2026-11-11 21:45:12 -0300
commit15de88cf82c187635c1989e91bfa639a10304066 (patch)
tree16fa83854258c0c6aec1dff7f70ebabf5fd64c09 /anim
parent0ec2376cae2fdfc50e90d930ebc86c7a5b7f5594 (diff)
downloadcomputeranim-15de88cf82c187635c1989e91bfa639a10304066.tar.gz
computeranim-15de88cf82c187635c1989e91bfa639a10304066.zip
canim: a column of text as an experiment; the disassembly tied to the stack
From the user. A scene may set its text in a column beside the panes a beat is about: col.beat names the panes and their rows, where the text is placed (beside, below, above, or on a drawing) and what it is level with; panes the beat leaves out fold to their title bars on a shelf, their changes struck there. Tried as two scenes beside the originals: the call followed down (column) and a bubble on sort's rings (column_sort). annotation = .tied names the word an instruction touched and draws a touch to its stack row; offsets count from the frame's base; rsp's pin travels with its amount before the stack follows; .whole keeps the full chain. carry = .arrow draws a value's way between memory and a register. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNCKgYCGiANnEwcEQxa
Diffstat (limited to 'anim')
-rw-r--r--anim/README.md284
-rw-r--r--anim/build.zig2
-rw-r--r--anim/scenes/column.zig133
-rw-r--r--anim/scenes/column_sort.zig59
-rw-r--r--anim/scenes/gallery.zig2
-rw-r--r--anim/scenes/heap.zig3
-rw-r--r--anim/scenes/sqlite.zig3
-rw-r--r--anim/scenes/zoom.zig5
-rw-r--r--anim/src/column.zig942
-rw-r--r--anim/src/context.zig239
-rw-r--r--anim/src/cursor.zig363
-rw-r--r--anim/src/descent.zig37
-rw-r--r--anim/src/disasm.zig210
-rw-r--r--anim/src/graph.zig12
-rw-r--r--anim/src/root.zig11
-rw-r--r--anim/src/rows.zig20
-rw-r--r--anim/src/stage.zig18
-rw-r--r--anim/src/theme.zig20
-rw-r--r--anim/src/ties.zig145
-rw-r--r--anim/src/words.zig21
-rw-r--r--anim/test/column.script10
-rw-r--r--anim/test/column_sort.script10
-rw-r--r--anim/test/recordings.zig57
23 files changed, 2415 insertions, 191 deletions
diff --git a/anim/README.md b/anim/README.md
index 8c18c82..39a035f 100644
--- a/anim/README.md
+++ b/anim/README.md
@@ -94,6 +94,62 @@ windows as they were as long ago (`Cursor.lags`, `time.minimap_lag`,
`time.minimap_fade`: its drawings are averaged), so nothing on it starts
on a primary onset's frame and nothing on it moves a pixel in one.
+**The annotation and the carry, two knobs** (`Levels`, design/README.md
+`insn` and "4. Ties"). `at.levels.annotation`, read when `canim.context`
+is made: `.tied` (the default) names the word an instruction reads or
+writes and gives one hop (`next → 405010`, `prev ← 0`, a global by its
+data name with its whole chain, `head → 407050 ← 9`), a register's first
+value (`rax 405010`), and a move of rsp or rbp first (`rsp -8 · saved rbp`,
+`fib(4) · rsp -8`, `rbp = rsp`, `→ 4011ad main+45 · rsp +8`); the stack
+counts its offsets from the frame's base (`· offsets from rbp`) with two
+`free` words of headroom over rsp, and a walked step goes cause to effect:
+its touch from the row to the word, the word, rsp's or rbp's pin travelling
+with the amount on it, the window following last. `.whole` is pwndbg's
+chain, offsets from rsp and the old cascade, for a scene whose story is the
+address itself (heap, sqlite, the gallery). `at.levels.carry` (`.off` by
+default, `.arrow`, `.value`) is read at each step, so a beat can set it
+before a walk and put it back after:
+
+```zig
+at.levels = .{ .idea = .calls, .source_rows = 8, .annotation = .whole }; // before canim.context
+at.levels.carry = .arrow; at.walk(s, .moment, to); at.levels.carry = .off; // the value's way, for one beat
+```
+
+**The text column, an experiment** (`src/column.zig`, design/README.md
+"column (an experiment)"). A scene can tell its beats with the panes a beat
+is about in the left column and its text beside them, level with the row it
+speaks of, every other pane folded to its tag on the shelf (y 48), a
+register struck on its tag as on its row. It is the author's instrument:
+each beat says which panes stand and with how many rows (`canim.column_rest`:
+what the column has left), where its text is placed (`.beside`; `.below`,
+the working frame whole with its caption; `.above` or `.on` a drawing
+across both columns), what the text is level with (`.pc`, the default: the
+row the beat's first step is on; `.{ .row = addr }`, `.{ .head = "open" }`,
+`.floor` (where the kernel's window opens), `.{ .block = addr }`, `.{ .y =
+744 }`) and where its stem points (`.level`, `.none`, `.{ .to = … }`), and
+the folded panes' notes (the registers', the source's and the disassembly's
+are computed where the beat gives none). Between beats, in a rest, the last
+text dims, the panes that leave fade and fold to the shelf, those that stay
+glide (a pane that changes its rows fades out and in round its glide), those
+that come unfold and fade in; an older text in the way glides up (or down
+where there is no room above), the new one arrives with its stem, and the
+stem draws back as the step fires. Three texts stand at most; at a run only
+the newest. `scenes/column.zig` is the trial (`open` followed down),
+`scenes/column_sort.zig` the wide placements on sort's rings:
+
+```zig
+const col = canim.column(s, ctx, .{ .lens = log, .titles = .{ .band = "system calls", .view = "its bytes" } });
+col.beat(s, .{ .at = .below, .say = "A program cannot open a file itself.\nIt asks the kernel, and waits." });
+cur.walk(s, .line, rec.lineMoment(6, main.enter));
+col.beat(s, .{
+ .panes = &.{ .{ .source, 3 }, .{ .disasm, 11 }, .{ .stack, canim.column_rest } },
+ .say = "The call pushes where to come back to, `main+45`, and goes down to open's stub.",
+ .level = .{ .row = call }, // default: the pc's row
+ .notes = &.{.{ .band, "none yet" }},
+});
+canim.descent.step(cur, s, .moment);
+```
+
## The scenes
| Scene | Shows | Split, lens | Recording |
@@ -108,6 +164,8 @@ on a primary onset's frame and nothing on it moves a pixel in one.
| `zoom` | one line of C as its instructions, the call's bytes | `none`, the camera at x1.16 on the instructions and the stack in one view, cause and effect (the stack's window set before the move and held); the map's drawing the calls of `fib` (`Map.drawing`) | `steps` |
| `sqlite` | a row's way to disk in SQLite: from `sqlite3_step` to `sqlite3BtreeInsert` (three continues, the row's struct on the stack), the commit's `unixWrite` nine calls under `main`, `pwrite64` of page 2 into the kernel, and the page read as a B-tree leaf | `subject`, `backtrace` (`Context.Options.backtrace`), then `syscalls`; its view a `hexdump.Dump`; as the caption names them, rdi's `BtCursor` opened in a loupe, then rsi linked to its row in the view (`Context.tiesWith`); the page's fields named a group at a time, 2 s apart; the backtrace lens drawn on its map | `sqlite` |
| `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 trial of 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: 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, 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` |
## The blocks
@@ -119,11 +177,11 @@ every state the code has in the `gallery` scene.
| 0 tokens | grid, colour, type, the splits | `src/theme.zig` | per "Token changes" (`layout.split` and `layout.fit`, `metric.registers` (the quiet cells), `time.unroll` (`unroll`, `roll`, a far jump's travel; the extend's 4 f is `time.extend` now), `metric.calls`, `time.pin`, `time.continue_wave`, `time.relayout_fade` there; the insn's character counts gone); JetBrains Mono NL (`.code*` faces) for all mono, Medium under 30 |
| 1 atom | `address` (`lead`, `name`, `rwx`), `value` (and `Ui.typed`: `fd`, `bool`, `char`), `arrow` (`points`, `holds`, `more`), `mark`s, `plaque` (`chip`), `pin` (`row`, `under`; and at a view's row's end, `Ui.pinEnd`), `bracket` (`quiet`, `tie`, `thread`), `tag` | `src/ui.zig` (`Ui.address`, `.value`, `.arrow`, `.written`, `.corner`, `.read`, `.cellWritten`, `.cellRead`, `.current`, `.trail`, `.unknown`, `.chip`, `.pinRow`, `.pinUnder`, `.bracket`, `.panel`) | marks as mock 15's column B: `current` the white wash (`color.wash`) and the gold plaque; `struck` the softened paper (`color.struck`) with bold bright digits; `held` a turned corner (9; 12 on a lens's cell), in over the cool's last 6 f (`Heat.corner`, `time.strike.corner`); `armed`, `read` |
| | `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 from rsp ranged right to 172, 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`; 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 |
+| 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`) |
+| | `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 |
| | `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 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` |
+| 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 |
| | `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`) |
@@ -131,9 +189,10 @@ every state the code has in the `gallery` scene.
| | `hexdump` | `src/hexdump.zig` | malloc's words: a field read as `size` (`0x20 a m P`, the bits as rip's flags) or `protected` (`→ 405050 ^ 405`, `NULL ^ 405`, its arc to the pointer it protects), and a field's `note` (Go 18 faint: `key`, `top`, `slots left`); a lens's view (`hexdump.panel`): `bytes` rows and their reading, veiled at a sprint; a row whose bytes the step changed where the recording saw no write (memory nothing watches, read anew at a stop), or that became known, crossfading over 12 f (`rowPasses`); one reading for every dump (`hexdump.reading`), a list a character apart, a typed number as its type reads (`char` quoted, `bool` by name); the address room once a dump, by its widest; `Dump`, a view of a region by the fields a scene gives it (`Field`: where, how long, read as a number, big-endian or not, a pointer, text, or left to the eye), the rows that hold a field and a `more` row for each stretch left out, and where those rows outnumber the window, a window kept round the first row a mark or the step is on, the rest folded into `more` rows; marks the scene plays, and the step's only from the stop it came in at (`since`); the bytes a syscall was given as the kernel took them (`given`), and only what the debugger read at the stop (`seen`) |
| | `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, 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 | `thread`, `link` (and its `pin`), `projection`, `echo` | `src/ties.zig` | panels publish places (`anchor`); `Ties`, added last, 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; a projection from the view's bytes, or from a frame's return address to its call's node |
+| 4 tie | `thread`, `link` (and its `pin`), `projection`, `echo` | `src/ties.zig` | panels publish places (`anchor`); `Ties`, added last, 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; 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. 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) |
-| | `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 |
+| | `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` (an experiment) | `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 12 f, fold 24 f, glide 24 f (48 f between kinds of placement, a pane crossing to the other column going down its own first, then across), unfold 24 f, fade in 12 f; a pane that changes its rows fades out and in round its glide) |
| | `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 |
@@ -209,6 +268,16 @@ Every recording the build makes carries each function's blocks
each stop on a jump: the graph and the linear rows' block rules read them.
The old `list` of the gallery has none, and draws none.
+Under `tied` the touched word of a step is the recorder's `touch` (a
+`push`, `call` or `enter` writes 8 at rsp-8, a `pop` or `ret` reads 8 at
+rsp, a `leave` 8 at rbp, as the tracer records them now); a recording made
+before that (the gallery's) has the word derived from rsp and rbp
+(`cursor.stackTouch`). A global's data name (`head+0`), the role a `push
+rbp` is about to write (`saved rbp`, at the push's own stop), a shared
+word's other locals and the canary's name are the tracer's; the
+return-address word a `call` is about to write has no role at the call's
+own stop, so its row says `fib(4) · rsp -8` alone.
+
A recording that begins inside a call (`--from`) has that call open from
its first stop (`Recording.index`, from the frame chain). Writes are the
bytes whose value changed, to the element the instruction stored (its
@@ -253,108 +322,131 @@ 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 |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| POP, before / after | 7 / 7 | 8 / 12 | 6 / 5 | 7 / 7 | 12 / 16 | 6 / 4 | 5 / 4 | 16 / 16 | 11 / 9 | 0 / 0 |
-| of them the strips' | 1 / 0 | 1 / 2 | 5 / 4 | 1 / 0 | 1 / 4 | 1 / 0 | 0 / 0 | 6 / 7 | 4 / 3 | 0 / 0 |
-| POP exempt, before / after | | | | | | | | | cut 5, keyframe 1 / cut 5 | |
-| CROWD, before / after | 4 / 3 | 8 / 9 | 10 / 8 | 4 / 4 | 2 / 3 | 1 / 2 | 1 / 1 | 16 / 17 | 5 / 6 | 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 |
-| 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 | |
-| CAPTION under its reading time, before / after | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | | |
-| 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 | |
-| AIR, before / after | 0 / 0 | 0 / 0 | 1 / 1 | 0 / 0 | 0 / 0 | 1 / 1 | 1 / 1 | 0 / 0 | 1 / 1 | 1 / 1 |
-| seconds, before / after | 42.0 / 42.1 | 81.7 / 82.1 | 63.8 / 70.5 | 83.8 / 83.8 | 68.9 / 68.9 | 33.5 / 33.5 | 62.9 / 62.9 | 78.6 / 79.2 | 27.0 / 27.0 | 12.3 / 12.3 |
+| | fib | list | sort | syscalls | musl | zoom | sqlite | heap | gallery | title | column | column_sort |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| POP, before / after | 7 / 10 | 12 / 13 | 5 / 3 | 7 / 21 | 16 / 16 | 4 / 5 | 4 / 7 | 16 / 17 | 9 / 9 | 0 / 0 | – / 9 | – / 6 |
+| of them the strips' | 0 / 1 | 2 / 4 | 4 / 2 | 0 / 8 | 4 / 1 | 0 / 2 | 0 / 0 | 7 / 6 | 3 / 3 | 0 / 0 | – / 4 | – / 3 |
+| POP exempt, before / after | | | | | | | | | cut 5 / cut 5 | | | |
+| CROWD, before / after | 3 / 3 | 9 / 8 | 8 / 6 | 4 / 4 | 3 / 8 | 2 / 4 | 1 / 2 | 17 / 18 | 6 / 6 | 0 / 0 | – / 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 |
+| CAPTION up over 720 f, before / after | 0 / 1 | 0 / 2 | 0 / 1 | 0 / 0 | 0 / 0 | 0 / 1 | 0 / 0 | 0 / 0 | 0 / 0 | | – / 0 | – / 1 |
+| 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 |
+| 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 |
+| AIR, before / after | 0 / 0 | 0 / 0 | 1 / 1 | 0 / 0 | 0 / 0 | 1 / 1 | 1 / 1 | 0 / 0 | 1 / 1 | 1 / 1 | – / 1 | – / 0 |
+| seconds, before / after | 42.1 / 50.2 | 82.1 / 88.0 | 70.5 / 72.9 | 83.8 / 85.4 | 68.9 / 77.5 | 33.5 / 38.0 | 62.9 / 62.9 | 79.2 / 80.2 | 27.0 / 27.0 | 12.3 / 12.3 | – / 104.8 | – / 30.6 |
-"Before" is the last pass's "after". Every scene's layout changed (layout
-A), so every count is of new pictures; a POP's place moved with its
-scene's timing. The title's export is the last pass's to the byte. Sort
-is 6.7 s longer: its first trip walks the swap's `reach` and the ring's
-first turn, then the disassembly unrolls for a beat under a caption of
-its own (its hold rolled back as the caption's reading time ends: no air
-over it).
+"Before" is the last pass's "after". The gallery and the title were not
+exported again (the gallery keeps `.whole` and its old recordings: its test
+against its pictures passes); every other scene was, on the tracer's new
+recordings. The scenes that walk stack code are longer: under `tied` a step
+that touches the stack or moves rsp plays its verbs one after another
+(touch, word, pin, window), and a call or a return walked in a descent takes
+the stack's timetable before its windows move (fib +8.1 s, musl +8.6, list
++5.9, zoom +4.5, sort +2.4, syscalls +1.6; heap +1.0 under `.whole`, its new
+pop and ret reads taking a memory slot). Five captions now stand over 720 f
+(fib, list twice, sort, zoom): the steps under them grew longer, not the
+captions. The column's regions are its own (`design/motion/motion.py`:
+the shelf, the panes' column and its strips, the text column, the clock and
+the caption band); its "caption" region is the text column, which in its
+opening and close is the state column and where an older text dims and
+glides: its CAPTION counts are not a caption's (the instrument finds 39
+"arrivals" for twelve texts), and are not checked.
-What this pass built (design/README.md's "The frame" (layout A),
-`registers`, `stack`, `source`, `disasm`, `graph`, the `blocks` lens, the
-verbs `reach`, `unfold`, `unroll`, `roll`, `leave`, `turn`, Forbidden's
-fact from after the moment; mocks 40 to 43, 22, 24, 25):
+What this pass built (design/README.md's "column (an experiment)", `insn`,
+`slot`, `stack`, "4. Ties" (`touch`, `carry`); motion.md's "A scene in the
+column", "A word touched", "A call pushed", "A return", "The stack's own
+instructions"; mocks 44 to 56):
-- Layout A in every split (`layout.split`, `layout.fit`): the
- disassembly under the source; the registers the scene never changes
- folded three to a row under a rule (`Registers.moves`, chosen once from
- the clock's way), the panel as tall as its rows and the stack the rest:
- fib 10 rows and 13 slots, list 9 and 14, sort 11 and 20, syscalls 14 and
- 11, musl 15 and 10, zoom 9 and 17 (with the backtrace's four), heap 14
- and 9, sqlite 17 and 6, the gallery 13 and 12 (beside). The `blocks`
- split has no view; the thread is drawn in every split. In a `dive` the
- registers fold as they land. The view's loupe lies over the stack's
- first rows.
-- The graph from the code alone, `rings` and `layers` (`graph.zig`,
- above), `reach` and `unfold`; on the map the lens's drawing beside the
- linear disassembly (the graph-with-rows gone). Sort tells it with its
- rings: the swap's first `reach`, the inner ring's first turn.
-- `unroll` and `roll` (`map.Unroll`); a far jump in the same column at a
- walk unrolls, travels and rolls; the strips' faults at a far jump out of
- the column (sqlite: the window lost through a continue, the step back
- from `pwrite64`, the tag's range) and the system calls' log's first
- pixel steps; a source tag's line range changing with its scroll.
-- On the way: a stack word too long for its row's room cut with `…`
- (`rows.chain`), a breakpoint recording's deepest chain read at every
- stop (sqlite's map no longer repacks as a continue sets off), the map's
- disassembly measured by the moment the pane shows; `time.unroll` (the
- extend's stagger is `time.extend`).
+- The text column (`src/column.zig`, above): the shelf, the panes in one
+ column, texts `beside` (level with their row, riding it, dimming, three at
+ most), `below`, `above`, `on`; the change between beats in its order
+ (fade, fold, glide, unfold, fade in), a pane crossing to the other column
+ going down its own first, a pane that changes its rows faded round its
+ glide; `Stage.glide`, `Stage.column` (the clock under the text column),
+ `Stage.zoom` (a drawing across both columns, its tag at its size); places
+ for a text to be level with (`ties.Place.row`, `floor`, `block`). The
+ trial `column` (the storyboard's C1 to C12) and `column_sort` (`on` and
+ `above` sort's rings).
+- The disassembly tied to the stack, the knob `annotation` (`.tied` the
+ default; `.whole` in heap, sqlite and the gallery): the row's names and one
+ hop, its moves of rsp and rbp, the stack's offsets from the frame's base
+ and its two words of headroom, the `touch`, the pin's travel (rows held,
+ the amount on the pin, rows gained or released, the span riding) and the
+ window following after, every verb in motion.md's order; the knob `carry`
+ (`.off` by default; `.arrow` on zoom's first beat). On the tracer's new
+ recordings: the touches of `push`, `pop`, `call`, `ret`, `leave`, data
+ names (`head`), the push's role at its own stop, shared words (`i, n`),
+ the canary.
Right in one frame, and exempted by name: the encoder's keyframes and the
gallery's cuts (above).
-What fires still, by kind (located on this pass's exports; those not
-looked at this pass say so):
+What fires still (this pass's exports; located where it says so, the rest
+counted, not looked at):
-- The strips' regions: list 3.13 and 3.87 (in the dive, 17 and 20
- pixels); sort 0.43 (its opening) and 42.57 (the map's own panels under
- the source strip's region while the sprint plays on the map), its 20.52
- and 59.23 (12 and 14 pixels, the stack strip) not looked at; musl's four
- (13 to 15 pixels, the stack strip) and heap's seven (the disassembly
- strip at 3.62 and 28.62, the stack strip 37.17 to 65.47, 12 to 71
- pixels) not looked at; the gallery's 12.27, 18.15 and 20.82 at a
- state's first frame. The unroll's two that fired in a draft (its
- window going bright in a frame, its page lifting off the strip in one)
- are gone: both fade now.
-- The stack: a few pixels in the arcs' lanes and the pins (fib 8.20,
- 25.07, 39.30; syscalls 57.72, 70.17; sqlite 20.43, 31.75; zoom 19.25;
- the gallery's 24.62); fib's 3.32 and 19.67 (139 and 235 pixels),
- syscalls' 29.13, musl's six, list's 7.30 and heap's 55.83 not looked at.
-- Registers: a held corner, a few pixels at a value's top left (fib 21.27,
- syscalls 44.32, sqlite 38.67); zoom's 12.80, list's 70.85, musl's 62.57,
- heap's 13.68 and the gallery's 26.23 not looked at.
-- The source and the disassembly: syscalls 17.92 and 28.23, the
- descent's rows; zoom 18.10 and 19.60, an annotation taking its value in
- place under the camera; musl's six in the disassembly, the descent's
- rows, a library address's leading digits changing in a frame (17.03
- looked at); list 62.97 and 78.87, the source's text changing in one
- frame at a run's first step (about 7 400 pixels, not the trail and not
- the tag: not identified); list's 46.22 and 51.95 (13 and 18 pixels in
- the disassembly) not looked at.
-- The view: syscalls 64.77, the read's first byte landing over the
- buffer's dots; the gallery's 9.00, 12.62 and 15.40, the nodes' dump
- re-windowing by a row at a step's first frame (9.00 looked at); sqlite
- 55.83 (15 pixels) not looked at. Sqlite's 42.47 (the system calls'
- log's first whole-pixel step) is gone.
-- The drawing: fib 33.80, the calls tree's badge corner; the heap's eight
- in its runs (its 17 CROWDs too: the calls and returns it does not
- narrate); list's 13.12, 41.02, 68.05 and 69.25 (120 to 281 pixels) and
- sort's 6.73 (18 pixels) not looked at.
-- AIR: sort's, zoom's and sqlite's last pictures (the last caption read,
- then held), sqlite 46.02 too, where the chart misses the read frame on
- one byte (`0d`) at 47.5 s; the gallery's atoms page, 3 s by design; the
- title's card, held by design.
-- CROWD: the advance (thread, plaques and rip as one mark, the source and
- the disassembly scrolling with it), the veil over three panels at a
- run's first step; zoom's two the camera coming back; sort's `surface`
- and `dive`, every panel at once by design.
+- The column: four in the panes' strips (12 to 38 pixels, 16.90 to 91.53);
+ 35.73, a library address's shared digits changing in a frame as the run
+ enters libc (looked at: the disassembly's own `lead`, as in musl); 82.85,
+ the read's first byte landing over the buffer's dots (looked at, as in
+ syscalls before); 59.55 and 91.65, a tag note's struck digits turning
+ bold (20 to 28 pixels on the shelf, looked at); 20.32 (12 pixels) not
+ looked at. No CROWD: the panes change one move after another. AIR at
+ 28.93 (4.9 s): the stub's text (104 characters) is still being read after
+ its step.
+- syscalls: 21, of them 8 in the strips. Looked at: 9.45 and 38.27, a row's
+ in-step annotation (the `lea`'s `= 402004 ← "note"`, a register set's
+ `r8 0`) appearing in one frame as the CPU's strike lands, not faded; 59.32,
+ the source and the disassembly scrolling to line 7 (its first frame the
+ largest). 11.05, 39.87, 41.47 (the disassembly), 16.62, 59.48, 81.70 (the
+ stack, 22 to 25 pixels), 44.88 and 49.80 (registers, 12 and 16 pixels),
+ 49.53 (source, 17), 65.85 (the view, 72: the read's first byte) not
+ looked at. The new ones are the tie's: they want the in-step annotation
+ faded in with its strike (`disasm.zig`'s `value_at`), for the same
+ instruction under `whole` too.
+- fib 10, list 13, musl 16, heap 17, sqlite 7, zoom 5, sort 3,
+ column_sort 6: counted, not located this pass (their timings all moved).
+ musl's sixteen are mostly in the disassembly, 1.6 s apart in its walks:
+ likely the same in-step annotations.
+- CAPTION over 720 f (fib 15.78, list 39.45 and 68.18, sort 45.48, zoom 1.25,
+ column_sort 9.67): the steps under a caption grew with the tie's order.
+- AIR: sort's, zoom's and sqlite's last pictures (held by design), the
+ gallery's atoms page and the title's card (not exported again).
+- CROWD: the advance (thread, plaques and rip as one mark), the veil over
+ three panels at a run's first step, sort's `surface` and `dive`; musl's
+ eight and zoom's four not looked at.
## What is not done
+- The column (an experiment): a text `on` a drawing sits where the scene
+ puts it (`Beat.where`) and its stem goes along the drawing's top lane and
+ down to the part it speaks of; nothing checks that it keeps 16 clear of
+ every element and path, nor falls back to `above` where it cannot. A text
+ about a folded pane does not point at its tag on the shelf; at a sprint
+ the scene does not surface to the map with a text `on` it. Only the
+ registers', the source's and the disassembly's tag notes are computed
+ (the lens's and the stack's are the scene's). A text rides its row until
+ the panes change or the row goes, then stays: remembered by the process
+ as frames are drawn in order (`last_level`, `latched`: an export, a
+ player playing), so after a seek a text whose row has gone sits at 400
+ until its row is seen again. A pane that changes its rows fades them out
+ and in round its glide (they are laid out for its height), so the
+ descent is empty for about 40 f as it grows to the kernel's floor. The
+ panes keep their minimaps (mocks 49 to 53 draw none). The lens is one
+ object: its view can stand with its drawing folded (the bytes over the
+ source), not the other way round. The trial is 104.8 s against the
+ working frame's 85.3 (`syscalls` this pass): the storyboard's longer
+ texts' reading times and about 9.6 s of pane changes (seven of them); a
+ sixth longer would be 99.5 s.
+- The tie to the stack (Part B's leftovers): the window's scroll to a touched
+ word outside it happens in the fire's frames, with no slot of its own; in
+ a step by line all writes land before the pins and the call row does not
+ fire within the step; `enter`; a `sub rsp` longer than the window slides
+ the rows (no `unroll`); at a run the pins are not drawn over the veil; a
+ carry to a dump's run, a loupe's row or a call's return row, and a carry's
+ stub off the window; the touch giving way to a link down the right lane
+ over the same rows. Data names are used only in a tied row, not inside
+ chains; a 4-byte access to a global keeps the whole chain, unnamed.
+
- The graph: the map draws the `blocks` drawing only where the scene asks
(`Context.Options.graph`: sort); the catalogue has it whenever the
recording has the function's blocks. Not built: the descent on the map
diff --git a/anim/build.zig b/anim/build.zig
index 24ce5e1..6351250 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" };
+const scenes = [_][]const u8{ "title", "fib", "list", "sort", "syscalls", "musl", "zoom", "heap", "gallery", "column", "column_sort" };
pub fn build(b: *std.Build) void {
const target = b.standardTargetOptions(.{});
diff --git a/anim/scenes/column.zig b/anim/scenes/column.zig
new file mode 100644
index 0000000..b1a8df7
--- /dev/null
+++ b/anim/scenes/column.zig
@@ -0,0 +1,133 @@
+//! The column, a trial (design/motion.md, "A scene in the column: `open`
+//! followed down"): the syscalls scene's story told beat by beat with the
+//! panes each beat is about in one column and its text beside them, level
+//! with the row it speaks of, the rest folded to their tags on the shelf.
+//! The same recording and the same steps as `syscalls`; the scene's
+//! choices, a beat at a time, are the storyboard's table (C1 to C12):
+//! the opening and the close the working frame whole, its caption below.
+const std = @import("std");
+const anim = @import("anim");
+const canim = @import("canim");
+const recordings = @import("recordings");
+
+pub const background = canim.background;
+pub const scene = anim.Live(frame, struct {});
+
+/// The first moment from `from` whose pc is named `name` (`open@plt+0`).
+fn at(rec: *canim.Recording, from: u64, name: []const u8) u64 {
+ var i = from;
+ while (i < rec.end()) : (i += 1) if (std.mem.eql(u8, rec.strings.get(rec.register(i, "rip")) orelse "", name)) return i;
+ return rec.end();
+}
+
+/// The first moment from `from` whose instruction is `text`.
+fn on(rec: *canim.Recording, from: u64, text: []const u8) u64 {
+ var buf: [256]u8 = undefined;
+ var i = from;
+ while (i < rec.end()) : (i += 1) if (rec.instruction(i, rec.register(i, "rip"), &buf)) |here| if (std.mem.startsWith(u8, here.text, text)) return i;
+ return rec.end();
+}
+
+fn frame(s: *anim.Frame) void {
+ const rec = canim.open(recordings.hello);
+ const main = rec.call("main", 0);
+ var cur = canim.cursor(s, rec, main.enter);
+ const stub = at(rec, main.enter, "open@plt+0");
+ const crossing = on(rec, stub, "syscall");
+ const back = on(rec, crossing, "ret");
+ const done = rec.lineMoment(10, back);
+ const call = rec.register(stub - 1, "rip");
+ cur.journey(.moment, done);
+ cur.levels = .{ .source_rows = 8, .fire = .disasm };
+ const ctx = canim.context(s, cur, .{ .split = canim.layout.split.beside, .syscalls = true, .descent = true });
+ const log = canim.crossing(s, .{ .cursor = cur, .stage = ctx.stage, .focus = true });
+ ctx.map.add(s, canim.Crossing{ .cursor = cur, .stage = ctx.map.stage });
+ const col = canim.column(s, ctx, .{ .lens = log, .titles = .{ .band = "system calls", .view = "its bytes" } });
+ const t = canim.theme.time;
+ const joins = ctx.ties(s);
+ canim.establish(s, .{ ctx.clock, ctx.registers, ctx.stack, ctx.source, ctx.disasm, log, joins });
+ const rest = canim.column_rest;
+ const regs: u32 = @intFromFloat(ctx.stage.registers_rows);
+
+ // C1: the working frame whole, its caption below.
+ col.beat(s, .{ .at = .below, .say = "A program cannot open a file itself.\nIt asks the kernel, and waits." });
+ cur.walk(s, .line, rec.lineMoment(6, main.enter));
+ // C2: the arguments, beside the rows that set them.
+ col.beat(s, .{
+ .panes = &.{ .{ .source, 3 }, .{ .disasm, 11 }, .{ .registers, regs } },
+ .say = "main puts open's arguments where the convention says: \"note\" in `rdi`, 0 (O_RDONLY) in `rsi`.",
+ .notes = &.{ .{ .band, "none yet" }, .{ .view, "no call crossing" } },
+ });
+ cur.walk(s, .moment, stub - 1);
+ // C3: the call goes down; the stack under the descent.
+ col.beat(s, .{
+ .panes = &.{ .{ .source, 3 }, .{ .disasm, 11 }, .{ .stack, rest } },
+ .say = "The call pushes where to come back to, `main+45`, and goes down to open's stub.",
+ });
+ canim.descent.step(cur, s, .moment);
+ s.wait(t.phrase_rest);
+ // C4: the stub's jmp: the stack holds still.
+ col.beat(s, .{ .say = "The stub in the PLT is one jump: it reads `open@got`, where the loader wrote libc's `open`. It pushes nothing.", .panes = &.{ .{ .source, 3 }, .{ .disasm, 11 }, .{ .stack, rest } } });
+ canim.descent.step(cur, s, .moment);
+ s.wait(t.phrase_rest);
+ // C5: the wrapper at a run, the bubble level with its window's head.
+ col.beat(s, .{
+ .panes = &.{ .{ .source, 3 }, .{ .disasm, 11 }, .{ .stack, rest } },
+ .say = "libc's `open` is a wrapper: a few lines of C around the one instruction that calls the kernel.",
+ .level = .{ .head = "open" },
+ });
+ cur.hurry(s, .moment, crossing - 3, .{});
+ // C6: its last three, beside the registers they set.
+ col.beat(s, .{
+ .panes = &.{ .{ .source, 3 }, .{ .disasm, 11 }, .{ .registers, regs } },
+ .say = "Its last three set the kernel's arguments: AT_FDCWD in `rdi`, and 257, openat's number, in `rax`.",
+ .stem = .none,
+ .notes = &.{ .{ .band, "none yet" }, .{ .view, "`\"note\"`" } },
+ });
+ cur.walk(s, .moment, crossing);
+ // C7: the crossing, the kernel at the descent's floor.
+ col.beat(s, .{
+ .panes = &.{ .{ .source, 3 }, .{ .disasm, 24 } },
+ .say = "`syscall` crosses down. The kernel opens \"note\" and answers 3: the file's descriptor, in `rax`.",
+ .level = .floor,
+ .stem = .none,
+ .notes = &.{ .{ .band, "none yet" }, .{ .view, "`\"note\"`" } },
+ });
+ canim.descent.step(cur, s, .moment);
+ s.wait(t.phrase_rest);
+ // C8: back up; the bubble climbs back to main's call row.
+ col.beat(s, .{
+ .panes = &.{ .{ .source, 3 }, .{ .disasm, 11 }, .{ .stack, rest } },
+ .say = "open's `ret` comes straight back to main: the stub was a jump, not a call. main keeps the answer in `f`.",
+ .level = .{ .row = call },
+ .stem = .none,
+ .notes = &.{ .{ .band, "`openat(…) = 3`" }, .{ .view, "" } },
+ });
+ cur.hurry(s, .moment, back, .{});
+ canim.descent.step(cur, s, .moment);
+ s.wait(t.phrase_rest);
+ cur.walk(s, .line, rec.lineMoment(7, back));
+
+ // C9 to C11: the other three stepped over, each beside its call row,
+ // its bytes over the source.
+ const lines = [_][]const u8{
+ "`read`: the kernel copies the file's bytes into `buf`, and says how many.",
+ "`close`: the number is handed back.",
+ "`write`: the same bytes go the other way, from `buf` to file number 1, the output.",
+ };
+ for (lines) |line| {
+ const here = cur.moment(s);
+ col.beat(s, .{
+ .panes = &.{ .{ .view, 3 }, .{ .source, 3 }, .{ .disasm, rest } },
+ .say = line,
+ .level = .{ .row = rec.register(on(rec, here, "call"), "rip") },
+ .notes = &.{.{ .band, "the calls so far" }},
+ });
+ canim.syscalls.step(cur, s, .line);
+ s.wait(t.phrase_rest);
+ }
+ // C12: the working frame whole again, to main's return.
+ col.beat(s, .{ .at = .below, .say = "" });
+ cur.walk(s, .line, done);
+ col.close(s);
+}
diff --git a/anim/scenes/column_sort.zig b/anim/scenes/column_sort.zig
new file mode 100644
index 0000000..d851172
--- /dev/null
+++ b/anim/scenes/column_sort.zig
@@ -0,0 +1,59 @@
+//! The column's wide placements, on sort's rings (design/README.md,
+//! "column (an experiment)", mock 55): the opening in the working frame
+//! (the `blocks` lens), then the drawing across both columns twice its size,
+//! the rest folded to the shelf, a beat's text `on` it, in the corner the
+//! rings leave free, its stem round the drawing's outside to the pc's block;
+//! then a beat `above` it; then the working frame again. The steps are
+//! sort's own: its first trip round the inner loop, a block at a time.
+const anim = @import("anim");
+const canim = @import("canim");
+const recordings = @import("recordings");
+
+pub const background = canim.background;
+pub const scene = anim.Live(frame, struct {});
+
+fn frame(s: *anim.Frame) void {
+ const rec = canim.open(recordings.sort);
+ const graph = canim.graph;
+ // As the sort scene opens: the `while`, about to compare 31 with 12.
+ var start = rec.call("sort", 0).enter;
+ while (rec.next(.over, rec.next(.over, start)) < rec.call("swap", 0).enter) start = rec.next(.over, start);
+ var at = canim.cursor(s, rec, start);
+ at.levels = .{ .fire = .disasm, .source_rows = 6 };
+ at.journey(.over, rec.call("swap", 0).exit.?);
+ const ctx = canim.context(s, at, .{ .split = canim.layout.split.blocks, .graph = true });
+ const blocks = canim.add(s, graph.Blocks{ .cursor = at, .stage = ctx.stage, .focus = true });
+ const col = canim.column(s, ctx, .{ .lens = blocks, .titles = .{ .band = "its blocks" }, .at = .below });
+ const joins = ctx.ties(s);
+ const block = struct {
+ fn walk(c: canim.Cursor, f: *anim.Frame) void {
+ graph.toEnd(c, f);
+ graph.leave(c, f);
+ }
+ /// The block the pc is in, by its first instruction's address.
+ fn here(c: canim.Cursor, f: *anim.Frame) u64 {
+ const i = c.moment(f);
+ const pc = c.rec.register(i, "rip");
+ const g = graph.read(f.arena, c.rec, i, pc) orelse return pc;
+ return g.nodes[g.nodeOf(pc) orelse return pc].start;
+ }
+ };
+
+ canim.establish(s, .{ ctx.clock, ctx.registers, ctx.stack, ctx.source, ctx.disasm, blocks, joins });
+ col.beat(s, .{ .say = "`sort` as its blocks: each loop a ring, the inner touching\nthe outer. `j > 0`, so `jle` goes on to the compare." });
+ block.walk(at, s);
+ // `on`: the drawing across both columns, the text in the corner the rings leave free.
+ col.beat(s, .{
+ .at = .on,
+ .say = "31 > 12: `setg` leaves 1,\nand `jne` takes the swap,\nthe first time it is reached.",
+ .where = .{ 104, 144 },
+ .level = .{ .block = block.here(at, s) },
+ });
+ block.walk(at, s);
+ block.walk(at, s);
+ // `above`: the text leads the eye in at the top.
+ col.beat(s, .{ .at = .above, .say = "The swap and `j--`; then the inner loop turns, back up to `j > 0`: its first turn." });
+ block.walk(at, s);
+ col.beat(s, .{ .at = .below, .say = "" });
+ col.close(s);
+}
diff --git a/anim/scenes/gallery.zig b/anim/scenes/gallery.zig
index 17d38ed..f6e4d9d 100644
--- a/anim/scenes/gallery.zig
+++ b/anim/scenes/gallery.zig
@@ -422,6 +422,8 @@ fn frame(s: *anim.Frame) void {
s.play(.{pages.fadeIn()}, .{ .seconds = 0 });
var at = canim.cursor(s, rec, rest);
+ // Its pictures are the frame as `test/gallery` keeps them: pwndbg's chains, offsets from rsp.
+ at.levels.annotation = .whole;
// Its way, the one step it takes: the registers that step does not change are folded.
at.journey(.line, rec.next(.line, rest));
const ctx = canim.context(s, at, .{ .split = canim.layout.split.beside, .quiet = true });
diff --git a/anim/scenes/heap.zig b/anim/scenes/heap.zig
index d42da12..6e521d0 100644
--- a/anim/scenes/heap.zig
+++ b/anim/scenes/heap.zig
@@ -423,7 +423,8 @@ fn frame(s: *anim.Frame) void {
// From main's first line, `push(7)`.
var at = canim.cursor(s, rec, rec.lineMoment(24, main.enter));
at.journey(.line, rec.lineMoment(30, main.enter));
- at.levels = .{ .idea = .data, .source_rows = 8 };
+ // The allocator's words are the story, by their addresses: pwndbg's chains (`annotation = .whole`).
+ at.levels = .{ .idea = .data, .source_rows = 8, .annotation = .whole };
const ctx = canim.context(s, at, .{ .split = canim.layout.split.subject });
// `head`, the program's global: where line 13 (`n->next = head;`) reads it, `[rip + X]`.
const head_at = globalOf(rec, lineIn(rec, "push", 0, 13));
diff --git a/anim/scenes/sqlite.zig b/anim/scenes/sqlite.zig
index 36630bd..dab127a 100644
--- a/anim/scenes/sqlite.zig
+++ b/anim/scenes/sqlite.zig
@@ -103,7 +103,8 @@ fn frame(s: *anim.Frame) void {
const start = stopAt(rec, "sqlite3_step+", first);
var at = canim.cursor(s, rec, start);
- at.levels = .{ .source_rows = 8 };
+ // Where a row's bytes go is the story, by their addresses: pwndbg's chains (`annotation = .whole`).
+ at.levels = .{ .source_rows = 8, .annotation = .whole };
at.journey(.moment, back);
// The lens is the subject: the backtrace, eleven rows, over the
// program column (where the kernel's side comes later), and over the
diff --git a/anim/scenes/zoom.zig b/anim/scenes/zoom.zig
index 426d3a3..8164b3b 100644
--- a/anim/scenes/zoom.zig
+++ b/anim/scenes/zoom.zig
@@ -36,8 +36,11 @@ fn frame(s: *anim.Frame) void {
const joins = ctx.ties(s);
canim.establish(s, .{ ctx.clock, ctx.registers, ctx.stack, ctx.backtrace, ctx.source, ctx.disasm, joins });
says.line(s, "A line of C is a handful of instructions.\nThis one calls `fib(n-1)`: follow it down.");
- // The CPU's level: an instruction a step. The argument is worked out in `rdi`.
+ // The CPU's level: an instruction a step. The argument is worked out in `rdi`,
+ // `n` carried into it from its word first (`carry`, for this beat).
+ at.levels.carry = .arrow;
at.walk(s, .moment, call.enter - 1);
+ at.levels.carry = .off;
says.line(s, "`call` writes eight bytes on the stack: the way back.");
// The stack holds still under the camera, set before it moves: six free
diff --git a/anim/src/column.zig b/anim/src/column.zig
new file mode 100644
index 0000000..32b3d4d
--- /dev/null
+++ b/anim/src/column.zig
@@ -0,0 +1,942 @@
+//! The column (design/README.md, "column (an experiment)"): a second way
+//! to compose a scene, beside the working frame. Two columns of 880: the
+//! panes a beat is about on the left (x 64, from y 84 to 1032, 12 apart, in
+//! the frame's order), the narration on the right (x 976), each `bubble`
+//! level with the row it speaks of; every pane the beat leaves out folded to
+//! its tag on the `shelf` (y 48), a register struck on its tag as on its row.
+//!
+//! It is an author's instrument: the scene says, beat by beat, which panes
+//! stand and with how many rows, where the text is placed (`beside`,
+//! `below` the working frame as a caption, `above` or `on` a wide drawing),
+//! what each bubble is level with and what its stem points at; what a beat
+//! leaves out is defaulted, never against what it wrote:
+//!
+//! const col = canim.column(s, ctx, .{ .lens = log, .titles = .{ .band = "system calls", .view = "its bytes" } });
+//! col.beat(s, .{
+//! .panes = &.{ .{ .source, 3 }, .{ .disasm, 11 }, .{ .stack, canim.column_rest } },
+//! .say = "The call pushes where to come back to, `main+45`, and goes down to open's stub.",
+//! .level = .{ .row = call }, // default: the pc's row at the beat
+//! });
+//!
+//! Between beats, in a rest (design/README.md, "Panes between beats"): the
+//! last bubble dims; the panes that leave fade (12 f) and fold to the shelf
+//! (24 f, `glide`); those that stay glide (24 f); those that come unfold
+//! (24 f) and fade in (12 f); an older bubble in the way glides out of it
+//! (24 f); the next arrives (18 f, rising 8), its stem drawing (12 f); the
+//! lead; the stem draws back as the step fires. A bubble never travels
+//! between placements: the last leaves (12 f), the frame changes (48 f), the
+//! next arrives.
+const std = @import("std");
+const sk = @import("sketch");
+const anim = @import("anim");
+const ui = @import("ui.zig");
+const ties = @import("ties.zig");
+const words = @import("words.zig");
+const cursors = @import("cursor.zig");
+const context = @import("context.zig");
+const Stage = @import("stage.zig").Stage;
+const theme = ui.theme;
+const time = theme.time;
+const Rect = ui.Rect;
+const Split = theme.layout.Split;
+const t = theme.color.text;
+const m = theme.metric.context;
+
+/// The panes, in the frame's order: the drawing, its view, the source, the
+/// disassembly (or the descent), the registers, the stack, the backtrace.
+pub const Part = enum { band, view, source, disasm, registers, stack, backtrace };
+const parts = std.enums.values(Part);
+/// A pane's rows: what the column has left (to 1032, the floor's foot).
+pub const rest: u32 = std.math.maxInt(u32);
+/// A pane that stands in a beat, and its rows (or `rest`).
+pub const Pane = struct { Part, u32 };
+pub const Placement = enum { beside, below, above, on };
+/// What a bubble is level with: the pc's row as the beat begins (the
+/// default), a row of the disassembly by its instruction's address, the head
+/// row over a function's window in a descent, the descent's floor (where the
+/// kernel's window opens), a graph's block by its address, or a height.
+pub const Level = union(enum) { pc, row: u64, head: []const u8, floor, block: u64, y: f32 };
+/// A bubble's stem: to what it is level with (the default), none (its level
+/// is the tie), or to another place.
+pub const Stem = union(enum) { level, none, to: Level };
+/// A folded pane's tag note, as the scene says it (`code` in backticks).
+pub const Note = struct { Part, []const u8 };
+
+pub const Beat = struct {
+ /// The panes that stand (`beside`); null: the beat's cause and effect,
+ /// the source (3 lines) and the disassembly (11 rows, a descent the rest)
+ /// and the pane the next step's effect lands in.
+ panes: ?[]const Pane = null,
+ say: []const u8,
+ /// Null: the column's (`Options.at`).
+ at: ?Placement = null,
+ level: Level = .pc,
+ stem: Stem = .level,
+ /// Folded panes' tag notes from this beat on (unless one is given: the
+ /// registers' is those the step changed, the source's its line, the
+ /// disassembly's the instruction at the pc).
+ notes: []const Note = &.{},
+ /// `on`: the bubble's top left in the frame (design units), in the drawing's free space.
+ where: ?[2]f32 = null,
+};
+
+pub const Options = struct {
+ /// The lens (one object drawing the band and its view: `Crossing`, a
+ /// graph), with its panes' titles for the shelf.
+ lens: ?anim.Obj = null,
+ titles: struct { band: []const u8 = "", view: []const u8 = "" } = .{},
+ /// The scene's placement where a beat names none.
+ at: Placement = .beside,
+};
+
+/// Frames, at 60 a second (design/README.md, "Panes between beats").
+const f = struct {
+ const dim = 18.0 / 60.0;
+ const rows = 12.0 / 60.0;
+ const fold = 24.0 / 60.0;
+ const glide = 24.0 / 60.0;
+ const relayout = theme.time.relayout;
+ const push = 24.0 / 60.0;
+ const arrive = 18.0 / 60.0;
+ const stem_after = 6.0 / 60.0;
+ const stem = 12.0 / 60.0;
+ const leave = 12.0 / 60.0;
+ const note = 12.0 / 60.0;
+};
+/// The bubble: Go 40 on 54, code in mono 35, 16 of padding, 812 wide at
+/// most, 40 characters a line; its first line's middle 40 under its top.
+const bubble = struct {
+ const x = 984;
+ const pad = 16;
+ const max_w = 812;
+ const chars = 40;
+ const pitch = theme.size.sans.caption_leading;
+ const first = 40;
+ const gap = 12;
+ const top = theme.canvas.stage.y;
+ const bottom = theme.canvas.stage.y + theme.canvas.stage.h;
+};
+/// A drawing's own size (the `blocks` lens's room, less its tag): `on` and `above` draw it larger.
+const lens_w = 896;
+const lens_h = 344;
+/// The panes' column: from 84 to 1032 (the floor's foot), 12 apart; the shelf at 48.
+const column_top = 84;
+const column_foot = 1032;
+const shelf_y = theme.canvas.stage.y;
+
+const Text = struct {
+ text: []const u8,
+ placement: Placement,
+ level: Level,
+ stem: ?Level,
+ where: ?[2]f32,
+ notes: [parts.len]?[]const u8,
+ /// 0 to 1: arriving (18 f), dimmed (18 f), leaving (12 f), its stem drawn,
+ /// the bubbles before it gliding out of its way (24 f), its notes in (12 f).
+ in: anim.Value,
+ dim: anim.Value,
+ out: anim.Value,
+ stem_v: anim.Value,
+ push: anim.Value,
+ notes_in: anim.Value,
+};
+
+pub const Column = struct {
+ cursor: cursors.Cursor,
+ stage: *Stage,
+ obj: anim.Obj = undefined,
+ objs: [parts.len]?anim.Obj,
+ titles: [parts.len][]const u8,
+ /// Whether each pane stands, as the scene's code has it so far.
+ standing: [parts.len]bool,
+ /// 1 on the shelf, 0 standing (the fold's travel between); 1 while the
+ /// column draws a pane's frame in its stead (folding, unfolding).
+ shelf: [parts.len]anim.Value,
+ ghost: [parts.len]anim.Value,
+ texts: [48]Text = undefined,
+ n: usize = 0,
+ placement: Placement = .below,
+ default: Placement,
+ /// The working frame's split, and the one the stage is going to.
+ working: Split,
+ split: Split,
+ /// The drawing across both columns (`on`, `above`): how much larger, and where its box goes.
+ zoom: f32 = 1,
+ read_by: f32 = 0,
+ said: bool = false,
+
+ /// One beat: the panes change (in a rest, never under a step), the text
+ /// arrives where the beat places it, the lead, then the scene's step.
+ pub fn beat(col: *Column, s: *anim.Frame, b: Beat) void {
+ const at = b.at orelse col.default;
+ const here = col.cursor.moment(s);
+ const rec = col.cursor.rec;
+ const level: Level = if (b.level == .pc) .{ .row = rec.register(here, "rip") } else b.level;
+ var notes: [parts.len]?[]const u8 = @splat(null);
+ for (b.notes) |note| notes[@intFromEnum(note[0])] = note[1];
+ // Which panes stand, and where.
+ var to: [parts.len]bool = @splat(false);
+ var split = col.split;
+ var zoom: f32 = 1;
+ switch (at) {
+ .below => {
+ for (parts) |p| to[@intFromEnum(p)] = col.objs[@intFromEnum(p)] != null;
+ split = col.working;
+ },
+ .beside => {
+ const panes = b.panes orelse col.defaults(s);
+ for (panes) |pane| to[@intFromEnum(pane[0])] = col.objs[@intFromEnum(pane[0])] != null;
+ split = col.columnSplit(panes);
+ },
+ .above, .on => {
+ to[@intFromEnum(Part.band)] = true;
+ for (b.panes orelse &.{}) |pane| to[@intFromEnum(pane[0])] = col.objs[@intFromEnum(pane[0])] != null;
+ // The drawing at its lens size across both columns, as large as the stage lets it.
+ const room: Rect = if (at == .on) .{ .x = 64, .y = column_top, .w = 1792, .h = 712 } else .{ .x = 64, .y = column_top + 132, .w = 1792, .h = bubble.bottom - column_top - 132 };
+ zoom = @min(room.w / lens_w, (room.h - m.tag) / lens_h);
+ split.band = room;
+ },
+ }
+ // Not before the text up has been read.
+ s.wait(@max(col.read_by - s.cursor, 0));
+ const kind = frameOf(at) != frameOf(col.placement);
+ const moves = !std.meta.eql(to, col.standing) or !sameBoxes(col.split, split, to) or zoom != col.zoom or kind;
+ const newest = col.newestStanding();
+ if (col.said) {
+ if (kind or at != .beside) {
+ // A text never travels between placements: what stands leaves (then a gap, as a caption's).
+ col.leaveAll(s);
+ if (!moves) s.wait(time.caption_gap);
+ } else if (moves) if (newest) |k| {
+ s.play(.{col.texts[k].dim.to(1)}, .{ .seconds = f.dim, .ease = anim.ease.linear });
+ };
+ }
+ if (moves) col.change(s, to, split, at, zoom, kind);
+ col.placement = at;
+ // A beat with nothing to say: the panes alone.
+ if (b.say.len == 0) return;
+ // The text.
+ const tx = col.add(s, b.say, at, level, switch (b.stem) {
+ .level => level,
+ .none => null,
+ .to => |l| l,
+ }, b.where, notes);
+ if (at == .beside) {
+ // Three stand at most: the oldest leaves first.
+ var standing: usize = 0;
+ var oldest: ?usize = null;
+ for (col.texts[0 .. col.n - 1], 0..) |x, k| if (x.placement == .beside and settled(s, x.out) < 1) {
+ standing += 1;
+ if (oldest == null) oldest = k;
+ };
+ if (standing >= 3) {
+ s.play(.{col.texts[oldest.?].out.to(1)}, .{ .seconds = f.leave, .ease = easeExit });
+ }
+ if (standing > 0) {
+ const start = s.cursor;
+ // A beat that keeps its panes: the last dims as the older ones make way.
+ if (!moves) if (newest) |k| {
+ s.play(.{col.texts[k].dim.to(1)}, .{ .seconds = f.dim, .ease = anim.ease.linear });
+ s.cursor = start;
+ };
+ s.play(.{tx.push.to(1)}, .{ .seconds = f.push, .ease = anim.ease.linear });
+ } else s.play(.{tx.push.to(1)}, .{ .seconds = 0 });
+ } else s.play(.{tx.push.to(1)}, .{ .seconds = 0 });
+ const arrives = s.cursor;
+ s.play(.{tx.notes_in.to(1)}, .{ .seconds = f.note, .ease = anim.ease.linear });
+ s.cursor = arrives;
+ s.play(.{tx.in.to(1)}, .{ .seconds = f.arrive, .ease = easeEnter });
+ if (tx.stem != null and at != .below and at != .above) {
+ const arrived = s.cursor;
+ s.cursor = arrives + f.stem_after;
+ s.play(.{tx.stem_v.to(1)}, .{ .seconds = f.stem, .ease = anim.ease.linear });
+ s.cursor = @max(s.cursor, arrived);
+ }
+ col.read_by = s.cursor + time.caption(@intCast(std.unicode.utf8CountCodepoints(b.say) catch b.say.len));
+ s.wait(if (col.said) time.caption_lead else time.caption_lead_first);
+ // The stem draws back as the step fires: the step's own ties have the gutter.
+ const fires = s.cursor;
+ s.play(.{tx.stem_v.to(2)}, .{ .seconds = f.stem, .ease = anim.ease.linear });
+ s.cursor = fires;
+ col.said = true;
+ }
+
+ /// The close: the last picture still, the last text read.
+ pub fn close(col: *Column, s: *anim.Frame) void {
+ s.wait(time.before_cut);
+ s.wait(@max(col.read_by - s.cursor, 0));
+ }
+
+ fn add(col: *Column, s: *anim.Frame, text: []const u8, at: Placement, level: Level, stem: ?Level, where: ?[2]f32, notes: [parts.len]?[]const u8) *Text {
+ const k = @min(col.n, col.texts.len - 1);
+ col.texts[k] = .{ .text = text, .placement = at, .level = level, .stem = stem, .where = where, .notes = notes, .in = s.value(0), .dim = s.value(0), .out = s.value(0), .stem_v = s.value(0), .push = s.value(0), .notes_in = s.value(0) };
+ col.n = k + 1;
+ return &col.texts[k];
+ }
+
+ fn newestStanding(col: *const Column) ?usize {
+ if (col.n == 0 or col.texts[col.n - 1].placement != .beside) return null;
+ return col.n - 1;
+ }
+
+ fn leaveAll(col: *Column, s: *anim.Frame) void {
+ var all: [48]anim.Animation = undefined;
+ var n: usize = 0;
+ for (col.texts[0..col.n]) |x| if (settled(s, x.out) < 1) {
+ all[n] = x.out.to(1);
+ n += 1;
+ };
+ if (n > 0) together(s, all[0..n], f.leave, easeExit);
+ }
+
+ /// The panes go from what stands to `to` at `split`: the leaving fade
+ /// and fold, the staying glide, the coming unfold and fade in; never a
+ /// fold and an unfold at once.
+ fn change(col: *Column, s: *anim.Frame, to: [parts.len]bool, split: Split, at: Placement, zoom: f32, kind: bool) void {
+ var leaving: [parts.len]bool = undefined;
+ var coming: [parts.len]bool = undefined;
+ // A pane that stays but changes its rows: its rows fade out and in round the
+ // glide (they are laid out for its height), its frame gliding as the column's.
+ var resized: [parts.len]bool = undefined;
+ var any_leaving = false;
+ var any_coming = false;
+ inline for (.{ "band", "view", "source", "disasm", "registers", "stack", "backtrace" }, 0..) |name, i| {
+ leaving[i] = col.standing[i] and !to[i];
+ coming[i] = !col.standing[i] and to[i];
+ resized[i] = col.standing[i] and to[i] and i > 1 and @field(col.split, name).h != @field(split, name).h;
+ any_leaving = any_leaving or leaving[i] or resized[i];
+ any_coming = any_coming or coming[i] or resized[i];
+ }
+ const band = @intFromEnum(Part.band);
+ const view = @intFromEnum(Part.view);
+ if (any_leaving) {
+ var anims: [3 * parts.len]anim.Animation = undefined;
+ var n: usize = 0;
+ for (parts, 0..) |_, i| if (leaving[i] or resized[i]) {
+ anims[n] = col.ghost[i].to(1);
+ n += 1;
+ };
+ for (parts, 0..) |_, i| if (resized[i]) if (col.objs[i]) |o| {
+ anims[n] = o.fadeOut();
+ n += 1;
+ };
+ for (parts, 0..) |_, i| if (leaving[i]) if (col.objs[i]) |o| {
+ // The lens is one object: it goes when neither of its panes stands (once).
+ const lens = i == band or i == view;
+ if (!lens or !(to[band] or to[view]) and !(i == view and leaving[band])) {
+ anims[n] = o.fadeOut();
+ n += 1;
+ }
+ if (i == band) {
+ anims[n] = col.stage.drawing.to(0);
+ n += 1;
+ }
+ };
+ if (n > 0) together(s, anims[0..n], f.rows, anim.ease.linear);
+ n = 0;
+ for (parts, 0..) |_, i| if (leaving[i]) {
+ anims[n] = col.shelf[i].to(1);
+ n += 1;
+ };
+ if (n > 0) {
+ together(s, anims[0..n], f.fold, anim.ease.linear);
+ n = 0;
+ for (parts, 0..) |_, i| if (leaving[i]) {
+ anims[n] = col.ghost[i].to(0);
+ n += 1;
+ };
+ together(s, anims[0..n], 0, anim.ease.linear);
+ }
+ }
+ // What stays glides (the frame changing between placements: 48 f); the
+ // folded keep their boxes, a folded band none, so that its view can stand alone.
+ var next = split;
+ inline for (.{ "band", "view", "source", "disasm", "registers", "stack", "backtrace" }, 0..) |name, i| if (!to[i]) {
+ @field(next, name) = @field(col.split, name);
+ if (i == band) next.band.h = 0;
+ };
+ const glides = !sameBoxes(col.split, next, col.standing) or zoom != col.zoom or kind;
+ const seconds: f32 = if (!glides) 0 else if (kind) f.relayout else f.glide;
+ const start = s.cursor;
+ // A pane going over to the other column goes down (or up) its own
+ // first, as the others make room, then across: never over another's rows.
+ var mid = next;
+ var crosses = false;
+ inline for (.{ "band", "view", "source", "disasm", "registers", "stack", "backtrace" }, 0..) |name, i| if (to[i] and col.standing[i] and @field(next, name).x != @field(col.split, name).x) {
+ @field(mid, name).x = @field(col.split, name).x;
+ crosses = true;
+ };
+ if (crosses) col.stage.glide(s, mid, seconds / 2);
+ col.stage.glide(s, next, if (crosses) seconds / 2 else seconds);
+ const end = s.cursor;
+ s.cursor = start;
+ s.play(.{col.stage.column.to(if (at == .beside) 1 else 0)}, .{ .seconds = seconds, .ease = anim.ease.linear });
+ // The drawing grows with its box, across both columns, its tag as it was.
+ s.cursor = start;
+ s.play(.{col.stage.zoom.to(zoom)}, .{ .seconds = seconds, .ease = easeGlide });
+ s.cursor = end;
+ col.split = next;
+ col.zoom = zoom;
+ if (any_coming) {
+ var anims: [3 * parts.len]anim.Animation = undefined;
+ var n: usize = 0;
+ for (parts, 0..) |_, i| if (coming[i]) {
+ anims[n] = col.ghost[i].to(1);
+ n += 1;
+ };
+ together(s, anims[0..n], 0, anim.ease.linear);
+ n = 0;
+ for (parts, 0..) |_, i| if (coming[i]) {
+ anims[n] = col.shelf[i].to(0);
+ n += 1;
+ };
+ if (n > 0) together(s, anims[0..n], f.fold, anim.ease.linear);
+ n = 0;
+ for (parts, 0..) |_, i| if (coming[i] or resized[i]) {
+ anims[n] = col.ghost[i].to(0);
+ n += 1;
+ };
+ for (parts, 0..) |_, i| if (resized[i]) if (col.objs[i]) |o| {
+ anims[n] = o.fadeIn();
+ n += 1;
+ };
+ for (parts, 0..) |_, i| if (coming[i]) if (col.objs[i]) |o| {
+ const lens = i == band or i == view;
+ if (!lens or !(col.standing[band] or col.standing[view]) and !(i == view and coming[band])) {
+ anims[n] = o.fadeIn();
+ n += 1;
+ }
+ if (i == band) {
+ anims[n] = col.stage.drawing.to(1);
+ n += 1;
+ }
+ };
+ if (n > 0) together(s, anims[0..n], f.rows, anim.ease.linear);
+ }
+ col.standing = to;
+ }
+
+ /// The beat's panes where the scene names none: its cause, the source
+ /// (three lines) over the disassembly; and where the next step's effect
+ /// lands, the registers or the stack.
+ fn defaults(col: *const Column, s: *anim.Frame) []const Pane {
+ const rec = col.cursor.rec;
+ const here = col.cursor.moment(s);
+ const next = rec.next(.moment, here);
+ const changed = rec.registersChanged(here, next) & ~cursors.quiet & ~(@as(u32, 1) << @intCast(context.index("rsp").?));
+ const pushes = rec.register(next, "rsp") != rec.register(here, "rsp") or rec.written(here, next).len > 0;
+ const out = s.arena.alloc(Pane, 3) catch @panic("column: out of memory");
+ out[0] = .{ .source, 3 };
+ if (changed != 0) {
+ out[1] = .{ .disasm, 11 };
+ out[2] = .{ .registers, if (col.stage.registers_rows > 0) @intFromFloat(col.stage.registers_rows) else @intCast(context.registerRows(context.every)) };
+ return out;
+ }
+ if (pushes) {
+ out[1] = .{ .disasm, 11 };
+ out[2] = .{ .stack, rest };
+ return out;
+ }
+ out[1] = .{ .disasm, rest };
+ return out[0..2];
+ }
+
+ /// The panes in one column, 12 apart from 84, in the frame's order.
+ fn columnSplit(col: *const Column, panes: []const Pane) Split {
+ var rows: [parts.len]?u32 = @splat(null);
+ for (panes) |p| rows[@intFromEnum(p[0])] = p[1];
+ var fixed: f32 = 0;
+ var n: f32 = 0;
+ for (rows) |r| if (r) |count| {
+ if (count != rest) fixed += theme.layout.panelH(@floatFromInt(count));
+ n += 1;
+ };
+ const left = column_foot - column_top - fixed - (n - 1) * theme.canvas.row_gap;
+ var out = col.split;
+ var y: f32 = column_top;
+ inline for (.{ "band", "view", "source", "disasm", "registers", "stack", "backtrace" }, 0..) |name, i| if (rows[i]) |count| {
+ const h = if (count == rest) theme.layout.panelH(@floatFromInt(theme.layout.rowsIn(left))) else theme.layout.panelH(@floatFromInt(count));
+ @field(out, name) = .{ .x = theme.layout.program.x, .y = y, .w = theme.layout.program.w, .h = h };
+ y += h + theme.canvas.row_gap;
+ };
+ return out;
+ }
+
+ pub fn draw(col: *const Column, fr: *sk.Frame, placed: anim.Placed) void {
+ const u: ui.Ui = .{ .f = fr, .at = placed };
+ col.drawShelf(u, placed);
+ col.drawTexts(u, placed);
+ }
+
+ fn box(col: *const Column, placed: anim.Placed, p: Part) Rect {
+ return col.stage.box(placed, switch (p) {
+ inline else => |tag| @field(@import("stage.zig").Part, @tagName(tag)),
+ });
+ }
+
+ /// The notes in force: the newest text's, crossfading from the one before.
+ fn notesNow(col: *const Column, placed: anim.Placed) struct { [parts.len]?[]const u8, [parts.len]?[]const u8, f32 } {
+ var k = col.n;
+ while (k > 0) {
+ k -= 1;
+ const p = placed.value(col.texts[k].notes_in);
+ if (p <= 0) continue;
+ const before: [parts.len]?[]const u8 = if (k > 0) col.texts[k - 1].notes else @splat(null);
+ return .{ before, col.texts[k].notes, p };
+ }
+ return .{ @splat(null), @splat(null), 1 };
+ }
+
+ /// The shelf: each folded pane's tag, side by side from 64 in the frame's
+ /// order; a pane folding or unfolding drawn as its frame on its way
+ /// between its box and its place there.
+ fn drawShelf(col: *const Column, u: ui.Ui, placed: anim.Placed) void {
+ const before, const after, const p = col.notesNow(placed);
+ var x: f32 = theme.layout.program.x;
+ for (parts, 0..) |part, i| {
+ if (col.objs[i] == null) continue;
+ const on = theme.ease(.glide, placed.value(col.shelf[i]));
+ // Its frame drawn in the pane's stead: crossfading with the pane at its box, alone on its way.
+ const ghost = placed.value(col.ghost[i]);
+ if (on <= 0 and ghost <= 0) continue;
+ const notes = [2]?[]const u8{ before[i], after[i] };
+ const w = std.math.lerp(tagWidth(col, u, placed, part, notes[0]), tagWidth(col, u, placed, part, notes[1]), p);
+ const slot: Rect = .{ .x = x, .y = shelf_y, .w = w, .h = m.tag };
+ const name = col.title(placed, part);
+ const b = col.box(placed, part);
+ const r: Rect = if (ghost > 0) .{ .x = std.math.lerp(b.x, slot.x, on), .y = std.math.lerp(b.y, slot.y, on), .w = std.math.lerp(b.w, slot.w, on), .h = std.math.lerp(b.h, slot.h, on) } else slot;
+ const v = u.moved(r.x, r.y).faded(if (on > 0) 1 else ghost);
+ _ = v.panel(r.w, r.h, name, .{});
+ // Its note comes as it lands on the shelf, and goes as it leaves.
+ const shows = std.math.clamp((on - 0.75) * 4, 0, 1);
+ if (shows > 0) {
+ const nx = 28 + v.width(.sans_medium, theme.size.sans.tag, name) + 12;
+ if (p < 1) _ = col.tagNote(v.faded(shows * (1 - p)), placed, part, nx, notes[0]);
+ _ = col.tagNote(v.faded(shows * p), placed, part, nx, notes[1]);
+ }
+ x += (w + theme.canvas.row_gap) * on;
+ }
+ }
+
+ fn title(col: *const Column, placed: anim.Placed, p: Part) []const u8 {
+ if (p != .source) return col.titles[@intFromEnum(p)];
+ const now = col.cursor.now(placed);
+ const rec = col.cursor.rec;
+ return rec.sources[rec.shown[now.marked()].src].name();
+ }
+
+ fn tagWidth(col: *const Column, u: ui.Ui, placed: anim.Placed, p: Part, note: ?[]const u8) f32 {
+ const title_w = u.width(.sans_medium, theme.size.sans.tag, col.title(placed, p));
+ const note_w = col.tagNote(u.faded(0), placed, p, 0, note);
+ return 28 + title_w + (if (note_w > 0) 12 + note_w else 0) + 12;
+ }
+
+ /// A folded pane's note from `x`: the scene's, or for the registers the
+ /// ones the last steps changed (the first with its value, struck on the
+ /// tag as on its row). How wide it is.
+ fn tagNote(col: *const Column, u: ui.Ui, placed: anim.Placed, p: Part, x: f32, note: ?[]const u8) f32 {
+ const base = m.tag - 6;
+ if (note) |text| return words.runs(u, x, base, text, .sans, theme.size.sans.micro, theme.size.mono.context, t.faint) - x;
+ if (p == .source or p == .disasm) {
+ // Where the mark is: the line, or the instruction and its address; changing with the advance.
+ const now = col.cursor.now(placed);
+ const turn = now.renaming();
+ const was = if (turn < 1) col.markNote(u.faded(1 - turn), now.marks[0], p, x) else 0;
+ const is = if (turn > 0) col.markNote(u.faded(turn), now.marks[1], p, x) else 0;
+ return std.math.lerp(was, is, turn);
+ }
+ if (p != .registers) return 0;
+ const now = col.cursor.now(placed);
+ // The step's registers come with their strike; the step before's go (6 f; at a run its 8 f).
+ const first = for (theme.metric.all_registers[0..16]) |name| {
+ const i = context.index(name).?;
+ if (now.registerAge(i) == 0) break ties.strikeDelay(now, i);
+ } else 0;
+ const turn: f32 = if (now.resting()) 1 else switch (now.plan.gait) {
+ .walk => std.math.clamp(now.since(.cpu, first) / time.strike.in, 0, 1),
+ .run => std.math.clamp(now.since(.cpu, 0) / time.run_ease, 0, 1),
+ .sprint => std.math.clamp(now.time / @max(now.plan.total, 1.0 / 60.0), 0, 1),
+ };
+ const was = if (turn < 1) col.registersNote(u.faded(1 - turn), now, x, 1) else 0;
+ const is = if (turn > 0) col.registersNote(u.faded(turn), now, x, 0) else 0;
+ return std.math.lerp(was, is, turn);
+ }
+
+ /// The source's line at `moment` (`line 12`), or the disassembly's instruction there (`jne 4011af`).
+ fn markNote(col: *const Column, u: ui.Ui, moment: u64, p: Part, x: f32) f32 {
+ const rec = col.cursor.rec;
+ const size = theme.size.mono.context;
+ const base = m.tag - 6;
+ var at = x;
+ if (p == .source) {
+ u.text(.mono, size, at, base, "line", t.dim);
+ at += u.width(.mono, size, "line") + ui.advance(size);
+ const n = u.print("{d}", .{rec.shown[moment].line});
+ u.text(.mono, size, at, base, n, t.primary);
+ return at + u.width(.mono, size, n) - x;
+ }
+ var buf: [256]u8 = undefined;
+ const pc = rec.register(moment, "rip");
+ const here = rec.instruction(moment, pc, &buf) orelse return 0;
+ const mn = (@import("disasm.zig").Insn{ .addr = pc, .len = here.len, .text = here.text }).mnemonic();
+ const word = u.print("{s}", .{mn});
+ u.text(.mono_bold, size, at, base, word, theme.color.code.keyword);
+ at += u.width(.mono, size, word) + ui.advance(size);
+ return u.address(at, base, pc, .{ .ink = ui.rgb(theme.color.region.code_) }) - x;
+ }
+
+ /// The registers the step `age` steps ago changed (three at most, in
+ /// pwndbg's order), the first with its value: struck on the tag as on its row.
+ fn registersNote(col: *const Column, u: ui.Ui, now: cursors.Now, x: f32, age: u64) f32 {
+ const base = m.tag - 6;
+ const rec = col.cursor.rec;
+ const size = theme.size.mono.context;
+ var at = x;
+ var shown: usize = 0;
+ for (theme.metric.all_registers[0..16]) |name| {
+ const i = context.index(name).?;
+ if (now.registerAgeFrom(i, age) != age or shown == 3) continue;
+ if (shown > 0) at += ui.advance(size);
+ u.text(.mono, size, at, base, name, if (shown == 0) t.dim else t.primary);
+ at += u.width(.mono, size, name);
+ if (shown == 0) {
+ const v = rec.register(now.stops[age], name);
+ at += ui.advance(size);
+ const digits = if (v < 0x10000) u.print("{d}", .{v}) else u.print("{x}", .{v});
+ const dw = u.width(.mono, size, digits);
+ const heat = if (age == 0) now.register(i, ties.strikeDelay(now, i)) else now.heat(1, null, 0);
+ const ink = u.written(.{ .x = at, .y = 0, .w = dw, .h = m.tag }, heat) orelse ui.Ink{};
+ u.text(ink.face, size, at, base, digits, ink.ink);
+ at += dw;
+ }
+ shown += 1;
+ }
+ return at - x;
+ }
+
+ fn drawTexts(col: *const Column, u: ui.Ui, placed: anim.Placed) void {
+ const inv = placed.xf.invert();
+ const now = col.cursor.now(placed);
+ // The newest text arriving (or arrived), and the beside ones standing.
+ var newest: ?usize = null;
+ for (col.texts[0..col.n], 0..) |x, k| if (placed.value(x.push) > 0 or placed.value(x.in) > 0) {
+ newest = k;
+ };
+ // While panes fold, unfold or are laid out anew, what has been said stays where it is, from then on.
+ for (col.ghost) |g| if (placed.value(g) > 0) {
+ for (col.texts[0..col.n], 0..) |_, k| if (last_level[k] != null) {
+ latched[k] = true;
+ };
+ break;
+ };
+ var with: [48]f32 = undefined;
+ var without: [48]f32 = undefined;
+ col.layout(placed, inv, newest, true, &with);
+ col.layout(placed, inv, newest, false, &without);
+ const push = if (newest) |k| theme.ease(.glide, placed.value(col.texts[k].push)) else 1;
+ for (col.texts[0..col.n], 0..) |x, k| {
+ const in = placed.value(x.in);
+ const out = placed.value(x.out);
+ if (in <= 0 or out >= 1) continue;
+ const rise = (1 - theme.ease(.enter, in)) * time.caption_rise;
+ var shows = in * (1 - out);
+ switch (x.placement) {
+ .below => {
+ const v = u.faded(shows).moved(0, rise);
+ var lines = std.mem.splitScalar(u8, x.text, '\n');
+ const two = std.mem.indexOfScalar(u8, x.text, '\n') != null;
+ var n: usize = if (two) 1 else 0;
+ while (lines.next()) |line| : (n += 1) {
+ if (n > 2) break;
+ _ = words.runs(v, theme.canvas.margin_x, theme.canvas.caption_baseline[n], line, .sans, theme.size.sans.caption, theme.size.mono.value, t.primary);
+ }
+ },
+ .above => {
+ const lines = wrap(u, x.text, 80);
+ const v = u.faded(shows).moved(0, rise);
+ for (lines, 0..) |line, n| _ = words.runs(v, theme.canvas.margin_x, column_top + bubble.first + @as(f32, @floatFromInt(n)) * bubble.pitch + 14, line, .sans, theme.size.sans.caption, theme.size.mono.value, t.primary);
+ },
+ .on => {
+ const where = x.where orelse .{ 104, 144 };
+ col.paper(u.faded(shows).moved(0, rise), x, where[0], where[1], 0);
+ if (x.stem) |target| col.stemOn(u, inv, x, where, target, placed);
+ },
+ .beside => {
+ // At a run only the newest stands.
+ if (newest != k) shows *= 1 - now.hurried;
+ const top = if (newest == k) with[k] else std.math.lerp(without[k], with[k], push);
+ col.paper(u.faded(shows).moved(0, rise), x, bubble.x, top, placed.value(x.dim));
+ if (x.stem) |target| col.stemBeside(u, inv, x, top, target, placed);
+ },
+ }
+ }
+ }
+
+ /// A bubble's text from `x, top`: on `raised` paper and primary, the
+ /// paper going and the ink dimming as it becomes the account (`dim`).
+ fn paper(_: *const Column, u: ui.Ui, x: Text, left: f32, top: f32, dim: f32) void {
+ const lines = wrap(u, x.text, bubble.chars);
+ const h = bubble.first * 2 + @as(f32, @floatFromInt(lines.len - 1)) * bubble.pitch;
+ if (dim < 1) u.faded(1 - dim).fill(.{ .x = left, .y = top, .w = paperWidth(u, x), .h = h }, theme.color.raised);
+ const ink = ui.mix(t.primary, t.dim, dim);
+ for (lines, 0..) |line, n| _ = words.runs(u, left + bubble.pad, top + bubble.first + @as(f32, @floatFromInt(n)) * bubble.pitch + 14, line, .sans, theme.size.sans.caption, theme.size.mono.value, ink);
+ }
+
+ /// Each beside text's top, the newest's or not: level with what it
+ /// speaks of where it can be; an older one in a newer one's way above it,
+ /// or under it where there is no room above.
+ fn layout(col: *const Column, placed: anim.Placed, inv: sk.math.Affine, newest: ?usize, with_newest: bool, out: *[48]f32) void {
+ var taken: [48][2]f32 = undefined;
+ var n_taken: usize = 0;
+ var k = col.n;
+ while (k > 0) {
+ k -= 1;
+ const x = col.texts[k];
+ out[k] = 0;
+ if (x.placement != .beside) continue;
+ if (!with_newest and newest == k) continue;
+ if (placed.value(x.out) >= 1) continue;
+ // Only what has arrived.
+ if (newest == null or k > newest.?) continue;
+ const h = height(x);
+ var top = std.math.clamp(levelY(placed, inv, k, x.level) - bubble.first, bubble.top, bubble.bottom - h);
+ // Above what is in its way, while there is room; else under it.
+ var tries: usize = 0;
+ while (tries < n_taken + 1) : (tries += 1) {
+ const hit = for (taken[0..n_taken]) |r| {
+ if (top < r[1] + bubble.gap and top + h + bubble.gap > r[0]) break r;
+ } else null;
+ const r = hit orelse break;
+ top = r[0] - bubble.gap - h;
+ }
+ if (top < bubble.top) {
+ var lowest: f32 = bubble.top;
+ for (taken[0..n_taken]) |r| lowest = @max(lowest, r[1] + bubble.gap);
+ top = lowest;
+ }
+ out[k] = top;
+ taken[n_taken] = .{ top, top + h };
+ n_taken += 1;
+ }
+ }
+
+ /// The stem of a beside text: from its first line across the gutter onto
+ /// the pane's right rule level with the row, a head 7 by 8 on the rule.
+ fn stemBeside(_: *const Column, u: ui.Ui, inv: sk.math.Affine, x: Text, top: f32, target: Level, placed: anim.Placed) void {
+ const v = placed.value(x.stem_v);
+ if (v <= 0 or v >= 2) return;
+ const r = find(inv, target) orelse return;
+ const y0 = top + bubble.first;
+ const y1 = (r[1] + r[3]) / 2;
+ const lane = theme.metric.tie.link_lane + 6;
+ var buf = [4]ui.Vec{ .{ bubble.x, y0 }, .{ lane, y0 }, .{ lane, y1 }, .{ r[2] + 1, y1 } };
+ const points: []const ui.Vec = if (@abs(y0 - y1) < 1) &.{ .{ bubble.x, y1 }, .{ r[2] + 1, y1 } } else buf[0..];
+ u.route(points, t.dim, .{ .width = theme.stroke.rule, .head = .{ 7, 8 }, .progress = cursors.standard(@min(v, 1)), .from = cursors.standard(@max(v - 1, 0)), .radius = 6 });
+ }
+
+ /// The stem of a text `on` a drawing: round the drawing's outside, along
+ /// its top lane (under its tag), down onto the part it speaks of.
+ fn stemOn(col: *const Column, u: ui.Ui, inv: sk.math.Affine, x: Text, where: [2]f32, target: Level, placed: anim.Placed) void {
+ const v = placed.value(x.stem_v);
+ if (v <= 0 or v >= 2) return;
+ const r = find(inv, target) orelse return;
+ const w = paperWidth(u, x);
+ const lane = column_top + m.tag + 10;
+ const from_x = where[0] + w - 32;
+ const to_x = r[2] - 24;
+ _ = col;
+ u.route(&.{ .{ from_x, where[1] }, .{ from_x, lane }, .{ to_x, lane }, .{ to_x, r[1] - 1 } }, t.dim, .{ .width = theme.stroke.rule, .head = .{ 7, 8 }, .progress = cursors.standard(@min(v, 1)), .from = cursors.standard(@max(v - 1, 0)), .radius = 8 });
+ }
+};
+
+/// `all` played together from the cursor, which then moves past them.
+fn together(s: *anim.Frame, all: []const anim.Animation, seconds: f32, ease: anim.Ease) void {
+ const start = s.cursor;
+ for (all) |a| {
+ s.cursor = start;
+ s.play(.{a}, .{ .seconds = seconds, .ease = ease });
+ }
+ s.cursor = start + seconds;
+}
+
+fn easeExit(x: f32) f32 {
+ return theme.ease(.exit, x);
+}
+fn easeEnter(x: f32) f32 {
+ return theme.ease(.enter, x);
+}
+fn easeGlide(x: f32) f32 {
+ return theme.ease(.glide, x);
+}
+
+fn frameOf(p: Placement) enum { working, column, wide } {
+ return switch (p) {
+ .below => .working,
+ .beside => .column,
+ .above, .on => .wide,
+ };
+}
+
+/// Whether the panes that stand in both have the same boxes.
+fn sameBoxes(a: Split, b: Split, standing: [parts.len]bool) bool {
+ inline for (.{ "band", "view", "source", "disasm", "registers", "stack", "backtrace" }, 0..) |name, i| {
+ if (standing[i] and !std.meta.eql(@field(a, name), @field(b, name))) return false;
+ }
+ return true;
+}
+
+fn settled(s: *const anim.Frame, v: anim.Value) f32 {
+ return s.values.items[@backingInt(v)].settled;
+}
+
+/// Where a level's place is this frame, in the frame's units: left, top, right, bottom.
+fn find(inv: sk.math.Affine, level: Level) ?[4]f32 {
+ const place: ties.Place = switch (level) {
+ .pc => .pc,
+ .row => |a| .{ .row = a },
+ .head => |name| .{ .row = @import("descent.zig").headKey(name) },
+ .floor => .floor,
+ .block => |a| .{ .block = a },
+ .y => |y| return .{ 0, y - m.row / 2, theme.layout.program.x + theme.layout.program.w, y + m.row / 2 },
+ };
+ const r = ties.find(place) orelse return null;
+ const a = inv.apply(.{ r[0], r[1] });
+ const b = inv.apply(.{ r[2], r[3] });
+ return .{ a[0], a[1], b[0], b[1] };
+}
+
+/// The middle of the row a text `k` is level with; where the row has gone
+/// (a window closed round it), where it last was.
+/// shortcut: remembered by the process as frames are drawn in order (an export, a player playing); after a seek a text whose row is gone sits at 400 until it is seen again.
+var last_level: [48]?f32 = @splat(null);
+/// Once its row has gone from a pane that is drawn, or the panes have changed, a text stays where it is (`latched`).
+var latched: [48]bool = @splat(false);
+fn levelY(_: anim.Placed, inv: sk.math.Affine, k: usize, level: Level) f32 {
+ if (!latched[k]) if (find(inv, level)) |r| {
+ const y = (r[1] + r[3]) / 2;
+ last_level[k] = y;
+ return y;
+ };
+ // A row of the disassembly, gone while the pane is there (its pc drawn): the text stays.
+ if (last_level[k] != null and (level == .row or level == .head or level == .floor) and ties.find(.pc) != null) latched[k] = true;
+ return last_level[k] orelse 400;
+}
+
+fn height(x: Text) f32 {
+ const n = lineCount(x.text, bubble.chars);
+ return bubble.first * 2 + @as(f32, @floatFromInt(n - 1)) * bubble.pitch;
+}
+
+fn paperWidth(u: ui.Ui, x: Text) f32 {
+ var w: f32 = 0;
+ for (wrap(u, x.text, bubble.chars)) |line| w = @max(w, runsWidth(u, line));
+ return @min(w + 2 * bubble.pad, bubble.max_w);
+}
+
+/// How wide `words.runs` sets `text`.
+fn runsWidth(u: ui.Ui, text: []const u8) f32 {
+ var w: f32 = 0;
+ var parts_ = std.mem.splitScalar(u8, text, '`');
+ var code = false;
+ while (parts_.next()) |part| : (code = !code) w += if (code) u.width(.mono, theme.size.mono.value, part) else u.width(.sans, theme.size.sans.caption, part);
+ return w;
+}
+
+/// `text` in lines of at most `chars` characters (a newline breaks one too),
+/// broken at spaces; a code span broken across two lines is closed and opened again.
+fn wrap(u: ui.Ui, text: []const u8, chars: usize) []const []const u8 {
+ var lines: std.ArrayList([]const u8) = .empty;
+ var paragraphs = std.mem.splitScalar(u8, text, '\n');
+ while (paragraphs.next()) |para| {
+ var line: std.ArrayList(u8) = .empty;
+ var count: usize = 0;
+ var code = false;
+ var ws = std.mem.splitScalar(u8, para, ' ');
+ while (ws.next()) |word| {
+ const n = visible(word);
+ if (count > 0 and count + 1 + n > chars) {
+ if (code) line.append(u.f.scratch, '`') catch {};
+ lines.append(u.f.scratch, line.items) catch {};
+ line = .empty;
+ count = 0;
+ if (code) line.append(u.f.scratch, '`') catch {};
+ }
+ if (count > 0) line.append(u.f.scratch, ' ') catch {};
+ line.appendSlice(u.f.scratch, word) catch {};
+ count += n + @intFromBool(count > 0);
+ for (word) |ch| if (ch == '`') {
+ code = !code;
+ };
+ }
+ lines.append(u.f.scratch, line.items) catch {};
+ }
+ return lines.items;
+}
+
+/// How many lines `wrap` makes of `text`.
+fn lineCount(text: []const u8, chars: usize) usize {
+ var n: usize = 0;
+ var paragraphs = std.mem.splitScalar(u8, text, '\n');
+ while (paragraphs.next()) |para| {
+ var count: usize = 0;
+ n += 1;
+ var ws = std.mem.splitScalar(u8, para, ' ');
+ while (ws.next()) |word| {
+ const w = visible(word);
+ if (count > 0 and count + 1 + w > chars) {
+ n += 1;
+ count = 0;
+ }
+ count += w + @intFromBool(count > 0);
+ }
+ }
+ return n;
+}
+
+/// Its characters as shown: backticks are not.
+fn visible(word: []const u8) usize {
+ const n = std.unicode.utf8CountCodepoints(word) catch word.len;
+ return n - std.mem.count(u8, word, "`");
+}
+
+/// The column over context `ctx`: add it after the panes and the lens and
+/// before the ties (`ctx.ties`); the scene opens in the working frame, its
+/// first beat usually `below` (the opening establishes everything).
+pub fn column(s: *anim.Frame, ctx: anytype, options: Options) *Column {
+ const st = ctx.stage;
+ const working = st.last();
+ var objs: [parts.len]?anim.Obj = .{ options.lens, options.lens, ctx.source, ctx.disasm, ctx.registers, ctx.stack, ctx.backtrace };
+ if (working.band.h <= 0) objs[0] = null;
+ if (working.view.h <= 0) objs[1] = null;
+ if (working.backtrace.h <= 0) objs[6] = null;
+ var shelf: [parts.len]anim.Value = undefined;
+ var ghost: [parts.len]anim.Value = undefined;
+ for (&shelf, &ghost) |*a, *b| {
+ a.* = s.value(0);
+ b.* = s.value(0);
+ }
+ var standing: [parts.len]bool = undefined;
+ for (objs, &standing) |o, *is| is.* = o != null;
+ const col = s.new(Column{
+ .cursor = ctx.cursor,
+ .stage = st,
+ .objs = objs,
+ .titles = .{ options.titles.band, options.titles.view, "", "disassembly", "registers", "stack", "backtrace" },
+ .standing = standing,
+ .shelf = shelf,
+ .ghost = ghost,
+ .default = options.at,
+ .working = working,
+ .split = working,
+ });
+ col.obj = s.custom(col, .{ .x = -640, .y = -360, .scale = ui.scale });
+ s.play(.{col.obj.fadeIn()}, .{ .seconds = 0 });
+ return col;
+}
+
+test "a bubble's lines: at most forty characters, a code span kept whole on each" {
+ const n = lineCount("main puts open's arguments where the convention says: \"note\" in rdi, 0 (O_RDONLY) in rsi.", 40);
+ try std.testing.expectEqual(@as(usize, 3), n);
+ try std.testing.expectEqual(@as(usize, 2), lineCount("`syscall` crosses down.\nThe kernel answers.", 40));
+ try std.testing.expectEqual(@as(usize, 4), visible("`rdi`,"));
+}
diff --git a/anim/src/context.zig b/anim/src/context.zig
index d4bc94d..16278e3 100644
--- a/anim/src/context.zig
+++ b/anim/src/context.zig
@@ -348,6 +348,42 @@ pub fn frames(rec: *const Recording, i: u64, out: []Frame) []Frame {
return out[0..found.len];
}
+/// The register the newest frame's code addresses its words by
+/// (design/README.md, `slot`): its call frame information's CFA register,
+/// rbp in a body that keeps a frame pointer; rsp at its entry, in its
+/// prologue before `mov rbp, rsp`, after its `pop rbp` or `leave`, in a
+/// function that keeps none, and where the recording has no such rows.
+pub const Base = struct {
+ rbp: bool = false,
+
+ pub fn name(b: Base) []const u8 {
+ return if (b.rbp) "rbp" else "rsp";
+ }
+
+ pub fn value(b: Base, regs: zt.Regs) u64 {
+ return if (b.rbp) regs.rbp else regs.rsp;
+ }
+};
+
+pub fn frameBase(rec: *const Recording, i: u64, regs: zt.Regs) Base {
+ const func = zt.telescope.function(rec.moment(i), regs.rip) orelse return .{};
+ const size = @sizeOf(zt.Symbols.Row);
+ var row: zt.Symbols.Row = .{};
+ var o: usize = 0;
+ while (o + size <= func.rows.len) : (o += size) {
+ const r = std.mem.bytesToValue(zt.Symbols.Row, func.rows[o..][0..size]);
+ if (r.offset > regs.rip -% func.start) break;
+ row = r;
+ }
+ // DWARF's 6 is rbp; and rbp must be in the frame (under its return address).
+ return .{ .rbp = row.cfa_reg == 6 and regs.rbp >= regs.rsp };
+}
+
+/// `d` bytes from base `name` (`rbp-18`, `rbp+8`, `rbp`), as the stack's tag writes a range.
+fn fromBase(u: ui.Ui, name: []const u8, d: i64) []const u8 {
+ return if (d == 0) name else if (d > 0) u.print("{s}+{x}", .{ name, @as(u64, @intCast(d)) }) else u.print("{s}-{x}", .{ name, @as(u64, @intCast(-d)) });
+}
+
/// A frame's span on the stack: its function's name, and as a call its
/// argument where it takes one (`fib(4)`): the digits on its node.
fn spanName(u: ui.Ui, rec: *const Recording, open: []const Recording.Call, i: usize, pc: u64) []const u8 {
@@ -439,6 +475,8 @@ pub const Stack = struct {
const hold = placed.value(k.stage.hold);
const held = hold >= 0;
const held_at: u64 = if (held) rec.register(@intFromFloat(hold), "rsp") -% 8 * @as(u64, @intFromFloat(placed.value(k.stage.hold_free))) else 0;
+ // `tied`: two `free` words over rsp, the window's headroom; offsets from the frame's base; rsp's and rbp's moves as pins travelling.
+ const tied = now.annotation == .tied;
var window = if (held) [2]u64{ held_at, held_at } else if (k.above != 0) [2]u64{ is.rsp -% @as(u64, @bitCast(@as(i64, 8 * k.above))), was.rsp -% @as(u64, @bitCast(@as(i64, 8 * k.above))) } else [2]u64{ windowAt(now, is, slots, 0), windowAt(now, was, slots, 1) };
// A window that goes farther than its own height (a continue to a
// stop deeper or shallower than a call is) does not scroll: the old
@@ -459,6 +497,11 @@ pub const Stack = struct {
// Going to the hold and coming from it, the rows scroll: the
// remaining way, in rows, from where the window would be.
const natural = windowAt(now, is, slots, 0);
+ // Under `tied`, the word the step touches, and the window over it before the touch goes there.
+ const touch: ?cursors.Touched = if (tied and !now.resting()) cursors.stackTouch(rec, now.stops[1], now.stops[0]) else null;
+ const touch_window = if (touch) |tt| if (!held and k.above == 0 and !jumped and (tt.addr < window[1] or tt.addr >= window[1] + 8 * @as(u64, slots))) windowOver(was, slots, tt.addr) else window[1] else window[1];
+ // The frame's base, before the step and after it (`whole`: rsp).
+ const bases = [2]Base{ if (tied) frameBase(rec, now.stops[1], was) else .{}, if (tied) frameBase(rec, now.stops[0], is) else .{} };
const hold_scroll: f32 = if (held) @as(f32, @floatFromInt(@as(i64, @bitCast(held_at -% natural)))) / 8 * (1 - cursors.glide(placed.value(k.stage.hold_in))) else 0;
// From rsp, or the range shown when the window is elsewhere: in
// bytes from rsp, as the catalogue writes it (`rsp+20 to rsp+48`).
@@ -471,10 +514,18 @@ pub const Stack = struct {
const words = if (slots < numbers.len) numbers[slots] else u.print("{d}", .{slots});
// The first word shown and the last.
// The range before memory lands and after: one that changes crossfades (12 f), as a role does.
- const recast = if (now.resting()) 1 else std.math.clamp(since_memory / time.quick, 0, 1);
+ // Under `tied` a walked step's labels change as its window follows, or its last pin lands (`Now.restacked`).
+ const recast = if (now.resting()) 1 else if (tied and now.walking()) std.math.clamp((now.time - now.restacked()) / time.quick, 0, 1) else std.math.clamp(since_memory / time.quick, 0, 1);
const ranges = [2]i64{ @bitCast(ways[1] -% was.rsp), @bitCast(ways[0] -% is.rsp) };
var notes: [2][]const u8 = undefined;
- for (ranges, &notes) |r_, *note| {
+ for (ranges, &notes, [2]zt.Regs{ was, is }, bases, 0..) |r_, *note, regs, base, side| {
+ if (tied) {
+ // From the base: `fourteen words` where the window is at its headroom, else the range.
+ const from: i64 = @bitCast(ways[1 - side] -% base.value(regs));
+ const range = if (ways[1 - side] == regs.rsp -% 16 and k.above == 0) u.print("{s} words", .{words}) else u.print("{s} to {s}", .{ fromBase(u, base.name(), from), fromBase(u, base.name(), from + 8 * (@as(i64, @intCast(slots)) - 1)) });
+ note.* = u.print("{s} \u{00b7} offsets from {s} \u{00b7} the frames they belong to", .{ range, base.name() });
+ continue;
+ }
const range = if (r_ == 0) u.print("{s} words from rsp", .{words}) else u.print("{s} to {s}", .{ offset(u, r_), offset(u, r_ + 8 * (@as(i64, @intCast(slots)) - 1)) });
note.* = u.print("{s} \u{00b7} the frames they belong to", .{range});
}
@@ -484,9 +535,38 @@ pub const Stack = struct {
u.faded(1 - recast).tagNote(box.w, notes[0]);
u.faded(recast).tagNote(box.w, notes[1]);
}
- const p = cursors.glide(now.moving(.memory, 0, time.move));
+ var p = cursors.glide(now.moving(.memory, 0, time.move));
const moved = @as(f32, @floatFromInt(@as(i64, @bitCast(window[0] -% window[1])))) / 8;
- const slide: f32 = (if (jumped) 0 else moved * (1 - p)) + hold_scroll;
+ var slide: f32 = (if (jumped) 0 else moved * (1 - p)) + hold_scroll;
+ // Under `tied`, walked (design/README.md, `stack`): the rows hold while the pin travels;
+ // a word the step touches outside the window is scrolled to before the touch goes there;
+ // where the climb is longer than the room over the pin, the rows slide under it (the pin on
+ // the top row); once it has landed the window follows (`Plan.follow`).
+ const pin_sp = now.pinGone(0);
+ if (tied and !jumped and !held and k.above == 0 and now.walking() and (now.plan.follow >= 0 or now.plan.touch >= 0 or pin_sp != null)) {
+ const rows_at = struct {
+ fn at(addr: u64, base: u64) f32 {
+ return @as(f32, @floatFromInt(@as(i64, @bitCast(addr -% base)))) / 8;
+ }
+ /// The window's top (rows from `window[0]`) with the pin at `pin`: never past it.
+ fn keep(d: f32, pin: f32, n: usize) f32 {
+ return std.math.clamp(d, pin - @as(f32, @floatFromInt(n - 1)), pin);
+ }
+ };
+ var d = rows_at.at(window[1], window[0]);
+ if (touch_window != window[1]) d = std.math.lerp(d, rows_at.at(touch_window, window[0]), cursors.glide(std.math.clamp(now.time / @max(now.plan.touch, time.fire), 0, 1)));
+ const pins_at = [2]f32{ rows_at.at(was.rsp, window[0]), rows_at.at(is.rsp, window[0]) };
+ const landed_d = rows_at.keep(rows_at.at(touch_window, window[0]), pins_at[1], slots);
+ if (pin_sp) |g| d = rows_at.keep(d, std.math.lerp(pins_at[0], pins_at[1], g), slots);
+ if (now.plan.follow >= 0) {
+ const span = @min(time.tied.follow + 2.0 / 60.0 * @max(@abs(landed_d) - 1, 0), time.tied.follow_most);
+ const q = cursors.glide(std.math.clamp((now.time - now.plan.follow) / span, 0, 1));
+ if (now.time >= now.plan.follow) d = std.math.lerp(landed_d, 0, q);
+ } else d = std.math.lerp(d, 0, p);
+ slide = -d;
+ // The strip's window goes as the pane's does.
+ p = if (moved != 0) std.math.clamp(1 - slide / moved, 0, 1) else 1;
+ }
const top = body.y + m.pad;
clipBody(u, box);
defer u.unclip();
@@ -532,11 +612,13 @@ pub const Stack = struct {
const calls_is = rec.stack(u.f.scratch, now.stops[0]);
var spans: [16]Span = undefined;
var n_spans: usize = 0;
+ // Under `tied` the spans ride rsp's pin: the newest stretches or shrinks with it.
+ const p_span = pin_sp orelse p;
for (chain, 0..) |frame, i| {
const old_frame = if (i < old_chain.len) old_chain[i] else frame;
- const first = std.math.lerp(rows_of(old_frame.lo, window[0]), rows_of(frame.lo, window[0]), p) + slide;
+ const first = std.math.lerp(rows_of(old_frame.lo, window[0]), rows_of(frame.lo, window[0]), p_span) + slide;
if (first >= @as(f32, @floatFromInt(slots))) break;
- const last = if (frame.hi) |hi| std.math.lerp(if (old_frame.hi) |oh| rows_of(oh, window[0]) else rows_of(hi, window[0]), rows_of(hi, window[0]), p) + slide else std.math.inf(f32);
+ const last = if (frame.hi) |hi| std.math.lerp(if (old_frame.hi) |oh| rows_of(oh, window[0]) else rows_of(hi, window[0]), rows_of(hi, window[0]), p_span) + slide else std.math.inf(f32);
if (last < 0) continue;
const open = last >= @as(f32, @floatFromInt(slots));
const y1 = top + (@min(last, @as(f32, @floatFromInt(slots)) - 1) + 1) * m.row;
@@ -558,6 +640,8 @@ pub const Stack = struct {
const goes = struct {
fn of(n: cursors.Now, a: zt.Regs, b: zt.Regs, name: []const u8) f32 {
if (n.resting()) return 1;
+ // `tied`: as its plan travels it (`Now.pinGone`).
+ if (n.pinGone(if (std.mem.eql(u8, name, "rsp")) 0 else 1)) |g| return g;
const pin = time.pin;
const rows_far: f32 = @floatFromInt(@abs(@as(i64, @bitCast((b.named(name) orelse 0) -% (a.named(name) orelse 0)))) / 8);
const takes = @min(pin.row + pin.step_per_row * @max(rows_far - 1, 0), pin.row_max);
@@ -592,19 +676,42 @@ pub const Stack = struct {
// Who points here: a pin in the lane, landing with its link.
const names = pins(u, now, is, was, addr, travel);
var marks: rows.Marks = .{ .lead = lead, .first = now.writtenWatched(addr, 8, .memory, 0, watched_from, watched_to) };
- if (watched_from == 0 and watched_to > 0 and now.wasRead(addr, 8) and now.writeAge(addr, 8) != 0) {
+ // Under `tied` the word a `pop`, a `ret` or a `leave` reads is read too (the recordings say no read there).
+ const touched_here = if (touch) |tt| tt.addr & ~@as(u64, 7) == addr else false;
+ if (watched_from == 0 and watched_to > 0 and (now.wasRead(addr, 8) or (touched_here and !touch.?.write)) and now.writeAge(addr, 8) != 0) {
marks.read = 0;
marks.read_shows = now.reading(.memory, 0);
}
- const below_rsp: i64 = @bitCast(addr -% if (held) rsp_shown else is.rsp);
+ // A word stored with the value it held (a `push rbp` over the old saved rbp): armed, and nothing struck.
+ if (touched_here and touch.?.write and now.walking() and now.writeAge(addr, 8) != 0) {
+ const s_at = now.plan.at[1];
+ marks.first.arm = std.math.clamp((now.time - (s_at - time.strike.arm)) / time.stagger, 0, 1) * (1 - std.math.clamp((now.time - s_at) / time.quick, 0, 1));
+ }
+ const below_rsp: i64 = if (tied) @bitCast(addr -% bases[1].value(is)) else @bitCast(addr -% if (held) rsp_shown else is.rsp);
map.row(.stack, addr, u, .{ .x = 0, .y = y, .w = box.w, .h = m.row });
// `free`: above rsp, not yet reached: its address at 60%, its word faint.
// A free word rsp reaches (a push, `sub rsp`) becomes a slot as memory strikes (12 f), never in a frame.
- const free_was = held and addr < was.rsp;
- const free_is = held and addr < is.rsp;
- const slot_shows: f32 = if (free_was == free_is or now.resting()) @as(f32, if (free_is) 0 else 1) else if (free_is) 1 - recast else recast;
- if (slot_shows < 1) rows.free(v.faded(1 - slot_shows), y, memory, addr, below_rsp, lead);
- if (slot_shows <= 0) continue;
+ // Under `tied` every word over rsp but a leaf's locals there (the red zone, its frame's).
+ const k_free = (addr -% roles_from) / 8;
+ // (A word a `push` is about to write has its role already, at the push's own stop: still free.)
+ const free_was = (held or tied) and addr < was.rsp and !(tied and k_free < roles[0].len and roles[0][k_free].frame != null and roles[0][k_free].role == .local);
+ const free_is = (held or tied) and addr < is.rsp and !(tied and k_free < roles[1].len and roles[1][k_free].frame != null and roles[1][k_free].role == .local);
+ // `tied`: gained or released as rsp's pin reaches it (12 f).
+ // A word the step writes over rsp (a push's, a call's, a store the line makes past the old rsp) is the frame's as its arm comes
+ // (the touch's word as the touch lands): armed, struck, and then the pin climbs over it.
+ const passed = if (touched_here and touch.?.write and now.walking() and now.plan.touch >= 0) now.time - now.plan.touch - time.tied.touch else if (tied and now.walking() and free_was and !free_is and now.writeAge(addr, 8) == 0) now.time - (now.plan.at[1] + now.writeDelay(addr, 8) - time.strike.arm) else if (pin_sp != null and !held) pinPassed(now, rows_of(was.rsp, window[0]), rows_of(is.rsp, window[0]), @as(f32, @floatFromInt(n))) else null;
+ const turned = if (passed) |ago| std.math.clamp(ago / time.quick, 0, 1) else recast;
+ const slot_shows: f32 = if (free_was == free_is or now.resting()) @as(f32, if (free_is) 0 else 1) else if (free_is) 1 - turned else turned;
+ const offset_was: ?i64 = if (tied) @as(i64, @bitCast(addr -% bases[0].value(was))) else null;
+ if (slot_shows < 1) rows.free(v.faded(1 - slot_shows), y, memory, addr, below_rsp, lead, .{ .name = "", .going = recast, .from_rsp = offset_was });
+ if (slot_shows <= 0) {
+ // `tied`: a free word is a place too (the touch of a push or a call goes to it).
+ if (tied and y >= top - 1 and y + m.row <= box.h - m.pad + 1) {
+ ties.anchor(u, .{ .word = addr }, .{ .x = theme.metric.slot.address, .y = y, .w = 120, .h = m.row });
+ ties.anchor(u, .{ .slot_pin = addr }, .{ .x = theme.metric.slot.lane, .y = y, .w = theme.metric.slot.lane_end - theme.metric.slot.lane, .h = m.row });
+ }
+ continue;
+ }
const vs = v.faded(slot_shows);
// A frame's name beside this row: the chain ends a character before it.
var room_w = map.content(box.w);
@@ -623,12 +730,11 @@ pub const Stack = struct {
const k_role = (addr -% roles_from) / 8;
var role_at: [2]@TypeOf(roleName(u, .none, 0)) = undefined;
for (&role_at, roles, [2]Recording.Moment{ now.before(), now.moment() }) |*r, of, mem| {
- const what: zt.telescope.Role = if (k_role < of.len) of[k_role].role else .none;
- r.* = roleName(u, what, (Recording.word(mem, addr, 8) catch null) orelse 1);
+ r.* = slotName(u, if (k_role < of.len) of[k_role] else .{}, (Recording.word(mem, addr, 8) catch null) orelse 1);
}
const what: zt.telescope.Role = if (k_role < roles[1].len) roles[1][k_role].role else .none;
const role = role_at[1];
- const role_was: rows.Role = .{ .name = role_at[0].name, .local = role_at[0].local, .going = recast, .from_rsp = @bitCast(addr -% was.rsp) };
+ const role_was: rows.Role = .{ .name = role_at[0].name, .local = role_at[0].local, .going = if (passed != null) turned else recast, .from_rsp = if (tied) @bitCast(addr -% bases[0].value(was)) else @bitCast(addr -% was.rsp), .offset_going = recast };
// At a run a word changes in place under an 8 f crossfade, as a register does.
const ran = runFade(now, .memory);
const word_was = Recording.word(now.before(), addr, 8) catch null;
@@ -669,18 +775,35 @@ pub const Stack = struct {
if (!ui.mapping) ties.stack_window = .{ .first = window[0], .slots = slots, .x = lane_at[0], .top = lane_at[1], .row = row_px };
// The travelling tags: both of them at one word share a pin.
var places: [2]f32 = undefined;
- for (travel, places[0..travel.len]) |name, *place| {
- const at_old = @as(f32, @floatFromInt(@as(i64, @bitCast((was.named(name) orelse 0) -% window[0])))) / 8 + slide;
+ var olds: [2]f32 = undefined;
+ const slots_f: f32 = @floatFromInt(slots);
+ for (travel, places[0..travel.len], olds[0..travel.len]) |name, *place, *old| {
+ var at_old = @as(f32, @floatFromInt(@as(i64, @bitCast((was.named(name) orelse 0) -% window[0])))) / 8 + slide;
const at_new = @as(f32, @floatFromInt(@as(i64, @bitCast((is.named(name) orelse 0) -% window[0])))) / 8 + slide;
+ // `tied`: a pin from outside the window comes in at its edge (rbp in from the window's foot).
+ if (tied) at_old = std.math.clamp(at_old, -1, slots_f);
+ old.* = at_old;
place.* = std.math.lerp(at_old, at_new, goes(now, was, is, name));
}
- for (travel, places[0..travel.len], 0..) |name, place, i| {
+ // `tied`: rsp's move on its pin as it travels, counting a row at a time, held to the advance and crossfading to the bare name (12 f).
+ const amount_shows: f32 = if (tied and now.walking() and pin_sp != null and now.time >= now.plan.pins[0]) 1 - std.math.clamp((now.time - now.plan.advance) / time.quick, 0, 1) else 0;
+ for (travel, places[0..travel.len], olds[0..travel.len], 0..) |name, place, old, i| {
if (i == 1 and @abs(places[0] - place) < 0.05) continue;
- if (place < -0.5 or place > @as(f32, @floatFromInt(slots)) - 0.5) continue;
+ if (place < (if (tied) @as(f32, -1) else -0.5) or place > (if (tied) slots_f else slots_f - 0.5)) continue;
const both = i == 0 and travel.len == 2 and @abs(places[1] - place) < 0.05;
// Alone, from its place among the names it leaves to its place among those it joins.
const x = if (lone != null) std.math.lerp(pinPlace(u, pins(u, now, is, was, was.named(name) orelse 0, travel).names, name), pinPlace(u, pins(u, now, is, was, is.named(name) orelse 0, travel).names, name), goes(now, was, is, name)) else theme.metric.slot.lane;
- u.pinRow(x, top + place * m.row, if (both) &.{ "rsp", "rbp" } else &.{name}, theme.color.region.stack);
+ const names_: []const []const u8 = if (both) &.{ "rsp", "rbp" } else &.{name};
+ if (amount_shows > 0 and std.mem.eql(u8, name, "rsp")) {
+ const crossed = @abs(place - old);
+ const total_rows = cursors.wordsApart(rec, now.stops[1], now.stops[0], "rsp");
+ // Rows crossed, counted on its whole way (its start may be off the window).
+ const count = std.math.clamp(@ceil(goes(now, was, is, "rsp") * total_rows - 0.01), 1, total_rows);
+ const bytes: u64 = @intFromFloat(count * 8);
+ pinAmount(u, x, top + place * m.row, names_, if (is.rsp < was.rsp) u.print("-{x}", .{bytes}) else u.print("+{x}", .{bytes}), amount_shows);
+ // The rows it crossed, a 3-unit vermilion bracket in the outer arc lane.
+ if (crossed > 0.05) u.faded(amount_shows).bracket(theme.metric.arc.lanes[0], top + @min(place, old) * m.row + 2, top + @max(place, old) * m.row - 2, theme.mark(.write).solid, theme.metric.bracket.tie, 1, false);
+ } else u.pinRow(x, top + place * m.row, names_, theme.color.region.stack);
}
for (spans[0..n_spans]) |sp| if (sp.was) |was_name| {
rows.span(v.faded(1 - renamed), map.content(box.w), sp.y0, sp.y1, was_name, sp.newest, sp.open);
@@ -694,10 +817,11 @@ pub const Stack = struct {
/// local's name (primary, `+8` a word into it); `argc`, `argv[0]`,
/// `argv end`, `envp end`, `auxv` (dim). A return address needs none:
/// its chain is code, named. `word`: what the slot holds (0 ends argv and envp).
- fn roleName(u: ui.Ui, role: zt.telescope.Role, word: u64) struct { name: []const u8, local: bool = false } {
+ pub fn roleName(u: ui.Ui, role: zt.telescope.Role, word: u64) struct { name: []const u8, local: bool = false } {
return switch (role) {
.none, .return_address => .{ .name = "" },
- .saved => |r| .{ .name = u.print("saved {s}", .{r}) },
+ // The stack protector's copy is the `canary`, not a register saved.
+ .saved => |r| .{ .name = if (std.mem.eql(u8, r, "canary")) "canary" else u.print("saved {s}", .{r}) },
.local => |l| .{ .name = if (l.offset > 0) u.print("{s}+{x}", .{ l.name, @as(u32, @intCast(l.offset)) }) else if (l.offset == -4 and l.size == 4) u.print("{s}, high half", .{l.name}) else if (l.offset < 0) u.print("{s}, from byte {d}", .{ l.name, -l.offset }) else l.name, .local = true },
.argc => .{ .name = "argc" },
.argv => |i| .{ .name = if (word == 0) "argv end" else u.print("argv[{d}]", .{i}) },
@@ -706,6 +830,31 @@ pub const Stack = struct {
};
}
+ /// A slot's role (`roleName`), with the other locals that share its word: `i, n`.
+ pub fn slotName(u: ui.Ui, slot: zt.telescope.Slot, word: u64) @TypeOf(roleName(u, .none, 0)) {
+ if (slot.role != .local or slot.also[0] == null) return roleName(u, slot.role, word);
+ var out: []const u8 = slot.role.local.name;
+ for (slot.also) |a| if (a) |l| {
+ out = u.print("{s}, {s}", .{ out, l.name });
+ };
+ return .{ .name = out, .local = true };
+ }
+
+ /// A row pin of `names` with rsp's move on it (`amount`, `-18`, bold in
+ /// write's vermilion), `shows` of the amount; its head after it.
+ fn pinAmount(u: ui.Ui, x: f32, y: f32, names: []const []const u8, amount: []const u8, shows: f32) void {
+ const size = theme.size.mono.context;
+ const p = theme.metric.pin;
+ const shown = if (names.len == 2) u.print("{s} {s}", .{ names[0], names[1] }) else names[0];
+ const base = theme.baseline(y, m.row, size);
+ u.text(.mono_bold, size, x, base, shown, t.primary);
+ const end = x + u.width(.mono, size, shown);
+ u.faded(shows).text(.mono_bold, size, end + ui.advance(size), base, amount, theme.mark(.write).solid);
+ const hx = end + shows * (ui.advance(size) + u.width(.mono, size, amount)) + p.row_gap;
+ const mid = y + m.row / 2;
+ sk.draw.polygon(u.f, &.{ .{ hx + p.row_head[0], mid }, .{ hx, mid - p.row_head[1] / 2 }, .{ hx, mid + p.row_head[1] / 2 } }, u.at.pen(.{ .fill = ui.rgb(theme.color.region.stack) }));
+ }
+
/// Where `name` goes in a row pin of `others` and it, in the registers' order.
fn pinPlace(u: ui.Ui, others: []const []const u8, name: []const u8) f32 {
const size = theme.size.mono.context;
@@ -736,6 +885,25 @@ pub const Stack = struct {
sk.draw.polygon(u.f, &.{ .{ hx + p.row_head[0], mid }, .{ hx, mid - p.row_head[1] / 2 }, .{ hx, mid + p.row_head[1] / 2 } }, u.at.pen(.{ .fill = ui.rgb(theme.color.region.stack) }));
}
+ /// Seconds since rsp's pin, going from row `from` to row `to` of the
+ /// window, passed the middle of row `n` (negative before it): when a word
+ /// it reaches is gained, or one it leaves released. Null where it does not cross it.
+ fn pinPassed(now: cursors.Now, from: f32, to: f32, n: f32) ?f32 {
+ if (from == to) return null;
+ const q = (n + 0.5 - from) / (to - from);
+ if (q < 0 or q > 1) return null;
+ const run = now.plan.gait == .run;
+ const start: f32 = if (run) 0 else now.plan.pins[0];
+ // When its eased way reaches q.
+ var lo: f32 = 0;
+ var hi: f32 = 1;
+ for (0..16) |_| {
+ const mid = (lo + hi) / 2;
+ if ((if (run) cursors.standard(mid) else cursors.glide(mid)) < q) lo = mid else hi = mid;
+ }
+ return now.time - (start + lo * cursors.pinTime(@abs(to - from), run));
+ }
+
/// Whether a window of `slots` going from word `a` to word `b` goes
/// farther than its own height: it fades, and does not scroll.
fn far(a: u64, b: u64, slots: usize) bool {
@@ -761,9 +929,11 @@ pub const Stack = struct {
/// read there is in the window's middle.
fn windowAt(now: cursors.Now, regs: zt.Regs, slots: usize, skip: usize) u64 {
const frame_end = regs.rbp +% 16;
- if (frame_end <= regs.rsp or frame_end - regs.rsp > 8 * 64) return regs.rsp;
- const words = (frame_end - regs.rsp) / 8;
- if (words <= slots) return regs.rsp;
+ // `tied`: from its headroom, two `free` words over rsp (the room a push, a call or a `sub rsp` takes).
+ const top = if (now.annotation == .tied) regs.rsp -% 16 else regs.rsp;
+ if (frame_end <= regs.rsp or frame_end - regs.rsp > 8 * 64) return top;
+ const words = (frame_end - top) / 8;
+ if (words <= slots) return top;
for (skip..skip + 3) |age| {
if (age + 1 >= now.stops.len) break;
for ([_][]const Recording.Span{ now.rec.written(now.stops[age + 1], now.stops[age]), now.rec.read(now.stops[age + 1], now.stops[age]) }) |spans| {
@@ -771,14 +941,23 @@ pub const Stack = struct {
while (k > 0) {
k -= 1;
const a = spans[k].addr;
- if (a < regs.rsp or a >= frame_end) continue;
- const word = (a - regs.rsp) / 8;
+ if (a < top or a >= frame_end) continue;
+ const word = (a - top) / 8;
const first = @min(word -| (slots - 1) / 2, words - slots);
- return regs.rsp + 8 * first;
+ return top + 8 * first;
}
}
}
- return regs.rsp;
+ return top;
+ }
+
+ /// Under `tied`, a window of `slots` from the headroom over `regs`'s rsp
+ /// that has word `addr` in its middle: where it scrolls before a touch.
+ fn windowOver(regs: zt.Regs, slots: usize, addr: u64) u64 {
+ const top = regs.rsp -% 16;
+ if (addr < top) return addr & ~@as(u64, 7);
+ const words = (@max(regs.rbp +% 16, addr + 8) - top) / 8;
+ return top + 8 * @min(((addr - top) / 8) -| (slots - 1) / 2, words -| slots);
}
const Pins = struct { names: []const []const u8, shows: f32 };
diff --git a/anim/src/cursor.zig b/anim/src/cursor.zig
index 16ccd77..5cb625a 100644
--- a/anim/src/cursor.zig
+++ b/anim/src/cursor.zig
@@ -63,6 +63,17 @@ pub const Levels = struct {
/// sets it, `Context.Options.syscalls`): what the step changed in the
/// registers strikes once the call is back.
crossings: bool = false,
+ /// The disassembly's annotation (design/README.md, `insn`), read when
+ /// the context is made: `tied` names the word an instruction touches,
+ /// the stack counts from the frame's base with two `free` words over
+ /// rsp, and a walked step goes cause to effect (the `touch`, the word,
+ /// rsp's or rbp's pin, then the window); `whole` is pwndbg's chain,
+ /// offsets from rsp, and the cascade as it was.
+ annotation: enum { tied, whole } = .tied,
+ /// A value's way between memory and a register (`carry`, "4. Ties"),
+ /// read at each step (a beat may turn it on): none, an arrow, or the
+ /// arrow carrying the value's digits on a chip.
+ carry: enum { off, arrow, value } = .off,
};
/// How a step is drawn. Walk: everything, as a sentence. Run: the mark and
@@ -88,6 +99,46 @@ pub const Plan = struct {
/// (a step that went on from it without its rest: a crossing from its
/// call row): what it struck goes on cooling, never cut in a frame.
cooling: f32 = 0,
+ /// A walk under `tied` (design/motion.md, "A word touched", "The
+ /// stack's own instructions"), seconds from its first frame, negative
+ /// where the step has none: the touch sets off; what the step read is
+ /// framed; the carry sets off (`carry_value`: its digits ride it); rsp's
+ /// pin and rbp's set off; the stack's window follows; the projection
+ /// sets off (else from memory's strike).
+ touch: f32 = -1,
+ read: f32 = -1,
+ carry: f32 = -1,
+ carry_value: bool = false,
+ pins: [2]f32 = .{ -1, -1 },
+ follow: f32 = -1,
+ project: f32 = -1,
+
+ /// How many values a plan is on the timeline (`pack`).
+ const values = 18;
+
+ 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 };
+ }
+
+ fn unpack(v: [values]f32) Plan {
+ return .{
+ .gait = @enumFromInt(@as(u2, @intFromFloat(std.math.clamp(@round(v[0]), 0, 2)))),
+ .at = .{ v[1], v[2], v[3] },
+ .advance = v[4],
+ .travel = v[5],
+ .total = v[6],
+ .wave = v[7] >= 0.5,
+ .fires = v[8] >= 0.5,
+ .cooling = v[9],
+ .touch = v[10],
+ .read = v[11],
+ .carry = v[12],
+ .carry_value = v[13] >= 0.5,
+ .pins = .{ v[14], v[15] },
+ .follow = v[16],
+ .project = v[17],
+ };
+ }
/// Once the pattern is known: the levels a stagger apart from the
/// first frame, the mark after them, in `seconds`.
@@ -110,6 +161,116 @@ pub const quiet: u32 = blk: {
break :blk mask;
};
+/// rsp's and rbp's places in `Regs.names`.
+pub const sp_index: u5 = blk: {
+ for (zt.Regs.names, 0..) |name, i| if (std.mem.eql(u8, name, "rsp")) break :blk i;
+ unreachable;
+};
+pub const bp_index: u5 = blk: {
+ for (zt.Regs.names, 0..) |name, i| if (std.mem.eql(u8, name, "rbp")) break :blk i;
+ unreachable;
+};
+
+/// The word of the stack a step's instruction reads or writes: what its
+/// `touch` goes to (design/README.md, "4. Ties"). The instruction's moment,
+/// the word's address and width, and whether it writes there.
+pub const Touched = struct { at: u64, addr: u64, len: u64, write: bool };
+
+/// The step's touched word: a write first (the effect), else the first
+/// read; the recorder's `touch` where it has one, else what a `push` or a
+/// `call` writes at the new rsp, a `pop` or a `ret` reads at the old, a
+/// `leave` at the old rbp (a recording made before the tracer's touches of
+/// implicit operands, the gallery's, carries none for those).
+pub fn stackTouch(rec: *const Recording, from: u64, to: u64) ?Touched {
+ var read: ?Touched = null;
+ var buf: [256]u8 = undefined;
+ var i = from;
+ // shortcut: a step of more than 64 instructions looks at its first 64.
+ while (i < to and i < from + 64 and i < rec.end()) : (i += 1) {
+ const m = rec.moment(i);
+ for (rec.insn_touches[i]) |maybe| if (maybe) |tt| {
+ if ((zt.telescope.region(m, tt.addr) catch .none) != .stack) continue;
+ const one: Touched = .{ .at = i, .addr = tt.addr, .len = tt.len, .write = tt.how & 2 != 0 };
+ if (one.write) return one;
+ if (read == null) read = one;
+ };
+ const was = rec.registers[i];
+ const is = rec.registers[i + 1];
+ const here = rec.instruction(i, was.rip, &buf) orelse continue;
+ const mn = here.text[0 .. std.mem.indexOfScalar(u8, here.text, ' ') orelse here.text.len];
+ const eql = std.mem.eql;
+ // Only where the moment after is the instruction's own (a recording by instruction).
+ const next = is.rip == was.rip + here.len or (rec.insn_branches[i] != null and rec.insn_branches[i].?.to == is.rip);
+ if (!next) continue;
+ if ((eql(u8, mn, "push") or eql(u8, mn, "call")) and is.rsp +% 8 == was.rsp) return .{ .at = i, .addr = is.rsp, .len = 8, .write = true };
+ if (read != null) continue;
+ if ((eql(u8, mn, "pop") or eql(u8, mn, "ret")) and is.rsp == was.rsp +% 8) read = .{ .at = i, .addr = was.rsp, .len = 8, .write = false };
+ if (eql(u8, mn, "leave")) read = .{ .at = i, .addr = was.rbp, .len = 8, .write = false };
+ }
+ return read;
+}
+
+/// A value's way for `carry`: a load (into the register, `load`) or a store
+/// (from it), by the touched instruction's operands: `mov` a register and
+/// the word, a `push` or a `pop` of a register. Null for anything else (a
+/// call's return address, an access with no register at its other end).
+pub const Carry = struct { load: bool, reg: []const u8 };
+
+pub fn carried(rec: *const Recording, touch: Touched) ?Carry {
+ var buf: [256]u8 = undefined;
+ const here = rec.instruction(touch.at, rec.register(touch.at, "rip"), &buf) orelse return null;
+ const text = here.text;
+ const space = std.mem.indexOfScalar(u8, text, ' ') orelse return null;
+ const mn = text[0..space];
+ const ops = std.mem.trim(u8, text[space..], " ");
+ const comma = std.mem.indexOfScalar(u8, ops, ',');
+ const first = std.mem.trim(u8, ops[0 .. comma orelse ops.len], " ");
+ const second = if (comma) |cm| std.mem.trim(u8, ops[cm + 1 ..], " ") else "";
+ const eql = std.mem.eql;
+ if (eql(u8, mn, "push")) return if (register64(first)) |r| .{ .load = false, .reg = r } else null;
+ if (eql(u8, mn, "pop")) return if (register64(first)) |r| .{ .load = true, .reg = r } else null;
+ if (!std.mem.startsWith(u8, mn, "mov")) return null;
+ if (touch.write) return if (register64(second)) |r| .{ .load = false, .reg = r } else null;
+ return if (register64(first)) |r| .{ .load = true, .reg = r } else null;
+}
+
+/// A general register's 64-bit name, from any of its widths; null for anything else.
+pub fn register64(name: []const u8) ?[]const u8 {
+ const table = [_][4][]const u8{
+ .{ "rax", "eax", "ax", "al" }, .{ "rbx", "ebx", "bx", "bl" }, .{ "rcx", "ecx", "cx", "cl" }, .{ "rdx", "edx", "dx", "dl" },
+ .{ "rsi", "esi", "si", "sil" }, .{ "rdi", "edi", "di", "dil" }, .{ "rbp", "ebp", "bp", "bpl" }, .{ "rsp", "esp", "sp", "spl" },
+ };
+ for (table) |row| for (row) |n| if (std.mem.eql(u8, n, name)) return row[0];
+ for ([_][]const u8{ "r8", "r9", "r10", "r11", "r12", "r13", "r14", "r15" }) |r| {
+ if (std.mem.startsWith(u8, name, r) and (name.len == r.len or (name.len == r.len + 1 and std.mem.indexOfScalar(u8, "dwb", name[r.len]) != null))) return r;
+ }
+ return null;
+}
+
+/// How many words register `name` (rsp, rbp) moved over the step from `from` to `to`.
+pub fn wordsApart(rec: *const Recording, from: u64, to: u64, name: []const u8) f32 {
+ const a = rec.register(from, name);
+ const b = rec.register(to, name);
+ return @floatFromInt(@abs(@as(i64, @bitCast(b -% a))) / 8);
+}
+
+/// Whether the step is a `pop rbp` (or ends in one alone): rbp's pin flies before rsp's falls.
+fn popsRbp(rec: *const Recording, from: u64, to: u64) bool {
+ if (to != from + 1) return false;
+ var buf: [256]u8 = undefined;
+ const here = rec.instruction(from, rec.register(from, "rip"), &buf) orelse return false;
+ return std.mem.startsWith(u8, here.text, "pop");
+}
+
+/// How long rsp's or rbp's pin takes over `rows` rows (`time.tied`): 24 f
+/// to the next, 6 f a further one, 48 f at most; at a run 8 f and 2 f a
+/// row, 16 f at most.
+pub fn pinTime(rows: f32, run: bool) f32 {
+ const k = time.tied;
+ if (run) return @min(time.run_ease + 2.0 / 60.0 * @max(rows - 1, 0), k.run_pin_most);
+ return @min(k.stack_pin + k.stack_pin_row * @max(rows - 1, 0), k.stack_pin_most);
+}
+
pub const Cursor = struct {
rec: *Recording,
/// Where it is (or is arriving), where it came from, and before that.
@@ -119,8 +280,8 @@ pub const Cursor = struct {
gaits: [history]anim.Value,
/// 0 to 1 through the step it is taking; 1 at rest.
phase: anim.Value,
- /// The step's `Plan`, a value a field.
- plan: [10]anim.Value,
+ /// The step's `Plan`, a value a field (`Plan.pack`).
+ plan: [Plan.values]anim.Value,
/// The moment the current mark was on, and the one it is on (or going to).
marks: [2]anim.Value,
/// 1 while steps are hurried (the head counts them), and while what
@@ -154,7 +315,7 @@ pub const Cursor = struct {
.stops = undefined,
.gaits = undefined,
.phase = s.value(1),
- .plan = .{ s.value(0), s.value(plan.at[0]), s.value(plan.at[1]), s.value(plan.at[2]), s.value(plan.advance), s.value(plan.travel), s.value(plan.total), s.value(0), s.value(1), s.value(0) },
+ .plan = undefined,
.marks = .{ s.value(here), s.value(here) },
.hurried = s.value(0),
.veil = s.value(0),
@@ -164,6 +325,7 @@ pub const Cursor = struct {
.first = start,
.last = start,
};
+ for (&c.plan, Plan.pack(plan)) |*value, is| value.* = s.value(is);
// shortcut: an f32 holds whole moments up to 16 million; a longer recording needs two values a stop.
for (&c.stops) |*stop| stop.* = s.value(here);
for (&c.gaits) |*gait| gait.* = s.value(0);
@@ -183,7 +345,7 @@ pub const Cursor = struct {
stops: [history]anim.Value,
gaits: [history]anim.Value,
phase: anim.Value,
- plan: [10]anim.Value,
+ plan: [Plan.values]anim.Value,
marks: [2]anim.Value,
hurried: anim.Value,
veil: anim.Value,
@@ -261,24 +423,25 @@ pub const Cursor = struct {
const Step = struct {
stops: [history]f32,
gaits: [history]f32,
- plan: [10]f32,
+ plan: [Plan.values]f32,
marks: [2]f32,
count: f32,
seconds: f32,
fn run(st: @This(), sf: *anim.Frame, v: Cursor) void {
- var set: [2 * history + 14]anim.Animation = undefined;
+ const n_plan = Plan.values;
+ var set: [2 * history + n_plan + 4]anim.Animation = undefined;
for (v.stops, st.stops, 0..) |value, is, i| set[i] = value.to(is);
- for (v.gaits, st.gaits, 0..) |value, is, i| set[history + 14 + i] = value.to(is);
+ for (v.gaits, st.gaits, 0..) |value, is, i| set[history + n_plan + 4 + i] = value.to(is);
for (v.plan, st.plan, history..) |value, is, n| set[n] = value.to(is);
- set[history + 10] = v.marks[0].to(st.marks[0]);
- set[history + 11] = v.marks[1].to(st.marks[1]);
- set[history + 12] = v.phase.to(0);
- set[history + 13] = v.count.to(st.count);
+ set[history + n_plan] = v.marks[0].to(st.marks[0]);
+ set[history + n_plan + 1] = v.marks[1].to(st.marks[1]);
+ set[history + n_plan + 2] = v.phase.to(0);
+ set[history + n_plan + 3] = v.count.to(st.count);
sf.play(set, .{ .seconds = 0 });
sf.play(.{v.phase.to(1)}, .{ .seconds = st.seconds, .ease = anim.ease.linear });
}
};
- var st: Step = .{ .stops = undefined, .gaits = undefined, .plan = .{ @floatFromInt(@intFromEnum(plan.gait)), plan.at[0], plan.at[1], plan.at[2], plan.advance, plan.travel, plan.total, @floatFromInt(@intFromBool(plan.wave)), @floatFromInt(@intFromBool(plan.fires)), plan.cooling }, .marks = undefined, .count = settled(s, c.count) + 1, .seconds = seconds };
+ var st: Step = .{ .stops = undefined, .gaits = undefined, .plan = Plan.pack(plan), .marks = undefined, .count = settled(s, c.count) + 1, .seconds = seconds };
st.stops[0] = @floatFromInt(to);
for (1..history) |i| st.stops[i] = settled(s, c.stops[i - 1]);
st.gaits[0] = @floatFromInt(@intFromEnum(plan.gait));
@@ -333,6 +496,7 @@ pub const Cursor = struct {
}
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;
const regs: f32 = @floatFromInt(@popCount(rec.registersChanged(from, to) & ~quiet));
// Memory gives up its slot when nothing it touched is drawn.
@@ -392,6 +556,126 @@ pub const Cursor = struct {
return plan;
}
+ /// `timetable` under `tied` (design/motion.md, "A word touched", "A call
+ /// pushed", "A return", "The stack's own instructions"): cause before
+ /// effect, nothing downstream marked before what causes it has shown.
+ /// Fire; what the step read, its touch first (a stack word), then its
+ /// frame; the registers it filled (not rsp or rbp), armed after their
+ /// cause, a load's carry between; what it wrote, its touch (or a store's
+ /// carry) first, then armed and struck; a return's idea; rsp's pin and
+ /// rbp's, each struck as it lands (a `pop`'s rbp first); a call's or the
+ /// data's idea; the window follows; the hold, the advance, the rest.
+ fn tiedTable(c: Cursor, from: u64, to: u64) Plan {
+ const rec = c.rec;
+ const k = time.tied;
+ const f = 1.0 / 60.0;
+ const changed = rec.registersChanged(from, to) & ~quiet;
+ const regs: f32 = @floatFromInt(@popCount(changed & ~(@as(u32, 1) << sp_index | @as(u32, 1) << bp_index)));
+ var wrote_n: usize = 0;
+ var strikes_n: usize = 0;
+ for (rec.written(from, to)) |span| {
+ wrote_n += @intFromBool(rec.drawn(span, from, to));
+ strikes_n += @intFromBool(takesPlace(rec, span, from, to));
+ }
+ var read_n: usize = 0;
+ for (rec.read(from, to)) |span| read_n += @intFromBool(rec.drawn(span, from, to));
+ const wrote: f32 = @floatFromInt(if (wrote_n > 0) @max(strikes_n, 1) else 0);
+ const touch = stackTouch(rec, from, to);
+ const deeper = rec.depths[to] > rec.depths[from];
+ const back = rec.depths[to] < rec.depths[from];
+ const idea = switch (c.levels.idea) {
+ .none => false,
+ .calls => deeper or back,
+ .data => wrote_n > 0 or read_n > 0,
+ };
+ const carry: ?Carry = if (c.levels.carry != .off) if (touch) |tt| carried(rec, tt) else null else null;
+ var plan: Plan = .{ .travel = c.travel(from, to, false), .carry_value = c.levels.carry == .value };
+ // When the last cause has shown, and how many things there are to read.
+ var t: f32 = time.fire;
+ var values: f32 = 0;
+ const reads = c.levels.memory and (read_n > 0 or (touch != null and !touch.?.write));
+ if (reads) {
+ if (touch) |tt| if (!tt.write) {
+ plan.touch = t + 6 * f;
+ };
+ plan.read = if (plan.touch >= 0) plan.touch + k.touch else t + 6 * f;
+ t = plan.read + time.read.in;
+ values += 1;
+ }
+ // (A load carried fills its register even where the value is the one it held: the arrow lands, nothing is struck.)
+ const loads = if (carry) |cc| cc.load else false;
+ if (c.levels.cpu and (regs > 0 or loads)) {
+ if (carry) |cc| if (cc.load) {
+ plan.carry = t;
+ t += k.carry;
+ };
+ plan.at[0] = @max(time.cascade, t + time.strike.arm);
+ t = plan.at[0] + @min(@max(regs - 1, 0), 3) * write_apart;
+ values += 1;
+ }
+ const writes = c.levels.memory and (wrote > 0 or (touch != null and touch.?.write));
+ if (writes) {
+ const store = if (carry) |cc| !cc.load else false;
+ if (store) {
+ // The register framed as read (6 f), then the carry: no touch, the row having named the word.
+ plan.carry = t + 12 * f;
+ plan.at[1] = plan.carry + k.carry + time.strike.arm;
+ } else if (touch != null and touch.?.write) {
+ plan.touch = t + 6 * f;
+ plan.at[1] = plan.touch + k.touch + time.strike.arm;
+ } else plan.at[1] = @max(time.cascade, (if (regs > 0) plan.at[0] else if (reads) plan.read else 0) + time.cascade);
+ t = plan.at[1] + @min(@max(wrote - 1, 0), 3) * write_apart;
+ values += 1;
+ } else plan.at[1] = if (reads) plan.read else t;
+ // The idea (design/motion.md, "A return"): a return's node answers before rsp falls.
+ var follow_through: f32 = 0;
+ if (idea and back) {
+ plan.at[2] = t + time.cascade;
+ t = plan.at[2];
+ follow_through = time.snap;
+ values += 1;
+ }
+ // rsp's pin and rbp's, one after the other: a `pop`'s rbp first (it takes the word rsp leaves).
+ const rows = [2]f32{ wordsApart(rec, from, to, "rsp"), wordsApart(rec, from, to, "rbp") };
+ if (rows[0] > 0 or rows[1] > 0) {
+ const order: [2]usize = if (popsRbp(rec, from, to)) .{ 1, 0 } else .{ 0, 1 };
+ var start = t + 6 * f;
+ var first_land: ?f32 = null;
+ for (order) |r| if (rows[r] > 0) {
+ plan.pins[r] = start;
+ t = start + pinTime(rows[r], false);
+ first_land = first_land orelse t;
+ start = t + 6 * f;
+ };
+ // Nothing else in the CPU's slot: it is rsp's (or rbp's) landing.
+ if (!(c.levels.cpu and regs > 0)) plan.at[0] = first_land.?;
+ values += 1;
+ }
+ if (idea and !back) {
+ // A drawing made of the bytes, or a call's node from the frame its return address made: projected once they have shown.
+ const projected = writes or reads;
+ plan.project = if (plan.pins[0] >= 0 or plan.pins[1] >= 0) t + 6 * f else plan.at[1];
+ if (projected) {
+ plan.at[2] = @max(t, plan.project + time.project.bracket + @as(f32, if (c.levels.idea == .data) time.project.draw else time.project.far) + @as(f32, if (wrote > 0 and c.levels.idea == .data) time.strike.arm else 0));
+ } else plan.at[2] = t + time.cascade;
+ t = plan.at[2];
+ follow_through = switch (c.levels.idea) {
+ .none => 0,
+ .calls => time.snap,
+ .data => c.levels.follow,
+ };
+ values += 1;
+ }
+ // The window follows, once rsp's pin has landed.
+ if (rows[0] > 0) {
+ plan.follow = t + 6 * f;
+ t = plan.follow + k.follow;
+ }
+ plan.advance = if (values > 0) t + follow_through + @min(time.read_value + time.read_more * (values - 1), time.read_most) else time.fire;
+ plan.total = plan.advance + plan.travel + time.rest;
+ return plan;
+ }
+
/// How long the mark takes to the next line: a slide by how far, or a
/// jump (out, then in) into or out of a call, further than a few rows,
/// or at the end of a continue (`wave`).
@@ -501,16 +785,7 @@ pub const Cursor = struct {
.rec = rec,
.stops = undefined,
.time = std.math.inf(f32),
- .plan = .{
- .gait = @enumFromInt(@as(u2, @intFromFloat(std.math.clamp(@round(placed.value(c.plan[0])), 0, 2)))),
- .at = .{ placed.value(c.plan[1]), placed.value(c.plan[2]), placed.value(c.plan[3]) },
- .advance = placed.value(c.plan[4]),
- .travel = placed.value(c.plan[5]),
- .total = placed.value(c.plan[6]),
- .wave = placed.value(c.plan[7]) >= 0.5,
- .fires = placed.value(c.plan[8]) >= 0.5,
- .cooling = placed.value(c.plan[9]),
- },
+ .plan = undefined,
.marks = .{ whole(rec, placed.value(c.marks[0])), whole(rec, placed.value(c.marks[1])) },
.hurried = placed.value(c.hurried),
.veil = placed.value(c.veil),
@@ -520,8 +795,12 @@ pub const Cursor = struct {
.place = 0,
.fired = c.levels.fire,
.crossings = c.levels.crossings,
+ .annotation = c.levels.annotation,
.way = .{ c.first, c.last },
};
+ var plan: [Plan.values]f32 = undefined;
+ for (&plan, c.plan) |*is, v| is.* = placed.value(v);
+ n.plan = Plan.unpack(plan);
for (&n.stops, c.stops) |*stop_at, v| stop_at.* = whole(rec, placed.value(v));
for (&n.gaits, c.gaits) |*gait, v| gait.* = @enumFromInt(@as(u2, @intFromFloat(std.math.clamp(@round(placed.value(v)), 0, 2))));
const phase = placed.value(c.phase);
@@ -586,6 +865,8 @@ pub const Now = struct {
fired: @FieldType(Levels, "fire") = .source,
/// Steps that make a syscall cross into the kernel (`Levels.crossings`).
crossings: bool = false,
+ /// The disassembly's annotation, and what goes with it (`Levels.annotation`).
+ annotation: @FieldType(Levels, "annotation") = .tied,
/// The scene's way through the recording: its first moment and its last.
way: [2]u64 = .{ 0, 0 },
@@ -927,12 +1208,48 @@ pub const Now = struct {
/// gold, and out as the mark leaves, gone before the next line fires.
pub fn reading(n: Now, level: Level, delay: f32) f32 {
return switch (n.plan.gait) {
- .walk => n.held(n.plan.at[@intFromEnum(level)] + delay),
+ // Under `tied` what a step read is framed in its own slot, before what it fills (`Plan.read`).
+ .walk => n.held((if (level == .memory and n.plan.read >= 0) n.plan.read else n.plan.at[@intFromEnum(level)]) + delay),
.run => if (n.resting()) 0 else @min(std.math.clamp(n.since(level, 0) / time.stagger, 0, 1), std.math.clamp((n.plan.total - n.time) / time.snap, 0, 1)),
.sprint => 0,
};
}
+ /// Under `tied`, rsp's (`k` 0) or rbp's (1) pin: how far (0 to 1, on
+ /// `glide`) it has travelled from where the step found it, at a walk
+ /// from `Plan.pins`, at a run over its 8 f and 2 f a row from the step's
+ /// start; 1 at rest. Null where the step does not move it so (the old
+ /// timing: a plan with no pins, a sprint, `whole`).
+ pub fn pinGone(n: Now, k: usize) ?f32 {
+ if (n.annotation != .tied) return null;
+ if (n.resting()) return 1;
+ const rows = wordsApart(n.rec, n.stops[1], n.stops[0], if (k == 0) "rsp" else "rbp");
+ if (rows == 0) return null;
+ return switch (n.plan.gait) {
+ .walk => if (n.plan.pins[k] < 0) null else glide(std.math.clamp((n.time - n.plan.pins[k]) / pinTime(rows, false), 0, 1)),
+ .run => standard(std.math.clamp(n.time / pinTime(rows, true), 0, 1)),
+ .sprint => null,
+ };
+ }
+
+ /// Seconds into a walked step when rsp's (`k` 0) or rbp's (1) pin lands: its strike.
+ pub fn pinLands(n: Now, k: usize) ?f32 {
+ if (n.annotation != .tied or n.plan.gait != .walk or n.plan.pins[k] < 0) return null;
+ return n.plan.pins[k] + pinTime(wordsApart(n.rec, n.stops[1], n.stops[0], if (k == 0) "rsp" else "rbp"), false);
+ }
+
+ /// When the stack's labels that the step changes (an offset whose base
+ /// moved, the tag's note) crossfade from, under `tied`: as the window
+ /// follows, else as the last pin lands, else with memory's strike.
+ pub fn restacked(n: Now) f32 {
+ if (n.plan.follow >= 0) return n.plan.follow;
+ var last: ?f32 = null;
+ for (0..2) |k| if (n.pinLands(k)) |l| {
+ last = @max(last orelse l, l);
+ };
+ return last orelse n.plan.at[1];
+ }
+
/// The same for a frame that comes in `from` seconds into a walked step.
pub fn held(n: Now, from: f32) f32 {
const r = time.read;
diff --git a/anim/src/descent.zig b/anim/src/descent.zig
index 5dd156c..ff478df 100644
--- a/anim/src/descent.zig
+++ b/anim/src/descent.zig
@@ -59,15 +59,32 @@ pub fn step(cur: cursors.Cursor, s: *anim.Frame, by: Recording.Stop) void {
const b = rec.insn_branches[from] orelse return cur.walk(s, by, to);
var name_buf: [256]u8 = undefined;
const here = (rec.moment(from).string(rec.register(from, "rip"), &name_buf) catch null) orelse "";
+ // `tied`: the push or the read first, as any call's or return's (the touch, the word, rsp's pin, the
+ // window following: the stack's own timetable), then the windows, 42 f (a call) or 48 f (a return) later.
+ const tied = cur.levels.annotation == .tied;
const plan: cursors.Plan = switch (b.kind) {
- .call => .{ .at = .{ f(24), f(60), f(60) }, .advance = f(138), .travel = f(12), .total = f(174) },
- .ret => .{ .at = .{ f(36), f(18), f(36) }, .advance = f(114), .travel = f(12), .total = f(150) },
+ .call => if (tied) stacked(cur, from, to, f(180), f(216)) else .{ .at = .{ f(24), f(60), f(60) }, .advance = f(138), .travel = f(12), .total = f(174) },
+ .ret => if (tied) stacked(cur, from, to, f(162), f(198)) else .{ .at = .{ f(36), f(18), f(36) }, .advance = f(114), .travel = f(12), .total = f(150) },
.jump => if (std.mem.indexOf(u8, here, "@plt") != null) .{ .at = .{ f(18), f(24), f(24) }, .advance = f(96), .travel = f(12), .total = f(132) } else return cur.walk(s, by, to),
.none => return cur.walk(s, by, to),
};
cur.step(s, to, plan, plan.total);
}
+/// The key of the head row over function `name`'s window (a `ties.Place.row`).
+pub fn headKey(name: []const u8) u64 {
+ return std.hash.Wyhash.hash(0, name) | 1 << 63;
+}
+
+/// The stack's own timetable for the step (`Cursor.planned`), its advance and its end the descent's.
+fn stacked(cur: cursors.Cursor, from: u64, to: u64, advance: f32, total: f32) cursors.Plan {
+ var plan = cur.planned(from, to, false);
+ plan.advance = advance;
+ plan.travel = f(12);
+ plan.total = total;
+ return plan;
+}
+
/// A row of the panel.
const Item = struct {
key: u64,
@@ -110,9 +127,15 @@ pub const Descent = struct {
const after = layout(u, rec, now.stops[0], room, d.root);
// On the map its box is as long as the rows it has wanted: not 69 for a function of 30.
if (ui.mapping) map.measure(.disasm, @max(before.items.len, after.items.len));
- const tm = now.time;
const going = now.advancing();
const kind: enum { same, down, through, up } = if (now.resting() or now.stops[0] == now.stops[1]) .same else if (after.windows > before.windows) (if (before.in_stub) .through else .down) else if (after.windows < before.windows) .up else .same;
+ // `tied` (a plan with the stack's own moves, `stacked`): the windows move once the stack has, 42 f later down, 48 f up.
+ const shift: f32 = if (now.plan.follow < 0) 0 else switch (kind) {
+ .down => f(42),
+ .up => f(48),
+ .same, .through => 0,
+ };
+ const tm = now.time - shift;
const shown = if (going >= 0.5) after else before;
// A tag that changes with the advance crossfades over it.
const retag = !std.mem.eql(u8, before.tag, after.tag);
@@ -268,6 +291,7 @@ pub const Descent = struct {
last_window = p.item.window;
switch (p.item.what) {
.head => |h| {
+ ties.anchor(u, .{ .row = p.item.key }, .{ .x = 0, .y = y, .w = box.w, .h = m.row });
v.fill(.{ .x = theme.stroke.rule, .y = y, .w = box.w - 2 * theme.stroke.rule, .h = theme.stroke.rule }, theme.color.rule);
v.text(.sans_medium, theme.size.sans.micro, c.address, y + 18, h.name, t.primary);
v.text(.sans, theme.size.sans.micro, map.content(box.w) - m.side - v.width(.sans, theme.size.sans.micro, h.note), y + 18, h.note, t.faint);
@@ -319,6 +343,7 @@ pub const Descent = struct {
covered = if (p.twin) @max(covered, hangs) else @max(covered -| 1, hangs);
last_line = line;
map.row(.disasm, row.addr, u, .{ .x = 0, .y = y, .w = box.w, .h = m.row });
+ if (!p.twin) ties.anchor(u, .{ .row = row.addr }, .{ .x = 0, .y = y, .w = box.w, .h = m.row });
},
}
}
@@ -348,7 +373,9 @@ pub const Descent = struct {
// Its strip is the deepest window's function's column, that window framed on it.
map.window(.disasm, deepest(after), deepest(before), cursors.glide(going));
if (pc_y[1] orelse pc_y[0]) |y| ties.anchor(u, .pc, .{ .x = 0, .y = y, .w = theme.metric.plaque.pc, .h = m.row });
- kernel(u, now, box, under orelse top + @as(f32, @floatFromInt(room -| 3)) * m.row, pc_y[0] orelse pc_y[1]);
+ const floor = under orelse top + @as(f32, @floatFromInt(room -| 3)) * m.row;
+ if (shown.kernel) ties.anchor(u, .floor, .{ .x = 0, .y = floor, .w = box.w, .h = m.row });
+ kernel(u, now, box, floor, pc_y[0] orelse pc_y[1]);
context.veiled(u, box, now.veil);
// Going down or up, the strip is another function's column: it fades through as the mark lands (24 f).
map.strip(.disasm, if (kind == .same) u else u.faded(map.through(now, now.plan.travel + f(12))), box);
@@ -513,7 +540,7 @@ fn layout(u: ui.Ui, rec: *const Recording, i: u64, room: usize, root: []const u8
row += 1;
}
if (li > 0) {
- items.append(a, .{ .key = std.hash.Wyhash.hash(0, l.name) | 1 << 63, .row = row, .window = window, .what = .{ .head = .{ .name = l.name, .note = headNote(u, rec, i, l) } } }) catch {};
+ items.append(a, .{ .key = headKey(l.name), .row = row, .window = window, .what = .{ .head = .{ .name = l.name, .note = headNote(u, rec, i, l) } } }) catch {};
row += 1;
}
const nearest = li + 2 == kept.len and l.kind == .caller;
diff --git a/anim/src/disasm.zig b/anim/src/disasm.zig
index 7017453..085982d 100644
--- a/anim/src/disasm.zig
+++ b/anim/src/disasm.zig
@@ -225,6 +225,7 @@ pub const Disasm = struct {
continue;
}
map.row(.disasm, row.addr, u, .{ .x = 0, .y = y, .w = box.w, .h = m.row });
+ ties.anchor(u, .{ .row = row.addr }, .{ .x = 0, .y = y, .w = box.w, .h = m.row });
const is_pc = row.addr == pc[if (going >= 0.5) 1 else 0];
const was = if (is_pc) null else ran[j];
if (was) |r| lit.trail(c.mark, y, r.k);
@@ -287,6 +288,12 @@ pub const Disasm = struct {
return 0;
}
if (!row.bare) _ = at.address(c.address, base_y, row.addr, .{ .ink = ui.rgb(code_ink), .lead = lead });
+ // `tied`: the row the step's touch (or carry) leaves from, its right rule, for the ties.
+ if (!ui.mapping and now.annotation == .tied and now.walking() and (now.plan.touch >= 0 or now.plan.carry >= 0)) if (touchPc(rec, now)) |pc| if (pc == row.addr) {
+ const a = at.at.xf.apply(.{ w + theme.strip.cost, y });
+ const b = at.at.xf.apply(.{ w + theme.strip.cost, y + m.row });
+ ties.touch_row = .{ a[0], a[1], b[0], b[1] };
+ };
if (first_of_line) if (line) |l| {
const num = u.print("{d}", .{l});
const now_line = l == current_line;
@@ -356,6 +363,15 @@ pub const Disasm = struct {
if (state == .ran) if (returned(rec, row, moment, now.stops[base])) |back| {
return a.said(a.cForm(row, b.to, moment, rec.register(back, "rax"), a.room - a.x), t.primary);
};
+ // `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);
+ if (stub) note.hangs = a.arguments(row, b.to, moment);
+ return note;
+ }
var note = a.callee(b.to, moment);
// Its arguments hang under it, a small `reg` a row, as many as the prototype has.
if (state == .current) note.hangs = a.arguments(row, b.to, moment);
@@ -363,7 +379,10 @@ pub const Disasm = struct {
},
.ret => {
u.text(.mono, size, x, base_y, "\u{2192}", t.faint);
- return .{ .drawn = true, .end = u.address(x + 2 * adv, base_y, b.to, .{ .ink = ui.rgb(code_ink), .name = rec.strings.get(b.to) orelse "" }) };
+ const end = u.address(x + 2 * adv, base_y, b.to, .{ .ink = ui.rgb(code_ink), .name = rec.strings.get(b.to) orelse "" });
+ // `tied`: then its move of rsp, `· rsp +8`.
+ if (now.annotation == .tied) return .{ .drawn = true, .end = a.move(end + adv, 8, if (state == .current) a.rspHeat(now, base) else .none, null, true) };
+ return .{ .drawn = true, .end = end };
},
.jump => {
// Through memory or a register: where it goes. Straight: nothing to say.
@@ -386,6 +405,8 @@ pub const Disasm = struct {
if (std.mem.eql(u8, mn, "jmp")) if (ripSlot(row)) |slot| if ((zt.telescope.got(rec.moment(moment), slot) catch null)) |held| return a.went(held.value, .{ .addr = slot, .len = 8, .how = 1 }, moment);
return .{};
}
+ // `tied`: an instruction that moves rsp or rbp says the move first.
+ if (now.annotation == .tied) if (a.stackMove(now, row, moment, after, state, base)) |note| return note;
// A compare: the two values, then (once it has run) the flags it leaves.
if (std.mem.eql(u8, mn, "cmp") or std.mem.eql(u8, mn, "test")) {
const left = a.compared(row, moment, touches[0]);
@@ -463,6 +484,8 @@ pub const Disasm = struct {
marks.changed_heat = now.written(touch.addr, touch.len, .memory, 0);
}
};
+ // `tied`: the word by its name and the value, one hop (the stack's row holds the rest).
+ if (now.annotation == .tied) if (a.tiedWord(touch, moment, shown, marks, d.stage.first.view.h > 0 or d.stage.last().view.h > 0)) |note| return note;
// Narrower than a word, it is read at its width.
if (touch.len < 8) return .{ .drawn = true, .end = rows.narrow(u, x, y, shown, touch.addr, touch.len, room, marks).end };
return .{ .drawn = true, .end = rows.chain(u, x, y, shown, touch.addr, room, marks).end };
@@ -472,7 +495,8 @@ pub const Disasm = struct {
const at = value_at orelse return .{};
const value = rec.register(at, reg);
u.text(.mono, size, x, base_y, reg, t.dim);
- return .{ .drawn = true, .end = rows.chain(u, x + @as(f32, @floatFromInt(reg.len + 1)) * adv, y, rec.moment(at), value, room, .{}).end };
+ // `tied`: its first value (the registers' row has its chain, struck in the same frame).
+ return .{ .drawn = true, .end = rows.chain(u, x + @as(f32, @floatFromInt(reg.len + 1)) * adv, y, rec.moment(at), value, room, .{ .most = if (now.annotation == .tied) 1 else 6 }).end };
}
};
@@ -509,6 +533,155 @@ const Say = struct {
return bare[0 .. bare.len - 4];
}
+ /// rsp's mark in this step, for the amount an annotation moves it by: an echo of its strike.
+ fn rspHeat(a: Say, now: cursors.Now, base: usize) ui.Heat {
+ _ = a;
+ if (base != 1 or now.resting()) return .none;
+ // The amount is new in this row: no corner of rsp's last change under it.
+ return now.heat(now.registerAge(cursors.sp_index), null, now.since(.cpu, ties.strikeDelay(now, cursors.sp_index)));
+ }
+
+ /// `rsp -8` from `x` (after something else: `· rsp -8`): the amount
+ /// `by` (in bytes) struck with `heat`; then, `· role` faint and its
+ /// role, where the word it writes or reads has one.
+ fn move(a: Say, x: f32, by: i64, heat: ui.Heat, role: ?Role, after: bool) f32 {
+ var end = a.word(if (after) a.word(x, "\u{00b7}", t.faint) + adv else x, "rsp", t.dim);
+ const n: u64 = @abs(by);
+ const amount = if (n <= 9) a.u.print("{c}{d}", .{ @as(u8, if (by < 0) '-' else '+'), n }) else a.u.print("{c}0x{x}", .{ @as(u8, if (by < 0) '-' else '+'), n });
+ end = a.struck(end + adv, amount, heat);
+ if (role) |r| if (r.shows > 0) {
+ const v = a.u.faded(r.shows);
+ const b: Say = .{ .u = v, .rec = a.rec, .y = a.y, .x = a.x, .room = a.room };
+ end = b.word(b.word(end + adv, "\u{00b7}", t.faint) + adv, r.name, if (r.local) t.primary else t.dim);
+ };
+ return end;
+ }
+
+ /// A word's role in an annotation, and how much of it shows.
+ const Role = struct { name: []const u8, local: bool, shows: f32 = 1 };
+
+ /// `text` at `x` in primary, marked as `heat` says (armed, struck, held): where it ends.
+ fn struck(a: Say, x: f32, text: []const u8, heat: ui.Heat) f32 {
+ const w = @as(f32, @floatFromInt(text.len)) * adv;
+ var ink: ui.Ink = .{ .ink = ui.rgb(t.primary) };
+ if (a.u.written(.{ .x = x, .y = a.y, .w = w, .h = m.row }, heat)) |s| ink = s;
+ a.u.text(ink.face, size, x, rows.baseline(a.y), text, ink.ink);
+ return x + w;
+ }
+
+ /// Under `tied` (design/README.md, `insn`, "moves rsp or rbp"): the move
+ /// in its own terms, first, its amount struck with rsp's strike: `rsp -8
+ /// · saved rbp` (a `push`; its word's role once the step has made it),
+ /// `rsp +8 · saved rbp` (a `pop`), `rsp +0x20 · saved rbp` (a `leave`),
+ /// `rsp -0x18 3 words` (`sub`, `add`), `rbp = rsp` (and its value,
+ /// struck as rbp lands). Null for any other instruction.
+ fn stackMove(a: Say, now: cursors.Now, row: Insn, moment: u64, after: ?u64, state: Disasm.State, base: usize) ?Disasm.Note {
+ const mn = row.mnemonic();
+ const ops = row.operands();
+ const eql = std.mem.eql;
+ const regs = a.rec.registers[@min(moment, a.rec.end())];
+ const heat = if (state == .current) a.rspHeat(now, base) else ui.Heat.none;
+ var by: i64 = 0;
+ var touched: ?u64 = null;
+ var word_at = moment;
+ var counts = false;
+ if (eql(u8, mn, "push")) {
+ by = -8;
+ touched = regs.rsp -% 8;
+ // The word it makes has its role at the push's own stop (a recording that says so);
+ // else the moment after's, arriving with the touch.
+ if (wordName(a.u, a.rec, moment, regs.rsp -% 8, 8) == null) if (after) |aa| {
+ word_at = aa;
+ };
+ } else if (eql(u8, mn, "pop")) {
+ by = 8;
+ touched = regs.rsp;
+ } else if (eql(u8, mn, "leave")) {
+ by = @bitCast(regs.rbp +% 8 -% regs.rsp);
+ touched = regs.rbp;
+ } else if ((eql(u8, mn, "sub") or eql(u8, mn, "add")) and std.mem.startsWith(u8, ops, "rsp, ")) {
+ const n: i64 = @bitCast(parseImmediate(std.mem.trim(u8, ops[5..], " ")) orelse return null);
+ by = if (eql(u8, mn, "sub")) -n else n;
+ counts = true;
+ } else if (eql(u8, mn, "mov") and eql(u8, ops, "rbp, rsp")) {
+ var end = a.word(a.x, "rbp = rsp", t.primary);
+ // Its value once rbp has landed, struck with it.
+ const lands = ties.strikeDelay(now, cursors.bp_index);
+ const value_at: ?u64 = switch (state) {
+ .ran => after,
+ .current => if (after != null and now.landed(.cpu, lands)) after.? else null,
+ .ahead, .waiting => null,
+ };
+ if (value_at) |v| end = a.struck(end + adv, a.u.print("{x}", .{a.rec.register(v, "rbp")}), if (state == .current and base == 1) now.heat(now.registerAge(cursors.bp_index), null, now.since(.cpu, lands)) else .none);
+ return .{ .drawn = true, .end = end };
+ } else return null;
+ var role: ?Role = null;
+ if (touched) |w| if (wordName(a.u, a.rec, word_at, w, 8)) |named| {
+ role = .{ .name = named.name, .local = named.local };
+ // A push's word arrives with the touch's landing (12 f), never in a frame.
+ if (word_at != moment and state == .current and !now.resting() and now.plan.touch >= 0) role.?.shows = std.math.clamp((now.time - now.plan.touch - theme.time.tied.touch) / theme.time.quick, 0, 1);
+ };
+ var end = a.move(a.x, by, heat, role, false);
+ if (counts) end = a.word(end + 2 * adv, a.u.print("{d} words", .{@abs(by) / 8}), t.faint);
+ return .{ .drawn = true, .end = end };
+ }
+
+ /// Under `tied` (design/README.md, `insn`, and its fallbacks), a word of
+ /// memory the instruction reads or writes: a stack word by its name, bold
+ /// in the stack's ink (an unnamed one by its address), and the value it
+ /// holds at the access's width, one hop: `next → 405010`, `n ◂ 15`,
+ /// `7fffffffecd0 ◂ 1`; a word a view on screen shows (`view`), its
+ /// address and one hop, `405038 → 405010`. The name (or address) framed
+ /// as read in the step, a write's value struck. Null for a word no pane
+ /// shows: the whole chain stands.
+ fn tiedWord(a: Say, touch: Recording.Touch, moment: u64, shown: Recording.Moment, marks: rows.Marks, view: bool) ?Disasm.Note {
+ const u = a.u;
+ const region = rows.regionOf(a.rec.moment(moment), touch.addr);
+ const named = if (region == .stack) wordName(u, a.rec, moment, touch.addr, touch.len) else null;
+ // The band's view is a dump of the heap. A word no pane shows (a global) keeps its whole
+ // chain, its data name in place of the address where it has one (`head → 405050 ◂ 9`).
+ if (region != .stack and !(view and region == .heap)) return a.globalWord(touch, moment, shown, marks);
+ const base_y = rows.baseline(a.y);
+ const mid = a.y + m.row / 2;
+ var x = a.x;
+ const w = if (named) |n| @as(f32, @floatFromInt(n.name.len)) * adv else ui.Value.of(touch.addr, true).width();
+ if (marks.read == 0) u.read(.{ .x = x, .y = a.y, .w = w, .h = m.row }, marks.read_shows);
+ if (named) |n| u.text(.mono_bold, size, x, base_y, n.name, rows.ink(.stack)) else _ = u.address(x, base_y, touch.addr, .{ .ink = ui.rgb(rows.ink(region)) });
+ x += w;
+ const len: usize = @intCast(@min(touch.len, 8));
+ var raw: [8]u8 = @splat(0);
+ var known: [8]bool = @splat(false);
+ shown.read(touch.addr, raw[0..len], known[0..len]) catch return .{ .drawn = true, .end = x };
+ if (std.mem.indexOfScalar(bool, known[0..len], false) != null) {
+ x = u.arrow(x, mid, .points);
+ u.unknown(.{ .x = x, .y = a.y, .w = 24, .h = m.row });
+ return .{ .drawn = true, .end = x + 24 };
+ }
+ const v = std.mem.readInt(u64, &raw, .little);
+ const pointer = len == 8 and rows.regionOf(shown, v) != .none;
+ x = u.arrow(x, mid, if (pointer) .points else .holds);
+ // The value, its first hop alone (a code address with its name), cut with `…` where the row ends; a write's struck.
+ return .{ .drawn = true, .end = rows.chain(u, x, a.y, shown, v, a.room, .{ .first = if (marks.changed == 1) marks.changed_heat else .none, .most = 1 }).end };
+ }
+
+ /// Under `tied`, a word no pane shows: its whole chain with its data
+ /// name (`head`, `big+4096`) in place of its address, bold in its
+ /// region's ink, read in the step; a write's value struck. Null where it
+ /// has no name (the chain as `whole` draws it).
+ fn globalWord(a: Say, touch: Recording.Touch, moment: u64, shown: Recording.Moment, marks: rows.Marks) ?Disasm.Note {
+ if (touch.len != 8) return null;
+ const full_name = ui.symbol(a.u, a.rec.strings.get(touch.addr) orelse return null);
+ // `head+0` is `head`.
+ const name = if (std.mem.endsWith(u8, full_name, "+0")) full_name[0 .. full_name.len - 2] else full_name;
+ const u = a.u;
+ const w = @as(f32, @floatFromInt(name.len)) * adv;
+ if (marks.read == 0) u.read(.{ .x = a.x, .y = a.y, .w = w, .h = m.row }, marks.read_shows);
+ u.text(.mono_bold, size, a.x, rows.baseline(a.y), name, rows.ink(rows.regionOf(a.rec.moment(moment), touch.addr)));
+ const v = (Recording.word(shown, touch.addr, 8) catch null) orelse return .{ .drawn = true, .end = a.x + w };
+ const x = u.arrow(a.x + w, a.y + m.row / 2, if (rows.regionOf(shown, v) != .none) .points else .holds);
+ 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 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) };
@@ -645,6 +818,39 @@ const Say = struct {
}
};
+/// The pc of the instruction a step's touch leaves from (`cursors.stackTouch`), kept for the step.
+var touch_memo: struct { rec: ?*const Recording = null, from: u64 = 0, to: u64 = 0, pc: ?u64 = null } = .{};
+
+fn touchPc(rec: *const Recording, now: cursors.Now) ?u64 {
+ if (touch_memo.rec != rec or touch_memo.from != now.stops[1] or touch_memo.to != now.stops[0]) {
+ const tt = cursors.stackTouch(rec, now.stops[1], now.stops[0]);
+ touch_memo = .{ .rec = rec, .from = now.stops[1], .to = now.stops[0], .pc = if (tt) |x| rec.register(x.at, "rip") else null };
+ }
+ return touch_memo.pc;
+}
+
+/// A stack word's name under `tied`, its role at moment `i` (a local's
+/// name, primary; `saved rbp`, `argv[0]`, dim), for an access of `len`
+/// bytes at `addr`; null where it has none, or where the local the word is
+/// named by does not hold those bytes (two locals in a word: never a guess).
+fn wordName(u: ui.Ui, rec: *const Recording, i: u64, addr: u64, len: u64) ?struct { name: []const u8, local: bool } {
+ const regs = rec.registers[@min(i, rec.end())];
+ var one: [1]zt.telescope.Slot = undefined;
+ const word = addr & ~@as(u64, 7);
+ const got = zt.telescope.slots(rec.moment(i), &regs, word, &one) catch return null;
+ if (got.len == 0) return null;
+ return switch (got[0].role) {
+ .none, .return_address => null,
+ // Of the locals that share the word (`Slot.also`), the one the access is to.
+ .local => |first| for ([_]?zt.telescope.Local{first} ++ got[0].also) |maybe| {
+ const l = maybe orelse continue;
+ const at = word -% @as(u64, @bitCast(@as(i64, l.offset)));
+ if (if (l.size > 0) addr >= at and addr + len <= at + l.size else addr == at) break .{ .name = l.name, .local = true };
+ } else null,
+ else => |role| .{ .name = context.Stack.roleName(u, role, (Recording.word(rec.moment(i), addr & ~@as(u64, 7), 8) catch null) orelse 1).name, .local = false },
+ };
+}
+
/// How many rows of arguments hang under `row` while it is current at
/// `moment`: a direct call's, a `syscall`'s; 0 for anything else.
pub fn hanging(u: ui.Ui, rec: *const Recording, row: Insn, moment: u64) usize {
diff --git a/anim/src/graph.zig b/anim/src/graph.zig
index 7066580..01b4ac7 100644
--- a/anim/src/graph.zig
+++ b/anim/src/graph.zig
@@ -1942,6 +1942,7 @@ fn drawPills(u: ui.Ui, v: Instant) void {
}
const o = u.faded(shows);
const r: ui.Rect = .{ .x = x, .y = y, .w = n.w, .h = n.h };
+ @import("ties.zig").anchor(u, .{ .block = n.start }, r);
const base_y = rows.baseline(y);
if (n.folded > 0) {
pill(o, r, ui.rgb(theme.color.page), ui.rgb(theme.color.rule), theme.stroke.rule, true);
@@ -2023,7 +2024,9 @@ pub const Blocks = struct {
defer u.unclip();
const now = b.cursor.now(placed);
const rule = theme.stroke.rule;
- const room: [2]f32 = .{ box.w - 2 * rule, box.h - m.tag - rule };
+ // Drawn larger (a column's drawing across both columns): laid out in its room at its own size, then scaled.
+ const z = placed.value(b.stage.zoom);
+ const room: [2]f32 = .{ (box.w - 2 * rule) / z, (box.h - m.tag - rule) / z };
const v = instant(f.scratch, now, b.form, room) orelse {
_ = u.panel(box.w, box.h, "its blocks", .{ .focus = b.focus });
return;
@@ -2033,8 +2036,11 @@ pub const Blocks = struct {
const short = name[0 .. std.mem.lastIndexOfScalar(u8, name, '+') orelse name.len];
const title = if (std.mem.indexOfScalar(u8, full, '!')) |bang| u.print("the blocks of {s} \u{00b7} {s}", .{ short, full[0..bang] }) else u.print("the blocks of {s}", .{short});
_ = u.panel(box.w, box.h, title, .{ .focus = b.focus, .note = if (v.g.rings.len > 0) "its blocks \u{00b7} the visits so far \u{00b7} the path \u{00b7} the loops' turns" else "its blocks \u{00b7} the visits so far \u{00b7} the path" });
- u.clip(.{ .x = rule, .y = m.tag, .w = room[0], .h = room[1] });
- const o = u.moved(rule + v.at[0], m.tag + v.at[1]);
+ u.clip(.{ .x = rule, .y = m.tag, .w = room[0] * z, .h = room[1] * z });
+ var big = u.moved(rule, m.tag);
+ big.at.xf = big.at.xf.mul(.scale(z, z));
+ big.at.scale *= z;
+ const o = big.moved(v.at[0], v.at[1]);
drawEdges(o, v);
drawTurns(o, v);
drawPills(o, v);
diff --git a/anim/src/root.zig b/anim/src/root.zig
index dca9a60..fcdb572 100644
--- a/anim/src/root.zig
+++ b/anim/src/root.zig
@@ -63,6 +63,14 @@ pub const Caption = words.Caption;
pub const Label = words.Label;
pub const Veil = words.Veil;
pub const Legend = words.Legend;
+/// The column (design/README.md, "column (an experiment)"): beat by beat,
+/// the panes a beat is about on the left, its text beside them, the rest
+/// folded to their tags on the shelf (`column.zig`).
+const columns = @import("column.zig");
+pub const Column = columns.Column;
+pub const column = columns.column;
+/// A column pane's rows: what the column has left.
+pub const column_rest = columns.rest;
/// The page behind every scene: `pub const background = canim.background;`.
pub const background: u32 = theme.color.page;
@@ -334,7 +342,7 @@ pub fn context(s: *anim.Frame, cursor_: Cursor, options: Context.Options) Contex
.registers = add(s, Registers{ .cursor = at, .stage = stage, .syscalls = options.syscalls, .quiet = options.quiet, .moves = moves }),
.stack = add(s, Stack{ .cursor = at, .stage = stage }),
.backtrace = add(s, Backtrace{ .cursor = at, .stage = stage, .lens = options.backtrace }),
- .clock = add(s, Clock{ .cursor = at, .map = whole }),
+ .clock = add(s, Clock{ .cursor = at, .map = whole, .stage = stage }),
};
}
@@ -407,4 +415,5 @@ test {
_ = @import("syscalls.zig");
_ = objects;
_ = words;
+ _ = columns;
}
diff --git a/anim/src/rows.zig b/anim/src/rows.zig
index 03c5898..08f1fb2 100644
--- a/anim/src/rows.zig
+++ b/anim/src/rows.zig
@@ -59,6 +59,8 @@ pub const Marks = struct {
/// How much the hops after the first show: they fade out as the memory
/// they read is about to change (`Now.following`).
hops: f32 = 1,
+ /// How many hops at most: a `tied` annotation's register is its first value (`rax 405010`).
+ most: usize = 6,
};
/// `chain` of a memory access narrower than a word: its address, then what
@@ -117,7 +119,7 @@ pub fn chain(u: ui.Ui, x: f32, y: f32, moment: Recording.Moment, value: u64, roo
const mid = y + row_h / 2;
var hops: Hops = .{};
var at = x;
- for (links, 0..) |link, i| {
+ for (links[0..@min(links.len, marks.most)], 0..) |link, i| {
const pointer = link.region != .none;
const shown = ui.Value.of(link.value, pointer);
const w = shown.width();
@@ -278,7 +280,7 @@ fn ripFlag(u: ui.Ui, x: f32, y: f32, flag: Flag, set: bool) void {
}
/// A slot's role as it was before the step, and how far (0 to 1) the role it has now has come in over it.
-pub const Role = struct { name: []const u8, local: bool = false, going: f32 = 1, from_rsp: ?i64 = null };
+pub const Role = struct { name: []const u8, local: bool = false, going: f32 = 1, from_rsp: ?i64 = null, offset_going: ?f32 = null };
/// `slot`: a word of the stack: a lane to 112 for `row` pins (`pins`, the
/// registers that hold its address); its offset from rsp (`from_rsp`
@@ -292,9 +294,9 @@ pub fn slot(u: ui.Ui, y: f32, w: f32, moment: Recording.Moment, addr: u64, from_
const s = theme.metric.slot;
if (pins.len > 0 and pin_shows > 0) u.faded(pin_shows).pinRow(s.lane, y, pins, theme.color.region.stack);
// An offset that changes with rsp (the window held, or moved by more than the slide) crossfades as a role does.
- if (was) |o| if (o.from_rsp) |old| if (old != from_rsp and o.going < 1) {
- offset(u.faded(1 - o.going), y, old);
- offset(u.faded(o.going), y, from_rsp);
+ if (was) |o| if (o.from_rsp) |old| if (old != from_rsp and (o.offset_going orelse o.going) < 1) {
+ offset(u.faded(1 - (o.offset_going orelse o.going)), y, old);
+ offset(u.faded(o.offset_going orelse o.going), y, from_rsp);
} else offset(u, y, from_rsp) else offset(u, y, from_rsp) else offset(u, y, from_rsp);
var lead = marks;
lead.first = .none;
@@ -333,10 +335,14 @@ fn offset(u: ui.Ui, y: f32, from_rsp: i64) void {
/// `slot` `free`: a word above rsp the stack has not reached, shown while
/// the window is held for the camera: its offset, its address at 60%, its
/// word faint, no chain, no pin.
-pub fn free(u: ui.Ui, y: f32, moment: Recording.Moment, addr: u64, from_rsp: i64, lead: usize) void {
+pub fn free(u: ui.Ui, y: f32, moment: Recording.Moment, addr: u64, from_rsp: i64, lead: usize, was: ?Role) void {
const s = theme.metric.slot;
const base = baseline(y);
- offset(u, y, from_rsp);
+ // An offset whose base the step moves crossfades, as a slot's does.
+ if (was) |o| if (o.from_rsp) |old| if (old != from_rsp and o.going < 1) {
+ offset(u.faded(1 - o.going), y, old);
+ offset(u.faded(o.going), y, from_rsp);
+ } else offset(u, y, from_rsp) else offset(u, y, from_rsp) else offset(u, y, from_rsp);
const end = u.address(s.address, base, addr, .{ .ink = ui.mix(theme.color.region.stack, theme.color.page, theme.metric.context.lead_alpha), .lead = lead });
const word = (Recording.word(moment, addr, 8) catch null) orelse return u.unknown(.{ .x = end + m.arrow_w, .y = y, .w = 24, .h = row_h });
u.text(.mono, size, end + m.arrow_w, base, u.print("{x}", .{word}), t.faint);
diff --git a/anim/src/stage.zig b/anim/src/stage.zig
index a03c8bd..bbf5887 100644
--- a/anim/src/stage.zig
+++ b/anim/src/stage.zig
@@ -14,7 +14,7 @@ pub const Part = enum { band, view, source, disasm, registers, stack, backtrace,
pub const Stage = struct {
first: Split,
- moves: [8]Move = undefined,
+ moves: [32]Move = undefined,
count: usize = 0,
/// Seconds into the band's lens rising from its bytes (`Context.establish`,
/// `ties.rise`); far past it, for a scene that does not raise one.
@@ -31,12 +31,26 @@ pub const Stage = struct {
hold_in: anim.Value,
/// The registers panel's rows (the scene's, `layout.fit`): every split it changes to keeps them. 0: as the split has it.
registers_rows: f32 = 0,
+ /// 0 the working frame, 1 the column (`column.zig`): the clock under the text column.
+ column: anim.Value,
+ /// How much larger the band's drawing is drawn than its lens's size (a
+ /// column's `on`, `above`: the drawing across both columns), its tag not.
+ zoom: anim.Value,
const Move = struct { from: Split, to: Split, p: anim.Value };
/// A stage at `split`, made where a scene's components can keep a pointer to it.
pub fn init(s: *anim.Frame, split: Split) *Stage {
- return s.new(Stage{ .first = split, .rise = s.value(std.math.floatMax(f32)), .drawing = s.value(1), .view = s.value(1), .hold = s.value(-1), .hold_free = s.value(0), .hold_in = s.value(0) });
+ return s.new(Stage{ .first = split, .rise = s.value(std.math.floatMax(f32)), .drawing = s.value(1), .view = s.value(1), .hold = s.value(-1), .hold_free = s.value(0), .hold_in = s.value(0), .column = s.value(0), .zoom = s.value(1) });
+ }
+
+ /// Every panel to its box in `to`, as it is (no fit), over `seconds` on
+ /// `glide`, the drawing not faded: the column's moves (`column.zig`).
+ pub fn glide(st: *Stage, s: *anim.Frame, to: Split, seconds: f32) void {
+ const p = s.value(0);
+ st.moves[st.count] = .{ .from = st.last(), .to = to, .p = p };
+ st.count += 1;
+ s.play(.{p.to(1)}, .{ .seconds = seconds, .ease = anim.ease.linear });
}
/// The split the stage ends in, after every move so far.
diff --git a/anim/src/theme.zig b/anim/src/theme.zig
index 8d4b044..90ad36b 100644
--- a/anim/src/theme.zig
+++ b/anim/src/theme.zig
@@ -767,6 +767,8 @@ pub const metric = struct {
pub const tie = struct {
pub const thread_x = 54;
pub const link_lane = 950;
+ /// The `touch`'s, from a row of the disassembly to a word of the stack.
+ pub const touch_lane = 956;
pub const projection_lane = 962;
pub const radius = 8;
pub const projection_radius = 6;
@@ -1034,6 +1036,24 @@ pub const time = struct {
pub const out = 0.20;
pub const names = 0.20;
};
+ /// Under `tied` (design/README.md, `touch`, `carry`, `travel`,
+ /// `follow`): the touch draws `touch` (`touch_long` past six rows); the
+ /// carry `carry` (`carry_long` past eight); rsp's and rbp's pins travel
+ /// `stack_pin` to the next row and `stack_pin_row` a further one,
+ /// `stack_pin_most` at most (at a run `run_ease`, 2 f a row, `run_pin_most`);
+ /// the window follows `follow`, 2 f a further slot, `follow_most` at most.
+ pub const tied = struct {
+ pub const touch = 0.20;
+ pub const touch_long = 0.30;
+ pub const carry = 0.30;
+ pub const carry_long = 0.40;
+ pub const stack_pin = 0.40;
+ pub const stack_pin_row = 0.10;
+ pub const stack_pin_most = 0.80;
+ pub const run_pin_most = 16.0 / 60.0;
+ pub const follow = 0.40;
+ pub const follow_most = 0.60;
+ };
/// `leave` (and `turn`, round a ring's foot): the jump fires; the
/// compare's chips framed as read from `chips` (the CPU's slot); the
/// edge it takes drawn gold over `edge`, ending as the mark sets off at
diff --git a/anim/src/ties.zig b/anim/src/ties.zig
index 58ada36..1b6a6ed 100644
--- a/anim/src/ties.zig
+++ b/anim/src/ties.zig
@@ -25,6 +25,7 @@ const zt = @import("ztrace");
const ui = @import("ui.zig");
const cursors = @import("cursor.zig");
const rows = @import("rows.zig");
+const Recording = @import("Recording.zig");
const Stage = @import("stage.zig").Stage;
const theme = ui.theme;
const time = theme.time;
@@ -55,6 +56,13 @@ pub const Place = union(enum) {
source,
pc,
run: usize,
+ /// A row of the disassembly by its key (an instruction's address, a
+ /// descent's head's `descent.headKey`); the descent's floor, where the
+ /// kernel's window opens; a graph's pill by its block's address: what a
+ /// column's bubble is level with (`column.zig`).
+ row: u64,
+ floor,
+ block: u64,
fn key(p: Place) u64 {
const low = (1 << 56) - 1;
@@ -72,6 +80,9 @@ pub const Place = union(enum) {
.pc => 11 << 56,
.run => |k| 12 << 56 | @as(u64, k),
.dump_pin => |a| 13 << 56 | (a & low),
+ .row => |a| 14 << 56 | (a & low),
+ .floor => 15 << 56,
+ .block => |a| 16 << 56 | (a & low),
};
}
};
@@ -80,6 +91,10 @@ pub const Place = union(enum) {
/// where its pin lane runs (canvas pixels: x, the first row's top, the
/// row's height). A link to a word outside it ends at its edge.
pub var stack_window: ?struct { first: u64, slots: usize, x: f32, top: f32, row: f32 } = null;
+/// The disassembly's row the step's `touch` and `carry` leave from or reach,
+/// this frame (canvas pixels: its right rule's x, the row's top, that x, its
+/// bottom), where it is drawn (`Disasm.insn`).
+pub var touch_row: ?[4]f32 = null;
/// The source's line waits (a `descent`: the pc is in code without source):
/// the thread waits with it, primary and 2 units.
pub var thread_waits = false;
@@ -110,10 +125,15 @@ pub fn find(place: Place) ?[4]f32 {
/// call is back; in a continue, a wave, 2 f after the one above it. Its
/// pin and its link go with it.
pub fn strikeDelay(now: cursors.Now, i: usize) f32 {
+ // Under `tied` rsp and rbp strike as their pins land (`Now.pinLands`), not in the CPU's slot.
+ 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];
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 (now.registerAge(k) == 0) before += 1;
}
if (now.plan.wave) return before * time.continue_wave;
@@ -188,6 +208,7 @@ pub const Ties = struct {
defer said = 0;
defer stack_window = null;
defer thread_waits = false;
+ defer touch_row = null;
const now = g.cursor.now(at);
// Diving or surfacing, the panels are on their way: no ties; nor while the map alone is looked at.
for (@import("context.zig").zoomed) |z| if (z != null) return;
@@ -200,8 +221,107 @@ pub const Ties = struct {
if (g.threaded) thread(raw.faded(@import("context.zig").thread_shows), at, k);
if (g.beat) |b| named(raw, at, now, k, split, b);
if (!now.walking()) return;
- if (!g.quiet) g.link(raw, at, now, k, split);
- g.projection(raw, at, now, k, split);
+ const linked = !g.quiet and g.link(raw, at, now, k, split);
+ const projected = g.projection(raw, at, now, k, split);
+ // Three lines at most: the touch is the first to give way (to an echo), where a step draws a link and a projection.
+ if (!(linked and projected)) g.touch(raw, at, now, k, split);
+ g.carry(raw, at, now, k);
+ }
+
+ /// `touch` (design/README.md, "4. Ties"), `tied`, in a walked step: this
+ /// instruction reads or writes that word. From the disassembly's right
+ /// rule level with the row, into the gutter's middle lane (x 956), up or
+ /// down it to the word's height, onto the stack's rule, a head 7 by 8 on
+ /// it: 2 units in read's colour or write's vermilion, 12 f (18 f past six
+ /// rows), `standard`, from `Plan.touch`; held to the advance and drawn
+ /// back into the row with it (12 f), or, a load carried, as the carry
+ /// leaves the word. Only to a word on show: the window is there first.
+ fn touch(g: *const Ties, raw: ui.Ui, at: anim.Placed, now: cursors.Now, k: f32, split: theme.layout.Split) void {
+ if (now.plan.touch < 0 or now.time < now.plan.touch) return;
+ const row = touch_row orelse return;
+ const tt = cursors.stackTouch(g.cursor.rec, now.stops[1], now.stops[0]) orelse return;
+ const word = find(.{ .word = tt.addr & ~@as(u64, 7) }) orelse return;
+ const lane_pin = find(.{ .slot_pin = tt.addr & ~@as(u64, 7) }) orelse return;
+ const lane = at.xf.apply(.{ theme.metric.tie.touch_lane, 0 })[0];
+ // Onto the stack's rule nearer the lane: its left in the state column, its right
+ // where it stands under the disassembly (a column's beat), the head pointing back.
+ const left = lane_pin[0] - theme.metric.slot.lane * k;
+ const rule = if (left > lane) left else at.xf.apply(.{ split.stack.x + split.stack.w, 0 })[0];
+ const ya = (row[1] + row[3]) / 2;
+ const yb = (word[1] + word[3]) / 2;
+ const long = @abs(yb - ya) > 6 * theme.metric.context.row * k;
+ const drawn = cursors.standard(std.math.clamp((now.time - now.plan.touch) / @as(f32, if (long) time.tied.touch_long else time.tied.touch), 0, 1));
+ const back_at = if (now.plan.carry >= 0 and !tt.write) now.plan.carry else now.plan.advance;
+ const back = cursors.standard(std.math.clamp((now.time - back_at) / time.quick, 0, 1));
+ if (back >= 1) return;
+ const color = theme.mark(if (tt.write) .write else .read).solid;
+ raw.route(&.{ .{ row[0], ya }, .{ lane, ya }, .{ lane, yb }, .{ rule, yb } }, color, .{ .width = theme.stroke.tie.projection * k, .head = .{ 7 * k, 8 * k }, .progress = @min(drawn, 1 - back), .radius = theme.metric.tie.radius * k });
+ }
+
+ /// `carry` (design/README.md, "4. Ties"; `Levels.carry`), in a walked
+ /// step: this value went from that word into this register, or from this
+ /// register into that word (a load, a store, a push's register, a pop's).
+ /// 2 units in primary, an open chevron 7 by 8 drawn in two strokes: from
+ /// the source's rule level with its row, along the gutter's right lane
+ /// (x 962) between the stack and the registers, onto the destination's
+ /// rule; 18 f (24 f past eight rows), `standard`, from `Plan.carry`, a
+ /// store's register framed as read the 6 f before; drawn back as the
+ /// destination strikes (18 f). With `carry_value` the value's digits ride
+ /// its head on a `raised` chip, landing as the strike.
+ fn carry(g: *const Ties, raw: ui.Ui, at: anim.Placed, now: cursors.Now, k: f32) void {
+ if (now.plan.carry < 0) return;
+ const rec = g.cursor.rec;
+ const tt = cursors.stackTouch(rec, now.stops[1], now.stops[0]) orelse return;
+ const how = cursors.carried(rec, tt) orelse return;
+ const i = @import("context.zig").index(how.reg) orelse return;
+ const reg = find(.{ .register = i }) orelse return;
+ const panel = find(.registers) orelse return;
+ const word = find(.{ .word = tt.addr & ~@as(u64, 7) }) orelse return;
+ const lane_pin = find(.{ .slot_pin = tt.addr & ~@as(u64, 7) }) orelse return;
+ const stack_rule = lane_pin[0] - theme.metric.slot.lane * k;
+ const lane = at.xf.apply(.{ theme.metric.tie.projection_lane, 0 })[0];
+ const y_reg = (reg[1] + reg[3]) / 2;
+ const y_word = (word[1] + word[3]) / 2;
+ const strike = if (how.load) now.plan.at[0] else now.plan.at[1];
+ // A store's register framed as read first (6 f), held while its value goes.
+ if (!how.load) {
+ const inv = at.xf.invert();
+ const a = inv.apply(.{ reg[0], reg[1] });
+ const c = inv.apply(.{ reg[2], reg[3] });
+ const shows = std.math.clamp((now.time - now.plan.carry + time.read.in) / time.read.in, 0, 1) * (1 - std.math.clamp((now.time - now.plan.advance) / time.read.out, 0, 1));
+ (ui.Ui{ .f = raw.f, .at = at }).read(.{ .x = a[0], .y = a[1], .w = c[0] - a[0], .h = c[1] - a[1] }, shows);
+ }
+ if (now.time < now.plan.carry) return;
+ const far = @abs(y_reg - y_word) > 8 * theme.metric.context.row * k;
+ const drawn = cursors.standard(std.math.clamp((now.time - now.plan.carry) / @as(f32, if (far) time.tied.carry_long else time.tied.carry), 0, 1));
+ const back = cursors.standard(std.math.clamp((now.time - strike) / (18.0 / 60.0), 0, 1));
+ if (back >= 1) return;
+ const points: [4]ui.Vec = if (how.load) .{ .{ stack_rule, y_word }, .{ lane, y_word }, .{ lane, y_reg }, .{ panel[0], y_reg } } else .{ .{ panel[0], y_reg }, .{ lane, y_reg }, .{ lane, y_word }, .{ stack_rule, y_word } };
+ const color = theme.color.text.primary;
+ raw.route(&points, color, .{ .width = theme.stroke.tie.projection * k, .head = null, .progress = drawn, .from = back, .radius = theme.metric.tie.radius * k });
+ // The open chevron at its head, two strokes.
+ const tip = along(&points, drawn);
+ const behind = along(&points, @max(drawn - 0.02, 0));
+ const dir = sk.math.normalize(if (sk.math.distance(tip, behind) > 0.01) tip - behind else points[3] - points[2]);
+ const side = sk.math.scale(sk.math.perp(dir), 4 * k);
+ const tail = tip - sk.math.scale(dir, 7 * k);
+ raw.line(tail + side, tip, color, theme.stroke.tie.projection * k);
+ raw.line(tail - side, tip, color, theme.stroke.tie.projection * k);
+ // `value`: the digits on a raised chip at the head, gone as the strike lands.
+ if (now.plan.carry_value) {
+ const shows = 1 - std.math.clamp((now.time - strike) / time.strike.in, 0, 1);
+ if (shows <= 0) return;
+ const value = if (how.load) (Recording.word(rec.moment(now.stops[0]), tt.addr, @intCast(@min(tt.len, 8))) catch null) orelse return else rec.register(tt.at, how.reg);
+ const v = raw.faded(shows);
+ const text = v.print("{x}", .{value});
+ const size = theme.size.mono.context * k;
+ const w = v.width(.mono, size, text) + 12 * k;
+ const h = theme.metric.context.row * k;
+ // Beside the head, on the lane's outer side: never over the rules.
+ const box: ui.Rect = .{ .x = lane - w - 6 * k, .y = tip[1] - h / 2, .w = w, .h = h };
+ v.fill(box, theme.color.raised);
+ v.text(.mono_bold, size, box.x + 6 * k, theme.baseline(box.y, h, size), text, theme.color.text.bright);
+ }
}
/// The gold thread: the current line and its instructions, one mark.
@@ -225,20 +345,23 @@ pub const Ties = struct {
/// The step's link: the first register it struck that now holds the
/// address of a pinned thing (a stack slot, a node, a view's row). rip
/// and rsp are where execution and the stack are, and have none.
- fn link(g: *const Ties, raw: ui.Ui, at: anim.Placed, now: cursors.Now, k: f32, split: theme.layout.Split) void {
+ fn link(g: *const Ties, raw: ui.Ui, at: anim.Placed, now: cursors.Now, k: f32, split: theme.layout.Split) bool {
const rec = g.cursor.rec;
- const regs = (now.moment().regs(rec.tid) catch null) orelse return;
+ const regs = (now.moment().regs(rec.tid) catch null) orelse return false;
for (theme.metric.all_registers[0..16]) |name| {
const i = @import("context.zig").index(name).?;
if (now.registerAge(i) != 0 or std.mem.eql(u8, name, "rsp")) continue;
+ // `tied`: rbp's move is its pin's flight in the stack's lane, not a link.
+ if (i == cursors.bp_index and now.pinGone(1) != null) continue;
const value = regs.named(name) orelse continue;
const since = linkSince(now, i);
const l = time.link;
const node = find(.{ .node_pin = value }) != null;
const drawn = cursors.standard(std.math.clamp((since - l.after) / linkTime(if (node) .node else .slot), 0, 1));
const back = std.math.clamp((now.time - now.plan.advance) / l.out, 0, 1);
- if (linkTo(raw, at, now, k, split, name, value, drawn, back)) return;
+ if (linkTo(raw, at, now, k, split, name, value, drawn, back)) return true;
}
+ return false;
}
/// A link from register `name` to what it points at (`value`): a node's
@@ -340,7 +463,7 @@ pub const Ties = struct {
/// The step's projection: the first run of bytes it read or wrote in
/// the lens's dump that a part of the drawing is made of.
- fn projection(g: *const Ties, raw: ui.Ui, at: anim.Placed, now: cursors.Now, k: f32, split: theme.layout.Split) void {
+ fn projection(g: *const Ties, raw: ui.Ui, at: anim.Placed, now: cursors.Now, k: f32, split: theme.layout.Split) bool {
const rec = g.cursor.rec;
const kinds = [2]struct { spans: []const @import("Recording.zig").Span, role: theme.Role }{
.{ .spans = rec.written(now.stops[1], now.stops[0]), .role = .write },
@@ -360,11 +483,12 @@ pub const Ties = struct {
const node_addr = if (stacked) span.addr else nodeOf(word) orelse continue;
const over = find(.{ .node_address = node_addr }) orelse continue;
const p = time.project;
- const since = now.since(.memory, 0);
+ // Under `tied`, once what made them has shown (a call's push, rsp's pin landed: `Plan.project`).
+ const since = if (now.plan.project >= 0) now.time - now.plan.project else now.since(.memory, 0);
const bracket = std.math.clamp(since / p.bracket, 0, 1);
const drawn = cursors.standard(std.math.clamp((since - p.bracket) / @as(f32, if (stacked) p.far else p.draw), 0, 1));
const out = 1 - std.math.clamp((now.time - now.plan.advance) / p.out, 0, 1);
- if (bracket <= 0 or out <= 0) return;
+ if (bracket <= 0 or out <= 0) return true;
const color = theme.mark(kind.role).solid;
const v = raw.faded(out);
const tie = [2]f32{ theme.metric.bracket.tie[0] * k, theme.metric.bracket.tie[1] * k };
@@ -386,7 +510,7 @@ pub const Ties = struct {
v.fill(.{ .x = over[0], .y = over[3] - 3 * k, .w = 3 * k, .h = 8 * k }, color);
v.fill(.{ .x = over[2] - 3 * k, .y = over[3] - 3 * k, .w = 3 * k, .h = 8 * k }, color);
}
- return;
+ return true;
}
const lane = at.xf.apply(.{ theme.metric.tie.projection_lane, 0 })[0];
const top = at.xf.apply(.{ 0, split.band.y + theme.metric.context.tag + theme.metric.lens.top_lane })[1];
@@ -397,8 +521,9 @@ pub const Ties = struct {
v.fill(.{ .x = over[0], .y = over[1] - 5 * k, .w = 3 * k, .h = 8 * k }, color);
v.fill(.{ .x = over[2] - 3 * k, .y = over[1] - 5 * k, .w = 3 * k, .h = 8 * k }, color);
}
- return;
+ return true;
};
+ return false;
}
};
diff --git a/anim/src/words.zig b/anim/src/words.zig
index 5411385..6549dfb 100644
--- a/anim/src/words.zig
+++ b/anim/src/words.zig
@@ -24,17 +24,26 @@ pub const Clock = struct {
box: Rect = .{ .x = theme.canvas.stage.x, .y = theme.canvas.clock_y - 12, .w = theme.canvas.stage.w, .h = 24 },
/// The map: with `CANIM_MAP`, drawn over everything (`Map.wholeMap`).
map: ?*const @import("map.zig").Map = null,
+ /// The stage: in the column (`Stage.column`) the clock is under the text column alone.
+ stage: ?*const @import("stage.zig").Stage = null,
pub fn draw(k: *const Clock, f: *sk.Frame, at: anim.Placed) void {
const u = fixed(f, at, 0);
const c = theme.canvas;
const now = k.cursor.now(at);
- const stage = c.stage;
- // The margins are the page's, whatever the camera has brought under them.
- u.fill(.{ .x = -c.width, .y = -c.height, .w = 3 * c.width, .h = c.height + stage.y }, theme.color.page);
- u.fill(.{ .x = -c.width, .y = stage.y + stage.h, .w = 3 * c.width, .h = 2 * c.height }, theme.color.page);
- u.fill(.{ .x = -c.width, .y = 0, .w = c.width + stage.x - 8, .h = c.height }, theme.color.page);
- u.fill(.{ .x = stage.x + stage.w + 8, .y = 0, .w = c.width, .h = c.height }, theme.color.page);
+ const in_column = if (k.stage) |st| at.value(st.column) else 0;
+ const whole = c.stage;
+ // The margins are the page's, whatever the camera has brought under them
+ // (in the column the panes run on under the floor, 888 to 1032).
+ u.fill(.{ .x = -c.width, .y = -c.height, .w = 3 * c.width, .h = c.height + whole.y }, theme.color.page);
+ const floor_x: f32 = if (in_column > 0) theme.layout.state.x - c.gutter / 2 else -c.width;
+ u.fill(.{ .x = floor_x, .y = whole.y + whole.h, .w = 3 * c.width, .h = 2 * c.height }, theme.color.page);
+ u.fill(.{ .x = -c.width, .y = 0, .w = c.width + whole.x - 8, .h = c.height }, theme.color.page);
+ u.fill(.{ .x = whole.x + whole.w + 8, .y = 0, .w = c.width, .h = c.height }, theme.color.page);
+ // The rule: the stage's width, or the text column's.
+ var stage = whole;
+ stage.x = std.math.lerp(whole.x, theme.layout.state.x, theme.ease(.glide, in_column));
+ stage.w = whole.x + whole.w - stage.x;
u.fill(.{ .x = stage.x, .y = c.clock_y - 1, .w = stage.w, .h = theme.stroke.rule }, theme.color.rule);
// Time itself: still while a step plays at a walk or a run; once its
// mark has landed, the step's piece fades in (12 f, 8 at a run) and
diff --git a/anim/test/column.script b/anim/test/column.script
new file mode 100644
index 0000000..4a308d1
--- /dev/null
+++ b/anim/test/column.script
@@ -0,0 +1,10 @@
+# The column trial, headless: it runs to three instants of its timeline without failing
+# (the opening in the working frame, a beat in the column, the close).
+frames 2
+console set playing false
+console set t 5
+screenshot .zig-cache/canim/column-early.png
+console set t 30
+screenshot .zig-cache/canim/column-mid.png
+console set t 999
+screenshot .zig-cache/canim/column-end.png
diff --git a/anim/test/column_sort.script b/anim/test/column_sort.script
new file mode 100644
index 0000000..540658b
--- /dev/null
+++ b/anim/test/column_sort.script
@@ -0,0 +1,10 @@
+# The column on sort's rings, headless: it runs to three instants of its timeline without failing
+# (the opening in the working frame, the drawing across both columns, the close).
+frames 2
+console set playing false
+console set t 5
+screenshot .zig-cache/canim/column_sort-early.png
+console set t 20
+screenshot .zig-cache/canim/column_sort-mid.png
+console set t 999
+screenshot .zig-cache/canim/column_sort-end.png
diff --git a/anim/test/recordings.zig b/anim/test/recordings.zig
index 7c3a26e..5f9ceb3 100644
--- a/anim/test/recordings.zig
+++ b/anim/test/recordings.zig
@@ -82,7 +82,8 @@ test "a walked step is as long as what it changed: fire, a slot a level, the hol
fn frame(s: *anim.Frame) void {
const r = canim.open(recordings.steps);
at = canim.cursor(s, r, r.lineMoment(10, r.call("main", 0).enter));
- at.levels = .{ .idea = .calls };
+ // The cascade as it was: `whole` (`tied` is the next test's).
+ at.levels = .{ .idea = .calls, .annotation = .whole };
}
};
var arena: std.heap.ArenaAllocator = .init(std.testing.allocator);
@@ -101,11 +102,63 @@ test "a walked step is as long as what it changed: fire, a slot a level, the hol
try expect(call.total > 2.0 and call.total < 3.5);
// A line that changes nothing shown: fire, advance, rest.
var quiet = scene.at;
- quiet.levels = .{ .cpu = false, .memory = false };
+ quiet.levels = .{ .cpu = false, .memory = false, .annotation = .whole };
const line = quiet.reading(rec.lineMoment(4, from), rec.lineMoment(6, from));
try std.testing.expectApproxEqAbs(t.fire + t.step + t.rest + t.step_per_row, line.total, 1e-3);
}
+test "under tied a step goes cause to effect: the touch, the word, rsp's pin, the window" {
+ const rec = canim.open(recordings.steps);
+ const scene = struct {
+ var at: canim.Cursor = undefined;
+ fn frame(s: *anim.Frame) void {
+ const r = canim.open(recordings.steps);
+ at = canim.cursor(s, r, r.call("fib", 1).enter - 1);
+ }
+ };
+ var arena: std.heap.ArenaAllocator = .init(std.testing.allocator);
+ defer arena.deinit();
+ var frame: anim.Frame = .{ .t = 0, .clock = 0, .in = undefined, .pointer = .{ 0, 0 }, .arena = arena.allocator() };
+ scene.frame(&frame);
+ const f = 1.0 / 60.0;
+ // fib(5)'s `call fib` (by instruction): the touch to the free word over rsp 18 to 30, the return
+ // address armed 30 to 42 and struck at 42, rsp's pin 48 to 72 (struck as it lands), the window 78 on.
+ const call = rec.call("fib", 1).enter - 1;
+ const pushed = scene.at.reading(call, call + 1);
+ try std.testing.expectApproxEqAbs(@as(f32, 18 * f), pushed.touch, 1e-4);
+ try std.testing.expectApproxEqAbs(@as(f32, 42 * f), pushed.at[1], 1e-4);
+ try std.testing.expectApproxEqAbs(@as(f32, 48 * f), pushed.pins[0], 1e-4);
+ try std.testing.expectApproxEqAbs(@as(f32, 78 * f), pushed.follow, 1e-4);
+ try expect(pushed.pins[1] < 0 and pushed.advance > pushed.follow);
+ // `push rbp`, at the callee's entry: the same order.
+ const push = scene.at.reading(call + 1, call + 2);
+ try expect(push.touch < push.at[1] and push.at[1] < push.pins[0] and push.pins[0] < push.follow);
+ // `mov rbp, rsp`: no word; rbp's pin from 18 f, and no window to follow.
+ const frame_ptr = scene.at.reading(call + 2, call + 3);
+ try expect(frame_ptr.touch < 0 and frame_ptr.pins[0] < 0 and frame_ptr.follow < 0);
+ try std.testing.expectApproxEqAbs(@as(f32, 18 * f), frame_ptr.pins[1], 1e-4);
+ // A load that fills a register (`mov rax, [rbp - 0x10]`, fib(1)'s `return n`): the word read
+ // (its touch 18 to 30, framed at 30) before rax strikes (48).
+ var at = call;
+ var buf: [256]u8 = undefined;
+ while (!(std.mem.eql(u8, rec.instruction(at, rec.register(at, "rip"), &buf).?.text, "mov rax, qword ptr [rbp - 0x10]") and rec.registersChanged(at, at + 1) & 1 != 0)) at += 1;
+ const load = scene.at.reading(at, at + 1);
+ try std.testing.expectApproxEqAbs(@as(f32, 30 * f), load.read, 1e-4);
+ try std.testing.expectApproxEqAbs(@as(f32, 48 * f), load.at[0], 1e-4);
+ // With `carry = .arrow` the value's way between: carried 36 to 54, rax struck at 66.
+ var carrying = scene.at;
+ carrying.levels.carry = .arrow;
+ const carried = carrying.reading(at, at + 1);
+ try std.testing.expectApproxEqAbs(@as(f32, 36 * f), carried.carry, 1e-4);
+ try std.testing.expectApproxEqAbs(@as(f32, 66 * f), carried.at[0], 1e-4);
+ // `pop rbp`: the word read (framed at 30), then rbp's pin (it takes the word), then rsp's, then the window.
+ var pop = at;
+ while (!std.mem.eql(u8, rec.instruction(pop, rec.register(pop, "rip"), &buf).?.text, "pop rbp")) pop += 1;
+ const popped = scene.at.reading(pop, pop + 1);
+ try std.testing.expectApproxEqAbs(@as(f32, 30 * f), popped.read, 1e-4);
+ try expect(popped.read < popped.pins[1] and popped.pins[1] < popped.pins[0] and popped.pins[0] < popped.follow);
+}
+
/// The first moment whose pc is in the function named `name` (as the recording names it: `libc.so.6!open`).
fn firstIn(rec: *const Recording, name: []const u8) u64 {
for (rec.registers, 0..) |regs, i| {